Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
111849d92a | ||
|
|
235384fb85 | ||
|
|
a9b59b361e | ||
|
|
c4501a17f2 | ||
|
|
5f00572e24 |
No files matched your search
@@ -1,159 +0,0 @@
|
||||
---
|
||||
name: marqdo
|
||||
description: >-
|
||||
Author and edit Marqdo programs (.mq.md): Markdown markers are executable
|
||||
syntax (functions, calls, statements, returns, control flow). Use when writing
|
||||
or modifying .mq.md files, teaching Marqdo, generating Marqdo from prose,
|
||||
importing lib/*, running marqdo CLI, or when the user mentions Marqdo,
|
||||
mq.md, markup-as-syntax, or code-as-documentation.
|
||||
---
|
||||
|
||||
# Marqdo development
|
||||
|
||||
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
|
||||
|
||||
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
|
||||
## Hard rules (do not violate)
|
||||
|
||||
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
|
||||
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
|
||||
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
|
||||
5. **Identifiers use backticks** — params `` + `name` ``, bindings `` `x` ``, foreach `` [`item`](`coll`) ``. **Complex text** uses `"..."` with escapes; bare tokens stay literal (no `\n` magic).
|
||||
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
|
||||
7. **Paths in bare expressions:** `/` is division. Prefer `` `path` `` vars, same-dir names, or call args — not raw `a/b` in expressions.
|
||||
8. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
|
||||
|
||||
## Markup → meaning (v0.2)
|
||||
|
||||
| Marker | Meaning |
|
||||
|--------|---------|
|
||||
| `#` | **Object / type** (constructor body). `# main` = entry object. |
|
||||
| `##` … `######` | **Function / method** (nesting by heading depth). |
|
||||
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
|
||||
| `1.` `2.` … in body | Branch arm (condition or `N. *` else) |
|
||||
| `- …` inside body | Loop (`while` or `` [`item`](`coll`) ``) |
|
||||
| Line `N. *` | Else arm |
|
||||
| `> fn args` | Call (named `k=v` or positional) |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter `> path.mq.md` | Import |
|
||||
| `*…*` | Statement (bind / expr) |
|
||||
| `**…**` | Return value |
|
||||
| `****` or `**` + spaces + `**` | Return `None` and end function body |
|
||||
| Lone `---` / `***` in function body | End function body (no value) |
|
||||
| GFM table after empty RHS bind | Collection |
|
||||
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
|
||||
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
|
||||
| Unmarked prose | Comment |
|
||||
|
||||
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
|
||||
|
||||
## Minimal program
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
Chinese builtins (same functions, no import):
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=你好
|
||||
```
|
||||
|
||||
## Functions, calls, end-body
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> greet who=Marqdo
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
- Call: `> name key=value` or `> name value`.
|
||||
- Nested helpers use deeper `#` (`##`, `###`, …).
|
||||
- After a helper with only side effects, end with `---` / `***`.
|
||||
|
||||
## Statements, returns, branches
|
||||
|
||||
```markdown
|
||||
*`x` = 1*
|
||||
*`y` = `x` + 2*
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
```markdown
|
||||
*`n` = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
2. `n` < 0
|
||||
> print text=negative
|
||||
3. *
|
||||
> print text=zero
|
||||
```
|
||||
|
||||
## Frontmatter imports + stdlib
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: example
|
||||
> lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`xs` = > split value=a,b,c sep=,*
|
||||
> print text=`xs`
|
||||
```
|
||||
|
||||
- Import **English** or **Chinese** library file; call that file’s API names (do not mix).
|
||||
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm` / `add agent` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — agent framework (layout + ABI; compose LLM per `doc/design/ext-agent.md`).
|
||||
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
|
||||
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
|
||||
Stdlib map: [reference.md](reference.md).
|
||||
|
||||
## AI authoring workflow
|
||||
|
||||
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
2. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
|
||||
3. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
|
||||
4. On `path:line:col: message`, fix that span; re-run until exit 0.
|
||||
5. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
|
||||
|
||||
## Anti-patterns (common model mistakes)
|
||||
|
||||
| Wrong | Right |
|
||||
|-------|-------|
|
||||
| `**Hello**` to print | `> print text=Hello` |
|
||||
| `# main` then prose then code with no blank line | Blank line before code |
|
||||
| `if x > 0:` | `1. `x` > 0` |
|
||||
| `* > print text=hi *` | `> print text=hi` |
|
||||
| Forgetting `---` after nested `##` helper | Add `---` / `***` / `****` |
|
||||
| Import `lib/text` then call `拆分` | Match file language |
|
||||
|
||||
## Checklist before finishing
|
||||
|
||||
- [ ] File ends with `.mq.md`
|
||||
- [ ] Print via `print` / `打印`, not bold
|
||||
- [ ] Blank lines separate comment paragraphs from code
|
||||
- [ ] `# main` exists when the file is an entry program
|
||||
- [ ] Nested functions ended with `---` / `***` / `****` when needed
|
||||
- [ ] Imports and call names share the same language file
|
||||
- [ ] `marqdo run` succeeds (or errors addressed)
|
||||
@@ -1,162 +0,0 @@
|
||||
# Marqdo examples (AI)
|
||||
|
||||
## 1. Hello (English)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
## 2. Hello (Chinese builtins)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=你好,世界!
|
||||
```
|
||||
|
||||
## 3. Function + named call + body end
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
Greeting via a nested function:
|
||||
|
||||
> greet who=Marqdo
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## 4. Bindings and return
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*`a` = 2*
|
||||
*`b` = > add_one n=`a`*
|
||||
> print text=`b`
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
## 5. Branch with else
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*`n` = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
2. `n` < 0
|
||||
> print text=negative
|
||||
3. *
|
||||
> print text=zero
|
||||
```
|
||||
|
||||
## 6. Foreach loop
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`篮子` =
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
|
||||
- [`果`](`篮子`)
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
## 7. Import text stdlib
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: split demo
|
||||
> lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`parts` = > split value=a,b,c sep=,*
|
||||
> print text=`parts`
|
||||
```
|
||||
|
||||
## 8. Comment paragraphs (blank-line rule)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
This whole paragraph is a comment, including lines that look like code:
|
||||
*`not_executed` = 1*
|
||||
> print text=also still comment
|
||||
|
||||
After a blank line, code runs:
|
||||
|
||||
> print text=this runs
|
||||
```
|
||||
|
||||
## 9. Frontmatter import only
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: loads math
|
||||
> lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`t` = > num value=3.5*
|
||||
> print text=`t`
|
||||
```
|
||||
|
||||
## 10. Object handle + method
|
||||
|
||||
See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` constructs a map with `_type`; methods use `` > `obj`.method `` and read `self` / `自`.
|
||||
|
||||
## 11. Agent layout (ABI)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load_native
|
||||
|
||||
*`ws` = > agent *
|
||||
*`n` = > `ws`.ensure_layout *
|
||||
> print text=`n`
|
||||
```
|
||||
|
||||
Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see `doc/design/ext-agent.md`).
|
||||
|
||||
## 12. What not to emit
|
||||
|
||||
```markdown
|
||||
# BAD — bold is return, not print
|
||||
**Hello**
|
||||
|
||||
# BAD — Python control keywords
|
||||
if x > 0:
|
||||
print(x)
|
||||
|
||||
# BAD — wrapping a call in italics
|
||||
*> print text=hi*
|
||||
|
||||
# BAD — old branch syntax (removed)
|
||||
+ `x` > 0
|
||||
|
||||
# GOOD — ordered list arms
|
||||
1. `x` > 0
|
||||
```
|
||||
@@ -1,135 +0,0 @@
|
||||
# Marqdo reference (AI)
|
||||
|
||||
Load this when you need stdlib names, CLI, or edge cases. Core rules stay in [SKILL.md](SKILL.md).
|
||||
|
||||
## CLI
|
||||
|
||||
```text
|
||||
marqdo --version
|
||||
marqdo run FILE.mq.md
|
||||
marqdo run FILE.mq.md --backend bytecode
|
||||
marqdo view PATH # docs browser, default port 7429
|
||||
marqdo debug PATH # debugger UI, default port 7430
|
||||
marqdo catalog PATH -o .marqdo
|
||||
marqdo ext list
|
||||
marqdo ext add llm|agent
|
||||
marqdo ext remove llm|agent
|
||||
```
|
||||
|
||||
Diagnostics look like `path:line:col: message` (1-based line/col).
|
||||
|
||||
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * ``; loops `` - [`item`](`coll`) ``; identifiers in backticks. See `doc/design/markdown-mapping.md`.
|
||||
|
||||
Stdlib search order for `lib/…` imports: `MARQDO_LIB`, `./lib`, directory of the `marqdo` executable (and a few parents). Prefer the **bundle zip** (`marqdo.exe` + `lib/`) over a bare exe.
|
||||
|
||||
官方扩展(`ext/…`,非 stdlib):`marqdo ext add` 装到 `MARQDO_EXT` 或 `~/.marqdo/ext`;导入仍写 `> ext/llm.mq.md`。解析还含 cwd `ext/`、二进制旁 `ext/`。对象:`doc/design/objects.md`。Agent:`doc/design/ext-agent.md` · 安装器:`doc/design/ext-cli.md`。
|
||||
|
||||
## Builtins (no import)
|
||||
|
||||
| EN | ZH | Role |
|
||||
|----|----|------|
|
||||
| `print` | `打印` | stdout; arg `text` / `内容` |
|
||||
| `input` | `输入` | one line; arg `prompt` / `提示` |
|
||||
| `len` | `长度` | length; arg `value` / `值` |
|
||||
| `str` | `文本` | to text; arg `value` / `值` |
|
||||
| `int` | `整数` | to int; arg `value` / `值` |
|
||||
|
||||
Keywords (not variable names): `True`/`真`, `False`/`假`, `None`/`空`, `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
|
||||
## Standard library files
|
||||
|
||||
Import one file; use **that** file’s function names.
|
||||
|
||||
| EN import | ZH import | Typical APIs (EN / ZH) |
|
||||
|-----------|-----------|-------------------------|
|
||||
| `lib/text.mq.md` | `lib/文本.mq.md` | text helpers / 去空白·拆分·拼接… |
|
||||
| `lib/table.mq.md` | `lib/表.mq.md` | table/rows helpers |
|
||||
| `lib/fs.mq.md` | `lib/文件.mq.md` | filesystem |
|
||||
| `lib/sys.mq.md` | `lib/系统.mq.md` | process / cwd / load_dotenv |
|
||||
| `lib/plugin.mq.md` | `lib/插件.mq.md` | load native ABI plugins (`doc/design/ext-abi.md`) |
|
||||
| `lib/time.mq.md` | `lib/时间.mq.md` | time/format |
|
||||
| `lib/net.mq.md` | `lib/网络.mq.md` | HTTP(S) helpers (+ optional headers) |
|
||||
| `lib/json.mq.md` | (see design) | JSON (+ `quote`) |
|
||||
| `lib/math.mq.md` | `lib/数学.mq.md` | num, trig, random, formula, plot |
|
||||
| `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks |
|
||||
| `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods |
|
||||
| `ext/agent.mq.md` | `ext/智能体.mq.md` | agent **framework** (layout now; LLM orchestration roadmap in `ext-agent.md`) |
|
||||
|
||||
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
|
||||
|
||||
## Formula + plot (math)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*`_svg` = > plot formula=`f` var=x min=-3 max=3 *
|
||||
```
|
||||
|
||||
Empty RHS assignment + following `$$…$$` binds a formula value. Narrative-only `$$` without binding is display, not assignment.
|
||||
|
||||
## Foreign (Python example)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
```
|
||||
|
||||
Lines starting with `` ` `` can be code (binding). Keep a blank line before/after fences per comment rules.
|
||||
|
||||
## Function-end details
|
||||
|
||||
| Form | Effect |
|
||||
|------|--------|
|
||||
| Lone `---` or `***` (≥3 same chars) at function body top level | End function; no return value |
|
||||
| `****` or empty bold | Return `None` and end body |
|
||||
| `**expr**` | Return `expr`; does **not** by itself cut off later sibling statements — still use HR or shallower heading |
|
||||
|
||||
File-leading paired `---` is frontmatter only; body `---` is not frontmatter.
|
||||
|
||||
## Call arguments
|
||||
|
||||
- Named: `> greet who=World`
|
||||
- Positional: `> greet World`
|
||||
- Spaces in values: allowed in named forms as in docs (`who=marqdo user`)
|
||||
- Inline call in statement: `` *`n` = > len value=`s`* ``
|
||||
|
||||
See `doc/design/call-arguments.md`.
|
||||
|
||||
## Identifiers
|
||||
|
||||
- Variables: `` `name` ``
|
||||
- Comparisons: `==` `>` `<` `>=` `<=`
|
||||
- Do not use keyword tokens as names
|
||||
|
||||
## Design docs (repo)
|
||||
|
||||
| Doc | Topic |
|
||||
|-----|--------|
|
||||
| `doc/design/markdown-mapping.md` | Syntax constitution |
|
||||
| `doc/design/objects.md` | `#` objects / `##` methods |
|
||||
| `doc/design/keywords.md` | Builtins / keywords |
|
||||
| `doc/design/return-hr-and-code-surface.md` | Function end / surfaces |
|
||||
| `doc/design/stdlib-i18n.md` | EN/ZH lib files |
|
||||
| `doc/design/stdlib-modules.md` | L1 modules including plugin |
|
||||
| `doc/design/ext-abi.md` | Native C ABI v1 |
|
||||
| `doc/design/ext-llm.md` | `ext/llm` |
|
||||
| `doc/design/ext-agent.md` | `ext/agent` agent **framework** (layout shipped; LLM orchestration roadmap) |
|
||||
| `doc/design/ext-cli.md` | `marqdo ext list/add/remove` |
|
||||
| `doc/design/view-debug.md` | view / debug hosts |
|
||||
@@ -1,50 +0,0 @@
|
||||
# Build public/ with marqdo and publish to the gh-pages branch.
|
||||
name: User docs site
|
||||
|
||||
on:
|
||||
push:
|
||||
branches: [main, master]
|
||||
paths:
|
||||
- "public/**"
|
||||
- "src/**"
|
||||
- "Cargo.toml"
|
||||
- "Cargo.lock"
|
||||
- ".github/workflows/pages.yml"
|
||||
- "scripts/build-public.*"
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
build-and-deploy:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Install Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Build & export site
|
||||
run: |
|
||||
cargo build --release
|
||||
find public -name '*.mq.md' ! -name 'utils.mq.md' ! -name '¹¤¾ß.mq.md' -print0 \
|
||||
| xargs -0 -n1 ./target/release/marqdo run
|
||||
./target/release/marqdo view output public -o public
|
||||
|
||||
- name: Verify site shape
|
||||
run: |
|
||||
if grep -R "tests/errors" public --include='*.html' ; then
|
||||
echo "user site must not include tests/errors fixtures" >&2
|
||||
exit 1
|
||||
fi
|
||||
test -f public/index.html
|
||||
test -f public/00-welcome.mq.md
|
||||
|
||||
- name: Deploy to gh-pages
|
||||
uses: peaceiris/actions-gh-pages@v4
|
||||
with:
|
||||
github_token: ${{ secrets.GITHUB_TOKEN }}
|
||||
publish_dir: ./public
|
||||
publish_branch: gh-pages
|
||||
force_orphan: true
|
||||
@@ -1,102 +0,0 @@
|
||||
# Build and attach release binaries when a version tag is pushed.
|
||||
name: Release
|
||||
|
||||
on:
|
||||
push:
|
||||
tags:
|
||||
- "v*"
|
||||
|
||||
permissions:
|
||||
contents: write
|
||||
|
||||
jobs:
|
||||
windows:
|
||||
runs-on: windows-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Install Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Install Node (VS Code extension)
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: "20"
|
||||
|
||||
- name: Build release
|
||||
run: cargo build --release
|
||||
|
||||
- name: Checkout extension sources (branch vscode-extension only)
|
||||
run: git fetch origin vscode-extension && git checkout origin/vscode-extension -- vscode-extension
|
||||
|
||||
- name: Build VSIX
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ver = "${{ github.ref_name }}".TrimStart("v")
|
||||
Push-Location vscode-extension
|
||||
npm ci
|
||||
npm run compile
|
||||
npx @vscode/vsce package --no-dependencies -o "../dist/marqdo-$ver.vsix"
|
||||
Pop-Location
|
||||
|
||||
- name: Package
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ver = "${{ github.ref_name }}".TrimStart("v")
|
||||
$target = "x86_64-pc-windows-msvc"
|
||||
New-Item -ItemType Directory -Force -Path dist | Out-Null
|
||||
$exe = "marqdo-$ver-$target.exe"
|
||||
$zip = "marqdo-$ver-$target.zip"
|
||||
$stdlib = "marqdo-$ver-stdlib.zip"
|
||||
$vsix = "marqdo-$ver.vsix"
|
||||
Copy-Item target/release/marqdo.exe "dist/$exe"
|
||||
$stage = "dist/stage-bundle"
|
||||
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path $stage | Out-Null
|
||||
Copy-Item target/release/marqdo.exe "$stage/marqdo.exe"
|
||||
Copy-Item lib "$stage/lib" -Recurse
|
||||
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
|
||||
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
|
||||
$stageLib = "dist/stage-stdlib"
|
||||
if (Test-Path $stageLib) { Remove-Item $stageLib -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path $stageLib | Out-Null
|
||||
Copy-Item lib "$stageLib/lib" -Recurse
|
||||
if (Test-Path "dist/$stdlib") { Remove-Item "dist/$stdlib" -Force }
|
||||
Compress-Archive -Path "$stageLib/*" -DestinationPath "dist/$stdlib" -Force
|
||||
echo "EXE=$exe" >> $env:GITHUB_ENV
|
||||
echo "ZIP=$zip" >> $env:GITHUB_ENV
|
||||
echo "STDLIB=$stdlib" >> $env:GITHUB_ENV
|
||||
echo "VSIX=$vsix" >> $env:GITHUB_ENV
|
||||
|
||||
- name: Upload release assets
|
||||
uses: softprops/action-gh-release@v2
|
||||
with:
|
||||
body: |
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### Highlights
|
||||
- **Embedded stdlib** (v0.1.2+): `lib/*.mq.md` built into the binary
|
||||
- **writeback** + **subtask** stdlibs
|
||||
- **`marqdo version --check`**
|
||||
- VSIX built from branch **`vscode-extension`** (not tracked on `main`)
|
||||
|
||||
### Downloads
|
||||
|
||||
| Asset | Contents |
|
||||
|-------|----------|
|
||||
| `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib |
|
||||
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` (optional disk override) |
|
||||
| `marqdo-*-stdlib.zip` | `lib/` only |
|
||||
| `marqdo-*.vsix` | VS Code / Cursor extension |
|
||||
|
||||
Extension workflow: [doc/design/vscode-extension-commit.md](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension-commit.md)
|
||||
files: |
|
||||
dist/${{ env.EXE }}
|
||||
dist/${{ env.ZIP }}
|
||||
dist/${{ env.STDLIB }}
|
||||
dist/${{ env.VSIX }}
|
||||
fail_on_unmatched_files: true
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
+1
-39
@@ -1,39 +1 @@
|
||||
/target/
|
||||
/dist/
|
||||
|
||||
# Copied by gold harness for ABI plugins
|
||||
/tests/lib/demo.dll
|
||||
/tests/lib/libdemo.so
|
||||
/tests/lib/libdemo.dylib
|
||||
/tests/ext/agent.dll
|
||||
/tests/ext/libagent.so
|
||||
/tests/ext/libagent.dylib
|
||||
/tests/ext/skel.mq.md
|
||||
/tests/ext/out-demo.mq.md
|
||||
/tests/ext/ticket.txt
|
||||
/tests/ext/ticket-stub.txt
|
||||
/tests/ext/agents/
|
||||
/tests/ext/runbooks/
|
||||
/tests/ext/templates/
|
||||
/tests/ext/reports/
|
||||
**/*.rs.bk
|
||||
.idea/
|
||||
.vscode/
|
||||
*.pdb
|
||||
.DS_Store
|
||||
.marqdo/
|
||||
.env
|
||||
|
||||
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
|
||||
/public/index.html
|
||||
/public/pages/
|
||||
|
||||
# VS Code extension: source only on branch `vscode-extension` (see doc/design/vscode-extension-commit.md)
|
||||
/vscode-extension/
|
||||
|
||||
# Python spike venv (local)
|
||||
spike/.venv/
|
||||
spike/__pycache__/
|
||||
spike/.pytest_cache/
|
||||
**/__pycache__/
|
||||
*.pyc
|
||||
/target
|
||||
@@ -1,22 +0,0 @@
|
||||
# Changelog
|
||||
|
||||
## v0.1.2 — 2026-08-07
|
||||
|
||||
### Added
|
||||
- **Embedded standard library**: official `lib/*.mq.md` ships inside the `marqdo` binary; disk `lib/` and `MARQDO_LIB` still override.
|
||||
- **`lib/writeback`** / **`lib/subtask`**: Jupyter-style writeback; concurrent subtasks (file / function / foreign).
|
||||
- **Surface syntax v0.2**: `` + `param` `` parameters, `1.` ordered branches, backtick identifiers, quoted strings.
|
||||
- **`marqdo version --check`**: compare installed CLI with latest GitHub release.
|
||||
- **VS Code extension v0.0.6** (branch **`vscode-extension` only**): v0.2 grammar, update check — see [doc/design/vscode-extension-commit.md](doc/design/vscode-extension-commit.md)
|
||||
|
||||
### Changed
|
||||
- Subtask `spawn` accepts `path=`, `fn=`, `code=`, or `lang=`+`source=` (not file-only).
|
||||
- Release notes: standalone `.exe` includes stdlib; bundle/stdlib zips remain optional for overrides.
|
||||
|
||||
## v0.1.1
|
||||
|
||||
- v0.2 syntax migration, writeback/subtask v1 (file subprocess only), view input deferral, optional parameters.
|
||||
|
||||
## v0.1.0
|
||||
|
||||
- Initial public releases: tree + bytecode backends, `view` / `debug` / `catalog`, core stdlib, `ext/` installer.
|
||||
Generated
+1
-1157
File diff suppressed because it is too large.
Load diff
+5
-30
@@ -1,35 +1,10 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.1.2"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
readme = "README.md"
|
||||
repository = "https://github.com/cflmy/marqdo"
|
||||
version = "0.1.0"
|
||||
edition = "2024"
|
||||
|
||||
[dependencies]
|
||||
|
||||
[[bin]]
|
||||
name = "marqdo"
|
||||
path = "src/main.rs"
|
||||
|
||||
[dependencies]
|
||||
anyhow = "1"
|
||||
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
|
||||
clap = { version = "=4.4.18", features = ["derive"] }
|
||||
pulldown-cmark = "0.12"
|
||||
serde_json = "1"
|
||||
thiserror = "1"
|
||||
tiny_http = "0.12"
|
||||
# Pin for Cargo/rustc 1.81 (newer rustls/idna/zeroize need edition2024).
|
||||
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"] }
|
||||
idna_adapter = "=1.1.0"
|
||||
zeroize = "=1.8.1"
|
||||
libloading = "=0.8.6"
|
||||
include_dir = "0.7"
|
||||
|
||||
[workspace]
|
||||
members = ["plugins/demo", "plugins/agent"]
|
||||
resolver = "2"
|
||||
|
||||
[dev-dependencies]
|
||||
assert_cmd = "=2.0.14"
|
||||
predicates = "=3.1.0"
|
||||
path = "src/marqdo.rs"
|
||||
@@ -1,201 +0,0 @@
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
|
||||
APPENDIX: How to apply the Apache License to your work.
|
||||
|
||||
To apply the Apache License to your work, attach the following
|
||||
boilerplate notice, with the fields enclosed by brackets "[]"
|
||||
replaced with your own identifying information. (Don't include
|
||||
the brackets!) The text should be enclosed in the appropriate
|
||||
comment syntax for the file format. We also recommend that a
|
||||
file or class name and description of purpose be included on the
|
||||
same "printed page" as the copyright notice for easier
|
||||
identification within third-party archives.
|
||||
|
||||
Copyright [yyyy] [name of copyright owner]
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
@@ -1,137 +0,0 @@
|
||||
# Marqdo
|
||||
|
||||
**代码即文档。文档即代码。文档即知识库。**
|
||||
|
||||
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
|
||||
|
||||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
||||
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
## 为什么重要
|
||||
|
||||
| 痛点 | Marqdo 的答案 |
|
||||
|------|----------------|
|
||||
| 文档过期、示例跑不通 | **一份源文件**:叙述、结构与执行结果同源 |
|
||||
| 知识散落在 Wiki / 注释 / 脚本里 | **`.mq.md` 即知识单元**,可浏览、可运行、可检索 |
|
||||
| 人写给人看,AI / 工具另起一套 | **人机同读同写同构**:标记语言对人类友好,对解释器确定 |
|
||||
| 大仓里「文档站」与「代码仓」脱节 | `view` 文档站 + `debug` 调试面 + `catalog` 清单,同一棵树长大 |
|
||||
|
||||
这不是「再做一个 Markdown 渲染器」,而是:**把文档升格为可解释的程序与可生长的知识库**,让协作在大型项目里依然站得住。
|
||||
|
||||
---
|
||||
|
||||
## 语法速览(v0.2)
|
||||
|
||||
| 标记 | 含义 |
|
||||
|------|------|
|
||||
| 无标记行 | 注释(空行分段) |
|
||||
| `*…*` | 程序语句 |
|
||||
| `**…**` | **返回值**(架构) |
|
||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||||
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
|
||||
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
|
||||
| `##` … | 函数 / 方法(按标题深度嵌套) |
|
||||
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
|
||||
| `+` / `1.` … | 函数头下 `` + `名` `` = 形参;体内 `1.` `2.` … = 分支(`N. *` = else) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [`项`](`集合`) ``) |
|
||||
| 表格 | 集合 |
|
||||
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
|
||||
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello `谁`!
|
||||
|
||||
---
|
||||
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
完整约定:[markdown-mapping.md](doc/design/markdown-mapping.md)。
|
||||
|
||||
---
|
||||
|
||||
## 理念
|
||||
|
||||
1. **叙述默认安全**(无标记 = 注释)。
|
||||
2. **返回是架构;打印只是函数。**
|
||||
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
|
||||
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
|
||||
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
|
||||
|
||||
---
|
||||
|
||||
## OKF 风格清单(自动生成)
|
||||
|
||||
从源码派生 YAML / Markdown 知识包(勿手改生成物):
|
||||
|
||||
```bash
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
marqdo sync [PATH] -o OUT_DIR # catalog 的别名
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
|
||||
| `-o` / `--out` | `.marqdo` | 输出目录 |
|
||||
|
||||
产物示例:`catalog.yaml`、`index.md`、`modules/*.md`(`type: Marqdo Module` 等)。设计见 [generated-yaml-manifest.md](doc/design/generated-yaml-manifest.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
|
||||
|
||||
```bash
|
||||
cargo run -- catalog public -o .marqdo
|
||||
# 或已安装二进制时:
|
||||
marqdo catalog public -o .marqdo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 现状(v0.1.2)
|
||||
|
||||
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Source)
|
||||
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
|
||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
|
||||
- **`marqdo version --check`**:与 GitHub 最新 release 对比
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**
|
||||
- **官方扩展 `ext/`**(非 stdlib):[`ext/llm`](doc/design/ext-llm.md);[`ext/agent`](doc/design/ext-agent.md) 智能体开发框架。安装:`marqdo ext list` / `add llm|agent` / `remove`(见 [ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext` 或 `MARQDO_EXT`)
|
||||
- **原生插件 ABI v1**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);demo `plugins/demo`
|
||||
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
|
||||
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
|
||||
|
||||
```bash
|
||||
cargo run -- run tests/structure/hello.mq.md
|
||||
cargo run -- run tests/structure/hello.mq.md --backend bytecode
|
||||
cargo run -- view public --no-open
|
||||
cargo run -- debug public --no-open
|
||||
cargo run -- catalog public -o .marqdo
|
||||
cargo run -- view output public -o public
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
**发布包(GitHub Releases)**:自 **v0.1.2** 起,单独 `.exe` **已内置**官方 `lib/`(`> lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发;`ext/` 与原生插件 `.dll` 仍须单独安装。`marqdo version --check` 可查看是否有新版本。OpenAI 兼容聊天见 [ext-llm.md](doc/design/ext-llm.md)。智能体布局见 [ext-agent.md](doc/design/ext-agent.md)。
|
||||
|
||||
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md)
|
||||
|
||||
---
|
||||
|
||||
## 命名
|
||||
|
||||
**Marqdo** = Marq(Markdown)+ do(执行)
|
||||
|
||||
## 许可
|
||||
|
||||
[Apache License 2.0](LICENSE)
|
||||
@@ -0,0 +1,91 @@
|
||||
---
|
||||
title: Marqdo主分支开发记录
|
||||
date: 2026-08-11
|
||||
author: pingan
|
||||
---
|
||||
|
||||
## 前言
|
||||
在经过一周多的ai疯狂开发之后,尽管marqdo已经做出了并拥有了许多非常良好的特性,作者确逐渐感到非常的不安,
|
||||
这种不安来自于崩塌感,作者不知道什么时候,ai就会更改关键的定义,导致突然的崩塌,在开发智能体拓展库的时候作者还尚未有这种感觉,但是在网络拓展库,这种不安定感几乎席卷了作者的全部身心。
|
||||
|
||||
必须承认,ai在没有经过大量训练就撰写一门崭新的语法,定义一些它完全没有接触过的东西对于ai还是太困难了,ai并不能通过我的监督,真正的理解marqdo代码即文档的设计思路,所以,尽管非常的遗憾,作者还是决定回归古法编程,还是手搓代码吧,尽管这意味着marqdo很难赶上ai的浪潮了。
|
||||
|
||||
marqdo的设计初衷很是简单,这就不是一门设计给程序员的语言,哪个程序员会用markdown表格来表示集合呢?不会的,这太过繁复了,但是ai可以,这就使得过去编程语言的范式变得不是那么重要了。
|
||||
|
||||
自然如果只是为了易读性,marqdo并没有完全的开发必要,重点在于对md的支持,作者必须承认谷歌提出的OKF规范,把markdown这种文件格式放到了一个极高的位置,这意味着,可执行的知识体系,如果能做到,为什么不试试?
|
||||
|
||||
此外,jupyter notebook笔记本体积太大不利于管理的问题也是存在的,作者就在想,markdown支持代码块的插入,这个代码如果可以直接执行并放回,这不就是最好的jupyter替代品吗?事实上,在main分支的marqdo已经实现了这个功能,但是还不够好,作者要把marqdo真正做成一门科学计算的顶级语言。
|
||||
|
||||
最后是数学公式的支持,公式库需要能够自动的渲染,高可读,还要能够自动的画图,自动的完成诸多内容,让可执行=正确,让ai支持数学推理不再困难。
|
||||
|
||||
最后,2026年8月11日,我预祝未来的自己,开发成功。
|
||||
|
||||
## 开发
|
||||
|
||||
### Marqdo上下文无关文法
|
||||
|
||||
file -> "---" metadata "---" content ;
|
||||
|
||||
metadata -> file_information |
|
||||
import_lib_name ;
|
||||
|
||||
content -> comment |
|
||||
code_body ;
|
||||
|
||||
comment -> comment_content ;
|
||||
|
||||
code_body -> class |
|
||||
function|
|
||||
code|
|
||||
$formula$|$$formula$$|\[formula\]|
|
||||
```code_block_type
|
||||
code_block
|
||||
```;
|
||||
|
||||
class -> # class_name code_body |
|
||||
# class_name => parent_class_name code_body ;
|
||||
|
||||
function -> function_header param_list body return_stmt ;
|
||||
|
||||
function_header -> ## identifier |
|
||||
### identifier |
|
||||
#### identifier ;
|
||||
|
||||
param_list -> + identifier ;
|
||||
|
||||
body -> statement |
|
||||
branch |
|
||||
loop ;
|
||||
|
||||
return_stmt -> ** statement ** ;
|
||||
|
||||
<!--the number of # stand for the level of function -->
|
||||
|
||||
code -> 1. branch |
|
||||
- loop |
|
||||
statement ;
|
||||
|
||||
<!--Ordered lists represent branch, unordered lists represent loop-->
|
||||
|
||||
branch -> statement ;
|
||||
|
||||
loop -> statement ;
|
||||
|
||||
statement -> > call |
|
||||
literal|
|
||||
`var_value_name`|
|
||||
list and dict|
|
||||
"str"|
|
||||
*statement_without_any_marker*;
|
||||
|
||||
<!--here we use markdown table to stand for list and dict-->
|
||||
|
||||
call -> function_name args;
|
||||
|
||||
literal -> literal_code as other code;
|
||||
|
||||
formula -> latex math code;
|
||||
|
||||
code_block_type -> code_block's code type;
|
||||
|
||||
code_block -> code of a code_block;
|
||||
@@ -1,59 +0,0 @@
|
||||
# Marqdo 开发文档
|
||||
|
||||
本目录存放各阶段设计、选型与路线图。
|
||||
|
||||
## 目录约定
|
||||
|
||||
| 路径 | 用途 |
|
||||
|------|------|
|
||||
| [`research/`](research/) | 外部标准与调研 |
|
||||
| [`design/`](design/) | 语言设计(语法映射等) |
|
||||
| [`adr/`](adr/) | 架构决策记录 |
|
||||
| [`roadmap/`](roadmap/) | 实现路线与里程碑 |
|
||||
|
||||
## 当前文档
|
||||
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.1 语法宪法** |
|
||||
| [design/objects.md](design/objects.md) | **`#` 对象 / `##` 函数与方法** |
|
||||
| [design/ai-skill.md](design/ai-skill.md) | **AI 接入 Skill**([`skills/marqdo/`](../skills/marqdo/)) |
|
||||
| [design/code-vs-comment.md](design/code-vs-comment.md) | 叙述 / 可执行 / 外联 |
|
||||
| [design/return-hr-and-code-surface.md](design/return-hr-and-code-surface.md) | 语句/返回/输出决议 |
|
||||
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单 |
|
||||
| [design/tech-stack.md](design/tech-stack.md) | 实现栈对比 |
|
||||
| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Rust 参考解释器;不用 Flex/Bison** |
|
||||
| [design/dependencies.md](design/dependencies.md) | 依赖详单(无 Flex/Bison) |
|
||||
| [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置函数** |
|
||||
| [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** |
|
||||
| [design/stdlib.md](design/stdlib.md) | **标准库:内置 + `lib/` + 错误约定** |
|
||||
| [design/stdlib-i18n.md](design/stdlib-i18n.md) | **标准库中英命名:靠库文件名区分,无 lang 开关** |
|
||||
| [design/stdlib-modules.md](design/stdlib-modules.md) | **L1:文件/系统/时间/JSON/网络/数学/外联/插件** |
|
||||
| [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** |
|
||||
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** |
|
||||
| [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) |
|
||||
| [design/ext-llm.md](design/ext-llm.md) | **官方扩展 `ext/llm`(OpenAI 兼容)** |
|
||||
| [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(智能体开发框架;布局已落地,编排/大模型组合路线已记录)** |
|
||||
| [design/ext-cli.md](design/ext-cli.md) | **`marqdo ext list/add/remove` 官方扩展安装器** |
|
||||
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
|
||||
| [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** |
|
||||
| [design/view.md](design/view.md) | **`marqdo view` / `view output` 黑白极简 + 静态文档** |
|
||||
| [design/user-site.md](design/user-site.md) | **用户站:`public/` → `gh-pages`** |
|
||||
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
|
||||
| [design/view-debug.md](design/view-debug.md) | **`marqdo debug` 独立调试页** |
|
||||
| [design/vscode-extension.md](design/vscode-extension.md) | **VS Code 扩展:分支 `vscode-extension`(main 不跟踪源码)** |
|
||||
| [design/vscode-extension-commit.md](design/vscode-extension-commit.md) | **扩展提交约定(禁止在 main 提交 `vscode-extension/`)** |
|
||||
| [design/bytecode.md](design/bytecode.md) | **M5 字节码 / 双后端** |
|
||||
| [design/pipeline-debug.md](design/pipeline-debug.md) | **流水线 `--dump-*` 可视调试** |
|
||||
| [dev-setup.md](dev-setup.md) | 开发环境配置(Rust M0) |
|
||||
| [roadmap/interpreter.md](roadmap/interpreter.md) | 正经解释器路线图 |
|
||||
| [roadmap/next-phase.md](roadmap/next-phase.md) | **下一阶段:input / 诊断 / 标准库 / view 调试** |
|
||||
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
## 写作原则
|
||||
|
||||
1. 先宪法与路线图,再实现。
|
||||
2. 金样例不过 = 未完成。
|
||||
3. 示例统一 `.mq.md`。
|
||||
@@ -1,53 +0,0 @@
|
||||
# ADR 0001:参考实现语言与前端工具
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted**(修订:实现语言 = Rust) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 决策者 | chaungming + 协作 |
|
||||
| 相关 | [dependencies.md](../design/dependencies.md) · [interpreter 路线图](../roadmap/interpreter.md) · [spike/REPORT.md](../../spike/REPORT.md) |
|
||||
|
||||
---
|
||||
|
||||
## 背景
|
||||
|
||||
语法宪法 v0.1 已定;Python Spike 已验证 GFM/行扫描风险。产品目标是正经**解释器**(`marqdo run index.mq.md`),实现语言需兼顾安全与可维护性。
|
||||
|
||||
---
|
||||
|
||||
## 决策
|
||||
|
||||
1. **参考解释器实现语言:Rust(stable)**
|
||||
- 内存安全、单静态二进制、适合长期演进到字节码 VM。
|
||||
- Python Spike **保留为算法原型/对照**,不是运行时依赖。
|
||||
|
||||
2. **词法 / 语法:不使用 Flex、Bison**
|
||||
- **主因是 Marqdo 的 Markdown 语法形态**,不是「因为选了 Rust」。换成 C++ 同样不建议用 Flex/Bison 做整语言前端。
|
||||
- 解释器需要词法·语法**阶段**;采用自研行分类 + GFM 库 + **手写递归下降** → AST。
|
||||
- 详见 [dependencies.md](../design/dependencies.md)。
|
||||
|
||||
3. **架构分期不变**
|
||||
- Phase I:树遍历解释器
|
||||
- Phase II:字节码 + VM
|
||||
- 见 [interpreter.md](../roadmap/interpreter.md)
|
||||
|
||||
4. **Markdown 库**
|
||||
- `pulldown-cmark` 或 `comrak` 二选一(建包前短 Spike 钉死)。
|
||||
|
||||
---
|
||||
|
||||
## 后果
|
||||
|
||||
- 正式代码以 Cargo 工程生长;不把 Flex/Bison/LLVM 列入 v1 依赖。
|
||||
- 金样例仍为 `tests/`;行为与宪法一致。
|
||||
- 此前「Python 作参考实现」的倾向由本修订取代;Spike 结论(行扫描等)仍然有效并迁入 Rust。
|
||||
|
||||
---
|
||||
|
||||
## 否决
|
||||
|
||||
| 方案 | 原因 |
|
||||
|------|------|
|
||||
| Flex + Bison 作主前端 | 与 Markup-as-Syntax / Rust 栈错配;解释器非必需 |
|
||||
| v1 上 LLVM | 产品是解释执行文档,不是机器后端 |
|
||||
| 仅 Python 正则玩具 | 达不到安全与长期目标 |
|
||||
@@ -1,29 +0,0 @@
|
||||
# Marqdo AI Skill
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已提供 |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 路径 | [`skills/marqdo/`](../../skills/marqdo/)(权威);Cursor 镜像 [`.cursor/skills/marqdo/`](../../.cursor/skills/marqdo/) |
|
||||
|
||||
---
|
||||
|
||||
## 目的
|
||||
|
||||
让接入方(Cursor Agent、其它支持 Agent Skills 的模型宿主)在**加载本 skill 后**即可按 v0.1 语法正确编写 / 修改 `.mq.md`,而不把 Markdown 习惯或 Python 控制流误套到 Marqdo。
|
||||
|
||||
## 内容
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `SKILL.md` | 必读:硬规则、标记表、工作流、反模式 |
|
||||
| `reference.md` | 按需:CLI、stdlib 索引、边界 |
|
||||
| `examples.md` | 按需:可复制样例 |
|
||||
|
||||
## 使用
|
||||
|
||||
- **本仓库 Cursor**:项目 skill 已在 `.cursor/skills/marqdo/`;描述含 `.mq.md` / Marqdo 触发词,可自动选用。
|
||||
- **其它 AI**:将 `skills/marqdo/` 整目录作为 skill 包导入,或把 `SKILL.md` 贴进系统/项目说明并允许模型按需打开 `reference.md` / `examples.md`。
|
||||
- **校验**:生成后执行 `marqdo run <file>.mq.md`,按 `path:line:col` 诊断迭代。
|
||||
|
||||
语法真相仍以 [markdown-mapping.md](markdown-mapping.md) 与 [keywords.md](keywords.md) 为准;skill 是面向模型的压缩操作手册。
|
||||
@@ -1,89 +0,0 @@
|
||||
# Marqdo 字节码(M5 原型)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 进行中(原型) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [roadmap/interpreter.md](../roadmap/interpreter.md) · Phase I 树遍历 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在保留树遍历后端(`--backend tree`,默认)的同时,提供栈式字节码 VM(`--backend bytecode`),使**核心金样例** stdout 与树遍历 bit 一致。
|
||||
|
||||
```
|
||||
.mq.md → load/parse → Module AST
|
||||
├─ tree-walk
|
||||
└─ compile → Chunk → VM
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. 指令集(草案 / 原型已实现子集)
|
||||
|
||||
| Op | 栈效应 | 说明 |
|
||||
|----|--------|------|
|
||||
| `Constant i` | → v | 常量池 |
|
||||
| `True` / `False` / `None` | → b | |
|
||||
| `Pop` | v → | |
|
||||
| `GetLocal i` / `SetLocal i` | | 当前帧槽 |
|
||||
| `GetGlobal i` / `SetGlobal i` | | 名字在常量池(文本) |
|
||||
| `Add` `Sub` `Mul` `Div` `Negate` `Not` | | |
|
||||
| `Equal` `NotEqual` `Greater` `GreaterEqual` `Less` `LessEqual` | | |
|
||||
| `Jump a` / `JumpIfFalse a` / `JumpBack a` | | 相对/绝对跳转(原型用绝对 u16) |
|
||||
| `Print` | v → | 弹出并写 stdout |
|
||||
| `BuildList n` | v… → list | |
|
||||
| `GetIndex` | list, i → v | foreach 用 |
|
||||
| `Call f argc` | args… → ret | 用户函数(按形参序压栈) |
|
||||
| `Return` | | 返回 / 结束帧 |
|
||||
| `Interp n` | parts… → text | n 个交错 Lit/Var 标记后的拼接(简化:编译期展开为常量+拼接) |
|
||||
|
||||
原型实现以 `src/bytecode/` 为准;未列出的 Op 不存在于当前构建。
|
||||
|
||||
---
|
||||
|
||||
## 3. 编译约定
|
||||
|
||||
- 每个 Marqdo `Function` → 一个 `FnChunk`(含 `name`、`params`、`code`、`constants`)。
|
||||
- 模块级 `Program`:函数表 + 入口名(`main` 或唯一无参 level-1)。
|
||||
- 局部变量:函数体内首次赋值/形参分配槽位。
|
||||
- 嵌套 `##`:编入同一 `Program`,按名 `Call`;查找规则对齐树遍历(子树优先,再顶层)。
|
||||
- `and` / `or`:短接跳转。
|
||||
- 分支 / while:`JumpIfFalse` + `Jump` / `JumpBack`。
|
||||
- foreach:`BuildList` 或已有 list 全局/局部 → 索引循环。
|
||||
|
||||
---
|
||||
|
||||
## 4. 覆盖表(M5 原型)
|
||||
|
||||
| 金样例 | tree | bytecode |
|
||||
|--------|------|----------|
|
||||
| `structure/hello` | ✅ | ✅ |
|
||||
| `structure/branch` | ✅ | ✅ |
|
||||
| `structure/loop` | ✅ | ✅ |
|
||||
| `structure/collection` | ✅ | ✅ |
|
||||
| `keywords/print` | ✅ | ✅ |
|
||||
| `keywords/bool-logic` | ✅ | ✅ |
|
||||
| `structure/nested-call` | ✅ | ✅ |
|
||||
| `structure/positional-call` | ✅ | ✅ |
|
||||
| `structure/import/*` | ✅ | ✅(load 合并 AST 后编译) |
|
||||
| `tests/errors/*` | ✅(非零退出) | 同 tree 语义(编译期/运行期诊断) |
|
||||
|
||||
核心金样例双后端已对齐;后续可扩展 Op、优化与更好的调试信息。
|
||||
|
||||
---
|
||||
|
||||
## 5. CLI
|
||||
|
||||
```bash
|
||||
marqdo run FILE --backend tree # 默认
|
||||
marqdo run FILE --backend bytecode
|
||||
marqdo run FILE --dump-bytecode # 反汇编后仍可按 backend 执行
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 6. 非目标(本原型)
|
||||
|
||||
优化、寄存器分配、GC、与树遍历指令级调试对齐、独立 sema IR。
|
||||
@@ -1,53 +0,0 @@
|
||||
# 调用实参:具名与位置
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.1 增补) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
`>` 调用同时支持:
|
||||
|
||||
| 形式 | 示例 | 说明 |
|
||||
|------|------|------|
|
||||
| **具名**(保留) | `> 问候 谁=Marqdo` | `名=值`;值可含空格(至下一 `名=`) |
|
||||
| **位置**(新增) | `> 问候 Marqdo` | 按形参声明顺序绑定 |
|
||||
|
||||
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。具名不可绑定同一形参两次;位置实参不得出现在「已出现具名实参」之后(对齐常见「位置在前、关键字在后」习惯)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 文法(调用尾部)
|
||||
|
||||
```
|
||||
call_tail ::= callee arg*
|
||||
arg ::= named | positional
|
||||
named ::= ident '=' value
|
||||
positional ::= value_token
|
||||
```
|
||||
|
||||
- `value`(具名右侧):可含空格与 `` `var` `` 插值,直到下一个 `ident=` 边界。
|
||||
- `value_token`(位置):空白分隔的一个词法单元——数字、`` `名` ``、标识/文本词;**不含空格**。多词字符串请用具名,例如 `> print text=Hello World!`。
|
||||
- 内置 `print` / `打印` 形参:`text` ≡ `内容`。
|
||||
- `input` / `输入`:`prompt` ≡ `提示`。
|
||||
- `len` / `长度`、`str` / `文本`、`int` / `整数`:`value` ≡ `值`。
|
||||
- 完整中英双名见 [keywords-i18n.md](keywords-i18n.md)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 绑定算法
|
||||
|
||||
1. 收集具名 → 映射;冲突则报错。
|
||||
2. 按函数形参表顺序:若具名已提供则用之,否则取下一个位置实参。
|
||||
3. 位置实参有余、或必填形参仍缺 → 报错(内置 `input` 的 `prompt` 可缺省)。
|
||||
4. 用户函数:额外具名键仍写入调用环境(便于扩展);位置实参不可超过形参数目。
|
||||
|
||||
---
|
||||
|
||||
## 4. 金样例
|
||||
|
||||
见 `tests/structure/positional-call.mq.md` 与更新后的 `tests/structure/import/`。
|
||||
@@ -1,128 +0,0 @@
|
||||
# OKF 兼容清单:`marqdo catalog`
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0 命令落地) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 取代 | [generated-yaml-manifest.md](generated-yaml-manifest.md) 中「待决:sync/doc 命令」的命令名部分 |
|
||||
| 相关 | [generated-yaml-manifest.md](generated-yaml-manifest.md) · [view.md](view.md) · [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 决策(重申)
|
||||
|
||||
YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。详见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
|
||||
|
||||
本文件规定 **CLI 与 v0 落盘格式**。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI
|
||||
|
||||
```bash
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
# 别名(与早期草案一致)
|
||||
marqdo sync [PATH] -o OUT_DIR
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
|
||||
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件) |
|
||||
|
||||
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 生成物(v0)
|
||||
|
||||
```
|
||||
OUT_DIR/
|
||||
catalog.yaml # 机器向总清单(OKF 风格字段)
|
||||
index.md # 人/Agent 可读总览(含 YAML frontmatter)
|
||||
modules/
|
||||
<stem>.md # 每个 .mq.md 一个概念页(frontmatter + 摘要)
|
||||
```
|
||||
|
||||
路径中的目录层级拍扁为文件名时用 `__` 连接,例如:
|
||||
|
||||
`structure/import/main.mq.md` → `modules/structure__import__main.md`
|
||||
|
||||
### 3.1 `catalog.yaml`(示意)
|
||||
|
||||
```yaml
|
||||
# GENERATED by marqdo — do not edit by hand
|
||||
type: Marqdo Catalog
|
||||
title: marqdo-project
|
||||
generated:
|
||||
by: marqdo/0.0.1
|
||||
# at: 可选 ISO8601;CI 比对时可忽略
|
||||
modules:
|
||||
- id: structure/hello
|
||||
resource: structure/hello.mq.md
|
||||
title: Hello World # 来自源 frontmatter title,缺省用文件名
|
||||
imports: []
|
||||
exports:
|
||||
- name: Hello World
|
||||
kind: fn
|
||||
- id: structure/import/main
|
||||
resource: structure/import/main.mq.md
|
||||
imports:
|
||||
- utils.mq.md
|
||||
exports:
|
||||
- name: main
|
||||
kind: fn
|
||||
```
|
||||
|
||||
字段约定(v0 最小集):
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `type` | 固定 `Marqdo Catalog`(OKF:未知 type 可降级) |
|
||||
| `modules[].resource` | 相对 `PATH` 的源路径 |
|
||||
| `modules[].imports` | 源 frontmatter 中的 `> *.mq.md` |
|
||||
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`);嵌套 `##` 列入 `children`(可选,v0 可扁平只列顶层) |
|
||||
| `generated.by` | `marqdo/<crate version>` |
|
||||
|
||||
不在 v0:版本锁定哈希、跨仓 URL、完整符号类型。
|
||||
|
||||
### 3.2 模块概念页 frontmatter
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: Marqdo Module
|
||||
title: …
|
||||
resource: structure/hello.mq.md
|
||||
depends: [] # imports 列表
|
||||
exports: [Hello World]
|
||||
generated:
|
||||
by: marqdo/0.0.1
|
||||
---
|
||||
```
|
||||
|
||||
正文含「请勿手改」提示、依赖列表、导出列表;可链到同包其它模块页。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 `view output` 的分工
|
||||
|
||||
| 命令 | 产物 | 受众 |
|
||||
|------|------|------|
|
||||
| `marqdo view output` | 静态 HTML(结构 + 运行结果) | 人类读程序文档站 |
|
||||
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引 | 工具 / Agent / 依赖总览 |
|
||||
|
||||
二者都从同一源树生成,互不替代。发布用户文档时可同时:
|
||||
|
||||
```bash
|
||||
marqdo view output public -o public
|
||||
marqdo catalog tests -o .marqdo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml` 与 `modules/`。
|
||||
2. `catalog.yaml` 含 `structure/hello` 与 import 模块的 `imports: [utils.mq.md]`。
|
||||
3. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
|
||||
4. `marqdo sync` 与 `catalog` 行为一致。
|
||||
@@ -1,38 +0,0 @@
|
||||
# 可执行面与叙述面
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 与 mapping v0.1 / keywords 对齐(成段注释) |
|
||||
| 日期 | 2026-08-04 |
|
||||
|
||||
---
|
||||
|
||||
## 三层
|
||||
|
||||
| 层 | 形态 | 角色 |
|
||||
|----|------|------|
|
||||
| **叙述面** | 成段注释(空行分段) | 注释;段内任意标记无语义 |
|
||||
| **Marqdo 可执行面** | 结构标记 + `*语句*` + `**返回**` | 本语言程序 |
|
||||
| **外联面** | ` ```lang ` | 其它语言(FFI) |
|
||||
|
||||
输出属于可执行面里的**函数调用**(`> print …`),见 [keywords.md](keywords.md)。
|
||||
|
||||
### 成段注释
|
||||
|
||||
- 以**空行**划分段落。
|
||||
- 段首行:首字符非标记 → 注释。
|
||||
- 段内续行:一律注释(即使以 `` ` `` / `-` / `**` 等开头)。
|
||||
- **例外**:整行仅为 `**expr**`(或 `****`)→ Marqdo **返回**;`**强调**` 后还有文字 → 仍是叙述注释。
|
||||
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
|
||||
|
||||
---
|
||||
|
||||
## 语句 vs 返回 vs 输出
|
||||
|
||||
| 标记/形式 | 角色 | 是否架构级 |
|
||||
|-----------|------|------------|
|
||||
| `*…*` | 程序语句 | 是 |
|
||||
| `**…**` | 返回值 | 是 |
|
||||
| `****` / 空粗体 | 空返回 + 结束函数体 | 是 |
|
||||
| `> print …` | 打印副作用 | 否(内置函数) |
|
||||
| 函数体 `---` / `***` | 结束函数体 | 是(边界) |
|
||||
@@ -1,175 +0,0 @@
|
||||
# Marqdo 实现依赖说明(Rust 参考解释器)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [ADR 0001](../adr/0001-implementation-language.md) · [interpreter 路线图](../roadmap/interpreter.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 要不要 Flex / Bison?
|
||||
|
||||
### 结论:**不需要。** 主因不是「用了 Rust」,而是 **Marqdo 的语法形态 + 解释器并不绑定生成器。**
|
||||
|
||||
把两件事分开:
|
||||
|
||||
| 问题 | 答案 |
|
||||
|------|------|
|
||||
| 因为 Rust 才不用 Flex/Bison? | **否。** Flex/Bison 生成的是 C(也可接 C++)。若实现改成 **C++**,**仍然不建议**用它们做 Marqdo 主前端。 |
|
||||
| 因为是解释器才不用? | **部分相关,但不是全部。** 解释器**需要**词法/语法阶段,但**不规定**必须用 Flex/Bison;手写递归下降是主流。即便将来做「编译到字节码/原生」,Marqdo 也因 Markdown 外壳而不适合整语言 Bison 化。 |
|
||||
| 真正主因 | **Markup-as-Syntax**:源是 GFM 文档结构(标题/列表/强调/表格/行分类),不是 Cminusf 那种纯字符流文法。 |
|
||||
|
||||
| 工具 | 典型用途 | Marqdo 为何不用(与宿主语言无关) |
|
||||
|------|----------|----------------------------------|
|
||||
| **Flex** | 正则 → C 词法分析器 | 「词法」是 **行分类 + Markdown 标记**,不是经典 `id\|num\|op` 字符流 |
|
||||
| **Bison** | Yacc 文法 → C LR 分析器 | 整体语法绑在 **GFM 块结构**上,硬写成单一 Bison 文法别扭且难与预览器对齐 |
|
||||
|
||||
[USTC 编译课 Lab1](https://ustc-compiler-2025.github.io/homepage/) 用 Flex/Bison,是因为对象语言是 **C 式源码的编译器**;换 C++ 写那个编译器也合理。
|
||||
Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这一判断。
|
||||
|
||||
**解释型语言同样需要词法与语法分析**,要的是阶段,不是这两个具体程序。
|
||||
|
||||
---
|
||||
|
||||
## 2. Marqdo 前端应怎样做(替代 Flex/Bison)
|
||||
|
||||
拆成三层,比「一个大 lexer/parser」更贴合宪法:
|
||||
|
||||
```
|
||||
.mq.md 文本
|
||||
│
|
||||
├─① 行分类(自研) 无标记 → 注释;有标记 → 代码行
|
||||
├─② GFM 块/行内(库) 标题、表、强调、列表结构
|
||||
├─③ 行扫描补强(自研) 保留 '-' / '+';frontmatter `> file.mq.md`
|
||||
└─④ Marqdo 语法(自研) 递归下降:Module/Fun/Stmt/Expr → AST
|
||||
└─ 表达式子语言 可手写,或仅对 Expr 用 pest/nom
|
||||
```
|
||||
|
||||
| 阶段 | 做法 | 对应编译学 |
|
||||
|------|------|------------|
|
||||
| ①③ | Rust 手写扫描 | 词法 / 扫描器 |
|
||||
| ② | `pulldown-cmark` 或 `comrak` | 复用 GFM,避免自研表格/强调 |
|
||||
| ④ | **手写递归下降**(推荐主路径) | 语法分析 |
|
||||
| Expr(可选) | `pest`(PEG)或 `nom`(组合子) | 仅迷你表达式,不是整门语言 |
|
||||
|
||||
**不推荐**整门语言上 LALRPOP / rusty_lr / Bison 等价物作为 v1 主前端:Markdown 外壳 + 行语义会让文法极度别扭。若将来有「纯文本 Marqdo 方言」,再另议生成器。
|
||||
|
||||
---
|
||||
|
||||
## 3. 详细依赖清单(Rust)
|
||||
|
||||
### 3.1 工具链(开发机)
|
||||
|
||||
| 依赖 | 用途 | 安装 |
|
||||
|------|------|------|
|
||||
| **Rust**(stable,建议 ≥ 1.75) | 编译实现 | [rustup](https://rustup.rs/):`rustup default stable` |
|
||||
| **Cargo** | 包与构建 | 随 rustup |
|
||||
| **rustfmt / clippy** | 格式与静态检查 | `rustup component add rustfmt clippy` |
|
||||
| **Git** | 版本管理 | 已有 |
|
||||
|
||||
**不要安装:** Flex、Bison、LLVM(v1 解释器不需要)。
|
||||
(日后若做原生后端再开 ADR;与当前解释器无关。)
|
||||
|
||||
### 3.2 Cargo crate(建议写入根 `Cargo.toml` / workspace)
|
||||
|
||||
#### 必选(Phase I 树遍历解释器)
|
||||
|
||||
| Crate | 角色 | 说明 |
|
||||
|-------|------|------|
|
||||
| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 |
|
||||
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`> x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
|
||||
|
||||
#### 强烈建议
|
||||
|
||||
| Crate | 角色 |
|
||||
|-------|------|
|
||||
| **camino** 或标准 `PathBuf` | 路径 |
|
||||
| **indexmap** | 保序 map(模块导出等) |
|
||||
|
||||
#### 测试
|
||||
|
||||
| Crate | 角色 |
|
||||
|-------|------|
|
||||
| **rust 自带** `#[test]` | 单元测试 |
|
||||
| **insta** 或手写金文件 | tests 期望 stdout 快照(可选) |
|
||||
| **assert_cmd** / **predicates** | CLI 集成测试(可选) |
|
||||
|
||||
#### Phase II(字节码 VM,后加)
|
||||
|
||||
无强制新依赖;VM 以自研为主。可选:
|
||||
|
||||
| Crate | 角色 |
|
||||
|-------|------|
|
||||
| **num_enum** 等 | opcode 枚举(可选) |
|
||||
|
||||
#### 明确不引入(v1)
|
||||
|
||||
| 东西 | 原因 |
|
||||
|------|------|
|
||||
| flex / bison / lemon | 见 §1 |
|
||||
| lalrpop / rusty_lr 作**整语言**前端 | 与 MD 外壳冲突;递归下降更合适 |
|
||||
| llvm-sys / inkwell | 非解释器 v1 |
|
||||
| 完整 Python 运行时嵌入 | 参考实现已定为 Rust,避免双运行时 |
|
||||
|
||||
### 3.3 表达式子语言(可选增强)
|
||||
|
||||
若手写 Expr 递归下降过痛,**仅**对 `` `a` + 1 == `b` `` 这类表达式引入其一:
|
||||
|
||||
| 选项 | 类型 | 何时用 |
|
||||
|------|------|--------|
|
||||
| **手写递归下降** | 无新依赖 | 默认;与全书一致、错误信息最好控 |
|
||||
| **pest** | PEG 生成器 | 文法清晰、想要 `.pest` 文件时 |
|
||||
| **nom** | 解析组合子 | 要零拷贝/细控时 |
|
||||
|
||||
整文件 `.mq.md` **不要**整份丢给 pest/nom。
|
||||
|
||||
---
|
||||
|
||||
## 4. 仓库布局(与依赖对应)
|
||||
|
||||
```
|
||||
Cargo.toml # workspace 或单包
|
||||
crates/marqdo/ # 或根包 marqdo
|
||||
src/
|
||||
main.rs / lib.rs
|
||||
lex/ # 行分类、Token(自研,无 flex)
|
||||
parse/ # 递归下降(自研,无 bison)
|
||||
ast/
|
||||
sema/
|
||||
interp/ # Phase I
|
||||
bytecode/ # Phase II
|
||||
runtime/
|
||||
tests/ # gold.rs + structure|keywords|errors
|
||||
public/ # 用户可执行文档
|
||||
spike/ # Python 风险探测存档(可保留,非运行时依赖)
|
||||
```
|
||||
|
||||
开发命令示例:
|
||||
|
||||
```bash
|
||||
cargo build
|
||||
cargo test
|
||||
cargo run -- run tests/structure/nested-call.mq.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 与 Python Spike 的关系
|
||||
|
||||
| | Python `spike/` | Rust 参考实现 |
|
||||
|--|-----------------|---------------|
|
||||
| 角色 | 已验证 S1–S5 风险 | **正式**词法/语法/语义/解释器 |
|
||||
| 是否运行时依赖 | 否 | 是 |
|
||||
| 算法可迁移 | 行扫描、`split_front_matter`、导入正则 | 用 Rust 重写同算法 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 一句话对照
|
||||
|
||||
- **需要:** 词法(行分类+标记)、语法(递归下降→AST)、语义、解释器/日后 VM。
|
||||
- **不需要:** Flex、Bison、LLVM(v1)。
|
||||
- **外部库只需:** Rust 工具链 + GFM crate(pulldown-cmark/comrak)+ CLI/错误/测试若干;表达式可选 pest/nom。
|
||||
@@ -1,68 +0,0 @@
|
||||
# 示例与测试布局
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 原则 | **夹具即金样例**:`tests/{structure,keywords,errors}/**/*.mq.md` 由 `cargo test` / CI 跑通;`marqdo view tests` 也可浏览 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目录
|
||||
|
||||
只保留 **`tests/`**,用子目录区分类别(不再另设 `examples/`):
|
||||
|
||||
```
|
||||
tests/
|
||||
README.md
|
||||
gold.rs # 集成测试入口
|
||||
structure/ # 代码基础结构(Markup 架构)
|
||||
hello.mq.md
|
||||
nested-call.mq.md
|
||||
positional-call.mq.md
|
||||
branch.mq.md
|
||||
loop.mq.md
|
||||
collection.mq.md
|
||||
import/
|
||||
main.mq.md
|
||||
utils.mq.md
|
||||
keywords/ # 关键字与内置名
|
||||
print.mq.md
|
||||
bool-logic.mq.md
|
||||
errors/ # 期望失败(诊断文案稳定后再加金样例)
|
||||
…
|
||||
```
|
||||
|
||||
面向访客的可执行介绍在 [`public/`](../../public/)(无 `errors/`),见 [user-site.md](user-site.md)。
|
||||
开发设计文稿在 [`doc/`](../)(单数)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分类职责
|
||||
|
||||
| 类别 | 测什么 | 不测什么 |
|
||||
|------|--------|----------|
|
||||
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、位置/具名实参 | 关键字边角 |
|
||||
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
|
||||
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
|
||||
|
||||
未单独建夹、但应覆盖的其它测试(`src/**` 单测或日后 `tests/runtime/`):
|
||||
|
||||
- **流水线调试**:`--dump-lines` / `--dump-ast` / `--trace-eval`
|
||||
- **CLI**:默认 `index.mq.md`、退出码
|
||||
- **view**:目录扫描、单文件页、执行区(见 [view.md](view.md))
|
||||
- **模块图**:循环导入拒绝
|
||||
|
||||
---
|
||||
|
||||
## 3. 金样例约定
|
||||
|
||||
每个可执行 `.mq.md` 在 `tests/gold.rs` 登记期望 stdout。
|
||||
`errors/` 内文件登记期望 stderr 子串与非零退出码。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 `view` / `public` 的关系
|
||||
|
||||
- `marqdo view tests`:开发者浏览金样例(含 errors)。
|
||||
- `marqdo view public`:用户文档站源;**不要**把 `tests/errors` 编进 `public/`。
|
||||
@@ -1,85 +0,0 @@
|
||||
# Native plugin ABI (v1)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted |
|
||||
| Date | 2026-08-06 |
|
||||
| Header | [`include/marqdo_abi.h`](../../include/marqdo_abi.h) |
|
||||
| Related | [ext-agent.md](ext-agent.md) · [stdlib-modules.md](stdlib-modules.md) |
|
||||
|
||||
## Goals
|
||||
|
||||
- Optional **native** extensions as shared libraries (`.dll` / `.so` / `.dylib`).
|
||||
- **Not** linked into the `marqdo` binary; load at runtime.
|
||||
- Stable **C** ABI only (no cross-compiler Rust ABI for plugins).
|
||||
- Official / local paths only — **no** third-party package registry.
|
||||
|
||||
## Contract
|
||||
|
||||
`MARQDO_ABI_VERSION = 1`.
|
||||
|
||||
Every plugin exports:
|
||||
|
||||
| Symbol | Role |
|
||||
|--------|------|
|
||||
| `marqdo_plugin_abi_version` | Must equal host’s supported version |
|
||||
| `marqdo_plugin_init` | Register functions via `MarqdoHostApi` |
|
||||
| `marqdo_plugin_shutdown` | Teardown |
|
||||
|
||||
Host provides `register_fn(name, params_csv, fn)`, `alloc`, `free`.
|
||||
|
||||
### Wire format
|
||||
|
||||
Arguments and results are **UTF-8 JSON**:
|
||||
|
||||
- Args: JSON object keyed by parameter names (from `params` CSV at registration).
|
||||
- Result: any JSON value mappable to Marqdo `Value` (same rules as `lib/json`).
|
||||
|
||||
Plugin fn returns `0` + `*out_json` on success; non-zero + optional `*err_msg` on failure. Host frees both strings with the host `free`.
|
||||
|
||||
## Marqdo surface (`lib/plugin` / `lib/插件`)
|
||||
|
||||
| English | Chinese | Host |
|
||||
|---------|---------|------|
|
||||
| `## load` (`path`) | `## 加载` (`路径`) | `host_plugin_load` |
|
||||
| `## unload` | `## 卸载` | `host_plugin_unload` |
|
||||
| `## list` | `## 列出` | `host_plugin_list` |
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/plugin.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load path=demo.dll
|
||||
|
||||
*`sum` = > demo_add a=1 b=2 *
|
||||
> print text=`sum`
|
||||
```
|
||||
|
||||
After `load`, registered names are callable like other functions (plugin registry lookup after fixed host fns, before user `#`/`##` defs).
|
||||
|
||||
**Path sandbox:** `path` resolves under the program’s cwd / `fs_root` (same as `lib/fs`). Absolute paths outside the root are rejected. Prefer a same-directory filename, or pass a path via a variable / env (see gold tests).
|
||||
|
||||
## Demo
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_demo
|
||||
# Windows: target/debug/demo.dll
|
||||
# Linux: target/debug/libdemo.so
|
||||
# macOS: target/debug/libdemo.dylib
|
||||
```
|
||||
|
||||
Registers `demo_add(a,b)`, `demo_echo(text)`. Gold: [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md).
|
||||
|
||||
Official agent layout plugin: [`plugins/agent`](../../plugins/agent) — see [ext-agent.md](ext-agent.md).
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Embedding plugins in the release exe by default
|
||||
- Callbacks from plugin into arbitrary Marqdo evaluation
|
||||
- OS sandbox / seccomp
|
||||
- **Third-party** plugin / package registry
|
||||
|
||||
Official install of known extensions (`marqdo ext add …`) is **planned** — see [ext-cli.md](ext-cli.md). That is not a public marketplace.
|
||||
@@ -1,137 +0,0 @@
|
||||
# Official agent development framework (`ext/ai/agent`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted · **thin agent loop locked** |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [objects.md](objects.md) |
|
||||
|
||||
## What we are building
|
||||
|
||||
An **agent-development framework** — smallest runtime surface for agents on Marqdo.
|
||||
|
||||
**Not** task-dispatch, **not** bundled domain tools, **not** layout/match/ticket helpers in official ext.
|
||||
|
||||
| In scope | Out of scope (your runbook / your code) |
|
||||
|----------|-------------------------------------------|
|
||||
| `# 智能体` ctor | `## 技能匹配` · `## 分配任务` · `## 创建工单` … |
|
||||
| `## 执行` | Anything task-specific in `ext/` |
|
||||
| `## 清空历史` | |
|
||||
| Auto context: source, position, history, Marqdo skill | |
|
||||
|
||||
## Repo layout (`ext/`)
|
||||
|
||||
Official extensions for LLM + agent live under **`ext/ai/`** only. No flat `.mq.md` at `ext/` root; future domains get their own subdir.
|
||||
|
||||
```text
|
||||
ext/
|
||||
ai/
|
||||
llm.mq.md
|
||||
大模型.mq.md
|
||||
agent.mq.md
|
||||
智能体.mq.md
|
||||
```
|
||||
|
||||
Import: `> ext/ai/智能体.mq.md` · `> ext/ai/llm.mq.md`
|
||||
|
||||
## Layering
|
||||
|
||||
| Layer | Role |
|
||||
|-------|------|
|
||||
| **Your runbook** | Tables, loops, **your** tools & logic |
|
||||
| **`ext/ai/llm`** | Model I/O |
|
||||
| **`ext/ai/agent`** | Framework: ctor + `执行` + `清空历史` |
|
||||
| **`lib/*`** | Generic I/O |
|
||||
|
||||
```text
|
||||
> ext/ai/智能体.mq.md
|
||||
▼
|
||||
# 智能体 (大模型, 工具, 用户提示信息?)
|
||||
## 执行
|
||||
## 清空历史
|
||||
```
|
||||
|
||||
`工具` = caller-supplied **function catalog** (table of `##` names); framework resolves names via `call_fn` / `调用` and runs the matching zero-arg function in the runbook module.
|
||||
|
||||
Install: [`ext-cli.md`](ext-cli.md) — `marqdo ext add agent` / `add llm`.
|
||||
|
||||
### Tools (v1)
|
||||
|
||||
Tools are **not** framework builtins — you define `## 函数名` in your runbook and list names in a table:
|
||||
|
||||
```markdown
|
||||
`工具表` =
|
||||
| 工具 |
|
||||
|------|
|
||||
| 获取时间 |
|
||||
| 分配任务 |
|
||||
```
|
||||
|
||||
- Single-column table → list of function **names** (text).
|
||||
- Multi-column table → each row is a map; name from column `工具` / `tools` / `name`.
|
||||
- Marqdo has no first-class function values in tables yet; the name must match a `##` in the same module (or imports). `执行` calls it with `call_fn` after the model replies `TOOL:<name>`.
|
||||
- Do **not** use `parse text=["fn"]` for the tools list — unquoted identifiers inside `parse` are evaluated as calls.
|
||||
|
||||
---
|
||||
|
||||
## Public API (v1)
|
||||
|
||||
| | Role |
|
||||
|--|------|
|
||||
| `# 智能体` / `# agent` | **大模型**, **工具**, optional **用户提示信息** |
|
||||
| `## 执行` / `## run` | **额外信息**; context + LLM + history append |
|
||||
| `## 清空历史` / `## clear_history` | Wipe history on this handle |
|
||||
|
||||
Module-level `##` helpers (e.g. context assembly) are internal — not public contract.
|
||||
|
||||
### Auto context (each `执行`)
|
||||
|
||||
- `.mq.md` source
|
||||
- Call-site / position
|
||||
- Conversation history on this handle
|
||||
- Marqdo skill (`skills/marqdo/`)
|
||||
|
||||
### History (v1)
|
||||
|
||||
- Host-backed id per handle
|
||||
- Append after each successful `执行`
|
||||
- `清空历史` ships with `执行`
|
||||
|
||||
---
|
||||
|
||||
## Example runbook (application — not framework)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/ai/智能体.mq.md
|
||||
> ext/ai/大模型.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`模型` = > 大模型 *
|
||||
*`工具名` = | 技能匹配 | 分配任务 | … |
|
||||
*`助手` = > 智能体 大模型=`模型` 工具=`工具名` 用户提示信息=… *
|
||||
|
||||
- [任务](任务队列)
|
||||
> `助手`.清空历史
|
||||
*`结果` = > `助手`.执行 额外信息=`任务` *
|
||||
```
|
||||
|
||||
Domain `##` functions live in **this file** or your lib — never in `ext/ai/`.
|
||||
|
||||
---
|
||||
|
||||
## Shipped / roadmap
|
||||
|
||||
| Item | Status |
|
||||
|------|--------|
|
||||
| `ext/ai/` + framework + context injection | in progress |
|
||||
| Live `执行` test (`tests/ext/agent-run-live.mq.md` + `.env`) | shipped |
|
||||
| Tool-call loop in `执行` (`TOOL:<name>` → `call_fn`) | shipped |
|
||||
|
||||
### Non-goals
|
||||
|
||||
- Domain tools in official ext
|
||||
- Flat `ext/*.mq.md` at repo root
|
||||
- Second chat stack beside llm
|
||||
@@ -1,61 +0,0 @@
|
||||
# Official extension installer (`marqdo ext`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted (v0.1)** |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
## Commands
|
||||
|
||||
```text
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext remove llm
|
||||
marqdo ext remove agent
|
||||
```
|
||||
|
||||
## Install root
|
||||
|
||||
1. `MARQDO_EXT` if set
|
||||
2. Else `~/.marqdo/ext`
|
||||
|
||||
Imports use paths like `> ext/ai/llm.mq.md` (see [`load.rs`](../../src/load.rs)).
|
||||
|
||||
## Source for `add`
|
||||
|
||||
1. `MARQDO_EXT_SOURCE` — directory containing `ai/llm.mq.md` …
|
||||
2. Else repo `./ext` near cwd / binary
|
||||
|
||||
## Layout (`ext/`)
|
||||
|
||||
Official extensions live under **`ext/ai/`** (LLM + agent framework only). Do not add flat `.mq.md` files at `ext/` root — keeps the tree from accumulating unrelated modules.
|
||||
|
||||
```text
|
||||
ext/
|
||||
ai/
|
||||
llm.mq.md
|
||||
大模型.mq.md
|
||||
agent.mq.md
|
||||
智能体.mq.md
|
||||
```
|
||||
|
||||
Future optional ext domains get their own subdirs (e.g. `ext/foo/`), not mixed into `ai/`.
|
||||
|
||||
## Catalog
|
||||
|
||||
| Id | Installs under `MARQDO_EXT` |
|
||||
|----|-----------------------------|
|
||||
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md` |
|
||||
|
||||
## Tests
|
||||
|
||||
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` (needs `tests/ext/.env`).
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Third-party registry
|
||||
- Merging into `lib/`
|
||||
- Bundling domain/task helpers in official ext
|
||||
@@ -1,70 +0,0 @@
|
||||
# Official extensions (`ext/`) — LLM
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted (v0.1.x) |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) |
|
||||
|
||||
## Scope
|
||||
|
||||
`ext/ai/` holds **official LLM + agent** extensions. Import paths:
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/ai/llm.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
Resolution: `MARQDO_EXT/ai/…`, repo `ext/ai/…`, cwd `ext/ai/…` (see [ext-cli.md](ext-cli.md)).
|
||||
|
||||
Other official ext: [ext-agent.md](ext-agent.md) (**agent development framework** — layout shipped; orchestration + LLM composition on roadmap). Installer CLI (planned): [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md).
|
||||
|
||||
**Note:** Prefer `marqdo ext add llm`. Import `> ext/ai/llm.mq.md` from repo or install root.
|
||||
|
||||
## Platform prerequisites
|
||||
|
||||
| Capability | Surface |
|
||||
|------------|---------|
|
||||
| HTTPS + headers | `lib/net` → `http_post` / `headers=` map |
|
||||
| Dotenv | `## load_env` in ext (or `load_dotenv` / `lib/sys`) |
|
||||
| JSON quote | `lib/json` → `quote` |
|
||||
|
||||
## `ext/ai/llm` / `ext/ai/大模型` (object handles)
|
||||
|
||||
| English | Chinese | Role |
|
||||
|---------|---------|------|
|
||||
| `## load_env` | `## 加载环境` | Free function: load `.env` |
|
||||
| `# llm` | `# 大模型` | Object ctor → handle map |
|
||||
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Methods on the handle |
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/ai/llm.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load_env
|
||||
|
||||
*`model` = > llm *
|
||||
*`reply` = > `model`.complete prompt=Say hi in one word *
|
||||
> print text=`reply`
|
||||
```
|
||||
|
||||
Environment (create a **project-local** `.env`; do not commit secrets):
|
||||
|
||||
```env
|
||||
OPENAI_API_KEY=sk-...
|
||||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||||
OPENAI_MODEL=gpt-4o-mini
|
||||
```
|
||||
|
||||
Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`.
|
||||
|
||||
## Tests
|
||||
|
||||
- Import smoke: `tests/ext/llm-import.mq.md`
|
||||
- Live complete (local): `tests/ext/llm-complete.mq.md` + `tests/ext/.env`
|
||||
- Live agent `执行`: `tests/ext/agent-run-live.mq.md` + same `.env` (gold: `ext_agent_run_live`, skips if missing)
|
||||
- Offline agent smoke: `tests/ext/agent-smoke.mq.md` (gold: `ext_agent_framework_smoke`)
|
||||
@@ -1,163 +0,0 @@
|
||||
# 设计草案:机器生成的 YAML 清单(OKF 风格)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 草案(已采纳方向;修正「配置文件」误解) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) |
|
||||
| 取代 | 此前「YAML = 人手写的编译器配置 / frontmatter 契约」的表述 |
|
||||
|
||||
---
|
||||
|
||||
## 决策
|
||||
|
||||
Marqdo 项目中的 **YAML(及由其组成的 OKF 风格知识包)是工具自动生成的产物,不是给人填的配置文件。**
|
||||
|
||||
它的角色接近其它语言里由工具维护的**依赖与包元数据**,例如:
|
||||
|
||||
| 生态 | 类比(职责相近,不是语法相同) |
|
||||
|------|--------------------------------|
|
||||
| Rust | `Cargo.toml` / 解析后的依赖图(由源与清单共同推导,工具可改写) |
|
||||
| Python | `requirements.txt`(常由解析/冻结生成) |
|
||||
| Go | `go.mod` + `go.sum`(`go mod tidy` 维护) |
|
||||
|
||||
我们选择 **OKF 的形态**(Markdown + YAML frontmatter 的概念目录)来承载这份生成结果,从而一举两得:
|
||||
|
||||
1. **给编译器 / 包管理**:依赖图、模块身份、导出符号、版本锁定等可查询元数据
|
||||
2. **给本项目文档**:同一份生成物可直接渲染为「项目知识目录」——模块说明、依赖关系、API 索引等**自动生成本项目文档内容**
|
||||
|
||||
**唯一手写真相**仍是 `.mq.md` 源文件正文。YAML 清单是派生工件;过时则重新生成,禁止当成第二套权威配置去手改(除非工具链明确支持的「生成后微调」流程,且须可复现)。
|
||||
|
||||
**与源 frontmatter 的分工**(见 [markdown-mapping.md](markdown-mapping.md)):源文件 `---` 块可含 `title` 等元信息,以及人手声明的跨文件导入行 `> other.mq.md`。那是**源上的导入声明**,不是工程依赖锁。工具仍应据此(及正文 `>` 调用)**生成** OKF 风格依赖/模块目录;不要把生成目录手改成权威。
|
||||
|
||||
---
|
||||
|
||||
## 纠正:它不是什么
|
||||
|
||||
| ❌ 不是 | ✅ 是 |
|
||||
|--------|------|
|
||||
| 人手维护的 `run` / `target` / 路径配置 | 从源码 **推导** 出的依赖与模块元数据 |
|
||||
| 编译器「怎么跑」的 ini/配置替代品 | 解析、链接、文档站共用的 **生成清单** |
|
||||
| 与正文平行的第二套程序描述 | 正文的 **投影**(projection):结构化、可查询、可渲染 |
|
||||
|
||||
执行方式(解释 / 检查 / 编译到某后端)由 **CLI、子命令或工程约定** 决定,不塞进这份 YAML 让人配置。
|
||||
|
||||
---
|
||||
|
||||
## 数据流
|
||||
|
||||
```
|
||||
手写 .mq.md 源
|
||||
(叙事 + 类型 + 函数 + 正文中的引用/导入)
|
||||
│
|
||||
▼
|
||||
marqdo 工具链
|
||||
· 解析正文 AST
|
||||
· 收集 import / 链接 / 导出
|
||||
· 解析依赖、锁定版本
|
||||
│
|
||||
├──────────────────────────────┐
|
||||
▼ ▼
|
||||
生成 OKF 风格清单 编译 / 类型检查 / 运行
|
||||
(YAML + 概念 Markdown) (消费清单加速解析)
|
||||
│
|
||||
▼
|
||||
自动生成本项目文档
|
||||
(模块索引、依赖图、API 目录……)
|
||||
```
|
||||
|
||||
- **源 → 清单**:单向派生;清单不得反向成为「唯一写依赖的地方」。
|
||||
- **清单 → 文档**:OKF 包本身即可浏览;也可再生成站点/目录页。
|
||||
- **清单 → 编译**:编译器可读生成结果以跳过重复发现,但语义仍以源为准;清单缺失时应能从源重建。
|
||||
|
||||
---
|
||||
|
||||
## 生成物长什么样(示意)
|
||||
|
||||
工程在构建或 `marqdo sync` 类命令后,可得到类似 OKF bundle 的目录(路径未定):
|
||||
|
||||
```
|
||||
.marqdo/ # 或 docs/catalog/ 等 — 待 ADR
|
||||
index.md # 生成:项目总览
|
||||
modules/
|
||||
cart.md # 生成:每个模块一个概念文档
|
||||
prelude-list.md
|
||||
deps/
|
||||
lock.yaml # 生成:依赖锁定(机器向)
|
||||
```
|
||||
|
||||
单个生成的概念文件可呈 OKF 形:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: Marqdo Module # 生成
|
||||
title: cart
|
||||
description: 购物车:行项目与总额
|
||||
resource: src/cart.mq.md # 指向源文件
|
||||
depends:
|
||||
- prelude/list
|
||||
- math/sum
|
||||
exports: [Line, total]
|
||||
generated:
|
||||
by: "marqdo/0.1"
|
||||
at: 2026-08-04T01:00:00Z
|
||||
---
|
||||
|
||||
# cart
|
||||
|
||||
> 本页由 Marqdo 工具链根据 [`src/cart.mq.md`](../../src/cart.mq.md) **自动生成**,请勿手改。
|
||||
|
||||
## 依赖
|
||||
|
||||
- [prelude/list](../modules/prelude-list.md)
|
||||
- [math/sum](../modules/math-sum.md)
|
||||
|
||||
## 导出
|
||||
|
||||
| 符号 | 种类 |
|
||||
|------|------|
|
||||
| `Line` | type |
|
||||
| `total` | fn |
|
||||
```
|
||||
|
||||
人要改行为或说明 → 改 `src/cart.mq.md`;再生成,文档与依赖清单一起更新。
|
||||
|
||||
---
|
||||
|
||||
## 与「代码即文档」的关系
|
||||
|
||||
Marqdo 有两层「文档」,不要混为一谈:
|
||||
|
||||
| 层 | 谁写 | 是什么 |
|
||||
|----|------|--------|
|
||||
| **源文档** | 人(及协助编写的 Agent) | `.mq.md`:程序本身,打开即读、即可跑 |
|
||||
| **项目目录文档** | 机器 | OKF 风格 YAML/Markdown:从全项目源 **汇总** 的依赖、模块图、索引 |
|
||||
|
||||
前者消灭「实现与说明漂移」;后者消灭「仓库级总览靠手维护 README 目录」——总览从源自动长出,格式还对 Agent / 搜索友好(OKF)。
|
||||
|
||||
---
|
||||
|
||||
## 原则
|
||||
|
||||
1. **源为唯一权威** — 依赖与导出以 `.mq.md` 正文中的语言构造为准;YAML 是提取结果。
|
||||
2. **生成、可复现** — 同一源树 + 同一工具版本 → 同一清单(允许时间戳等字段除外或规范化)。
|
||||
3. **勿手改生成物** — 生成文件应带头注释或 `generated` 字段;CI 可校验「未提交脏生成」或「提交的生成与源一致」。
|
||||
4. **OKF 形、Marqdo 义** — 文件形态对齐 OKF(`type`、链接、目录),词汇服务模块/依赖/导出,而不是照搬 BigQuery 概念类型。
|
||||
5. **清单可删可再生** — 没有清单时,编译器仍须能直接从源工作(可能更慢);清单是缓存与文档面,不是语言语义的一部分。
|
||||
|
||||
---
|
||||
|
||||
## 待决问题(后续 ADR)
|
||||
|
||||
- [x] 生成物默认路径:`.marqdo/`(`-o` 可改)— 见 [catalog-cli.md](catalog-cli.md)
|
||||
- [x] `marqdo catalog` / `sync`;静态用户文档:`marqdo view output` — 见 [view.md](view.md)
|
||||
- [ ] 是否提交生成物进 git(项目自定;CI 可校验干净生成)
|
||||
- [ ] 与「可手写包身份 name/version」的边界
|
||||
- [ ] 是否沿用 OKF v0.2 的 `sources` 等溯源字段
|
||||
|
||||
---
|
||||
|
||||
## 结论
|
||||
|
||||
**YAML(OKF 风格清单)= 机器从 `.mq.md` 自动生成的依赖与项目元数据,并可据此自动生成本项目文档;不是人手填写的配置文件。**
|
||||
人写源,工具写清单与目录文档;编译器与文档站共同消费生成物,语义始终回到源。
|
||||
@@ -1,137 +0,0 @@
|
||||
# 内置关键字 / 函数:中英双名(草案)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已定(已实现)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 原则 | **无需导入**;中英为**同一语义的别名**,不是语言模式开关 |
|
||||
| 相关 | [keywords.md](keywords.md) · [stdlib-i18n.md](stdlib-i18n.md) · [call-arguments.md](call-arguments.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
Marqdo 要中英文都能自然书写。标准库已约定「**库文件名区分语言**」(见 [stdlib-i18n.md](stdlib-i18n.md));对**不必导入**的一层——字面量关键字与极少内置函数——也要对等提供中文名。
|
||||
|
||||
正因为每增加一个内置名,就要同时维护中英(及日后更多语言)别名,所以:
|
||||
|
||||
> **关键字 / 内置必须少而精**——体积在「名字 × 语言」上放大,而不是在功能清单上堆满。
|
||||
|
||||
更多能力进可导入的 `lib/`,用中英**不同库文件、不同函数名**扩展,不膨胀解释器内核。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层(与标准库对齐)
|
||||
|
||||
| 层 | 是否导入 | 中英怎么区分 |
|
||||
|----|----------|--------------|
|
||||
| **L0 内核** | 否 | **同一文件内双名**:`print` ≡ `打印`;`True` ≡ `真` |
|
||||
| **L1 标准库** | 是(`> lib/…`) | **不同文件**:`text.mq.md` vs `文本.mq.md`(见 i18n 草案) |
|
||||
|
||||
L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英文,写中文名就用中文,可在同一程序里混用。
|
||||
|
||||
---
|
||||
|
||||
## 3. 范围:哪些要双名
|
||||
|
||||
### 3.1 字面量 / 逻辑关键字(词法保留)
|
||||
|
||||
控制流仍靠 Markdown(`#` `1.` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。形参用 `+`。
|
||||
|
||||
| 英文 | 中文(提案) | 备注 |
|
||||
|------|--------------|------|
|
||||
| `True` | `真` | 布尔真 |
|
||||
| `False` | `假` | 布尔假 |
|
||||
| `None` | `空` | 空值 |
|
||||
| `and` | `且` | 逻辑与 |
|
||||
| `or` | `或` | 逻辑或 |
|
||||
| `not` | `非` | 逻辑非 |
|
||||
|
||||
中英文名均**不可作变量名**(同一保留集)。
|
||||
|
||||
### 3.2 内置函数(可调用、无需导入)
|
||||
|
||||
**仅**下列核心五项做中英双名(与「少而精」一致):
|
||||
|
||||
| 英文 | 中文(提案) | 作用 |
|
||||
|------|--------------|------|
|
||||
| `print` | `打印` | 写 stdout |
|
||||
| `input` | `输入` | 读一行 |
|
||||
| `len` | `长度` | 文本/表长度 |
|
||||
| `str` | `文本` | 转为显示文本 |
|
||||
| `int` | `整数` | 转为整数 |
|
||||
|
||||
形参名也提供中英别名(便于纯中文调用):
|
||||
|
||||
| 英文形参 | 中文形参 | 用于 |
|
||||
|----------|----------|------|
|
||||
| `text` | `内容` | `print` / `打印` |
|
||||
| `prompt` | `提示` | `input` / `输入` |
|
||||
| `value` | `值` | `len`/`str`/`int` 及对应中文名 |
|
||||
|
||||
示例(等价):
|
||||
|
||||
```markdown
|
||||
> print text=Hello
|
||||
> 打印 内容=你好
|
||||
|
||||
*`n` = > len `s`*
|
||||
*`n` = > 长度 值=`s`*
|
||||
```
|
||||
|
||||
### 3.3 明确不进 L0 双名表
|
||||
|
||||
下列若已在解释器中实现,视为**宿主原语 / 过渡 API**,**不**再批中文内核别名;应迁入或仅通过标准库暴露(中英分文件):
|
||||
|
||||
| 英文名 | 去向 |
|
||||
|--------|------|
|
||||
| `type` | L1 或维持实现细节,不进「关键字最少集」宣传 |
|
||||
| `trim` `split` `join` | L1:`lib/text.mq.md` / `lib/文本.mq.md` |
|
||||
| `at` | L1:`lib/table.mq.md` / `lib/表.mq.md` |
|
||||
|
||||
这样 L0 公开面 ≈ **6 个关键字词 ×2 + 5 个函数 ×2**,而不是「每个工具函数都 ×2」。
|
||||
|
||||
---
|
||||
|
||||
## 4. 语义规则
|
||||
|
||||
1. **别名等价**:中英文名绑定同一实现;诊断文案可用英文稳定串(金样例已有),用户文档中英均可举例。
|
||||
2. **可混用**:同一文件可同时出现 `print` 与 `打印`、`True` 与 `真`。
|
||||
3. **遮蔽**:用户 `# 打印` 与 `# print` 均会遮蔽对应内置名(实现阶段应警告)。
|
||||
4. **大小写**:英文关键字保持 Python 风格(`True`/`False`/`None`);中文无名感大小写问题。
|
||||
5. **扩语言**:日后日文等 → 再为 L0 增加第三个别名列;仍无「名字表」而非语言开关。标准库继续用**文件名**区分(见 i18n 草案)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与旧决议的关系
|
||||
|
||||
- 旧文「中文 `print` 废弃、统一为 `print`」:**废止**;改为正式双名 `print` / `打印`。
|
||||
- [keywords.md](keywords.md) 原则条「英文标识」改为「**内核双名;标准库分文件**」——实现阶段改正文。
|
||||
- 不引入中文控制流关键字(`如果`/`循环` 等);分支用 `1.` …,循环用 `-`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 文档与金样例义务(实现时)
|
||||
|
||||
| 项 | 要求 |
|
||||
|----|------|
|
||||
| `keywords.md` | L0 表改为中英并列;砍掉对 `trim`/`split`/… 的「内核关键字」宣传 |
|
||||
| `public/` | 英 / 中文件同目录并列(拉丁名 vs 中文名) |
|
||||
| `tests/` | 中文关键字 / `打印`·`长度` 等金样例;与英文样例对等 |
|
||||
| 诊断 | 位置格式不变;message 可暂维持英文,或中英均可接受(另开小节) |
|
||||
|
||||
---
|
||||
|
||||
## 7. 实现备忘(暂不开发)
|
||||
|
||||
1. 词法 / 解析:字面量与 `and`/`or`/`not` 识别中文别名。
|
||||
2. 调用解析:内置表按别名归一到同一 `BuiltinId`。
|
||||
3. 形参绑定:`text`≡`内容`,`prompt`≡`提示`,`value`≡`值`。
|
||||
4. **不要**加 `lang:` 或全局「中文模式」。
|
||||
5. 与 [stdlib-i18n.md](stdlib-i18n.md) 一并落地时:先收束 L0 公开面,再铺 `lib/text` ↔ `lib/文本`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 一句话
|
||||
|
||||
**内核:中英别名、无需导入、必须少;标准库:中英分文件、靠导入路径选择——这样 Marqdo 才能中英文通用而不把解释器撑爆。**
|
||||
@@ -1,97 +0,0 @@
|
||||
# Marqdo 关键字与内置名(v0 最小集)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(中英双名) |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 原则 | **少而精**;控制流靠 Markdown;内核中英**别名等价**(见 [keywords-i18n.md](keywords-i18n.md)) |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords-i18n.md](keywords-i18n.md) · [stdlib-i18n.md](stdlib-i18n.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 设计原则
|
||||
|
||||
1. **标记承担架构**:函数=`#`,**形参=`+`**,**分支=`1.`…**,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
|
||||
2. **内核双名**:字面量 / 逻辑词 / 五个核心内置函数均有中英别名,**无需导入**,可混用。
|
||||
3. **学 Python 的边界**:区分 **关键字** vs **内置函数名**。
|
||||
4. **宁少勿多**:扩展能力进可导入标准库(中英分文件,见 [stdlib-i18n.md](stdlib-i18n.md))。
|
||||
|
||||
---
|
||||
|
||||
## 2. 关键字(词法保留,不可作变量名)
|
||||
|
||||
| 英文 | 中文 | 含义 |
|
||||
|------|------|------|
|
||||
| `True` | `真` | 布尔真 |
|
||||
| `False` | `假` | 布尔假 |
|
||||
| `None` | `空` | 空值 |
|
||||
| `and` | `且` | 逻辑与 |
|
||||
| `or` | `或` | 逻辑或 |
|
||||
| `not` | `非` | 逻辑非 |
|
||||
|
||||
**不引入:** `if` `else` `while` `for` `def` `return` …(分支臂 `*` 不是单词 `else`。)
|
||||
|
||||
---
|
||||
|
||||
## 3. 内置函数(可调用,无需导入)
|
||||
|
||||
| 英文 | 中文 | 作用 |
|
||||
|------|------|------|
|
||||
| `print` | `打印` | 写 stdout |
|
||||
| `input` | `输入` | 读一行;capture / view 用 frontmatter `stdin:` / `输入:`、表单或 `--stdin-file` 预置 |
|
||||
| `len` | `长度` | 文本/表长度 |
|
||||
| `str` | `文本` | 转为显示文本 |
|
||||
| `int` | `整数` | 转为整数 |
|
||||
|
||||
**文本**:裸 token 按字面量;需 `\n` 等转义时用 `"..."`(见 [markdown-mapping.md](markdown-mapping.md) §7)。
|
||||
|
||||
形参别名:
|
||||
|
||||
| 英文 | 中文 | 用于 |
|
||||
|------|------|------|
|
||||
| `text` | `内容` | `print` / `打印` |
|
||||
| `prompt` | `提示` | `input` / `输入` |
|
||||
| `value` | `值` | `len`/`str`/`int` 及其中文名 |
|
||||
|
||||
```markdown
|
||||
> print text=Hello
|
||||
> 打印 内容=你好
|
||||
|
||||
*`n` = > 长度 值=`s`*
|
||||
```
|
||||
|
||||
宿主原语 `type` / `trim` / `split` / `join` / `at` **无**内核中文别名;文本/表扩展走标准库文件(见 [stdlib-i18n.md](stdlib-i18n.md))。转换错误见 [stdlib.md](stdlib.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 Markup 调用的关系
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=Hello World!
|
||||
|
||||
*`n` = 1*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
2. *
|
||||
> 打印 内容=other
|
||||
```
|
||||
|
||||
- `>` 是调用标记;`print` / `打印` 是同一内置的别名。
|
||||
- 用户 `# print` 或 `# 打印` 会遮蔽对应名字。
|
||||
|
||||
---
|
||||
|
||||
## 5. 标识符规则(摘要)
|
||||
|
||||
- 变量:`` `name` ``;不可为上表任一中英文关键字。
|
||||
- 函数名:`#` 标题;中英文均可。
|
||||
- 比较:`==` `>` `<` `>=` `<=`;逻辑:`and`/`且`、`or`/`或`、`not`/`非`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 后续可增(未批准)
|
||||
|
||||
`float`、`range`;以及 `break`/`continue`。增加前开短 ADR,并同步考虑是否值得占用双名配额。
|
||||
@@ -1,271 +0,0 @@
|
||||
# Marqdo 语法映射 v0.2(Markup-as-Syntax)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、标识符反引号、`-` 专用于循环) |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 取代 | v0.1 中「函数头 `-` 形参 / 裸名形参与遍历变量 / `+` 分支」 |
|
||||
| 相关 | [objects.md](objects.md) · [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) |
|
||||
|
||||
Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。
|
||||
|
||||
---
|
||||
|
||||
## 1. 哲学
|
||||
|
||||
1. `.mq.md`:打开即文档,运行即程序。
|
||||
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
|
||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` `1.` 表…)与 **斜体语句** / **粗体返回**。
|
||||
4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
||||
5. **标识符一律反引号**:凡表示变量槽位(形参、绑定、引用、遍历项、集合名)均写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。
|
||||
|
||||
---
|
||||
|
||||
## 2. 行首判别与成段注释
|
||||
|
||||
跳过前导空白后,对**段首行**(空行之后的第一行,或文件起始):
|
||||
|
||||
| 首字符 | 分类 |
|
||||
|--------|------|
|
||||
| 普通文字 / 空 | **注释** |
|
||||
| 标记字符 | **代码** |
|
||||
|
||||
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字 `1.`、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
|
||||
|
||||
**成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。
|
||||
|
||||
---
|
||||
|
||||
## 3. 映射总表(v0.2)
|
||||
|
||||
| 标记 | 语义 |
|
||||
|------|------|
|
||||
| `#` … `######` | **`#` = 对象/类型**;**`##`+ = 函数/方法**(层差=嵌套)。见 [objects.md](objects.md) |
|
||||
| 函数头下 `+ `` `名` `` ` | 形参 / 构造参数(可选 `` `名`=默认值 ``) |
|
||||
| 体内 `1.` `2.` … | **分支**(有序列表臂;条件行或 else) |
|
||||
| 体内 `-` | **循环**(`while` 条件,或 `` [`项`](`集合`) `` 遍历) |
|
||||
| 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` |
|
||||
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
|
||||
| `` > `对象`.方法 … `` | 方法调用(实例 map 须含 `_type`) |
|
||||
| frontmatter `> path.mq.md` | 跨文件导入 |
|
||||
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
|
||||
| `**…**` | **返回值**(架构级;函数结果) |
|
||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||||
| 无标记行 / 成段续行 | 注释(空行分段,见 §2) |
|
||||
| GFM 表格 | 集合 |
|
||||
| 空 RHS 赋值 + 后随 `$$…$$`(或同行 `$$…$$`) | **公式赋值** → 运行时 `formula`(见 [stdlib-math.md](stdlib-math.md));叙述面无名 `$$` 仅展示 |
|
||||
| ` ```lang ` | 外联异种代码 |
|
||||
| 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §11) |
|
||||
|
||||
### `+` / `-` / `1.` 消歧
|
||||
|
||||
| 位置 | `+` | `1.` … | `-` |
|
||||
|------|-----|--------|-----|
|
||||
| 函数标题后、**首条体语句前** | 形参:`` + `名` `` / `` + `名`=默认 `` | (非法) | (非法作形参) |
|
||||
| 函数体内 | (非法作分支) | 分支臂:`1. `条件`` / `2. *` | 循环 |
|
||||
|
||||
**分支从未使用 `+`。** 自 v0 起即采用 GFM 有序列表;`+` 在 v0.2 专用于形参,与 `-` 循环彻底分离。
|
||||
|
||||
### 输出不是架构
|
||||
|
||||
| 错误(旧) | 正确(v0.2) |
|
||||
|------------|--------------|
|
||||
| `**Hello**` 表示打印 | `> print text=Hello` |
|
||||
| `+ `x` > 0` 作分支 | `1. `x` > 0` |
|
||||
| `- 谁` 作形参 | `` + `谁` `` |
|
||||
| `[果](篮子)` 裸名遍历 | `` [`果`](`篮子`) `` |
|
||||
|
||||
`print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 语句、返回、调用
|
||||
|
||||
### 程序语句(斜体)
|
||||
|
||||
```markdown
|
||||
*`x` = 1*
|
||||
|
||||
*`y` = `x` + 2*
|
||||
```
|
||||
|
||||
行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
|
||||
|
||||
### 返回值(粗体)
|
||||
|
||||
```markdown
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
### 输出(内置函数 `print`)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
### else 与斜体消歧
|
||||
|
||||
- 分支臂有序行 `N. *`(或 `N.` 后仅 `*`)→ else。
|
||||
- `*中间有内容*` → 程序语句。
|
||||
- `**…**` → 返回(与 else 无关)。
|
||||
|
||||
---
|
||||
|
||||
## 5. Frontmatter 与跨文件
|
||||
|
||||
同 v0:文件头 `---` 对为元信息;其中 `> file.mq.md` 为导入。
|
||||
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 对象、函数、形参
|
||||
|
||||
- `# Name`:对象(构造体);`# main` 为入口对象。
|
||||
- `##` / `###` …:函数或方法;挂在对象下则为方法。
|
||||
- 标准库顶层 API 使用自由函数 `## name`(见 [objects.md](objects.md))。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
|
||||
## 加问候
|
||||
+ `谁`
|
||||
|
||||
**你好,`谁`**
|
||||
```
|
||||
|
||||
可选形参:
|
||||
|
||||
```markdown
|
||||
## 问候
|
||||
+ `谁`
|
||||
+ `礼貌`=False
|
||||
```
|
||||
|
||||
方法体内自动绑定 `` `自` `` / `` `self` ``。
|
||||
|
||||
---
|
||||
|
||||
## 7. 绑定、比较与字符串
|
||||
|
||||
| 写法 | 含义 |
|
||||
|------|------|
|
||||
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定 |
|
||||
| `` `x` == 1 `` | 相等比较 |
|
||||
| `"text"` | **双引号字符串**(复杂文本;见下) |
|
||||
| `hello` / `路径` | **裸 token**(无转义,按字面量) |
|
||||
|
||||
### 双引号字符串(复杂文本)
|
||||
|
||||
需要转义或嵌入变量时用 `"..."`;**裸 token 不转义**,保持文档简洁:
|
||||
|
||||
```markdown
|
||||
> input prompt="你叫什么名字\n"
|
||||
*`msg` = "Hello, `name`!\n"*
|
||||
```
|
||||
|
||||
| 转义 | 含义 |
|
||||
|------|------|
|
||||
| `\n` | 换行 |
|
||||
| `\t` | 制表 |
|
||||
| `\r` | 回车 |
|
||||
| `\\` | `\` |
|
||||
| `\"` | `"` |
|
||||
|
||||
引号内仍可用 `` `变量` `` 插值。字面反斜杠+n 写 `\\n`(裸 token `\\n` 则就是两个字符)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 分支与循环
|
||||
|
||||
分支(**有序列表** `1.` `2.` …),循环(`-`):
|
||||
|
||||
```markdown
|
||||
*`x` = 0*
|
||||
|
||||
1. `x` > 0
|
||||
> print text=正数
|
||||
2. `x` < 0
|
||||
> print text=负数
|
||||
3. *
|
||||
> print text=零
|
||||
```
|
||||
|
||||
```markdown
|
||||
*`bool_value` = True*
|
||||
|
||||
1. `bool_value` == True
|
||||
> print text=True
|
||||
2. *
|
||||
> print text=False
|
||||
```
|
||||
|
||||
```markdown
|
||||
- [`果`](`篮子`)
|
||||
> print text=今天吃`果`
|
||||
```
|
||||
|
||||
`while`:
|
||||
|
||||
```markdown
|
||||
- `n` > 0
|
||||
> print text=`n`
|
||||
*`n` = `n` - 1*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 集合(表格)
|
||||
|
||||
同 v0。`` `篮子` = `` 后接 GFM 表。
|
||||
|
||||
---
|
||||
|
||||
## 10. 求值入口
|
||||
|
||||
1. 加载 `index.mq.md` + 导入。
|
||||
2. Pass1 收集定义。
|
||||
3. Pass2 执行 `# main`。
|
||||
4. `*` 语句、`**` 返回、`>` 调用、`1.` 分支、`-` 循环、表绑定按语义执行;`> print` 写 stdout。
|
||||
|
||||
---
|
||||
|
||||
## 11. 函数体结束(`---` / `***` / 空返回)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello `谁`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
| 约定 | 说明 |
|
||||
|------|------|
|
||||
| `---` 或 `***` | 函数体**顶层**单独一行 → **结束本函数** |
|
||||
| `****` / 空粗体 | 空返回(`None`),并结束本函数体 |
|
||||
| Frontmatter | 仅**文件开头**成对 `---` = 元信息 |
|
||||
|
||||
---
|
||||
|
||||
## 12. v0.2 非目标
|
||||
|
||||
- break/continue、完整错误模型、静态类型、完整 FFI
|
||||
- `+` 作分支、`+`/`-` 作形参(**不保留**)
|
||||
|
||||
---
|
||||
|
||||
## 13. 示例索引
|
||||
|
||||
见 [`tests/`](../../tests/)。
|
||||
@@ -1,73 +0,0 @@
|
||||
# Objects(`#`)与函数(`##`+)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | Accepted |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [ext-llm.md](ext-llm.md) |
|
||||
|
||||
## 1. 约定
|
||||
|
||||
| 标题层 | 含义 |
|
||||
|--------|------|
|
||||
| `#`(恰好一层) | **对象 / 类型**。正文 = 构造体;调用类型名 = 构造实例。 |
|
||||
| `##` 及更深 | **函数**(自由函数或方法)。层数差表示嵌套,与 v0.1 相同。 |
|
||||
|
||||
`# main` 是**入口对象**:运行文件 = 执行其构造体。若无 `main`,且文件恰好只有一个无参顶层 `#` 对象(如 `# Hello World`),则把它当作入口。
|
||||
|
||||
## 2. 实例句柄
|
||||
|
||||
构造返回值若为 `map`,运行时写入 `_type`(文本,值为类型名),形成句柄。
|
||||
方法调用通过 `_type` 找到定义对象,再解析其下的 `##` 方法。
|
||||
|
||||
方法体内自动绑定:
|
||||
|
||||
- `自`(中文)
|
||||
- `self`(英文)
|
||||
|
||||
二者同一接收者。
|
||||
|
||||
## 3. 调用外形
|
||||
|
||||
```markdown
|
||||
# 大模型
|
||||
+ `模型名`
|
||||
|
||||
*`自` = …配置 map…*
|
||||
**`自`**
|
||||
|
||||
## 运行
|
||||
+ `提示`
|
||||
|
||||
…使用 `自` …
|
||||
**`内容`**
|
||||
|
||||
# main
|
||||
|
||||
*`模型` = > 大模型 模型名=gpt-4o-mini *
|
||||
*`回复` = > `模型`.运行 提示=你好 *
|
||||
> print text=`回复`
|
||||
```
|
||||
|
||||
- `> 大模型 …` — 构造
|
||||
- `` > `模型`.运行 … `` — 方法(接收者 + `.` + 方法名)
|
||||
- `## 自由函数` 挂在模块顶层(非某对象子标题)— 与旧版顶层 `# http_get` 对等,现写为 `## http_get`
|
||||
|
||||
## 4. 标准库
|
||||
|
||||
官方 `lib/*.mq.md` 以**顶层自由函数**为主:全部为 `##`(不再使用 `#` 冒充类型)。
|
||||
真正的类型化扩展(如 `ext/llm`)使用 `# 类型` + `##` 方法。
|
||||
|
||||
## 5. 非目标(本波)
|
||||
|
||||
- 继承 / 接口 / 可见性
|
||||
- 无 `_type` 的「鸭子」方法分发
|
||||
- 用表格声明字段 schema(表格仍表示集合)
|
||||
|
||||
## 6. 迁移摘要
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| 库顶层 `# http_get` | `## http_get` |
|
||||
| `# main` + `## 嵌套` | 不变(main = 入口对象) |
|
||||
| `ext` 顶层 `# complete` | `# llm` / `# 大模型` 构造 + `## complete` / `## 运行` |
|
||||
@@ -1,75 +0,0 @@
|
||||
# 解释器流水线可视调试
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(开发期强制友好) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 参考 | [Crafting Interpreters — Scanning](https://www.craftinginterpreters.com/scanning.html)(先打 token)· [AstPrinter](https://craftinginterpreters.com/representing-code.html) · CLI `--dump-ast` 类实践 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
开发 `marqdo` 时,对任意 `.mq.md` 应能**分阶段看见**中间结果,避免黑盒;正式 `run` 默认安静,仅输出程序 `print` 的内容。
|
||||
|
||||
---
|
||||
|
||||
## 2. CLI 开关
|
||||
|
||||
```bash
|
||||
marqdo run FILE [dumps...]
|
||||
marqdo dump FILE --stage lines|tokens|ast|sema|all
|
||||
```
|
||||
|
||||
| 标志 | 阶段 | 输出内容 |
|
||||
|------|------|----------|
|
||||
| `--dump-lines` | 行分类 | 每行:`LINE kind=Comment\|Code\|Blank` + 原文预览 |
|
||||
| `--dump-tokens` | 词法 | Token 流:`type lexeme line:col` |
|
||||
| `--dump-ast` | 语法 | S 表达式或缩进树(模块/函数/语句) |
|
||||
| `--dump-sema` | 语义 | 作用域、导入图、提升后的符号表 |
|
||||
| `--trace-eval` | 求值 | **JSON 行**(stderr):语句级事件,含 `path` / `span`(`line:col`) |
|
||||
| `--dump-bytecode` | 字节码 | 反汇编 `Program`(指令旁带 `@line:col`;见 [bytecode.md](bytecode.md)) |
|
||||
| `--backend tree\|bytecode` | 执行后端 | 默认 `tree`;`bytecode` 走栈式 VM |
|
||||
| `--dump-all` | 以上全部 | 按管道顺序打印,段之间用横幅分隔 |
|
||||
|
||||
格式约定:
|
||||
|
||||
- dump 人类可读优先;段首统一:`=== marqdo: <stage> ===`
|
||||
- `--trace-eval`:每条事件一行 JSON,例如
|
||||
`{"event":"stmt","path":"…","span":"5:1","kind":"call","callee":"print"}`
|
||||
树遍历:`enter_fn` / `stmt` / `leave_fn`;字节码:`op`(`print`/`input`/`call`/`return`)。
|
||||
- 有 dump 时:若求值未实现,仍打印已实现阶段再以非 0 退出(便于 M1 只测 lines)
|
||||
|
||||
---
|
||||
|
||||
## 3. 横幅示例
|
||||
|
||||
```
|
||||
=== marqdo: lines (tests/structure/hello.mq.md) ===
|
||||
1 Blank
|
||||
2 Comment | # Hello World
|
||||
3 Blank
|
||||
4 Comment | 本程序调用...
|
||||
5 Blank
|
||||
6 Code | > print text=Hello World!
|
||||
=== marqdo: end lines ===
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 实现要点
|
||||
|
||||
- dump 逻辑放在 `src/debug/`(或各阶段 `fmt`),**不**与安静求值路径搅在一起。
|
||||
- 每个阶段纯函数:`input → (artifacts, diagnostics)`,CLI 负责打印。
|
||||
- 单测可断言 dump 字符串包含关键行(稳定子集),避免绑死全文格式。
|
||||
|
||||
---
|
||||
|
||||
## 5. 与里程碑
|
||||
|
||||
| 里程碑 | 必须可用的 dump |
|
||||
|--------|-----------------|
|
||||
| M1 | `--dump-lines`(及可选 tokens 雏形) |
|
||||
| M2 | `--dump-ast` |
|
||||
| M3–M4 | `--dump-sema`、`--trace-eval` |
|
||||
| 全程 | `--dump-all` 随阶段增长自动变完整 |
|
||||
@@ -1,19 +0,0 @@
|
||||
# 记录:返回 / 语句 / 输出 / 分割线(决议)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已决议(并入 mapping v0.1 + keywords;2026-08-04 修订函数收束) |
|
||||
| 日期 | 2026-08-04 |
|
||||
|
||||
---
|
||||
|
||||
## 决议
|
||||
|
||||
1. **`*…*` = 程序语句**。
|
||||
2. **`**…**` = 返回值**(架构级);空粗体 `****` / `** **` = 空返回(`None`)并结束函数体。
|
||||
3. **输出**用内置函数 **`print`**(英文),不是粗体,不是中文名。
|
||||
4. **`---` / `***`(函数体顶层)**:结束本函数体(无返回值函数收束);**不是**分支/循环装饰框。
|
||||
5. **成段注释**:空行分段;段内续行不因首字符升级为代码。
|
||||
6. **否决**:无标记行 = 默认代码。
|
||||
|
||||
详见 [keywords.md](keywords.md)、[markdown-mapping.md](markdown-mapping.md)、[code-vs-comment.md](code-vs-comment.md)。
|
||||
@@ -1,49 +0,0 @@
|
||||
# 外联 / 胶水标准库
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(v1)** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原则
|
||||
|
||||
**导入即用**:`lib/foreign` / `lib/外联`。解释器来自用户本机(PATH / `set_cmd` / `MARQDO_FOREIGN_*`)。live view 可点 Run;静态导出展示源码,Run 禁用。
|
||||
|
||||
---
|
||||
|
||||
## 2. 绑定语法(与公式同构)
|
||||
|
||||
```markdown
|
||||
`hi` =
|
||||
```python
|
||||
print("hello")
|
||||
```
|
||||
|
||||
*`out` = > run code=`hi` *
|
||||
```
|
||||
|
||||
得到运行时类型 **`code`**(`lang` + `source`)。未绑定的 \`\`\` 围栏仍是叙述注释。
|
||||
|
||||
曾用的 \`\`\`python name=hi **已移除**。
|
||||
|
||||
---
|
||||
|
||||
## 3. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `set_cmd` | `设置命令` | `lang`, `cmd` | None |
|
||||
| `run` | `运行` | `code`(code 值) | 文本 stdout |
|
||||
| `run_lang` | `按语言运行` | `lang`, `source` | 文本 |
|
||||
| `langs` | `语言表` | | 列表 |
|
||||
|
||||
live view:Structure 中 code 卡片带命令框 + Run → `POST /api/foreign-run`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 一句话
|
||||
|
||||
**`name` = + \`\`\`lang 围栏 → code 值;显式 run;本机解释器可配置。**
|
||||
@@ -1,146 +0,0 @@
|
||||
# 标准库多语言命名(草案)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **草案(先文档、后实现)** |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 原则 | **不指定语言**;靠**库文件名**区分中英(及日后其它语言) |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [keywords.md](keywords.md) · [keywords-i18n.md](keywords-i18n.md) · [user-site.md](user-site.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 要解决什么
|
||||
|
||||
- 内置(解释器里的名字)必须**少而精**;更多能力放进可 `>` 导入的标准库。
|
||||
- 标准库需要**中英两套 API**(函数名不同),并方便以后再加日文、西班牙文等。
|
||||
- **不要**用 frontmatter `lang:`、环境变量默认语言、或「同一导入路径再解析语言」——那是负累,也不符合「文档即代码」的直观性。
|
||||
|
||||
---
|
||||
|
||||
## 2. 方案(采用)
|
||||
|
||||
**导入哪个库文件,就用哪套函数名。**
|
||||
文件名本身表达语言;解释器只做路径解析,不做语言推断。
|
||||
|
||||
### 2.1 推荐:库名用目标语言书写
|
||||
|
||||
| 导入 | 库内函数名(示例) |
|
||||
|------|-------------------|
|
||||
| `> lib/text.mq.md` | `trim` · `split` · `join` |
|
||||
| `> lib/文本.mq.md` | `去空白` · `拆分` · `拼接` |
|
||||
| `> lib/table.mq.md` | `rows` · `row_at` |
|
||||
| `> lib/表.mq.md` | `行数` · `取行` |
|
||||
|
||||
示例:
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
*`xs` = > split value=a,b,c sep=,*
|
||||
```
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/文本.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
*`xs` = > 拆分 s=a,b,c sep=,*
|
||||
```
|
||||
|
||||
读者看到导入路径就能知道后面该用英文还是中文函数名——**无需再声明语言**。
|
||||
|
||||
### 2.2 可选:同概念用后缀区分(同目录、同「概念」)
|
||||
|
||||
若希望「同一概念」在文件名上仍共享拉丁词根,可用:
|
||||
|
||||
| 导入 | 含义 |
|
||||
|------|------|
|
||||
| `> lib/text-en.mq.md` | 英文 API |
|
||||
| `> lib/text-zh.mq.md` | 中文 API |
|
||||
|
||||
这与 §2.1 **等价可选**,不是第二套解析器:仍然是「写哪个路径就加载哪个文件」。
|
||||
**优先推荐 §2.1**(`text` / `文本`),后缀形式留给需要 ASCII-only 路径的环境。
|
||||
|
||||
### 2.3 明确不做
|
||||
|
||||
| 不做 | 原因 |
|
||||
|------|------|
|
||||
| `lang: zh` / `MARQDO_LANG` | 隐式状态,难读、难测 |
|
||||
| `> std/text` 再按语言展开 | 多一次魔法 |
|
||||
| 同一文件内中英函数双份导出 | 遮蔽与文档混乱 |
|
||||
| 强制用户只许用中文或只许用英文 | Marqdo 本就多语言友好 |
|
||||
|
||||
---
|
||||
|
||||
## 2.4 特例:JSON
|
||||
|
||||
`JSON` 为专有缩写,**不强求**中文库名或中文 API 翻译。官方只提供:
|
||||
|
||||
```text
|
||||
lib/json.mq.md # 中英文档均 `> lib/json.mq.md`;函数 parse / stringify / get / keys
|
||||
```
|
||||
|
||||
不设 `lib/数据.mq.md` 等平行文件。其余模块仍遵守 §2.1。详见 [stdlib-modules.md](stdlib-modules.md) §3.4。
|
||||
|
||||
---
|
||||
|
||||
## 3. 与「少而精内置」的边界
|
||||
|
||||
| 层 | 内容 | 如何获得 |
|
||||
|----|------|----------|
|
||||
| **内置(L0)** | 极少:`print` `input` `len` `str` `int`(及语言字面量关键字) | 直接调用,无需导入 |
|
||||
| **标准库(L1)** | 文本/表等扩展 API;**通常**中英各一套文件、各一套函数名(**JSON 例外**:仅 `lib/json.mq.md`) | frontmatter `> lib/…` |
|
||||
| **宿主原语(实现细节)** | 若 `trim`/`split` 等暂由解释器实现 | 仅供标准库包装调用;**文档与用户站引导走 L1**,不鼓励当「关键字」堆砌 |
|
||||
|
||||
日后若某能力足够「核心」,可再升格为 L0;升格前先留在 L1。
|
||||
|
||||
---
|
||||
|
||||
## 4. 目录与扩展约定
|
||||
|
||||
```text
|
||||
lib/
|
||||
text.mq.md / 文本.mq.md
|
||||
table.mq.md / 表.mq.md
|
||||
# 本波:fs/文件 · sys/系统 · time/时间 · json(中英同文件)· net/网络
|
||||
# 暂缓:math/数学 · foreign/外联
|
||||
# 其它语言:texte.mq.md / テキスト.mq.md …
|
||||
```
|
||||
|
||||
扩展新语言时:
|
||||
|
||||
1. **新加一个库文件**(文件名用该语言或 `概念-xx`)。
|
||||
2. 库内函数名用该语言习惯。
|
||||
3. 文档表增加一行映射;**无需改解释器语言开关**。
|
||||
|
||||
导入解析仍沿用现有规则:相对路径 → 官方 `lib/` 根(`MARQDO_LIB` / 工作区 `lib/` 等),**不增加语言分支**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 文档与示例义务
|
||||
|
||||
- 用户站:英/中库各一页(或同页两小节),导入路径与调用名并排;**JSON** 可共用一页、同一导入。
|
||||
- 金样例:分文件模块中英导入至少各一条;JSON 测 `lib/json.mq.md` 即可。
|
||||
- [keywords.md](keywords.md) 只列 L0;L1 指向本文 + [stdlib.md](stdlib.md) + [stdlib-modules.md](stdlib-modules.md)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 实现备忘(暂不开发)
|
||||
|
||||
实现阶段仅需:
|
||||
|
||||
1. 落地 `lib/text.mq.md` 与 `lib/文本.mq.md`(及 table / 表)两套文件与函数名。
|
||||
2. 更新导入示例与金样例;删除「仅中文库名」的单轨示例。
|
||||
3. **不要**实现 `lang:`、默认语言、或 `std/text` 自动选语言。
|
||||
|
||||
若历史上加过 `Module.lang` / `lang:` 解析,应撤回,与本草案对齐。
|
||||
|
||||
---
|
||||
|
||||
## 7. 一句话
|
||||
|
||||
**标准库用文件名区分语言(导入即选择);JSON 为缩写特例,中英共用 `lib/json.mq.md`——无语言开关。**
|
||||
@@ -1,231 +0,0 @@
|
||||
# 数学标准库(方案)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已实现(M1–M4)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) |
|
||||
| 导入 | `lib/math.mq.md`(英)· `lib/数学.mq.md`(中) |
|
||||
| 范围 | **高中数学**(初等函数、导数、圆锥曲线、简单方程);非大学 CAS |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. **公式类型**:解析 `$$…$$`(及行内 `$…$` 的可选支持),得到可绑定、可传递的 **`formula` 值**——语义上像「公式常量 / 公式变量」。
|
||||
2. **数学库对 `formula`(及文本表达式)做操作**:求值、化简、求导、求解、作图等。
|
||||
3. **数值 + 随机**:日常算术与可复现随机。
|
||||
4. **作图**:view / 静态页内嵌 SVG;CLI 写本地文件(可指定 `path`)。
|
||||
|
||||
**难度自觉:** 只覆盖高中知识面,自研小型表达式 AST + 规则即可,**不**追求 Mathematica / SymPy 完备性。
|
||||
|
||||
---
|
||||
|
||||
## 2. 核心模型:`formula` 类型
|
||||
|
||||
### 2.1 运行时
|
||||
|
||||
| 类型 | `type` 标签 | 说明 |
|
||||
|------|-------------|------|
|
||||
| `Value::Num(f64)` | `num` | 浮点 |
|
||||
| `Value::Formula(…)` | `formula` | 已解析的表达式树(或等价内部表示) |
|
||||
|
||||
`print` / `str` 对 `formula`:输出规范 ASCII(如 `2*x + 1`)或保留源 LaTeX 的一种(实现时写死并文档化;建议 **ASCII 规范式** 便于测试)。
|
||||
|
||||
### 2.2 文档中的 `$$` = 公式赋值(与表格同构)
|
||||
|
||||
在可执行面用 **空 RHS 赋值** 后跟展示数学块,把公式绑到变量(与 `` `xs` = `` 后跟表格一致):
|
||||
|
||||
````markdown
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
sin(x) + x
|
||||
$$
|
||||
|
||||
*`df` = > diff formula=`f` var=x *
|
||||
|
||||
> plot formula=`f` var=x min=-3 max=3 path=f.svg
|
||||
````
|
||||
|
||||
也支持:
|
||||
|
||||
- 单行围栏:下一行 `$$x^2 - 2$$`
|
||||
- 同行 compact:`*`f` = $$x^2 - 2$$ *`
|
||||
|
||||
**废除:** `$$:name` / `$$ name=…` 模块级具名块(不再产生绑定)。
|
||||
|
||||
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区若出现未挂在赋值上的裸 `$$` 围栏 → 报错,提示使用 `` `name` = `` + 围栏。
|
||||
|
||||
**行内 `$…$`:** v1 不做绑定;需要时用 `> formula text=…` 显式构造。
|
||||
|
||||
### 2.3 从文本构造
|
||||
|
||||
| 英文 | 中文 | 说明 |
|
||||
|------|------|------|
|
||||
| `formula` | `公式` | `text=` 解析为 `formula`(ASCII 或简单 LaTeX 子集) |
|
||||
|
||||
数学库函数形参统一接受:**`formula` 值**,或能解析的 **文本**(内部先 `formula` 化)。
|
||||
|
||||
### 2.4 与叙述面的关系
|
||||
|
||||
- `` `f` = `` + `$$…$$`:代码面赋值,得到 `formula` 值。
|
||||
- 成段注释里的 `$$`:仍是注释,不解析为公式。
|
||||
- view:公式赋值在 Structure 中显示为绑定,不是 comment。
|
||||
|
||||
(见 [markdown-mapping.md](markdown-mapping.md):空 RHS + `$$` → 公式赋值。)
|
||||
|
||||
---
|
||||
|
||||
## 3. 知识范围(高中)
|
||||
|
||||
### 3.1 表达式与符号(S)
|
||||
|
||||
| 纳入 | 例子 |
|
||||
|------|------|
|
||||
| 多项式 | `x^2 - 3*x + 2` |
|
||||
| 初等函数 | `sin` `cos` `tan` `ln` `exp` `sqrt` `abs` |
|
||||
| 四则、幂 | `+ - * / ^` |
|
||||
| 化简 / 展开 | 合并同类项、基本三角恒等(小集合) |
|
||||
| 求导 | 单变元,初等函数求导法则 |
|
||||
| 代入求值 | `subs` → `num` 或公式 |
|
||||
| 求解 | 一元一次 / 二次闭式;其它用数值求根并标明 |
|
||||
|
||||
**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、矩阵、复数完备、任意证明。
|
||||
|
||||
### 3.2 作图(P)
|
||||
|
||||
| 纳入 | 说明 |
|
||||
|------|------|
|
||||
| 显函数 `y=f(x)` | 采样折线 SVG |
|
||||
| 导数曲线 | 对 `formula` 先 `diff` 再画,或 `plot` 选项 `derivative=true` |
|
||||
| 圆锥曲线 | 标准形:圆、椭圆、双曲线、抛物线(参数方程或隐式采样) |
|
||||
| 点列 | `plot_points` |
|
||||
|
||||
**不做:** 三维、隐函数通用求解器、交互缩放(静态 SVG 足够)。
|
||||
|
||||
### 3.3 数值与随机(N)
|
||||
|
||||
常数、四则、三角、对数、取整、`num` 转换、`random` / `random_int` / `seed`(同前稿)。
|
||||
|
||||
---
|
||||
|
||||
## 4. API 草图(对 `formula` 操作)
|
||||
|
||||
### 4.1 构造与数值
|
||||
|
||||
| 英文 | 中文 | 要点 |
|
||||
|------|------|------|
|
||||
| `formula` | `公式` | 文本 → formula |
|
||||
| `pi` `e` | `圆周率` `自然底数` | → num |
|
||||
| `add`… / `sin`… | `加`… / `正弦`… | 对 num;若传入 formula 则返回 formula(符号)或报错——**v1 建议:算术函数只接 num;符号用 simplify/diff/subs** |
|
||||
| `eval` | `求值` | `formula` + 变量赋值 → num |
|
||||
| `random` / `random_int` / `seed` | `随机` / `随机整数` / `设种子` | 见前 |
|
||||
|
||||
### 4.2 符号
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `simplify` | `化简` | `formula` | formula |
|
||||
| `expand` | `展开` | `formula` | formula |
|
||||
| `diff` | `求导` | `formula`, `var` | formula |
|
||||
| `subs` | `代入` | `formula`, `var`, `value` | formula 或 num |
|
||||
| `solve` | `求解` | `formula`, `var`,可选区间 | list(num 或公式根) |
|
||||
|
||||
### 4.3 作图
|
||||
|
||||
| 英文 | 中文 | 形参 |
|
||||
|------|------|------|
|
||||
| `plot` | `绘图` | **`formula`**(或 `expr` 文本), `var`, `min`, `max`;可选 `steps`, `path`, `derivative`, **`grid`**(默认开;`False`/`假` 关) |
|
||||
| `plot_conic` | `绘圆锥` | `kind`(circle/ellipse/hyperbola/parabola)+ 系数;可选 `path`, `grid` |
|
||||
| `plot_points` | `绘点列` | `xs`, `ys`;可选 `path`, `grid` |
|
||||
|
||||
返回 **SVG 文本**;坐标轴带箭头与刻度,默认网格;写文件与 view 嵌入规则同前(§5)。
|
||||
|
||||
`diff` / `simplify` / `expand` / 未完全数值化的 `subs` 返回 **`formula`**,可继续链式调用。
|
||||
|
||||
示例:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*`roots` = > solve formula=`f` var=x *
|
||||
|
||||
> print text=`roots`
|
||||
|
||||
*`svg` = > plot formula=`f` var=x min=-3 max=3 path=parabola.svg *
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 作图:CLI / view / 静态(不变精神)
|
||||
|
||||
| 场景 | 行为 |
|
||||
|------|------|
|
||||
| 带 `path=` | 写 SVG 到该路径(沙箱内) |
|
||||
| CLI 无 path | 自动 `{stem}-plot-{n}.svg` + 一行 `plot: …` |
|
||||
| view / 导出无 path | 不强制写盘;加入 **plots 产物列表**,Execution 内嵌 |
|
||||
| view / 导出有 path | 写盘 + 内嵌 |
|
||||
|
||||
不把整段 SVG 默认灌进 CLI stdout。
|
||||
|
||||
---
|
||||
|
||||
## 6. 分期
|
||||
|
||||
| 期 | 交付 |
|
||||
|----|------|
|
||||
| **M1** | `Num` + 数值/随机;`Formula` AST + `` `name` = `` + `$$…$$` 赋值绑定 |
|
||||
| **M2** | `simplify` / `diff` / `subs` / `eval` / 二次 `solve`(高中子集) |
|
||||
| **M3** | `plot` / `plot_points` / `plot_conic` + view 内嵌 + path 写盘 |
|
||||
| **M4** | 用户文档 `public/stdlib/math*` · 金样例 · mapping 文档补丁 |
|
||||
|
||||
M1–M3 可在同一发版列车上连续落地;验收以「公式赋值 → 求导 → 作图」一条龙为准。
|
||||
|
||||
---
|
||||
|
||||
## 7. 实现要点
|
||||
|
||||
```text
|
||||
src/formula/ # 词法/AST/化简/求导/求值(高中规则表)
|
||||
src/host/math.rs # 数值、随机、对 formula 的 host 入口
|
||||
src/host/plot.rs # SVG
|
||||
lex/parse:空 RHS 赋值 + $$ 围栏 → Expr::Formula
|
||||
Value::Num / Value::Formula
|
||||
Interpreter.plots: Vec<String>
|
||||
lib/math.mq.md · lib/数学.mq.md
|
||||
```
|
||||
|
||||
依赖:纯 Rust;不绑 SymPy。公式复杂度、采样点、SVG 大小设硬上限。
|
||||
|
||||
---
|
||||
|
||||
## 8. 刻意不做
|
||||
|
||||
- `$$:name` 模块级具名绑定(已废除)。
|
||||
- 无名 `$$` 自动进运行时。
|
||||
- 大学级数 / 完备积分 / 定理证明。
|
||||
- 通用隐函数作图引擎。
|
||||
- 3D、交互式图表库。
|
||||
|
||||
---
|
||||
|
||||
## 9. 验收
|
||||
|
||||
1. `` `f` = `` + `$$…$$` + `diff` / `solve` / `plot` 金样例(中英库)。
|
||||
2. 固定 `seed` 的随机金样例。
|
||||
3. `plot` + `path` 在 CLI 落盘;view HTML 含 `<svg`。
|
||||
4. `type` 对公式为 `formula`,对浮点为 `num`。
|
||||
5. view Structure 将公式赋值显示为绑定,而非 comment。
|
||||
|
||||
---
|
||||
|
||||
## 10. 一句话
|
||||
|
||||
**`` `f` = `` + `$$…$$` 产出 `formula` 值;数学库对它做高中范围的符号运算、求解与作图——数值与随机并行,图在 view 内嵌、在 CLI 写文件。**
|
||||
@@ -1,181 +0,0 @@
|
||||
# 标准库 L1 模块
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本与可选原生扩展。标准库**必须导入**才可用。
|
||||
|
||||
| 模块族 | 英文库 | 中文库 | 状态 |
|
||||
|--------|--------|--------|------|
|
||||
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
|
||||
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有 |
|
||||
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 |
|
||||
| 系统 | `lib/sys.mq.md` | `lib/系统.mq.md` | 已有(含 `load_dotenv`) |
|
||||
| 时间 | `lib/time.mq.md` | `lib/时间.mq.md` | 已有 |
|
||||
| JSON | `lib/json.mq.md` | **同文件** | 已有(含 `quote`) |
|
||||
| 网络 | `lib/net.mq.md` | `lib/网络.mq.md` | 已有(HTTPS + headers) |
|
||||
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | 已有 |
|
||||
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | 已有 |
|
||||
| **插件** | `lib/plugin.mq.md` | `lib/插件.mq.md` | **已有**(加载 C ABI 共享库) |
|
||||
| **自写回** | `lib/writeback.mq.md` | `lib/自写回.mq.md` | **已有**(Jupyter 式输出写回) |
|
||||
| **子任务** | `lib/subtask.mq.md` | `lib/子任务.mq.md` | **已有**(OS 子进程 + KillOnDrop) |
|
||||
|
||||
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` — 见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
设计细节:[stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层与实现分工
|
||||
|
||||
```text
|
||||
用户 .mq.md
|
||||
│ > lib/fs.mq.md / > ext/llm.mq.md
|
||||
▼
|
||||
L1 官方库 / 官方 ext(.mq.md)
|
||||
│
|
||||
▼
|
||||
L0.5 宿主原语(Rust)或 原生插件(ABI v1)
|
||||
│
|
||||
▼
|
||||
OS / HTTP / 时钟 / 共享库 …
|
||||
```
|
||||
|
||||
| 层 | 谁实现 | 用户是否直接调用 |
|
||||
|----|--------|------------------|
|
||||
| **L0** | 解释器内置 | 是(`print`/`len`/…) |
|
||||
| **L0.5 宿主原语** | Rust(`src/host/`) | **原则上否**;供 L1 包装 |
|
||||
| **L1 官方库** | `lib/*.mq.md` | **是** |
|
||||
| **官方 ext** | `ext/*.mq.md`(+ 可选 ABI 插件) | **是**(需显式导入 `ext/`) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心模块 API(摘要)
|
||||
|
||||
文件 / 系统 / 时间 / JSON / 网络 API 见下文历史草图(已实现)。补充:
|
||||
|
||||
### 3.2 系统 — 已含 dotenv
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `load_dotenv` | `加载环境` | 可选 `path` | 新写入的键数量;缺文件 → `0`;不覆盖已有环境变量 |
|
||||
|
||||
### 3.4 JSON — 已含 `quote`
|
||||
|
||||
| 函数 | 形参 | 结果 |
|
||||
|------|------|------|
|
||||
| `quote` | `text` | JSON 字符串字面量(含引号) |
|
||||
|
||||
### 3.5 网络 — HTTPS
|
||||
|
||||
仅 **HTTP / HTTPS**(ureq);可选 `headers=`(map)、`content_type=`。
|
||||
|
||||
### 3.6 插件 — `plugin` / `插件`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `load` | `加载` | `path` / `路径` | 注册函数个数 |
|
||||
| `unload` | `卸载` | (无) | `None` |
|
||||
| `list` | `列出` | (无) | 已注册名列表 |
|
||||
|
||||
契约:[ext-abi.md](ext-abi.md)。路径受 cwd/fs_root 沙箱约束。
|
||||
|
||||
### 3.1–3.5 历史 API 草图
|
||||
|
||||
#### 文件 — `fs` / `文件`
|
||||
|
||||
| 英文 | 中文 | 形参(英 / 中) | 结果 |
|
||||
|------|------|-----------------|------|
|
||||
| `read_text` | `读文本` | `path` / `路径` | 文本 |
|
||||
| `write_text` | `写文本` | `path`, `text` / `路径`, `内容` | `None` |
|
||||
| `append_text` | `追加文本` | 同上 | `None` |
|
||||
| `exists` | `存在` | `path` / `路径` | 布尔 |
|
||||
| `list_dir` | `列目录` | `path` / `路径` | 文本列表 |
|
||||
| `make_dir` | `建目录` | `path` / `路径` | `None` |
|
||||
| `remove` | `删除` | `path` / `路径` | `None` |
|
||||
|
||||
#### 系统 — `sys` / `系统`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `env_get` | `取环境` | `name` / `名` | 文本或 `None` |
|
||||
| `env_set` | `设环境` | `name`, `value` / `名`, `值` | `None` |
|
||||
| `load_dotenv` | `加载环境` | 可选 `path` | 见上 |
|
||||
| `args` | `参数表` | (无) | 文本列表 |
|
||||
| `cwd` | `工作目录` | (无) | 文本 |
|
||||
| `exit` | `退出` | `code` / `码` | 不返回 |
|
||||
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码 |
|
||||
|
||||
#### 时间 — `time` / `时间`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `now_unix` | `此刻秒` | (无) | 整数(Unix 秒) |
|
||||
| `now_ms` | `此刻毫秒` | (无) | 整数 |
|
||||
| `format` | `格式化` | `unix`, `pattern` / `秒`, `格式` | 文本 |
|
||||
| `sleep_ms` | `睡眠毫秒` | `ms` / `毫秒` | `None` |
|
||||
| `parse` | `解析时间` | `text`, `pattern` / `内容`, `格式` | 整数秒或诊断失败 |
|
||||
|
||||
#### JSON — `json`
|
||||
|
||||
| 函数 | 形参 | 结果 |
|
||||
|------|------|------|
|
||||
| `parse` | `text` | 值 |
|
||||
| `stringify` | `value`, 可选 `indent` | JSON 文本 |
|
||||
| `get` | `value`, `key` | 值或 `None` |
|
||||
| `keys` | `value` | 文本列表 |
|
||||
| `quote` | `text` | JSON 字符串字面量 |
|
||||
|
||||
#### 网络 — `net` / `网络`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `http_get` | `获取` | `url` / `地址` | 响应文本 |
|
||||
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` / `headers` | 同上 |
|
||||
| `url_encode` | `编码地址` | `text` / `内容` | 文本 |
|
||||
|
||||
**路径字面量:** 具名实参里 `path=a/b` 会被解析成除法。请用无斜杠文件名,或先赋给变量再传入。
|
||||
|
||||
---
|
||||
|
||||
## 4. 中英路径总表
|
||||
|
||||
```text
|
||||
lib/
|
||||
text.mq.md / 文本.mq.md
|
||||
table.mq.md / 表.mq.md
|
||||
fs.mq.md / 文件.mq.md
|
||||
sys.mq.md / 系统.mq.md
|
||||
time.mq.md / 时间.mq.md
|
||||
json.mq.md # 中英共用
|
||||
net.mq.md / 网络.mq.md
|
||||
math.mq.md / 数学.mq.md
|
||||
foreign.mq.md / 外联.mq.md
|
||||
plugin.mq.md / 插件.mq.md
|
||||
|
||||
ext/ # 非 stdlib
|
||||
llm.mq.md / 大模型.mq.md
|
||||
agent.mq.md / 智能体.mq.md
|
||||
```
|
||||
|
||||
别名:`std/…` ≡ `lib/…`。扩展解析:`MARQDO_EXT` / `./ext` / 二进制旁 `ext/`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 安全与 view / 静态导出
|
||||
|
||||
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**。差异仅在软退出 / sleep 钳制。相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。插件路径同沙箱。
|
||||
|
||||
---
|
||||
|
||||
## 6. 一句话
|
||||
|
||||
**L1 含文件 / 系统 / 时间 / JSON / 网络 / 数学 / 外联 / 插件;`ext/` 为可选官方扩展(llm、agent)。**
|
||||
@@ -1,25 +0,0 @@
|
||||
# 子任务标准库(subtask)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | v2 |
|
||||
| 库 | `lib/subtask.mq.md` · `lib/子任务.mq.md` |
|
||||
|
||||
## 定位
|
||||
|
||||
**并发**执行单元。`spawn` 四选一:
|
||||
|
||||
| 参数 | 执行方式 | `join` 返回值 |
|
||||
|------|----------|---------------|
|
||||
| `path=` | `marqdo run <file>` 子进程 | 退出码 `Int` |
|
||||
| `fn=` + 可选 `args=` | 当前入口模块中的函数(进程内线程) | 函数返回值 `Value` |
|
||||
| `code=` | 外联代码块(`Value::Code`)子进程 | stdout `Text` |
|
||||
| `lang=` + `source=` | 外联源码子进程 | stdout `Text` |
|
||||
|
||||
`args=`:文件子任务为 `List`(命令行参数);函数子任务为 `Map`(形参绑定)或 `List`(按 `arg0`… 命名)。
|
||||
|
||||
父进程结束(含 panic)时 **KillOnDrop** 终止所有文件/外联子进程;函数线程标记为 killed 并 detach(无法强杀 OS 线程)。
|
||||
|
||||
`poll` → `{ status: running | done | failed, … }`;函数 done 时含 `value`,进程/外联 failed 时含 `code` 或 `error`。
|
||||
|
||||
Host:`host_subtask_*`(`src/host/subtask.rs`)。
|
||||
@@ -1,36 +0,0 @@
|
||||
# 自写回标准库(writeback)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | v1 已落地 |
|
||||
| 库 | `lib/writeback.mq.md` · `lib/自写回.mq.md` |
|
||||
|
||||
## 定位
|
||||
|
||||
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` 的 `<!-- marqdo-out … -->` → `marqdo view` 在对应语句下显示 **output-card**。普通 Markdown 预览不显示该区域。
|
||||
|
||||
## 存储格式
|
||||
|
||||
```markdown
|
||||
*`n` = > len value=`xs` *
|
||||
<!-- marqdo-out
|
||||
42
|
||||
-->
|
||||
```
|
||||
|
||||
- 注释内仅保留 `marqdo-out` 标识,**不存行号**(避免写回后行号漂移)
|
||||
- 默认在**调用行下方**插入或替换紧邻块(中间可有空行)
|
||||
- `at_end=true` / `末尾=true`:在文件末尾保留单块(替换已有末尾块)
|
||||
|
||||
## API
|
||||
|
||||
| EN | ZH | 说明 |
|
||||
|----|-----|------|
|
||||
| `record` | `写回` | `value=`,可选 `at_end=false` |
|
||||
| `get` | `取` | 可选 `at_end=false` |
|
||||
| `clear` | `清除` | 可选 `at_end=false` |
|
||||
| `list` | `列出` | 全文所有输出块(含推断锚点行) |
|
||||
|
||||
可选参数语法:`` + `参数名`=默认值 ``(与现有参数列表兼容)。
|
||||
|
||||
Host:`host_writeback_*`(`src/host/writeback.rs`)。
|
||||
@@ -1,104 +0,0 @@
|
||||
# 标准库(P2)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **S0–S3 + L1 全模块落地** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-abi.md](ext-abi.md) |
|
||||
|
||||
> **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。
|
||||
> **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
> **`ext/` 不是 stdlib**:官方可选扩展见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 分层
|
||||
|
||||
| 层 | 内容 |
|
||||
|----|------|
|
||||
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at`(`type` 可含 `map`) |
|
||||
| **L1 官方库** | 仓库根目录 [`lib/`](../../lib/)(`.mq.md`);可用 `lib/…` 或别名 `std/…` 导入 |
|
||||
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1 |
|
||||
| **L2** | catalog / 用户站收录(随发版) |
|
||||
|
||||
---
|
||||
|
||||
## 2. 内置一览(S0 + S1)
|
||||
|
||||
| 名 | 形参 | 结果 |
|
||||
|----|------|------|
|
||||
| `len` | `value` | 文本标量数或列表长度 |
|
||||
| `str` | `value` | 显示文本 |
|
||||
| `int` | `value` | 整数(失败 → 诊断) |
|
||||
| `type` | `value` | `none`/`bool`/`int`/`text`/`list`/`map` |
|
||||
| `trim` | `value` | 去首尾空白 |
|
||||
| `split` | `value`, `sep` | 文本列表 |
|
||||
| `join` | `value`, `sep` | 拼接文本 |
|
||||
| `at` | `value`, `index` | 列表下标(越界 → `None`) |
|
||||
|
||||
表(单列表格)在运行时是 `list`:行数用 `len`,取行用 `at`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 官方库导入(S2)
|
||||
|
||||
Frontmatter:
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/text.mq.md
|
||||
> lib/table.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
`std/text.mq.md` 等价于 `lib/text.mq.md`。解析顺序:
|
||||
|
||||
1. 相对当前文件
|
||||
2. `MARQDO_LIB`(可指向 `lib` 目录或仓库根)
|
||||
3. 当前工作目录的 `lib/`
|
||||
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
|
||||
5. **内嵌 stdlib**(v0.1.2+,编译进二进制;无磁盘 `lib/` 时自动使用)
|
||||
|
||||
当前模块(API 多为 `##` 自由函数;见 [objects.md](objects.md)):
|
||||
|
||||
| 路径 | 导出 |
|
||||
|------|------|
|
||||
| `lib/fs.mq.md` / `lib/文件.mq.md` | `read_text`… / `读文本`… |
|
||||
| `lib/time.mq.md` / `lib/时间.mq.md` | `now_unix`… / `此刻秒`… |
|
||||
| `lib/sys.mq.md` / `lib/系统.mq.md` | `env_get`…、`load_dotenv`… / `取环境`…、`加载环境`… |
|
||||
| `lib/json.mq.md` | `parse` `stringify` `get` `keys` `quote`(中英同文件) |
|
||||
| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`…(HTTPS)/ `获取`… |
|
||||
| `lib/math.mq.md` / `lib/数学.mq.md` | 数值 / 随机 / 公式 / 绘图 |
|
||||
| `lib/foreign.mq.md` / `lib/外联.mq.md` | 具名围栏外联 |
|
||||
| `lib/plugin.mq.md` / `lib/插件.mq.md` | `load` / `unload` / `list`(原生 ABI) |
|
||||
| `lib/writeback.mq.md` / `lib/自写回.mq.md` | `record` `get` `clear` `list` |
|
||||
| `lib/subtask.mq.md` / `lib/子任务.mq.md` | `spawn` `poll` `wait` `kill` `wait_all` |
|
||||
| `lib/text.mq.md` | `str_trim` `str_split` `str_join` |
|
||||
| `lib/文本.mq.md` | `去空白` `拆分` `拼接` |
|
||||
| `lib/table.mq.md` | `rows` `row_at` |
|
||||
| `lib/表.mq.md` | `行数` `取行` |
|
||||
|
||||
完整清单见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 转换错误约定(S3)
|
||||
|
||||
用户可见失败统一为:
|
||||
|
||||
```text
|
||||
path:line:col: message
|
||||
```
|
||||
|
||||
内置转换相关文案(稳定子集,金样例断言):
|
||||
|
||||
| 情况 | message |
|
||||
|------|---------|
|
||||
| 非法整数文本 | `cannot convert to int: "…"` |
|
||||
| `int` 类型不对 | `int needs int, bool, or text` |
|
||||
| `len` 类型不对 | `len needs text or list` |
|
||||
| `trim` 非文本 | `trim needs text` |
|
||||
| `split`/`join` 参数类型 | `split needs text value` 等 |
|
||||
| 空分隔符 | `split sep must not be empty` |
|
||||
|
||||
不引入独立异常类型对象;一律走 `Diagnostic`。
|
||||
@@ -1,152 +0,0 @@
|
||||
# 参考实现:技术选型分析(尚未拍板)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **分析中 — 未定案** |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 说明 | 对比候选与约束;**不在本文直接开写实现仓库脚手架** |
|
||||
|
||||
上一版曾草率写「就用 TypeScript」——信息不足,已作废为定论。本文只做选型框架与对比,**最终实现语言须单开 ADR 确认后再动工。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 我们在选什么
|
||||
|
||||
参考实现至少包含:
|
||||
|
||||
1. **读入** `.mq.md`(含 frontmatter 混合行)
|
||||
2. **对齐 GFM** 的结构:标题、列表(`-`/`+`/`1.`)、强调、表格、围栏、链接
|
||||
3. **Lower**:行首判别、标题树作用域、列表符语义、注释剥离
|
||||
4. **两遍**:收集定义 + 导入 → 求值
|
||||
5. **CLI** + **金样例测试**(`tests/`)
|
||||
|
||||
可选后期:字节码/编译、LSP、格式化。首版目标是**验证语法宪法**,不是上生产编译器。
|
||||
|
||||
---
|
||||
|
||||
## 2. 选型准则(按权重)
|
||||
|
||||
| 权重 | 准则 | 说明 |
|
||||
|------|------|------|
|
||||
| 高 | GFM 忠实度 | 表格、列表符、强调边界与 GitHub 预览一致,减少「能渲染不能跑 / 能跑不能渲染」 |
|
||||
| 高 | 与宪法同构 | 易于表达「先 mdast/事件流,再 Marqdo AST」 |
|
||||
| 高 | 测试与迭代速度 | 改语法宪法时能快速改测试 |
|
||||
| 中 | 静态类型 / 可维护 AST | 长期改解释器不疼 |
|
||||
| 中 | CLI 与打包 | 单二进制或 `npx`/等价体验 |
|
||||
| 低 | 极致性能 | v0 样例很小 |
|
||||
| 低 | 浏览器内运行 | 可后置 |
|
||||
|
||||
非准则:跟风、先写再选、与「生成 OKF」强绑某一云厂商。
|
||||
|
||||
---
|
||||
|
||||
## 3. 架构共性(与语言无关)
|
||||
|
||||
无论选哪门实现语言,流水线应一致:
|
||||
|
||||
```
|
||||
.mq.md 文本
|
||||
→ 前端:GFM 友好解析(或事件扫描)
|
||||
→ Middle:Marqdo lower(行类、标题树、- / +、表、围栏)
|
||||
→ Marqdo AST
|
||||
→ 语义:导入图、提升、作用域
|
||||
→ 后端:解释器(v0)/日后编译
|
||||
→ 测试:tests 金样例 → 期望 stdout
|
||||
```
|
||||
|
||||
**前端可复用成熟 GFM 库,也可自研**;Middle/后端必须自研(这是语言本体)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 候选对比
|
||||
|
||||
### A. TypeScript / Node + remark(mdast)
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| remark-gfm 与预览器语义接近;mdast 节点齐全 | 运行时依赖 Node;发行 CLI 需打包 |
|
||||
| 迭代快、Vitest 方便 | 性能与「系统级编译器」形象偏软 |
|
||||
| 与 Markdown 工具链同生态 | 需纪律:避免把业务写进插件泥潭 |
|
||||
|
||||
**适合:** 验证宪法、快速金样例。
|
||||
**不自动等于最终生产编译器。**
|
||||
|
||||
### B. Rust + pulldown-cmark / comrak
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| 单静态二进制、性能好、适合日后正式编译器 | GFM 表格/细节与 GitHub 仍可能有差异,要对齐测试 |
|
||||
| 类型与代数数据类型适合 AST | 前期迭代比 TS 慢 |
|
||||
| 无 GC、可嵌入 | MD 生态碎片,选库要论证 |
|
||||
|
||||
**适合:** 中长期「真编译器」或与 TS 原型双轨。
|
||||
**风险:** 首版就上 Rust 可能拖慢语法验证。
|
||||
|
||||
### C. Python + markdown-it-py / mistune
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| 原型极快 | 类型与工程化偏弱;双实现时易弃 |
|
||||
| 文本处理友好 | 打包 CLI 体验一般 |
|
||||
|
||||
**适合:** 一次性语法实验。
|
||||
**不推荐**作为唯一长期实现,除非团队强约束。
|
||||
|
||||
### D. Go + goldmark
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| 单二进制、部署简单 | 泛型/AST 表达力一般;MD 库选 goldmark 需 GFM 扩展评估 |
|
||||
| 并发与工具链成熟 | 与 MD 研究生态联系弱于 JS |
|
||||
|
||||
**适合:** 工具型 CLI 优先的团队。
|
||||
|
||||
### E. 自研扫描器(任意语言)+ 仅用 GFM 做对照测试
|
||||
|
||||
| 利 | 弊 |
|
||||
|----|----|
|
||||
| 完全控制行首判别与 `+`/`-` 语义 | 重复实现表格/强调,易与渲染不一致 |
|
||||
| 可强制「行分类优先于块解析」 | 工作量大 |
|
||||
|
||||
**适合:** 证明「行首判别」与 CommonMark 块结构冲突时的研究分支。
|
||||
可与 A/B 组合:自研 lower,块结构仍喂给现成解析器。
|
||||
|
||||
---
|
||||
|
||||
## 5. 关键技术风险(与选语言正交)
|
||||
|
||||
1. **行首判别 vs 块解析器** — CommonMark 先成块再看内容;Marqdo 先看行类。可能需「行预分类再喂解析器」或「解析后按源位置重分类」。选型时要让候选语言/库能拿到**源行映射**。
|
||||
2. **frontmatter 非纯 YAML** — `>` 导入行是扩展;不能整块丢给严格 YAML 解析器。
|
||||
3. **`+` 与 `-` 列表** — 多数解析器都认,但 lower 必须保留**项目符字符**,不能只得「unordered list」。选库时验证 AST 是否保留 bullet type。
|
||||
4. **`*` else vs `*返回*` vs 强调** — 依赖 inline 解析与「整行恰好一个 `*`」的行级规则并存。
|
||||
|
||||
以上 4 点应作为**选型验收用例**,写进 ADR:用最小样例在候选栈上 Spike,再定案。
|
||||
|
||||
---
|
||||
|
||||
## 6. 建议的决策流程(尚未执行)
|
||||
|
||||
1. **Spike(各 ≤0.5–1 日)**
|
||||
- 候选 A:TS + remark-gfm — 能否区分 `-`/`+` bullet、解析单列表格、读 strong/emphasis。
|
||||
- 候选 B:Rust + comrak/pulldown — 同上。
|
||||
- (可选)C 或 D 若团队有偏好再做。
|
||||
2. **对照验收用例**(固定):`tests/structure/hello.mq.md`、`branch.mq.md`(`+`)、`collection.mq.md`(表)、含 `> x.mq.md` 的 frontmatter 行。
|
||||
3. **出 ADR**:选定「验证期实现」与(可选)「生产目标实现」是否同一语言。
|
||||
4. **再**建仓库脚手架与测试——禁止在 ADR 前默认生成 `package.json` / `Cargo.toml` 当既成事实。
|
||||
|
||||
---
|
||||
|
||||
## 7. 当前态度(非正式投票)
|
||||
|
||||
| 阶段 | 倾向(待 Spike 验证) |
|
||||
|------|------------------------|
|
||||
| 语法验证期 | 更可能是 **TypeScript + remark**(快、GFM 近) |
|
||||
| 长期生产编译器 | **开放** Rust / Go,不与验证期绑定 |
|
||||
|
||||
**本文不授权开始实现。** 确认 Spike 计划或直接指定语言后,再写 `adr/0001-implementation-language.md`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 与「无标记 = 注释」的关系
|
||||
|
||||
实现必须先做**行分类**(见 [code-vs-comment.md](code-vs-comment.md)),再谈用何种语言写分类器。选型不能假设「整文件都是可执行代码」。
|
||||
@@ -1,66 +0,0 @@
|
||||
# 用户静态文档站(public / gh-pages)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [view.md](view.md) · 源目录 [`public/`](../../public/) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 分工
|
||||
|
||||
| 路径 | 是否入库 | 职责 |
|
||||
|------|----------|------|
|
||||
| `doc/` | 是 | 开发者设计 / ADR / 路线图(单数 `doc`,勿再造 `docs/`) |
|
||||
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / **stdlib** / 特性迭代);**双语**:拉丁文件名 = 英文,中文文件名 = 中文编程,同目录并列。stdlib 含 `plugin`;特性页覆盖对象与 `ext/`(llm / agent) |
|
||||
| `public/index.html`、`public/pages/` | **否**(ignore) | `marqdo view output` 生成的 HTML |
|
||||
| `tests/{structure,keywords,errors}/` | 是 | 金样例与失败夹具(含 errors) |
|
||||
| 远程分支 `gh-pages` | 发布产物 | 发布整个 `public/`(源文件 + 生成 HTML) |
|
||||
|
||||
**禁止**把 `tests/errors/` 编进用户站。
|
||||
|
||||
---
|
||||
|
||||
## 2. 生成
|
||||
|
||||
```bash
|
||||
cargo run --release -- view output public -o public
|
||||
# 或
|
||||
./scripts/build-public.sh
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
产物写在源旁:
|
||||
|
||||
```
|
||||
public/
|
||||
*.mq.md / structure/ / … # 入库源
|
||||
index.html # 生成(ignore)
|
||||
pages/… # 生成(ignore)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 发布分支
|
||||
|
||||
将构建后的 `public/` 推到 **`gh-pages`**。CI:`.github/workflows/pages.yml`。
|
||||
|
||||
仓库 Settings → Pages → Source = Deploy from branch → `gh-pages` / root。
|
||||
|
||||
---
|
||||
|
||||
## 4. 内容分层(用户站)
|
||||
|
||||
| 目录 | 内容 |
|
||||
|------|------|
|
||||
| `public/stdlib/` | L1 模块页(含 `plugin` / `插件`);概述注明 `ext/` 非 stdlib |
|
||||
| `public/features/` | 迭代特性:树遍历、字节码、view、**对象**、**官方扩展** |
|
||||
|
||||
设计文档仍在 `doc/design/`(`objects.md`、`ext-llm.md`、`ext-abi.md`、`ext-agent.md`)。
|
||||
|
||||
## 5. 验收
|
||||
|
||||
1. `public/` 下每个 `.mq.md`(除纯工具模块外)`marqdo run` 退出码 0。
|
||||
2. `view output public -o public` 后首页为欢迎页,侧栏无 errors。
|
||||
3. 主分支跟踪 `public/**/*.mq.md`;不提交 `public/index.html` / `public/pages/`。
|
||||
@@ -1,42 +0,0 @@
|
||||
# View 调试(`marqdo debug`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **v1(独立 debug 页)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [pipeline-debug.md](pipeline-debug.md) |
|
||||
|
||||
## 分工
|
||||
|
||||
| 命令 | 角色 |
|
||||
|------|------|
|
||||
| `marqdo view` | 文档浏览器:Structure + Execution + Source;函数大纲与搜索;**无断点** |
|
||||
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;**仅 live** |
|
||||
|
||||
静态 `gh-pages` / `view output` **不能**真断点。
|
||||
|
||||
## Debug 布局(对齐常见调试器)
|
||||
|
||||
参考 VS Code / Chrome DevTools / Jupyter debugger:
|
||||
|
||||
```
|
||||
┌ Toolbar: Start · Continue (F5) · Step (F10) · Stop · status ─┐
|
||||
├ Files ─┬─ Structure (gutter BP) + outline ─┬─ Variables ┤
|
||||
│ │ ├─ Breakpoints │
|
||||
│ │ └─ Call stack │
|
||||
├────────┴────────────────────────────────────┴────────────────┤
|
||||
│ Debug Console (session stdout) │
|
||||
└──────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
- 暂停粒度:语句起点(树遍历)。
|
||||
- 无断点时 Start 停在第一句。
|
||||
- Structure 为断点面(非 Source 行)。
|
||||
|
||||
## API
|
||||
|
||||
与此前相同:`POST /api/debug/start|continue|step|stop|breakpoints`(仅 debug 服务)。
|
||||
|
||||
## View 大纲
|
||||
|
||||
Structure 旁(或窄屏下方)函数树:`#fn-{line}` 锚点 + 搜索框过滤 `data-fn` / `data-fn-path`。
|
||||
@@ -1,116 +0,0 @@
|
||||
# `marqdo view` — 源结构浏览器与静态文档导出
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.0.2 方向) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
`.mq.md` 既是文档也是程序。需要:
|
||||
|
||||
1. **本地浏览**:按 AST 展示结构 + 执行结果;
|
||||
2. **静态导出**:同一套渲染写成 HTML,作为**用户文档站点**(勿手写第二套站点);
|
||||
3. **启动快**:样式极简,无外链字体/厚主题,避免 view 冷启动慢。
|
||||
|
||||
---
|
||||
|
||||
## 2. 视觉(Apple HIG / Docs 极简)
|
||||
|
||||
对齐 [Apple HIG](https://developer.apple.com/design/human-interface-guidelines) 的 **clarity / deference / white space**,并参考常见 docs 布局(sticky 侧栏 + 居中主栏,见 Nextra / Docusaurus 类站点):**系统灰底、白内容面、浅分隔线、系统字体**。作者站 [id.cflmy.cn](https://id.cflmy.cn) 仍作克制感参考,但不强行纯黑描边。
|
||||
|
||||
| 规则 | 要求 |
|
||||
|------|------|
|
||||
| 色板 | 页底 `#f5f5f7`;内容面 `#ffffff`;正文 `#1d1d1f`;次要字 `#6e6e73`;分隔 `#d2d2d7`;选中侧栏项反白 |
|
||||
| 布局 | 壳层 `max-width ≈ 1680px`;侧栏 ≈280px;主内容 `max-width ≈ 76rem`;Structure 旁函数大纲;**≤800px 侧栏收起** |
|
||||
| 默认页 | 打开目录时 **直接展示排序后的第一个 `.mq.md`**(实时 `/` 与静态 `index.html` 同),不要求用户先从欢迎页点选 |
|
||||
| 字体 | 仅系统栈:`-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif`;等宽 `ui-monospace, SFMono-Regular, Menlo, Consolas, monospace` |
|
||||
| 外链 | **禁止** Google Fonts / CDN 样式;CSS 全部内联于 HTML |
|
||||
| 装饰 | 无多层阴影、无渐变、无发光;圆角 ≈12px;结构区为分组列表(底部分隔),非堆叠厚卡片 |
|
||||
| 诊断路径 | 展示时去掉 Windows `\\?\` 前缀,并优先用相对 view 根的路径 |
|
||||
|
||||
验收:首屏无外网字体请求;宽屏主栏明显宽于早期 `58rem` 方案(现约 `76rem` / 壳 `1680px`)。
|
||||
|
||||
---
|
||||
|
||||
## 3. CLI
|
||||
|
||||
### 3.1 实时浏览
|
||||
|
||||
```bash
|
||||
marqdo view [PATH] [--port PORT] [--host HOST] [--no-open]
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | `.mq.md` 或目录 |
|
||||
| `--port` | `7429` | |
|
||||
| `--host` | `127.0.0.1` | |
|
||||
| `--no-open` | 关 | 不打开浏览器 |
|
||||
|
||||
### 3.2 静态导出(文档生成)
|
||||
|
||||
```bash
|
||||
marqdo view output [PATH] -o OUT_DIR [--no-exec]
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 与 `view` 相同扫描范围 |
|
||||
| `-o` / `--out` | (必填) | 输出目录(不存在则创建) |
|
||||
| `--no-exec` | 关 | 不跑程序,执行区显示「skipped」 |
|
||||
|
||||
**产物布局:**
|
||||
|
||||
```
|
||||
OUT_DIR/
|
||||
index.html # 默认 = 排序后第一个 .mq.md 的完整页(侧栏高亮该项)
|
||||
pages/
|
||||
<相对路径>.html # 每个 .mq.md 一页;路径中的 `/` 保留为子目录
|
||||
# 例:structure/hello.mq.md → pages/structure/hello.mq.md.html
|
||||
```
|
||||
|
||||
- 页内链接一律**相对路径**,可用任意静态服务器或 `file://`(同目录结构下)打开。
|
||||
- 用户文档推荐流程:`marqdo view output public -o public`,将生成物发布到 `gh-pages`(见 [user-site.md](user-site.md))。
|
||||
- **执行权限**:与 `marqdo run` 一致(导入即用);view/导出仅对 `exit`/`sleep` 做软化,避免拖垮进程。详见 [stdlib-modules.md](stdlib-modules.md) §6。
|
||||
- 金样例浏览仍可用:`marqdo view output tests -o /tmp/mq-tests`(含 errors,勿当对外用户站)。
|
||||
- 渲染逻辑与实时 `view` **共用**同一套 HTML 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
|
||||
|
||||
示例:
|
||||
|
||||
```bash
|
||||
marqdo view output public -o public
|
||||
marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 信息架构
|
||||
|
||||
侧栏文件索引 + 主区:结构(AST+注释;旁侧函数大纲可搜索)· 执行 · 源码。表达式为表面语法。
|
||||
**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
|
||||
|
||||
---
|
||||
|
||||
## 5. HTTP(实时模式)
|
||||
|
||||
| 方法 | 路径 | 含义 |
|
||||
|------|------|------|
|
||||
| `GET` | `/` | 默认打开第一个 `.mq.md`(无文件时为空提示) |
|
||||
| `GET` | `/file?path=…` | 单文件页 |
|
||||
| `GET` | `/api/tree` | JSON 树(可选) |
|
||||
|
||||
根目录锁死;拒绝 `..` 逃逸。
|
||||
|
||||
---
|
||||
|
||||
## 6. 验收
|
||||
|
||||
1. 实时 `view`:HIG 风极简、无外链字体、结构与执行正确;打开目录即见首个文件;函数大纲可搜索跳转。
|
||||
2. `view output public -o public`(或临时目录)生成可点的 `index.html`(首文件)与各 `pages/…`。
|
||||
3. 静态页中执行区与 `marqdo run` 一致(未加 `--no-exec` 时);失败诊断路径无 `\\?\`。
|
||||
4. 冷启动无明显外网依赖。
|
||||
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
|
||||
@@ -1,82 +0,0 @@
|
||||
# VS Code 扩展 — 分支与提交约定
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **强制约定**(勿在 `main` 提交扩展源码) |
|
||||
| 扩展分支 | **`vscode-extension`** |
|
||||
| 设计说明 | [vscode-extension.md](vscode-extension.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原则(必读)
|
||||
|
||||
| 分支 | 是否跟踪 `vscode-extension/` |
|
||||
|------|-------------------------------|
|
||||
| **`main`** | **否** — `.gitignore` 含 `/vscode-extension/` |
|
||||
| **`vscode-extension`** | **是** — 扩展唯一源码所在分支 |
|
||||
|
||||
**禁止**在 `main` 上:
|
||||
|
||||
- 删除 `.gitignore` 里的 `/vscode-extension/`
|
||||
- `git add vscode-extension/`
|
||||
- 把扩展目录「合并进 main」以便发版
|
||||
|
||||
发版时从 **`vscode-extension` 分支检出**扩展目录打 VSIX(见 §4),**不是**把扩展提交进 `main`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 日常开发(扩展)
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
git checkout vscode-extension
|
||||
cd vscode-extension && npm ci && npm run compile
|
||||
```
|
||||
|
||||
改语法、CLI 检测、扩展版本 → **只在 `vscode-extension` 分支提交**:
|
||||
|
||||
```bash
|
||||
git add vscode-extension/
|
||||
git commit -m "vscode-extension: <简要说明>"
|
||||
git push origin vscode-extension
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 日常开发(CLI / 语言)
|
||||
|
||||
在 **`main`** 上改 `src/`、`lib/`、`public/`、`tests/` 等;**不要**顺带提交 `vscode-extension/`。
|
||||
|
||||
若本地为了调试 checkout 过扩展目录,工作区里可以有 `vscode-extension/` 文件夹,但应被 ignore,且 **`git status` 不应出现**该目录下文件。
|
||||
|
||||
---
|
||||
|
||||
## 4. 发版(CLI tag + VSIX)
|
||||
|
||||
1. **`main`**:打 tag(如 `v0.1.2`),CI 构建 `marqdo.exe` 等。
|
||||
2. **VSIX**:Release 工作流在 tag 构建时执行:
|
||||
```bash
|
||||
git fetch origin vscode-extension
|
||||
git checkout origin/vscode-extension -- vscode-extension
|
||||
cd vscode-extension && npm ci && npm run compile && npx @vscode/vsce package
|
||||
```
|
||||
3. 本地脚本 `scripts/release-windows.ps1` 同样假定:先 `git checkout origin/vscode-extension -- vscode-extension`(或已在 `vscode-extension` 分支),再打 VSIX。
|
||||
|
||||
扩展版本号与最低 CLI 要求写在 **`vscode-extension/package.json`** 与分支 README,**不要**在 `main` 的 CHANGELOG 里冒充已合并扩展源码。
|
||||
|
||||
---
|
||||
|
||||
## 5. 给 Agent / 协作者
|
||||
|
||||
执行「更新 VS Code 插件」类任务时:
|
||||
|
||||
1. **切到或基于 `vscode-extension` 分支**改 `vscode-extension/**`
|
||||
2. **不要**移除 `main` 上 `.gitignore` 的 `/vscode-extension/`
|
||||
3. **不要**在 `main` 的 release 提交里包含 `vscode-extension/package-lock.json` 等大文件
|
||||
4. 仅需在 `main` 更新时:改 `doc/design/vscode-extension.md`、Release 说明、**本文件** — 指针文档即可
|
||||
|
||||
---
|
||||
|
||||
## 6. 历史说明
|
||||
|
||||
v0.1.2 准备阶段曾误将 `vscode-extension/` 并入 `main`(并删除 ignore),导致推送体积过大。已恢复:**扩展仅 `vscode-extension` 分支**;`main` 只保留本约定与设计指针。
|
||||
@@ -1,31 +0,0 @@
|
||||
# VS Code 扩展(分支指针)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已定分支模型** |
|
||||
| 代码分支 | **`vscode-extension`**(同仓库) |
|
||||
| 目录 | 工作区 `vscode-extension/`(**仅在该分支跟踪;`main` 在 `.gitignore` 忽略**) |
|
||||
| 提交约定 | **[vscode-extension-commit.md](vscode-extension-commit.md)**(必读,避免误提交到 `main`) |
|
||||
|
||||
---
|
||||
|
||||
## 分工(类比 `public` / `gh-pages`)
|
||||
|
||||
| 分支 | 内容 |
|
||||
|------|------|
|
||||
| `main` | Marqdo 语言 / CLI / `public/*.mq.md`;**不**存放扩展实现 |
|
||||
| `vscode-extension` | VS Code 扩展源码、TextMate 语法、VSIX 发版 |
|
||||
| `gh-pages` | 用户站生成 HTML |
|
||||
|
||||
```bash
|
||||
git checkout vscode-extension
|
||||
cd vscode-extension && npm install
|
||||
```
|
||||
|
||||
规范入口(在 **`vscode-extension` 分支**上阅读):
|
||||
|
||||
- `vscode-extension/README.md` — 目标与目录
|
||||
- `vscode-extension/DEVELOPMENT.md` — 日常流程
|
||||
- `vscode-extension/ARCHITECTURE.md` — 与 CLI 边界
|
||||
|
||||
扩展是 CLI 的薄宿主;语法真相仍是 [markdown-mapping.md](markdown-mapping.md)。
|
||||
@@ -1,87 +0,0 @@
|
||||
# 开发环境配置(Rust 参考解释器)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | M0 |
|
||||
| 相关 | [dependencies.md](design/dependencies.md) · [interpreter.md](roadmap/interpreter.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 必备软件
|
||||
|
||||
| 软件 | 要求 | 检查 |
|
||||
|------|------|------|
|
||||
| Rust + Cargo | stable,建议 ≥ 1.81(本机验证过 1.81) | `rustc --version` / `cargo --version` |
|
||||
| Git | 任意近期版本 | `git --version` |
|
||||
|
||||
安装 Rust(若尚未安装):
|
||||
|
||||
- 官方:[https://rustup.rs/](https://rustup.rs/)
|
||||
- Windows:下载 `rustup-init.exe`,按提示安装后**重新打开终端**
|
||||
|
||||
本仓库可选 `rust-toolchain.toml`(钉 1.81.0)。若本机无 `rustup`、但已有匹配的 `rustc`/`cargo`,也可直接开发。
|
||||
|
||||
**不需要:** Flex、Bison、LLVM、Node/npm(实现栈为 Rust)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 获取代码与构建
|
||||
|
||||
```bash
|
||||
git clone https://github.com/cflmy/marqdo.git
|
||||
cd marqdo
|
||||
|
||||
cargo build
|
||||
cargo test
|
||||
cargo run -- run tests/structure/hello.mq.md
|
||||
```
|
||||
|
||||
当前 M0:`run` 会读入文件并明确报错「evaluation not implemented」(脚手架,非静默假成功)。
|
||||
|
||||
> 若 `cargo build` 报 `edition2024` / 过新 crate:仓库已对 `clap` 等做兼容钉扎(见 `Cargo.toml`);请使用附带的 `Cargo.lock`,勿盲目 `cargo update` 到最新 major。
|
||||
|
||||
---
|
||||
|
||||
## 3. 推荐组件
|
||||
|
||||
```bash
|
||||
rustup component add rustfmt clippy # 若使用 rustup
|
||||
cargo fmt
|
||||
cargo clippy --all-targets
|
||||
```
|
||||
|
||||
代理下拉 crate(可选,与 git 推送类似):
|
||||
|
||||
```bash
|
||||
# Windows PowerShell 示例
|
||||
$env:HTTPS_PROXY="http://127.0.0.1:7897"
|
||||
$env:HTTP_PROXY="http://127.0.0.1:7897"
|
||||
cargo build
|
||||
```
|
||||
|
||||
或配置 `%USERPROFILE%\.cargo\config.toml`:
|
||||
|
||||
```toml
|
||||
[http]
|
||||
proxy = "http://127.0.0.1:7897"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. 目录约定
|
||||
|
||||
| 路径 | 含义 |
|
||||
|------|------|
|
||||
| `src/lex` | 行分类 / 词法(自研) |
|
||||
| `src/parse` | 递归下降语法 |
|
||||
| `src/diagnostics` | 诊断 |
|
||||
| `tests/` | 金样例 + 集成测试(`structure` / `keywords` / `errors`) |
|
||||
| `public/` | 用户可执行文档(无 errors) |
|
||||
| `spike/` | 旧 Python 风险探测,非运行时依赖 |
|
||||
| `doc/` | 设计与路线图 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 下一里程碑
|
||||
|
||||
见 [interpreter.md](roadmap/interpreter.md):M1 词法·行分类与最小 AST。
|
||||
@@ -1,215 +0,0 @@
|
||||
# 调研:Google Open Knowledge Format(OKF)与 Marqdo
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 调研笔记 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 对象 | [OKF v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) |
|
||||
| 公告 | [v0.1 介绍](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing) · [v0.2 trust signals](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals) |
|
||||
|
||||
---
|
||||
|
||||
## 1. OKF 是什么
|
||||
|
||||
**Open Knowledge Format(开放知识格式)** 是 Google Cloud 于 2026 年 6 月发布的厂商中立开放规范(Apache 2.0)。它把「LLM Wiki」模式形式化为可移植格式:用**目录树中的 Markdown 文件 + YAML frontmatter** 表示组织知识(表结构、指标、API、操作手册等),供人类与 AI Agent 共同阅读、交换与维护。
|
||||
|
||||
一句话定位:
|
||||
|
||||
> 知识应活在**格式**里,而不是专有服务或散落的非结构化文本里。
|
||||
|
||||
### 核心形态
|
||||
|
||||
```
|
||||
bundle/
|
||||
index.md # 可选:目录索引(渐进披露)
|
||||
log.md # 可选:变更历史
|
||||
concepts/.../*.md # 每个概念一个 Markdown 文件
|
||||
```
|
||||
|
||||
每个概念文件:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: Metric # 唯一必填
|
||||
title: Monthly Active Users
|
||||
description: ...
|
||||
tags: [product, growth]
|
||||
sources: [...] # v0.2:出处
|
||||
generated: {...} # v0.2:谁生成的
|
||||
verified: {...} # v0.2:谁验证的
|
||||
status: stable # v0.2:生命周期
|
||||
stale_after: 2026-12-01 # v0.2:过期日
|
||||
---
|
||||
|
||||
# 正文(自由 Markdown)
|
||||
|
||||
指标定义为……
|
||||
```
|
||||
|
||||
- **Concept ID** = 相对路径去掉 `.md`
|
||||
- **链接** = 普通 Markdown 链接,形成可遍历关系图
|
||||
- **无中心 schema registry**;未知 `type` 必须被优雅降级处理
|
||||
|
||||
### 设计三原则(官方表述)
|
||||
|
||||
1. **Minimally opinionated** — 只强制互通所需的最小公约;其余留给生产者。
|
||||
2. **Producer / consumer independence** — 写知识的人(或 Agent)与读知识的 Agent/工具解耦;格式即契约。
|
||||
3. **Format, not platform** — 不绑定云、数据库、模型或 Agent 框架;`cat` 能读,`git clone` 能分发。
|
||||
|
||||
### v0.2 新增:五类信任信号
|
||||
|
||||
当知识主要由 Agent **持续生成**时,纯 Markdown 不够。v0.2 把下列问题变成 frontmatter 一等字段:
|
||||
|
||||
| 问题 | 机制 |
|
||||
|------|------|
|
||||
| 从何而来? | `sources`(出处 + 可信度信号,不作统一打分) |
|
||||
| 该信多少? | `generated` / `verified` → 推导 trust tier(未验证 / 机器确认 / 人工审核) |
|
||||
| 是否仍真? | `stale_after`(绝对日期,非相对 TTL) |
|
||||
| 是否现行? | `status`: `draft` → `stable` → `deprecated` |
|
||||
| 数字是否按约定算出? | 概念类型 `Attested Computation`:executor 跑计算出 receipt,**非 LLM** 的 attester 核验 |
|
||||
|
||||
---
|
||||
|
||||
## 2. OKF 与 Marqdo:相邻,但不等同
|
||||
|
||||
| 维度 | OKF | Marqdo |
|
||||
|------|-----|--------|
|
||||
| 本质 | **知识交换格式** | **编程语言** |
|
||||
| 文件角色 | 描述资产与概念的文档 | 可执行程序 = 可渲染文档 |
|
||||
| 机器侧 | 解析 metadata、遍历链接、过滤信任 | 解析、类型检查、求值/编译 |
|
||||
| Markdown 地位 | 载体与呈现层 | **语法表层的一部分**(源即 Markdown) |
|
||||
| 成功标准 | 跨组织互通、Agent 可策展 | 严肃编程能力 + 阅读体验同时成立 |
|
||||
|
||||
OKF 回答:「人和 Agent 如何**共享与信任知识**?」
|
||||
Marqdo 回答:「程序如何**本身就是知识**,且仍能运行?」
|
||||
|
||||
因此借鉴应落在**表示哲学与工程约束**,而不是照搬「知识目录」产品形态。
|
||||
|
||||
---
|
||||
|
||||
## 3. 值得借鉴的设计点
|
||||
|
||||
### 3.1 后缀与生态搭便车 — 已采纳
|
||||
|
||||
OKF 坚持「就是 Markdown」:GitHub 渲染、编辑器预览、静态站、搜索索引零摩擦。
|
||||
|
||||
**Marqdo 对应决策:源文件后缀为 `.mq.md`。**
|
||||
|
||||
- `.md` 确保通用 Markdown 渲染器开箱可用
|
||||
- `.mq` 前缀声明这是 Marqdo 源,而非普通文档
|
||||
- 与 OKF「格式优先于平台」一致:可读性不依赖自研 viewer
|
||||
|
||||
### 3.2 最小强制面(Minimally opinionated)
|
||||
|
||||
OKF 只强制 `type`;其余可选,未知字段保留不拒绝。
|
||||
|
||||
**对 Marqdo 的启发:**
|
||||
|
||||
- 语言的「文档面」与「程序面」之间,划清**硬语法**与**散文**
|
||||
- 第一版语法宜小:标题层级、声明、表达式……先钉死互通/可执行最小集
|
||||
- 扩展用约定或可选 frontmatter,避免一上来造完整注解宇宙
|
||||
|
||||
### 3.3 生成式 YAML / OKF 清单 — 已采纳方向(已修正)
|
||||
|
||||
OKF 用 YAML frontmatter 承载「可查询元数据」。Marqdo **借鉴其形态**,但职责不同:
|
||||
|
||||
**YAML(OKF 风格知识包)由工具从 `.mq.md` 自动生成,不是人手写的配置文件。**
|
||||
|
||||
详见 [`design/generated-yaml-manifest.md`](../design/generated-yaml-manifest.md)。
|
||||
|
||||
| | |
|
||||
|--|--|
|
||||
| 类比 | 其它语言中由工具维护的依赖描述(如 `Cargo.toml` / `requirements.txt` 所承担的那类角色) |
|
||||
| 形态 | OKF:概念目录 + YAML frontmatter + Markdown 正文 |
|
||||
| 用途 | ① 编译器/包管理消费依赖图与导出 ② **自动生成本项目文档**(模块索引、依赖关系等) |
|
||||
| 权威 | 始终是手写 `.mq.md`;清单可删、可重建 |
|
||||
|
||||
```
|
||||
.mq.md 源(人写)
|
||||
→ marqdo 工具链
|
||||
→ 生成 OKF 风格清单(YAML + 概念页)
|
||||
→ 供编译解析,并渲染为项目目录文档
|
||||
```
|
||||
|
||||
执行方式等运行参数不放进该 YAML 当配置;由 CLI / 子命令决定。
|
||||
程序本体(类型、函数)只活在源正文里。
|
||||
|
||||
### 3.4 路径即身份,链接即关系
|
||||
|
||||
Concept ID = 路径;关系 = Markdown 链接;目录 = 渐进披露(`index.md`)。
|
||||
|
||||
**对模块系统的启发:**
|
||||
|
||||
- 文件路径可成为模块身份的一部分(类比 OKF concept ID)
|
||||
- `import` / 交叉引用尽量与 Markdown 链接同构,使「读文档跳转」与「解析依赖」共用一种边
|
||||
- 大型程序按「书的章节」组织目录,而不是扁平包名墙
|
||||
|
||||
### 3.5 生产者 / 消费者分离
|
||||
|
||||
同一 bundle:人手写、Agent 生成、管道导出,均可被另一 Agent 或 UI 消费。
|
||||
|
||||
**对 Marqdo 工具链:**
|
||||
|
||||
- 解析器、渲染器、求值器、LSP 都是**消费者**;源格式是唯一契约
|
||||
- 允许 Agent 协助编写 `.mq.md`,但语言必须对「纯手写」同样友好
|
||||
- 不把语义锁进某一 IDE 或云服务
|
||||
|
||||
### 3.6 信任与 attestation(中长期)
|
||||
|
||||
OKF v0.2 的 Attested Computation:批准的算法 + 确定性核验,防止 Agent「随口报数」。
|
||||
|
||||
**远期可借鉴(非 v0 范围):**
|
||||
|
||||
- 文档中嵌入的「可运行示例」是否经过核验执行?
|
||||
- 渲染出的结果是否带来源与 receipt?
|
||||
- Agent 生成的 Marqdo 模块如何标注 `generated` / `verified`?
|
||||
|
||||
这强化「文档中的数字/行为与真实执行一致」——与 Marqdo「同一份真相」高度同向。
|
||||
|
||||
### 3.7 规范本身的克制
|
||||
|
||||
OKF 规范强调:一页纸能讲清 v0.1 的互通面;v0.2 只**加词汇、不加强制规则**。
|
||||
|
||||
**对 Marqdo 文档文化:**
|
||||
|
||||
- ADR 记录否决项
|
||||
- 语法草案保持短小、可验证的 conformance 描述
|
||||
- 版本演进优先加法兼容,避免随意破坏「已是有效程序」的源文件
|
||||
|
||||
---
|
||||
|
||||
## 4. 不应照搬之处
|
||||
|
||||
1. **OKF 不是语言** — 其 body 是自由散文;Marqdo body 必须有严格可执行语义。不能停在「Markdown 知识库」。
|
||||
2. **无中心 type 注册** 适合知识目录;编程语言的类型系统需要更强的一致性与检查规则。
|
||||
3. **`Attested Computation` 的 executor/attester** 面向数据平台查询核验;Marqdo 若引入类似机制,应长在「测试 / 示例求值 / 再现构建」上,而不是 BigQuery 收据模型。
|
||||
4. **保留文件名**(`index.md` / `log.md`)可参考,但是否占用需在模块设计里单独 ADR,避免与源文件约定冲突。
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议纳入 Marqdo 设计议程的议题
|
||||
|
||||
来自本次调研、建议在 `design/` 或 `adr/` 中跟进:
|
||||
|
||||
1. **`.mq.md` 的双重解析模型** — Markdown CST 与 Marqdo AST 如何共享同一文本、何处分叉。
|
||||
2. **生成式 OKF 清单的落盘与命令** — 路径、是否提交 git、`sync`/`doc` 行为(方向已采纳,见 [design/generated-yaml-manifest.md](../design/generated-yaml-manifest.md))。
|
||||
3. **正文中的依赖声明语法** — import / 链接如何写出,供工具提取进生成清单。
|
||||
4. **Agent 友好但不 Agent 绑定** — 源格式对 LLM 可写,语义对确定性工具可检。
|
||||
5. **可渲染结果的 attestation(后期)** — 文档内求值结果的可验证性。
|
||||
|
||||
---
|
||||
|
||||
## 6. 参考链接
|
||||
|
||||
- 规范:[okf/SPEC.md](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(v0.2)
|
||||
- 仓库:[GoogleCloudPlatform/knowledge-catalog](https://github.com/GoogleCloudPlatform/knowledge-catalog/tree/main/okf)
|
||||
- 博客:[Introducing OKF](https://cloud.google.com/blog/products/data-analytics/how-the-open-knowledge-format-can-improve-data-sharing)
|
||||
- 博客:[OKF v0.2 trust signals](https://cloud.google.com/blog/products/data-analytics/okf-v0-2-adds-trust-signals)
|
||||
|
||||
---
|
||||
|
||||
## 7. 结论
|
||||
|
||||
OKF 证明了一条与 Marqdo 同向的产业判断:**人类可读的 Markdown 可以成为机器与 Agent 的一等交换面**,前提是约定足够小、足够稳,并把信任做成可查询字段而非口头保证。
|
||||
|
||||
Marqdo 比 OKF 多走一步:Markdown 不仅是知识的容器,更是**程序的表面语法**。我们借鉴 OKF 的形态,用作**从源自动生成的依赖清单与项目目录文档**(而非人手配置);同时借鉴「格式而非平台」、路径/链接身份、以及(远期)provenance。语言设计必须单独完成——**可渲染不等于可执行,可执行才是 Marqdo 的终点。**
|
||||
@@ -1,178 +0,0 @@
|
||||
# Marqdo 参考实现:正经解释器路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已采纳方向 |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 目标 | `marqdo run path/to/index.mq.md` 得到真实执行结果;非演示玩具 |
|
||||
| 相关 | [markdown-mapping.md](../design/markdown-mapping.md) · [ADR 0001](../adr/0001-implementation-language.md) · [USTC 编译课 2025](https://ustc-compiler-2025.github.io/homepage/) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 为何是解释器,而不是 USTC 式「编译到机器码」
|
||||
|
||||
[USTC《编译原理与技术》2025](https://ustc-compiler-2025.github.io/homepage/) 的实验链是经典**编译器**路径:
|
||||
|
||||
```
|
||||
源码 → 词法(Flex) → 语法(Bison) → AST
|
||||
→ 语义 / Light IR → 优化 → 后端(龙芯汇编等)
|
||||
```
|
||||
|
||||
这条路适合 Cminusf 一类「最终变成机器指令」的语言。Marqdo 的产品形态是:
|
||||
|
||||
- 源即 Markdown 文档,**打开即读、运行即算**;
|
||||
- 首要交付是 **从 `index.mq.md` 得到求值结果**(stdout、返回值、模块图),不是龙芯/ x86 二进制;
|
||||
- 语法表面是 Markup-as-Syntax,前端与传统正则+Bison 不同,但**中后端的编译学知识仍然全部用得上**。
|
||||
|
||||
因此:
|
||||
|
||||
| USTC / 龙书阶段 | Marqdo 解释器中的对应 |
|
||||
|-----------------|------------------------|
|
||||
| 词法分析 | **行分类 + 标记词法**(无标记=注释;`#`/`*`/`**`/`>`/`+`/`-`/表…) |
|
||||
| 语法分析 | **结构解析 → Marqdo AST**(可递归下降;不必上 Bison,除非日后自研纯文本方言) |
|
||||
| 语义分析 | 作用域、提升、导入、形参绑定、类型(可后置) |
|
||||
| 中间代码 | **可选**:先树遍历;第二期再降到**字节码** |
|
||||
| 优化 / 目标代码 | **非 v1 目标**;日后若要可另开「编译后端」ADR |
|
||||
|
||||
**结论:做正经解释器 = 把编译前端做扎实 + 把运行时做完整;不是跳过词法语法,也不是一上来 LLVM。**
|
||||
|
||||
权威地图见 [Crafting Interpreters — A Map of the Territory](https://craftinginterpreters.com/a-map-of-the-territory.html):用户眼里的「解释器」内部往往仍含编译到字节码(如 CPython);树遍历是第一期,字节码 VM 是第二期。
|
||||
|
||||
---
|
||||
|
||||
## 2. 推荐总体架构
|
||||
|
||||
```
|
||||
index.mq.md (+ 导入的 .mq.md)
|
||||
│
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 0. 源加载 / 模块图 │ frontmatter `> a.mq.md` → 依赖图
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 1. 词法·行分类 │ 注释行丢弃语义;代码行 → Token 流
|
||||
│ (+ MD 块辅助) │ pulldown-cmark/comrak;+/- 靠行扫描
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 2. 语法分析 │ Token/块 → Marqdo AST
|
||||
│ (递归下降) │ Module / Fun / Stmt / Expr / Branch / Loop …
|
||||
│ │ **不用 Flex/Bison**(见 dependencies.md)
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入合并
|
||||
│ │ 作用域链、形参、未定义名诊断
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 4a. 树遍历解释器 │ ← Phase I(必须先完成,跑通全部 tests 金样例)
|
||||
│ 或 │
|
||||
│ 4b. 字节码编译+VM │ ← Phase II(性能与「更像真语言实现」)
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
stdout / 返回值 / 退出码
|
||||
```
|
||||
|
||||
Phase I 对齐 Crafting Interpreters 的 **jlox(树遍历)**;Phase II 对齐 **clox(字节码 VM)**(见 [Chunks of Bytecode](https://craftinginterpreters.com/chunks-of-bytecode.html))。这是 Python/Ruby/Lua 主实现走过的正经路径,不是玩具捷径。
|
||||
|
||||
---
|
||||
|
||||
## 3. 各阶段「做满」的标准(反玩具清单)
|
||||
|
||||
### Phase 0 — 工程骨架(正式包,不是 `spike/`)
|
||||
|
||||
- 包名:`marqdo`(`src/marqdo/` 或 `marqdo/`)
|
||||
- CLI:`marqdo run <file.mq.md>`,默认找目录下 `index.mq.md`
|
||||
- 诊断:带文件名、行号、列号
|
||||
- 测试:每个 `tests/{structure,keywords}/*.mq.md` 有期望 stdout(金样例);CI 可跑
|
||||
|
||||
### Phase I — 可运行的语言核心(树遍历)
|
||||
|
||||
必须全部为真实现,禁止「正则特判 hello」:
|
||||
|
||||
1. **词法 / 行分类**:注释与代码严格分离。
|
||||
2. **语法 → AST**:函数、形参、`*` 语句、`**` 返回、`>` 调用、`+` 分支、`-` 循环、表格集合、绑定与 `==`。
|
||||
3. **语义**:提升、嵌套作用域、`##` 私有、frontmatter 导入公有顶层。
|
||||
4. **运行时**:环境、调用栈、值(文/数/表/记录)、内置 `print`。
|
||||
5. **验收**:`tests/structure/*` 与 `tests/keywords/*` 全部 `marqdo run` 通过。
|
||||
|
||||
### Phase II — 字节码 VM(正经化)
|
||||
|
||||
- AST → 线性字节码(栈式 VM 即可,与 clox / [GoAWK 经验](https://benhoyt.com/writings/goawk-compiler-vm/) 同类)
|
||||
- 控制流用跳转指令实现分支/循环
|
||||
- 同一套金样例必须 bit-同结果(回归)
|
||||
- 性能与可调试性(反汇编、栈跟踪)优于 Phase I
|
||||
|
||||
### Phase III — 语言完备(按需)
|
||||
|
||||
- 更完整表达式文法、错误模型、外联围栏 FFI
|
||||
- 生成 OKF 依赖目录
|
||||
- (可选)另一后端:编译到 Python/WASM——**另开 ADR**,不替代自研语义
|
||||
|
||||
---
|
||||
|
||||
## 4. 与 USTC Lab 的知识复用(学什么、不搬什么)
|
||||
|
||||
| 课程内容(摘要) | Marqdo 用法 |
|
||||
|------------------|-------------|
|
||||
| Lab1 词法/语法/AST | **直接对标** Phase I 前端;工具可自研递归下降,不必 Flex/Bison |
|
||||
| Lab2 IR / 访问者 | Phase II 字节码 ≈ 轻量 IR;访问者可用于 AST→字节码 |
|
||||
| Lab3 后端汇编 | **v1 不做**;解释器 VM 代替机器后端 |
|
||||
| Lab4 优化 | Phase II 之后可选;解释器也可做常量折叠等 |
|
||||
|
||||
教材仍可读:龙书、陈意云《编译原理》、课主页参考书;解释器专项读 **Crafting Interpreters**(免费:[craftinginterpreters.com](https://craftinginterpreters.com/))。
|
||||
|
||||
---
|
||||
|
||||
## 5. 实现语言(本路线图默认)
|
||||
|
||||
**参考解释器:Rust**([ADR 0001](../adr/0001-implementation-language.md))。
|
||||
|
||||
- 词法/语法:**自研 + GFM crate**,不用 Flex/Bison([dependencies.md](../design/dependencies.md))。
|
||||
- Python `spike/` 仅作风险探测与算法草稿。
|
||||
- Phase I 树遍历、Phase II 字节码 VM 均在 Rust 中实现。
|
||||
|
||||
---
|
||||
|
||||
## 6. 目录规划(正式代码,非 spike)
|
||||
|
||||
```
|
||||
Cargo.toml
|
||||
src/lex/ parse/ ast/ sema/ interp/ bytecode/ runtime/
|
||||
tests/ # gold.rs + structure|keywords|errors 夹具
|
||||
public/ # 用户可执行文档
|
||||
doc/ # 设计文稿
|
||||
spike/ # Python 存档,非运行时依赖
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. 近期里程碑(可执行顺序)
|
||||
|
||||
| 周序 | 交付 | 完成定义 |
|
||||
|------|------|----------|
|
||||
| M0 | 正式包 + CLI 空壳 + 金样例框架 | `marqdo run` 可调用;测试发现「未实现」 | ✅ |
|
||||
| M1 | 词法·行分类 + 最小 AST | 单测覆盖注释/代码行 | ✅ |
|
||||
| M2 | 解析:函数、输出调用、返回 | `hello` + `index` 金样例绿 | ✅ |
|
||||
| M3 | 分支、循环、表格、绑定 | `branch`/`loop`/`collection` 绿 | ✅ |
|
||||
| M4 | 导入与提升 | `with-import` 绿;**宣称 Phase I 达标** | ✅ |
|
||||
| M5 | 字节码设计文档 + 原型 opcode | 核心金样例双后端一致;覆盖表见 [bytecode.md](../design/bytecode.md) | ✅ 原型 |
|
||||
|
||||
**Phase I 完成前,不宣称「语言已实现」。**
|
||||
**仅 hello 特判通过,不算完成。**
|
||||
|
||||
---
|
||||
|
||||
## 8. 成功判据(产品级)
|
||||
|
||||
在仓库根或任意含 `index.mq.md` 的目录:
|
||||
|
||||
```bash
|
||||
marqdo run tests/structure/nested-call.mq.md
|
||||
# 或
|
||||
marqdo run tests/structure/import/main.mq.md
|
||||
```
|
||||
|
||||
输出与金样例一致;错误带位置;新增语法必须加金样例与单测。这才是「一门解释型语言」的最低合格线。
|
||||
@@ -1,220 +0,0 @@
|
||||
# 下一阶段:从玩具到可用语言
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **进行中**(P3-D1–D3 live view 断点 v1) |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 目标 | 交互 I/O、可信诊断、可生长标准库;view 渐进成为调试宿主 |
|
||||
| 相关 | [interpreter.md](interpreter.md) · [keywords.md](../design/keywords.md) · [pipeline-debug.md](../design/pipeline-debug.md) · [view.md](../design/view.md) · [view-debug.md](../design/view-debug.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 现状快照(决策依据)
|
||||
|
||||
| 能力 | 现状 | 结论 |
|
||||
|------|------|------|
|
||||
| **`print`** | 树遍历 + 字节码均可用 | 够用 |
|
||||
| **`input`** | CLI 双后端 + `--stdin-file`;frontmatter `stdin:`/`输入:`;live view 表单覆盖;无预置时 capture 提示补线 | **P1a + P1b 完成** |
|
||||
| **诊断** | 语句级 `path:line:col: message`;字节码指令带 `spans`;errors 金样例双后端断言位置 | **P0 完成** |
|
||||
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
|
||||
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
|
||||
| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
|
||||
| **模块** | `> file.mq.md` 顶层函数合并,无命名空间 | 短期可继续用 |
|
||||
|
||||
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
|
||||
|
||||
---
|
||||
|
||||
## 1. 轻重缓急(总序)
|
||||
|
||||
```text
|
||||
P0 诊断加固(短、撬动后续一切)
|
||||
P1 输入补完(先 CLI,再 view)
|
||||
P2 最小标准库(内置 + 可选 .mq.md 库)
|
||||
P3 view 调试(断点 / 单步)—— 在 P0 之后分期,勿一上来做 DAP
|
||||
```
|
||||
|
||||
| 优先级 | 主题 | 为何此刻 | 不做的代价 |
|
||||
|--------|------|----------|------------|
|
||||
| **P0** | 诊断完备度 | 便宜;给金样例、字节码、调试打地基 | 断点停错行;双后端错误体验分裂 |
|
||||
| **P1** | `input` | 「真语言」最低交互面;已有半截实现 | 只能写纯计算/打印 demo |
|
||||
| **P2** | 标准库 | 无库则用户无法写稍大程序 | 人人自造轮子、示例膨胀 |
|
||||
| **P3** | 前端调试 | 差异化(文档即调试);成本最高 | view 仍停留在「跑完看 stdout」 |
|
||||
|
||||
**原则:** 先让 **CLI 树遍历**成为完备参考实现;字节码跟进同语义;view 只接「已有事件/钩子」,不单独发明第二套语义。
|
||||
|
||||
---
|
||||
|
||||
## 2. P0 — 诊断与错误模型(约 3–7 天)
|
||||
|
||||
### 目标
|
||||
|
||||
所有用户可见失败统一为:
|
||||
|
||||
```text
|
||||
path:line:col: message
|
||||
```
|
||||
|
||||
树遍历与字节码**同文案、同位置粒度(至少语句级)**;金样例断言位置而不只子串。
|
||||
|
||||
### 工作项
|
||||
|
||||
1. **统一出口**
|
||||
- 解析侧尽量只产 `Diagnostic`(减少裸 `bail!("7:1: …")`)。
|
||||
- 字节码编译/VM:错误携带 `Span`(或指令 → 源行映射)。
|
||||
2. **位置粒度**
|
||||
- 短期:保持「语句起点」亦可;中期:为 `Expr`/`CallExpr` 补 `span`,让「未定义名」落在标识符上。
|
||||
3. **金样例**
|
||||
- `tests/errors/*`:断言完整 `path:line:col` 前缀(或相对路径规范化后的形式)。
|
||||
- 补:类型错误、除零、循环条件、capture 下 `input` 等。
|
||||
4. **文档**
|
||||
- 更新 [pipeline-debug.md](../design/pipeline-debug.md):错误码/严重级别可列为 P0.5(可选 `E0001` 一类,不阻塞)。
|
||||
|
||||
### 完成定义
|
||||
|
||||
- `cargo test`:errors 金样例含位置。
|
||||
- 同一 `.mq.md` 在 `--backend tree|bytecode` 下诊断一致(允许实现细节差异写进豁免表)。
|
||||
- view 执行失败区仍可读,路径无 `\\?\`。
|
||||
|
||||
### 刻意不做
|
||||
|
||||
- IDE DAP、完整堆栈 UI、sourcemap 可视化编辑器。
|
||||
|
||||
---
|
||||
|
||||
## 3. P1 — 输入(约 1–2 周)
|
||||
|
||||
分两轨:**CLI 必须先绿**;**view 交互后做**。
|
||||
|
||||
### P1a — CLI 完备(高优先级)
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 树遍历 | 已实现 stdin;补 `tests/keywords/input.mq.md`(用管道喂入) |
|
||||
| 字节码 | 增加 `Op::Input`(或等价 host call);与树同语义;capture 下同样拒绝或改走注入 API |
|
||||
| 文档/用户站 | `public/keywords/input.mq.md`;说明「view 默认无交互 stdin」 |
|
||||
|
||||
完成定义:`echo Alice | marqdo run …` 与字节码后端输出一致;金样例稳定。
|
||||
|
||||
### P1b — view / 静态站中的输入(中优先级,接在 P1a 后)
|
||||
|
||||
当前 `run_file_capture` **不能**接真实 stdin——这是设计,不是偶然 bug。
|
||||
|
||||
推荐路径(由易到难):
|
||||
|
||||
1. **脚本化注入(无 UI)**
|
||||
- `marqdo run --stdin-file answers.txt` 或 frontmatter/`---` 旁测数据。
|
||||
- view:执行前提供「预置输入行」文本框,一次性灌入队列。
|
||||
2. **实时交互(live view)**
|
||||
- 执行到 `input` → 暂停 → HTTP/WS 返回 prompt → 用户提交一行 → 继续。
|
||||
- 依赖 P3 的「可暂停执行」钩子;可与断点共用会话模型。
|
||||
3. **静态 `view output`**
|
||||
- 无服务器则只支持预置输入或跳过并标明 `input skipped`。
|
||||
|
||||
完成定义:live `marqdo view` 下至少一个带 `input` 的示例可点按跑通;静态导出行为有文档。
|
||||
|
||||
---
|
||||
|
||||
## 4. P2 — 标准库(约 2–3 周,可与 P1b/P3 前半重叠)
|
||||
|
||||
### 分层
|
||||
|
||||
```text
|
||||
L0 内置函数(解释器内) len / str / int / float? / type?
|
||||
L1 标准库模块(.mq.md) 文本、表/集合小工具;官方路径如 lib/ 或 std/
|
||||
L2 生态约定 catalog 收录;用户站专章
|
||||
```
|
||||
|
||||
### 建议落地顺序
|
||||
|
||||
| 迭代 | 内容 | 依据 |
|
||||
|------|------|------|
|
||||
| **S0** | `len`(文本/表)、`str`、`int` | keywords.md 已列候选;字节码已有闲置 `Op::Len` 可接线 |
|
||||
| **S1** | 表工具:取列、行数;字符串 trim/split(先内置或纯 mq 实现二选一) | 文档型语言高频 |
|
||||
| **S2** | 官方 `lib/` 或 `std/` + 导入约定(仍可用 frontmatter;或日后 `> std/text.mq.md`) | 可生长而不破现有导入 |
|
||||
| **S3** | 错误类型约定(如非法 `int` 文本 → 诊断) | 依赖 P0 |
|
||||
|
||||
### 完成定义(S0)
|
||||
|
||||
- 金样例 + 双后端;`public/` 有对应介绍页。
|
||||
- 不引入 `if`/`while` 英文关键字(控制流仍归 Markdown 标记)。
|
||||
|
||||
### 刻意不做(本阶段)
|
||||
|
||||
- 完整面向对象、包管理器、异步 I/O、HTTP 客户端(可列远期)。
|
||||
|
||||
---
|
||||
|
||||
## 5. P3 — 前端成为调试机构(约 3–6 周,分里程碑)
|
||||
|
||||
**不要从 DAP/VS Code 插件开干。** view 已有 Structure / Source / Execution,是天然宿主。
|
||||
|
||||
```mermaid
|
||||
flowchart LR
|
||||
P0loc[P0 可信位置] --> Pause[语句边界暂停钩子]
|
||||
Pause --> Sess[调试会话 API]
|
||||
Sess --> UI[view 断点与单步 UI]
|
||||
UI --> DAP[可选 DAP 适配]
|
||||
```
|
||||
|
||||
| 里程碑 | 交付 | 依赖 |
|
||||
|--------|------|------|
|
||||
| **D0** | 语句级源映射(树优先;字节码指令→行) | P0 |
|
||||
| **D1** | 运行时钩子:进入语句前可 pause;`--trace-eval` 结构化事件(JSON 行) | D0 |
|
||||
| **D2** | 进程内调试会话:设/清断点、continue、step over(先树遍历) | D1 |
|
||||
| **D3** | **view debug 模式**:源码行点击断点;高亮当前行;侧栏 locals/栈;与文档模式切换 | D2 + 少量 JS 或服务端推进 |
|
||||
| **D4** | 与 P1b 合流:`input` 暂停复用同一会话 | P1b |
|
||||
| **D5**(可选) | DAP 薄适配,供外部 IDE | D2 稳定后 |
|
||||
|
||||
### 完成定义(D3 即「可用调试」)
|
||||
|
||||
- 用户能在 `marqdo view` 对某 `.mq.md` 设断点、单步、看变量。
|
||||
- 文档站默认模式不变(一次执行);debug 为显式开关。
|
||||
- 断点命中行与 P0 诊断行一致(允许文档说明「语句起点」语义)。
|
||||
|
||||
### 风险与边界
|
||||
|
||||
- 静态 `gh-pages` **无法**真断点(无常驻 VM);调试仅 **live view**(或未来 WASM 解释器)。
|
||||
- 字节码调试可晚于树遍历一个迭代。
|
||||
|
||||
---
|
||||
|
||||
## 6. 推荐排期(可执行流程)
|
||||
|
||||
按「每段都可合并、可演示」切周,避免大爆炸:
|
||||
|
||||
| 周序 | 主题 | 可合并交付 |
|
||||
|------|------|------------|
|
||||
| **W1** | P0 诊断统一 + errors 金样例加固 | 双后端错误位置一致 |
|
||||
| **W2** | P1a `input` 字节码 + 管道金样例 + 用户文档 | CLI 交互闭环 |
|
||||
| **W3** | P2-S0 `len`/`str`/`int` + 样例 | 「有点像语言」的第一批库 |
|
||||
| **W4** | P1b 预置输入(view 文本框 / `--stdin-file`) | view 可跑含 input 的 demo |
|
||||
| **W5–W6** | P3-D0–D2 暂停与会话 | 无 UI 也能用 API/CLI 单步 |
|
||||
| **W7–W8** | P3-D3 view 断点 UI + D4 与 input 暂停 | **调试机构**第一版 |
|
||||
| **并行/随后** | P2-S1/S2 扩库;P3-D5 DAP | 按反馈加 |
|
||||
|
||||
若人力紧:**砍掉顺序为 D5 → S2 花活 → 字节码调试**;**不可砍:P0、P1a、P2-S0、D3 之前的 D0–D2。**
|
||||
|
||||
---
|
||||
|
||||
## 7. 验收总表(「真正可用」最低线)
|
||||
|
||||
1. **I/O**:CLI 上 `print`/`input` 双后端一致;view 至少支持预置或交互输入之一。
|
||||
2. **错误**:失败必有稳定位置;常见错误有金样例;用户站不靠「瞎猜 stderr」。
|
||||
3. **库**:至少 `len`/`str`/`int` 可用并有文档。
|
||||
4. **调试**:live view 可断点 + 单步 + 看当前绑定(树遍历即可宣称 v1)。
|
||||
5. **不破坏**:现有 `tests/` 金样例与 `public/` 用户站回归绿。
|
||||
|
||||
---
|
||||
|
||||
## 8. 文档与工程动作(开工时)
|
||||
|
||||
1. 本文件定为「下一阶段宪法」;开工后把各 P 拆到 `doc/design/` 子设计(`input-interactive.md`、`stdlib.md`、`view-debug.md`)。
|
||||
2. 每个里程碑:金样例 → 实现 → `public/` 更新 →(若行为用户可见)再发版 / 刷 `gh-pages`。
|
||||
3. 版本建议:P1a+P0 可打 `v0.0.4`;P2-S0 打 `v0.0.5`;P3-D3 打 `v0.1.0`(「可用调试」语义升级)。
|
||||
|
||||
---
|
||||
|
||||
## 9. 一句话路线
|
||||
|
||||
**先把错误说准、把输入在 CLI 做完,再长出最小标准库;最后把现有 view 升级成可暂停的调试宿主——而不是先做 IDE 插件或大而全标准库。**
|
||||
@@ -1,111 +0,0 @@
|
||||
---
|
||||
title: ext/ai/agent
|
||||
description: Thin agent framework — ctor, run, clear_history only.
|
||||
> ext/ai/llm.mq.md
|
||||
---
|
||||
|
||||
## build_agent_context
|
||||
+ `agent`
|
||||
+ `extra`
|
||||
|
||||
Internal: assemble prompt (user prompt, extra, tool list, source, call site, history, Marqdo skill).
|
||||
|
||||
*`user_prompt` = > get value=`agent` key=user_prompt *
|
||||
1. `user_prompt`
|
||||
*`up` = `user_prompt`*
|
||||
2. *
|
||||
*`up` = None*
|
||||
|
||||
*`tools` = > get value=`agent` key=tools *
|
||||
*`tools_s` = > host_format_tools_for_llm tools=`tools` *
|
||||
*`src` = > host_module_source *
|
||||
*`site` = > host_call_site *
|
||||
*`site_s` = > stringify value=`site` *
|
||||
*`id` = > get value=`agent` key=id *
|
||||
*`hist` = > host_agent_history_get id=`id` *
|
||||
*`hist_s` = > stringify value=`hist` *
|
||||
*`skill` = > host_marqdo_skill *
|
||||
*`extra_s` = > stringify value=`extra` *
|
||||
|
||||
*`sep` = > parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- extra ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source ---\n","f":"\n\n--- history ---\n","g":"\n\n--- marqdo skill ---\n"} *
|
||||
*`a` = > get value=`sep` key=a *
|
||||
*`b` = > get value=`sep` key=b *
|
||||
*`c` = > get value=`sep` key=c *
|
||||
*`d` = > get value=`sep` key=d *
|
||||
*`e` = > get value=`sep` key=e *
|
||||
*`f` = > get value=`sep` key=f *
|
||||
*`g` = > get value=`sep` key=g *
|
||||
|
||||
*`tool_proto` = \n\n--- tool protocol ---\nEach tool is a zero-arg Marqdo function in this module (see tools list). To call one, reply with exactly one line: TOOL:<name>. No other text on that line.\nAfter the tool runs you will get its output and should answer the user.\n *
|
||||
|
||||
*`p` = You are a Marqdo agent. Follow Marqdo skill rules when reading or writing .mq.md. *
|
||||
*`p` = `p` + `a` + `up` + `b` + `extra_s` + `c` + `tool_proto` + `tools_s` + `d` + `site_s` + `e` + `src` + `f` + `hist_s` + `g` + `skill` *
|
||||
**`p`**
|
||||
|
||||
# agent
|
||||
+ `model`
|
||||
+ `tools`
|
||||
+ `user_prompt`
|
||||
|
||||
*`id` = > host_agent_alloc *
|
||||
*`h` = > parse text={"_type":"agent"} *
|
||||
*`h` = > map_set map=`h` key=id value=`id` *
|
||||
*`h` = > map_set map=`h` key=model value=`model` *
|
||||
*`h` = > map_set map=`h` key=tools value=`tools` *
|
||||
|
||||
1. `user_prompt`
|
||||
*`h` = > map_set map=`h` key=user_prompt value=`user_prompt` *
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
**`h`**
|
||||
|
||||
## clear_history
|
||||
|
||||
*`id` = > get value=`self` key=id *
|
||||
> host_agent_history_clear id=`id`
|
||||
****
|
||||
|
||||
## run
|
||||
+ `extra`
|
||||
|
||||
*`ctx` = > build_agent_context agent=`self` extra=`extra` *
|
||||
*`id` = > get value=`self` key=id *
|
||||
|
||||
*`user_turn` = > parse text={"role":"user"} *
|
||||
*`user_turn` = > map_set map=`user_turn` key=content value=`extra` *
|
||||
> host_agent_history_append id=`id` item=`user_turn`
|
||||
|
||||
*`model` = > get value=`self` key=model *
|
||||
*`reply` = > `model`.complete prompt=`ctx` *
|
||||
*`tools` = > get value=`self` key=tools *
|
||||
*`reply` = > trim value=`reply` *
|
||||
|
||||
*`parts` = > split value=`reply` sep=: *
|
||||
*`head` = > at value=`parts` index=0 *
|
||||
*`tool_name` = > at value=`parts` index=1 *
|
||||
*`tool_name` = > trim value=`tool_name` *
|
||||
|
||||
1. `head` == TOOL
|
||||
*`allowed` = > host_tool_allowed tools=`tools` name=`tool_name` *
|
||||
1. `allowed`
|
||||
*`tool_out` = > call_fn name=`tool_name` *
|
||||
*`tool_s` = > stringify value=`tool_out` *
|
||||
*`extra_s` = > stringify value=`extra` *
|
||||
*`fp` = The user asked: *
|
||||
*`fp` = `fp` + `extra_s` *
|
||||
*`fp` = `fp` + . You invoked tool *
|
||||
*`fp` = `fp` + `tool_name` *
|
||||
*`fp` = `fp` + which returned: *
|
||||
*`fp` = `fp` + `tool_s` *
|
||||
*`fp` = `fp` + . Reply to the user in one brief sentence. *
|
||||
*`reply` = > `model`.complete prompt=`fp` *
|
||||
2. *
|
||||
*`reply` = Tool not allowed: `tool_name` *
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
*`as_turn` = > parse text={"role":"assistant"} *
|
||||
*`as_turn` = > map_set map=`as_turn` key=content value=`reply` *
|
||||
> host_agent_history_append id=`id` item=`as_turn`
|
||||
**`reply`**
|
||||
@@ -1,130 +0,0 @@
|
||||
---
|
||||
title: ext/ai/llm
|
||||
description: OpenAI-compatible LLM object (English). Import ext/ai/llm.mq.md.
|
||||
> lib/sys.mq.md
|
||||
> lib/net.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## load_env
|
||||
|
||||
Load `.env` from cwd (optional named arg `path=`). Does not override existing variables.
|
||||
|
||||
**> load_dotenv**
|
||||
|
||||
# llm
|
||||
|
||||
Construct an LLM handle from `OPENAI_*` / `MARQDO_LLM_*` (default base OpenAI v1, model `gpt-4o-mini`).
|
||||
|
||||
*`d` = > parse text={"base":"https://api.openai.com/v1","model":"gpt-4o-mini","suffix":"/chat/completions","bearer":"Bearer ","p1":"{\"model\":","p2":",\"messages\":[{\"role\":\"user\",\"content\":","p3":"}]}","h1":"{\"Authorization\":","h2":"}","a1":"{\"api_key\":","a2":",\"base_url\":","a3":",\"model\":","a4":",\"suffix\":","a5":",\"bearer\":","a6":",\"p1\":","a7":",\"p2\":","a8":",\"p3\":","a9":",\"h1\":","a10":",\"h2\":","a11":"}"} *
|
||||
|
||||
*`api_key` = > env_get name=OPENAI_API_KEY *
|
||||
1. `api_key`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`api_key` = > env_get name=MARQDO_LLM_API_KEY *
|
||||
3. `api_key`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
> print text=ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY
|
||||
> exit code=1
|
||||
|
||||
*`base_url` = > env_get name=OPENAI_BASE_URL *
|
||||
1. `base_url`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`base_url` = > env_get name=MARQDO_LLM_BASE_URL *
|
||||
3. `base_url`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`base_url` = > get value=`d` key=base *
|
||||
|
||||
*`model` = > env_get name=OPENAI_MODEL *
|
||||
1. `model`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`model` = > env_get name=MARQDO_LLM_MODEL *
|
||||
3. `model`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`model` = > get value=`d` key=model *
|
||||
|
||||
*`q_key` = > quote text=`api_key` *
|
||||
*`q_base` = > quote text=`base_url` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`suffix` = > get value=`d` key=suffix *
|
||||
*`bearer` = > get value=`d` key=bearer *
|
||||
*`p1` = > get value=`d` key=p1 *
|
||||
*`p2` = > get value=`d` key=p2 *
|
||||
*`p3` = > get value=`d` key=p3 *
|
||||
*`h1` = > get value=`d` key=h1 *
|
||||
*`h2` = > get value=`d` key=h2 *
|
||||
*`q_suf` = > quote text=`suffix` *
|
||||
*`q_br` = > quote text=`bearer` *
|
||||
*`q_p1` = > quote text=`p1` *
|
||||
*`q_p2` = > quote text=`p2` *
|
||||
*`q_p3` = > quote text=`p3` *
|
||||
*`q_h1` = > quote text=`h1` *
|
||||
*`q_h2` = > quote text=`h2` *
|
||||
*`a1` = > get value=`d` key=a1 *
|
||||
*`a2` = > get value=`d` key=a2 *
|
||||
*`a3` = > get value=`d` key=a3 *
|
||||
*`a4` = > get value=`d` key=a4 *
|
||||
*`a5` = > get value=`d` key=a5 *
|
||||
*`a6` = > get value=`d` key=a6 *
|
||||
*`a7` = > get value=`d` key=a7 *
|
||||
*`a8` = > get value=`d` key=a8 *
|
||||
*`a9` = > get value=`d` key=a9 *
|
||||
*`a10` = > get value=`d` key=a10 *
|
||||
*`a11` = > get value=`d` key=a11 *
|
||||
*`raw` = `a1` + `q_key` + `a2` + `q_base` + `a3` + `q_model` + `a4` + `q_suf` + `a5` + `q_br` + `a6` + `q_p1` + `a7` + `q_p2` + `a8` + `q_p3` + `a9` + `q_h1` + `a10` + `q_h2` + `a11` *
|
||||
**> parse text=`raw`**
|
||||
|
||||
## complete
|
||||
+ `prompt`
|
||||
|
||||
Chat completion using `self` / `自` handle fields.
|
||||
|
||||
*`api_key` = > get value=`self` key=api_key *
|
||||
*`base_url` = > get value=`self` key=base_url *
|
||||
*`model` = > get value=`self` key=model *
|
||||
*`suffix` = > get value=`self` key=suffix *
|
||||
*`bearer` = > get value=`self` key=bearer *
|
||||
*`p1` = > get value=`self` key=p1 *
|
||||
*`p2` = > get value=`self` key=p2 *
|
||||
*`p3` = > get value=`self` key=p3 *
|
||||
*`h1` = > get value=`self` key=h1 *
|
||||
*`h2` = > get value=`self` key=h2 *
|
||||
*`url` = `base_url` + `suffix` *
|
||||
*`auth` = `bearer` + `api_key` *
|
||||
*`q_auth` = > quote text=`auth` *
|
||||
*`hdr_raw` = `h1` + `q_auth` + `h2` *
|
||||
*`headers` = > parse text=`hdr_raw` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`q_prompt` = > quote text=`prompt` *
|
||||
*`body` = `p1` + `q_model` + `p2` + `q_prompt` + `p3` *
|
||||
*`resp` = > http_post url=`url` body=`body` headers=`headers` *
|
||||
*`status` = > get value=`resp` key=status *
|
||||
*`raw` = > get value=`resp` key=body *
|
||||
|
||||
1. `status` == 200
|
||||
*`data` = > parse text=`raw` *
|
||||
*`choices` = > get value=`data` key=choices *
|
||||
*`first` = > at value=`choices` index=0 *
|
||||
*`message` = > get value=`first` key=message *
|
||||
*`content` = > get value=`message` key=content *
|
||||
**`content`**
|
||||
2. *
|
||||
> print text=ext/ai/llm: HTTP error
|
||||
> print text=`status`
|
||||
> print text=`raw`
|
||||
> exit code=1
|
||||
|
||||
---
|
||||
|
||||
## chat
|
||||
+ `prompt`
|
||||
|
||||
Alias for `complete`.
|
||||
|
||||
**> `self`.complete prompt=`prompt`**
|
||||
@@ -1,130 +0,0 @@
|
||||
---
|
||||
title: ext/ai/大模型
|
||||
description: OpenAI 兼容大模型对象(中文)。导入 ext/ai/大模型.mq.md。
|
||||
> lib/系统.mq.md
|
||||
> lib/网络.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## 加载环境
|
||||
|
||||
从工作目录加载 `.env`(可选具名实参 `path=`)。不覆盖已有变量。
|
||||
|
||||
**> load_dotenv**
|
||||
|
||||
# 大模型
|
||||
|
||||
从 `OPENAI_*` / `MARQDO_LLM_*` 构造句柄(默认 OpenAI v1 + `gpt-4o-mini`)。
|
||||
|
||||
*`d` = > parse text={"base":"https://api.openai.com/v1","model":"gpt-4o-mini","suffix":"/chat/completions","bearer":"Bearer ","p1":"{\"model\":","p2":",\"messages\":[{\"role\":\"user\",\"content\":","p3":"}]}","h1":"{\"Authorization\":","h2":"}","a1":"{\"api_key\":","a2":",\"base_url\":","a3":",\"model\":","a4":",\"suffix\":","a5":",\"bearer\":","a6":",\"p1\":","a7":",\"p2\":","a8":",\"p3\":","a9":",\"h1\":","a10":",\"h2\":","a11":"}"} *
|
||||
|
||||
*`api_key` = > 取环境 名=OPENAI_API_KEY *
|
||||
1. `api_key`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`api_key` = > 取环境 名=MARQDO_LLM_API_KEY *
|
||||
3. `api_key`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
> 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY
|
||||
> 退出 码=1
|
||||
|
||||
*`base_url` = > 取环境 名=OPENAI_BASE_URL *
|
||||
1. `base_url`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`base_url` = > 取环境 名=MARQDO_LLM_BASE_URL *
|
||||
3. `base_url`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`base_url` = > get value=`d` key=base *
|
||||
|
||||
*`model` = > 取环境 名=OPENAI_MODEL *
|
||||
1. `model`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`model` = > 取环境 名=MARQDO_LLM_MODEL *
|
||||
3. `model`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`model` = > get value=`d` key=model *
|
||||
|
||||
*`q_key` = > quote text=`api_key` *
|
||||
*`q_base` = > quote text=`base_url` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`suffix` = > get value=`d` key=suffix *
|
||||
*`bearer` = > get value=`d` key=bearer *
|
||||
*`p1` = > get value=`d` key=p1 *
|
||||
*`p2` = > get value=`d` key=p2 *
|
||||
*`p3` = > get value=`d` key=p3 *
|
||||
*`h1` = > get value=`d` key=h1 *
|
||||
*`h2` = > get value=`d` key=h2 *
|
||||
*`q_suf` = > quote text=`suffix` *
|
||||
*`q_br` = > quote text=`bearer` *
|
||||
*`q_p1` = > quote text=`p1` *
|
||||
*`q_p2` = > quote text=`p2` *
|
||||
*`q_p3` = > quote text=`p3` *
|
||||
*`q_h1` = > quote text=`h1` *
|
||||
*`q_h2` = > quote text=`h2` *
|
||||
*`a1` = > get value=`d` key=a1 *
|
||||
*`a2` = > get value=`d` key=a2 *
|
||||
*`a3` = > get value=`d` key=a3 *
|
||||
*`a4` = > get value=`d` key=a4 *
|
||||
*`a5` = > get value=`d` key=a5 *
|
||||
*`a6` = > get value=`d` key=a6 *
|
||||
*`a7` = > get value=`d` key=a7 *
|
||||
*`a8` = > get value=`d` key=a8 *
|
||||
*`a9` = > get value=`d` key=a9 *
|
||||
*`a10` = > get value=`d` key=a10 *
|
||||
*`a11` = > get value=`d` key=a11 *
|
||||
*`raw` = `a1` + `q_key` + `a2` + `q_base` + `a3` + `q_model` + `a4` + `q_suf` + `a5` + `q_br` + `a6` + `q_p1` + `a7` + `q_p2` + `a8` + `q_p3` + `a9` + `q_h1` + `a10` + `q_h2` + `a11` *
|
||||
**> parse text=`raw`**
|
||||
|
||||
## 运行
|
||||
+ `提示`
|
||||
|
||||
使用 `自` / `self` 句柄字段做聊天补全。
|
||||
|
||||
*`api_key` = > get value=`自` key=api_key *
|
||||
*`base_url` = > get value=`自` key=base_url *
|
||||
*`model` = > get value=`自` key=model *
|
||||
*`suffix` = > get value=`自` key=suffix *
|
||||
*`bearer` = > get value=`自` key=bearer *
|
||||
*`p1` = > get value=`自` key=p1 *
|
||||
*`p2` = > get value=`自` key=p2 *
|
||||
*`p3` = > get value=`自` key=p3 *
|
||||
*`h1` = > get value=`自` key=h1 *
|
||||
*`h2` = > get value=`自` key=h2 *
|
||||
*`url` = `base_url` + `suffix` *
|
||||
*`auth` = `bearer` + `api_key` *
|
||||
*`q_auth` = > quote text=`auth` *
|
||||
*`hdr_raw` = `h1` + `q_auth` + `h2` *
|
||||
*`headers` = > parse text=`hdr_raw` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`q_prompt` = > quote text=`提示` *
|
||||
*`body` = `p1` + `q_model` + `p2` + `q_prompt` + `p3` *
|
||||
*`resp` = > http_post url=`url` body=`body` headers=`headers` *
|
||||
*`status` = > get value=`resp` key=status *
|
||||
*`raw` = > get value=`resp` key=body *
|
||||
|
||||
1. `status` == 200
|
||||
*`data` = > parse text=`raw` *
|
||||
*`choices` = > get value=`data` key=choices *
|
||||
*`first` = > at value=`choices` index=0 *
|
||||
*`message` = > get value=`first` key=message *
|
||||
*`content` = > get value=`message` key=content *
|
||||
**`content`**
|
||||
2. *
|
||||
> 打印 内容=ext/ai/大模型: HTTP 错误
|
||||
> 打印 内容=`status`
|
||||
> 打印 内容=`raw`
|
||||
> 退出 码=1
|
||||
|
||||
---
|
||||
|
||||
## 聊天
|
||||
+ `提示`
|
||||
|
||||
`运行` 的别名。
|
||||
|
||||
**> `自`.运行 提示=`提示`**
|
||||
@@ -1,111 +0,0 @@
|
||||
---
|
||||
title: ext/ai/智能体
|
||||
description: 薄智能体框架 — 仅构造、执行、清空历史。
|
||||
> ext/ai/大模型.mq.md
|
||||
---
|
||||
|
||||
## 构建上下文
|
||||
+ `智能体`
|
||||
+ `额外信息`
|
||||
|
||||
内部:组装提示(用户提示、额外信息、工具列表、源码、位置、历史、Marqdo skill)。
|
||||
|
||||
*`user_prompt` = > get value=`智能体` key=user_prompt *
|
||||
1. `user_prompt`
|
||||
*`up` = `user_prompt`*
|
||||
2. *
|
||||
*`up` = 空*
|
||||
|
||||
*`tools` = > get value=`智能体` key=tools *
|
||||
*`tools_s` = > host_format_tools_for_llm tools=`tools` *
|
||||
*`src` = > host_module_source *
|
||||
*`site` = > host_call_site *
|
||||
*`site_s` = > stringify value=`site` *
|
||||
*`id` = > get value=`智能体` key=id *
|
||||
*`hist` = > host_agent_history_get id=`id` *
|
||||
*`hist_s` = > stringify value=`hist` *
|
||||
*`skill` = > host_marqdo_skill *
|
||||
*`extra_s` = > stringify value=`额外信息` *
|
||||
|
||||
*`sep` = > parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- extra ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source ---\n","f":"\n\n--- history ---\n","g":"\n\n--- marqdo skill ---\n"} *
|
||||
*`a` = > get value=`sep` key=a *
|
||||
*`b` = > get value=`sep` key=b *
|
||||
*`c` = > get value=`sep` key=c *
|
||||
*`d` = > get value=`sep` key=d *
|
||||
*`e` = > get value=`sep` key=e *
|
||||
*`f` = > get value=`sep` key=f *
|
||||
*`g` = > get value=`sep` key=g *
|
||||
|
||||
*`tool_proto` = \n\n--- tool protocol ---\nEach tool is a zero-arg Marqdo function in this module (see tools list). To call one, reply with exactly one line: TOOL:<name>. No other text on that line.\nAfter the tool runs you will get its output and should answer the user.\n *
|
||||
|
||||
*`p` = You are a Marqdo agent. Follow Marqdo skill rules when reading or writing .mq.md. *
|
||||
*`p` = `p` + `a` + `up` + `b` + `extra_s` + `c` + `tool_proto` + `tools_s` + `d` + `site_s` + `e` + `src` + `f` + `hist_s` + `g` + `skill` *
|
||||
**`p`**
|
||||
|
||||
# 智能体
|
||||
+ `大模型`
|
||||
+ `工具`
|
||||
+ `用户提示信息`
|
||||
|
||||
*`id` = > host_agent_alloc *
|
||||
*`h` = > parse text={"_type":"智能体"} *
|
||||
*`h` = > map_set map=`h` key=id value=`id` *
|
||||
*`h` = > map_set map=`h` key=model value=`大模型` *
|
||||
*`h` = > map_set map=`h` key=tools value=`工具` *
|
||||
|
||||
1. `用户提示信息`
|
||||
*`h` = > map_set map=`h` key=user_prompt value=`用户提示信息` *
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
**`h`**
|
||||
|
||||
## 清空历史
|
||||
|
||||
*`id` = > get value=`自` key=id *
|
||||
> host_agent_history_clear id=`id`
|
||||
****
|
||||
|
||||
## 执行
|
||||
+ `额外信息`
|
||||
|
||||
*`ctx` = > 构建上下文 智能体=`自` 额外信息=`额外信息` *
|
||||
*`id` = > get value=`自` key=id *
|
||||
|
||||
*`user_turn` = > parse text={"role":"user"} *
|
||||
*`user_turn` = > map_set map=`user_turn` key=content value=`额外信息` *
|
||||
> host_agent_history_append id=`id` item=`user_turn`
|
||||
|
||||
*`model` = > get value=`自` key=model *
|
||||
*`reply` = > `model`.运行 提示=`ctx` *
|
||||
*`tools` = > get value=`自` key=tools *
|
||||
*`reply` = > trim value=`reply` *
|
||||
|
||||
*`parts` = > split value=`reply` sep=: *
|
||||
*`head` = > at value=`parts` index=0 *
|
||||
*`tool_name` = > at value=`parts` index=1 *
|
||||
*`tool_name` = > trim value=`tool_name` *
|
||||
|
||||
1. `head` == TOOL
|
||||
*`allowed` = > host_tool_allowed tools=`tools` name=`tool_name` *
|
||||
1. `allowed`
|
||||
*`tool_out` = > 调用 名=`tool_name` *
|
||||
*`tool_s` = > stringify value=`tool_out` *
|
||||
*`extra_s` = > stringify value=`额外信息` *
|
||||
*`fp` = The user asked: *
|
||||
*`fp` = `fp` + `extra_s` *
|
||||
*`fp` = `fp` + . You invoked tool *
|
||||
*`fp` = `fp` + `tool_name` *
|
||||
*`fp` = `fp` + which returned: *
|
||||
*`fp` = `fp` + `tool_s` *
|
||||
*`fp` = `fp` + . Reply to the user in one brief sentence. *
|
||||
*`reply` = > `model`.运行 提示=`fp` *
|
||||
2. *
|
||||
*`reply` = Tool not allowed: `tool_name` *
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
*`as_turn` = > parse text={"role":"assistant"} *
|
||||
*`as_turn` = > map_set map=`as_turn` key=content value=`reply` *
|
||||
> host_agent_history_append id=`id` item=`as_turn`
|
||||
**`reply`**
|
||||
@@ -1,43 +0,0 @@
|
||||
/* Marqdo plugin ABI v1 — C contract (source of truth).
|
||||
*
|
||||
* Plugins are optional shared libraries (.dll / .so / .dylib), never linked
|
||||
* into the marqdo binary. Values cross the boundary as UTF-8 JSON.
|
||||
*/
|
||||
#ifndef MARQDO_ABI_H
|
||||
#define MARQDO_ABI_H
|
||||
|
||||
#include <stddef.h>
|
||||
#include <stdint.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
#define MARQDO_ABI_VERSION 1u
|
||||
|
||||
/* Plugin function: args_json is a UTF-8 JSON object whose keys are param names.
|
||||
* On success: return 0, set *out_json to a heap string (host frees via free).
|
||||
* On failure: return non-zero; optional *err_msg heap string (host frees).
|
||||
* out_json / err_msg may be left NULL.
|
||||
*/
|
||||
typedef int (*MarqdoPluginFn)(const char *args_json, char **out_json, char **err_msg);
|
||||
|
||||
typedef struct MarqdoHostApi {
|
||||
void *userdata;
|
||||
/* params: comma-separated param names in order, e.g. "a,b". May be "". */
|
||||
int (*register_fn)(void *userdata, const char *name, const char *params,
|
||||
MarqdoPluginFn fn);
|
||||
void *(*alloc)(size_t n);
|
||||
void (*free)(void *p);
|
||||
} MarqdoHostApi;
|
||||
|
||||
/* Required exports from every plugin shared library. */
|
||||
uint32_t marqdo_plugin_abi_version(void);
|
||||
int marqdo_plugin_init(const MarqdoHostApi *host);
|
||||
void marqdo_plugin_shutdown(void);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* MARQDO_ABI_H */
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
title: lib/foreign
|
||||
description: Run bound code fences and inline sources via local interpreters
|
||||
---
|
||||
|
||||
## set_cmd
|
||||
+ `lang`
|
||||
+ `cmd`
|
||||
|
||||
**> host_foreign_set_cmd lang=`lang` cmd=`cmd`**
|
||||
|
||||
## run
|
||||
+ `code`
|
||||
|
||||
**> host_foreign_run code=`code`**
|
||||
|
||||
## run_lang
|
||||
+ `lang`
|
||||
+ `source`
|
||||
|
||||
**> host_foreign_run_lang lang=`lang` source=`source`**
|
||||
|
||||
## langs
|
||||
|
||||
**> host_foreign_langs**
|
||||
@@ -1,41 +0,0 @@
|
||||
---
|
||||
title: lib/fs
|
||||
description: English filesystem wrappers
|
||||
---
|
||||
|
||||
## read_text
|
||||
+ `path`
|
||||
|
||||
**> host_read_text path=`path`**
|
||||
|
||||
## write_text
|
||||
+ `path`
|
||||
+ `text`
|
||||
|
||||
**> host_write_text path=`path` text=`text`**
|
||||
|
||||
## append_text
|
||||
+ `path`
|
||||
+ `text`
|
||||
|
||||
**> host_append_text path=`path` text=`text`**
|
||||
|
||||
## exists
|
||||
+ `path`
|
||||
|
||||
**> host_exists path=`path`**
|
||||
|
||||
## list_dir
|
||||
+ `path`
|
||||
|
||||
**> host_list_dir path=`path`**
|
||||
|
||||
## make_dir
|
||||
+ `path`
|
||||
|
||||
**> host_make_dir path=`path`**
|
||||
|
||||
## remove
|
||||
+ `path`
|
||||
|
||||
**> host_remove path=`path`**
|
||||
@@ -1,43 +0,0 @@
|
||||
---
|
||||
title: lib/json
|
||||
description: JSON parse/stringify (shared EN/ZH import)
|
||||
---
|
||||
|
||||
## parse
|
||||
+ `text`
|
||||
|
||||
**> host_json_parse text=`text`**
|
||||
|
||||
## stringify
|
||||
+ `value`
|
||||
|
||||
**> host_json_stringify value=`value`**
|
||||
|
||||
## get
|
||||
+ `value`
|
||||
+ `key`
|
||||
|
||||
**> host_json_get value=`value` key=`key`**
|
||||
|
||||
## keys
|
||||
+ `value`
|
||||
|
||||
**> host_json_keys value=`value`**
|
||||
|
||||
## quote
|
||||
+ `text`
|
||||
|
||||
**> host_json_quote text=`text`**
|
||||
|
||||
## set
|
||||
+ `map`
|
||||
+ `key`
|
||||
+ `value`
|
||||
|
||||
**> host_map_set map=`map` key=`key` value=`value`**
|
||||
|
||||
## append
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
**> host_list_append list=`list` item=`item`**
|
||||
-200
@@ -1,200 +0,0 @@
|
||||
---
|
||||
title: lib/math
|
||||
description: High-school math — num, random, formula, plot
|
||||
---
|
||||
|
||||
## pi
|
||||
|
||||
**> host_pi**
|
||||
|
||||
## e
|
||||
|
||||
**> host_e**
|
||||
|
||||
## num
|
||||
+ `value`
|
||||
|
||||
**> host_num value=`value`**
|
||||
|
||||
## add
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_add a=`a` b=`b`**
|
||||
|
||||
## sub
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_sub a=`a` b=`b`**
|
||||
|
||||
## mul
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_mul a=`a` b=`b`**
|
||||
|
||||
## div
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_div a=`a` b=`b`**
|
||||
|
||||
## pow
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_pow a=`a` b=`b`**
|
||||
|
||||
## neg
|
||||
+ `value`
|
||||
|
||||
**> host_math_neg value=`value`**
|
||||
|
||||
## sin
|
||||
+ `value`
|
||||
|
||||
**> host_math_sin value=`value`**
|
||||
|
||||
## cos
|
||||
+ `value`
|
||||
|
||||
**> host_math_cos value=`value`**
|
||||
|
||||
## tan
|
||||
+ `value`
|
||||
|
||||
**> host_math_tan value=`value`**
|
||||
|
||||
## asin
|
||||
+ `value`
|
||||
|
||||
**> host_math_asin value=`value`**
|
||||
|
||||
## acos
|
||||
+ `value`
|
||||
|
||||
**> host_math_acos value=`value`**
|
||||
|
||||
## atan
|
||||
+ `value`
|
||||
|
||||
**> host_math_atan value=`value`**
|
||||
|
||||
## sqrt
|
||||
+ `value`
|
||||
|
||||
**> host_math_sqrt value=`value`**
|
||||
|
||||
## abs
|
||||
+ `value`
|
||||
|
||||
**> host_math_abs value=`value`**
|
||||
|
||||
## ln
|
||||
+ `value`
|
||||
|
||||
**> host_math_ln value=`value`**
|
||||
|
||||
## exp
|
||||
+ `value`
|
||||
|
||||
**> host_math_exp value=`value`**
|
||||
|
||||
## floor
|
||||
+ `value`
|
||||
|
||||
**> host_math_floor value=`value`**
|
||||
|
||||
## ceil
|
||||
+ `value`
|
||||
|
||||
**> host_math_ceil value=`value`**
|
||||
|
||||
## min
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_min a=`a` b=`b`**
|
||||
|
||||
## max
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_max a=`a` b=`b`**
|
||||
|
||||
## random
|
||||
|
||||
**> host_random**
|
||||
|
||||
## random_int
|
||||
+ `min`
|
||||
+ `max`
|
||||
|
||||
**> host_random_int min=`min` max=`max`**
|
||||
|
||||
## seed
|
||||
+ `value`
|
||||
|
||||
**> host_seed value=`value`**
|
||||
|
||||
## formula
|
||||
+ `text`
|
||||
|
||||
**> host_formula value=`text`**
|
||||
|
||||
## simplify
|
||||
+ `formula`
|
||||
|
||||
**> host_simplify value=`formula`**
|
||||
|
||||
## expand
|
||||
+ `formula`
|
||||
|
||||
**> host_expand value=`formula`**
|
||||
|
||||
## diff
|
||||
+ `formula`
|
||||
+ `var`
|
||||
|
||||
**> host_diff formula=`formula` var=`var`**
|
||||
|
||||
## subs
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `value`
|
||||
|
||||
**> host_subs formula=`formula` var=`var` value=`value`**
|
||||
|
||||
## eval
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `value`
|
||||
|
||||
**> host_eval formula=`formula` var=`var` value=`value`**
|
||||
|
||||
## solve
|
||||
+ `formula`
|
||||
+ `var`
|
||||
|
||||
**> host_solve formula=`formula` var=`var`**
|
||||
|
||||
## plot
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `min`
|
||||
+ `max`
|
||||
|
||||
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
|
||||
|
||||
## plot_points
|
||||
+ `xs`
|
||||
+ `ys`
|
||||
|
||||
**> host_plot_points xs=`xs` ys=`ys`**
|
||||
|
||||
## plot_conic
|
||||
+ `kind`
|
||||
+ `a`
|
||||
|
||||
**> host_plot_conic kind=`kind` a=`a`**
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
title: lib/net
|
||||
description: English HTTP(S) wrappers. Optional headers / content_type via host aliases.
|
||||
---
|
||||
|
||||
## http_get
|
||||
+ `url`
|
||||
|
||||
HTTPS supported. Optional named arg `headers=` (map).
|
||||
|
||||
**> host_http_get url=`url`**
|
||||
|
||||
## http_post
|
||||
+ `url`
|
||||
+ `body`
|
||||
|
||||
Default content type is JSON. Optional `content_type=` / `headers=` (map).
|
||||
|
||||
**> host_http_post url=`url` body=`body`**
|
||||
|
||||
## http_request
|
||||
+ `method`
|
||||
+ `url`
|
||||
|
||||
Optional `body=` / `content_type=` / `headers=`.
|
||||
|
||||
**> host_http_request method=`method` url=`url`**
|
||||
|
||||
## url_encode
|
||||
+ `text`
|
||||
|
||||
**> host_url_encode text=`text`**
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
title: lib/plugin
|
||||
description: Load optional native ABI plugins (.dll / .so / .dylib)
|
||||
---
|
||||
|
||||
## load
|
||||
+ `path`
|
||||
|
||||
**> host_plugin_load path=`path`**
|
||||
|
||||
## unload
|
||||
|
||||
**> host_plugin_unload**
|
||||
|
||||
## list
|
||||
|
||||
**> host_plugin_list**
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
title: lib/subtask
|
||||
description: Concurrent subtasks — file, function, or foreign code
|
||||
---
|
||||
|
||||
## spawn
|
||||
+ `path`=None
|
||||
+ `fn`=None
|
||||
+ `args`=None
|
||||
+ `code`=None
|
||||
+ `lang`=None
|
||||
+ `source`=None
|
||||
+ `stdin`=None
|
||||
|
||||
**> host_subtask_spawn path=`path` fn=`fn` args=`args` code=`code` lang=`lang` source=`source` stdin=`stdin`**
|
||||
|
||||
## poll
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_poll id=`id`**
|
||||
|
||||
## wait
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_join id=`id`**
|
||||
|
||||
## kill
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_kill id=`id`**
|
||||
|
||||
## wait_all
|
||||
|
||||
**> host_subtask_wait_all**
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
title: lib/sys
|
||||
description: English system wrappers (load_dotenv accepts optional path via host alias)
|
||||
---
|
||||
|
||||
## env_get
|
||||
+ `name`
|
||||
|
||||
**> host_env_get name=`name`**
|
||||
|
||||
## env_set
|
||||
+ `name`
|
||||
+ `value`
|
||||
|
||||
**> host_env_set name=`name` value=`value`**
|
||||
|
||||
## load_dotenv
|
||||
|
||||
Load `.env` (optional named arg `path=`). Existing process env is not overridden.
|
||||
|
||||
**> host_dotenv_load**
|
||||
|
||||
## args
|
||||
|
||||
**> host_args**
|
||||
|
||||
## cwd
|
||||
|
||||
**> host_cwd**
|
||||
|
||||
## exit
|
||||
+ `code`
|
||||
|
||||
**> host_exit code=`code`**
|
||||
|
||||
## exec
|
||||
+ `cmd`
|
||||
|
||||
**> host_exec cmd=`cmd`**
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
title: lib/table
|
||||
description: English table helpers over len / at
|
||||
---
|
||||
|
||||
## rows
|
||||
+ `xs`
|
||||
|
||||
**> len `xs`**
|
||||
|
||||
## row_at
|
||||
+ `xs`
|
||||
+ `i`
|
||||
|
||||
**> at value=`xs` index=`i`**
|
||||
@@ -1,21 +0,0 @@
|
||||
---
|
||||
title: lib/text
|
||||
description: English text helpers over trim / split / join
|
||||
---
|
||||
|
||||
## str_trim
|
||||
+ `s`
|
||||
|
||||
**> trim `s`**
|
||||
|
||||
## str_split
|
||||
+ `s`
|
||||
+ `sep`
|
||||
|
||||
**> split value=`s` sep=`sep`**
|
||||
|
||||
## str_join
|
||||
+ `xs`
|
||||
+ `sep`
|
||||
|
||||
**> join value=`xs` sep=`sep`**
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
title: lib/time
|
||||
description: English time wrappers
|
||||
---
|
||||
|
||||
## now_unix
|
||||
|
||||
**> host_now_unix**
|
||||
|
||||
## now_ms
|
||||
|
||||
**> host_now_ms**
|
||||
|
||||
## format
|
||||
+ `unix`
|
||||
+ `pattern`
|
||||
|
||||
**> host_format_time unix=`unix` pattern=`pattern`**
|
||||
|
||||
## sleep_ms
|
||||
+ `ms`
|
||||
|
||||
**> host_sleep_ms ms=`ms`**
|
||||
|
||||
## parse
|
||||
+ `text`
|
||||
+ `pattern`
|
||||
|
||||
**> host_parse_time text=`text` pattern=`pattern`**
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
title: lib/writeback
|
||||
description: Persist run output in .mq.md (Jupyter-style writeback)
|
||||
---
|
||||
|
||||
## record
|
||||
+ `value`
|
||||
+ `at_end`=False
|
||||
|
||||
Write `value` to `<!-- marqdo-out … -->` in the entry file. Default: insert or replace the block immediately below the call; `at_end=true` appends a single block at EOF.
|
||||
|
||||
**> host_writeback_record value=`value` at_end=`at_end`**
|
||||
|
||||
## get
|
||||
+ `at_end`=False
|
||||
|
||||
Read persisted output for the current call site (adjacent block), or the EOF block when `at_end=true`.
|
||||
|
||||
**> host_writeback_get at_end=`at_end`**
|
||||
|
||||
## clear
|
||||
+ `at_end`=False
|
||||
|
||||
Remove the adjacent or EOF output block.
|
||||
|
||||
**> host_writeback_clear at_end=`at_end`**
|
||||
|
||||
## list
|
||||
|
||||
List all output blocks in the entry file.
|
||||
|
||||
**> host_writeback_list**
|
||||
@@ -1,25 +0,0 @@
|
||||
---
|
||||
title: lib/外联
|
||||
description: 通过本机解释器运行绑定的代码围栏与内联源码
|
||||
---
|
||||
|
||||
## 设置命令
|
||||
+ `语言`
|
||||
+ `命令`
|
||||
|
||||
**> host_foreign_set_cmd lang=`语言` cmd=`命令`**
|
||||
|
||||
## 运行
|
||||
+ `代码`
|
||||
|
||||
**> host_foreign_run code=`代码`**
|
||||
|
||||
## 按语言运行
|
||||
+ `语言`
|
||||
+ `源码`
|
||||
|
||||
**> host_foreign_run_lang lang=`语言` source=`源码`**
|
||||
|
||||
## 语言表
|
||||
|
||||
**> host_foreign_langs**
|
||||
@@ -1,34 +0,0 @@
|
||||
---
|
||||
title: lib/子任务
|
||||
description: 并发子任务 — 文件、函数或外联代码
|
||||
---
|
||||
|
||||
## 启动
|
||||
+ `路径`=None
|
||||
+ `函数`=None
|
||||
+ `参数`=None
|
||||
+ `代码`=None
|
||||
+ `语言`=None
|
||||
+ `源码`=None
|
||||
+ `输入`=None
|
||||
|
||||
**> host_subtask_spawn path=`路径` fn=`函数` args=`参数` code=`代码` lang=`语言` source=`源码` stdin=`输入`**
|
||||
|
||||
## 探测
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_poll id=`id`**
|
||||
|
||||
## 等待
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_join id=`id`**
|
||||
|
||||
## 终止
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_kill id=`id`**
|
||||
|
||||
## 等待全部
|
||||
|
||||
**> host_subtask_wait_all**
|
||||
@@ -1,17 +0,0 @@
|
||||
---
|
||||
title: lib/插件
|
||||
description: 加载可选原生 ABI 插件(.dll / .so / .dylib)
|
||||
---
|
||||
|
||||
## 加载
|
||||
+ `路径`
|
||||
|
||||
**> host_plugin_load path=`路径`**
|
||||
|
||||
## 卸载
|
||||
|
||||
**> host_plugin_unload**
|
||||
|
||||
## 列出
|
||||
|
||||
**> host_plugin_list**
|
||||
-200
@@ -1,200 +0,0 @@
|
||||
---
|
||||
title: lib/数学
|
||||
description: 高中数学 — 数值、随机、公式、作图
|
||||
---
|
||||
|
||||
## 圆周率
|
||||
|
||||
**> host_pi**
|
||||
|
||||
## 自然底数
|
||||
|
||||
**> host_e**
|
||||
|
||||
## 数
|
||||
+ `value`
|
||||
|
||||
**> host_num value=`value`**
|
||||
|
||||
## 加
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_add a=`a` b=`b`**
|
||||
|
||||
## 减
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_sub a=`a` b=`b`**
|
||||
|
||||
## 乘
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_mul a=`a` b=`b`**
|
||||
|
||||
## 除
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_div a=`a` b=`b`**
|
||||
|
||||
## 幂
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_pow a=`a` b=`b`**
|
||||
|
||||
## 负
|
||||
+ `value`
|
||||
|
||||
**> host_math_neg value=`value`**
|
||||
|
||||
## 正弦
|
||||
+ `value`
|
||||
|
||||
**> host_math_sin value=`value`**
|
||||
|
||||
## 余弦
|
||||
+ `value`
|
||||
|
||||
**> host_math_cos value=`value`**
|
||||
|
||||
## 正切
|
||||
+ `value`
|
||||
|
||||
**> host_math_tan value=`value`**
|
||||
|
||||
## 反正弦
|
||||
+ `value`
|
||||
|
||||
**> host_math_asin value=`value`**
|
||||
|
||||
## 反余弦
|
||||
+ `value`
|
||||
|
||||
**> host_math_acos value=`value`**
|
||||
|
||||
## 反正切
|
||||
+ `value`
|
||||
|
||||
**> host_math_atan value=`value`**
|
||||
|
||||
## 平方根
|
||||
+ `value`
|
||||
|
||||
**> host_math_sqrt value=`value`**
|
||||
|
||||
## 绝对值
|
||||
+ `value`
|
||||
|
||||
**> host_math_abs value=`value`**
|
||||
|
||||
## 对数
|
||||
+ `value`
|
||||
|
||||
**> host_math_ln value=`value`**
|
||||
|
||||
## 指数
|
||||
+ `value`
|
||||
|
||||
**> host_math_exp value=`value`**
|
||||
|
||||
## 向下取整
|
||||
+ `value`
|
||||
|
||||
**> host_math_floor value=`value`**
|
||||
|
||||
## 向上取整
|
||||
+ `value`
|
||||
|
||||
**> host_math_ceil value=`value`**
|
||||
|
||||
## 最小
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_min a=`a` b=`b`**
|
||||
|
||||
## 最大
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_max a=`a` b=`b`**
|
||||
|
||||
## 随机
|
||||
|
||||
**> host_random**
|
||||
|
||||
## 随机整数
|
||||
+ `min`
|
||||
+ `max`
|
||||
|
||||
**> host_random_int min=`min` max=`max`**
|
||||
|
||||
## 设种子
|
||||
+ `value`
|
||||
|
||||
**> host_seed value=`value`**
|
||||
|
||||
## 公式
|
||||
+ `text`
|
||||
|
||||
**> host_formula value=`text`**
|
||||
|
||||
## 化简
|
||||
+ `formula`
|
||||
|
||||
**> host_simplify value=`formula`**
|
||||
|
||||
## 展开
|
||||
+ `formula`
|
||||
|
||||
**> host_expand value=`formula`**
|
||||
|
||||
## 求导
|
||||
+ `formula`
|
||||
+ `var`
|
||||
|
||||
**> host_diff formula=`formula` var=`var`**
|
||||
|
||||
## 代入
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `value`
|
||||
|
||||
**> host_subs formula=`formula` var=`var` value=`value`**
|
||||
|
||||
## 求值
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `value`
|
||||
|
||||
**> host_eval formula=`formula` var=`var` value=`value`**
|
||||
|
||||
## 求解
|
||||
+ `formula`
|
||||
+ `var`
|
||||
|
||||
**> host_solve formula=`formula` var=`var`**
|
||||
|
||||
## 绘图
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `min`
|
||||
+ `max`
|
||||
|
||||
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
|
||||
|
||||
## 绘点列
|
||||
+ `xs`
|
||||
+ `ys`
|
||||
|
||||
**> host_plot_points xs=`xs` ys=`ys`**
|
||||
|
||||
## 绘圆锥
|
||||
+ `kind`
|
||||
+ `a`
|
||||
|
||||
**> host_plot_conic kind=`kind` a=`a`**
|
||||
@@ -1,41 +0,0 @@
|
||||
---
|
||||
title: lib/文件
|
||||
description: 中文文件系统包装
|
||||
---
|
||||
|
||||
## 读文本
|
||||
+ `路径`
|
||||
|
||||
**> host_read_text path=`路径`**
|
||||
|
||||
## 写文本
|
||||
+ `路径`
|
||||
+ `内容`
|
||||
|
||||
**> host_write_text path=`路径` text=`内容`**
|
||||
|
||||
## 追加文本
|
||||
+ `路径`
|
||||
+ `内容`
|
||||
|
||||
**> host_append_text path=`路径` text=`内容`**
|
||||
|
||||
## 存在
|
||||
+ `路径`
|
||||
|
||||
**> host_exists path=`路径`**
|
||||
|
||||
## 列目录
|
||||
+ `路径`
|
||||
|
||||
**> host_list_dir path=`路径`**
|
||||
|
||||
## 建目录
|
||||
+ `路径`
|
||||
|
||||
**> host_make_dir path=`路径`**
|
||||
|
||||
## 删除
|
||||
+ `路径`
|
||||
|
||||
**> host_remove path=`路径`**
|
||||
@@ -1,21 +0,0 @@
|
||||
---
|
||||
title: lib/文本
|
||||
description: 中文文本库:去空白 / 拆分 / 拼接
|
||||
---
|
||||
|
||||
## 去空白
|
||||
+ `s`
|
||||
|
||||
**> trim `s`**
|
||||
|
||||
## 拆分
|
||||
+ `s`
|
||||
+ `sep`
|
||||
|
||||
**> split value=`s` sep=`sep`**
|
||||
|
||||
## 拼接
|
||||
+ `xs`
|
||||
+ `sep`
|
||||
|
||||
**> join value=`xs` sep=`sep`**
|
||||
@@ -1,29 +0,0 @@
|
||||
---
|
||||
title: lib/时间
|
||||
description: 中文时间包装
|
||||
---
|
||||
|
||||
## 此刻秒
|
||||
|
||||
**> host_now_unix**
|
||||
|
||||
## 此刻毫秒
|
||||
|
||||
**> host_now_ms**
|
||||
|
||||
## 格式化
|
||||
+ `秒`
|
||||
+ `格式`
|
||||
|
||||
**> host_format_time unix=`秒` pattern=`格式`**
|
||||
|
||||
## 睡眠毫秒
|
||||
+ `毫秒`
|
||||
|
||||
**> host_sleep_ms ms=`毫秒`**
|
||||
|
||||
## 解析时间
|
||||
+ `内容`
|
||||
+ `格式`
|
||||
|
||||
**> host_parse_time text=`内容` pattern=`格式`**
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
title: lib/系统
|
||||
description: 中文系统包装(加载环境 可选 路径=)
|
||||
---
|
||||
|
||||
## 取环境
|
||||
+ `名`
|
||||
|
||||
**> host_env_get name=`名`**
|
||||
|
||||
## 设环境
|
||||
+ `名`
|
||||
+ `值`
|
||||
|
||||
**> host_env_set name=`名` value=`值`**
|
||||
|
||||
## 加载环境
|
||||
|
||||
加载 `.env`(可选具名实参 `路径=`)。不覆盖已有进程环境变量。
|
||||
|
||||
**> host_dotenv_load**
|
||||
|
||||
## 参数表
|
||||
|
||||
**> host_args**
|
||||
|
||||
## 工作目录
|
||||
|
||||
**> host_cwd**
|
||||
|
||||
## 退出
|
||||
+ `码`
|
||||
|
||||
**> host_exit code=`码`**
|
||||
|
||||
## 执行
|
||||
+ `命令`
|
||||
|
||||
**> host_exec cmd=`命令`**
|
||||
@@ -1,32 +0,0 @@
|
||||
---
|
||||
title: lib/网络
|
||||
description: 中文 HTTP(S) 包装。可选 headers / content_type 经宿主别名绑定。
|
||||
---
|
||||
|
||||
## 获取
|
||||
+ `地址`
|
||||
|
||||
支持 HTTPS。可选具名实参 `headers=`(映射)。
|
||||
|
||||
**> host_http_get url=`地址`**
|
||||
|
||||
## 提交
|
||||
+ `地址`
|
||||
+ `内容`
|
||||
|
||||
默认 Content-Type 为 JSON。可选 `content_type=` / `headers=`。
|
||||
|
||||
**> host_http_post url=`地址` body=`内容`**
|
||||
|
||||
## 请求
|
||||
+ `方法`
|
||||
+ `地址`
|
||||
|
||||
可选 `body=` / `content_type=` / `headers=`。
|
||||
|
||||
**> host_http_request method=`方法` url=`地址`**
|
||||
|
||||
## 编码地址
|
||||
+ `内容`
|
||||
|
||||
**> host_url_encode text=`内容`**
|
||||
@@ -1,30 +0,0 @@
|
||||
---
|
||||
title: lib/自写回
|
||||
description: 将运行结果写回 .mq.md(Jupyter 式自写回)
|
||||
---
|
||||
|
||||
## 写回
|
||||
+ `值`
|
||||
+ `末尾`=False
|
||||
|
||||
在入口文件中写入 `<!-- marqdo-out … -->`。默认在调用行下方插入或替换;`末尾=true` 时在文件末尾保留单块。
|
||||
|
||||
**> host_writeback_record value=`值` at_end=`末尾`**
|
||||
|
||||
## 取
|
||||
+ `末尾`=False
|
||||
|
||||
读取当前调用处紧邻块,或 `末尾=true` 时读取文件末尾块。
|
||||
|
||||
**> host_writeback_get at_end=`末尾`**
|
||||
|
||||
## 清除
|
||||
+ `末尾`=False
|
||||
|
||||
删除紧邻块或末尾块。
|
||||
|
||||
**> host_writeback_clear at_end=`末尾`**
|
||||
|
||||
## 列出
|
||||
|
||||
**> host_writeback_list**
|
||||
-15
@@ -1,15 +0,0 @@
|
||||
---
|
||||
title: lib/表
|
||||
description: 中文表库:行数 / 取行
|
||||
---
|
||||
|
||||
## 行数
|
||||
+ `xs`
|
||||
|
||||
**> len `xs`**
|
||||
|
||||
## 取行
|
||||
+ `xs`
|
||||
+ `i`
|
||||
|
||||
**> at value=`xs` index=`i`**
|
||||
@@ -1,39 +0,0 @@
|
||||
---
|
||||
title: 人工文档
|
||||
description: 这是人工写的文档,禁止机器修改
|
||||
---
|
||||
|
||||
对于marqdo这个项目,详细的语法定义为:
|
||||
---
|
||||
|
||||
#标识对象,#main不算特殊这是一个项目的传统入口可以视为是一个对象。
|
||||
---
|
||||
##、### 、####等标识函数,不同数目表示从属关系,例如###是##函数的子函数,作用域不超过
|
||||
这个函数,使用-表示函数的变量名
|
||||
**** 空返回(None),并结束本函数体
|
||||
---
|
||||
无标记行表示注释信息,对于无标记行应该这么约定不是说开头没有符合不然就会出现:
|
||||
|
||||
**强调信息**是什么什么
|
||||
|
||||
上面应该是一个注释
|
||||
---
|
||||
程序语言使用*程序*也就是斜体表示
|
||||
---
|
||||
`变量名`表示变量
|
||||
---
|
||||
> 表示引用函数
|
||||
---
|
||||
有序列表表示分支语句
|
||||
---
|
||||
无序列表表示循环语句
|
||||
---
|
||||
公式由数学库渲染
|
||||
---
|
||||
代码片段由外联库渲染
|
||||
---
|
||||
添加一个新的标准库,自写回标准库,自写回的内容必须使用<!---->包裹,这个不会被md识别,
|
||||
但是这个可以被marqdo识别,当作提示信息或生成结果的一律表示,markdo view要能渲染,以某种方式
|
||||
---
|
||||
添加一个新的标准库,子任务库,能够自由的运行子任务,现在的调用还是顺序化的,但是子任务允许多个
|
||||
进程式的调用,子任务库将成为marqdo的护城河项目,子任务要依赖于父任务,父任务结束子任务一定结束,防止出现问题
|
||||
@@ -1,20 +0,0 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
这是人工构建的用于测试的样例
|
||||
|
||||
`测试目录` =
|
||||
|测试文件夹|
|
||||
|-----|
|
||||
|structure|
|
||||
|keyword|
|
||||
|lib|
|
||||
|
||||
|
||||
- [`测试文件夹`](`测试目录`)
|
||||
> 打印 `测试文件夹`
|
||||
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`a` = True*
|
||||
*`b` = False*
|
||||
|
||||
1. `a` and not `b`
|
||||
> print text=ok
|
||||
2. *
|
||||
> print text=fail
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试输入
|
||||
|
||||
*`name`=> input "你叫什么名字\n"*
|
||||
|
||||
> print `name`
|
||||
@@ -1,10 +0,0 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试输出
|
||||
|
||||
> print 欢迎你
|
||||
@@ -1,33 +0,0 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
> lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 + 2
|
||||
$$
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*`ty` = > type `f` *
|
||||
|
||||
> print text=`ty`
|
||||
|
||||
*`df` = > diff formula=`f` var=x *
|
||||
|
||||
> print text=`df`
|
||||
|
||||
*`roots` = > solve formula=`f` var=x *
|
||||
|
||||
> print text=`roots`
|
||||
|
||||
*`y` = > eval formula=`f` var=x value=3 *
|
||||
|
||||
> print text=`y`
|
||||
@@ -1,23 +0,0 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
> lib/writeback.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试写回库
|
||||
|
||||
*`name`=>input "你叫什么名字?\n"*
|
||||
|
||||
> record `name`
|
||||
<!-- marqdo-out
|
||||
123132
|
||||
-->
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试分支语句
|
||||
|
||||
* `bool_value` = True *
|
||||
|
||||
1. `bool_value` == True
|
||||
> print True
|
||||
2. *
|
||||
> print False
|
||||
@@ -1,15 +0,0 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试循环语句语句
|
||||
|
||||
*`n`=0*
|
||||
|
||||
- `n` < 42
|
||||
`n`=`n`+1
|
||||
|
||||
> print `n`
|
||||
@@ -1,14 +0,0 @@
|
||||
[package]
|
||||
name = "marqdo_plugin_agent"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo agent layout plugin (ABI v1 cdylib)"
|
||||
publish = false
|
||||
|
||||
[lib]
|
||||
name = "agent"
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
serde_json = "1"
|
||||
@@ -1,574 +0,0 @@
|
||||
//! Agent layout plugin (C ABI v1): find_root, ensure_layout, probe, scaffold.
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::path::{Component, Path, PathBuf};
|
||||
use std::ptr;
|
||||
|
||||
const ABI_VERSION: u32 = 1;
|
||||
const DEFAULT_MARKERS: &str = "agents,runbooks,marqdo.agent.json";
|
||||
const LAYOUT_DIRS: &[&str] = &["agents", "runbooks", "templates", "reports"];
|
||||
|
||||
type PluginFn = unsafe extern "C" fn(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
#[repr(C)]
|
||||
pub struct MarqdoHostApi {
|
||||
pub userdata: *mut c_void,
|
||||
pub register_fn: Option<
|
||||
unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
params: *const c_char,
|
||||
fn_ptr: PluginFn,
|
||||
) -> c_int,
|
||||
>,
|
||||
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
|
||||
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
|
||||
}
|
||||
|
||||
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
|
||||
unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn parse_args(args_json: *const c_char) -> Result<serde_json::Value, String> {
|
||||
if args_json.is_null() {
|
||||
return Err("null args".into());
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(args_json) }
|
||||
.to_str()
|
||||
.map_err(|_| "args not utf-8".to_string())?;
|
||||
serde_json::from_str(s).map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
fn arg_str<'a>(v: &'a serde_json::Value, key: &str) -> Result<&'a str, String> {
|
||||
v.get(key)
|
||||
.and_then(|x| x.as_str())
|
||||
.ok_or_else(|| format!("missing text `{key}`"))
|
||||
}
|
||||
|
||||
fn has_parent_escape(rel: &Path) -> bool {
|
||||
rel.components().any(|c| matches!(c, Component::ParentDir))
|
||||
}
|
||||
|
||||
fn find_root(start: &str, markers: &str) -> Result<PathBuf, String> {
|
||||
let markers: Vec<&str> = markers
|
||||
.split(',')
|
||||
.map(|s| s.trim())
|
||||
.filter(|s| !s.is_empty())
|
||||
.collect();
|
||||
if markers.is_empty() {
|
||||
return Err("empty markers".into());
|
||||
}
|
||||
let mut cur = PathBuf::from(start);
|
||||
if cur.as_os_str().is_empty() {
|
||||
cur = std::env::current_dir().map_err(|e| e.to_string())?;
|
||||
}
|
||||
if !cur.exists() {
|
||||
return Err(format!("start path missing: {}", cur.display()));
|
||||
}
|
||||
let mut cur = std::fs::canonicalize(&cur).map_err(|e| e.to_string())?;
|
||||
loop {
|
||||
for m in &markers {
|
||||
let p = cur.join(m);
|
||||
let ok = if m.contains('.') {
|
||||
p.is_file()
|
||||
} else {
|
||||
p.is_dir()
|
||||
};
|
||||
if ok {
|
||||
return Ok(cur);
|
||||
}
|
||||
}
|
||||
if !cur.pop() {
|
||||
break;
|
||||
}
|
||||
}
|
||||
Err("agent project root not found".into())
|
||||
}
|
||||
|
||||
fn ensure_layout(root: &Path) -> Result<i64, String> {
|
||||
let root = std::fs::canonicalize(root).map_err(|e| e.to_string())?;
|
||||
let mut created = 0i64;
|
||||
for d in LAYOUT_DIRS {
|
||||
let p = root.join(d);
|
||||
if !p.exists() {
|
||||
std::fs::create_dir_all(&p).map_err(|e| e.to_string())?;
|
||||
created += 1;
|
||||
} else if !p.is_dir() {
|
||||
return Err(format!("{} exists and is not a directory", p.display()));
|
||||
}
|
||||
}
|
||||
Ok(created)
|
||||
}
|
||||
|
||||
fn probe(root: &Path) -> Result<serde_json::Value, String> {
|
||||
let root = std::fs::canonicalize(root).map_err(|e| e.to_string())?;
|
||||
let mut map = serde_json::Map::new();
|
||||
map.insert(
|
||||
"root".into(),
|
||||
serde_json::Value::String(root.to_string_lossy().into_owned()),
|
||||
);
|
||||
for d in LAYOUT_DIRS {
|
||||
let key = format!("has_{d}");
|
||||
map.insert(key, serde_json::Value::Bool(root.join(d).is_dir()));
|
||||
}
|
||||
Ok(serde_json::Value::Object(map))
|
||||
}
|
||||
|
||||
fn scaffold(root: &Path, name: &str, template: &str, dest: &str) -> Result<String, String> {
|
||||
if name.is_empty() {
|
||||
return Err("name is empty".into());
|
||||
}
|
||||
let root = std::fs::canonicalize(root).map_err(|e| e.to_string())?;
|
||||
let tmpl_rel = Path::new(template);
|
||||
let dest_rel = Path::new(dest);
|
||||
if has_parent_escape(tmpl_rel) {
|
||||
return Err("template path escapes project root".into());
|
||||
}
|
||||
if has_parent_escape(dest_rel) {
|
||||
return Err("dest path escapes project root".into());
|
||||
}
|
||||
let tmpl_path = root.join(tmpl_rel);
|
||||
if !tmpl_path.is_file() {
|
||||
return Err(format!("template not found: {}", tmpl_path.display()));
|
||||
}
|
||||
let tmpl_can = std::fs::canonicalize(&tmpl_path).map_err(|e| e.to_string())?;
|
||||
if !tmpl_can.starts_with(&root) {
|
||||
return Err("template path escapes project root".into());
|
||||
}
|
||||
let dest_path = root.join(dest_rel);
|
||||
if let Some(parent) = dest_path.parent() {
|
||||
std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
|
||||
let parent_can = std::fs::canonicalize(parent).map_err(|e| e.to_string())?;
|
||||
if !parent_can.starts_with(&root) {
|
||||
return Err("dest path escapes project root".into());
|
||||
}
|
||||
}
|
||||
let body = std::fs::read_to_string(&tmpl_can).map_err(|e| e.to_string())?;
|
||||
let body = body.replace("{{name}}", name);
|
||||
std::fs::write(&dest_path, body).map_err(|e| e.to_string())?;
|
||||
Ok(dest_path.to_string_lossy().into_owned())
|
||||
}
|
||||
|
||||
fn map_get_str<'a>(m: &'a serde_json::Value, keys: &[&str]) -> Option<&'a str> {
|
||||
let obj = m.as_object()?;
|
||||
for k in keys {
|
||||
if let Some(v) = obj.get(*k) {
|
||||
if let Some(s) = v.as_str() {
|
||||
return Some(s);
|
||||
}
|
||||
if let Some(n) = v.as_i64() {
|
||||
// allow numeric fields to be read as display later
|
||||
let _ = n;
|
||||
}
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
fn map_get_i64(m: &serde_json::Value, keys: &[&str]) -> i64 {
|
||||
let Some(obj) = m.as_object() else {
|
||||
return i64::MAX;
|
||||
};
|
||||
for k in keys {
|
||||
if let Some(v) = obj.get(*k) {
|
||||
if let Some(n) = v.as_i64() {
|
||||
return n;
|
||||
}
|
||||
if let Some(s) = v.as_str() {
|
||||
if let Ok(n) = s.parse::<i64>() {
|
||||
return n;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
i64::MAX
|
||||
}
|
||||
|
||||
fn skills_text(m: &serde_json::Value) -> String {
|
||||
map_get_str(m, &["技能", "skills", "skill"])
|
||||
.unwrap_or("")
|
||||
.to_string()
|
||||
}
|
||||
|
||||
fn match_skill(skill: &str, members: &serde_json::Value) -> Result<serde_json::Value, String> {
|
||||
let arr = members
|
||||
.as_array()
|
||||
.ok_or_else(|| "members must be a JSON array".to_string())?;
|
||||
let skill = skill.trim();
|
||||
if skill.is_empty() {
|
||||
return Err("skill is empty".into());
|
||||
}
|
||||
let mut best: Option<&serde_json::Value> = None;
|
||||
let mut best_load = i64::MAX;
|
||||
for m in arr {
|
||||
let sk = skills_text(m);
|
||||
if sk.split(',').any(|p| p.trim() == skill) || sk.contains(skill) {
|
||||
let load = map_get_i64(m, &["负载", "load"]);
|
||||
if load < best_load {
|
||||
best_load = load;
|
||||
best = Some(m);
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(best.cloned().unwrap_or(serde_json::Value::Null))
|
||||
}
|
||||
|
||||
fn bump_load(member: &serde_json::Value, delta: i64) -> Result<serde_json::Value, String> {
|
||||
let mut obj = member
|
||||
.as_object()
|
||||
.cloned()
|
||||
.ok_or_else(|| "member must be a JSON object".to_string())?;
|
||||
let key = if obj.contains_key("负载") {
|
||||
"负载"
|
||||
} else if obj.contains_key("load") {
|
||||
"load"
|
||||
} else {
|
||||
obj.insert("负载".into(), serde_json::Value::Number(0.into()));
|
||||
"负载"
|
||||
};
|
||||
let cur = match obj.get(key) {
|
||||
Some(serde_json::Value::Number(n)) => n.as_i64().unwrap_or(0),
|
||||
Some(serde_json::Value::String(s)) => s.parse().unwrap_or(0),
|
||||
_ => 0,
|
||||
};
|
||||
obj.insert(
|
||||
key.into(),
|
||||
serde_json::Value::Number((cur + delta).into()),
|
||||
);
|
||||
Ok(serde_json::Value::Object(obj))
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_find_root(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_find_root: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let start = match arg_str(&v, "start") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_find_root: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let markers = v
|
||||
.get("markers")
|
||||
.and_then(|x| x.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
.unwrap_or(DEFAULT_MARKERS);
|
||||
match find_root(start, markers) {
|
||||
Ok(p) => {
|
||||
let out = serde_json::Value::String(p.to_string_lossy().into_owned()).to_string();
|
||||
set_out(out_json, &out);
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_find_root: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_ensure_layout(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_ensure_layout: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let root = match arg_str(&v, "root") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_ensure_layout: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
match ensure_layout(Path::new(root)) {
|
||||
Ok(n) => {
|
||||
set_out(out_json, &n.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_ensure_layout: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_probe(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_probe: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let root = match arg_str(&v, "root") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_probe: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
match probe(Path::new(root)) {
|
||||
Ok(j) => {
|
||||
set_out(out_json, &j.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_probe: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_scaffold(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let root = match arg_str(&v, "root") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let name = match arg_str(&v, "name") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let template = match arg_str(&v, "template") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let dest = match arg_str(&v, "dest") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
match scaffold(Path::new(root), name, template, dest) {
|
||||
Ok(p) => {
|
||||
let out = serde_json::Value::String(p).to_string();
|
||||
set_out(out_json, &out);
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_match_skill(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_match_skill: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let skill = match arg_str(&v, "skill") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_match_skill: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let members = match v.get("members") {
|
||||
Some(m) => m.clone(),
|
||||
None => {
|
||||
set_err(err_msg, "agent_match_skill: missing members");
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
// members may be a JSON string (from Marqdo stringify) or already an array
|
||||
let members = if let Some(s) = members.as_str() {
|
||||
match serde_json::from_str::<serde_json::Value>(s) {
|
||||
Ok(j) => j,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_match_skill: members JSON: {e}"));
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
} else {
|
||||
members
|
||||
};
|
||||
match match_skill(skill, &members) {
|
||||
Ok(j) => {
|
||||
set_out(out_json, &j.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_match_skill: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_bump_load(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_bump_load: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let member = match v.get("member") {
|
||||
Some(m) => m.clone(),
|
||||
None => {
|
||||
set_err(err_msg, "agent_bump_load: missing member");
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let member = if let Some(s) = member.as_str() {
|
||||
match serde_json::from_str::<serde_json::Value>(s) {
|
||||
Ok(j) => j,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_bump_load: member JSON: {e}"));
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
} else {
|
||||
member
|
||||
};
|
||||
let delta = v.get("delta").and_then(|x| x.as_i64()).unwrap_or(1);
|
||||
match bump_load(&member, delta) {
|
||||
Ok(j) => {
|
||||
set_out(out_json, &j.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_bump_load: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn register(host: &MarqdoHostApi, name: &str, params: &str, fn_ptr: PluginFn) -> c_int {
|
||||
let register = match host.register_fn {
|
||||
Some(f) => f,
|
||||
None => return 1,
|
||||
};
|
||||
let n = CString::new(name).unwrap();
|
||||
let p = CString::new(params).unwrap();
|
||||
unsafe { register(host.userdata, n.as_ptr(), p.as_ptr(), fn_ptr) }
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
ABI_VERSION
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
if register(host, "agent_find_root", "start,markers", agent_find_root) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_ensure_layout", "root", agent_ensure_layout) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_probe", "root", agent_probe) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_scaffold",
|
||||
"root,name,template,dest",
|
||||
agent_scaffold,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_match_skill", "skill,members", agent_match_skill) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_bump_load", "member,delta", agent_bump_load) != 0 {
|
||||
return 1;
|
||||
}
|
||||
0
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {
|
||||
HOST_ALLOC = None;
|
||||
HOST_FREE = None;
|
||||
}
|
||||
@@ -1,14 +0,0 @@
|
||||
[package]
|
||||
name = "marqdo_plugin_demo"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Demo Marqdo ABI v1 plugin (cdylib)"
|
||||
publish = false
|
||||
|
||||
[lib]
|
||||
name = "demo"
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
serde_json = "1"
|
||||
@@ -1,170 +0,0 @@
|
||||
//! Demo Marqdo plugin (C ABI v1). Registers `demo_add` and `demo_echo`.
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::ptr;
|
||||
|
||||
const ABI_VERSION: u32 = 1;
|
||||
|
||||
type PluginFn = unsafe extern "C" fn(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
#[repr(C)]
|
||||
pub struct MarqdoHostApi {
|
||||
pub userdata: *mut c_void,
|
||||
pub register_fn: Option<
|
||||
unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
params: *const c_char,
|
||||
fn_ptr: PluginFn,
|
||||
) -> c_int,
|
||||
>,
|
||||
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
|
||||
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
|
||||
}
|
||||
|
||||
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
|
||||
unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn demo_add(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
if args_json.is_null() {
|
||||
set_err(err_msg, "demo_add: null args");
|
||||
return 1;
|
||||
}
|
||||
let s = match CStr::from_ptr(args_json).to_str() {
|
||||
Ok(s) => s,
|
||||
Err(_) => {
|
||||
set_err(err_msg, "demo_add: args not utf-8");
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let v: serde_json::Value = match serde_json::from_str(s) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("demo_add: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let a = v.get("a").and_then(|x| x.as_i64()).unwrap_or(0);
|
||||
let b = v.get("b").and_then(|x| x.as_i64()).unwrap_or(0);
|
||||
set_out(out_json, &(a + b).to_string());
|
||||
0
|
||||
}
|
||||
|
||||
unsafe extern "C" fn demo_echo(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
if args_json.is_null() {
|
||||
set_err(err_msg, "demo_echo: null args");
|
||||
return 1;
|
||||
}
|
||||
let s = match CStr::from_ptr(args_json).to_str() {
|
||||
Ok(s) => s,
|
||||
Err(_) => {
|
||||
set_err(err_msg, "demo_echo: args not utf-8");
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let v: serde_json::Value = match serde_json::from_str(s) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("demo_echo: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let text = v
|
||||
.get("text")
|
||||
.and_then(|x| x.as_str())
|
||||
.unwrap_or("");
|
||||
let out = serde_json::Value::String(text.to_string()).to_string();
|
||||
set_out(out_json, &out);
|
||||
0
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
ABI_VERSION
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
let register = match host.register_fn {
|
||||
Some(f) => f,
|
||||
None => return 1,
|
||||
};
|
||||
let name_add = CString::new("demo_add").unwrap();
|
||||
let params_add = CString::new("a,b").unwrap();
|
||||
if register(
|
||||
host.userdata,
|
||||
name_add.as_ptr(),
|
||||
params_add.as_ptr(),
|
||||
demo_add,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
let name_echo = CString::new("demo_echo").unwrap();
|
||||
let params_echo = CString::new("text").unwrap();
|
||||
if register(
|
||||
host.userdata,
|
||||
name_echo.as_ptr(),
|
||||
params_echo.as_ptr(),
|
||||
demo_echo,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
0
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {
|
||||
HOST_ALLOC = None;
|
||||
HOST_FREE = None;
|
||||
}
|
||||
@@ -1,55 +0,0 @@
|
||||
---
|
||||
title: Welcome to Marqdo
|
||||
description: User docs home — code is documentation (English)
|
||||
> lib/math.mq.md
|
||||
> lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Hi — thanks for reading this far. I am Marqdo’s developer. Marqdo is a language where **code is documentation, and documentation is code**: Markdown markers are the program structure, so what you read is what runs.
|
||||
|
||||
AI already prefers Markdown-shaped output. The idea was: why keep docs and code as two separate worlds? So Marqdo was born as a “docs are code” language. To keep every source renderable as Markdown, files use the `.mq.md` suffix. From early on we aimed for richer tooling — auto-generated YAML for OKF-style knowledge bases, even auto-generated slides — those are later goals. Happily, it already works well as a blogging tool: yes, this site is generated by Marqdo. And when AI writes Marqdo, you tend to burn fewer tokens — wallets everywhere thank you.
|
||||
|
||||
The language is still young: structure markers, bilingual core names (`print` / `打印`, …), importable stdlibs (see [`stdlib/`](stdlib/) on this site), local `view`, and static export. Contribute on [GitHub](https://github.com/cflmy/marqdo).
|
||||
|
||||
中文文档请看同目录的 [`00-欢迎.mq.md`](00-欢迎.mq.md)(叙述与内置均用中文)。
|
||||
|
||||
A small function to say hello:
|
||||
|
||||
> greet who=marqdo
|
||||
|
||||
Named args can include spaces:
|
||||
|
||||
> greet who=marqdo user
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Welcome, `who`!
|
||||
|
||||
---
|
||||
|
||||
Beyond the basics above, Marqdo also ships standard libraries: table, time, text, files, system, math, foreign, and more.
|
||||
|
||||
Math and foreign deserve a special mention. With the math library you can bind a formula like this:
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
Then plot it:
|
||||
|
||||
*`_svg` = > plot formula=`f` var=x min=-3 max=3 *
|
||||
|
||||
The foreign library lets you call external code, for example:
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
|
||||
Under Markdown this stays easy to read — which is the point: Marqdo’s design is code as documentation, documentation as code.
|
||||
|
||||
Welcome again — enjoy exploring Marqdo.
|
||||
@@ -1,56 +0,0 @@
|
||||
---
|
||||
title: 欢迎使用 Marqdo
|
||||
description: 用户文档首页 — 代码即文档(中文版)
|
||||
> lib/数学.mq.md
|
||||
> lib/外联.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
阅读到这里的朋友你好!我是 Marqdo 的开发者。Marqdo 是一门**代码即文档,文档即代码**的语言:Markdown 标记就是程序结构,你读到的就是能跑的程序。
|
||||
|
||||
AI 偏爱 Markdown结构的输出。作者的念头是:何必再把文档和代码拆成两套?我们来实现一个文档即代码的语言,所以marqdo应运而生,为了确保代码一定可以被渲染,marqdo的文件后缀定义为了`.mq.md`。在开发之处我们就尝试希望更丰富的支持,自动生成一个yaml文件使得 OKF 式知识库便捷的自动配置,乃至自动生成ppt,自然这都是以后的目标了。不过相当不错的是,至少这会成为一个不错的博客工具——对,这个站点就是 Marqdo 生成的,而且AI输出的时候会节约不少token,你知道的,token烧的太多,钱包会可怜的饿瘦的。
|
||||
|
||||
语言仍在起步:结构标记、中英内核双名(`打印` / `print` …)、可导入的标准库(见本站 [`stdlib/`](stdlib/))、本地 `view` 与静态导出。欢迎到 [GitHub](https://github.com/cflmy/marqdo) 一起做。
|
||||
|
||||
English docs: [`00-welcome.mq.md`](00-welcome.mq.md) (English prose and English builtins).
|
||||
|
||||
用一个小函数打个招呼:
|
||||
|
||||
> 问候 谁=marqdo
|
||||
|
||||
具名实参可以带空格:
|
||||
|
||||
> 问候 谁=marqdo user
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> 打印 内容=欢迎,`谁`!
|
||||
|
||||
---
|
||||
|
||||
除了上面的一些基本内容之外,我还开发了这个语言的一些标准库,包括表、时间、文本、文件、系统、数学和外联等标准库。
|
||||
|
||||
其中数学库和外联库是我要着重提到的,例如数学库,你可以通过下面的方式调用:
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
之后让我们画个图像吧!
|
||||
|
||||
*`_svg` = > 绘图 formula=`f` var=x min=-3 max=3 *
|
||||
|
||||
外联库则允许你调用外部代码,例如:
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
|
||||
这些代码在markdown下面都非常的易读,就像我说的,marqdo的设计思想就是代码即文档,
|
||||
文档即代码。
|
||||
|
||||
最后,再次欢迎你,尽情体验marqdo吧!
|
||||
@@ -1,28 +0,0 @@
|
||||
# 用户文档(可执行 · 可下载 · 中英双语)
|
||||
|
||||
本目录即面向访客的 Marqdo 介绍:每个 `.mq.md` 既是文稿也能 `marqdo run`,并随仓库 / 静态站一起下载。
|
||||
|
||||
**双语约定:** 拉丁文件名 → 英文叙述与英文内置;中文文件名 → 中文叙述与中文编程。成对放在同一目录。标准库:拉丁路径用英文 API,中文路径用中文 API;JSON 仅 `lib/json.mq.md`。
|
||||
|
||||
| 路径 | 内容 |
|
||||
|------|------|
|
||||
| [`00-welcome.mq.md`](00-welcome.mq.md) / [`00-欢迎.mq.md`](00-欢迎.mq.md) | 首页(英 / 中) |
|
||||
| [`structure/`](structure/) | 基本结构 |
|
||||
| [`keywords/`](keywords/) | 关键字与 L0 内置 |
|
||||
| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联/插件/**自写回**/**子任务**;v0.1.2+ 内置于 CLI) |
|
||||
| [`features/`](features/) | 特性迭代(含对象、官方 `ext/`) |
|
||||
|
||||
官方扩展(非 stdlib):`ext/llm`、`ext/agent` — 见 `features/05-extensions.mq.md` / `05-扩展.mq.md` 与 `doc/design/ext-*.md`。
|
||||
|
||||
**不放** `errors/`:失败样例只在 `tests/errors/`。
|
||||
|
||||
开发文档在 [`doc/`](../doc/)。
|
||||
|
||||
## 浏览与生成 HTML
|
||||
|
||||
```bash
|
||||
cargo run -- view public
|
||||
cargo run -- view output public -o public
|
||||
```
|
||||
|
||||
详见 [user-site.md](../doc/design/user-site.md)。
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
title: Phase I — tree-walk interpreter
|
||||
description: Lex · parse · check · tree-walk end to end
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Milestone: Phase I (tree-walk).
|
||||
|
||||
Pipeline: load → line classify → recursive-descent parse → semantic check → tree-walk eval. No Flex/Bison.
|
||||
|
||||
This page runs as a program — documentation is executable:
|
||||
|
||||
> print text=Phase I: tree-walk interpreter is live.
|
||||
@@ -1,14 +0,0 @@
|
||||
---
|
||||
title: 第一阶段 — 树遍历解释器
|
||||
description: 词法 · 语法 · 语义 · 树遍历已贯通
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
里程碑:第一阶段(树遍历)。
|
||||
|
||||
流水线:加载 → 行分类 → 递归下降语法 → 语义检查 → 树遍历执行。实现不用 Flex/Bison。
|
||||
|
||||
本页本身即可运行,证明「文档即程序」已落地:
|
||||
|
||||
> 打印 内容=第一阶段:树遍历解释器已就绪。
|
||||
@@ -1,18 +0,0 @@
|
||||
---
|
||||
title: Bytecode backend
|
||||
description: `--backend bytecode` shares semantics with tree-walk
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Milestone: bytecode prototype.
|
||||
|
||||
The same `.mq.md` runs on tree-walk or the bytecode VM:
|
||||
|
||||
marqdo run FILE --backend tree
|
||||
|
||||
marqdo run FILE --backend bytecode
|
||||
|
||||
Output matches on both backends:
|
||||
|
||||
> print text=Bytecode backend: same program, alternate engine.
|
||||
@@ -1,18 +0,0 @@
|
||||
---
|
||||
title: 字节码后端
|
||||
description: `--backend bytecode` 与树遍历共用语义
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
里程碑:字节码原型。
|
||||
|
||||
同一套 `.mq.md` 可用树遍历或字节码 VM:
|
||||
|
||||
marqdo run FILE --backend tree
|
||||
|
||||
marqdo run FILE --backend bytecode
|
||||
|
||||
两种后端输出一致:
|
||||
|
||||
> 打印 内容=字节码后端:同一程序,另一引擎。
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
title: view and the user docs site
|
||||
description: Local browse and static export from the interpreter
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Milestone: `marqdo view` and `view output`.
|
||||
|
||||
Local: `marqdo view public`
|
||||
|
||||
Static export: `marqdo view output public -o public`
|
||||
|
||||
Executable user docs live under `public/`. Generated HTML (`index.html` / `pages/`) is for hosting; CI publishes to `gh-pages`.
|
||||
|
||||
> print text=Docs site: generated by the Marqdo interpreter, not hand-written HTML.
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
title: view 与用户文档站
|
||||
description: 本地浏览与静态导出由解释器生成
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
里程碑:`marqdo view` 与 `view output`。
|
||||
|
||||
本地浏览:`marqdo view public`
|
||||
|
||||
静态导出:`marqdo view output public -o public`
|
||||
|
||||
用户可执行文档在 `public/`;生成的 HTML(`index.html` / `pages/`)供静态托管,CI 发布到 `gh-pages`。
|
||||
|
||||
> 打印 内容=文档站:由 Marqdo 解释器生成,不是手写 HTML。
|
||||
@@ -1,12 +0,0 @@
|
||||
---
|
||||
title: Objects and methods
|
||||
description: Sharp heading is a type; deeper headings are functions or methods
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
In Marqdo, a single sharp (#) defines an object / type constructor. Double sharp and deeper (## …) define free functions or methods. Constructing an object yields a map handle tagged with _type. Call methods with backtick object, then dot, then method name.
|
||||
|
||||
See doc/design/objects.md. Example gold: tests/structure/object-handle.mq.md. Official ext/llm and ext/agent use this pattern.
|
||||
|
||||
> print text=objects-ok
|
||||
Loaded 100 of 284 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user