Compare commits

..
16 Commits
Author SHA1 Message Date
cflmyandCursor 2e65c055b8 Release v0.1.2: embedded stdlib, docs, and extension branch policy.
Embed lib/*.mq.md in binary; marqdo version --check; public writeback/subtask pages; restore /vscode-extension/ ignore. VSIX built from branch vscode-extension only (see doc/design/vscode-extension-commit.md).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 09:41:53 +08:00
cflmyandCursor 3da7b276d3 Extend subtask stdlib for file, function, and foreign concurrency.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 09:41:22 +08:00
cflmyandCursor 63e5be80ab Add v0.2 surface syntax, writeback/subtask stdlib, and view input deferral.
Use + for parameters, ordered-list branches, backtick identifiers, and quoted strings with escapes. Add writeback and subtask host libs, optional parameter defaults, narrative-bold comment fix, and defer view execution until preset stdin is submitted.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-06 17:52:33 +08:00
cflmyandCursor 92d88fe761 Move LLM and agent into ext/ai with host tool catalog and call_fn.
Consolidate official AI extensions under ext/ai/, add agent history/context host APIs, dynamic call_fn, and a first-pass TOOL:name loop so runbooks can list zero-arg tools in a table.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-06 15:28:39 +08:00
cflmyandCursor c4ffb9473f Extend ext/agent with skill match/assign and multi-column tables.
Compose ext/llm, add ABI match_skill/bump_load, map-valued GFM tables, and agent-assign gold coverage.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-06 13:46:34 +08:00
cflmyandCursor 3a7e11c995 Add ext/agent layout framework, ext CLI, and docs catch-up.
Ship ABI agent plugin helpers, marqdo ext list/add/remove, and document the agent development roadmap (compose LLM, match/assign).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-06 13:31:25 +08:00
cflmyandCursor b0c777c480 Add versioned C ABI for optional native plugins.
Load .dll/.so/.dylib at runtime via libloading, register JSON-wired functions, and ship a Rust cdylib demo with lib/plugin wrappers and gold coverage.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-06 12:45:18 +08:00
cflmyandCursor b00b018056 Add object primitives, official ext/llm, and HTTPS/dotenv platform.
Introduce # objects with ## methods (handles + ` x.method `), ship OpenAI-compatible ext/llm, and upgrade net/sys for HTTPS headers and dotenv loading.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-06 11:53:14 +08:00
cflmy b974f10c6e Add Marqdo AI skill for correct .mq.md authoring.
Ship a portable skills/marqdo package (and Cursor mirror) so agents follow markup-as-syntax rules, stdlib imports, and the run-fix loop.
2026-08-05 17:36:21 +08:00
cflmyandCursor 72777a8c74 Release v0.1.1: debug page Logo branding and packaging notes.
Bump crate version, use official Logo for marqdo debug favicon/brand, and document VS Code extension assets in the Windows release script.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 17:17:00 +08:00
cflmyandCursor e08cd839be Ignore vscode-extension on main and document the extension branch.
Point editors to the vscode-extension branch for host work, mirroring the public/gh-pages split.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 16:25:38 +08:00
cflmyandCursor 5309848292 Fix README syntax for function-end HR and document catalog CLI.
Correct ---/***/empty-return conventions and spell out marqdo catalog/sync for OKF-style YAML generation.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 16:01:22 +08:00
cflmyandCursor 1271aafcdd Package release zips with stdlib and document bare-exe limits.
Ship recommended marqdo.exe+lib bundle, a separate stdlib zip, and clear release notes that the standalone exe does not include lib/.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 15:50:10 +08:00
cflmyandCursor 54a507d906 Ship v0.1.0: dedicated debug host, view outline, code-as-docs README.
Add marqdo debug (breakpoints/step/locals), restore view as docs with function search, and emphasize OKF-aligned knowledge-base direction.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 15:40:29 +08:00
cflmyandCursor ea17ae1074 Add Windows release packaging so tagged releases ship binaries.
Upload exe/zip via CI on v* tags and provide a local release-windows script.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 13:04:06 +08:00
cflmyandCursor fe9046cecf Sync Cargo.lock package version to 0.0.4.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 12:52:43 +08:00
182 changed files with 11342 additions and 942 deletions

No files matched your search

+159
View File
@@ -0,0 +1,159 @@
---
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
@@ -0,0 +1,162 @@
# 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
@@ -0,0 +1,135 @@
# Marqdo reference (AI)
Load this when you need stdlib names, CLI, or edge cases. Core rules stay in [SKILL.md](SKILL.md).
## CLI
```text
marqdo --version
marqdo run FILE.mq.md
marqdo run FILE.mq.md --backend bytecode
marqdo view PATH # docs browser, default port 7429
marqdo debug PATH # debugger UI, default port 7430
marqdo catalog PATH -o .marqdo
marqdo ext list
marqdo ext add llm|agent
marqdo ext remove llm|agent
```
Diagnostics look like `path:line:col: message` (1-based line/col).
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * ``; 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 |
+102
View File
@@ -0,0 +1,102 @@
# 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 }}
+21
View File
@@ -1,15 +1,36 @@
/target/
/dist/
# Copied by gold harness for ABI plugins
/tests/lib/demo.dll
/tests/lib/libdemo.so
/tests/lib/libdemo.dylib
/tests/ext/agent.dll
/tests/ext/libagent.so
/tests/ext/libagent.dylib
/tests/ext/skel.mq.md
/tests/ext/out-demo.mq.md
/tests/ext/ticket.txt
/tests/ext/ticket-stub.txt
/tests/ext/agents/
/tests/ext/runbooks/
/tests/ext/templates/
/tests/ext/reports/
**/*.rs.bk
.idea/
.vscode/
*.pdb
.DS_Store
.marqdo/
.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__/
+22
View File
@@ -0,0 +1,22 @@
# 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
+399 -7
View File
@@ -2,6 +2,12 @@
# It is not intended for manual editing.
version = 3
[[package]]
name = "adler2"
version = "2.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
[[package]]
name = "aho-corasick"
version = "1.1.5"
@@ -13,9 +19,9 @@ dependencies = [
[[package]]
name = "android_system_properties"
version = "0.1.5"
version = "0.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311"
checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc"
dependencies = [
"libc",
]
@@ -56,7 +62,7 @@ version = "1.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
dependencies = [
"windows-sys",
"windows-sys 0.61.2",
]
[[package]]
@@ -67,7 +73,7 @@ checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
dependencies = [
"anstyle",
"once_cell_polyfill",
"windows-sys",
"windows-sys 0.61.2",
]
[[package]]
@@ -103,6 +109,12 @@ version = "1.5.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
[[package]]
name = "base64"
version = "0.22.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
[[package]]
name = "bitflags"
version = "2.13.1"
@@ -211,6 +223,15 @@ version = "0.8.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
[[package]]
name = "crc32fast"
version = "1.5.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511"
dependencies = [
"cfg-if",
]
[[package]]
name = "difflib"
version = "0.4.0"
@@ -229,6 +250,16 @@ version = "0.1.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
[[package]]
name = "flate2"
version = "1.1.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
dependencies = [
"crc32fast",
"miniz_oxide",
]
[[package]]
name = "float-cmp"
version = "0.9.0"
@@ -238,6 +269,15 @@ dependencies = [
"num-traits",
]
[[package]]
name = "form_urlencoded"
version = "1.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
dependencies = [
"percent-encoding",
]
[[package]]
name = "futures-core"
version = "0.3.33"
@@ -271,6 +311,17 @@ dependencies = [
"unicode-width",
]
[[package]]
name = "getrandom"
version = "0.2.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
dependencies = [
"cfg-if",
"libc",
"wasi",
]
[[package]]
name = "heck"
version = "0.4.1"
@@ -307,6 +358,56 @@ dependencies = [
"cc",
]
[[package]]
name = "idna"
version = "1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
dependencies = [
"idna_adapter",
"smallvec",
"utf8_iter",
]
[[package]]
name = "idna_adapter"
version = "1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "279259b0ac81c89d11c290495fdcfa96ea3643b7df311c138b6fe8ca5237f0f8"
dependencies = [
"idna_mapping",
"unicode-bidi",
"unicode-normalization",
]
[[package]]
name = "idna_mapping"
version = "1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "11c13906586a4b339310541a274dd927aff6fcbb5b8e3af90634c4b31681c792"
dependencies = [
"unicode-joining-type",
]
[[package]]
name = "include_dir"
version = "0.7.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "923d117408f1e49d914f1a379a309cffe4f18c05cf4e3d12e613a15fc81bd0dd"
dependencies = [
"include_dir_macros",
]
[[package]]
name = "include_dir_macros"
version = "0.7.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7cab85a7ed0bd5f0e76d93846e0147172bed2e2d3f859bcc33a8d9699cad1a75"
dependencies = [
"proc-macro2",
"quote",
]
[[package]]
name = "is_terminal_polyfill"
version = "1.70.2"
@@ -336,6 +437,16 @@ version = "0.2.189"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
[[package]]
name = "libloading"
version = "0.8.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "fc2f4eb4bc735547cfed7c0a4922cbd04a4655978c09b54f1f7b228750664c34"
dependencies = [
"cfg-if",
"windows-targets",
]
[[package]]
name = "log"
version = "0.4.33"
@@ -344,17 +455,36 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "marqdo"
version = "0.0.3"
version = "0.1.2"
dependencies = [
"anyhow",
"assert_cmd",
"chrono",
"clap",
"idna_adapter",
"include_dir",
"libloading",
"predicates",
"pulldown-cmark",
"serde_json",
"thiserror",
"tiny_http",
"ureq",
"zeroize",
]
[[package]]
name = "marqdo_plugin_agent"
version = "0.1.0"
dependencies = [
"serde_json",
]
[[package]]
name = "marqdo_plugin_demo"
version = "0.1.0"
dependencies = [
"serde_json",
]
[[package]]
@@ -363,6 +493,16 @@ version = "2.8.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
[[package]]
name = "miniz_oxide"
version = "0.8.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
dependencies = [
"adler2",
"simd-adler32",
]
[[package]]
name = "normalize-line-endings"
version = "0.3.0"
@@ -390,6 +530,12 @@ version = "1.70.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
[[package]]
name = "percent-encoding"
version = "2.3.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
[[package]]
name = "pin-project-lite"
version = "0.2.17"
@@ -477,9 +623,9 @@ dependencies = [
[[package]]
name = "regex-automata"
version = "0.4.16"
version = "0.4.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad"
checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
dependencies = [
"aho-corasick",
"memchr",
@@ -492,6 +638,54 @@ version = "0.8.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
[[package]]
name = "ring"
version = "0.17.14"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
dependencies = [
"cc",
"cfg-if",
"getrandom",
"libc",
"untrusted",
"windows-sys 0.52.0",
]
[[package]]
name = "rustls"
version = "0.22.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bf4ef73721ac7bcd79b2b315da7779d8fc09718c6b3d2d1b2d94850eb8c18432"
dependencies = [
"log",
"ring",
"rustls-pki-types",
"rustls-webpki",
"subtle",
"zeroize",
]
[[package]]
name = "rustls-pki-types"
version = "1.15.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96"
dependencies = [
"zeroize",
]
[[package]]
name = "rustls-webpki"
version = "0.102.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "64ca1bc8749bd4cf37b5ce386cc146580777b4e8572c7b97baf22c83f444bee9"
dependencies = [
"ring",
"rustls-pki-types",
"untrusted",
]
[[package]]
name = "rustversion"
version = "1.0.23"
@@ -546,18 +740,36 @@ version = "2.0.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
[[package]]
name = "simd-adler32"
version = "0.3.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
[[package]]
name = "slab"
version = "0.4.12"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
[[package]]
name = "smallvec"
version = "1.15.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
[[package]]
name = "strsim"
version = "0.10.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "73473c0e59e6d5812c5dfe2a064a6444949f089e20eec9a2e5506596494e4623"
[[package]]
name = "subtle"
version = "2.6.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
[[package]]
name = "syn"
version = "2.0.119"
@@ -618,24 +830,101 @@ dependencies = [
"log",
]
[[package]]
name = "tinyvec"
version = "1.12.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bb4ebadaa0af04fab11ae01eb5f9fdb5f9c5b875506e210e71c07873528baa7f"
dependencies = [
"tinyvec_macros",
]
[[package]]
name = "tinyvec_macros"
version = "0.1.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
[[package]]
name = "unicase"
version = "2.9.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142"
[[package]]
name = "unicode-bidi"
version = "0.3.18"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5c1cb5db39152898a79168971543b1cb5020dff7fe43c8dc468b0885f5e29df5"
[[package]]
name = "unicode-ident"
version = "1.0.24"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
[[package]]
name = "unicode-joining-type"
version = "1.0.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d8d00a78170970967fdb83f9d49b92f959ab2bb829186b113e4f4604ad98e180"
[[package]]
name = "unicode-normalization"
version = "0.1.25"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5fd4f6878c9cb28d874b009da9e8d183b5abc80117c40bbd187a1fde336be6e8"
dependencies = [
"tinyvec",
]
[[package]]
name = "unicode-width"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
[[package]]
name = "untrusted"
version = "0.9.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
[[package]]
name = "ureq"
version = "2.9.7"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d11a831e3c0b56e438a28308e7c810799e3c118417f342d30ecec080105395cd"
dependencies = [
"base64",
"flate2",
"log",
"once_cell",
"rustls",
"rustls-pki-types",
"rustls-webpki",
"url",
"webpki-roots 0.26.11",
]
[[package]]
name = "url"
version = "2.5.8"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
dependencies = [
"form_urlencoded",
"idna",
"percent-encoding",
"serde",
]
[[package]]
name = "utf8_iter"
version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
[[package]]
name = "utf8parse"
version = "0.2.2"
@@ -651,6 +940,12 @@ dependencies = [
"libc",
]
[[package]]
name = "wasi"
version = "0.11.1+wasi-snapshot-preview1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
[[package]]
name = "wasm-bindgen"
version = "0.2.126"
@@ -696,6 +991,24 @@ dependencies = [
"unicode-ident",
]
[[package]]
name = "webpki-roots"
version = "0.26.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9"
dependencies = [
"webpki-roots 1.0.9",
]
[[package]]
name = "webpki-roots"
version = "1.0.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7dcd9d09a39985f5344844e66b0c530a33843579125f23e21e9f0f220850f22a"
dependencies = [
"rustls-pki-types",
]
[[package]]
name = "windows-core"
version = "0.62.2"
@@ -755,6 +1068,15 @@ dependencies = [
"windows-link",
]
[[package]]
name = "windows-sys"
version = "0.52.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
dependencies = [
"windows-targets",
]
[[package]]
name = "windows-sys"
version = "0.61.2"
@@ -764,6 +1086,76 @@ dependencies = [
"windows-link",
]
[[package]]
name = "windows-targets"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
dependencies = [
"windows_aarch64_gnullvm",
"windows_aarch64_msvc",
"windows_i686_gnu",
"windows_i686_gnullvm",
"windows_i686_msvc",
"windows_x86_64_gnu",
"windows_x86_64_gnullvm",
"windows_x86_64_msvc",
]
[[package]]
name = "windows_aarch64_gnullvm"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
[[package]]
name = "windows_aarch64_msvc"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
[[package]]
name = "windows_i686_gnu"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
[[package]]
name = "windows_i686_gnullvm"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
[[package]]
name = "windows_i686_msvc"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
[[package]]
name = "windows_x86_64_gnu"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
[[package]]
name = "windows_x86_64_gnullvm"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
[[package]]
name = "windows_x86_64_msvc"
version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
[[package]]
name = "zeroize"
version = "1.8.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ced3678a2879b30306d323f4542626697a464a97c0a07c9aebf7ebca65cd4dde"
[[package]]
name = "zmij"
version = "1.0.23"
+11 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "0.0.4"
version = "0.1.2"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -19,6 +19,16 @@ 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"
+85 -26
View File
@@ -1,71 +1,130 @@
# Marqdo
**代码即文档。文档即代码。**
**代码即文档。文档即代码。文档即知识库。**
Marqdo:Markdown **标记即语法**。源文件 `.mq.md` 既是文稿也是程序。
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
欢迎访问[marqdo官方网站](https://www.marqdo.com/)阅读marqdo更多特性
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 测试布局:[examples-and-tests.md](doc/design/examples-and-tests.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 金样例:[tests/](tests/) · 用户文档:[public/](public/)
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
---
## 语法速览(v0.1)
## 为什么重要
| 痛点 | Marqdo 的答案 |
|------|----------------|
| 文档过期、示例跑不通 | **一份源文件**:叙述、结构与执行结果同源 |
| 知识散落在 Wiki / 注释 / 脚本里 | **`.mq.md` 即知识单元**,可浏览、可运行、可检索 |
| 人写给人看,AI / 工具另起一套 | **人机同读同写同构**:标记语言对人类友好,对解释器确定 |
| 大仓里「文档站」与「代码仓」脱节 | `view` 文档站 + `debug` 调试面 + `catalog` 清单,同一棵树长大 |
这不是「再做一个 Markdown 渲染器」,而是:**把文档升格为可解释的程序与可生长的知识库**,让协作在大型项目里依然站得住。
---
## 语法速览(v0.2)
| 标记 | 含义 |
|------|------|
| 无标记行 | 注释 |
| 无标记行 | 注释(空行分段) |
| `*…*` | 程序语句 |
| `**…**` | **返回值**(架构) |
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
| `#` / `##` | 函数与作用域 |
| `+` / `1.` | 分支(臂头单独 `*` = else) |
| `-` | 循环(头下纯名则为形参) |
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
| `##` … | 函数 / 方法(按标题深度嵌套) |
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
| `+` / `1.` … | 函数头下 `` + `名` `` = 形参;体内 `1.` `2.` … = 分支(`N. *` = else) |
| `-` | 循环(`` - `条件` `` 或 `` - [`项`](`集合`) ``) |
| 表格 | 集合 |
| `---` / `***` | 可选:框住分支/循环(不强制) |
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
```markdown
# main
> print text=Hello World!
> 问候 谁=World
## 问候
+ `谁`
> print text=Hello `谁`!
---
## 加一
- n
+ `n`
**`n` + 1**
```
完整约定:[markdown-mapping.md](doc/design/markdown-mapping.md)。
---
## 理念
1. 叙述默认安全(无标记 = 注释)。
2. 返回是架构;打印只是函数。
3. 依赖清单由工具生成(OKF 风格),不是手填配置。
4. **正经解释器(Rust)**:词法/行分类 → 递归下降语法 → 语义 → 树遍历 → 日后字节码;**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md) 与 [依赖说明](doc/design/dependencies.md)。
1. **叙述默认安全**(无标记 = 注释)。
2. **返回是架构;打印只是函数。**
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
---
## 现状
## OKF 风格清单(自动生成)
- 映射 v0.1:[markdown-mapping.md](doc/design/markdown-mapping.md)
- 解释器路线图:[interpreter.md](doc/roadmap/interpreter.md)
- **Phase I(树遍历)已通**:`tests/structure/` 与 `tests/keywords/` 金样例均可 `marqdo run`
- **view**:`marqdo view public` 浏览用户文档;金样例用 `marqdo view tests`
- **用户静态站**:可执行文稿在 `public/`(无 errors);`view output` 生成 HTML(ignore),CI 发布到 `gh-pages` — 见 [user-site.md](doc/design/user-site.md)
- 依赖(Rust,无 Flex/Bison):[dependencies.md](doc/design/dependencies.md)
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
从源码派生 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
cargo run -- catalog tests -o .marqdo
```
文档:用户站见 [public/](public/) 与 [user-site.md](doc/design/user-site.md);设计文稿见 [doc/](doc/);`view` 皮肤见 [view.md](doc/design/view.md);OKF 清单见 [catalog-cli.md](doc/design/catalog-cli.md)。
**发布包(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)
---
+13 -4
View File
@@ -16,6 +16,8 @@
| 文档 | 摘要 |
|------|------|
| [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 清单 |
@@ -24,16 +26,23 @@
| [design/dependencies.md](design/dependencies.md) | 依赖详单(无 Flex/Bison) |
| [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置函数** |
| [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** |
| [design/stdlib.md](design/stdlib.md) | **P2 标准库:内置 + `lib/` + 错误约定** |
| [design/stdlib.md](design/stdlib.md) | **标准库:内置 + `lib/` + 错误约定** |
| [design/stdlib-i18n.md](design/stdlib-i18n.md) | **标准库中英命名:靠库文件名区分,无 lang 开关** |
| [design/stdlib-modules.md](design/stdlib-modules.md) | **本波 L1:文件/系统/时间/JSON/网络(JSON 中英同库)** |
| [design/stdlib-math.md](design/stdlib-math.md) | **方案:数学库(数值/随机/作图/轻量求解)** |
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **暂缓:外联胶水(\`\`\`lang 具名块)** |
| [design/stdlib-modules.md](design/stdlib-modules.md) | **L1:文件/系统/时间/JSON/网络/数学/外联/插件** |
| [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** |
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** |
| [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) |
| [design/ext-llm.md](design/ext-llm.md) | **官方扩展 `ext/llm`(OpenAI 兼容)** |
| [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(智能体开发框架;布局已落地,编排/大模型组合路线已记录)** |
| [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) |
+29
View File
@@ -0,0 +1,29 @@
# Marqdo AI Skill
| | |
|---|---|
| 状态 | 已提供 |
| 日期 | 2026-08-05 |
| 路径 | [`skills/marqdo/`](../../skills/marqdo/)(权威);Cursor 镜像 [`.cursor/skills/marqdo/`](../../.cursor/skills/marqdo/) |
---
## 目的
让接入方(Cursor Agent、其它支持 Agent Skills 的模型宿主)在**加载本 skill 后**即可按 v0.1 语法正确编写 / 修改 `.mq.md`,而不把 Markdown 习惯或 Python 控制流误套到 Marqdo。
## 内容
| 文件 | 用途 |
|------|------|
| `SKILL.md` | 必读:硬规则、标记表、工作流、反模式 |
| `reference.md` | 按需:CLI、stdlib 索引、边界 |
| `examples.md` | 按需:可复制样例 |
## 使用
- **本仓库 Cursor**:项目 skill 已在 `.cursor/skills/marqdo/`;描述含 `.mq.md` / Marqdo 触发词,可自动选用。
- **其它 AI**:将 `skills/marqdo/` 整目录作为 skill 包导入,或把 `SKILL.md` 贴进系统/项目说明并允许模型按需打开 `reference.md` / `examples.md`。
- **校验**:生成后执行 `marqdo run <file>.mq.md`,按 `path:line:col` 诊断迭代。
语法真相仍以 [markdown-mapping.md](markdown-mapping.md) 与 [keywords.md](keywords.md) 为准;skill 是面向模型的压缩操作手册。
+2 -1
View File
@@ -21,7 +21,8 @@
- 以**空行**划分段落。
- 段首行:首字符非标记 → 注释。
- 段内续行:一律注释(即使以 `` ` `` / `-` 等开头)。
- 段内续行:一律注释(即使以 `` ` `` / `-` / `**` 等开头)。
- **例外**:整行仅为 `**expr**`(或 `****`)→ Marqdo **返回**;`**强调**` 后还有文字 → 仍是叙述注释。
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
---
+1
View File
@@ -81,6 +81,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
| **clap** | CLI | `marqdo run [path]` |
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`> x.mq.md` 仍按**行**抽取(见 Spike) |
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
#### 强烈建议
+1 -1
View File
@@ -42,7 +42,7 @@ tests/
| 类别 | 测什么 | 不测什么 |
|------|--------|----------|
| **structure** | `#`/`##`、形参、`>` 调用、`*`/`**`、`+`/`-`、表、导入、位置/具名实参 | 关键字边角 |
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、位置/具名实参 | 关键字边角 |
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
+85
View File
@@ -0,0 +1,85 @@
# 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
@@ -0,0 +1,137 @@
# 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
@@ -0,0 +1,61 @@
# 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
@@ -0,0 +1,70 @@
# 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`)
+2 -2
View File
@@ -36,7 +36,7 @@ L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英
### 3.1 字面量 / 逻辑关键字(词法保留)
控制流仍靠 Markdown(`#` `+` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。
控制流仍靠 Markdown(`#` `1.` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。形参用 `+`。
| 英文 | 中文(提案) | 备注 |
|------|--------------|------|
@@ -107,7 +107,7 @@ L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英
- 旧文「中文 `print` 废弃、统一为 `print`」:**废止**;改为正式双名 `print` / `打印`。
- [keywords.md](keywords.md) 原则条「英文标识」改为「**内核双名;标准库分文件**」——实现阶段改正文。
- 不引入中文控制流关键字(`如果`/`循环` 等);分支循环仍用 `+` / `-`。
- 不引入中文控制流关键字(`如果`/`循环` 等);分支用 `1.` …,循环用 `-`。
---
+5 -3
View File
@@ -11,7 +11,7 @@
## 1. 设计原则
1. **标记承担架构**:函数=`#`,分支=`+`,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
1. **标记承担架构**:函数=`#`,**形参=`+`**,**分支=`1.`…**,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
2. **内核双名**:字面量 / 逻辑词 / 五个核心内置函数均有中英别名,**无需导入**,可混用。
3. **学 Python 的边界**:区分 **关键字** vs **内置函数名**。
4. **宁少勿多**:扩展能力进可导入标准库(中英分文件,见 [stdlib-i18n.md](stdlib-i18n.md))。
@@ -43,6 +43,8 @@
| `str` | `文本` | 转为显示文本 |
| `int` | `整数` | 转为整数 |
**文本**:裸 token 按字面量;需 `\n` 等转义时用 `"..."`(见 [markdown-mapping.md](markdown-mapping.md) §7)。
形参别名:
| 英文 | 中文 | 用于 |
@@ -71,9 +73,9 @@
*`n` = 1*
+ `n` > 0
1. `n` > 0
> print text=positive
+ *
2. *
> 打印 内容=other
```
+97 -47
View File
@@ -1,11 +1,11 @@
# Marqdo 语法映射 v0.1(Markup-as-Syntax)
# Marqdo 语法映射 v0.2(Markup-as-Syntax)
| | |
|---|---|
| 状态 | 已定论(修订:语句 / 返回 / 输出职责分离) |
| 日期 | 2026-08-04 |
| 取代 | v0 中「`**`=输出、`*`=返回」 |
| 相关 | [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) |
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、标识符反引号、`-` 专用于循环) |
| 日期 | 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))。
@@ -15,8 +15,9 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
1. `.mq.md`:打开即文档,运行即程序。
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` 表…)与 **斜体语句** / **粗体返回**。
4. 作用域 = `#` 层数;入口 = `index.mq.md`。函数体可用 `---` / `***` 或空返回收束(见 §11)。
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` `1.` 表…)与 **斜体语句** / **粗体返回**。
4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。
5. **标识符一律反引号**:凡表示变量槽位(形参、绑定、引用、遍历项、集合名)均写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。
---
@@ -29,22 +30,23 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
| 普通文字 / 空 | **注释** |
| 标记字符 | **代码** |
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字 `1.`、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
**成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。
---
## 3. 映射总表(v0.1)
## 3. 映射总表(v0.2)
| 标记 | 语义 |
|------|------|
| `#` … `######` | 函数;层数 = 作用域 |
| 函数头下 `-` 纯名 | 形参 |
| 体内 `-` | 循环 |
| 体内 `+` 或 `1.` | 分支 |
| 分支臂头整行恰为 `*` | else |
| `#` … `######` | **`#` = 对象/类型**;**`##`+ = 函数/方法**(层差=嵌套)。见 [objects.md](objects.md) |
| 函数头下 `+ `` `名` `` ` | 形参 / 构造参数(可选 `` `名`=默认值 ``) |
| 体内 `1.` `2.` … | **分支**(有序列表臂;条件行或 else) |
| 体内 `-` | **循环**(`while` 条件,或 `` [`项`](`集合`) `` 遍历) |
| 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` |
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
| `` > `对象`.方法 … `` | 方法调用(实例 map 须含 `_type`) |
| frontmatter `> path.mq.md` | 跨文件导入 |
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
| `**…**` | **返回值**(架构级;函数结果) |
@@ -55,13 +57,23 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
| ` ```lang ` | 外联异种代码 |
| 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §11) |
### `+` / `-` / `1.` 消歧
| 位置 | `+` | `1.` … | `-` |
|------|-----|--------|-----|
| 函数标题后、**首条体语句前** | 形参:`` + `名` `` / `` + `名`=默认 `` | (非法) | (非法作形参) |
| 函数体内 | (非法作分支) | 分支臂:`1. `条件`` / `2. *` | 循环 |
**分支从未使用 `+`。** 自 v0 起即采用 GFM 有序列表;`+` 在 v0.2 专用于形参,与 `-` 循环彻底分离。
### 输出不是架构
| 错误(旧) | 正确(v0.1) |
| 错误(旧) | 正确(v0.2) |
|------------|--------------|
| `**Hello**` 表示打印 | `> print text=Hello` |
| 中文名 `输出`(已废弃) | 统一英文内置 `print` |
| 输出与返回抢粗体 | 粗体只表示 **返回** |
| `+ `x` > 0` 作分支 | `1. `x` > 0` |
| `- 谁` 作形参 | `` + `谁` `` |
| `[果](篮子)` 裸名遍历 | `` [`果`](`篮子`) `` |
`print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。
@@ -77,13 +89,13 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
*`y` = `x` + 2*
```
行首已是结构标记的构造(`#` `>` `+` `-` `|`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
### 返回值(粗体)
```markdown
# 加一
- n
## 加一
+ `n`
**`n` + 1**
```
@@ -98,7 +110,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
### else 与斜体消歧
- 分支臂**第一行整行只有一个** `*` → else。
- 分支臂有序行 `N. *`(或 `N.` 后仅 `*`)→ else。
- `*中间有内容*` → 程序语句。
- `**…**` → 返回(与 else 无关)。
@@ -111,9 +123,11 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
---
## 6. 函数、作用域、提升
## 6. 对象、函数、形参
规则同 v0。推荐:
- `# Name`:对象(构造体);`# main` 为入口对象。
- `##` / `###` …:函数或方法;挂在对象下则为方法。
- 标准库顶层 API 使用自由函数 `## name`(见 [objects.md](objects.md))。
```markdown
# main
@@ -121,48 +135,90 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
> print text=Hello World!
## 加问候
- 谁
+ `谁`
**你好,`谁`**
```
(需要打印时对返回值再 `> print`,或直接 `> print`。)
可选形参:
形参 `- 名` → 体内 `` `名` ``。
```markdown
## 问候
+ `谁`
+ `礼貌`=False
```
方法体内自动绑定 `` `自` `` / `` `self` ``。
---
## 7. 绑定与比较
## 7. 绑定、比较与字符串
| 写法 | 含义 |
|------|------|
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定(两种均允许;实现应统一) |
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定 |
| `` `x` == 1 `` | 相等比较 |
| `"text"` | **双引号字符串**(复杂文本;见下) |
| `hello` / `路径` | **裸 token**(无转义,按字面量) |
v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致;行首 `` ` `` 仍合法以便表格右值绑定。
### 双引号字符串(复杂文本)
需要转义或嵌入变量时用 `"..."`;**裸 token 不转义**,保持文档简洁:
```markdown
> input prompt="你叫什么名字\n"
*`msg` = "Hello, `name`!\n"*
```
| 转义 | 含义 |
|------|------|
| `\n` | 换行 |
| `\t` | 制表 |
| `\r` | 回车 |
| `\\` | `\` |
| `\"` | `"` |
引号内仍可用 `` `变量` `` 插值。字面反斜杠+n 写 `\\n`(裸 token `\\n` 则就是两个字符)。
---
## 8. 分支与循环
分支(`+` / 有序),循环(`-`),语义同 v0。臂体内打印改为调用 `print`:
分支(**有序列表** `1.` `2.` …),循环(`-`):
```markdown
*`x` = 0*
+ `x` > 0
1. `x` > 0
> print text=正数
+ `x` < 0
2. `x` < 0
> print text=负数
+ *
3. *
> print text=零
```
```markdown
- [果](篮子)
*`bool_value` = True*
1. `bool_value` == True
> print text=True
2. *
> print text=False
```
```markdown
- [`果`](`篮子`)
> print text=今天吃`果`
```
`while`:
```markdown
- `n` > 0
> print text=`n`
*`n` = `n` - 1*
```
---
## 9. 集合(表格)
@@ -176,21 +232,19 @@ v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致
1. 加载 `index.mq.md` + 导入。
2. Pass1 收集定义。
3. Pass2 执行 `# main`。
4. `*` 语句、`**` 返回、`>` 调用、`+`/`-` 控制流、表绑定按语义执行;`> print` 写 stdout。
4. `*` 语句、`**` 返回、`>` 调用、`1.` 分支、`-` 循环、表绑定按语义执行;`> print` 写 stdout。
---
## 11. 函数体结束(`---` / `***` / 空返回)
无返回值(或已写完副作用)的函数,在体末用分割线收束,避免后续同级语句被吞进嵌套函数:
```markdown
# main
> 问候 谁=World
## 问候
- 谁
+ `谁`
> print text=Hello `谁`!
@@ -199,20 +253,16 @@ v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致
| 约定 | 说明 |
|------|------|
| `---` 或 `***` | 函数体**顶层**单独一行(长度 ≥ 3 且全为 `-` 或全为 `*`)→ **结束本函数**;后续语句属于外层 |
| `****` / 空粗体 | 空返回(值为 `None`),并同样结束本函数体 |
| 有值 `**expr**` | 普通返回;**不**自动截断后续兄弟句(仍可用分割线或下一同级/更浅标题收束) |
| Frontmatter | 仅**文件开头**成对 `---` = 元信息;与函数体内结束符消歧 |
| 分支/循环臂内 | 分割线仍可忽略(噪声),不截断外层函数 |
曾设想的「可选框住分支/循环」废止,分割线专用于函数收束。
| `---` 或 `***` | 函数体**顶层**单独一行 → **结束本函数** |
| `****` / 空粗体 | 空返回(`None`),并结束本函数体 |
| Frontmatter | 仅**文件开头**成对 `---` = 元信息 |
---
## 12. v0.1 非目标
## 12. v0.2 非目标
- break/continue、完整错误模型、静态类型、完整 FFI
- 用 `*` 作无序列表符
- `+` 作分支、`+`/`-` 作形参(**不保留**)
---
+73
View File
@@ -0,0 +1,73 @@
# 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` / `## 运行` |
+2 -2
View File
@@ -2,8 +2,8 @@
| | |
|---|---|
| 状态 | **已定(v1)** |
| 日期 | 2026-08-05 |
| 状态 | **已落地(v1)** |
| 日期 | 2026-08-06 |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
---
+88 -135
View File
@@ -1,32 +1,36 @@
# 标准库下一波(L1 扩展模块)
# 标准库 L1 模块
| | |
|---|---|
| 状态 | **五库 + 数学已落地**;下一波:**外联**([stdlib-foreign.md](stdlib-foreign.md)) |
| 日期 | 2026-08-05 |
| 本波范围 | 文件 / 系统 / 时间 / JSON / 网络 / 数学(已完成) |
| 下一波 | **外联**(本机解释器 / 具名围栏) |
| 暂缓 | — |
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin** |
| 日期 | 2026-08-06 |
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 |
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [keywords-i18n.md](keywords-i18n.md) · [view.md](view.md) |
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) |
---
## 1. 目标
在现有 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本。标准库**必须导入**才可用。
在 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本与可选原生扩展。标准库**必须导入**才可用。
| 模块族 | 英文库 | 中文库 | 本波 |
| 模块族 | 英文库 | 中文库 | 状态 |
|--------|--------|--------|------|
| 文本(已有) | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
| 表(已有) | `lib/table.mq.md` | `lib/表.mq.md` | 已有 |
| **文件** | `lib/fs.mq.md` | `lib/文件.mq.md` | **做** |
| **系统** | `lib/sys.mq.md` | `lib/系统.mq.md` | **做** |
| **时间** | `lib/time.mq.md` | `lib/时间.mq.md` | **做** |
| **JSON** | `lib/json.mq.md` | **同文件(特例,§3.4)** | **做** |
| **网络(简)** | `lib/net.mq.md` | `lib/网络.mq.md` | **做** |
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | **下一波** |
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | **做** |
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有 |
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 |
| 系统 | `lib/sys.mq.md` | `lib/系统.mq.md` | 已有(含 `load_dotenv`) |
| 时间 | `lib/time.mq.md` | `lib/时间.mq.md` | 已有 |
| JSON | `lib/json.mq.md` | **同文件** | 已有(含 `quote`) |
| 网络 | `lib/net.mq.md` | `lib/网络.mq.md` | 已有(HTTPS + headers) |
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | 已有 |
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | 已有 |
| **插件** | `lib/plugin.mq.md` | `lib/插件.mq.md` | **已有**(加载 C ABI 共享库) |
| **自写回** | `lib/writeback.mq.md` | `lib/自写回.mq.md` | **已有**(Jupyter 式输出写回) |
| **子任务** | `lib/subtask.mq.md` | `lib/子任务.mq.md` | **已有**(OS 子进程 + KillOnDrop) |
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` — 见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
设计细节:[stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md)。
---
@@ -34,35 +38,59 @@
```text
用户 .mq.md
│ > lib/fs.mq.md
│ > lib/fs.mq.md / > ext/llm.mq.md
▼
L1 官方库(.mq.md)
L1 官方库 / 官方 ext(.mq.md)
│
▼
L0.5 宿主原语(Rust,英文蛇形)
L0.5 宿主原语(Rust)或 原生插件(ABI v1)
│
▼
OS / HTTP / 时钟 / …
OS / HTTP / 时钟 / 共享库 …
```
| 层 | 谁实现 | 用户是否直接调用 |
|----|--------|------------------|
| **L0** | 解释器内置 | 是(`print`/`len`/…) |
| **L0.5 宿主原语** | Rust(`src/builtin` 或 `src/host/`) | **原则上否**;供 L1 包装;金样例可直测 |
| **L1 官方库** | `lib/*.mq.md` | **是**(文档与用户站只教这一层) |
规则:
1. **导入即选择语言**(JSON 除外):`lib/fs.mq.md` → 英文 API;`lib/文件.mq.md` → 中文 API(见 [stdlib-i18n.md](stdlib-i18n.md))。
2. **不设 `lang:`**。
3. 宿主原语保持英文;中英差异只存在于 L1 包装层(JSON 无第二套包装)。
4. 失败一律 `path:line:col: message`([stdlib.md](stdlib.md) §4)。
| **L0.5 宿主原语** | Rust(`src/host/`) | **原则上否**;供 L1 包装 |
| **L1 官方库** | `lib/*.mq.md` | **是** |
| **官方 ext** | `ext/*.mq.md`(+ 可选 ABI 插件) | **是**(需显式导入 `ext/`) |
---
## 3. 核心模块 API 草图(L1)
## 3. 核心模块 API(摘要)
### 3.1 文件 — `fs` / `文件`
文件 / 系统 / 时间 / JSON / 网络 API 见下文历史草图(已实现)。补充:
### 3.2 系统 — 已含 dotenv
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `load_dotenv` | `加载环境` | 可选 `path` | 新写入的键数量;缺文件 → `0`;不覆盖已有环境变量 |
### 3.4 JSON — 已含 `quote`
| 函数 | 形参 | 结果 |
|------|------|------|
| `quote` | `text` | JSON 字符串字面量(含引号) |
### 3.5 网络 — HTTPS
仅 **HTTP / HTTPS**(ureq);可选 `headers=`(map)、`content_type=`。
### 3.6 插件 — `plugin` / `插件`
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `load` | `加载` | `path` / `路径` | 注册函数个数 |
| `unload` | `卸载` | (无) | `None` |
| `list` | `列出` | (无) | 已注册名列表 |
契约:[ext-abi.md](ext-abi.md)。路径受 cwd/fs_root 沙箱约束。
### 3.1–3.5 历史 API 草图
#### 文件 — `fs` / `文件`
| 英文 | 中文 | 形参(英 / 中) | 结果 |
|------|------|-----------------|------|
@@ -74,22 +102,19 @@ OS / HTTP / 时钟 / …
| `make_dir` | `建目录` | `path` / `路径` | `None` |
| `remove` | `删除` | `path` / `路径` | `None` |
约定:路径相对工作目录或绝对路径;二进制 I/O 本波不做;写/删默认需 `--allow-fs-write`(§6)。
### 3.2 系统 — `sys` / `系统`
#### 系统 — `sys` / `系统`
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `env_get` | `取环境` | `name` / `名` | 文本或 `None` |
| `env_set` | `设环境` | `name`, `value` / `名`, `值` | `None` |
| `load_dotenv` | `加载环境` | 可选 `path` | 见上 |
| `args` | `参数表` | (无) | 文本列表 |
| `cwd` | `工作目录` | (无) | 文本 |
| `exit` | `退出` | `code` / `码` | 不返回 |
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码(实现时写死语义) |
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码 |
`exec` 默认关(`--allow-exec`);view / 静态站永不开放。
### 3.3 时间 — `time` / `时间`
#### 时间 — `time` / `时间`
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
@@ -99,130 +124,58 @@ OS / HTTP / 时钟 / …
| `sleep_ms` | `睡眠毫秒` | `ms` / `毫秒` | `None` |
| `parse` | `解析时间` | `text`, `pattern` / `内容`, `格式` | 整数秒或诊断失败 |
view 中 `sleep_ms` 设上限(如 5s)。
### 3.4 JSON — `json`(**中英同库特例**)
JSON 是专有缩写,**很难也不必要**做合规中文库名/API 翻译。本波定稿:
| 项 | 约定 |
|----|------|
| 唯一路径 | **`lib/json.mq.md`**(中英文档均导入此路径) |
| 函数名 | 国际通行英文:`parse` / `stringify` / `get` / `keys` |
| 形参 | 英文:`text` / `value` / `key` / `indent` |
| 不设 | `lib/数据.mq.md`、音译名、中文函数双份 |
这是对 [stdlib-i18n.md](stdlib-i18n.md)「一概念两文件」的**显式例外**;其它模块仍中英分文件。
#### JSON — `json`
| 函数 | 形参 | 结果 |
|------|------|------|
| `parse` | `text` | 值(见下) |
| `parse` | `text` | 值 |
| `stringify` | `value`, 可选 `indent` | JSON 文本 |
| `get` | `value`, `key` | 值或 `None` |
| `keys` | `value` | 文本列表 |
| `quote` | `text` | JSON 字符串字面量 |
**类型映射(草案)**:
| JSON | Marqdo Value |
|------|----------------|
| `null` | `None` |
| bool | bool |
| number(整数可表) | int |
| number(其余) | 文本(本波不引入 float)或诊断拒绝 |
| string | text |
| array | list |
| object | 倾向新宿主类型 **`map`**(`type` → `map`);否则体验差 |
`map` 为 L0.5 类型扩展,可与 json 同期或紧随;不阻塞 `fs`/`time` 先行。
### 3.5 网络(简)— `net` / `网络`
#### 网络 — `net` / `网络`
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `http_get` | `获取` | `url` / `地址` | 响应文本(或 map:status/body) |
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` | 同上 |
| `http_get` | `获取` | `url` / `地址` | 响应文本 |
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` / `headers` | 同上 |
| `url_encode` | `编码地址` | `text` / `内容` | 文本 |
仅 **HTTP 明文**(HTTPS 本波未做,会诊断提示);短超时、响应体上限;默认需 `--allow-net`;view / 静态站默认关。
**路径字面量:** 具名实参里 `path=a/b` 会被解析成除法。请用无斜杠文件名,或先赋给变量再传入。
---
## 4. 中英路径总表(本波)
## 4. 中英路径总表
```text
lib/
text.mq.md / 文本.mq.md # 已有
table.mq.md / 表.mq.md # 已有
fs.mq.md / 文件.mq.md # 本波
text.mq.md / 文本.mq.md
table.mq.md / 表.mq.md
fs.mq.md / 文件.mq.md
sys.mq.md / 系统.mq.md
time.mq.md / 时间.mq.md
json.mq.md # 本波;中英共用,无第二文件
json.mq.md # 中英共用
net.mq.md / 网络.mq.md
# 暂缓:math / 数学 · foreign / 外联
math.mq.md / 数学.mq.md
foreign.mq.md / 外联.mq.md
plugin.mq.md / 插件.mq.md
ext/ # 非 stdlib
llm.mq.md / 大模型.mq.md
agent.mq.md / 智能体.mq.md
```
别名:`std/…` ≡ `lib/…`。
别名:`std/…` ≡ `lib/…`。扩展解析:`MARQDO_EXT` / `./ext` / 二进制旁 `ext/`。
---
## 5. 落地分期(本波 = M1–M5)
## 5. 安全与 view / 静态导出
| 期 | 内容 | 完成定义 |
|----|------|----------|
| **M1** | 宿主能力框架:权限旗标、`host` 分发、错误文案 | `--allow-*` 可测 |
| **M2** | `fs` + `time`(只读 fs + 时钟) | 中英库 + 金样例 |
| **M3** | `sys`(env/cwd/args;`exec` 默认关) | 同上 |
| **M4** | `json`(+ 可选 `map`) | 往返金样例;唯 `lib/json.mq.md` |
| **M5** | `net`(默认关) | 本地 mock 或录制夹具 |
**不做 M6/M7**(数学 / 外联):详稿仅存档,待五库稳定后再议。
文档站:`fs`/`sys`/`time`/`net` 英中各一页;`json` 可一页双语叙述、同一导入路径。
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**。差异仅在软退出 / sleep 钳制。相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。插件路径同沙箱。
---
## 6. 安全与 view / 静态导出
## 6. 一句话
### 6.1 行为一致
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**(读/写盘、HTTP、exec 均可用)。导入库即表示要用;不再要求 `--allow-*`。
差异仅在 **软退出**:
| | CLI `run` | view / capture / 静态导出 |
|--|-----------|---------------------------|
| `exit` | 结束进程 | 报诊断,不杀 view/构建进程 |
| `sleep_ms` | 默认可睡(有上限) | live 有上限;导出通常为 0 |
沙箱:相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。
### 6.2 静态部署
访客浏览器 **不再执行** Marqdo;HTML 里是构建时冻结的输出。源码中的路径/URL 访客改不了、也触发不了新的 host 调用。审 PR 时审查写死的目标即可。
勿在静态页嵌入「用户可改 URL 再请求」的浏览器脚本。
---
## 7. 与现有库的关系
- `text` / `table` 继续纯包装、无 IO。
- JSON `stringify` ≠ `str`(显示)。
---
## 8. 刻意不做(本波)
- 数学库、外联/胶水库(及其依赖、权限旗标实现)。
- 数据库、异步事件循环、WebSocket、原始 TCP。
- float/复数进 L0。
- `lang:` 或按 locale 自动选库。
- 为 JSON 强造中文库名或中文 API 双份。
---
## 9. 一句话
**本波只落地文件 / 系统 / 时间 / JSON / 网络;JSON 中英共用 `lib/json.mq.md`;数学与外联暂缓。**
**L1 含文件 / 系统 / 时间 / JSON / 网络 / 数学 / 外联 / 插件;`ext/` 为可选官方扩展(llm、agent)。**
+25
View File
@@ -0,0 +1,25 @@
# 子任务标准库(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
@@ -0,0 +1,36 @@
# 自写回标准库(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`)。
+22 -14
View File
@@ -2,12 +2,13 @@
| | |
|---|---|
| 状态 | **S0–S3 落地** |
| 日期 | 2026-08-04 |
| 相关 | [keywords.md](keywords.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [roadmap/next-phase.md](../roadmap/next-phase.md) |
| 状态 | **S0–S3 + L1 全模块落地** |
| 日期 | 2026-08-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:`;中英分文件)。
> **下一波模块(本波:文件 / 系统 / 时间 / JSON / 网络;数学·外联暂缓)**:见 [stdlib-modules.md](stdlib-modules.md)。
> **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。
> **`ext/` 不是 stdlib**:官方可选扩展见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
---
@@ -15,8 +16,9 @@
| 层 | 内容 |
|----|------|
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at` |
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at`(`type` 可含 `map`) |
| **L1 官方库** | 仓库根目录 [`lib/`](../../lib/)(`.mq.md`);可用 `lib/…` 或别名 `std/…` 导入 |
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1 |
| **L2** | catalog / 用户站收录(随发版) |
---
@@ -28,7 +30,7 @@
| `len` | `value` | 文本标量数或列表长度 |
| `str` | `value` | 显示文本 |
| `int` | `value` | 整数(失败 → 诊断) |
| `type` | `value` | `none`/`bool`/`int`/`text`/`list` |
| `type` | `value` | `none`/`bool`/`int`/`text`/`list`/`map` |
| `trim` | `value` | 去首尾空白 |
| `split` | `value`, `sep` | 文本列表 |
| `join` | `value`, `sep` | 拼接文本 |
@@ -54,23 +56,29 @@ Frontmatter:
1. 相对当前文件
2. `MARQDO_LIB`(可指向 `lib` 目录或仓库根)
3. 当前工作目录的 `lib/`
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
5. **内嵌 stdlib**(v0.1.2+,编译进二进制;无磁盘 `lib/` 时自动使用)
当前模块:
当前模块(API 多为 `##` 自由函数;见 [objects.md](objects.md)):
| 路径 | 导出函数 |
|------|----------|
| 路径 | 导出 |
|------|------|
| `lib/fs.mq.md` / `lib/文件.mq.md` | `read_text`… / `读文本`… |
| `lib/time.mq.md` / `lib/时间.mq.md` | `now_unix`… / `此刻秒`… |
| `lib/sys.mq.md` / `lib/系统.mq.md` | `env_get`… / `取环境`… |
| `lib/json.mq.md` | `parse` `stringify` `get` `keys`(中英同文件) |
| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`… / `获取`… |
| `lib/sys.mq.md` / `lib/系统.mq.md` | `env_get`…、`load_dotenv`… / `取环境`…、`加载环境`… |
| `lib/json.mq.md` | `parse` `stringify` `get` `keys` `quote`(中英同文件) |
| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`…(HTTPS)/ `获取`… |
| `lib/math.mq.md` / `lib/数学.mq.md` | 数值 / 随机 / 公式 / 绘图 |
| `lib/foreign.mq.md` / `lib/外联.mq.md` | 具名围栏外联 |
| `lib/plugin.mq.md` / `lib/插件.mq.md` | `load` / `unload` / `list`(原生 ABI) |
| `lib/writeback.mq.md` / `lib/自写回.mq.md` | `record` `get` `clear` `list` |
| `lib/subtask.mq.md` / `lib/子任务.mq.md` | `spawn` `poll` `wait` `kill` `wait_all` |
| `lib/text.mq.md` | `str_trim` `str_split` `str_join` |
| `lib/文本.mq.md` | `去空白` `拆分` `拼接` |
| `lib/table.mq.md` | `rows` `row_at` |
| `lib/表.mq.md` | `行数` `取行` |
规划中的 L1 扩展见 [stdlib-modules.md](stdlib-modules.md)。
完整清单见 [stdlib-modules.md](stdlib-modules.md)。
---
+11 -2
View File
@@ -13,7 +13,7 @@
| 路径 | 是否入库 | 职责 |
|------|----------|------|
| `doc/` | 是 | 开发者设计 / ADR / 路线图(单数 `doc`,勿再造 `docs/`) |
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / 特性迭代);**双语**:拉丁文件名 = 英文,中文文件名 = 中文编程,同目录并列 |
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / **stdlib** / 特性迭代);**双语**:拉丁文件名 = 英文,中文文件名 = 中文编程,同目录并列。stdlib 含 `plugin`;特性页覆盖对象与 `ext/`(llm / agent) |
| `public/index.html`、`public/pages/` | **否**(ignore) | `marqdo view output` 生成的 HTML |
| `tests/{structure,keywords,errors}/` | 是 | 金样例与失败夹具(含 errors) |
| 远程分支 `gh-pages` | 发布产物 | 发布整个 `public/`(源文件 + 生成 HTML) |
@@ -50,7 +50,16 @@ public/
---
## 4. 验收
## 4. 内容分层(用户站)
| 目录 | 内容 |
|------|------|
| `public/stdlib/` | L1 模块页(含 `plugin` / `插件`);概述注明 `ext/` 非 stdlib |
| `public/features/` | 迭代特性:树遍历、字节码、view、**对象**、**官方扩展** |
设计文档仍在 `doc/design/`(`objects.md`、`ext-llm.md`、`ext-abi.md`、`ext-agent.md`)。
## 5. 验收
1. `public/` 下每个 `.mq.md`(除纯工具模块外)`marqdo run` 退出码 0。
2. `view output public -o public` 后首页为欢迎页,侧栏无 errors。
+42
View File
@@ -0,0 +1,42 @@
# View 调试(`marqdo debug`)
| | |
|---|---|
| 状态 | **v1(独立 debug 页)** |
| 日期 | 2026-08-05 |
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [pipeline-debug.md](pipeline-debug.md) |
## 分工
| 命令 | 角色 |
|------|------|
| `marqdo view` | 文档浏览器:Structure + Execution + Source;函数大纲与搜索;**无断点** |
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;**仅 live** |
静态 `gh-pages` / `view output` **不能**真断点。
## Debug 布局(对齐常见调试器)
参考 VS Code / Chrome DevTools / Jupyter debugger:
```
┌ Toolbar: Start · Continue (F5) · Step (F10) · Stop · status ─┐
├ Files ─┬─ Structure (gutter BP) + outline ─┬─ Variables ┤
│ │ ├─ Breakpoints │
│ │ └─ Call stack │
├────────┴────────────────────────────────────┴────────────────┤
│ Debug Console (session stdout) │
└──────────────────────────────────────────────────────────────┘
```
- 暂停粒度:语句起点(树遍历)。
- 无断点时 Start 停在第一句。
- Structure 为断点面(非 Source 行)。
## API
与此前相同:`POST /api/debug/start|continue|step|stop|breakpoints`(仅 debug 服务)。
## View 大纲
Structure 旁(或窄屏下方)函数树:`#fn-{line}` 锚点 + 搜索框过滤 `data-fn` / `data-fn-path`。
+8 -6
View File
@@ -25,14 +25,14 @@
| 规则 | 要求 |
|------|------|
| 色板 | 页底 `#f5f5f7`;内容面 `#ffffff`;正文 `#1d1d1f`;次要字 `#6e6e73`;分隔 `#d2d2d7`;选中侧栏项反白 |
| 布局 | 壳层 `max-width ≈ 1400px` 居中;侧栏 ≈280px sticky;主内容 `max-width ≈ 58rem`(宽屏可读、不过窄);**≤800px 侧栏收起**,顶栏汉堡(checkbox,无 JS) |
| 布局 | 壳层 `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 根的路径 |
验收:首屏无外网字体请求;宽屏主栏明显宽于早期 `40rem` 方案。
验收:首屏无外网字体请求;宽屏主栏明显宽于早期 `58rem` 方案(现约 `76rem` / 壳 `1680px`)。
---
@@ -88,9 +88,10 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
---
## 4. 信息架构(不变)
## 4. 信息架构
侧栏索引 + 主区三节:结构(AST+注释插回)· 执行 · 源码。表达式为表面语法,非 Debug。
侧栏文件索引 + 主区:结构(AST+注释;旁侧函数大纲可搜索)· 执行 · 源码。表达式为表面语法。
**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
---
@@ -108,7 +109,8 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
## 6. 验收
1. 实时 `view`:HIG 风极简、无外链字体、结构与执行正确;打开目录即见首个文件。
1. 实时 `view`:HIG 风极简、无外链字体、结构与执行正确;打开目录即见首个文件;函数大纲可搜索跳转。
2. `view output public -o public`(或临时目录)生成可点的 `index.html`(首文件)与各 `pages/…`。
3. 静态页中执行区与 `marqdo run` 一致(未加 `--no-exec` 时);失败诊断路径无 `\\?\`。
4. 冷启动无明显外网依赖。
4. 冷启动无明显外网依赖。
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
+82
View File
@@ -0,0 +1,82 @@
# VS Code 扩展 — 分支与提交约定
| | |
|---|---|
| 状态 | **强制约定**(勿在 `main` 提交扩展源码) |
| 扩展分支 | **`vscode-extension`** |
| 设计说明 | [vscode-extension.md](vscode-extension.md) |
---
## 1. 原则(必读)
| 分支 | 是否跟踪 `vscode-extension/` |
|------|-------------------------------|
| **`main`** | **否** — `.gitignore` 含 `/vscode-extension/` |
| **`vscode-extension`** | **是** — 扩展唯一源码所在分支 |
**禁止**在 `main` 上:
- 删除 `.gitignore` 里的 `/vscode-extension/`
- `git add vscode-extension/`
- 把扩展目录「合并进 main」以便发版
发版时从 **`vscode-extension` 分支检出**扩展目录打 VSIX(见 §4),**不是**把扩展提交进 `main`。
---
## 2. 日常开发(扩展)
```bash
git fetch origin
git checkout vscode-extension
cd vscode-extension && npm ci && npm run compile
```
改语法、CLI 检测、扩展版本 → **只在 `vscode-extension` 分支提交**:
```bash
git add vscode-extension/
git commit -m "vscode-extension: <简要说明>"
git push origin vscode-extension
```
---
## 3. 日常开发(CLI / 语言)
在 **`main`** 上改 `src/`、`lib/`、`public/`、`tests/` 等;**不要**顺带提交 `vscode-extension/`。
若本地为了调试 checkout 过扩展目录,工作区里可以有 `vscode-extension/` 文件夹,但应被 ignore,且 **`git status` 不应出现**该目录下文件。
---
## 4. 发版(CLI tag + VSIX)
1. **`main`**:打 tag(如 `v0.1.2`),CI 构建 `marqdo.exe` 等。
2. **VSIX**:Release 工作流在 tag 构建时执行:
```bash
git fetch origin vscode-extension
git checkout origin/vscode-extension -- vscode-extension
cd vscode-extension && npm ci && npm run compile && npx @vscode/vsce package
```
3. 本地脚本 `scripts/release-windows.ps1` 同样假定:先 `git checkout origin/vscode-extension -- vscode-extension`(或已在 `vscode-extension` 分支),再打 VSIX。
扩展版本号与最低 CLI 要求写在 **`vscode-extension/package.json`** 与分支 README,**不要**在 `main` 的 CHANGELOG 里冒充已合并扩展源码。
---
## 5. 给 Agent / 协作者
执行「更新 VS Code 插件」类任务时:
1. **切到或基于 `vscode-extension` 分支**改 `vscode-extension/**`
2. **不要**移除 `main` 上 `.gitignore` 的 `/vscode-extension/`
3. **不要**在 `main` 的 release 提交里包含 `vscode-extension/package-lock.json` 等大文件
4. 仅需在 `main` 更新时:改 `doc/design/vscode-extension.md`、Release 说明、**本文件** — 指针文档即可
---
## 6. 历史说明
v0.1.2 准备阶段曾误将 `vscode-extension/` 并入 `main`(并删除 ignore),导致推送体积过大。已恢复:**扩展仅 `vscode-extension` 分支**;`main` 只保留本约定与设计指针。
+31
View File
@@ -0,0 +1,31 @@
# VS Code 扩展(分支指针)
| | |
|---|---|
| 状态 | **已定分支模型** |
| 代码分支 | **`vscode-extension`**(同仓库) |
| 目录 | 工作区 `vscode-extension/`(**仅在该分支跟踪;`main` 在 `.gitignore` 忽略**) |
| 提交约定 | **[vscode-extension-commit.md](vscode-extension-commit.md)**(必读,避免误提交到 `main`) |
---
## 分工(类比 `public` / `gh-pages`)
| 分支 | 内容 |
|------|------|
| `main` | Marqdo 语言 / CLI / `public/*.mq.md`;**不**存放扩展实现 |
| `vscode-extension` | VS Code 扩展源码、TextMate 语法、VSIX 发版 |
| `gh-pages` | 用户站生成 HTML |
```bash
git checkout vscode-extension
cd vscode-extension && npm install
```
规范入口(在 **`vscode-extension` 分支**上阅读):
- `vscode-extension/README.md` — 目标与目录
- `vscode-extension/DEVELOPMENT.md` — 日常流程
- `vscode-extension/ARCHITECTURE.md` — 与 CLI 边界
扩展是 CLI 的薄宿主;语法真相仍是 [markdown-mapping.md](markdown-mapping.md)。
+5 -4
View File
@@ -2,10 +2,10 @@
| | |
|---|---|
| 状态 | **进行中**(P2 完成;下一:P3-D2 调试会话) |
| 日期 | 2026-08-04 |
| 状态 | **进行中**(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) |
| 相关 | [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) |
---
@@ -16,7 +16,8 @@
| **`print`** | 树遍历 + 字节码均可用 | 够用 |
| **`input`** | CLI 双后端 + `--stdin-file`;frontmatter `stdin:`/`输入:`;live view 表单覆盖;无预置时 capture 提示补线 | **P1a + P1b 完成** |
| **诊断** | 语句级 `path:line:col: message`;字节码指令带 `spans`;errors 金样例双后端断言位置 | **P0 完成** |
| **view** | 结构 + 一次执行 + 源码;注释已 Markdown 渲染;无暂停/断点 | **文档浏览器,不是调试器** |
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
| **模块** | `> file.mq.md` 顶层函数合并,无命名空间 | 短期可继续用 |
+111
View File
@@ -0,0 +1,111 @@
---
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
@@ -0,0 +1,130 @@
---
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
@@ -0,0 +1,130 @@
---
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
@@ -0,0 +1,111 @@
---
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
@@ -0,0 +1,43 @@
/* 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 */
+9 -9
View File
@@ -3,23 +3,23 @@ title: lib/foreign
description: Run bound code fences and inline sources via local interpreters
---
# set_cmd
- lang
- cmd
## set_cmd
+ `lang`
+ `cmd`
**> host_foreign_set_cmd lang=`lang` cmd=`cmd`**
# run
- code
## run
+ `code`
**> host_foreign_run code=`code`**
# run_lang
- lang
- source
## run_lang
+ `lang`
+ `source`
**> host_foreign_run_lang lang=`lang` source=`source`**
# langs
## langs
**> host_foreign_langs**
+16 -16
View File
@@ -3,39 +3,39 @@ title: lib/fs
description: English filesystem wrappers
---
# read_text
- path
## read_text
+ `path`
**> host_read_text path=`path`**
# write_text
- path
- text
## write_text
+ `path`
+ `text`
**> host_write_text path=`path` text=`text`**
# append_text
- path
- text
## append_text
+ `path`
+ `text`
**> host_append_text path=`path` text=`text`**
# exists
- path
## exists
+ `path`
**> host_exists path=`path`**
# list_dir
- path
## list_dir
+ `path`
**> host_list_dir path=`path`**
# make_dir
- path
## make_dir
+ `path`
**> host_make_dir path=`path`**
# remove
- path
## remove
+ `path`
**> host_remove path=`path`**
+27 -9
View File
@@ -3,23 +3,41 @@ title: lib/json
description: JSON parse/stringify (shared EN/ZH import)
---
# parse
- text
## parse
+ `text`
**> host_json_parse text=`text`**
# stringify
- value
## stringify
+ `value`
**> host_json_stringify value=`value`**
# get
- value
- key
## get
+ `value`
+ `key`
**> host_json_get value=`value` key=`key`**
# keys
- value
## keys
+ `value`
**> host_json_keys value=`value`**
## quote
+ `text`
**> host_json_quote text=`text`**
## set
+ `map`
+ `key`
+ `value`
**> host_map_set map=`map` key=`key` value=`value`**
## append
+ `list`
+ `item`
**> host_list_append list=`list` item=`item`**
+88 -88
View File
@@ -3,198 +3,198 @@ title: lib/math
description: High-school math — num, random, formula, plot
---
# pi
## pi
**> host_pi**
# e
## e
**> host_e**
# num
- value
## num
+ `value`
**> host_num value=`value`**
# add
- a
- b
## add
+ `a`
+ `b`
**> host_math_add a=`a` b=`b`**
# sub
- a
- b
## sub
+ `a`
+ `b`
**> host_math_sub a=`a` b=`b`**
# mul
- a
- b
## mul
+ `a`
+ `b`
**> host_math_mul a=`a` b=`b`**
# div
- a
- b
## div
+ `a`
+ `b`
**> host_math_div a=`a` b=`b`**
# pow
- a
- b
## pow
+ `a`
+ `b`
**> host_math_pow a=`a` b=`b`**
# neg
- value
## neg
+ `value`
**> host_math_neg value=`value`**
# sin
- value
## sin
+ `value`
**> host_math_sin value=`value`**
# cos
- value
## cos
+ `value`
**> host_math_cos value=`value`**
# tan
- value
## tan
+ `value`
**> host_math_tan value=`value`**
# asin
- value
## asin
+ `value`
**> host_math_asin value=`value`**
# acos
- value
## acos
+ `value`
**> host_math_acos value=`value`**
# atan
- value
## atan
+ `value`
**> host_math_atan value=`value`**
# sqrt
- value
## sqrt
+ `value`
**> host_math_sqrt value=`value`**
# abs
- value
## abs
+ `value`
**> host_math_abs value=`value`**
# ln
- value
## ln
+ `value`
**> host_math_ln value=`value`**
# exp
- value
## exp
+ `value`
**> host_math_exp value=`value`**
# floor
- value
## floor
+ `value`
**> host_math_floor value=`value`**
# ceil
- value
## ceil
+ `value`
**> host_math_ceil value=`value`**
# min
- a
- b
## min
+ `a`
+ `b`
**> host_math_min a=`a` b=`b`**
# max
- a
- b
## max
+ `a`
+ `b`
**> host_math_max a=`a` b=`b`**
# random
## random
**> host_random**
# random_int
- min
- max
## random_int
+ `min`
+ `max`
**> host_random_int min=`min` max=`max`**
# seed
- value
## seed
+ `value`
**> host_seed value=`value`**
# formula
- text
## formula
+ `text`
**> host_formula value=`text`**
# simplify
- formula
## simplify
+ `formula`
**> host_simplify value=`formula`**
# expand
- formula
## expand
+ `formula`
**> host_expand value=`formula`**
# diff
- formula
- var
## diff
+ `formula`
+ `var`
**> host_diff formula=`formula` var=`var`**
# subs
- formula
- var
- value
## subs
+ `formula`
+ `var`
+ `value`
**> host_subs formula=`formula` var=`var` value=`value`**
# eval
- formula
- var
- value
## eval
+ `formula`
+ `var`
+ `value`
**> host_eval formula=`formula` var=`var` value=`value`**
# solve
- formula
- var
## solve
+ `formula`
+ `var`
**> host_solve formula=`formula` var=`var`**
# plot
- formula
- var
- min
- max
## plot
+ `formula`
+ `var`
+ `min`
+ `max`
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
# plot_points
- xs
- ys
## plot_points
+ `xs`
+ `ys`
**> host_plot_points xs=`xs` ys=`ys`**
# plot_conic
- kind
- a
## plot_conic
+ `kind`
+ `a`
**> host_plot_conic kind=`kind` a=`a`**
+20 -8
View File
@@ -1,20 +1,32 @@
---
title: lib/net
description: English minimal HTTP wrappers
description: English HTTP(S) wrappers. Optional headers / content_type via host aliases.
---
# http_get
- url
## http_get
+ `url`
HTTPS supported. Optional named arg `headers=` (map).
**> host_http_get url=`url`**
# http_post
- url
- body
## http_post
+ `url`
+ `body`
Default content type is JSON. Optional `content_type=` / `headers=` (map).
**> host_http_post url=`url` body=`body`**
# url_encode
- text
## 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
@@ -0,0 +1,17 @@
---
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
@@ -0,0 +1,34 @@
---
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**
+18 -12
View File
@@ -1,33 +1,39 @@
---
title: lib/sys
description: English system wrappers
description: English system wrappers (load_dotenv accepts optional path via host alias)
---
# env_get
- name
## env_get
+ `name`
**> host_env_get name=`name`**
# env_set
- name
- value
## env_set
+ `name`
+ `value`
**> host_env_set name=`name` value=`value`**
# args
## load_dotenv
Load `.env` (optional named arg `path=`). Existing process env is not overridden.
**> host_dotenv_load**
## args
**> host_args**
# cwd
## cwd
**> host_cwd**
# exit
- code
## exit
+ `code`
**> host_exit code=`code`**
# exec
- cmd
## exec
+ `cmd`
**> host_exec cmd=`cmd`**
+5 -5
View File
@@ -3,13 +3,13 @@ title: lib/table
description: English table helpers over len / at
---
# rows
- xs
## rows
+ `xs`
**> len `xs`**
# row_at
- xs
- i
## row_at
+ `xs`
+ `i`
**> at value=`xs` index=`i`**
+8 -8
View File
@@ -3,19 +3,19 @@ title: lib/text
description: English text helpers over trim / split / join
---
# str_trim
- s
## str_trim
+ `s`
**> trim `s`**
# str_split
- s
- sep
## str_split
+ `s`
+ `sep`
**> split value=`s` sep=`sep`**
# str_join
- xs
- sep
## str_join
+ `xs`
+ `sep`
**> join value=`xs` sep=`sep`**
+10 -10
View File
@@ -3,27 +3,27 @@ title: lib/time
description: English time wrappers
---
# now_unix
## now_unix
**> host_now_unix**
# now_ms
## now_ms
**> host_now_ms**
# format
- unix
- pattern
## format
+ `unix`
+ `pattern`
**> host_format_time unix=`unix` pattern=`pattern`**
# sleep_ms
- ms
## sleep_ms
+ `ms`
**> host_sleep_ms ms=`ms`**
# parse
- text
- pattern
## parse
+ `text`
+ `pattern`
**> host_parse_time text=`text` pattern=`pattern`**
+32
View File
@@ -0,0 +1,32 @@
---
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**
+9 -9
View File
@@ -3,23 +3,23 @@ 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
@@ -0,0 +1,34 @@
---
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
@@ -0,0 +1,17 @@
---
title: lib/插件
description: 加载可选原生 ABI 插件(.dll / .so / .dylib)
---
## 加载
+ `路径`
**> host_plugin_load path=`路径`**
## 卸载
**> host_plugin_unload**
## 列出
**> host_plugin_list**
+88 -88
View File
@@ -3,198 +3,198 @@ title: lib/数学
description: 高中数学 — 数值、随机、公式、作图
---
# 圆周率
## 圆周率
**> host_pi**
# 自然底数
## 自然底数
**> host_e**
# 数
- value
## 数
+ `value`
**> host_num value=`value`**
# 加
- a
- b
## 加
+ `a`
+ `b`
**> host_math_add a=`a` b=`b`**
# 减
- a
- b
## 减
+ `a`
+ `b`
**> host_math_sub a=`a` b=`b`**
# 乘
- a
- b
## 乘
+ `a`
+ `b`
**> host_math_mul a=`a` b=`b`**
# 除
- a
- b
## 除
+ `a`
+ `b`
**> host_math_div a=`a` b=`b`**
# 幂
- a
- b
## 幂
+ `a`
+ `b`
**> host_math_pow a=`a` b=`b`**
# 负
- value
## 负
+ `value`
**> host_math_neg value=`value`**
# 正弦
- value
## 正弦
+ `value`
**> host_math_sin value=`value`**
# 余弦
- value
## 余弦
+ `value`
**> host_math_cos value=`value`**
# 正切
- value
## 正切
+ `value`
**> host_math_tan value=`value`**
# 反正弦
- value
## 反正弦
+ `value`
**> host_math_asin value=`value`**
# 反余弦
- value
## 反余弦
+ `value`
**> host_math_acos value=`value`**
# 反正切
- value
## 反正切
+ `value`
**> host_math_atan value=`value`**
# 平方根
- value
## 平方根
+ `value`
**> host_math_sqrt value=`value`**
# 绝对值
- value
## 绝对值
+ `value`
**> host_math_abs value=`value`**
# 对数
- value
## 对数
+ `value`
**> host_math_ln value=`value`**
# 指数
- value
## 指数
+ `value`
**> host_math_exp value=`value`**
# 向下取整
- value
## 向下取整
+ `value`
**> host_math_floor value=`value`**
# 向上取整
- value
## 向上取整
+ `value`
**> host_math_ceil value=`value`**
# 最小
- a
- b
## 最小
+ `a`
+ `b`
**> host_math_min a=`a` b=`b`**
# 最大
- a
- b
## 最大
+ `a`
+ `b`
**> host_math_max a=`a` b=`b`**
# 随机
## 随机
**> host_random**
# 随机整数
- min
- max
## 随机整数
+ `min`
+ `max`
**> host_random_int min=`min` max=`max`**
# 设种子
- value
## 设种子
+ `value`
**> host_seed value=`value`**
# 公式
- text
## 公式
+ `text`
**> host_formula value=`text`**
# 化简
- formula
## 化简
+ `formula`
**> host_simplify value=`formula`**
# 展开
- formula
## 展开
+ `formula`
**> host_expand value=`formula`**
# 求导
- formula
- var
## 求导
+ `formula`
+ `var`
**> host_diff formula=`formula` var=`var`**
# 代入
- formula
- var
- value
## 代入
+ `formula`
+ `var`
+ `value`
**> host_subs formula=`formula` var=`var` value=`value`**
# 求值
- formula
- var
- value
## 求值
+ `formula`
+ `var`
+ `value`
**> host_eval formula=`formula` var=`var` value=`value`**
# 求解
- formula
- var
## 求解
+ `formula`
+ `var`
**> host_solve formula=`formula` var=`var`**
# 绘图
- formula
- var
- min
- max
## 绘图
+ `formula`
+ `var`
+ `min`
+ `max`
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
# 绘点列
- xs
- ys
## 绘点列
+ `xs`
+ `ys`
**> host_plot_points xs=`xs` ys=`ys`**
# 绘圆锥
- kind
- a
## 绘圆锥
+ `kind`
+ `a`
**> host_plot_conic kind=`kind` a=`a`**
+16 -16
View File
@@ -3,39 +3,39 @@ 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=`路径`**
+8 -8
View File
@@ -3,19 +3,19 @@ title: lib/文本
description: 中文文本库:去空白 / 拆分 / 拼接
---
# 去空白
- s
## 去空白
+ `s`
**> trim `s`**
# 拆分
- s
- sep
## 拆分
+ `s`
+ `sep`
**> split value=`s` sep=`sep`**
# 拼接
- xs
- sep
## 拼接
+ `xs`
+ `sep`
**> join value=`xs` sep=`sep`**
+10 -10
View File
@@ -3,27 +3,27 @@ title: lib/时间
description: 中文时间包装
---
# 此刻秒
## 此刻秒
**> host_now_unix**
# 此刻毫秒
## 此刻毫秒
**> host_now_ms**
# 格式化
- 秒
- 格式
## 格式化
+ `秒`
+ `格式`
**> host_format_time unix=`秒` pattern=`格式`**
# 睡眠毫秒
- 毫秒
## 睡眠毫秒
+ `毫秒`
**> host_sleep_ms ms=`毫秒`**
# 解析时间
- 内容
- 格式
## 解析时间
+ `内容`
+ `格式`
**> host_parse_time text=`内容` pattern=`格式`**
+18 -12
View File
@@ -1,33 +1,39 @@
---
title: lib/系统
description: 中文系统包装
description: 中文系统包装(加载环境 可选 路径=)
---
# 取环境
- 名
## 取环境
+ `名`
**> host_env_get name=`名`**
# 设环境
- 名
- 值
## 设环境
+ `名`
+ `值`
**> host_env_set name=`名` value=`值`**
# 参数表
## 加载环境
加载 `.env`(可选具名实参 `路径=`)。不覆盖已有进程环境变量。
**> host_dotenv_load**
## 参数表
**> host_args**
# 工作目录
## 工作目录
**> host_cwd**
# 退出
- 码
## 退出
+ `码`
**> host_exit code=`码`**
# 执行
- 命令
## 执行
+ `命令`
**> host_exec cmd=`命令`**
+20 -8
View File
@@ -1,20 +1,32 @@
---
title: lib/网络
description: 中文简易网络包装
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
@@ -0,0 +1,30 @@
---
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**
+5 -5
View File
@@ -3,13 +3,13 @@ title: lib/表
description: 中文表库:行数 / 取行
---
# 行数
- xs
## 行数
+ `xs`
**> len `xs`**
# 取行
- xs
- i
## 取行
+ `xs`
+ `i`
**> at value=`xs` index=`i`**
+39
View File
@@ -0,0 +1,39 @@
---
title: 人工文档
description: 这是人工写的文档,禁止机器修改
---
对于marqdo这个项目,详细的语法定义为:
---
#标识对象,#main不算特殊这是一个项目的传统入口可以视为是一个对象。
---
##、### 、####等标识函数,不同数目表示从属关系,例如###是##函数的子函数,作用域不超过
这个函数,使用-表示函数的变量名
**** 空返回(None),并结束本函数体
---
无标记行表示注释信息,对于无标记行应该这么约定不是说开头没有符合不然就会出现:
**强调信息**是什么什么
上面应该是一个注释
---
程序语言使用*程序*也就是斜体表示
---
`变量名`表示变量
---
> 表示引用函数
---
有序列表表示分支语句
---
无序列表表示循环语句
---
公式由数学库渲染
---
代码片段由外联库渲染
---
添加一个新的标准库,自写回标准库,自写回的内容必须使用<!---->包裹,这个不会被md识别,
但是这个可以被marqdo识别,当作提示信息或生成结果的一律表示,markdo view要能渲染,以某种方式
---
添加一个新的标准库,子任务库,能够自由的运行子任务,现在的调用还是顺序化的,但是子任务允许多个
进程式的调用,子任务库将成为marqdo的护城河项目,子任务要依赖于父任务,父任务结束子任务一定结束,防止出现问题
+20
View File
@@ -0,0 +1,20 @@
---
title: 手工构造的测试样例
description: AI禁止更改
---
# main
这是人工构建的用于测试的样例
`测试目录` =
|测试文件夹|
|-----|
|structure|
|keyword|
|lib|
- [`测试文件夹`](`测试目录`)
> 打印 `测试文件夹`
+14
View File
@@ -0,0 +1,14 @@
---
title: 手工构造的测试样例
description: AI禁止更改
---
# main
*`a` = True*
*`b` = False*
1. `a` and not `b`
> print text=ok
2. *
> print text=fail
+12
View File
@@ -0,0 +1,12 @@
---
title: 手工构造的测试样例
description: AI禁止更改
---
# main
测试输入
*`name`=> input "你叫什么名字\n"*
> print `name`
+10
View File
@@ -0,0 +1,10 @@
---
title: 手工构造的测试样例
description: AI禁止更改
---
# main
测试输出
> print 欢迎你
+33
View File
@@ -0,0 +1,33 @@
---
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
@@ -0,0 +1,23 @@
---
title: 手工构造的测试样例
description: AI禁止更改
> lib/writeback.mq.md
---
# main
测试写回库
*`name`=>input "你叫什么名字?\n"*
> record `name`
<!-- marqdo-out
123132
-->
+15
View File
@@ -0,0 +1,15 @@
---
title: 手工构造的测试样例
description: AI禁止更改
---
# main
测试分支语句
* `bool_value` = True *
1. `bool_value` == True
> print True
2. *
> print False
+15
View File
@@ -0,0 +1,15 @@
---
title: 手工构造的测试样例
description: AI禁止更改
---
# main
测试循环语句语句
*`n`=0*
- `n` < 42
`n`=`n`+1
> print `n`
+14
View File
@@ -0,0 +1,14 @@
[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
@@ -0,0 +1,574 @@
//! 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
@@ -0,0 +1,14 @@
[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
@@ -0,0 +1,170 @@
//! 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;
}
+1 -1
View File
@@ -24,7 +24,7 @@ Named args can include spaces:
> greet who=marqdo user
## greet
- who
+ `who`
> print text=Welcome, `who`!
+1 -1
View File
@@ -24,7 +24,7 @@ English docs: [`00-welcome.mq.md`](00-welcome.mq.md) (English prose and English
> 问候 谁=marqdo user
## 问候
- 谁
+ `谁`
> 打印 内容=欢迎,`谁`!
+4 -2
View File
@@ -9,8 +9,10 @@
| [`00-welcome.mq.md`](00-welcome.mq.md) / [`00-欢迎.mq.md`](00-欢迎.mq.md) | 首页(英 / 中) |
| [`structure/`](structure/) | 基本结构 |
| [`keywords/`](keywords/) | 关键字与 L0 内置 |
| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联) |
| [`features/`](features/) | 特性迭代 |
| [`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/`。
+12
View File
@@ -0,0 +1,12 @@
---
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
+12
View File
@@ -0,0 +1,12 @@
---
title: 对象与方法
description: 一级标题是类型;更深标题是函数或方法
---
# main
Marqdo 中,单个井号(#)定义对象 / 类型构造体;二级及以上(## …)定义自由函数或方法。构造得到带 _type 标记的 map 句柄。方法调用形如:反引号对象、点、方法名。
详见 doc/design/objects.md。金样例:tests/structure/object-handle.mq.md。官方 ext/llm 与 ext/agent 使用同一模式。
> 打印 内容=对象就绪
+15
View File
@@ -0,0 +1,15 @@
---
title: Official extensions (ext/)
description: Optional packages — not stdlib
---
# main
ext/ holds official optional extensions. They are not part of lib/. Resolve via MARQDO_EXT, ./ext, or ext/ next to the binary.
- ext/llm — OpenAI-compatible chat object. Design: doc/design/ext-llm.md
- ext/agent — agent development framework (layout helpers today; compose with ext/llm for model-backed orchestration). Design: doc/design/ext-agent.md
- Installer: marqdo ext list / add / remove — doc/design/ext-cli.md
- Native plugins: lib/plugin + include/marqdo_abi.h — doc/design/ext-abi.md
> print text=ext-ok
+15
View File
@@ -0,0 +1,15 @@
---
title: 官方扩展(ext/)
description: 可选包 — 不是标准库
---
# main
ext/ 存放官方可选扩展,不属于 lib/。解析顺序:MARQDO_EXT、./ext、或可执行文件旁的 ext/。
- ext/llm(ext/大模型)— OpenAI 兼容聊天。设计:doc/design/ext-llm.md
- ext/agent(ext/智能体)— 智能体开发框架(当前含布局助手;与大模型组合做编排见路线)。设计:doc/design/ext-agent.md
- 安装器:marqdo ext list / add / remove — doc/design/ext-cli.md
- 通用原生插件:lib/plugin + include/marqdo_abi.h — doc/design/ext-abi.md
> 打印 内容=扩展就绪
+4 -4
View File
@@ -10,14 +10,14 @@ Keywords: `True`, `False`, `None`, and `and` / `or` / `not`.
*`a` = True*
*`b` = False*
+ `a` and not `b`
1. `a` and not `b`
> print text=ok
+ *
2. *
> print text=fail
*`probe` = 1*
+ None
1. None
> print text=none-truthy
+ *
2. *
> print text=none-falsy
+4 -4
View File
@@ -10,14 +10,14 @@ description: 真 / 假 / 空 与 且 / 或 / 非
*`a` = 真*
*`b` = 假*
+ `a` 且 非 `b`
1. `a` 且 非 `b`
> 打印 内容=通过
+ *
2. *
> 打印 内容=失败
*`probe` = 1*
+ 空
1. 空
> 打印 内容=空为真
+ *
2. *
> 打印 内容=空为假
+5 -1
View File
@@ -11,7 +11,11 @@ English-named files export English APIs; Chinese-named files export Chinese APIs
No extra allow flags: importing a module means you intend to use it. Under marqdo view or static export, exit soft-fails and long sleeps are clamped so the console stays up.
Modules: text (text / 文本), table (table / 表), files (fs / 文件), time (time / 时间), system (sys / 系统), json (json only), net (net / 网络), math (math / 数学), foreign (foreign / 外联).
Modules: text (text / 文本), table (table / 表), files (fs / 文件), time (time / 时间), system (sys / 系统), json (json only), net (net / 网络), math (math / 数学), foreign (foreign / 外联), plugin (plugin / 插件), writeback (writeback / 自写回), subtask (subtask / 子任务).
From **v0.1.2**, official `lib/*.mq.md` is **embedded in the `marqdo` binary** (disk `lib/` or `MARQDO_LIB` still overrides). Standalone `.exe` works without a separate stdlib zip.
Official optional extensions live under ext/ (not stdlib): ext/llm, ext/agent — see features/05-extensions.mq.md and doc/design/ext-llm.md / ext-agent.md.
Sibling pages in this folder document each module. Chinese overview: 00-索引.mq.md.
+5 -1
View File
@@ -11,7 +11,11 @@ description: 如何导入官方 lib 模块
导入即表示要用对应能力,无需再加允许旗标。marqdo view 或静态导出里,退出会软失败、长睡眠会被钳制,以免拖垮控制台。
模块:文本(text / 文本)、表(table / 表)、文件(fs / 文件)、时间(time / 时间)、系统(sys / 系统)、json(仅 json)、网络(net / 网络)、数学(math / 数学)、外联(foreign / 外联)。
模块:文本(text / 文本)、表(table / 表)、文件(fs / 文件)、时间(time / 时间)、系统(sys / 系统)、json(仅 json)、网络(net / 网络)、数学(math / 数学)、外联(foreign / 外联)、插件(plugin / 插件)、自写回(writeback / 自写回)、子任务(subtask / 子任务)。
自 **v0.1.2** 起,官方 `lib/*.mq.md` **内置于 `marqdo` 二进制**(磁盘 `lib/` 或 `MARQDO_LIB` 仍可覆盖)。单独下载 `.exe` 即可导入标准库,无需再解压 stdlib 包。
官方可选扩展在 ext/(不是标准库):ext/llm、ext/agent — 见 features/05-扩展.mq.md。
各模块说明见本目录其它页。English: 00-overview.mq.md.
+2 -2
View File
@@ -12,7 +12,7 @@ Bare path words must not contain a slash character (parsed as division). Prefer
*`ok` = > exists path=demo.txt *
+ `ok`
1. `ok`
> print text=demo-present
+ *
2. *
> print text=demo-missing
+1 -1
View File
@@ -6,7 +6,7 @@ description: Shared EN/ZH path; parse and stringify
# main
Import lib/json.mq.md from both English and Chinese docs (no translated twin). Functions: parse(text), stringify(value), get(value, key), keys(value). Objects become the map runtime type.
Import lib/json.mq.md from both English and Chinese docs (no translated twin). Functions: parse(text), stringify(value), get(value, key), keys(value), quote(text) — JSON string literal with quotes (for building request bodies). Objects become the map runtime type.
*`obj` = > parse text={} *
+3 -3
View File
@@ -1,12 +1,12 @@
---
title: lib/net — HTTP
description: Minimal HTTP client and URL encode
title: lib/net — HTTP(S)
description: Minimal HTTP(S) client and URL encode
> lib/net.mq.md
---
# main
Import lib/net.mq.md. Functions: http_get(url) returns map status/body, http_post(url, body), url_encode(text). v1 speaks cleartext http only.
Import lib/net.mq.md. Functions: http_get(url), http_post(url, body), http_request(method, url), url_encode(text). HTTPS and optional headers= map are supported. Default post content-type is JSON.
*`e` = > url_encode text=hello world *
+18
View File
@@ -0,0 +1,18 @@
---
title: lib/plugin — native ABI
description: Load optional shared libraries (.dll / .so / .dylib)
> lib/plugin.mq.md
---
# main
Import lib/plugin.mq.md. Functions: load(path), unload(), list(). After load, registered plugin names are callable like other functions. C ABI: include/marqdo_abi.h — see doc/design/ext-abi.md. Path must stay under the program sandbox (cwd / fs root).
*`names` = > list *
*`n` = > len `names` *
1. `n` >= 0
> print text=plugin-ok
2. *
> print text=plugin-bad
+20
View File
@@ -0,0 +1,20 @@
---
title: lib/subtask — concurrent tasks
description: Spawn file, function, or foreign code in parallel
> lib/subtask.mq.md
---
# main
`spawn` picks **one** mode (others default to `None`):
| Argument | Runs | `wait` returns |
|----------|------|----------------|
| `path=` | `marqdo run` child process | exit code |
| `fn=` + optional `args=` | function in a thread (entry module) | return value |
| `code=` | foreign ``` fence ``` subprocess | stdout text |
| `lang=` + `source=` | foreign source subprocess | stdout text |
Also: `poll id=`, `kill id=`, `wait_all`. Parent exit kills file/foreign children.
> print text=subtask overview ok
+4 -4
View File
@@ -1,18 +1,18 @@
---
title: lib/sys — process
description: Env, cwd, args, exit, exec
description: Env, dotenv, cwd, args, exit, exec
> lib/sys.mq.md
---
# main
Import lib/sys.mq.md. Functions: env_get, env_set, args, cwd, exit(code), exec(cmd). Under view, exit soft-fails instead of killing the process.
Import lib/sys.mq.md. Functions: env_get, env_set, load_dotenv(optional path), args, cwd, exit(code), exec(cmd). load_dotenv does not override existing variables. Under view, exit soft-fails instead of killing the process.
*`d` = > cwd *
*`n` = > len `d` *
+ `n` > 0
1. `n` > 0
> print text=cwd-ok
+ *
2. *
> print text=cwd-empty
+15
View File
@@ -0,0 +1,15 @@
---
title: lib/writeback — Jupyter-style writeback
description: Persist run output in the entry .mq.md file
> lib/writeback.mq.md
---
# main
Writeback stores output in `<!-- marqdo-out … -->` blocks in the **entry** file (the one you run).
- `record value=` — default: insert or replace the block **below the call**; `at_end=true` → single block at EOF
- `get` / `clear` — read or remove the adjacent block (or EOF block when `at_end=true`)
- `list` — all output blocks in the entry file
> print text=writeback overview ok
+20
View File
@@ -0,0 +1,20 @@
---
title: lib/子任务 — 并发子任务
description: 文件、函数或外联代码并行执行
> lib/子任务.mq.md
---
# main
`启动`(`spawn`)四选一(其余参数默认 `None`):
| 参数 | 方式 | `等待` 返回 |
|------|------|-------------|
| `路径=` | `marqdo run` 子进程 | 退出码 |
| `函数=` + 可选 `参数=` | 入口模块中的函数(线程) | 返回值 |
| `代码=` | 外联代码块子进程 | stdout 文本 |
| `语言=` + `源码=` | 外联源码子进程 | stdout 文本 |
另有:`探测`、`终止`、`等待全部`。父进程结束会终止文件/外联子进程。
> 打印 内容=子任务总览就绪
+18
View File
@@ -0,0 +1,18 @@
---
title: lib/插件 — 原生 ABI
description: 加载可选共享库(.dll / .so / .dylib)
> lib/插件.mq.md
---
# main
导入 lib/插件.mq.md。函数:加载(路径)、卸载()、列出()。加载后,插件注册的名称可像普通函数一样调用。C 契约见 include/marqdo_abi.h 与 doc/design/ext-abi.md。路径须落在程序沙箱内。
*`names` = > 列出 *
*`n` = > 长度 值=`names` *
1. `n` >= 0
> 打印 内容=插件就绪
2. *
> 打印 内容=插件异常
+2 -2
View File
@@ -12,7 +12,7 @@ description: 沙箱内读写文本
*`ok` = > 存在 路径=demo.txt *
+ `ok`
1. `ok`
> 打印 内容=有演示文件
+ *
2. *
> 打印 内容=无演示文件
+4 -4
View File
@@ -1,18 +1,18 @@
---
title: lib/系统 — 进程
description: 环境变量、工作目录、参数、退出、执行
description: 环境变量、dotenv、工作目录、参数、退出、执行
> lib/系统.mq.md
---
# main
导入 lib/系统.mq.md。函数:取环境、设环境、参数表、工作目录、退出(码)、执行(命令)。view 下退出会软失败,不结束进程。
导入 lib/系统.mq.md。函数:取环境、设环境、加载环境(可选路径)、参数表、工作目录、退出(码)、执行(命令)。加载环境不覆盖已有变量。view 下退出会软失败,不结束进程。
*`d` = > 工作目录 *
*`n` = > 长度 值=`d` *
+ `n` > 0
1. `n` > 0
> 打印 内容=工作目录就绪
+ *
2. *
> 打印 内容=工作目录空
+2 -2
View File
@@ -1,12 +1,12 @@
---
title: lib/网络 — HTTP
description: 简易 HTTP 与地址编码
description: HTTP(S) 与地址编码
> lib/网络.mq.md
---
# main
导入 lib/网络.mq.md。函数:获取(地址) 返回 map status/body、提交(地址, 内容)、编码地址(内容)。本波仅明文 http。
导入 lib/网络.mq.md。函数:获取(地址)、提交(地址, 内容;可选 content_type / headers)、编码地址(内容)。支持 HTTP 与 HTTPS(ureq)。
*`e` = > 编码地址 内容=你好 *
+15
View File
@@ -0,0 +1,15 @@
---
title: lib/自写回 — Jupyter 式写回
description: 把运行结果写回入口 .mq.md
> lib/自写回.mq.md
---
# main
自写回把结果写入入口文件(你 `run` 的那份 `.mq.md`)里的 `<!-- marqdo-out … -->` 块。
- `记录 内容=`(`record`)— 默认写在调用下方;`at_end=真` 则在文件末尾单独一块
- `读取` / `清除` — 读或删相邻块(`at_end` 时指 EOF 块)
- `列表` — 列出文件中所有输出块
> 打印 内容=自写回总览就绪
+1 -1
View File
@@ -12,6 +12,6 @@ Call with `>` and named args `param=value`:
> greet who=World
## greet
- who
+ `who`
> print text=Hello `who`!
+1 -1
View File
@@ -12,6 +12,6 @@ description: `#` 定义函数;`>` 调用;`-` 列出参数名
> 问候 谁=世界
## 问候
- 谁
+ `谁`
> 打印 内容=你好 `谁`!
Loaded 100 of 182 files, more files were not shown because too many files have changed in this diff. Show more