Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
2e65c055b8 | ||
|
|
3da7b276d3 | ||
|
|
63e5be80ab | ||
|
|
92d88fe761 | ||
|
|
c4ffb9473f | ||
|
|
3a7e11c995 | ||
|
|
b0c777c480 | ||
|
|
b00b018056 | ||
|
|
b974f10c6e | ||
|
|
72777a8c74 | ||
|
|
e08cd839be | ||
|
|
5309848292 | ||
|
|
1271aafcdd |
No files matched your search
@@ -0,0 +1,159 @@
|
||||
---
|
||||
name: marqdo
|
||||
description: >-
|
||||
Author and edit Marqdo programs (.mq.md): Markdown markers are executable
|
||||
syntax (functions, calls, statements, returns, control flow). Use when writing
|
||||
or modifying .mq.md files, teaching Marqdo, generating Marqdo from prose,
|
||||
importing lib/*, running marqdo CLI, or when the user mentions Marqdo,
|
||||
mq.md, markup-as-syntax, or code-as-documentation.
|
||||
---
|
||||
|
||||
# Marqdo development
|
||||
|
||||
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
|
||||
|
||||
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
|
||||
## Hard rules (do not violate)
|
||||
|
||||
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
|
||||
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
|
||||
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
|
||||
5. **Identifiers use backticks** — params `` + `name` ``, bindings `` `x` ``, foreach `` [`item`](`coll`) ``. **Complex text** uses `"..."` with escapes; bare tokens stay literal (no `\n` magic).
|
||||
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
|
||||
7. **Paths in bare expressions:** `/` is division. Prefer `` `path` `` vars, same-dir names, or call args — not raw `a/b` in expressions.
|
||||
8. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
|
||||
|
||||
## Markup → meaning (v0.2)
|
||||
|
||||
| Marker | Meaning |
|
||||
|--------|---------|
|
||||
| `#` | **Object / type** (constructor body). `# main` = entry object. |
|
||||
| `##` … `######` | **Function / method** (nesting by heading depth). |
|
||||
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
|
||||
| `1.` `2.` … in body | Branch arm (condition or `N. *` else) |
|
||||
| `- …` inside body | Loop (`while` or `` [`item`](`coll`) ``) |
|
||||
| Line `N. *` | Else arm |
|
||||
| `> fn args` | Call (named `k=v` or positional) |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter `> path.mq.md` | Import |
|
||||
| `*…*` | Statement (bind / expr) |
|
||||
| `**…**` | Return value |
|
||||
| `****` or `**` + spaces + `**` | Return `None` and end function body |
|
||||
| Lone `---` / `***` in function body | End function body (no value) |
|
||||
| GFM table after empty RHS bind | Collection |
|
||||
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
|
||||
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
|
||||
| Unmarked prose | Comment |
|
||||
|
||||
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
|
||||
|
||||
## Minimal program
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
Chinese builtins (same functions, no import):
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=你好
|
||||
```
|
||||
|
||||
## Functions, calls, end-body
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> greet who=Marqdo
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
- Call: `> name key=value` or `> name value`.
|
||||
- Nested helpers use deeper `#` (`##`, `###`, …).
|
||||
- After a helper with only side effects, end with `---` / `***`.
|
||||
|
||||
## Statements, returns, branches
|
||||
|
||||
```markdown
|
||||
*`x` = 1*
|
||||
*`y` = `x` + 2*
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
```markdown
|
||||
*`n` = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
2. `n` < 0
|
||||
> print text=negative
|
||||
3. *
|
||||
> print text=zero
|
||||
```
|
||||
|
||||
## Frontmatter imports + stdlib
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: example
|
||||
> lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`xs` = > split value=a,b,c sep=,*
|
||||
> print text=`xs`
|
||||
```
|
||||
|
||||
- Import **English** or **Chinese** library file; call that file’s API names (do not mix).
|
||||
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm` / `add agent` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — agent framework (layout + ABI; compose LLM per `doc/design/ext-agent.md`).
|
||||
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
|
||||
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
|
||||
Stdlib map: [reference.md](reference.md).
|
||||
|
||||
## AI authoring workflow
|
||||
|
||||
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
2. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
|
||||
3. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
|
||||
4. On `path:line:col: message`, fix that span; re-run until exit 0.
|
||||
5. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
|
||||
|
||||
## Anti-patterns (common model mistakes)
|
||||
|
||||
| Wrong | Right |
|
||||
|-------|-------|
|
||||
| `**Hello**` to print | `> print text=Hello` |
|
||||
| `# main` then prose then code with no blank line | Blank line before code |
|
||||
| `if x > 0:` | `1. `x` > 0` |
|
||||
| `* > print text=hi *` | `> print text=hi` |
|
||||
| Forgetting `---` after nested `##` helper | Add `---` / `***` / `****` |
|
||||
| Import `lib/text` then call `拆分` | Match file language |
|
||||
|
||||
## Checklist before finishing
|
||||
|
||||
- [ ] File ends with `.mq.md`
|
||||
- [ ] Print via `print` / `打印`, not bold
|
||||
- [ ] Blank lines separate comment paragraphs from code
|
||||
- [ ] `# main` exists when the file is an entry program
|
||||
- [ ] Nested functions ended with `---` / `***` / `****` when needed
|
||||
- [ ] Imports and call names share the same language file
|
||||
- [ ] `marqdo run` succeeds (or errors addressed)
|
||||
@@ -0,0 +1,162 @@
|
||||
# Marqdo examples (AI)
|
||||
|
||||
## 1. Hello (English)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
## 2. Hello (Chinese builtins)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=你好,世界!
|
||||
```
|
||||
|
||||
## 3. Function + named call + body end
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
Greeting via a nested function:
|
||||
|
||||
> greet who=Marqdo
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
## 4. Bindings and return
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*`a` = 2*
|
||||
*`b` = > add_one n=`a`*
|
||||
> print text=`b`
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
## 5. Branch with else
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*`n` = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
2. `n` < 0
|
||||
> print text=negative
|
||||
3. *
|
||||
> print text=zero
|
||||
```
|
||||
|
||||
## 6. Foreach loop
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`篮子` =
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
|
||||
- [`果`](`篮子`)
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
## 7. Import text stdlib
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: split demo
|
||||
> lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`parts` = > split value=a,b,c sep=,*
|
||||
> print text=`parts`
|
||||
```
|
||||
|
||||
## 8. Comment paragraphs (blank-line rule)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
This whole paragraph is a comment, including lines that look like code:
|
||||
*`not_executed` = 1*
|
||||
> print text=also still comment
|
||||
|
||||
After a blank line, code runs:
|
||||
|
||||
> print text=this runs
|
||||
```
|
||||
|
||||
## 9. Frontmatter import only
|
||||
|
||||
```markdown
|
||||
---
|
||||
description: loads math
|
||||
> lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`t` = > num value=3.5*
|
||||
> print text=`t`
|
||||
```
|
||||
|
||||
## 10. Object handle + method
|
||||
|
||||
See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` constructs a map with `_type`; methods use `` > `obj`.method `` and read `self` / `自`.
|
||||
|
||||
## 11. Agent layout (ABI)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load_native
|
||||
|
||||
*`ws` = > agent *
|
||||
*`n` = > `ws`.ensure_layout *
|
||||
> print text=`n`
|
||||
```
|
||||
|
||||
Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see `doc/design/ext-agent.md`).
|
||||
|
||||
## 12. What not to emit
|
||||
|
||||
```markdown
|
||||
# BAD — bold is return, not print
|
||||
**Hello**
|
||||
|
||||
# BAD — Python control keywords
|
||||
if x > 0:
|
||||
print(x)
|
||||
|
||||
# BAD — wrapping a call in italics
|
||||
*> print text=hi*
|
||||
|
||||
# BAD — old branch syntax (removed)
|
||||
+ `x` > 0
|
||||
|
||||
# GOOD — ordered list arms
|
||||
1. `x` > 0
|
||||
```
|
||||
@@ -0,0 +1,135 @@
|
||||
# Marqdo reference (AI)
|
||||
|
||||
Load this when you need stdlib names, CLI, or edge cases. Core rules stay in [SKILL.md](SKILL.md).
|
||||
|
||||
## CLI
|
||||
|
||||
```text
|
||||
marqdo --version
|
||||
marqdo run FILE.mq.md
|
||||
marqdo run FILE.mq.md --backend bytecode
|
||||
marqdo view PATH # docs browser, default port 7429
|
||||
marqdo debug PATH # debugger UI, default port 7430
|
||||
marqdo catalog PATH -o .marqdo
|
||||
marqdo ext list
|
||||
marqdo ext add llm|agent
|
||||
marqdo ext remove llm|agent
|
||||
```
|
||||
|
||||
Diagnostics look like `path:line:col: message` (1-based line/col).
|
||||
|
||||
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * ``; loops `` - [`item`](`coll`) ``; identifiers in backticks. See `doc/design/markdown-mapping.md`.
|
||||
|
||||
Stdlib search order for `lib/…` imports: `MARQDO_LIB`, `./lib`, directory of the `marqdo` executable (and a few parents). Prefer the **bundle zip** (`marqdo.exe` + `lib/`) over a bare exe.
|
||||
|
||||
官方扩展(`ext/…`,非 stdlib):`marqdo ext add` 装到 `MARQDO_EXT` 或 `~/.marqdo/ext`;导入仍写 `> ext/llm.mq.md`。解析还含 cwd `ext/`、二进制旁 `ext/`。对象:`doc/design/objects.md`。Agent:`doc/design/ext-agent.md` · 安装器:`doc/design/ext-cli.md`。
|
||||
|
||||
## Builtins (no import)
|
||||
|
||||
| EN | ZH | Role |
|
||||
|----|----|------|
|
||||
| `print` | `打印` | stdout; arg `text` / `内容` |
|
||||
| `input` | `输入` | one line; arg `prompt` / `提示` |
|
||||
| `len` | `长度` | length; arg `value` / `值` |
|
||||
| `str` | `文本` | to text; arg `value` / `值` |
|
||||
| `int` | `整数` | to int; arg `value` / `值` |
|
||||
|
||||
Keywords (not variable names): `True`/`真`, `False`/`假`, `None`/`空`, `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
|
||||
## Standard library files
|
||||
|
||||
Import one file; use **that** file’s function names.
|
||||
|
||||
| EN import | ZH import | Typical APIs (EN / ZH) |
|
||||
|-----------|-----------|-------------------------|
|
||||
| `lib/text.mq.md` | `lib/文本.mq.md` | text helpers / 去空白·拆分·拼接… |
|
||||
| `lib/table.mq.md` | `lib/表.mq.md` | table/rows helpers |
|
||||
| `lib/fs.mq.md` | `lib/文件.mq.md` | filesystem |
|
||||
| `lib/sys.mq.md` | `lib/系统.mq.md` | process / cwd / load_dotenv |
|
||||
| `lib/plugin.mq.md` | `lib/插件.mq.md` | load native ABI plugins (`doc/design/ext-abi.md`) |
|
||||
| `lib/time.mq.md` | `lib/时间.mq.md` | time/format |
|
||||
| `lib/net.mq.md` | `lib/网络.mq.md` | HTTP(S) helpers (+ optional headers) |
|
||||
| `lib/json.mq.md` | (see design) | JSON (+ `quote`) |
|
||||
| `lib/math.mq.md` | `lib/数学.mq.md` | num, trig, random, formula, plot |
|
||||
| `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks |
|
||||
| `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods |
|
||||
| `ext/agent.mq.md` | `ext/智能体.mq.md` | agent **framework** (layout now; LLM orchestration roadmap in `ext-agent.md`) |
|
||||
|
||||
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
|
||||
|
||||
## Formula + plot (math)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*`_svg` = > plot formula=`f` var=x min=-3 max=3 *
|
||||
```
|
||||
|
||||
Empty RHS assignment + following `$$…$$` binds a formula value. Narrative-only `$$` without binding is display, not assignment.
|
||||
|
||||
## Foreign (Python example)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`hi` =
|
||||
```python
|
||||
print("hello-from-python")
|
||||
```
|
||||
```
|
||||
|
||||
Lines starting with `` ` `` can be code (binding). Keep a blank line before/after fences per comment rules.
|
||||
|
||||
## Function-end details
|
||||
|
||||
| Form | Effect |
|
||||
|------|--------|
|
||||
| Lone `---` or `***` (≥3 same chars) at function body top level | End function; no return value |
|
||||
| `****` or empty bold | Return `None` and end body |
|
||||
| `**expr**` | Return `expr`; does **not** by itself cut off later sibling statements — still use HR or shallower heading |
|
||||
|
||||
File-leading paired `---` is frontmatter only; body `---` is not frontmatter.
|
||||
|
||||
## Call arguments
|
||||
|
||||
- Named: `> greet who=World`
|
||||
- Positional: `> greet World`
|
||||
- Spaces in values: allowed in named forms as in docs (`who=marqdo user`)
|
||||
- Inline call in statement: `` *`n` = > len value=`s`* ``
|
||||
|
||||
See `doc/design/call-arguments.md`.
|
||||
|
||||
## Identifiers
|
||||
|
||||
- Variables: `` `name` ``
|
||||
- Comparisons: `==` `>` `<` `>=` `<=`
|
||||
- Do not use keyword tokens as names
|
||||
|
||||
## Design docs (repo)
|
||||
|
||||
| Doc | Topic |
|
||||
|-----|--------|
|
||||
| `doc/design/markdown-mapping.md` | Syntax constitution |
|
||||
| `doc/design/objects.md` | `#` objects / `##` methods |
|
||||
| `doc/design/keywords.md` | Builtins / keywords |
|
||||
| `doc/design/return-hr-and-code-surface.md` | Function end / surfaces |
|
||||
| `doc/design/stdlib-i18n.md` | EN/ZH lib files |
|
||||
| `doc/design/stdlib-modules.md` | L1 modules including plugin |
|
||||
| `doc/design/ext-abi.md` | Native C ABI v1 |
|
||||
| `doc/design/ext-llm.md` | `ext/llm` |
|
||||
| `doc/design/ext-agent.md` | `ext/agent` agent **framework** (layout shipped; LLM orchestration roadmap) |
|
||||
| `doc/design/ext-cli.md` | `marqdo ext list/add/remove` |
|
||||
| `doc/design/view-debug.md` | view / debug hosts |
|
||||
@@ -14,13 +14,33 @@ jobs:
|
||||
runs-on: windows-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
with:
|
||||
fetch-depth: 0
|
||||
|
||||
- name: Install Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Install Node (VS Code extension)
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: "20"
|
||||
|
||||
- name: Build release
|
||||
run: cargo build --release
|
||||
|
||||
- name: Checkout extension sources (branch vscode-extension only)
|
||||
run: git fetch origin vscode-extension && git checkout origin/vscode-extension -- vscode-extension
|
||||
|
||||
- name: Build VSIX
|
||||
shell: pwsh
|
||||
run: |
|
||||
$ver = "${{ github.ref_name }}".TrimStart("v")
|
||||
Push-Location vscode-extension
|
||||
npm ci
|
||||
npm run compile
|
||||
npx @vscode/vsce package --no-dependencies -o "../dist/marqdo-$ver.vsix"
|
||||
Pop-Location
|
||||
|
||||
- name: Package
|
||||
shell: pwsh
|
||||
run: |
|
||||
@@ -29,17 +49,54 @@ jobs:
|
||||
New-Item -ItemType Directory -Force -Path dist | Out-Null
|
||||
$exe = "marqdo-$ver-$target.exe"
|
||||
$zip = "marqdo-$ver-$target.zip"
|
||||
$stdlib = "marqdo-$ver-stdlib.zip"
|
||||
$vsix = "marqdo-$ver.vsix"
|
||||
Copy-Item target/release/marqdo.exe "dist/$exe"
|
||||
Compress-Archive -Path "dist/$exe" -DestinationPath "dist/$zip" -Force
|
||||
$stage = "dist/stage-bundle"
|
||||
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path $stage | Out-Null
|
||||
Copy-Item target/release/marqdo.exe "$stage/marqdo.exe"
|
||||
Copy-Item lib "$stage/lib" -Recurse
|
||||
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
|
||||
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
|
||||
$stageLib = "dist/stage-stdlib"
|
||||
if (Test-Path $stageLib) { Remove-Item $stageLib -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path $stageLib | Out-Null
|
||||
Copy-Item lib "$stageLib/lib" -Recurse
|
||||
if (Test-Path "dist/$stdlib") { Remove-Item "dist/$stdlib" -Force }
|
||||
Compress-Archive -Path "$stageLib/*" -DestinationPath "dist/$stdlib" -Force
|
||||
echo "EXE=$exe" >> $env:GITHUB_ENV
|
||||
echo "ZIP=$zip" >> $env:GITHUB_ENV
|
||||
echo "STDLIB=$stdlib" >> $env:GITHUB_ENV
|
||||
echo "VSIX=$vsix" >> $env:GITHUB_ENV
|
||||
|
||||
- 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 }}
|
||||
+20
@@ -1,16 +1,36 @@
|
||||
/target/
|
||||
/dist/
|
||||
|
||||
# Copied by gold harness for ABI plugins
|
||||
/tests/lib/demo.dll
|
||||
/tests/lib/libdemo.so
|
||||
/tests/lib/libdemo.dylib
|
||||
/tests/ext/agent.dll
|
||||
/tests/ext/libagent.so
|
||||
/tests/ext/libagent.dylib
|
||||
/tests/ext/skel.mq.md
|
||||
/tests/ext/out-demo.mq.md
|
||||
/tests/ext/ticket.txt
|
||||
/tests/ext/ticket-stub.txt
|
||||
/tests/ext/agents/
|
||||
/tests/ext/runbooks/
|
||||
/tests/ext/templates/
|
||||
/tests/ext/reports/
|
||||
**/*.rs.bk
|
||||
.idea/
|
||||
.vscode/
|
||||
*.pdb
|
||||
.DS_Store
|
||||
.marqdo/
|
||||
.env
|
||||
|
||||
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
|
||||
/public/index.html
|
||||
/public/pages/
|
||||
|
||||
# VS Code extension: source only on branch `vscode-extension` (see doc/design/vscode-extension-commit.md)
|
||||
/vscode-extension/
|
||||
|
||||
# Python spike venv (local)
|
||||
spike/.venv/
|
||||
spike/__pycache__/
|
||||
|
||||
@@ -0,0 +1,22 @@
|
||||
# Changelog
|
||||
|
||||
## v0.1.2 — 2026-08-07
|
||||
|
||||
### Added
|
||||
- **Embedded standard library**: official `lib/*.mq.md` ships inside the `marqdo` binary; disk `lib/` and `MARQDO_LIB` still override.
|
||||
- **`lib/writeback`** / **`lib/subtask`**: Jupyter-style writeback; concurrent subtasks (file / function / foreign).
|
||||
- **Surface syntax v0.2**: `` + `param` `` parameters, `1.` ordered branches, backtick identifiers, quoted strings.
|
||||
- **`marqdo version --check`**: compare installed CLI with latest GitHub release.
|
||||
- **VS Code extension v0.0.6** (branch **`vscode-extension` only**): v0.2 grammar, update check — see [doc/design/vscode-extension-commit.md](doc/design/vscode-extension-commit.md)
|
||||
|
||||
### Changed
|
||||
- Subtask `spawn` accepts `path=`, `fn=`, `code=`, or `lang=`+`source=` (not file-only).
|
||||
- Release notes: standalone `.exe` includes stdlib; bundle/stdlib zips remain optional for overrides.
|
||||
|
||||
## v0.1.1
|
||||
|
||||
- v0.2 syntax migration, writeback/subtask v1 (file subprocess only), view input deferral, optional parameters.
|
||||
|
||||
## v0.1.0
|
||||
|
||||
- Initial public releases: tree + bytecode backends, `view` / `debug` / `catalog`, core stdlib, `ext/` installer.
|
||||
Generated
+399
-7
@@ -2,6 +2,12 @@
|
||||
# It is not intended for manual editing.
|
||||
version = 3
|
||||
|
||||
[[package]]
|
||||
name = "adler2"
|
||||
version = "2.0.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
|
||||
|
||||
[[package]]
|
||||
name = "aho-corasick"
|
||||
version = "1.1.5"
|
||||
@@ -13,9 +19,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "android_system_properties"
|
||||
version = "0.1.5"
|
||||
version = "0.1.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "819e7219dbd41043ac279b19830f2efc897156490d7fd6ea916720117ee66311"
|
||||
checksum = "ae221649c9976a6f6c56ae1facf410f3ddb33cc661c4b7b61020a912d4237fbc"
|
||||
dependencies = [
|
||||
"libc",
|
||||
]
|
||||
@@ -56,7 +62,7 @@ version = "1.1.5"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"
|
||||
dependencies = [
|
||||
"windows-sys",
|
||||
"windows-sys 0.61.2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -67,7 +73,7 @@ checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"
|
||||
dependencies = [
|
||||
"anstyle",
|
||||
"once_cell_polyfill",
|
||||
"windows-sys",
|
||||
"windows-sys 0.61.2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -103,6 +109,12 @@ version = "1.5.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
|
||||
|
||||
[[package]]
|
||||
name = "base64"
|
||||
version = "0.22.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
|
||||
|
||||
[[package]]
|
||||
name = "bitflags"
|
||||
version = "2.13.1"
|
||||
@@ -211,6 +223,15 @@ version = "0.8.7"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
|
||||
|
||||
[[package]]
|
||||
name = "crc32fast"
|
||||
version = "1.5.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "difflib"
|
||||
version = "0.4.0"
|
||||
@@ -229,6 +250,16 @@ version = "0.1.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582"
|
||||
|
||||
[[package]]
|
||||
name = "flate2"
|
||||
version = "1.1.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c"
|
||||
dependencies = [
|
||||
"crc32fast",
|
||||
"miniz_oxide",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "float-cmp"
|
||||
version = "0.9.0"
|
||||
@@ -238,6 +269,15 @@ dependencies = [
|
||||
"num-traits",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "form_urlencoded"
|
||||
version = "1.2.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"
|
||||
dependencies = [
|
||||
"percent-encoding",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "futures-core"
|
||||
version = "0.3.33"
|
||||
@@ -271,6 +311,17 @@ dependencies = [
|
||||
"unicode-width",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "getrandom"
|
||||
version = "0.2.17"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"libc",
|
||||
"wasi",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "heck"
|
||||
version = "0.4.1"
|
||||
@@ -307,6 +358,56 @@ dependencies = [
|
||||
"cc",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "idna"
|
||||
version = "1.1.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"
|
||||
dependencies = [
|
||||
"idna_adapter",
|
||||
"smallvec",
|
||||
"utf8_iter",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "idna_adapter"
|
||||
version = "1.1.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "279259b0ac81c89d11c290495fdcfa96ea3643b7df311c138b6fe8ca5237f0f8"
|
||||
dependencies = [
|
||||
"idna_mapping",
|
||||
"unicode-bidi",
|
||||
"unicode-normalization",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "idna_mapping"
|
||||
version = "1.1.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "11c13906586a4b339310541a274dd927aff6fcbb5b8e3af90634c4b31681c792"
|
||||
dependencies = [
|
||||
"unicode-joining-type",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "include_dir"
|
||||
version = "0.7.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "923d117408f1e49d914f1a379a309cffe4f18c05cf4e3d12e613a15fc81bd0dd"
|
||||
dependencies = [
|
||||
"include_dir_macros",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "include_dir_macros"
|
||||
version = "0.7.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7cab85a7ed0bd5f0e76d93846e0147172bed2e2d3f859bcc33a8d9699cad1a75"
|
||||
dependencies = [
|
||||
"proc-macro2",
|
||||
"quote",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "is_terminal_polyfill"
|
||||
version = "1.70.2"
|
||||
@@ -336,6 +437,16 @@ version = "0.2.189"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
|
||||
|
||||
[[package]]
|
||||
name = "libloading"
|
||||
version = "0.8.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "fc2f4eb4bc735547cfed7c0a4922cbd04a4655978c09b54f1f7b228750664c34"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"windows-targets",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "log"
|
||||
version = "0.4.33"
|
||||
@@ -344,17 +455,36 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "0.1.0"
|
||||
version = "0.1.2"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
"chrono",
|
||||
"clap",
|
||||
"idna_adapter",
|
||||
"include_dir",
|
||||
"libloading",
|
||||
"predicates",
|
||||
"pulldown-cmark",
|
||||
"serde_json",
|
||||
"thiserror",
|
||||
"tiny_http",
|
||||
"ureq",
|
||||
"zeroize",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_agent"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_demo"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -363,6 +493,16 @@ version = "2.8.3"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"
|
||||
|
||||
[[package]]
|
||||
name = "miniz_oxide"
|
||||
version = "0.8.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316"
|
||||
dependencies = [
|
||||
"adler2",
|
||||
"simd-adler32",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "normalize-line-endings"
|
||||
version = "0.3.0"
|
||||
@@ -390,6 +530,12 @@ version = "1.70.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
|
||||
|
||||
[[package]]
|
||||
name = "percent-encoding"
|
||||
version = "2.3.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
|
||||
|
||||
[[package]]
|
||||
name = "pin-project-lite"
|
||||
version = "0.2.17"
|
||||
@@ -477,9 +623,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "regex-automata"
|
||||
version = "0.4.16"
|
||||
version = "0.4.18"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8fcfdb36bda0c880c5931cdc7a2bcdc8ba4556847b9d912bca70bc94708711ad"
|
||||
checksum = "ad8553b9b26413251cbf30e620595c7a41b3887f03da04579c0e6b0d6a06b4b2"
|
||||
dependencies = [
|
||||
"aho-corasick",
|
||||
"memchr",
|
||||
@@ -492,6 +638,54 @@ version = "0.8.11"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
|
||||
|
||||
[[package]]
|
||||
name = "ring"
|
||||
version = "0.17.14"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"
|
||||
dependencies = [
|
||||
"cc",
|
||||
"cfg-if",
|
||||
"getrandom",
|
||||
"libc",
|
||||
"untrusted",
|
||||
"windows-sys 0.52.0",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustls"
|
||||
version = "0.22.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "bf4ef73721ac7bcd79b2b315da7779d8fc09718c6b3d2d1b2d94850eb8c18432"
|
||||
dependencies = [
|
||||
"log",
|
||||
"ring",
|
||||
"rustls-pki-types",
|
||||
"rustls-webpki",
|
||||
"subtle",
|
||||
"zeroize",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustls-pki-types"
|
||||
version = "1.15.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96"
|
||||
dependencies = [
|
||||
"zeroize",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustls-webpki"
|
||||
version = "0.102.8"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "64ca1bc8749bd4cf37b5ce386cc146580777b4e8572c7b97baf22c83f444bee9"
|
||||
dependencies = [
|
||||
"ring",
|
||||
"rustls-pki-types",
|
||||
"untrusted",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "rustversion"
|
||||
version = "1.0.23"
|
||||
@@ -546,18 +740,36 @@ version = "2.0.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"
|
||||
|
||||
[[package]]
|
||||
name = "simd-adler32"
|
||||
version = "0.3.10"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
|
||||
|
||||
[[package]]
|
||||
name = "slab"
|
||||
version = "0.4.12"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"
|
||||
|
||||
[[package]]
|
||||
name = "smallvec"
|
||||
version = "1.15.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8ed6a63f02c8539c91a8685a86f4099661ba3da017932f6ebbea6de3f0fa7c90"
|
||||
|
||||
[[package]]
|
||||
name = "strsim"
|
||||
version = "0.10.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "73473c0e59e6d5812c5dfe2a064a6444949f089e20eec9a2e5506596494e4623"
|
||||
|
||||
[[package]]
|
||||
name = "subtle"
|
||||
version = "2.6.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"
|
||||
|
||||
[[package]]
|
||||
name = "syn"
|
||||
version = "2.0.119"
|
||||
@@ -618,24 +830,101 @@ dependencies = [
|
||||
"log",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tinyvec"
|
||||
version = "1.12.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "bb4ebadaa0af04fab11ae01eb5f9fdb5f9c5b875506e210e71c07873528baa7f"
|
||||
dependencies = [
|
||||
"tinyvec_macros",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "tinyvec_macros"
|
||||
version = "0.1.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "1f3ccbac311fea05f86f61904b462b55fb3df8837a366dfc601a0161d0532f20"
|
||||
|
||||
[[package]]
|
||||
name = "unicase"
|
||||
version = "2.9.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "dbc4bc3a9f746d862c45cb89d705aa10f187bb96c76001afab07a0d35ce60142"
|
||||
|
||||
[[package]]
|
||||
name = "unicode-bidi"
|
||||
version = "0.3.18"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5c1cb5db39152898a79168971543b1cb5020dff7fe43c8dc468b0885f5e29df5"
|
||||
|
||||
[[package]]
|
||||
name = "unicode-ident"
|
||||
version = "1.0.24"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75"
|
||||
|
||||
[[package]]
|
||||
name = "unicode-joining-type"
|
||||
version = "1.0.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d8d00a78170970967fdb83f9d49b92f959ab2bb829186b113e4f4604ad98e180"
|
||||
|
||||
[[package]]
|
||||
name = "unicode-normalization"
|
||||
version = "0.1.25"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "5fd4f6878c9cb28d874b009da9e8d183b5abc80117c40bbd187a1fde336be6e8"
|
||||
dependencies = [
|
||||
"tinyvec",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "unicode-width"
|
||||
version = "0.2.2"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b4ac048d71ede7ee76d585517add45da530660ef4390e49b098733c6e897f254"
|
||||
|
||||
[[package]]
|
||||
name = "untrusted"
|
||||
version = "0.9.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"
|
||||
|
||||
[[package]]
|
||||
name = "ureq"
|
||||
version = "2.9.7"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d11a831e3c0b56e438a28308e7c810799e3c118417f342d30ecec080105395cd"
|
||||
dependencies = [
|
||||
"base64",
|
||||
"flate2",
|
||||
"log",
|
||||
"once_cell",
|
||||
"rustls",
|
||||
"rustls-pki-types",
|
||||
"rustls-webpki",
|
||||
"url",
|
||||
"webpki-roots 0.26.11",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "url"
|
||||
version = "2.5.8"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"
|
||||
dependencies = [
|
||||
"form_urlencoded",
|
||||
"idna",
|
||||
"percent-encoding",
|
||||
"serde",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "utf8_iter"
|
||||
version = "1.0.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"
|
||||
|
||||
[[package]]
|
||||
name = "utf8parse"
|
||||
version = "0.2.2"
|
||||
@@ -651,6 +940,12 @@ dependencies = [
|
||||
"libc",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "wasi"
|
||||
version = "0.11.1+wasi-snapshot-preview1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
|
||||
|
||||
[[package]]
|
||||
name = "wasm-bindgen"
|
||||
version = "0.2.126"
|
||||
@@ -696,6 +991,24 @@ dependencies = [
|
||||
"unicode-ident",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "webpki-roots"
|
||||
version = "0.26.11"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "521bc38abb08001b01866da9f51eb7c5d647a19260e00054a8c7fd5f9e57f7a9"
|
||||
dependencies = [
|
||||
"webpki-roots 1.0.9",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "webpki-roots"
|
||||
version = "1.0.9"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "7dcd9d09a39985f5344844e66b0c530a33843579125f23e21e9f0f220850f22a"
|
||||
dependencies = [
|
||||
"rustls-pki-types",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-core"
|
||||
version = "0.62.2"
|
||||
@@ -755,6 +1068,15 @@ dependencies = [
|
||||
"windows-link",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-sys"
|
||||
version = "0.52.0"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
|
||||
dependencies = [
|
||||
"windows-targets",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-sys"
|
||||
version = "0.61.2"
|
||||
@@ -764,6 +1086,76 @@ dependencies = [
|
||||
"windows-link",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows-targets"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
|
||||
dependencies = [
|
||||
"windows_aarch64_gnullvm",
|
||||
"windows_aarch64_msvc",
|
||||
"windows_i686_gnu",
|
||||
"windows_i686_gnullvm",
|
||||
"windows_i686_msvc",
|
||||
"windows_x86_64_gnu",
|
||||
"windows_x86_64_gnullvm",
|
||||
"windows_x86_64_msvc",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "windows_aarch64_gnullvm"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
|
||||
|
||||
[[package]]
|
||||
name = "windows_aarch64_msvc"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
|
||||
|
||||
[[package]]
|
||||
name = "windows_i686_gnu"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
|
||||
|
||||
[[package]]
|
||||
name = "windows_i686_gnullvm"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
|
||||
|
||||
[[package]]
|
||||
name = "windows_i686_msvc"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
|
||||
|
||||
[[package]]
|
||||
name = "windows_x86_64_gnu"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
|
||||
|
||||
[[package]]
|
||||
name = "windows_x86_64_gnullvm"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
|
||||
|
||||
[[package]]
|
||||
name = "windows_x86_64_msvc"
|
||||
version = "0.52.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
|
||||
|
||||
[[package]]
|
||||
name = "zeroize"
|
||||
version = "1.8.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ced3678a2879b30306d323f4542626697a464a97c0a07c9aebf7ebca65cd4dde"
|
||||
|
||||
[[package]]
|
||||
name = "zmij"
|
||||
version = "1.0.23"
|
||||
|
||||
+11
-1
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.1.0"
|
||||
version = "0.1.2"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -19,6 +19,16 @@ pulldown-cmark = "0.12"
|
||||
serde_json = "1"
|
||||
thiserror = "1"
|
||||
tiny_http = "0.12"
|
||||
# Pin for Cargo/rustc 1.81 (newer rustls/idna/zeroize need edition2024).
|
||||
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"] }
|
||||
idna_adapter = "=1.1.0"
|
||||
zeroize = "=1.8.1"
|
||||
libloading = "=0.8.6"
|
||||
include_dir = "0.7"
|
||||
|
||||
[workspace]
|
||||
members = ["plugins/demo", "plugins/agent"]
|
||||
resolver = "2"
|
||||
|
||||
[dev-dependencies]
|
||||
assert_cmd = "=2.0.14"
|
||||
|
||||
@@ -6,7 +6,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
||||
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · 金样例:[tests/](tests/) · 用户文档:[public/](public/)
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
|
||||
|
||||
---
|
||||
|
||||
@@ -23,31 +23,44 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
---
|
||||
|
||||
## 语法速览(v0.1)
|
||||
## 语法速览(v0.2)
|
||||
|
||||
| 标记 | 含义 |
|
||||
|------|------|
|
||||
| 无标记行 | 注释 |
|
||||
| 无标记行 | 注释(空行分段) |
|
||||
| `*…*` | 程序语句 |
|
||||
| `**…**` | **返回值**(架构) |
|
||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||||
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
|
||||
| `#` / `##` | 函数与作用域 |
|
||||
| `+` / `1.` | 分支(臂头单独 `*` = else) |
|
||||
| `-` | 循环(头下纯名则为形参) |
|
||||
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
|
||||
| `##` … | 函数 / 方法(按标题深度嵌套) |
|
||||
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
|
||||
| `+` / `1.` … | 函数头下 `` + `名` `` = 形参;体内 `1.` `2.` … = 分支(`N. *` = else) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [`项`](`集合`) ``) |
|
||||
| 表格 | 集合 |
|
||||
| `---` / `***` | 可选:框住分支/循环(不强制) |
|
||||
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
|
||||
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello `谁`!
|
||||
|
||||
---
|
||||
|
||||
## 加一
|
||||
- n
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
|
||||
完整约定:[markdown-mapping.md](doc/design/markdown-mapping.md)。
|
||||
|
||||
---
|
||||
|
||||
## 理念
|
||||
@@ -55,18 +68,48 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
1. **叙述默认安全**(无标记 = 注释)。
|
||||
2. **返回是架构;打印只是函数。**
|
||||
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
|
||||
4. **计划对齐 [OKF](doc/design/generated-yaml-manifest.md) 规范**:依赖与模块清单由工具生成(`marqdo catalog` / `sync`),不是手填配置——知识图谱与仓库结构同源生长。见 [catalog-cli.md](doc/design/catalog-cli.md)。
|
||||
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
|
||||
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
|
||||
|
||||
---
|
||||
|
||||
## 现状(v0.1.0)
|
||||
## OKF 风格清单(自动生成)
|
||||
|
||||
从源码派生 YAML / Markdown 知识包(勿手改生成物):
|
||||
|
||||
```bash
|
||||
marqdo catalog [PATH] -o OUT_DIR
|
||||
marqdo sync [PATH] -o OUT_DIR # catalog 的别名
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
|
||||
| `-o` / `--out` | `.marqdo` | 输出目录 |
|
||||
|
||||
产物示例:`catalog.yaml`、`index.md`、`modules/*.md`(`type: Marqdo Module` 等)。设计见 [generated-yaml-manifest.md](doc/design/generated-yaml-manifest.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
|
||||
|
||||
```bash
|
||||
cargo run -- catalog public -o .marqdo
|
||||
# 或已安装二进制时:
|
||||
marqdo catalog public -o .marqdo
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 现状(v0.1.2)
|
||||
|
||||
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Source)
|
||||
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430)
|
||||
- 标准库:文本、文件、系统、时间、JSON、网络、数学(公式/绘图)、外联(Python 等)
|
||||
- **`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
|
||||
@@ -74,11 +117,13 @@ cargo run -- run tests/structure/hello.mq.md
|
||||
cargo run -- run tests/structure/hello.mq.md --backend bytecode
|
||||
cargo run -- view public --no-open
|
||||
cargo run -- debug public --no-open
|
||||
cargo run -- catalog public -o .marqdo
|
||||
cargo run -- view output public -o public
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
cargo run -- catalog tests -o .marqdo
|
||||
```
|
||||
|
||||
**发布包(GitHub Releases)**:自 **v0.1.2** 起,单独 `.exe` **已内置**官方 `lib/`(`> lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发;`ext/` 与原生插件 `.dll` 仍须单独安装。`marqdo version --check` 可查看是否有新版本。OpenAI 兼容聊天见 [ext-llm.md](doc/design/ext-llm.md)。智能体布局见 [ext-agent.md](doc/design/ext-agent.md)。
|
||||
|
||||
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md)
|
||||
|
||||
---
|
||||
|
||||
+13
-4
@@ -16,6 +16,8 @@
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.1 语法宪法** |
|
||||
| [design/objects.md](design/objects.md) | **`#` 对象 / `##` 函数与方法** |
|
||||
| [design/ai-skill.md](design/ai-skill.md) | **AI 接入 Skill**([`skills/marqdo/`](../skills/marqdo/)) |
|
||||
| [design/code-vs-comment.md](design/code-vs-comment.md) | 叙述 / 可执行 / 外联 |
|
||||
| [design/return-hr-and-code-surface.md](design/return-hr-and-code-surface.md) | 语句/返回/输出决议 |
|
||||
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单 |
|
||||
@@ -24,16 +26,23 @@
|
||||
| [design/dependencies.md](design/dependencies.md) | 依赖详单(无 Flex/Bison) |
|
||||
| [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置函数** |
|
||||
| [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** |
|
||||
| [design/stdlib.md](design/stdlib.md) | **P2 标准库:内置 + `lib/` + 错误约定** |
|
||||
| [design/stdlib.md](design/stdlib.md) | **标准库:内置 + `lib/` + 错误约定** |
|
||||
| [design/stdlib-i18n.md](design/stdlib-i18n.md) | **标准库中英命名:靠库文件名区分,无 lang 开关** |
|
||||
| [design/stdlib-modules.md](design/stdlib-modules.md) | **本波 L1:文件/系统/时间/JSON/网络(JSON 中英同库)** |
|
||||
| [design/stdlib-math.md](design/stdlib-math.md) | **方案:数学库(数值/随机/作图/轻量求解)** |
|
||||
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **暂缓:外联胶水(\`\`\`lang 具名块)** |
|
||||
| [design/stdlib-modules.md](design/stdlib-modules.md) | **L1:文件/系统/时间/JSON/网络/数学/外联/插件** |
|
||||
| [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** |
|
||||
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** |
|
||||
| [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) |
|
||||
| [design/ext-llm.md](design/ext-llm.md) | **官方扩展 `ext/llm`(OpenAI 兼容)** |
|
||||
| [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(智能体开发框架;布局已落地,编排/大模型组合路线已记录)** |
|
||||
| [design/ext-cli.md](design/ext-cli.md) | **`marqdo ext list/add/remove` 官方扩展安装器** |
|
||||
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
|
||||
| [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** |
|
||||
| [design/view.md](design/view.md) | **`marqdo view` / `view output` 黑白极简 + 静态文档** |
|
||||
| [design/user-site.md](design/user-site.md) | **用户站:`public/` → `gh-pages`** |
|
||||
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
|
||||
| [design/view-debug.md](design/view-debug.md) | **`marqdo debug` 独立调试页** |
|
||||
| [design/vscode-extension.md](design/vscode-extension.md) | **VS Code 扩展:分支 `vscode-extension`(main 不跟踪源码)** |
|
||||
| [design/vscode-extension-commit.md](design/vscode-extension-commit.md) | **扩展提交约定(禁止在 main 提交 `vscode-extension/`)** |
|
||||
| [design/bytecode.md](design/bytecode.md) | **M5 字节码 / 双后端** |
|
||||
| [design/pipeline-debug.md](design/pipeline-debug.md) | **流水线 `--dump-*` 可视调试** |
|
||||
| [dev-setup.md](dev-setup.md) | 开发环境配置(Rust M0) |
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# Marqdo AI Skill
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已提供 |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 路径 | [`skills/marqdo/`](../../skills/marqdo/)(权威);Cursor 镜像 [`.cursor/skills/marqdo/`](../../.cursor/skills/marqdo/) |
|
||||
|
||||
---
|
||||
|
||||
## 目的
|
||||
|
||||
让接入方(Cursor Agent、其它支持 Agent Skills 的模型宿主)在**加载本 skill 后**即可按 v0.1 语法正确编写 / 修改 `.mq.md`,而不把 Markdown 习惯或 Python 控制流误套到 Marqdo。
|
||||
|
||||
## 内容
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `SKILL.md` | 必读:硬规则、标记表、工作流、反模式 |
|
||||
| `reference.md` | 按需:CLI、stdlib 索引、边界 |
|
||||
| `examples.md` | 按需:可复制样例 |
|
||||
|
||||
## 使用
|
||||
|
||||
- **本仓库 Cursor**:项目 skill 已在 `.cursor/skills/marqdo/`;描述含 `.mq.md` / Marqdo 触发词,可自动选用。
|
||||
- **其它 AI**:将 `skills/marqdo/` 整目录作为 skill 包导入,或把 `SKILL.md` 贴进系统/项目说明并允许模型按需打开 `reference.md` / `examples.md`。
|
||||
- **校验**:生成后执行 `marqdo run <file>.mq.md`,按 `path:line:col` 诊断迭代。
|
||||
|
||||
语法真相仍以 [markdown-mapping.md](markdown-mapping.md) 与 [keywords.md](keywords.md) 为准;skill 是面向模型的压缩操作手册。
|
||||
@@ -21,7 +21,8 @@
|
||||
|
||||
- 以**空行**划分段落。
|
||||
- 段首行:首字符非标记 → 注释。
|
||||
- 段内续行:一律注释(即使以 `` ` `` / `-` 等开头)。
|
||||
- 段内续行:一律注释(即使以 `` ` `` / `-` / `**` 等开头)。
|
||||
- **例外**:整行仅为 `**expr**`(或 `****`)→ Marqdo **返回**;`**强调**` 后还有文字 → 仍是叙述注释。
|
||||
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
|
||||
|
||||
---
|
||||
|
||||
@@ -81,6 +81,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`> x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
|
||||
|
||||
#### 强烈建议
|
||||
|
||||
|
||||
@@ -42,7 +42,7 @@ tests/
|
||||
|
||||
| 类别 | 测什么 | 不测什么 |
|
||||
|------|--------|----------|
|
||||
| **structure** | `#`/`##`、形参、`>` 调用、`*`/`**`、`+`/`-`、表、导入、位置/具名实参 | 关键字边角 |
|
||||
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、位置/具名实参 | 关键字边角 |
|
||||
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
|
||||
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
|
||||
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
# Native plugin ABI (v1)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted |
|
||||
| Date | 2026-08-06 |
|
||||
| Header | [`include/marqdo_abi.h`](../../include/marqdo_abi.h) |
|
||||
| Related | [ext-agent.md](ext-agent.md) · [stdlib-modules.md](stdlib-modules.md) |
|
||||
|
||||
## Goals
|
||||
|
||||
- Optional **native** extensions as shared libraries (`.dll` / `.so` / `.dylib`).
|
||||
- **Not** linked into the `marqdo` binary; load at runtime.
|
||||
- Stable **C** ABI only (no cross-compiler Rust ABI for plugins).
|
||||
- Official / local paths only — **no** third-party package registry.
|
||||
|
||||
## Contract
|
||||
|
||||
`MARQDO_ABI_VERSION = 1`.
|
||||
|
||||
Every plugin exports:
|
||||
|
||||
| Symbol | Role |
|
||||
|--------|------|
|
||||
| `marqdo_plugin_abi_version` | Must equal host’s supported version |
|
||||
| `marqdo_plugin_init` | Register functions via `MarqdoHostApi` |
|
||||
| `marqdo_plugin_shutdown` | Teardown |
|
||||
|
||||
Host provides `register_fn(name, params_csv, fn)`, `alloc`, `free`.
|
||||
|
||||
### Wire format
|
||||
|
||||
Arguments and results are **UTF-8 JSON**:
|
||||
|
||||
- Args: JSON object keyed by parameter names (from `params` CSV at registration).
|
||||
- Result: any JSON value mappable to Marqdo `Value` (same rules as `lib/json`).
|
||||
|
||||
Plugin fn returns `0` + `*out_json` on success; non-zero + optional `*err_msg` on failure. Host frees both strings with the host `free`.
|
||||
|
||||
## Marqdo surface (`lib/plugin` / `lib/插件`)
|
||||
|
||||
| English | Chinese | Host |
|
||||
|---------|---------|------|
|
||||
| `## load` (`path`) | `## 加载` (`路径`) | `host_plugin_load` |
|
||||
| `## unload` | `## 卸载` | `host_plugin_unload` |
|
||||
| `## list` | `## 列出` | `host_plugin_list` |
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/plugin.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load path=demo.dll
|
||||
|
||||
*`sum` = > demo_add a=1 b=2 *
|
||||
> print text=`sum`
|
||||
```
|
||||
|
||||
After `load`, registered names are callable like other functions (plugin registry lookup after fixed host fns, before user `#`/`##` defs).
|
||||
|
||||
**Path sandbox:** `path` resolves under the program’s cwd / `fs_root` (same as `lib/fs`). Absolute paths outside the root are rejected. Prefer a same-directory filename, or pass a path via a variable / env (see gold tests).
|
||||
|
||||
## Demo
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_demo
|
||||
# Windows: target/debug/demo.dll
|
||||
# Linux: target/debug/libdemo.so
|
||||
# macOS: target/debug/libdemo.dylib
|
||||
```
|
||||
|
||||
Registers `demo_add(a,b)`, `demo_echo(text)`. Gold: [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md).
|
||||
|
||||
Official agent layout plugin: [`plugins/agent`](../../plugins/agent) — see [ext-agent.md](ext-agent.md).
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Embedding plugins in the release exe by default
|
||||
- Callbacks from plugin into arbitrary Marqdo evaluation
|
||||
- OS sandbox / seccomp
|
||||
- **Third-party** plugin / package registry
|
||||
|
||||
Official install of known extensions (`marqdo ext add …`) is **planned** — see [ext-cli.md](ext-cli.md). That is not a public marketplace.
|
||||
@@ -0,0 +1,137 @@
|
||||
# Official agent development framework (`ext/ai/agent`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted · **thin agent loop locked** |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [objects.md](objects.md) |
|
||||
|
||||
## What we are building
|
||||
|
||||
An **agent-development framework** — smallest runtime surface for agents on Marqdo.
|
||||
|
||||
**Not** task-dispatch, **not** bundled domain tools, **not** layout/match/ticket helpers in official ext.
|
||||
|
||||
| In scope | Out of scope (your runbook / your code) |
|
||||
|----------|-------------------------------------------|
|
||||
| `# 智能体` ctor | `## 技能匹配` · `## 分配任务` · `## 创建工单` … |
|
||||
| `## 执行` | Anything task-specific in `ext/` |
|
||||
| `## 清空历史` | |
|
||||
| Auto context: source, position, history, Marqdo skill | |
|
||||
|
||||
## Repo layout (`ext/`)
|
||||
|
||||
Official extensions for LLM + agent live under **`ext/ai/`** only. No flat `.mq.md` at `ext/` root; future domains get their own subdir.
|
||||
|
||||
```text
|
||||
ext/
|
||||
ai/
|
||||
llm.mq.md
|
||||
大模型.mq.md
|
||||
agent.mq.md
|
||||
智能体.mq.md
|
||||
```
|
||||
|
||||
Import: `> ext/ai/智能体.mq.md` · `> ext/ai/llm.mq.md`
|
||||
|
||||
## Layering
|
||||
|
||||
| Layer | Role |
|
||||
|-------|------|
|
||||
| **Your runbook** | Tables, loops, **your** tools & logic |
|
||||
| **`ext/ai/llm`** | Model I/O |
|
||||
| **`ext/ai/agent`** | Framework: ctor + `执行` + `清空历史` |
|
||||
| **`lib/*`** | Generic I/O |
|
||||
|
||||
```text
|
||||
> ext/ai/智能体.mq.md
|
||||
▼
|
||||
# 智能体 (大模型, 工具, 用户提示信息?)
|
||||
## 执行
|
||||
## 清空历史
|
||||
```
|
||||
|
||||
`工具` = caller-supplied **function catalog** (table of `##` names); framework resolves names via `call_fn` / `调用` and runs the matching zero-arg function in the runbook module.
|
||||
|
||||
Install: [`ext-cli.md`](ext-cli.md) — `marqdo ext add agent` / `add llm`.
|
||||
|
||||
### Tools (v1)
|
||||
|
||||
Tools are **not** framework builtins — you define `## 函数名` in your runbook and list names in a table:
|
||||
|
||||
```markdown
|
||||
`工具表` =
|
||||
| 工具 |
|
||||
|------|
|
||||
| 获取时间 |
|
||||
| 分配任务 |
|
||||
```
|
||||
|
||||
- Single-column table → list of function **names** (text).
|
||||
- Multi-column table → each row is a map; name from column `工具` / `tools` / `name`.
|
||||
- Marqdo has no first-class function values in tables yet; the name must match a `##` in the same module (or imports). `执行` calls it with `call_fn` after the model replies `TOOL:<name>`.
|
||||
- Do **not** use `parse text=["fn"]` for the tools list — unquoted identifiers inside `parse` are evaluated as calls.
|
||||
|
||||
---
|
||||
|
||||
## Public API (v1)
|
||||
|
||||
| | Role |
|
||||
|--|------|
|
||||
| `# 智能体` / `# agent` | **大模型**, **工具**, optional **用户提示信息** |
|
||||
| `## 执行` / `## run` | **额外信息**; context + LLM + history append |
|
||||
| `## 清空历史` / `## clear_history` | Wipe history on this handle |
|
||||
|
||||
Module-level `##` helpers (e.g. context assembly) are internal — not public contract.
|
||||
|
||||
### Auto context (each `执行`)
|
||||
|
||||
- `.mq.md` source
|
||||
- Call-site / position
|
||||
- Conversation history on this handle
|
||||
- Marqdo skill (`skills/marqdo/`)
|
||||
|
||||
### History (v1)
|
||||
|
||||
- Host-backed id per handle
|
||||
- Append after each successful `执行`
|
||||
- `清空历史` ships with `执行`
|
||||
|
||||
---
|
||||
|
||||
## Example runbook (application — not framework)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/ai/智能体.mq.md
|
||||
> ext/ai/大模型.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`模型` = > 大模型 *
|
||||
*`工具名` = | 技能匹配 | 分配任务 | … |
|
||||
*`助手` = > 智能体 大模型=`模型` 工具=`工具名` 用户提示信息=… *
|
||||
|
||||
- [任务](任务队列)
|
||||
> `助手`.清空历史
|
||||
*`结果` = > `助手`.执行 额外信息=`任务` *
|
||||
```
|
||||
|
||||
Domain `##` functions live in **this file** or your lib — never in `ext/ai/`.
|
||||
|
||||
---
|
||||
|
||||
## Shipped / roadmap
|
||||
|
||||
| Item | Status |
|
||||
|------|--------|
|
||||
| `ext/ai/` + framework + context injection | in progress |
|
||||
| Live `执行` test (`tests/ext/agent-run-live.mq.md` + `.env`) | shipped |
|
||||
| Tool-call loop in `执行` (`TOOL:<name>` → `call_fn`) | shipped |
|
||||
|
||||
### Non-goals
|
||||
|
||||
- Domain tools in official ext
|
||||
- Flat `ext/*.mq.md` at repo root
|
||||
- Second chat stack beside llm
|
||||
@@ -0,0 +1,61 @@
|
||||
# Official extension installer (`marqdo ext`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted (v0.1)** |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
## Commands
|
||||
|
||||
```text
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext remove llm
|
||||
marqdo ext remove agent
|
||||
```
|
||||
|
||||
## Install root
|
||||
|
||||
1. `MARQDO_EXT` if set
|
||||
2. Else `~/.marqdo/ext`
|
||||
|
||||
Imports use paths like `> ext/ai/llm.mq.md` (see [`load.rs`](../../src/load.rs)).
|
||||
|
||||
## Source for `add`
|
||||
|
||||
1. `MARQDO_EXT_SOURCE` — directory containing `ai/llm.mq.md` …
|
||||
2. Else repo `./ext` near cwd / binary
|
||||
|
||||
## Layout (`ext/`)
|
||||
|
||||
Official extensions live under **`ext/ai/`** (LLM + agent framework only). Do not add flat `.mq.md` files at `ext/` root — keeps the tree from accumulating unrelated modules.
|
||||
|
||||
```text
|
||||
ext/
|
||||
ai/
|
||||
llm.mq.md
|
||||
大模型.mq.md
|
||||
agent.mq.md
|
||||
智能体.mq.md
|
||||
```
|
||||
|
||||
Future optional ext domains get their own subdirs (e.g. `ext/foo/`), not mixed into `ai/`.
|
||||
|
||||
## Catalog
|
||||
|
||||
| Id | Installs under `MARQDO_EXT` |
|
||||
|----|-----------------------------|
|
||||
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md` |
|
||||
|
||||
## Tests
|
||||
|
||||
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` (needs `tests/ext/.env`).
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Third-party registry
|
||||
- Merging into `lib/`
|
||||
- Bundling domain/task helpers in official ext
|
||||
@@ -0,0 +1,70 @@
|
||||
# Official extensions (`ext/`) — LLM
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted (v0.1.x) |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) |
|
||||
|
||||
## Scope
|
||||
|
||||
`ext/ai/` holds **official LLM + agent** extensions. Import paths:
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/ai/llm.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
Resolution: `MARQDO_EXT/ai/…`, repo `ext/ai/…`, cwd `ext/ai/…` (see [ext-cli.md](ext-cli.md)).
|
||||
|
||||
Other official ext: [ext-agent.md](ext-agent.md) (**agent development framework** — layout shipped; orchestration + LLM composition on roadmap). Installer CLI (planned): [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md).
|
||||
|
||||
**Note:** Prefer `marqdo ext add llm`. Import `> ext/ai/llm.mq.md` from repo or install root.
|
||||
|
||||
## Platform prerequisites
|
||||
|
||||
| Capability | Surface |
|
||||
|------------|---------|
|
||||
| HTTPS + headers | `lib/net` → `http_post` / `headers=` map |
|
||||
| Dotenv | `## load_env` in ext (or `load_dotenv` / `lib/sys`) |
|
||||
| JSON quote | `lib/json` → `quote` |
|
||||
|
||||
## `ext/ai/llm` / `ext/ai/大模型` (object handles)
|
||||
|
||||
| English | Chinese | Role |
|
||||
|---------|---------|------|
|
||||
| `## load_env` | `## 加载环境` | Free function: load `.env` |
|
||||
| `# llm` | `# 大模型` | Object ctor → handle map |
|
||||
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Methods on the handle |
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/ai/llm.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load_env
|
||||
|
||||
*`model` = > llm *
|
||||
*`reply` = > `model`.complete prompt=Say hi in one word *
|
||||
> print text=`reply`
|
||||
```
|
||||
|
||||
Environment (create a **project-local** `.env`; do not commit secrets):
|
||||
|
||||
```env
|
||||
OPENAI_API_KEY=sk-...
|
||||
OPENAI_BASE_URL=https://api.openai.com/v1
|
||||
OPENAI_MODEL=gpt-4o-mini
|
||||
```
|
||||
|
||||
Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`.
|
||||
|
||||
## Tests
|
||||
|
||||
- Import smoke: `tests/ext/llm-import.mq.md`
|
||||
- Live complete (local): `tests/ext/llm-complete.mq.md` + `tests/ext/.env`
|
||||
- Live agent `执行`: `tests/ext/agent-run-live.mq.md` + same `.env` (gold: `ext_agent_run_live`, skips if missing)
|
||||
- Offline agent smoke: `tests/ext/agent-smoke.mq.md` (gold: `ext_agent_framework_smoke`)
|
||||
@@ -36,7 +36,7 @@ L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英
|
||||
|
||||
### 3.1 字面量 / 逻辑关键字(词法保留)
|
||||
|
||||
控制流仍靠 Markdown(`#` `+` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。
|
||||
控制流仍靠 Markdown(`#` `1.` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。形参用 `+`。
|
||||
|
||||
| 英文 | 中文(提案) | 备注 |
|
||||
|------|--------------|------|
|
||||
@@ -107,7 +107,7 @@ L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英
|
||||
|
||||
- 旧文「中文 `print` 废弃、统一为 `print`」:**废止**;改为正式双名 `print` / `打印`。
|
||||
- [keywords.md](keywords.md) 原则条「英文标识」改为「**内核双名;标准库分文件**」——实现阶段改正文。
|
||||
- 不引入中文控制流关键字(`如果`/`循环` 等);分支循环仍用 `+` / `-`。
|
||||
- 不引入中文控制流关键字(`如果`/`循环` 等);分支用 `1.` …,循环用 `-`。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -11,7 +11,7 @@
|
||||
|
||||
## 1. 设计原则
|
||||
|
||||
1. **标记承担架构**:函数=`#`,分支=`+`,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
|
||||
1. **标记承担架构**:函数=`#`,**形参=`+`**,**分支=`1.`…**,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
|
||||
2. **内核双名**:字面量 / 逻辑词 / 五个核心内置函数均有中英别名,**无需导入**,可混用。
|
||||
3. **学 Python 的边界**:区分 **关键字** vs **内置函数名**。
|
||||
4. **宁少勿多**:扩展能力进可导入标准库(中英分文件,见 [stdlib-i18n.md](stdlib-i18n.md))。
|
||||
@@ -43,6 +43,8 @@
|
||||
| `str` | `文本` | 转为显示文本 |
|
||||
| `int` | `整数` | 转为整数 |
|
||||
|
||||
**文本**:裸 token 按字面量;需 `\n` 等转义时用 `"..."`(见 [markdown-mapping.md](markdown-mapping.md) §7)。
|
||||
|
||||
形参别名:
|
||||
|
||||
| 英文 | 中文 | 用于 |
|
||||
@@ -71,9 +73,9 @@
|
||||
|
||||
*`n` = 1*
|
||||
|
||||
+ `n` > 0
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
+ *
|
||||
2. *
|
||||
> 打印 内容=other
|
||||
```
|
||||
|
||||
|
||||
@@ -1,11 +1,11 @@
|
||||
# Marqdo 语法映射 v0.1(Markup-as-Syntax)
|
||||
# Marqdo 语法映射 v0.2(Markup-as-Syntax)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定论(修订:语句 / 返回 / 输出职责分离) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 取代 | v0 中「`**`=输出、`*`=返回」 |
|
||||
| 相关 | [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) |
|
||||
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、标识符反引号、`-` 专用于循环) |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 取代 | v0.1 中「函数头 `-` 形参 / 裸名形参与遍历变量 / `+` 分支」 |
|
||||
| 相关 | [objects.md](objects.md) · [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) |
|
||||
|
||||
Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。
|
||||
|
||||
@@ -15,8 +15,9 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
1. `.mq.md`:打开即文档,运行即程序。
|
||||
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
|
||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` 表…)与 **斜体语句** / **粗体返回**。
|
||||
4. 作用域 = `#` 层数;入口 = `index.mq.md`。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` `1.` 表…)与 **斜体语句** / **粗体返回**。
|
||||
4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
||||
5. **标识符一律反引号**:凡表示变量槽位(形参、绑定、引用、遍历项、集合名)均写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。
|
||||
|
||||
---
|
||||
|
||||
@@ -29,22 +30,23 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
| 普通文字 / 空 | **注释** |
|
||||
| 标记字符 | **代码** |
|
||||
|
||||
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
|
||||
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字 `1.`、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
|
||||
|
||||
**成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。
|
||||
|
||||
---
|
||||
|
||||
## 3. 映射总表(v0.1)
|
||||
## 3. 映射总表(v0.2)
|
||||
|
||||
| 标记 | 语义 |
|
||||
|------|------|
|
||||
| `#` … `######` | 函数;层数 = 作用域 |
|
||||
| 函数头下 `-` 纯名 | 形参 |
|
||||
| 体内 `-` | 循环 |
|
||||
| 体内 `+` 或 `1.` | 分支 |
|
||||
| 分支臂头整行恰为 `*` | else |
|
||||
| `#` … `######` | **`#` = 对象/类型**;**`##`+ = 函数/方法**(层差=嵌套)。见 [objects.md](objects.md) |
|
||||
| 函数头下 `+ `` `名` `` ` | 形参 / 构造参数(可选 `` `名`=默认值 ``) |
|
||||
| 体内 `1.` `2.` … | **分支**(有序列表臂;条件行或 else) |
|
||||
| 体内 `-` | **循环**(`while` 条件,或 `` [`项`](`集合`) `` 遍历) |
|
||||
| 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` |
|
||||
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
|
||||
| `` > `对象`.方法 … `` | 方法调用(实例 map 须含 `_type`) |
|
||||
| frontmatter `> path.mq.md` | 跨文件导入 |
|
||||
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
|
||||
| `**…**` | **返回值**(架构级;函数结果) |
|
||||
@@ -55,13 +57,23 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
| ` ```lang ` | 外联异种代码 |
|
||||
| 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §11) |
|
||||
|
||||
### `+` / `-` / `1.` 消歧
|
||||
|
||||
| 位置 | `+` | `1.` … | `-` |
|
||||
|------|-----|--------|-----|
|
||||
| 函数标题后、**首条体语句前** | 形参:`` + `名` `` / `` + `名`=默认 `` | (非法) | (非法作形参) |
|
||||
| 函数体内 | (非法作分支) | 分支臂:`1. `条件`` / `2. *` | 循环 |
|
||||
|
||||
**分支从未使用 `+`。** 自 v0 起即采用 GFM 有序列表;`+` 在 v0.2 专用于形参,与 `-` 循环彻底分离。
|
||||
|
||||
### 输出不是架构
|
||||
|
||||
| 错误(旧) | 正确(v0.1) |
|
||||
| 错误(旧) | 正确(v0.2) |
|
||||
|------------|--------------|
|
||||
| `**Hello**` 表示打印 | `> print text=Hello` |
|
||||
| 中文名 `输出`(已废弃) | 统一英文内置 `print` |
|
||||
| 输出与返回抢粗体 | 粗体只表示 **返回** |
|
||||
| `+ `x` > 0` 作分支 | `1. `x` > 0` |
|
||||
| `- 谁` 作形参 | `` + `谁` `` |
|
||||
| `[果](篮子)` 裸名遍历 | `` [`果`](`篮子`) `` |
|
||||
|
||||
`print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。
|
||||
|
||||
@@ -77,13 +89,13 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
*`y` = `x` + 2*
|
||||
```
|
||||
|
||||
行首已是结构标记的构造(`#` `>` `+` `-` `|`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
|
||||
行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
|
||||
|
||||
### 返回值(粗体)
|
||||
|
||||
```markdown
|
||||
# 加一
|
||||
- n
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
```
|
||||
@@ -98,7 +110,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
### else 与斜体消歧
|
||||
|
||||
- 分支臂**第一行整行只有一个** `*` → else。
|
||||
- 分支臂有序行 `N. *`(或 `N.` 后仅 `*`)→ else。
|
||||
- `*中间有内容*` → 程序语句。
|
||||
- `**…**` → 返回(与 else 无关)。
|
||||
|
||||
@@ -111,9 +123,11 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
---
|
||||
|
||||
## 6. 函数、作用域、提升
|
||||
## 6. 对象、函数、形参
|
||||
|
||||
规则同 v0。推荐:
|
||||
- `# Name`:对象(构造体);`# main` 为入口对象。
|
||||
- `##` / `###` …:函数或方法;挂在对象下则为方法。
|
||||
- 标准库顶层 API 使用自由函数 `## name`(见 [objects.md](objects.md))。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
@@ -121,48 +135,90 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
> print text=Hello World!
|
||||
|
||||
## 加问候
|
||||
- 谁
|
||||
+ `谁`
|
||||
|
||||
**你好,`谁`**
|
||||
```
|
||||
|
||||
(需要打印时对返回值再 `> print`,或直接 `> print`。)
|
||||
可选形参:
|
||||
|
||||
形参 `- 名` → 体内 `` `名` ``。
|
||||
```markdown
|
||||
## 问候
|
||||
+ `谁`
|
||||
+ `礼貌`=False
|
||||
```
|
||||
|
||||
方法体内自动绑定 `` `自` `` / `` `self` ``。
|
||||
|
||||
---
|
||||
|
||||
## 7. 绑定与比较
|
||||
## 7. 绑定、比较与字符串
|
||||
|
||||
| 写法 | 含义 |
|
||||
|------|------|
|
||||
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定(两种均允许;实现应统一) |
|
||||
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定 |
|
||||
| `` `x` == 1 `` | 相等比较 |
|
||||
| `"text"` | **双引号字符串**(复杂文本;见下) |
|
||||
| `hello` / `路径` | **裸 token**(无转义,按字面量) |
|
||||
|
||||
v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致;行首 `` ` `` 仍合法以便表格右值绑定。
|
||||
### 双引号字符串(复杂文本)
|
||||
|
||||
需要转义或嵌入变量时用 `"..."`;**裸 token 不转义**,保持文档简洁:
|
||||
|
||||
```markdown
|
||||
> input prompt="你叫什么名字\n"
|
||||
*`msg` = "Hello, `name`!\n"*
|
||||
```
|
||||
|
||||
| 转义 | 含义 |
|
||||
|------|------|
|
||||
| `\n` | 换行 |
|
||||
| `\t` | 制表 |
|
||||
| `\r` | 回车 |
|
||||
| `\\` | `\` |
|
||||
| `\"` | `"` |
|
||||
|
||||
引号内仍可用 `` `变量` `` 插值。字面反斜杠+n 写 `\\n`(裸 token `\\n` 则就是两个字符)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 分支与循环
|
||||
|
||||
分支(`+` / 有序),循环(`-`),语义同 v0。臂体内打印改为调用 `print`:
|
||||
分支(**有序列表** `1.` `2.` …),循环(`-`):
|
||||
|
||||
```markdown
|
||||
*`x` = 0*
|
||||
|
||||
+ `x` > 0
|
||||
1. `x` > 0
|
||||
> print text=正数
|
||||
+ `x` < 0
|
||||
2. `x` < 0
|
||||
> print text=负数
|
||||
+ *
|
||||
3. *
|
||||
> print text=零
|
||||
```
|
||||
|
||||
```markdown
|
||||
- [果](篮子)
|
||||
*`bool_value` = True*
|
||||
|
||||
1. `bool_value` == True
|
||||
> print text=True
|
||||
2. *
|
||||
> print text=False
|
||||
```
|
||||
|
||||
```markdown
|
||||
- [`果`](`篮子`)
|
||||
> print text=今天吃`果`
|
||||
```
|
||||
|
||||
`while`:
|
||||
|
||||
```markdown
|
||||
- `n` > 0
|
||||
> print text=`n`
|
||||
*`n` = `n` - 1*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 9. 集合(表格)
|
||||
@@ -176,21 +232,19 @@ v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致
|
||||
1. 加载 `index.mq.md` + 导入。
|
||||
2. Pass1 收集定义。
|
||||
3. Pass2 执行 `# main`。
|
||||
4. `*` 语句、`**` 返回、`>` 调用、`+`/`-` 控制流、表绑定按语义执行;`> print` 写 stdout。
|
||||
4. `*` 语句、`**` 返回、`>` 调用、`1.` 分支、`-` 循环、表绑定按语义执行;`> print` 写 stdout。
|
||||
|
||||
---
|
||||
|
||||
## 11. 函数体结束(`---` / `***` / 空返回)
|
||||
|
||||
无返回值(或已写完副作用)的函数,在体末用分割线收束,避免后续同级语句被吞进嵌套函数:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello `谁`!
|
||||
|
||||
@@ -199,20 +253,16 @@ v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致
|
||||
|
||||
| 约定 | 说明 |
|
||||
|------|------|
|
||||
| `---` 或 `***` | 函数体**顶层**单独一行(长度 ≥ 3 且全为 `-` 或全为 `*`)→ **结束本函数**;后续语句属于外层 |
|
||||
| `****` / 空粗体 | 空返回(值为 `None`),并同样结束本函数体 |
|
||||
| 有值 `**expr**` | 普通返回;**不**自动截断后续兄弟句(仍可用分割线或下一同级/更浅标题收束) |
|
||||
| Frontmatter | 仅**文件开头**成对 `---` = 元信息;与函数体内结束符消歧 |
|
||||
| 分支/循环臂内 | 分割线仍可忽略(噪声),不截断外层函数 |
|
||||
|
||||
曾设想的「可选框住分支/循环」废止,分割线专用于函数收束。
|
||||
| `---` 或 `***` | 函数体**顶层**单独一行 → **结束本函数** |
|
||||
| `****` / 空粗体 | 空返回(`None`),并结束本函数体 |
|
||||
| Frontmatter | 仅**文件开头**成对 `---` = 元信息 |
|
||||
|
||||
---
|
||||
|
||||
## 12. v0.1 非目标
|
||||
## 12. v0.2 非目标
|
||||
|
||||
- break/continue、完整错误模型、静态类型、完整 FFI
|
||||
- 用 `*` 作无序列表符
|
||||
- `+` 作分支、`+`/`-` 作形参(**不保留**)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,73 @@
|
||||
# Objects(`#`)与函数(`##`+)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | Accepted |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [ext-llm.md](ext-llm.md) |
|
||||
|
||||
## 1. 约定
|
||||
|
||||
| 标题层 | 含义 |
|
||||
|--------|------|
|
||||
| `#`(恰好一层) | **对象 / 类型**。正文 = 构造体;调用类型名 = 构造实例。 |
|
||||
| `##` 及更深 | **函数**(自由函数或方法)。层数差表示嵌套,与 v0.1 相同。 |
|
||||
|
||||
`# main` 是**入口对象**:运行文件 = 执行其构造体。若无 `main`,且文件恰好只有一个无参顶层 `#` 对象(如 `# Hello World`),则把它当作入口。
|
||||
|
||||
## 2. 实例句柄
|
||||
|
||||
构造返回值若为 `map`,运行时写入 `_type`(文本,值为类型名),形成句柄。
|
||||
方法调用通过 `_type` 找到定义对象,再解析其下的 `##` 方法。
|
||||
|
||||
方法体内自动绑定:
|
||||
|
||||
- `自`(中文)
|
||||
- `self`(英文)
|
||||
|
||||
二者同一接收者。
|
||||
|
||||
## 3. 调用外形
|
||||
|
||||
```markdown
|
||||
# 大模型
|
||||
+ `模型名`
|
||||
|
||||
*`自` = …配置 map…*
|
||||
**`自`**
|
||||
|
||||
## 运行
|
||||
+ `提示`
|
||||
|
||||
…使用 `自` …
|
||||
**`内容`**
|
||||
|
||||
# main
|
||||
|
||||
*`模型` = > 大模型 模型名=gpt-4o-mini *
|
||||
*`回复` = > `模型`.运行 提示=你好 *
|
||||
> print text=`回复`
|
||||
```
|
||||
|
||||
- `> 大模型 …` — 构造
|
||||
- `` > `模型`.运行 … `` — 方法(接收者 + `.` + 方法名)
|
||||
- `## 自由函数` 挂在模块顶层(非某对象子标题)— 与旧版顶层 `# http_get` 对等,现写为 `## http_get`
|
||||
|
||||
## 4. 标准库
|
||||
|
||||
官方 `lib/*.mq.md` 以**顶层自由函数**为主:全部为 `##`(不再使用 `#` 冒充类型)。
|
||||
真正的类型化扩展(如 `ext/llm`)使用 `# 类型` + `##` 方法。
|
||||
|
||||
## 5. 非目标(本波)
|
||||
|
||||
- 继承 / 接口 / 可见性
|
||||
- 无 `_type` 的「鸭子」方法分发
|
||||
- 用表格声明字段 schema(表格仍表示集合)
|
||||
|
||||
## 6. 迁移摘要
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| 库顶层 `# http_get` | `## http_get` |
|
||||
| `# main` + `## 嵌套` | 不变(main = 入口对象) |
|
||||
| `ext` 顶层 `# complete` | `# llm` / `# 大模型` 构造 + `## complete` / `## 运行` |
|
||||
@@ -2,8 +2,8 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已定(v1)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 状态 | **已落地(v1)** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
|
||||
|
||||
---
|
||||
|
||||
+88
-135
@@ -1,32 +1,36 @@
|
||||
# 标准库下一波(L1 扩展模块)
|
||||
# 标准库 L1 模块
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **五库 + 数学已落地**;下一波:**外联**([stdlib-foreign.md](stdlib-foreign.md)) |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 本波范围 | 文件 / 系统 / 时间 / JSON / 网络 / 数学(已完成) |
|
||||
| 下一波 | **外联**(本机解释器 / 具名围栏) |
|
||||
| 暂缓 | — |
|
||||
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [keywords-i18n.md](keywords-i18n.md) · [view.md](view.md) |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
在现有 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本。标准库**必须导入**才可用。
|
||||
在 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本与可选原生扩展。标准库**必须导入**才可用。
|
||||
|
||||
| 模块族 | 英文库 | 中文库 | 本波 |
|
||||
| 模块族 | 英文库 | 中文库 | 状态 |
|
||||
|--------|--------|--------|------|
|
||||
| 文本(已有) | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
|
||||
| 表(已有) | `lib/table.mq.md` | `lib/表.mq.md` | 已有 |
|
||||
| **文件** | `lib/fs.mq.md` | `lib/文件.mq.md` | **做** |
|
||||
| **系统** | `lib/sys.mq.md` | `lib/系统.mq.md` | **做** |
|
||||
| **时间** | `lib/time.mq.md` | `lib/时间.mq.md` | **做** |
|
||||
| **JSON** | `lib/json.mq.md` | **同文件(特例,§3.4)** | **做** |
|
||||
| **网络(简)** | `lib/net.mq.md` | `lib/网络.mq.md` | **做** |
|
||||
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | **下一波** |
|
||||
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | **做** |
|
||||
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
|
||||
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有 |
|
||||
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 |
|
||||
| 系统 | `lib/sys.mq.md` | `lib/系统.mq.md` | 已有(含 `load_dotenv`) |
|
||||
| 时间 | `lib/time.mq.md` | `lib/时间.mq.md` | 已有 |
|
||||
| JSON | `lib/json.mq.md` | **同文件** | 已有(含 `quote`) |
|
||||
| 网络 | `lib/net.mq.md` | `lib/网络.mq.md` | 已有(HTTPS + headers) |
|
||||
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | 已有 |
|
||||
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | 已有 |
|
||||
| **插件** | `lib/plugin.mq.md` | `lib/插件.mq.md` | **已有**(加载 C ABI 共享库) |
|
||||
| **自写回** | `lib/writeback.mq.md` | `lib/自写回.mq.md` | **已有**(Jupyter 式输出写回) |
|
||||
| **子任务** | `lib/subtask.mq.md` | `lib/子任务.mq.md` | **已有**(OS 子进程 + KillOnDrop) |
|
||||
|
||||
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` — 见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
设计细节:[stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -34,35 +38,59 @@
|
||||
|
||||
```text
|
||||
用户 .mq.md
|
||||
│ > lib/fs.mq.md
|
||||
│ > lib/fs.mq.md / > ext/llm.mq.md
|
||||
▼
|
||||
L1 官方库(.mq.md)
|
||||
L1 官方库 / 官方 ext(.mq.md)
|
||||
│
|
||||
▼
|
||||
L0.5 宿主原语(Rust,英文蛇形)
|
||||
L0.5 宿主原语(Rust)或 原生插件(ABI v1)
|
||||
│
|
||||
▼
|
||||
OS / HTTP / 时钟 / …
|
||||
OS / HTTP / 时钟 / 共享库 …
|
||||
```
|
||||
|
||||
| 层 | 谁实现 | 用户是否直接调用 |
|
||||
|----|--------|------------------|
|
||||
| **L0** | 解释器内置 | 是(`print`/`len`/…) |
|
||||
| **L0.5 宿主原语** | Rust(`src/builtin` 或 `src/host/`) | **原则上否**;供 L1 包装;金样例可直测 |
|
||||
| **L1 官方库** | `lib/*.mq.md` | **是**(文档与用户站只教这一层) |
|
||||
|
||||
规则:
|
||||
|
||||
1. **导入即选择语言**(JSON 除外):`lib/fs.mq.md` → 英文 API;`lib/文件.mq.md` → 中文 API(见 [stdlib-i18n.md](stdlib-i18n.md))。
|
||||
2. **不设 `lang:`**。
|
||||
3. 宿主原语保持英文;中英差异只存在于 L1 包装层(JSON 无第二套包装)。
|
||||
4. 失败一律 `path:line:col: message`([stdlib.md](stdlib.md) §4)。
|
||||
| **L0.5 宿主原语** | Rust(`src/host/`) | **原则上否**;供 L1 包装 |
|
||||
| **L1 官方库** | `lib/*.mq.md` | **是** |
|
||||
| **官方 ext** | `ext/*.mq.md`(+ 可选 ABI 插件) | **是**(需显式导入 `ext/`) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 核心模块 API 草图(L1)
|
||||
## 3. 核心模块 API(摘要)
|
||||
|
||||
### 3.1 文件 — `fs` / `文件`
|
||||
文件 / 系统 / 时间 / JSON / 网络 API 见下文历史草图(已实现)。补充:
|
||||
|
||||
### 3.2 系统 — 已含 dotenv
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `load_dotenv` | `加载环境` | 可选 `path` | 新写入的键数量;缺文件 → `0`;不覆盖已有环境变量 |
|
||||
|
||||
### 3.4 JSON — 已含 `quote`
|
||||
|
||||
| 函数 | 形参 | 结果 |
|
||||
|------|------|------|
|
||||
| `quote` | `text` | JSON 字符串字面量(含引号) |
|
||||
|
||||
### 3.5 网络 — HTTPS
|
||||
|
||||
仅 **HTTP / HTTPS**(ureq);可选 `headers=`(map)、`content_type=`。
|
||||
|
||||
### 3.6 插件 — `plugin` / `插件`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `load` | `加载` | `path` / `路径` | 注册函数个数 |
|
||||
| `unload` | `卸载` | (无) | `None` |
|
||||
| `list` | `列出` | (无) | 已注册名列表 |
|
||||
|
||||
契约:[ext-abi.md](ext-abi.md)。路径受 cwd/fs_root 沙箱约束。
|
||||
|
||||
### 3.1–3.5 历史 API 草图
|
||||
|
||||
#### 文件 — `fs` / `文件`
|
||||
|
||||
| 英文 | 中文 | 形参(英 / 中) | 结果 |
|
||||
|------|------|-----------------|------|
|
||||
@@ -74,22 +102,19 @@ OS / HTTP / 时钟 / …
|
||||
| `make_dir` | `建目录` | `path` / `路径` | `None` |
|
||||
| `remove` | `删除` | `path` / `路径` | `None` |
|
||||
|
||||
约定:路径相对工作目录或绝对路径;二进制 I/O 本波不做;写/删默认需 `--allow-fs-write`(§6)。
|
||||
|
||||
### 3.2 系统 — `sys` / `系统`
|
||||
#### 系统 — `sys` / `系统`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `env_get` | `取环境` | `name` / `名` | 文本或 `None` |
|
||||
| `env_set` | `设环境` | `name`, `value` / `名`, `值` | `None` |
|
||||
| `load_dotenv` | `加载环境` | 可选 `path` | 见上 |
|
||||
| `args` | `参数表` | (无) | 文本列表 |
|
||||
| `cwd` | `工作目录` | (无) | 文本 |
|
||||
| `exit` | `退出` | `code` / `码` | 不返回 |
|
||||
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码(实现时写死语义) |
|
||||
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码 |
|
||||
|
||||
`exec` 默认关(`--allow-exec`);view / 静态站永不开放。
|
||||
|
||||
### 3.3 时间 — `time` / `时间`
|
||||
#### 时间 — `time` / `时间`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
@@ -99,130 +124,58 @@ OS / HTTP / 时钟 / …
|
||||
| `sleep_ms` | `睡眠毫秒` | `ms` / `毫秒` | `None` |
|
||||
| `parse` | `解析时间` | `text`, `pattern` / `内容`, `格式` | 整数秒或诊断失败 |
|
||||
|
||||
view 中 `sleep_ms` 设上限(如 5s)。
|
||||
|
||||
### 3.4 JSON — `json`(**中英同库特例**)
|
||||
|
||||
JSON 是专有缩写,**很难也不必要**做合规中文库名/API 翻译。本波定稿:
|
||||
|
||||
| 项 | 约定 |
|
||||
|----|------|
|
||||
| 唯一路径 | **`lib/json.mq.md`**(中英文档均导入此路径) |
|
||||
| 函数名 | 国际通行英文:`parse` / `stringify` / `get` / `keys` |
|
||||
| 形参 | 英文:`text` / `value` / `key` / `indent` |
|
||||
| 不设 | `lib/数据.mq.md`、音译名、中文函数双份 |
|
||||
|
||||
这是对 [stdlib-i18n.md](stdlib-i18n.md)「一概念两文件」的**显式例外**;其它模块仍中英分文件。
|
||||
#### JSON — `json`
|
||||
|
||||
| 函数 | 形参 | 结果 |
|
||||
|------|------|------|
|
||||
| `parse` | `text` | 值(见下) |
|
||||
| `parse` | `text` | 值 |
|
||||
| `stringify` | `value`, 可选 `indent` | JSON 文本 |
|
||||
| `get` | `value`, `key` | 值或 `None` |
|
||||
| `keys` | `value` | 文本列表 |
|
||||
| `quote` | `text` | JSON 字符串字面量 |
|
||||
|
||||
**类型映射(草案)**:
|
||||
|
||||
| JSON | Marqdo Value |
|
||||
|------|----------------|
|
||||
| `null` | `None` |
|
||||
| bool | bool |
|
||||
| number(整数可表) | int |
|
||||
| number(其余) | 文本(本波不引入 float)或诊断拒绝 |
|
||||
| string | text |
|
||||
| array | list |
|
||||
| object | 倾向新宿主类型 **`map`**(`type` → `map`);否则体验差 |
|
||||
|
||||
`map` 为 L0.5 类型扩展,可与 json 同期或紧随;不阻塞 `fs`/`time` 先行。
|
||||
|
||||
### 3.5 网络(简)— `net` / `网络`
|
||||
#### 网络 — `net` / `网络`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `http_get` | `获取` | `url` / `地址` | 响应文本(或 map:status/body) |
|
||||
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` | 同上 |
|
||||
| `http_get` | `获取` | `url` / `地址` | 响应文本 |
|
||||
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` / `headers` | 同上 |
|
||||
| `url_encode` | `编码地址` | `text` / `内容` | 文本 |
|
||||
|
||||
仅 **HTTP 明文**(HTTPS 本波未做,会诊断提示);短超时、响应体上限;默认需 `--allow-net`;view / 静态站默认关。
|
||||
|
||||
**路径字面量:** 具名实参里 `path=a/b` 会被解析成除法。请用无斜杠文件名,或先赋给变量再传入。
|
||||
|
||||
---
|
||||
|
||||
## 4. 中英路径总表(本波)
|
||||
## 4. 中英路径总表
|
||||
|
||||
```text
|
||||
lib/
|
||||
text.mq.md / 文本.mq.md # 已有
|
||||
table.mq.md / 表.mq.md # 已有
|
||||
fs.mq.md / 文件.mq.md # 本波
|
||||
text.mq.md / 文本.mq.md
|
||||
table.mq.md / 表.mq.md
|
||||
fs.mq.md / 文件.mq.md
|
||||
sys.mq.md / 系统.mq.md
|
||||
time.mq.md / 时间.mq.md
|
||||
json.mq.md # 本波;中英共用,无第二文件
|
||||
json.mq.md # 中英共用
|
||||
net.mq.md / 网络.mq.md
|
||||
# 暂缓:math / 数学 · foreign / 外联
|
||||
math.mq.md / 数学.mq.md
|
||||
foreign.mq.md / 外联.mq.md
|
||||
plugin.mq.md / 插件.mq.md
|
||||
|
||||
ext/ # 非 stdlib
|
||||
llm.mq.md / 大模型.mq.md
|
||||
agent.mq.md / 智能体.mq.md
|
||||
```
|
||||
|
||||
别名:`std/…` ≡ `lib/…`。
|
||||
别名:`std/…` ≡ `lib/…`。扩展解析:`MARQDO_EXT` / `./ext` / 二进制旁 `ext/`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 落地分期(本波 = M1–M5)
|
||||
## 5. 安全与 view / 静态导出
|
||||
|
||||
| 期 | 内容 | 完成定义 |
|
||||
|----|------|----------|
|
||||
| **M1** | 宿主能力框架:权限旗标、`host` 分发、错误文案 | `--allow-*` 可测 |
|
||||
| **M2** | `fs` + `time`(只读 fs + 时钟) | 中英库 + 金样例 |
|
||||
| **M3** | `sys`(env/cwd/args;`exec` 默认关) | 同上 |
|
||||
| **M4** | `json`(+ 可选 `map`) | 往返金样例;唯 `lib/json.mq.md` |
|
||||
| **M5** | `net`(默认关) | 本地 mock 或录制夹具 |
|
||||
|
||||
**不做 M6/M7**(数学 / 外联):详稿仅存档,待五库稳定后再议。
|
||||
|
||||
文档站:`fs`/`sys`/`time`/`net` 英中各一页;`json` 可一页双语叙述、同一导入路径。
|
||||
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**。差异仅在软退出 / sleep 钳制。相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。插件路径同沙箱。
|
||||
|
||||
---
|
||||
|
||||
## 6. 安全与 view / 静态导出
|
||||
## 6. 一句话
|
||||
|
||||
### 6.1 行为一致
|
||||
|
||||
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**(读/写盘、HTTP、exec 均可用)。导入库即表示要用;不再要求 `--allow-*`。
|
||||
|
||||
差异仅在 **软退出**:
|
||||
|
||||
| | CLI `run` | view / capture / 静态导出 |
|
||||
|--|-----------|---------------------------|
|
||||
| `exit` | 结束进程 | 报诊断,不杀 view/构建进程 |
|
||||
| `sleep_ms` | 默认可睡(有上限) | live 有上限;导出通常为 0 |
|
||||
|
||||
沙箱:相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。
|
||||
|
||||
### 6.2 静态部署
|
||||
|
||||
访客浏览器 **不再执行** Marqdo;HTML 里是构建时冻结的输出。源码中的路径/URL 访客改不了、也触发不了新的 host 调用。审 PR 时审查写死的目标即可。
|
||||
|
||||
勿在静态页嵌入「用户可改 URL 再请求」的浏览器脚本。
|
||||
|
||||
---
|
||||
|
||||
## 7. 与现有库的关系
|
||||
|
||||
- `text` / `table` 继续纯包装、无 IO。
|
||||
- JSON `stringify` ≠ `str`(显示)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 刻意不做(本波)
|
||||
|
||||
- 数学库、外联/胶水库(及其依赖、权限旗标实现)。
|
||||
- 数据库、异步事件循环、WebSocket、原始 TCP。
|
||||
- float/复数进 L0。
|
||||
- `lang:` 或按 locale 自动选库。
|
||||
- 为 JSON 强造中文库名或中文 API 双份。
|
||||
|
||||
---
|
||||
|
||||
## 9. 一句话
|
||||
|
||||
**本波只落地文件 / 系统 / 时间 / JSON / 网络;JSON 中英共用 `lib/json.mq.md`;数学与外联暂缓。**
|
||||
**L1 含文件 / 系统 / 时间 / JSON / 网络 / 数学 / 外联 / 插件;`ext/` 为可选官方扩展(llm、agent)。**
|
||||
@@ -0,0 +1,25 @@
|
||||
# 子任务标准库(subtask)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | v2 |
|
||||
| 库 | `lib/subtask.mq.md` · `lib/子任务.mq.md` |
|
||||
|
||||
## 定位
|
||||
|
||||
**并发**执行单元。`spawn` 四选一:
|
||||
|
||||
| 参数 | 执行方式 | `join` 返回值 |
|
||||
|------|----------|---------------|
|
||||
| `path=` | `marqdo run <file>` 子进程 | 退出码 `Int` |
|
||||
| `fn=` + 可选 `args=` | 当前入口模块中的函数(进程内线程) | 函数返回值 `Value` |
|
||||
| `code=` | 外联代码块(`Value::Code`)子进程 | stdout `Text` |
|
||||
| `lang=` + `source=` | 外联源码子进程 | stdout `Text` |
|
||||
|
||||
`args=`:文件子任务为 `List`(命令行参数);函数子任务为 `Map`(形参绑定)或 `List`(按 `arg0`… 命名)。
|
||||
|
||||
父进程结束(含 panic)时 **KillOnDrop** 终止所有文件/外联子进程;函数线程标记为 killed 并 detach(无法强杀 OS 线程)。
|
||||
|
||||
`poll` → `{ status: running | done | failed, … }`;函数 done 时含 `value`,进程/外联 failed 时含 `code` 或 `error`。
|
||||
|
||||
Host:`host_subtask_*`(`src/host/subtask.rs`)。
|
||||
@@ -0,0 +1,36 @@
|
||||
# 自写回标准库(writeback)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | v1 已落地 |
|
||||
| 库 | `lib/writeback.mq.md` · `lib/自写回.mq.md` |
|
||||
|
||||
## 定位
|
||||
|
||||
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` 的 `<!-- marqdo-out … -->` → `marqdo view` 在对应语句下显示 **output-card**。普通 Markdown 预览不显示该区域。
|
||||
|
||||
## 存储格式
|
||||
|
||||
```markdown
|
||||
*`n` = > len value=`xs` *
|
||||
<!-- marqdo-out
|
||||
42
|
||||
-->
|
||||
```
|
||||
|
||||
- 注释内仅保留 `marqdo-out` 标识,**不存行号**(避免写回后行号漂移)
|
||||
- 默认在**调用行下方**插入或替换紧邻块(中间可有空行)
|
||||
- `at_end=true` / `末尾=true`:在文件末尾保留单块(替换已有末尾块)
|
||||
|
||||
## API
|
||||
|
||||
| EN | ZH | 说明 |
|
||||
|----|-----|------|
|
||||
| `record` | `写回` | `value=`,可选 `at_end=false` |
|
||||
| `get` | `取` | 可选 `at_end=false` |
|
||||
| `clear` | `清除` | 可选 `at_end=false` |
|
||||
| `list` | `列出` | 全文所有输出块(含推断锚点行) |
|
||||
|
||||
可选参数语法:`` + `参数名`=默认值 ``(与现有参数列表兼容)。
|
||||
|
||||
Host:`host_writeback_*`(`src/host/writeback.rs`)。
|
||||
+22
-14
@@ -2,12 +2,13 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **S0–S3 落地** |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [keywords.md](keywords.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [roadmap/next-phase.md](../roadmap/next-phase.md) |
|
||||
| 状态 | **S0–S3 + L1 全模块落地** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-abi.md](ext-abi.md) |
|
||||
|
||||
> **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。
|
||||
> **下一波模块(本波:文件 / 系统 / 时间 / JSON / 网络;数学·外联暂缓)**:见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
> **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
> **`ext/` 不是 stdlib**:官方可选扩展见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -15,8 +16,9 @@
|
||||
|
||||
| 层 | 内容 |
|
||||
|----|------|
|
||||
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at` |
|
||||
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at`(`type` 可含 `map`) |
|
||||
| **L1 官方库** | 仓库根目录 [`lib/`](../../lib/)(`.mq.md`);可用 `lib/…` 或别名 `std/…` 导入 |
|
||||
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1 |
|
||||
| **L2** | catalog / 用户站收录(随发版) |
|
||||
|
||||
---
|
||||
@@ -28,7 +30,7 @@
|
||||
| `len` | `value` | 文本标量数或列表长度 |
|
||||
| `str` | `value` | 显示文本 |
|
||||
| `int` | `value` | 整数(失败 → 诊断) |
|
||||
| `type` | `value` | `none`/`bool`/`int`/`text`/`list` |
|
||||
| `type` | `value` | `none`/`bool`/`int`/`text`/`list`/`map` |
|
||||
| `trim` | `value` | 去首尾空白 |
|
||||
| `split` | `value`, `sep` | 文本列表 |
|
||||
| `join` | `value`, `sep` | 拼接文本 |
|
||||
@@ -54,23 +56,29 @@ Frontmatter:
|
||||
1. 相对当前文件
|
||||
2. `MARQDO_LIB`(可指向 `lib` 目录或仓库根)
|
||||
3. 当前工作目录的 `lib/`
|
||||
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
|
||||
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
|
||||
5. **内嵌 stdlib**(v0.1.2+,编译进二进制;无磁盘 `lib/` 时自动使用)
|
||||
|
||||
当前模块:
|
||||
当前模块(API 多为 `##` 自由函数;见 [objects.md](objects.md)):
|
||||
|
||||
| 路径 | 导出函数 |
|
||||
|------|----------|
|
||||
| 路径 | 导出 |
|
||||
|------|------|
|
||||
| `lib/fs.mq.md` / `lib/文件.mq.md` | `read_text`… / `读文本`… |
|
||||
| `lib/time.mq.md` / `lib/时间.mq.md` | `now_unix`… / `此刻秒`… |
|
||||
| `lib/sys.mq.md` / `lib/系统.mq.md` | `env_get`… / `取环境`… |
|
||||
| `lib/json.mq.md` | `parse` `stringify` `get` `keys`(中英同文件) |
|
||||
| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`… / `获取`… |
|
||||
| `lib/sys.mq.md` / `lib/系统.mq.md` | `env_get`…、`load_dotenv`… / `取环境`…、`加载环境`… |
|
||||
| `lib/json.mq.md` | `parse` `stringify` `get` `keys` `quote`(中英同文件) |
|
||||
| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`…(HTTPS)/ `获取`… |
|
||||
| `lib/math.mq.md` / `lib/数学.mq.md` | 数值 / 随机 / 公式 / 绘图 |
|
||||
| `lib/foreign.mq.md` / `lib/外联.mq.md` | 具名围栏外联 |
|
||||
| `lib/plugin.mq.md` / `lib/插件.mq.md` | `load` / `unload` / `list`(原生 ABI) |
|
||||
| `lib/writeback.mq.md` / `lib/自写回.mq.md` | `record` `get` `clear` `list` |
|
||||
| `lib/subtask.mq.md` / `lib/子任务.mq.md` | `spawn` `poll` `wait` `kill` `wait_all` |
|
||||
| `lib/text.mq.md` | `str_trim` `str_split` `str_join` |
|
||||
| `lib/文本.mq.md` | `去空白` `拆分` `拼接` |
|
||||
| `lib/table.mq.md` | `rows` `row_at` |
|
||||
| `lib/表.mq.md` | `行数` `取行` |
|
||||
|
||||
规划中的 L1 扩展见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
完整清单见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+11
-2
@@ -13,7 +13,7 @@
|
||||
| 路径 | 是否入库 | 职责 |
|
||||
|------|----------|------|
|
||||
| `doc/` | 是 | 开发者设计 / ADR / 路线图(单数 `doc`,勿再造 `docs/`) |
|
||||
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / 特性迭代);**双语**:拉丁文件名 = 英文,中文文件名 = 中文编程,同目录并列 |
|
||||
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / **stdlib** / 特性迭代);**双语**:拉丁文件名 = 英文,中文文件名 = 中文编程,同目录并列。stdlib 含 `plugin`;特性页覆盖对象与 `ext/`(llm / agent) |
|
||||
| `public/index.html`、`public/pages/` | **否**(ignore) | `marqdo view output` 生成的 HTML |
|
||||
| `tests/{structure,keywords,errors}/` | 是 | 金样例与失败夹具(含 errors) |
|
||||
| 远程分支 `gh-pages` | 发布产物 | 发布整个 `public/`(源文件 + 生成 HTML) |
|
||||
@@ -50,7 +50,16 @@ public/
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收
|
||||
## 4. 内容分层(用户站)
|
||||
|
||||
| 目录 | 内容 |
|
||||
|------|------|
|
||||
| `public/stdlib/` | L1 模块页(含 `plugin` / `插件`);概述注明 `ext/` 非 stdlib |
|
||||
| `public/features/` | 迭代特性:树遍历、字节码、view、**对象**、**官方扩展** |
|
||||
|
||||
设计文档仍在 `doc/design/`(`objects.md`、`ext-llm.md`、`ext-abi.md`、`ext-agent.md`)。
|
||||
|
||||
## 5. 验收
|
||||
|
||||
1. `public/` 下每个 `.mq.md`(除纯工具模块外)`marqdo run` 退出码 0。
|
||||
2. `view output public -o public` 后首页为欢迎页,侧栏无 errors。
|
||||
|
||||
@@ -0,0 +1,82 @@
|
||||
# VS Code 扩展 — 分支与提交约定
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **强制约定**(勿在 `main` 提交扩展源码) |
|
||||
| 扩展分支 | **`vscode-extension`** |
|
||||
| 设计说明 | [vscode-extension.md](vscode-extension.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 原则(必读)
|
||||
|
||||
| 分支 | 是否跟踪 `vscode-extension/` |
|
||||
|------|-------------------------------|
|
||||
| **`main`** | **否** — `.gitignore` 含 `/vscode-extension/` |
|
||||
| **`vscode-extension`** | **是** — 扩展唯一源码所在分支 |
|
||||
|
||||
**禁止**在 `main` 上:
|
||||
|
||||
- 删除 `.gitignore` 里的 `/vscode-extension/`
|
||||
- `git add vscode-extension/`
|
||||
- 把扩展目录「合并进 main」以便发版
|
||||
|
||||
发版时从 **`vscode-extension` 分支检出**扩展目录打 VSIX(见 §4),**不是**把扩展提交进 `main`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 日常开发(扩展)
|
||||
|
||||
```bash
|
||||
git fetch origin
|
||||
git checkout vscode-extension
|
||||
cd vscode-extension && npm ci && npm run compile
|
||||
```
|
||||
|
||||
改语法、CLI 检测、扩展版本 → **只在 `vscode-extension` 分支提交**:
|
||||
|
||||
```bash
|
||||
git add vscode-extension/
|
||||
git commit -m "vscode-extension: <简要说明>"
|
||||
git push origin vscode-extension
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 3. 日常开发(CLI / 语言)
|
||||
|
||||
在 **`main`** 上改 `src/`、`lib/`、`public/`、`tests/` 等;**不要**顺带提交 `vscode-extension/`。
|
||||
|
||||
若本地为了调试 checkout 过扩展目录,工作区里可以有 `vscode-extension/` 文件夹,但应被 ignore,且 **`git status` 不应出现**该目录下文件。
|
||||
|
||||
---
|
||||
|
||||
## 4. 发版(CLI tag + VSIX)
|
||||
|
||||
1. **`main`**:打 tag(如 `v0.1.2`),CI 构建 `marqdo.exe` 等。
|
||||
2. **VSIX**:Release 工作流在 tag 构建时执行:
|
||||
```bash
|
||||
git fetch origin vscode-extension
|
||||
git checkout origin/vscode-extension -- vscode-extension
|
||||
cd vscode-extension && npm ci && npm run compile && npx @vscode/vsce package
|
||||
```
|
||||
3. 本地脚本 `scripts/release-windows.ps1` 同样假定:先 `git checkout origin/vscode-extension -- vscode-extension`(或已在 `vscode-extension` 分支),再打 VSIX。
|
||||
|
||||
扩展版本号与最低 CLI 要求写在 **`vscode-extension/package.json`** 与分支 README,**不要**在 `main` 的 CHANGELOG 里冒充已合并扩展源码。
|
||||
|
||||
---
|
||||
|
||||
## 5. 给 Agent / 协作者
|
||||
|
||||
执行「更新 VS Code 插件」类任务时:
|
||||
|
||||
1. **切到或基于 `vscode-extension` 分支**改 `vscode-extension/**`
|
||||
2. **不要**移除 `main` 上 `.gitignore` 的 `/vscode-extension/`
|
||||
3. **不要**在 `main` 的 release 提交里包含 `vscode-extension/package-lock.json` 等大文件
|
||||
4. 仅需在 `main` 更新时:改 `doc/design/vscode-extension.md`、Release 说明、**本文件** — 指针文档即可
|
||||
|
||||
---
|
||||
|
||||
## 6. 历史说明
|
||||
|
||||
v0.1.2 准备阶段曾误将 `vscode-extension/` 并入 `main`(并删除 ignore),导致推送体积过大。已恢复:**扩展仅 `vscode-extension` 分支**;`main` 只保留本约定与设计指针。
|
||||
@@ -0,0 +1,31 @@
|
||||
# VS Code 扩展(分支指针)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已定分支模型** |
|
||||
| 代码分支 | **`vscode-extension`**(同仓库) |
|
||||
| 目录 | 工作区 `vscode-extension/`(**仅在该分支跟踪;`main` 在 `.gitignore` 忽略**) |
|
||||
| 提交约定 | **[vscode-extension-commit.md](vscode-extension-commit.md)**(必读,避免误提交到 `main`) |
|
||||
|
||||
---
|
||||
|
||||
## 分工(类比 `public` / `gh-pages`)
|
||||
|
||||
| 分支 | 内容 |
|
||||
|------|------|
|
||||
| `main` | Marqdo 语言 / CLI / `public/*.mq.md`;**不**存放扩展实现 |
|
||||
| `vscode-extension` | VS Code 扩展源码、TextMate 语法、VSIX 发版 |
|
||||
| `gh-pages` | 用户站生成 HTML |
|
||||
|
||||
```bash
|
||||
git checkout vscode-extension
|
||||
cd vscode-extension && npm install
|
||||
```
|
||||
|
||||
规范入口(在 **`vscode-extension` 分支**上阅读):
|
||||
|
||||
- `vscode-extension/README.md` — 目标与目录
|
||||
- `vscode-extension/DEVELOPMENT.md` — 日常流程
|
||||
- `vscode-extension/ARCHITECTURE.md` — 与 CLI 边界
|
||||
|
||||
扩展是 CLI 的薄宿主;语法真相仍是 [markdown-mapping.md](markdown-mapping.md)。
|
||||
@@ -0,0 +1,111 @@
|
||||
---
|
||||
title: ext/ai/agent
|
||||
description: Thin agent framework — ctor, run, clear_history only.
|
||||
> ext/ai/llm.mq.md
|
||||
---
|
||||
|
||||
## build_agent_context
|
||||
+ `agent`
|
||||
+ `extra`
|
||||
|
||||
Internal: assemble prompt (user prompt, extra, tool list, source, call site, history, Marqdo skill).
|
||||
|
||||
*`user_prompt` = > get value=`agent` key=user_prompt *
|
||||
1. `user_prompt`
|
||||
*`up` = `user_prompt`*
|
||||
2. *
|
||||
*`up` = None*
|
||||
|
||||
*`tools` = > get value=`agent` key=tools *
|
||||
*`tools_s` = > host_format_tools_for_llm tools=`tools` *
|
||||
*`src` = > host_module_source *
|
||||
*`site` = > host_call_site *
|
||||
*`site_s` = > stringify value=`site` *
|
||||
*`id` = > get value=`agent` key=id *
|
||||
*`hist` = > host_agent_history_get id=`id` *
|
||||
*`hist_s` = > stringify value=`hist` *
|
||||
*`skill` = > host_marqdo_skill *
|
||||
*`extra_s` = > stringify value=`extra` *
|
||||
|
||||
*`sep` = > parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- extra ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source ---\n","f":"\n\n--- history ---\n","g":"\n\n--- marqdo skill ---\n"} *
|
||||
*`a` = > get value=`sep` key=a *
|
||||
*`b` = > get value=`sep` key=b *
|
||||
*`c` = > get value=`sep` key=c *
|
||||
*`d` = > get value=`sep` key=d *
|
||||
*`e` = > get value=`sep` key=e *
|
||||
*`f` = > get value=`sep` key=f *
|
||||
*`g` = > get value=`sep` key=g *
|
||||
|
||||
*`tool_proto` = \n\n--- tool protocol ---\nEach tool is a zero-arg Marqdo function in this module (see tools list). To call one, reply with exactly one line: TOOL:<name>. No other text on that line.\nAfter the tool runs you will get its output and should answer the user.\n *
|
||||
|
||||
*`p` = You are a Marqdo agent. Follow Marqdo skill rules when reading or writing .mq.md. *
|
||||
*`p` = `p` + `a` + `up` + `b` + `extra_s` + `c` + `tool_proto` + `tools_s` + `d` + `site_s` + `e` + `src` + `f` + `hist_s` + `g` + `skill` *
|
||||
**`p`**
|
||||
|
||||
# agent
|
||||
+ `model`
|
||||
+ `tools`
|
||||
+ `user_prompt`
|
||||
|
||||
*`id` = > host_agent_alloc *
|
||||
*`h` = > parse text={"_type":"agent"} *
|
||||
*`h` = > map_set map=`h` key=id value=`id` *
|
||||
*`h` = > map_set map=`h` key=model value=`model` *
|
||||
*`h` = > map_set map=`h` key=tools value=`tools` *
|
||||
|
||||
1. `user_prompt`
|
||||
*`h` = > map_set map=`h` key=user_prompt value=`user_prompt` *
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
**`h`**
|
||||
|
||||
## clear_history
|
||||
|
||||
*`id` = > get value=`self` key=id *
|
||||
> host_agent_history_clear id=`id`
|
||||
****
|
||||
|
||||
## run
|
||||
+ `extra`
|
||||
|
||||
*`ctx` = > build_agent_context agent=`self` extra=`extra` *
|
||||
*`id` = > get value=`self` key=id *
|
||||
|
||||
*`user_turn` = > parse text={"role":"user"} *
|
||||
*`user_turn` = > map_set map=`user_turn` key=content value=`extra` *
|
||||
> host_agent_history_append id=`id` item=`user_turn`
|
||||
|
||||
*`model` = > get value=`self` key=model *
|
||||
*`reply` = > `model`.complete prompt=`ctx` *
|
||||
*`tools` = > get value=`self` key=tools *
|
||||
*`reply` = > trim value=`reply` *
|
||||
|
||||
*`parts` = > split value=`reply` sep=: *
|
||||
*`head` = > at value=`parts` index=0 *
|
||||
*`tool_name` = > at value=`parts` index=1 *
|
||||
*`tool_name` = > trim value=`tool_name` *
|
||||
|
||||
1. `head` == TOOL
|
||||
*`allowed` = > host_tool_allowed tools=`tools` name=`tool_name` *
|
||||
1. `allowed`
|
||||
*`tool_out` = > call_fn name=`tool_name` *
|
||||
*`tool_s` = > stringify value=`tool_out` *
|
||||
*`extra_s` = > stringify value=`extra` *
|
||||
*`fp` = The user asked: *
|
||||
*`fp` = `fp` + `extra_s` *
|
||||
*`fp` = `fp` + . You invoked tool *
|
||||
*`fp` = `fp` + `tool_name` *
|
||||
*`fp` = `fp` + which returned: *
|
||||
*`fp` = `fp` + `tool_s` *
|
||||
*`fp` = `fp` + . Reply to the user in one brief sentence. *
|
||||
*`reply` = > `model`.complete prompt=`fp` *
|
||||
2. *
|
||||
*`reply` = Tool not allowed: `tool_name` *
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
*`as_turn` = > parse text={"role":"assistant"} *
|
||||
*`as_turn` = > map_set map=`as_turn` key=content value=`reply` *
|
||||
> host_agent_history_append id=`id` item=`as_turn`
|
||||
**`reply`**
|
||||
@@ -0,0 +1,130 @@
|
||||
---
|
||||
title: ext/ai/llm
|
||||
description: OpenAI-compatible LLM object (English). Import ext/ai/llm.mq.md.
|
||||
> lib/sys.mq.md
|
||||
> lib/net.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## load_env
|
||||
|
||||
Load `.env` from cwd (optional named arg `path=`). Does not override existing variables.
|
||||
|
||||
**> load_dotenv**
|
||||
|
||||
# llm
|
||||
|
||||
Construct an LLM handle from `OPENAI_*` / `MARQDO_LLM_*` (default base OpenAI v1, model `gpt-4o-mini`).
|
||||
|
||||
*`d` = > parse text={"base":"https://api.openai.com/v1","model":"gpt-4o-mini","suffix":"/chat/completions","bearer":"Bearer ","p1":"{\"model\":","p2":",\"messages\":[{\"role\":\"user\",\"content\":","p3":"}]}","h1":"{\"Authorization\":","h2":"}","a1":"{\"api_key\":","a2":",\"base_url\":","a3":",\"model\":","a4":",\"suffix\":","a5":",\"bearer\":","a6":",\"p1\":","a7":",\"p2\":","a8":",\"p3\":","a9":",\"h1\":","a10":",\"h2\":","a11":"}"} *
|
||||
|
||||
*`api_key` = > env_get name=OPENAI_API_KEY *
|
||||
1. `api_key`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`api_key` = > env_get name=MARQDO_LLM_API_KEY *
|
||||
3. `api_key`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
> print text=ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY
|
||||
> exit code=1
|
||||
|
||||
*`base_url` = > env_get name=OPENAI_BASE_URL *
|
||||
1. `base_url`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`base_url` = > env_get name=MARQDO_LLM_BASE_URL *
|
||||
3. `base_url`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`base_url` = > get value=`d` key=base *
|
||||
|
||||
*`model` = > env_get name=OPENAI_MODEL *
|
||||
1. `model`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`model` = > env_get name=MARQDO_LLM_MODEL *
|
||||
3. `model`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`model` = > get value=`d` key=model *
|
||||
|
||||
*`q_key` = > quote text=`api_key` *
|
||||
*`q_base` = > quote text=`base_url` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`suffix` = > get value=`d` key=suffix *
|
||||
*`bearer` = > get value=`d` key=bearer *
|
||||
*`p1` = > get value=`d` key=p1 *
|
||||
*`p2` = > get value=`d` key=p2 *
|
||||
*`p3` = > get value=`d` key=p3 *
|
||||
*`h1` = > get value=`d` key=h1 *
|
||||
*`h2` = > get value=`d` key=h2 *
|
||||
*`q_suf` = > quote text=`suffix` *
|
||||
*`q_br` = > quote text=`bearer` *
|
||||
*`q_p1` = > quote text=`p1` *
|
||||
*`q_p2` = > quote text=`p2` *
|
||||
*`q_p3` = > quote text=`p3` *
|
||||
*`q_h1` = > quote text=`h1` *
|
||||
*`q_h2` = > quote text=`h2` *
|
||||
*`a1` = > get value=`d` key=a1 *
|
||||
*`a2` = > get value=`d` key=a2 *
|
||||
*`a3` = > get value=`d` key=a3 *
|
||||
*`a4` = > get value=`d` key=a4 *
|
||||
*`a5` = > get value=`d` key=a5 *
|
||||
*`a6` = > get value=`d` key=a6 *
|
||||
*`a7` = > get value=`d` key=a7 *
|
||||
*`a8` = > get value=`d` key=a8 *
|
||||
*`a9` = > get value=`d` key=a9 *
|
||||
*`a10` = > get value=`d` key=a10 *
|
||||
*`a11` = > get value=`d` key=a11 *
|
||||
*`raw` = `a1` + `q_key` + `a2` + `q_base` + `a3` + `q_model` + `a4` + `q_suf` + `a5` + `q_br` + `a6` + `q_p1` + `a7` + `q_p2` + `a8` + `q_p3` + `a9` + `q_h1` + `a10` + `q_h2` + `a11` *
|
||||
**> parse text=`raw`**
|
||||
|
||||
## complete
|
||||
+ `prompt`
|
||||
|
||||
Chat completion using `self` / `自` handle fields.
|
||||
|
||||
*`api_key` = > get value=`self` key=api_key *
|
||||
*`base_url` = > get value=`self` key=base_url *
|
||||
*`model` = > get value=`self` key=model *
|
||||
*`suffix` = > get value=`self` key=suffix *
|
||||
*`bearer` = > get value=`self` key=bearer *
|
||||
*`p1` = > get value=`self` key=p1 *
|
||||
*`p2` = > get value=`self` key=p2 *
|
||||
*`p3` = > get value=`self` key=p3 *
|
||||
*`h1` = > get value=`self` key=h1 *
|
||||
*`h2` = > get value=`self` key=h2 *
|
||||
*`url` = `base_url` + `suffix` *
|
||||
*`auth` = `bearer` + `api_key` *
|
||||
*`q_auth` = > quote text=`auth` *
|
||||
*`hdr_raw` = `h1` + `q_auth` + `h2` *
|
||||
*`headers` = > parse text=`hdr_raw` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`q_prompt` = > quote text=`prompt` *
|
||||
*`body` = `p1` + `q_model` + `p2` + `q_prompt` + `p3` *
|
||||
*`resp` = > http_post url=`url` body=`body` headers=`headers` *
|
||||
*`status` = > get value=`resp` key=status *
|
||||
*`raw` = > get value=`resp` key=body *
|
||||
|
||||
1. `status` == 200
|
||||
*`data` = > parse text=`raw` *
|
||||
*`choices` = > get value=`data` key=choices *
|
||||
*`first` = > at value=`choices` index=0 *
|
||||
*`message` = > get value=`first` key=message *
|
||||
*`content` = > get value=`message` key=content *
|
||||
**`content`**
|
||||
2. *
|
||||
> print text=ext/ai/llm: HTTP error
|
||||
> print text=`status`
|
||||
> print text=`raw`
|
||||
> exit code=1
|
||||
|
||||
---
|
||||
|
||||
## chat
|
||||
+ `prompt`
|
||||
|
||||
Alias for `complete`.
|
||||
|
||||
**> `self`.complete prompt=`prompt`**
|
||||
@@ -0,0 +1,130 @@
|
||||
---
|
||||
title: ext/ai/大模型
|
||||
description: OpenAI 兼容大模型对象(中文)。导入 ext/ai/大模型.mq.md。
|
||||
> lib/系统.mq.md
|
||||
> lib/网络.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## 加载环境
|
||||
|
||||
从工作目录加载 `.env`(可选具名实参 `path=`)。不覆盖已有变量。
|
||||
|
||||
**> load_dotenv**
|
||||
|
||||
# 大模型
|
||||
|
||||
从 `OPENAI_*` / `MARQDO_LLM_*` 构造句柄(默认 OpenAI v1 + `gpt-4o-mini`)。
|
||||
|
||||
*`d` = > parse text={"base":"https://api.openai.com/v1","model":"gpt-4o-mini","suffix":"/chat/completions","bearer":"Bearer ","p1":"{\"model\":","p2":",\"messages\":[{\"role\":\"user\",\"content\":","p3":"}]}","h1":"{\"Authorization\":","h2":"}","a1":"{\"api_key\":","a2":",\"base_url\":","a3":",\"model\":","a4":",\"suffix\":","a5":",\"bearer\":","a6":",\"p1\":","a7":",\"p2\":","a8":",\"p3\":","a9":",\"h1\":","a10":",\"h2\":","a11":"}"} *
|
||||
|
||||
*`api_key` = > 取环境 名=OPENAI_API_KEY *
|
||||
1. `api_key`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`api_key` = > 取环境 名=MARQDO_LLM_API_KEY *
|
||||
3. `api_key`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
> 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY
|
||||
> 退出 码=1
|
||||
|
||||
*`base_url` = > 取环境 名=OPENAI_BASE_URL *
|
||||
1. `base_url`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`base_url` = > 取环境 名=MARQDO_LLM_BASE_URL *
|
||||
3. `base_url`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`base_url` = > get value=`d` key=base *
|
||||
|
||||
*`model` = > 取环境 名=OPENAI_MODEL *
|
||||
1. `model`
|
||||
*`_k` = 1*
|
||||
2. *
|
||||
*`model` = > 取环境 名=MARQDO_LLM_MODEL *
|
||||
3. `model`
|
||||
*`_k` = 1*
|
||||
4. *
|
||||
*`model` = > get value=`d` key=model *
|
||||
|
||||
*`q_key` = > quote text=`api_key` *
|
||||
*`q_base` = > quote text=`base_url` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`suffix` = > get value=`d` key=suffix *
|
||||
*`bearer` = > get value=`d` key=bearer *
|
||||
*`p1` = > get value=`d` key=p1 *
|
||||
*`p2` = > get value=`d` key=p2 *
|
||||
*`p3` = > get value=`d` key=p3 *
|
||||
*`h1` = > get value=`d` key=h1 *
|
||||
*`h2` = > get value=`d` key=h2 *
|
||||
*`q_suf` = > quote text=`suffix` *
|
||||
*`q_br` = > quote text=`bearer` *
|
||||
*`q_p1` = > quote text=`p1` *
|
||||
*`q_p2` = > quote text=`p2` *
|
||||
*`q_p3` = > quote text=`p3` *
|
||||
*`q_h1` = > quote text=`h1` *
|
||||
*`q_h2` = > quote text=`h2` *
|
||||
*`a1` = > get value=`d` key=a1 *
|
||||
*`a2` = > get value=`d` key=a2 *
|
||||
*`a3` = > get value=`d` key=a3 *
|
||||
*`a4` = > get value=`d` key=a4 *
|
||||
*`a5` = > get value=`d` key=a5 *
|
||||
*`a6` = > get value=`d` key=a6 *
|
||||
*`a7` = > get value=`d` key=a7 *
|
||||
*`a8` = > get value=`d` key=a8 *
|
||||
*`a9` = > get value=`d` key=a9 *
|
||||
*`a10` = > get value=`d` key=a10 *
|
||||
*`a11` = > get value=`d` key=a11 *
|
||||
*`raw` = `a1` + `q_key` + `a2` + `q_base` + `a3` + `q_model` + `a4` + `q_suf` + `a5` + `q_br` + `a6` + `q_p1` + `a7` + `q_p2` + `a8` + `q_p3` + `a9` + `q_h1` + `a10` + `q_h2` + `a11` *
|
||||
**> parse text=`raw`**
|
||||
|
||||
## 运行
|
||||
+ `提示`
|
||||
|
||||
使用 `自` / `self` 句柄字段做聊天补全。
|
||||
|
||||
*`api_key` = > get value=`自` key=api_key *
|
||||
*`base_url` = > get value=`自` key=base_url *
|
||||
*`model` = > get value=`自` key=model *
|
||||
*`suffix` = > get value=`自` key=suffix *
|
||||
*`bearer` = > get value=`自` key=bearer *
|
||||
*`p1` = > get value=`自` key=p1 *
|
||||
*`p2` = > get value=`自` key=p2 *
|
||||
*`p3` = > get value=`自` key=p3 *
|
||||
*`h1` = > get value=`自` key=h1 *
|
||||
*`h2` = > get value=`自` key=h2 *
|
||||
*`url` = `base_url` + `suffix` *
|
||||
*`auth` = `bearer` + `api_key` *
|
||||
*`q_auth` = > quote text=`auth` *
|
||||
*`hdr_raw` = `h1` + `q_auth` + `h2` *
|
||||
*`headers` = > parse text=`hdr_raw` *
|
||||
*`q_model` = > quote text=`model` *
|
||||
*`q_prompt` = > quote text=`提示` *
|
||||
*`body` = `p1` + `q_model` + `p2` + `q_prompt` + `p3` *
|
||||
*`resp` = > http_post url=`url` body=`body` headers=`headers` *
|
||||
*`status` = > get value=`resp` key=status *
|
||||
*`raw` = > get value=`resp` key=body *
|
||||
|
||||
1. `status` == 200
|
||||
*`data` = > parse text=`raw` *
|
||||
*`choices` = > get value=`data` key=choices *
|
||||
*`first` = > at value=`choices` index=0 *
|
||||
*`message` = > get value=`first` key=message *
|
||||
*`content` = > get value=`message` key=content *
|
||||
**`content`**
|
||||
2. *
|
||||
> 打印 内容=ext/ai/大模型: HTTP 错误
|
||||
> 打印 内容=`status`
|
||||
> 打印 内容=`raw`
|
||||
> 退出 码=1
|
||||
|
||||
---
|
||||
|
||||
## 聊天
|
||||
+ `提示`
|
||||
|
||||
`运行` 的别名。
|
||||
|
||||
**> `自`.运行 提示=`提示`**
|
||||
@@ -0,0 +1,111 @@
|
||||
---
|
||||
title: ext/ai/智能体
|
||||
description: 薄智能体框架 — 仅构造、执行、清空历史。
|
||||
> ext/ai/大模型.mq.md
|
||||
---
|
||||
|
||||
## 构建上下文
|
||||
+ `智能体`
|
||||
+ `额外信息`
|
||||
|
||||
内部:组装提示(用户提示、额外信息、工具列表、源码、位置、历史、Marqdo skill)。
|
||||
|
||||
*`user_prompt` = > get value=`智能体` key=user_prompt *
|
||||
1. `user_prompt`
|
||||
*`up` = `user_prompt`*
|
||||
2. *
|
||||
*`up` = 空*
|
||||
|
||||
*`tools` = > get value=`智能体` key=tools *
|
||||
*`tools_s` = > host_format_tools_for_llm tools=`tools` *
|
||||
*`src` = > host_module_source *
|
||||
*`site` = > host_call_site *
|
||||
*`site_s` = > stringify value=`site` *
|
||||
*`id` = > get value=`智能体` key=id *
|
||||
*`hist` = > host_agent_history_get id=`id` *
|
||||
*`hist_s` = > stringify value=`hist` *
|
||||
*`skill` = > host_marqdo_skill *
|
||||
*`extra_s` = > stringify value=`额外信息` *
|
||||
|
||||
*`sep` = > parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- extra ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source ---\n","f":"\n\n--- history ---\n","g":"\n\n--- marqdo skill ---\n"} *
|
||||
*`a` = > get value=`sep` key=a *
|
||||
*`b` = > get value=`sep` key=b *
|
||||
*`c` = > get value=`sep` key=c *
|
||||
*`d` = > get value=`sep` key=d *
|
||||
*`e` = > get value=`sep` key=e *
|
||||
*`f` = > get value=`sep` key=f *
|
||||
*`g` = > get value=`sep` key=g *
|
||||
|
||||
*`tool_proto` = \n\n--- tool protocol ---\nEach tool is a zero-arg Marqdo function in this module (see tools list). To call one, reply with exactly one line: TOOL:<name>. No other text on that line.\nAfter the tool runs you will get its output and should answer the user.\n *
|
||||
|
||||
*`p` = You are a Marqdo agent. Follow Marqdo skill rules when reading or writing .mq.md. *
|
||||
*`p` = `p` + `a` + `up` + `b` + `extra_s` + `c` + `tool_proto` + `tools_s` + `d` + `site_s` + `e` + `src` + `f` + `hist_s` + `g` + `skill` *
|
||||
**`p`**
|
||||
|
||||
# 智能体
|
||||
+ `大模型`
|
||||
+ `工具`
|
||||
+ `用户提示信息`
|
||||
|
||||
*`id` = > host_agent_alloc *
|
||||
*`h` = > parse text={"_type":"智能体"} *
|
||||
*`h` = > map_set map=`h` key=id value=`id` *
|
||||
*`h` = > map_set map=`h` key=model value=`大模型` *
|
||||
*`h` = > map_set map=`h` key=tools value=`工具` *
|
||||
|
||||
1. `用户提示信息`
|
||||
*`h` = > map_set map=`h` key=user_prompt value=`用户提示信息` *
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
**`h`**
|
||||
|
||||
## 清空历史
|
||||
|
||||
*`id` = > get value=`自` key=id *
|
||||
> host_agent_history_clear id=`id`
|
||||
****
|
||||
|
||||
## 执行
|
||||
+ `额外信息`
|
||||
|
||||
*`ctx` = > 构建上下文 智能体=`自` 额外信息=`额外信息` *
|
||||
*`id` = > get value=`自` key=id *
|
||||
|
||||
*`user_turn` = > parse text={"role":"user"} *
|
||||
*`user_turn` = > map_set map=`user_turn` key=content value=`额外信息` *
|
||||
> host_agent_history_append id=`id` item=`user_turn`
|
||||
|
||||
*`model` = > get value=`自` key=model *
|
||||
*`reply` = > `model`.运行 提示=`ctx` *
|
||||
*`tools` = > get value=`自` key=tools *
|
||||
*`reply` = > trim value=`reply` *
|
||||
|
||||
*`parts` = > split value=`reply` sep=: *
|
||||
*`head` = > at value=`parts` index=0 *
|
||||
*`tool_name` = > at value=`parts` index=1 *
|
||||
*`tool_name` = > trim value=`tool_name` *
|
||||
|
||||
1. `head` == TOOL
|
||||
*`allowed` = > host_tool_allowed tools=`tools` name=`tool_name` *
|
||||
1. `allowed`
|
||||
*`tool_out` = > 调用 名=`tool_name` *
|
||||
*`tool_s` = > stringify value=`tool_out` *
|
||||
*`extra_s` = > stringify value=`额外信息` *
|
||||
*`fp` = The user asked: *
|
||||
*`fp` = `fp` + `extra_s` *
|
||||
*`fp` = `fp` + . You invoked tool *
|
||||
*`fp` = `fp` + `tool_name` *
|
||||
*`fp` = `fp` + which returned: *
|
||||
*`fp` = `fp` + `tool_s` *
|
||||
*`fp` = `fp` + . Reply to the user in one brief sentence. *
|
||||
*`reply` = > `model`.运行 提示=`fp` *
|
||||
2. *
|
||||
*`reply` = Tool not allowed: `tool_name` *
|
||||
2. *
|
||||
*`_` = 1*
|
||||
|
||||
*`as_turn` = > parse text={"role":"assistant"} *
|
||||
*`as_turn` = > map_set map=`as_turn` key=content value=`reply` *
|
||||
> host_agent_history_append id=`id` item=`as_turn`
|
||||
**`reply`**
|
||||
@@ -0,0 +1,43 @@
|
||||
/* Marqdo plugin ABI v1 — C contract (source of truth).
|
||||
*
|
||||
* Plugins are optional shared libraries (.dll / .so / .dylib), never linked
|
||||
* into the marqdo binary. Values cross the boundary as UTF-8 JSON.
|
||||
*/
|
||||
#ifndef MARQDO_ABI_H
|
||||
#define MARQDO_ABI_H
|
||||
|
||||
#include <stddef.h>
|
||||
#include <stdint.h>
|
||||
|
||||
#ifdef __cplusplus
|
||||
extern "C" {
|
||||
#endif
|
||||
|
||||
#define MARQDO_ABI_VERSION 1u
|
||||
|
||||
/* Plugin function: args_json is a UTF-8 JSON object whose keys are param names.
|
||||
* On success: return 0, set *out_json to a heap string (host frees via free).
|
||||
* On failure: return non-zero; optional *err_msg heap string (host frees).
|
||||
* out_json / err_msg may be left NULL.
|
||||
*/
|
||||
typedef int (*MarqdoPluginFn)(const char *args_json, char **out_json, char **err_msg);
|
||||
|
||||
typedef struct MarqdoHostApi {
|
||||
void *userdata;
|
||||
/* params: comma-separated param names in order, e.g. "a,b". May be "". */
|
||||
int (*register_fn)(void *userdata, const char *name, const char *params,
|
||||
MarqdoPluginFn fn);
|
||||
void *(*alloc)(size_t n);
|
||||
void (*free)(void *p);
|
||||
} MarqdoHostApi;
|
||||
|
||||
/* Required exports from every plugin shared library. */
|
||||
uint32_t marqdo_plugin_abi_version(void);
|
||||
int marqdo_plugin_init(const MarqdoHostApi *host);
|
||||
void marqdo_plugin_shutdown(void);
|
||||
|
||||
#ifdef __cplusplus
|
||||
}
|
||||
#endif
|
||||
|
||||
#endif /* MARQDO_ABI_H */
|
||||
+9
-9
@@ -3,23 +3,23 @@ title: lib/foreign
|
||||
description: Run bound code fences and inline sources via local interpreters
|
||||
---
|
||||
|
||||
# set_cmd
|
||||
- lang
|
||||
- cmd
|
||||
## set_cmd
|
||||
+ `lang`
|
||||
+ `cmd`
|
||||
|
||||
**> host_foreign_set_cmd lang=`lang` cmd=`cmd`**
|
||||
|
||||
# run
|
||||
- code
|
||||
## run
|
||||
+ `code`
|
||||
|
||||
**> host_foreign_run code=`code`**
|
||||
|
||||
# run_lang
|
||||
- lang
|
||||
- source
|
||||
## run_lang
|
||||
+ `lang`
|
||||
+ `source`
|
||||
|
||||
**> host_foreign_run_lang lang=`lang` source=`source`**
|
||||
|
||||
# langs
|
||||
## langs
|
||||
|
||||
**> host_foreign_langs**
|
||||
+16
-16
@@ -3,39 +3,39 @@ title: lib/fs
|
||||
description: English filesystem wrappers
|
||||
---
|
||||
|
||||
# read_text
|
||||
- path
|
||||
## read_text
|
||||
+ `path`
|
||||
|
||||
**> host_read_text path=`path`**
|
||||
|
||||
# write_text
|
||||
- path
|
||||
- text
|
||||
## write_text
|
||||
+ `path`
|
||||
+ `text`
|
||||
|
||||
**> host_write_text path=`path` text=`text`**
|
||||
|
||||
# append_text
|
||||
- path
|
||||
- text
|
||||
## append_text
|
||||
+ `path`
|
||||
+ `text`
|
||||
|
||||
**> host_append_text path=`path` text=`text`**
|
||||
|
||||
# exists
|
||||
- path
|
||||
## exists
|
||||
+ `path`
|
||||
|
||||
**> host_exists path=`path`**
|
||||
|
||||
# list_dir
|
||||
- path
|
||||
## list_dir
|
||||
+ `path`
|
||||
|
||||
**> host_list_dir path=`path`**
|
||||
|
||||
# make_dir
|
||||
- path
|
||||
## make_dir
|
||||
+ `path`
|
||||
|
||||
**> host_make_dir path=`path`**
|
||||
|
||||
# remove
|
||||
- path
|
||||
## remove
|
||||
+ `path`
|
||||
|
||||
**> host_remove path=`path`**
|
||||
+27
-9
@@ -3,23 +3,41 @@ title: lib/json
|
||||
description: JSON parse/stringify (shared EN/ZH import)
|
||||
---
|
||||
|
||||
# parse
|
||||
- text
|
||||
## parse
|
||||
+ `text`
|
||||
|
||||
**> host_json_parse text=`text`**
|
||||
|
||||
# stringify
|
||||
- value
|
||||
## stringify
|
||||
+ `value`
|
||||
|
||||
**> host_json_stringify value=`value`**
|
||||
|
||||
# get
|
||||
- value
|
||||
- key
|
||||
## get
|
||||
+ `value`
|
||||
+ `key`
|
||||
|
||||
**> host_json_get value=`value` key=`key`**
|
||||
|
||||
# keys
|
||||
- value
|
||||
## keys
|
||||
+ `value`
|
||||
|
||||
**> host_json_keys value=`value`**
|
||||
|
||||
## quote
|
||||
+ `text`
|
||||
|
||||
**> host_json_quote text=`text`**
|
||||
|
||||
## set
|
||||
+ `map`
|
||||
+ `key`
|
||||
+ `value`
|
||||
|
||||
**> host_map_set map=`map` key=`key` value=`value`**
|
||||
|
||||
## append
|
||||
+ `list`
|
||||
+ `item`
|
||||
|
||||
**> host_list_append list=`list` item=`item`**
|
||||
+88
-88
@@ -3,198 +3,198 @@ title: lib/math
|
||||
description: High-school math — num, random, formula, plot
|
||||
---
|
||||
|
||||
# pi
|
||||
## pi
|
||||
|
||||
**> host_pi**
|
||||
|
||||
# e
|
||||
## e
|
||||
|
||||
**> host_e**
|
||||
|
||||
# num
|
||||
- value
|
||||
## num
|
||||
+ `value`
|
||||
|
||||
**> host_num value=`value`**
|
||||
|
||||
# add
|
||||
- a
|
||||
- b
|
||||
## add
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_add a=`a` b=`b`**
|
||||
|
||||
# sub
|
||||
- a
|
||||
- b
|
||||
## sub
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_sub a=`a` b=`b`**
|
||||
|
||||
# mul
|
||||
- a
|
||||
- b
|
||||
## mul
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_mul a=`a` b=`b`**
|
||||
|
||||
# div
|
||||
- a
|
||||
- b
|
||||
## div
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_div a=`a` b=`b`**
|
||||
|
||||
# pow
|
||||
- a
|
||||
- b
|
||||
## pow
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_pow a=`a` b=`b`**
|
||||
|
||||
# neg
|
||||
- value
|
||||
## neg
|
||||
+ `value`
|
||||
|
||||
**> host_math_neg value=`value`**
|
||||
|
||||
# sin
|
||||
- value
|
||||
## sin
|
||||
+ `value`
|
||||
|
||||
**> host_math_sin value=`value`**
|
||||
|
||||
# cos
|
||||
- value
|
||||
## cos
|
||||
+ `value`
|
||||
|
||||
**> host_math_cos value=`value`**
|
||||
|
||||
# tan
|
||||
- value
|
||||
## tan
|
||||
+ `value`
|
||||
|
||||
**> host_math_tan value=`value`**
|
||||
|
||||
# asin
|
||||
- value
|
||||
## asin
|
||||
+ `value`
|
||||
|
||||
**> host_math_asin value=`value`**
|
||||
|
||||
# acos
|
||||
- value
|
||||
## acos
|
||||
+ `value`
|
||||
|
||||
**> host_math_acos value=`value`**
|
||||
|
||||
# atan
|
||||
- value
|
||||
## atan
|
||||
+ `value`
|
||||
|
||||
**> host_math_atan value=`value`**
|
||||
|
||||
# sqrt
|
||||
- value
|
||||
## sqrt
|
||||
+ `value`
|
||||
|
||||
**> host_math_sqrt value=`value`**
|
||||
|
||||
# abs
|
||||
- value
|
||||
## abs
|
||||
+ `value`
|
||||
|
||||
**> host_math_abs value=`value`**
|
||||
|
||||
# ln
|
||||
- value
|
||||
## ln
|
||||
+ `value`
|
||||
|
||||
**> host_math_ln value=`value`**
|
||||
|
||||
# exp
|
||||
- value
|
||||
## exp
|
||||
+ `value`
|
||||
|
||||
**> host_math_exp value=`value`**
|
||||
|
||||
# floor
|
||||
- value
|
||||
## floor
|
||||
+ `value`
|
||||
|
||||
**> host_math_floor value=`value`**
|
||||
|
||||
# ceil
|
||||
- value
|
||||
## ceil
|
||||
+ `value`
|
||||
|
||||
**> host_math_ceil value=`value`**
|
||||
|
||||
# min
|
||||
- a
|
||||
- b
|
||||
## min
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_min a=`a` b=`b`**
|
||||
|
||||
# max
|
||||
- a
|
||||
- b
|
||||
## max
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_max a=`a` b=`b`**
|
||||
|
||||
# random
|
||||
## random
|
||||
|
||||
**> host_random**
|
||||
|
||||
# random_int
|
||||
- min
|
||||
- max
|
||||
## random_int
|
||||
+ `min`
|
||||
+ `max`
|
||||
|
||||
**> host_random_int min=`min` max=`max`**
|
||||
|
||||
# seed
|
||||
- value
|
||||
## seed
|
||||
+ `value`
|
||||
|
||||
**> host_seed value=`value`**
|
||||
|
||||
# formula
|
||||
- text
|
||||
## formula
|
||||
+ `text`
|
||||
|
||||
**> host_formula value=`text`**
|
||||
|
||||
# simplify
|
||||
- formula
|
||||
## simplify
|
||||
+ `formula`
|
||||
|
||||
**> host_simplify value=`formula`**
|
||||
|
||||
# expand
|
||||
- formula
|
||||
## expand
|
||||
+ `formula`
|
||||
|
||||
**> host_expand value=`formula`**
|
||||
|
||||
# diff
|
||||
- formula
|
||||
- var
|
||||
## diff
|
||||
+ `formula`
|
||||
+ `var`
|
||||
|
||||
**> host_diff formula=`formula` var=`var`**
|
||||
|
||||
# subs
|
||||
- formula
|
||||
- var
|
||||
- value
|
||||
## subs
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `value`
|
||||
|
||||
**> host_subs formula=`formula` var=`var` value=`value`**
|
||||
|
||||
# eval
|
||||
- formula
|
||||
- var
|
||||
- value
|
||||
## eval
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `value`
|
||||
|
||||
**> host_eval formula=`formula` var=`var` value=`value`**
|
||||
|
||||
# solve
|
||||
- formula
|
||||
- var
|
||||
## solve
|
||||
+ `formula`
|
||||
+ `var`
|
||||
|
||||
**> host_solve formula=`formula` var=`var`**
|
||||
|
||||
# plot
|
||||
- formula
|
||||
- var
|
||||
- min
|
||||
- max
|
||||
## plot
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `min`
|
||||
+ `max`
|
||||
|
||||
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
|
||||
|
||||
# plot_points
|
||||
- xs
|
||||
- ys
|
||||
## plot_points
|
||||
+ `xs`
|
||||
+ `ys`
|
||||
|
||||
**> host_plot_points xs=`xs` ys=`ys`**
|
||||
|
||||
# plot_conic
|
||||
- kind
|
||||
- a
|
||||
## plot_conic
|
||||
+ `kind`
|
||||
+ `a`
|
||||
|
||||
**> host_plot_conic kind=`kind` a=`a`**
|
||||
+20
-8
@@ -1,20 +1,32 @@
|
||||
---
|
||||
title: lib/net
|
||||
description: English minimal HTTP wrappers
|
||||
description: English HTTP(S) wrappers. Optional headers / content_type via host aliases.
|
||||
---
|
||||
|
||||
# http_get
|
||||
- url
|
||||
## http_get
|
||||
+ `url`
|
||||
|
||||
HTTPS supported. Optional named arg `headers=` (map).
|
||||
|
||||
**> host_http_get url=`url`**
|
||||
|
||||
# http_post
|
||||
- url
|
||||
- body
|
||||
## http_post
|
||||
+ `url`
|
||||
+ `body`
|
||||
|
||||
Default content type is JSON. Optional `content_type=` / `headers=` (map).
|
||||
|
||||
**> host_http_post url=`url` body=`body`**
|
||||
|
||||
# url_encode
|
||||
- text
|
||||
## http_request
|
||||
+ `method`
|
||||
+ `url`
|
||||
|
||||
Optional `body=` / `content_type=` / `headers=`.
|
||||
|
||||
**> host_http_request method=`method` url=`url`**
|
||||
|
||||
## url_encode
|
||||
+ `text`
|
||||
|
||||
**> host_url_encode text=`text`**
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: lib/plugin
|
||||
description: Load optional native ABI plugins (.dll / .so / .dylib)
|
||||
---
|
||||
|
||||
## load
|
||||
+ `path`
|
||||
|
||||
**> host_plugin_load path=`path`**
|
||||
|
||||
## unload
|
||||
|
||||
**> host_plugin_unload**
|
||||
|
||||
## list
|
||||
|
||||
**> host_plugin_list**
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: lib/subtask
|
||||
description: Concurrent subtasks — file, function, or foreign code
|
||||
---
|
||||
|
||||
## spawn
|
||||
+ `path`=None
|
||||
+ `fn`=None
|
||||
+ `args`=None
|
||||
+ `code`=None
|
||||
+ `lang`=None
|
||||
+ `source`=None
|
||||
+ `stdin`=None
|
||||
|
||||
**> host_subtask_spawn path=`path` fn=`fn` args=`args` code=`code` lang=`lang` source=`source` stdin=`stdin`**
|
||||
|
||||
## poll
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_poll id=`id`**
|
||||
|
||||
## wait
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_join id=`id`**
|
||||
|
||||
## kill
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_kill id=`id`**
|
||||
|
||||
## wait_all
|
||||
|
||||
**> host_subtask_wait_all**
|
||||
+18
-12
@@ -1,33 +1,39 @@
|
||||
---
|
||||
title: lib/sys
|
||||
description: English system wrappers
|
||||
description: English system wrappers (load_dotenv accepts optional path via host alias)
|
||||
---
|
||||
|
||||
# env_get
|
||||
- name
|
||||
## env_get
|
||||
+ `name`
|
||||
|
||||
**> host_env_get name=`name`**
|
||||
|
||||
# env_set
|
||||
- name
|
||||
- value
|
||||
## env_set
|
||||
+ `name`
|
||||
+ `value`
|
||||
|
||||
**> host_env_set name=`name` value=`value`**
|
||||
|
||||
# args
|
||||
## load_dotenv
|
||||
|
||||
Load `.env` (optional named arg `path=`). Existing process env is not overridden.
|
||||
|
||||
**> host_dotenv_load**
|
||||
|
||||
## args
|
||||
|
||||
**> host_args**
|
||||
|
||||
# cwd
|
||||
## cwd
|
||||
|
||||
**> host_cwd**
|
||||
|
||||
# exit
|
||||
- code
|
||||
## exit
|
||||
+ `code`
|
||||
|
||||
**> host_exit code=`code`**
|
||||
|
||||
# exec
|
||||
- cmd
|
||||
## exec
|
||||
+ `cmd`
|
||||
|
||||
**> host_exec cmd=`cmd`**
|
||||
+5
-5
@@ -3,13 +3,13 @@ title: lib/table
|
||||
description: English table helpers over len / at
|
||||
---
|
||||
|
||||
# rows
|
||||
- xs
|
||||
## rows
|
||||
+ `xs`
|
||||
|
||||
**> len `xs`**
|
||||
|
||||
# row_at
|
||||
- xs
|
||||
- i
|
||||
## row_at
|
||||
+ `xs`
|
||||
+ `i`
|
||||
|
||||
**> at value=`xs` index=`i`**
|
||||
+8
-8
@@ -3,19 +3,19 @@ title: lib/text
|
||||
description: English text helpers over trim / split / join
|
||||
---
|
||||
|
||||
# str_trim
|
||||
- s
|
||||
## str_trim
|
||||
+ `s`
|
||||
|
||||
**> trim `s`**
|
||||
|
||||
# str_split
|
||||
- s
|
||||
- sep
|
||||
## str_split
|
||||
+ `s`
|
||||
+ `sep`
|
||||
|
||||
**> split value=`s` sep=`sep`**
|
||||
|
||||
# str_join
|
||||
- xs
|
||||
- sep
|
||||
## str_join
|
||||
+ `xs`
|
||||
+ `sep`
|
||||
|
||||
**> join value=`xs` sep=`sep`**
|
||||
+10
-10
@@ -3,27 +3,27 @@ title: lib/time
|
||||
description: English time wrappers
|
||||
---
|
||||
|
||||
# now_unix
|
||||
## now_unix
|
||||
|
||||
**> host_now_unix**
|
||||
|
||||
# now_ms
|
||||
## now_ms
|
||||
|
||||
**> host_now_ms**
|
||||
|
||||
# format
|
||||
- unix
|
||||
- pattern
|
||||
## format
|
||||
+ `unix`
|
||||
+ `pattern`
|
||||
|
||||
**> host_format_time unix=`unix` pattern=`pattern`**
|
||||
|
||||
# sleep_ms
|
||||
- ms
|
||||
## sleep_ms
|
||||
+ `ms`
|
||||
|
||||
**> host_sleep_ms ms=`ms`**
|
||||
|
||||
# parse
|
||||
- text
|
||||
- pattern
|
||||
## parse
|
||||
+ `text`
|
||||
+ `pattern`
|
||||
|
||||
**> host_parse_time text=`text` pattern=`pattern`**
|
||||
@@ -0,0 +1,32 @@
|
||||
---
|
||||
title: lib/writeback
|
||||
description: Persist run output in .mq.md (Jupyter-style writeback)
|
||||
---
|
||||
|
||||
## record
|
||||
+ `value`
|
||||
+ `at_end`=False
|
||||
|
||||
Write `value` to `<!-- marqdo-out … -->` in the entry file. Default: insert or replace the block immediately below the call; `at_end=true` appends a single block at EOF.
|
||||
|
||||
**> host_writeback_record value=`value` at_end=`at_end`**
|
||||
|
||||
## get
|
||||
+ `at_end`=False
|
||||
|
||||
Read persisted output for the current call site (adjacent block), or the EOF block when `at_end=true`.
|
||||
|
||||
**> host_writeback_get at_end=`at_end`**
|
||||
|
||||
## clear
|
||||
+ `at_end`=False
|
||||
|
||||
Remove the adjacent or EOF output block.
|
||||
|
||||
**> host_writeback_clear at_end=`at_end`**
|
||||
|
||||
## list
|
||||
|
||||
List all output blocks in the entry file.
|
||||
|
||||
**> host_writeback_list**
|
||||
+9
-9
@@ -3,23 +3,23 @@ title: lib/外联
|
||||
description: 通过本机解释器运行绑定的代码围栏与内联源码
|
||||
---
|
||||
|
||||
# 设置命令
|
||||
- 语言
|
||||
- 命令
|
||||
## 设置命令
|
||||
+ `语言`
|
||||
+ `命令`
|
||||
|
||||
**> host_foreign_set_cmd lang=`语言` cmd=`命令`**
|
||||
|
||||
# 运行
|
||||
- 代码
|
||||
## 运行
|
||||
+ `代码`
|
||||
|
||||
**> host_foreign_run code=`代码`**
|
||||
|
||||
# 按语言运行
|
||||
- 语言
|
||||
- 源码
|
||||
## 按语言运行
|
||||
+ `语言`
|
||||
+ `源码`
|
||||
|
||||
**> host_foreign_run_lang lang=`语言` source=`源码`**
|
||||
|
||||
# 语言表
|
||||
## 语言表
|
||||
|
||||
**> host_foreign_langs**
|
||||
@@ -0,0 +1,34 @@
|
||||
---
|
||||
title: lib/子任务
|
||||
description: 并发子任务 — 文件、函数或外联代码
|
||||
---
|
||||
|
||||
## 启动
|
||||
+ `路径`=None
|
||||
+ `函数`=None
|
||||
+ `参数`=None
|
||||
+ `代码`=None
|
||||
+ `语言`=None
|
||||
+ `源码`=None
|
||||
+ `输入`=None
|
||||
|
||||
**> host_subtask_spawn path=`路径` fn=`函数` args=`参数` code=`代码` lang=`语言` source=`源码` stdin=`输入`**
|
||||
|
||||
## 探测
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_poll id=`id`**
|
||||
|
||||
## 等待
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_join id=`id`**
|
||||
|
||||
## 终止
|
||||
+ `id`
|
||||
|
||||
**> host_subtask_kill id=`id`**
|
||||
|
||||
## 等待全部
|
||||
|
||||
**> host_subtask_wait_all**
|
||||
@@ -0,0 +1,17 @@
|
||||
---
|
||||
title: lib/插件
|
||||
description: 加载可选原生 ABI 插件(.dll / .so / .dylib)
|
||||
---
|
||||
|
||||
## 加载
|
||||
+ `路径`
|
||||
|
||||
**> host_plugin_load path=`路径`**
|
||||
|
||||
## 卸载
|
||||
|
||||
**> host_plugin_unload**
|
||||
|
||||
## 列出
|
||||
|
||||
**> host_plugin_list**
|
||||
+88
-88
@@ -3,198 +3,198 @@ title: lib/数学
|
||||
description: 高中数学 — 数值、随机、公式、作图
|
||||
---
|
||||
|
||||
# 圆周率
|
||||
## 圆周率
|
||||
|
||||
**> host_pi**
|
||||
|
||||
# 自然底数
|
||||
## 自然底数
|
||||
|
||||
**> host_e**
|
||||
|
||||
# 数
|
||||
- value
|
||||
## 数
|
||||
+ `value`
|
||||
|
||||
**> host_num value=`value`**
|
||||
|
||||
# 加
|
||||
- a
|
||||
- b
|
||||
## 加
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_add a=`a` b=`b`**
|
||||
|
||||
# 减
|
||||
- a
|
||||
- b
|
||||
## 减
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_sub a=`a` b=`b`**
|
||||
|
||||
# 乘
|
||||
- a
|
||||
- b
|
||||
## 乘
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_mul a=`a` b=`b`**
|
||||
|
||||
# 除
|
||||
- a
|
||||
- b
|
||||
## 除
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_div a=`a` b=`b`**
|
||||
|
||||
# 幂
|
||||
- a
|
||||
- b
|
||||
## 幂
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_pow a=`a` b=`b`**
|
||||
|
||||
# 负
|
||||
- value
|
||||
## 负
|
||||
+ `value`
|
||||
|
||||
**> host_math_neg value=`value`**
|
||||
|
||||
# 正弦
|
||||
- value
|
||||
## 正弦
|
||||
+ `value`
|
||||
|
||||
**> host_math_sin value=`value`**
|
||||
|
||||
# 余弦
|
||||
- value
|
||||
## 余弦
|
||||
+ `value`
|
||||
|
||||
**> host_math_cos value=`value`**
|
||||
|
||||
# 正切
|
||||
- value
|
||||
## 正切
|
||||
+ `value`
|
||||
|
||||
**> host_math_tan value=`value`**
|
||||
|
||||
# 反正弦
|
||||
- value
|
||||
## 反正弦
|
||||
+ `value`
|
||||
|
||||
**> host_math_asin value=`value`**
|
||||
|
||||
# 反余弦
|
||||
- value
|
||||
## 反余弦
|
||||
+ `value`
|
||||
|
||||
**> host_math_acos value=`value`**
|
||||
|
||||
# 反正切
|
||||
- value
|
||||
## 反正切
|
||||
+ `value`
|
||||
|
||||
**> host_math_atan value=`value`**
|
||||
|
||||
# 平方根
|
||||
- value
|
||||
## 平方根
|
||||
+ `value`
|
||||
|
||||
**> host_math_sqrt value=`value`**
|
||||
|
||||
# 绝对值
|
||||
- value
|
||||
## 绝对值
|
||||
+ `value`
|
||||
|
||||
**> host_math_abs value=`value`**
|
||||
|
||||
# 对数
|
||||
- value
|
||||
## 对数
|
||||
+ `value`
|
||||
|
||||
**> host_math_ln value=`value`**
|
||||
|
||||
# 指数
|
||||
- value
|
||||
## 指数
|
||||
+ `value`
|
||||
|
||||
**> host_math_exp value=`value`**
|
||||
|
||||
# 向下取整
|
||||
- value
|
||||
## 向下取整
|
||||
+ `value`
|
||||
|
||||
**> host_math_floor value=`value`**
|
||||
|
||||
# 向上取整
|
||||
- value
|
||||
## 向上取整
|
||||
+ `value`
|
||||
|
||||
**> host_math_ceil value=`value`**
|
||||
|
||||
# 最小
|
||||
- a
|
||||
- b
|
||||
## 最小
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_min a=`a` b=`b`**
|
||||
|
||||
# 最大
|
||||
- a
|
||||
- b
|
||||
## 最大
|
||||
+ `a`
|
||||
+ `b`
|
||||
|
||||
**> host_math_max a=`a` b=`b`**
|
||||
|
||||
# 随机
|
||||
## 随机
|
||||
|
||||
**> host_random**
|
||||
|
||||
# 随机整数
|
||||
- min
|
||||
- max
|
||||
## 随机整数
|
||||
+ `min`
|
||||
+ `max`
|
||||
|
||||
**> host_random_int min=`min` max=`max`**
|
||||
|
||||
# 设种子
|
||||
- value
|
||||
## 设种子
|
||||
+ `value`
|
||||
|
||||
**> host_seed value=`value`**
|
||||
|
||||
# 公式
|
||||
- text
|
||||
## 公式
|
||||
+ `text`
|
||||
|
||||
**> host_formula value=`text`**
|
||||
|
||||
# 化简
|
||||
- formula
|
||||
## 化简
|
||||
+ `formula`
|
||||
|
||||
**> host_simplify value=`formula`**
|
||||
|
||||
# 展开
|
||||
- formula
|
||||
## 展开
|
||||
+ `formula`
|
||||
|
||||
**> host_expand value=`formula`**
|
||||
|
||||
# 求导
|
||||
- formula
|
||||
- var
|
||||
## 求导
|
||||
+ `formula`
|
||||
+ `var`
|
||||
|
||||
**> host_diff formula=`formula` var=`var`**
|
||||
|
||||
# 代入
|
||||
- formula
|
||||
- var
|
||||
- value
|
||||
## 代入
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `value`
|
||||
|
||||
**> host_subs formula=`formula` var=`var` value=`value`**
|
||||
|
||||
# 求值
|
||||
- formula
|
||||
- var
|
||||
- value
|
||||
## 求值
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `value`
|
||||
|
||||
**> host_eval formula=`formula` var=`var` value=`value`**
|
||||
|
||||
# 求解
|
||||
- formula
|
||||
- var
|
||||
## 求解
|
||||
+ `formula`
|
||||
+ `var`
|
||||
|
||||
**> host_solve formula=`formula` var=`var`**
|
||||
|
||||
# 绘图
|
||||
- formula
|
||||
- var
|
||||
- min
|
||||
- max
|
||||
## 绘图
|
||||
+ `formula`
|
||||
+ `var`
|
||||
+ `min`
|
||||
+ `max`
|
||||
|
||||
**> host_plot formula=`formula` var=`var` min=`min` max=`max`**
|
||||
|
||||
# 绘点列
|
||||
- xs
|
||||
- ys
|
||||
## 绘点列
|
||||
+ `xs`
|
||||
+ `ys`
|
||||
|
||||
**> host_plot_points xs=`xs` ys=`ys`**
|
||||
|
||||
# 绘圆锥
|
||||
- kind
|
||||
- a
|
||||
## 绘圆锥
|
||||
+ `kind`
|
||||
+ `a`
|
||||
|
||||
**> host_plot_conic kind=`kind` a=`a`**
|
||||
+16
-16
@@ -3,39 +3,39 @@ title: lib/文件
|
||||
description: 中文文件系统包装
|
||||
---
|
||||
|
||||
# 读文本
|
||||
- 路径
|
||||
## 读文本
|
||||
+ `路径`
|
||||
|
||||
**> host_read_text path=`路径`**
|
||||
|
||||
# 写文本
|
||||
- 路径
|
||||
- 内容
|
||||
## 写文本
|
||||
+ `路径`
|
||||
+ `内容`
|
||||
|
||||
**> host_write_text path=`路径` text=`内容`**
|
||||
|
||||
# 追加文本
|
||||
- 路径
|
||||
- 内容
|
||||
## 追加文本
|
||||
+ `路径`
|
||||
+ `内容`
|
||||
|
||||
**> host_append_text path=`路径` text=`内容`**
|
||||
|
||||
# 存在
|
||||
- 路径
|
||||
## 存在
|
||||
+ `路径`
|
||||
|
||||
**> host_exists path=`路径`**
|
||||
|
||||
# 列目录
|
||||
- 路径
|
||||
## 列目录
|
||||
+ `路径`
|
||||
|
||||
**> host_list_dir path=`路径`**
|
||||
|
||||
# 建目录
|
||||
- 路径
|
||||
## 建目录
|
||||
+ `路径`
|
||||
|
||||
**> host_make_dir path=`路径`**
|
||||
|
||||
# 删除
|
||||
- 路径
|
||||
## 删除
|
||||
+ `路径`
|
||||
|
||||
**> host_remove path=`路径`**
|
||||
+8
-8
@@ -3,19 +3,19 @@ title: lib/文本
|
||||
description: 中文文本库:去空白 / 拆分 / 拼接
|
||||
---
|
||||
|
||||
# 去空白
|
||||
- s
|
||||
## 去空白
|
||||
+ `s`
|
||||
|
||||
**> trim `s`**
|
||||
|
||||
# 拆分
|
||||
- s
|
||||
- sep
|
||||
## 拆分
|
||||
+ `s`
|
||||
+ `sep`
|
||||
|
||||
**> split value=`s` sep=`sep`**
|
||||
|
||||
# 拼接
|
||||
- xs
|
||||
- sep
|
||||
## 拼接
|
||||
+ `xs`
|
||||
+ `sep`
|
||||
|
||||
**> join value=`xs` sep=`sep`**
|
||||
+10
-10
@@ -3,27 +3,27 @@ title: lib/时间
|
||||
description: 中文时间包装
|
||||
---
|
||||
|
||||
# 此刻秒
|
||||
## 此刻秒
|
||||
|
||||
**> host_now_unix**
|
||||
|
||||
# 此刻毫秒
|
||||
## 此刻毫秒
|
||||
|
||||
**> host_now_ms**
|
||||
|
||||
# 格式化
|
||||
- 秒
|
||||
- 格式
|
||||
## 格式化
|
||||
+ `秒`
|
||||
+ `格式`
|
||||
|
||||
**> host_format_time unix=`秒` pattern=`格式`**
|
||||
|
||||
# 睡眠毫秒
|
||||
- 毫秒
|
||||
## 睡眠毫秒
|
||||
+ `毫秒`
|
||||
|
||||
**> host_sleep_ms ms=`毫秒`**
|
||||
|
||||
# 解析时间
|
||||
- 内容
|
||||
- 格式
|
||||
## 解析时间
|
||||
+ `内容`
|
||||
+ `格式`
|
||||
|
||||
**> host_parse_time text=`内容` pattern=`格式`**
|
||||
+18
-12
@@ -1,33 +1,39 @@
|
||||
---
|
||||
title: lib/系统
|
||||
description: 中文系统包装
|
||||
description: 中文系统包装(加载环境 可选 路径=)
|
||||
---
|
||||
|
||||
# 取环境
|
||||
- 名
|
||||
## 取环境
|
||||
+ `名`
|
||||
|
||||
**> host_env_get name=`名`**
|
||||
|
||||
# 设环境
|
||||
- 名
|
||||
- 值
|
||||
## 设环境
|
||||
+ `名`
|
||||
+ `值`
|
||||
|
||||
**> host_env_set name=`名` value=`值`**
|
||||
|
||||
# 参数表
|
||||
## 加载环境
|
||||
|
||||
加载 `.env`(可选具名实参 `路径=`)。不覆盖已有进程环境变量。
|
||||
|
||||
**> host_dotenv_load**
|
||||
|
||||
## 参数表
|
||||
|
||||
**> host_args**
|
||||
|
||||
# 工作目录
|
||||
## 工作目录
|
||||
|
||||
**> host_cwd**
|
||||
|
||||
# 退出
|
||||
- 码
|
||||
## 退出
|
||||
+ `码`
|
||||
|
||||
**> host_exit code=`码`**
|
||||
|
||||
# 执行
|
||||
- 命令
|
||||
## 执行
|
||||
+ `命令`
|
||||
|
||||
**> host_exec cmd=`命令`**
|
||||
+20
-8
@@ -1,20 +1,32 @@
|
||||
---
|
||||
title: lib/网络
|
||||
description: 中文简易网络包装
|
||||
description: 中文 HTTP(S) 包装。可选 headers / content_type 经宿主别名绑定。
|
||||
---
|
||||
|
||||
# 获取
|
||||
- 地址
|
||||
## 获取
|
||||
+ `地址`
|
||||
|
||||
支持 HTTPS。可选具名实参 `headers=`(映射)。
|
||||
|
||||
**> host_http_get url=`地址`**
|
||||
|
||||
# 提交
|
||||
- 地址
|
||||
- 内容
|
||||
## 提交
|
||||
+ `地址`
|
||||
+ `内容`
|
||||
|
||||
默认 Content-Type 为 JSON。可选 `content_type=` / `headers=`。
|
||||
|
||||
**> host_http_post url=`地址` body=`内容`**
|
||||
|
||||
# 编码地址
|
||||
- 内容
|
||||
## 请求
|
||||
+ `方法`
|
||||
+ `地址`
|
||||
|
||||
可选 `body=` / `content_type=` / `headers=`。
|
||||
|
||||
**> host_http_request method=`方法` url=`地址`**
|
||||
|
||||
## 编码地址
|
||||
+ `内容`
|
||||
|
||||
**> host_url_encode text=`内容`**
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: lib/自写回
|
||||
description: 将运行结果写回 .mq.md(Jupyter 式自写回)
|
||||
---
|
||||
|
||||
## 写回
|
||||
+ `值`
|
||||
+ `末尾`=False
|
||||
|
||||
在入口文件中写入 `<!-- marqdo-out … -->`。默认在调用行下方插入或替换;`末尾=true` 时在文件末尾保留单块。
|
||||
|
||||
**> host_writeback_record value=`值` at_end=`末尾`**
|
||||
|
||||
## 取
|
||||
+ `末尾`=False
|
||||
|
||||
读取当前调用处紧邻块,或 `末尾=true` 时读取文件末尾块。
|
||||
|
||||
**> host_writeback_get at_end=`末尾`**
|
||||
|
||||
## 清除
|
||||
+ `末尾`=False
|
||||
|
||||
删除紧邻块或末尾块。
|
||||
|
||||
**> host_writeback_clear at_end=`末尾`**
|
||||
|
||||
## 列出
|
||||
|
||||
**> host_writeback_list**
|
||||
+5
-5
@@ -3,13 +3,13 @@ title: lib/表
|
||||
description: 中文表库:行数 / 取行
|
||||
---
|
||||
|
||||
# 行数
|
||||
- xs
|
||||
## 行数
|
||||
+ `xs`
|
||||
|
||||
**> len `xs`**
|
||||
|
||||
# 取行
|
||||
- xs
|
||||
- i
|
||||
## 取行
|
||||
+ `xs`
|
||||
+ `i`
|
||||
|
||||
**> at value=`xs` index=`i`**
|
||||
@@ -0,0 +1,39 @@
|
||||
---
|
||||
title: 人工文档
|
||||
description: 这是人工写的文档,禁止机器修改
|
||||
---
|
||||
|
||||
对于marqdo这个项目,详细的语法定义为:
|
||||
---
|
||||
|
||||
#标识对象,#main不算特殊这是一个项目的传统入口可以视为是一个对象。
|
||||
---
|
||||
##、### 、####等标识函数,不同数目表示从属关系,例如###是##函数的子函数,作用域不超过
|
||||
这个函数,使用-表示函数的变量名
|
||||
**** 空返回(None),并结束本函数体
|
||||
---
|
||||
无标记行表示注释信息,对于无标记行应该这么约定不是说开头没有符合不然就会出现:
|
||||
|
||||
**强调信息**是什么什么
|
||||
|
||||
上面应该是一个注释
|
||||
---
|
||||
程序语言使用*程序*也就是斜体表示
|
||||
---
|
||||
`变量名`表示变量
|
||||
---
|
||||
> 表示引用函数
|
||||
---
|
||||
有序列表表示分支语句
|
||||
---
|
||||
无序列表表示循环语句
|
||||
---
|
||||
公式由数学库渲染
|
||||
---
|
||||
代码片段由外联库渲染
|
||||
---
|
||||
添加一个新的标准库,自写回标准库,自写回的内容必须使用<!---->包裹,这个不会被md识别,
|
||||
但是这个可以被marqdo识别,当作提示信息或生成结果的一律表示,markdo view要能渲染,以某种方式
|
||||
---
|
||||
添加一个新的标准库,子任务库,能够自由的运行子任务,现在的调用还是顺序化的,但是子任务允许多个
|
||||
进程式的调用,子任务库将成为marqdo的护城河项目,子任务要依赖于父任务,父任务结束子任务一定结束,防止出现问题
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
这是人工构建的用于测试的样例
|
||||
|
||||
`测试目录` =
|
||||
|测试文件夹|
|
||||
|-----|
|
||||
|structure|
|
||||
|keyword|
|
||||
|lib|
|
||||
|
||||
|
||||
- [`测试文件夹`](`测试目录`)
|
||||
> 打印 `测试文件夹`
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`a` = True*
|
||||
*`b` = False*
|
||||
|
||||
1. `a` and not `b`
|
||||
> print text=ok
|
||||
2. *
|
||||
> print text=fail
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试输入
|
||||
|
||||
*`name`=> input "你叫什么名字\n"*
|
||||
|
||||
> print `name`
|
||||
@@ -0,0 +1,10 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试输出
|
||||
|
||||
> print 欢迎你
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
> lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 + 2
|
||||
$$
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*`ty` = > type `f` *
|
||||
|
||||
> print text=`ty`
|
||||
|
||||
*`df` = > diff formula=`f` var=x *
|
||||
|
||||
> print text=`df`
|
||||
|
||||
*`roots` = > solve formula=`f` var=x *
|
||||
|
||||
> print text=`roots`
|
||||
|
||||
*`y` = > eval formula=`f` var=x value=3 *
|
||||
|
||||
> print text=`y`
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
> lib/writeback.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试写回库
|
||||
|
||||
*`name`=>input "你叫什么名字?\n"*
|
||||
|
||||
> record `name`
|
||||
<!-- marqdo-out
|
||||
123132
|
||||
-->
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试分支语句
|
||||
|
||||
* `bool_value` = True *
|
||||
|
||||
1. `bool_value` == True
|
||||
> print True
|
||||
2. *
|
||||
> print False
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: 手工构造的测试样例
|
||||
description: AI禁止更改
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
测试循环语句语句
|
||||
|
||||
*`n`=0*
|
||||
|
||||
- `n` < 42
|
||||
`n`=`n`+1
|
||||
|
||||
> print `n`
|
||||
@@ -0,0 +1,14 @@
|
||||
[package]
|
||||
name = "marqdo_plugin_agent"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo agent layout plugin (ABI v1 cdylib)"
|
||||
publish = false
|
||||
|
||||
[lib]
|
||||
name = "agent"
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
serde_json = "1"
|
||||
@@ -0,0 +1,574 @@
|
||||
//! Agent layout plugin (C ABI v1): find_root, ensure_layout, probe, scaffold.
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::path::{Component, Path, PathBuf};
|
||||
use std::ptr;
|
||||
|
||||
const ABI_VERSION: u32 = 1;
|
||||
const DEFAULT_MARKERS: &str = "agents,runbooks,marqdo.agent.json";
|
||||
const LAYOUT_DIRS: &[&str] = &["agents", "runbooks", "templates", "reports"];
|
||||
|
||||
type PluginFn = unsafe extern "C" fn(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
#[repr(C)]
|
||||
pub struct MarqdoHostApi {
|
||||
pub userdata: *mut c_void,
|
||||
pub register_fn: Option<
|
||||
unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
params: *const c_char,
|
||||
fn_ptr: PluginFn,
|
||||
) -> c_int,
|
||||
>,
|
||||
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
|
||||
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
|
||||
}
|
||||
|
||||
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
|
||||
unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn parse_args(args_json: *const c_char) -> Result<serde_json::Value, String> {
|
||||
if args_json.is_null() {
|
||||
return Err("null args".into());
|
||||
}
|
||||
let s = unsafe { CStr::from_ptr(args_json) }
|
||||
.to_str()
|
||||
.map_err(|_| "args not utf-8".to_string())?;
|
||||
serde_json::from_str(s).map_err(|e| e.to_string())
|
||||
}
|
||||
|
||||
fn arg_str<'a>(v: &'a serde_json::Value, key: &str) -> Result<&'a str, String> {
|
||||
v.get(key)
|
||||
.and_then(|x| x.as_str())
|
||||
.ok_or_else(|| format!("missing text `{key}`"))
|
||||
}
|
||||
|
||||
fn has_parent_escape(rel: &Path) -> bool {
|
||||
rel.components().any(|c| matches!(c, Component::ParentDir))
|
||||
}
|
||||
|
||||
fn find_root(start: &str, markers: &str) -> Result<PathBuf, String> {
|
||||
let markers: Vec<&str> = markers
|
||||
.split(',')
|
||||
.map(|s| s.trim())
|
||||
.filter(|s| !s.is_empty())
|
||||
.collect();
|
||||
if markers.is_empty() {
|
||||
return Err("empty markers".into());
|
||||
}
|
||||
let mut cur = PathBuf::from(start);
|
||||
if cur.as_os_str().is_empty() {
|
||||
cur = std::env::current_dir().map_err(|e| e.to_string())?;
|
||||
}
|
||||
if !cur.exists() {
|
||||
return Err(format!("start path missing: {}", cur.display()));
|
||||
}
|
||||
let mut cur = std::fs::canonicalize(&cur).map_err(|e| e.to_string())?;
|
||||
loop {
|
||||
for m in &markers {
|
||||
let p = cur.join(m);
|
||||
let ok = if m.contains('.') {
|
||||
p.is_file()
|
||||
} else {
|
||||
p.is_dir()
|
||||
};
|
||||
if ok {
|
||||
return Ok(cur);
|
||||
}
|
||||
}
|
||||
if !cur.pop() {
|
||||
break;
|
||||
}
|
||||
}
|
||||
Err("agent project root not found".into())
|
||||
}
|
||||
|
||||
fn ensure_layout(root: &Path) -> Result<i64, String> {
|
||||
let root = std::fs::canonicalize(root).map_err(|e| e.to_string())?;
|
||||
let mut created = 0i64;
|
||||
for d in LAYOUT_DIRS {
|
||||
let p = root.join(d);
|
||||
if !p.exists() {
|
||||
std::fs::create_dir_all(&p).map_err(|e| e.to_string())?;
|
||||
created += 1;
|
||||
} else if !p.is_dir() {
|
||||
return Err(format!("{} exists and is not a directory", p.display()));
|
||||
}
|
||||
}
|
||||
Ok(created)
|
||||
}
|
||||
|
||||
fn probe(root: &Path) -> Result<serde_json::Value, String> {
|
||||
let root = std::fs::canonicalize(root).map_err(|e| e.to_string())?;
|
||||
let mut map = serde_json::Map::new();
|
||||
map.insert(
|
||||
"root".into(),
|
||||
serde_json::Value::String(root.to_string_lossy().into_owned()),
|
||||
);
|
||||
for d in LAYOUT_DIRS {
|
||||
let key = format!("has_{d}");
|
||||
map.insert(key, serde_json::Value::Bool(root.join(d).is_dir()));
|
||||
}
|
||||
Ok(serde_json::Value::Object(map))
|
||||
}
|
||||
|
||||
fn scaffold(root: &Path, name: &str, template: &str, dest: &str) -> Result<String, String> {
|
||||
if name.is_empty() {
|
||||
return Err("name is empty".into());
|
||||
}
|
||||
let root = std::fs::canonicalize(root).map_err(|e| e.to_string())?;
|
||||
let tmpl_rel = Path::new(template);
|
||||
let dest_rel = Path::new(dest);
|
||||
if has_parent_escape(tmpl_rel) {
|
||||
return Err("template path escapes project root".into());
|
||||
}
|
||||
if has_parent_escape(dest_rel) {
|
||||
return Err("dest path escapes project root".into());
|
||||
}
|
||||
let tmpl_path = root.join(tmpl_rel);
|
||||
if !tmpl_path.is_file() {
|
||||
return Err(format!("template not found: {}", tmpl_path.display()));
|
||||
}
|
||||
let tmpl_can = std::fs::canonicalize(&tmpl_path).map_err(|e| e.to_string())?;
|
||||
if !tmpl_can.starts_with(&root) {
|
||||
return Err("template path escapes project root".into());
|
||||
}
|
||||
let dest_path = root.join(dest_rel);
|
||||
if let Some(parent) = dest_path.parent() {
|
||||
std::fs::create_dir_all(parent).map_err(|e| e.to_string())?;
|
||||
let parent_can = std::fs::canonicalize(parent).map_err(|e| e.to_string())?;
|
||||
if !parent_can.starts_with(&root) {
|
||||
return Err("dest path escapes project root".into());
|
||||
}
|
||||
}
|
||||
let body = std::fs::read_to_string(&tmpl_can).map_err(|e| e.to_string())?;
|
||||
let body = body.replace("{{name}}", name);
|
||||
std::fs::write(&dest_path, body).map_err(|e| e.to_string())?;
|
||||
Ok(dest_path.to_string_lossy().into_owned())
|
||||
}
|
||||
|
||||
fn map_get_str<'a>(m: &'a serde_json::Value, keys: &[&str]) -> Option<&'a str> {
|
||||
let obj = m.as_object()?;
|
||||
for k in keys {
|
||||
if let Some(v) = obj.get(*k) {
|
||||
if let Some(s) = v.as_str() {
|
||||
return Some(s);
|
||||
}
|
||||
if let Some(n) = v.as_i64() {
|
||||
// allow numeric fields to be read as display later
|
||||
let _ = n;
|
||||
}
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
fn map_get_i64(m: &serde_json::Value, keys: &[&str]) -> i64 {
|
||||
let Some(obj) = m.as_object() else {
|
||||
return i64::MAX;
|
||||
};
|
||||
for k in keys {
|
||||
if let Some(v) = obj.get(*k) {
|
||||
if let Some(n) = v.as_i64() {
|
||||
return n;
|
||||
}
|
||||
if let Some(s) = v.as_str() {
|
||||
if let Ok(n) = s.parse::<i64>() {
|
||||
return n;
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
i64::MAX
|
||||
}
|
||||
|
||||
fn skills_text(m: &serde_json::Value) -> String {
|
||||
map_get_str(m, &["技能", "skills", "skill"])
|
||||
.unwrap_or("")
|
||||
.to_string()
|
||||
}
|
||||
|
||||
fn match_skill(skill: &str, members: &serde_json::Value) -> Result<serde_json::Value, String> {
|
||||
let arr = members
|
||||
.as_array()
|
||||
.ok_or_else(|| "members must be a JSON array".to_string())?;
|
||||
let skill = skill.trim();
|
||||
if skill.is_empty() {
|
||||
return Err("skill is empty".into());
|
||||
}
|
||||
let mut best: Option<&serde_json::Value> = None;
|
||||
let mut best_load = i64::MAX;
|
||||
for m in arr {
|
||||
let sk = skills_text(m);
|
||||
if sk.split(',').any(|p| p.trim() == skill) || sk.contains(skill) {
|
||||
let load = map_get_i64(m, &["负载", "load"]);
|
||||
if load < best_load {
|
||||
best_load = load;
|
||||
best = Some(m);
|
||||
}
|
||||
}
|
||||
}
|
||||
Ok(best.cloned().unwrap_or(serde_json::Value::Null))
|
||||
}
|
||||
|
||||
fn bump_load(member: &serde_json::Value, delta: i64) -> Result<serde_json::Value, String> {
|
||||
let mut obj = member
|
||||
.as_object()
|
||||
.cloned()
|
||||
.ok_or_else(|| "member must be a JSON object".to_string())?;
|
||||
let key = if obj.contains_key("负载") {
|
||||
"负载"
|
||||
} else if obj.contains_key("load") {
|
||||
"load"
|
||||
} else {
|
||||
obj.insert("负载".into(), serde_json::Value::Number(0.into()));
|
||||
"负载"
|
||||
};
|
||||
let cur = match obj.get(key) {
|
||||
Some(serde_json::Value::Number(n)) => n.as_i64().unwrap_or(0),
|
||||
Some(serde_json::Value::String(s)) => s.parse().unwrap_or(0),
|
||||
_ => 0,
|
||||
};
|
||||
obj.insert(
|
||||
key.into(),
|
||||
serde_json::Value::Number((cur + delta).into()),
|
||||
);
|
||||
Ok(serde_json::Value::Object(obj))
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_find_root(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_find_root: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let start = match arg_str(&v, "start") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_find_root: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let markers = v
|
||||
.get("markers")
|
||||
.and_then(|x| x.as_str())
|
||||
.filter(|s| !s.is_empty())
|
||||
.unwrap_or(DEFAULT_MARKERS);
|
||||
match find_root(start, markers) {
|
||||
Ok(p) => {
|
||||
let out = serde_json::Value::String(p.to_string_lossy().into_owned()).to_string();
|
||||
set_out(out_json, &out);
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_find_root: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_ensure_layout(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_ensure_layout: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let root = match arg_str(&v, "root") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_ensure_layout: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
match ensure_layout(Path::new(root)) {
|
||||
Ok(n) => {
|
||||
set_out(out_json, &n.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_ensure_layout: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_probe(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_probe: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let root = match arg_str(&v, "root") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_probe: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
match probe(Path::new(root)) {
|
||||
Ok(j) => {
|
||||
set_out(out_json, &j.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_probe: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_scaffold(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let root = match arg_str(&v, "root") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let name = match arg_str(&v, "name") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let template = match arg_str(&v, "template") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let dest = match arg_str(&v, "dest") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
match scaffold(Path::new(root), name, template, dest) {
|
||||
Ok(p) => {
|
||||
let out = serde_json::Value::String(p).to_string();
|
||||
set_out(out_json, &out);
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_scaffold: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_match_skill(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_match_skill: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let skill = match arg_str(&v, "skill") {
|
||||
Ok(s) => s,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_match_skill: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let members = match v.get("members") {
|
||||
Some(m) => m.clone(),
|
||||
None => {
|
||||
set_err(err_msg, "agent_match_skill: missing members");
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
// members may be a JSON string (from Marqdo stringify) or already an array
|
||||
let members = if let Some(s) = members.as_str() {
|
||||
match serde_json::from_str::<serde_json::Value>(s) {
|
||||
Ok(j) => j,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_match_skill: members JSON: {e}"));
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
} else {
|
||||
members
|
||||
};
|
||||
match match_skill(skill, &members) {
|
||||
Ok(j) => {
|
||||
set_out(out_json, &j.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_match_skill: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn agent_bump_load(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
let v = match parse_args(args_json) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_bump_load: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let member = match v.get("member") {
|
||||
Some(m) => m.clone(),
|
||||
None => {
|
||||
set_err(err_msg, "agent_bump_load: missing member");
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let member = if let Some(s) = member.as_str() {
|
||||
match serde_json::from_str::<serde_json::Value>(s) {
|
||||
Ok(j) => j,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_bump_load: member JSON: {e}"));
|
||||
return 1;
|
||||
}
|
||||
}
|
||||
} else {
|
||||
member
|
||||
};
|
||||
let delta = v.get("delta").and_then(|x| x.as_i64()).unwrap_or(1);
|
||||
match bump_load(&member, delta) {
|
||||
Ok(j) => {
|
||||
set_out(out_json, &j.to_string());
|
||||
0
|
||||
}
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("agent_bump_load: {e}"));
|
||||
1
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
fn register(host: &MarqdoHostApi, name: &str, params: &str, fn_ptr: PluginFn) -> c_int {
|
||||
let register = match host.register_fn {
|
||||
Some(f) => f,
|
||||
None => return 1,
|
||||
};
|
||||
let n = CString::new(name).unwrap();
|
||||
let p = CString::new(params).unwrap();
|
||||
unsafe { register(host.userdata, n.as_ptr(), p.as_ptr(), fn_ptr) }
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
ABI_VERSION
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
if register(host, "agent_find_root", "start,markers", agent_find_root) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_ensure_layout", "root", agent_ensure_layout) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_probe", "root", agent_probe) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(
|
||||
host,
|
||||
"agent_scaffold",
|
||||
"root,name,template,dest",
|
||||
agent_scaffold,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_match_skill", "skill,members", agent_match_skill) != 0 {
|
||||
return 1;
|
||||
}
|
||||
if register(host, "agent_bump_load", "member,delta", agent_bump_load) != 0 {
|
||||
return 1;
|
||||
}
|
||||
0
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {
|
||||
HOST_ALLOC = None;
|
||||
HOST_FREE = None;
|
||||
}
|
||||
@@ -0,0 +1,14 @@
|
||||
[package]
|
||||
name = "marqdo_plugin_demo"
|
||||
version = "0.1.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Demo Marqdo ABI v1 plugin (cdylib)"
|
||||
publish = false
|
||||
|
||||
[lib]
|
||||
name = "demo"
|
||||
crate-type = ["cdylib"]
|
||||
|
||||
[dependencies]
|
||||
serde_json = "1"
|
||||
@@ -0,0 +1,170 @@
|
||||
//! Demo Marqdo plugin (C ABI v1). Registers `demo_add` and `demo_echo`.
|
||||
|
||||
use std::ffi::{CStr, CString};
|
||||
use std::os::raw::{c_char, c_int, c_void};
|
||||
use std::ptr;
|
||||
|
||||
const ABI_VERSION: u32 = 1;
|
||||
|
||||
type PluginFn = unsafe extern "C" fn(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int;
|
||||
|
||||
#[repr(C)]
|
||||
pub struct MarqdoHostApi {
|
||||
pub userdata: *mut c_void,
|
||||
pub register_fn: Option<
|
||||
unsafe extern "C" fn(
|
||||
userdata: *mut c_void,
|
||||
name: *const c_char,
|
||||
params: *const c_char,
|
||||
fn_ptr: PluginFn,
|
||||
) -> c_int,
|
||||
>,
|
||||
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
|
||||
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
|
||||
}
|
||||
|
||||
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
|
||||
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
|
||||
|
||||
unsafe fn host_strdup(s: &str) -> *mut c_char {
|
||||
let alloc = HOST_ALLOC.expect("host alloc");
|
||||
let bytes = s.as_bytes();
|
||||
let p = alloc(bytes.len() + 1) as *mut u8;
|
||||
if p.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
|
||||
*p.add(bytes.len()) = 0;
|
||||
p as *mut c_char
|
||||
}
|
||||
|
||||
fn set_out(out: *mut *mut c_char, s: &str) {
|
||||
if out.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*out = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
fn set_err(err: *mut *mut c_char, s: &str) {
|
||||
if err.is_null() {
|
||||
return;
|
||||
}
|
||||
unsafe {
|
||||
*err = host_strdup(s);
|
||||
}
|
||||
}
|
||||
|
||||
unsafe extern "C" fn demo_add(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
if args_json.is_null() {
|
||||
set_err(err_msg, "demo_add: null args");
|
||||
return 1;
|
||||
}
|
||||
let s = match CStr::from_ptr(args_json).to_str() {
|
||||
Ok(s) => s,
|
||||
Err(_) => {
|
||||
set_err(err_msg, "demo_add: args not utf-8");
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let v: serde_json::Value = match serde_json::from_str(s) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("demo_add: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let a = v.get("a").and_then(|x| x.as_i64()).unwrap_or(0);
|
||||
let b = v.get("b").and_then(|x| x.as_i64()).unwrap_or(0);
|
||||
set_out(out_json, &(a + b).to_string());
|
||||
0
|
||||
}
|
||||
|
||||
unsafe extern "C" fn demo_echo(
|
||||
args_json: *const c_char,
|
||||
out_json: *mut *mut c_char,
|
||||
err_msg: *mut *mut c_char,
|
||||
) -> c_int {
|
||||
if args_json.is_null() {
|
||||
set_err(err_msg, "demo_echo: null args");
|
||||
return 1;
|
||||
}
|
||||
let s = match CStr::from_ptr(args_json).to_str() {
|
||||
Ok(s) => s,
|
||||
Err(_) => {
|
||||
set_err(err_msg, "demo_echo: args not utf-8");
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let v: serde_json::Value = match serde_json::from_str(s) {
|
||||
Ok(v) => v,
|
||||
Err(e) => {
|
||||
set_err(err_msg, &format!("demo_echo: {e}"));
|
||||
return 1;
|
||||
}
|
||||
};
|
||||
let text = v
|
||||
.get("text")
|
||||
.and_then(|x| x.as_str())
|
||||
.unwrap_or("");
|
||||
let out = serde_json::Value::String(text.to_string()).to_string();
|
||||
set_out(out_json, &out);
|
||||
0
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
|
||||
ABI_VERSION
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int {
|
||||
if host.is_null() {
|
||||
return 1;
|
||||
}
|
||||
let host = &*host;
|
||||
HOST_ALLOC = host.alloc;
|
||||
HOST_FREE = host.free;
|
||||
let register = match host.register_fn {
|
||||
Some(f) => f,
|
||||
None => return 1,
|
||||
};
|
||||
let name_add = CString::new("demo_add").unwrap();
|
||||
let params_add = CString::new("a,b").unwrap();
|
||||
if register(
|
||||
host.userdata,
|
||||
name_add.as_ptr(),
|
||||
params_add.as_ptr(),
|
||||
demo_add,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
let name_echo = CString::new("demo_echo").unwrap();
|
||||
let params_echo = CString::new("text").unwrap();
|
||||
if register(
|
||||
host.userdata,
|
||||
name_echo.as_ptr(),
|
||||
params_echo.as_ptr(),
|
||||
demo_echo,
|
||||
) != 0
|
||||
{
|
||||
return 1;
|
||||
}
|
||||
0
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {
|
||||
HOST_ALLOC = None;
|
||||
HOST_FREE = None;
|
||||
}
|
||||
@@ -24,7 +24,7 @@ Named args can include spaces:
|
||||
> greet who=marqdo user
|
||||
|
||||
## greet
|
||||
- who
|
||||
+ `who`
|
||||
|
||||
> print text=Welcome, `who`!
|
||||
|
||||
|
||||
+1
-1
@@ -24,7 +24,7 @@ English docs: [`00-welcome.mq.md`](00-welcome.mq.md) (English prose and English
|
||||
> 问候 谁=marqdo user
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
+ `谁`
|
||||
|
||||
> 打印 内容=欢迎,`谁`!
|
||||
|
||||
|
||||
+4
-2
@@ -9,8 +9,10 @@
|
||||
| [`00-welcome.mq.md`](00-welcome.mq.md) / [`00-欢迎.mq.md`](00-欢迎.mq.md) | 首页(英 / 中) |
|
||||
| [`structure/`](structure/) | 基本结构 |
|
||||
| [`keywords/`](keywords/) | 关键字与 L0 内置 |
|
||||
| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联) |
|
||||
| [`features/`](features/) | 特性迭代 |
|
||||
| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联/插件/**自写回**/**子任务**;v0.1.2+ 内置于 CLI) |
|
||||
| [`features/`](features/) | 特性迭代(含对象、官方 `ext/`) |
|
||||
|
||||
官方扩展(非 stdlib):`ext/llm`、`ext/agent` — 见 `features/05-extensions.mq.md` / `05-扩展.mq.md` 与 `doc/design/ext-*.md`。
|
||||
|
||||
**不放** `errors/`:失败样例只在 `tests/errors/`。
|
||||
|
||||
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: Objects and methods
|
||||
description: Sharp heading is a type; deeper headings are functions or methods
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
In Marqdo, a single sharp (#) defines an object / type constructor. Double sharp and deeper (## …) define free functions or methods. Constructing an object yields a map handle tagged with _type. Call methods with backtick object, then dot, then method name.
|
||||
|
||||
See doc/design/objects.md. Example gold: tests/structure/object-handle.mq.md. Official ext/llm and ext/agent use this pattern.
|
||||
|
||||
> print text=objects-ok
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: 对象与方法
|
||||
description: 一级标题是类型;更深标题是函数或方法
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Marqdo 中,单个井号(#)定义对象 / 类型构造体;二级及以上(## …)定义自由函数或方法。构造得到带 _type 标记的 map 句柄。方法调用形如:反引号对象、点、方法名。
|
||||
|
||||
详见 doc/design/objects.md。金样例:tests/structure/object-handle.mq.md。官方 ext/llm 与 ext/agent 使用同一模式。
|
||||
|
||||
> 打印 内容=对象就绪
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: Official extensions (ext/)
|
||||
description: Optional packages — not stdlib
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
ext/ holds official optional extensions. They are not part of lib/. Resolve via MARQDO_EXT, ./ext, or ext/ next to the binary.
|
||||
|
||||
- ext/llm — OpenAI-compatible chat object. Design: doc/design/ext-llm.md
|
||||
- ext/agent — agent development framework (layout helpers today; compose with ext/llm for model-backed orchestration). Design: doc/design/ext-agent.md
|
||||
- Installer: marqdo ext list / add / remove — doc/design/ext-cli.md
|
||||
- Native plugins: lib/plugin + include/marqdo_abi.h — doc/design/ext-abi.md
|
||||
|
||||
> print text=ext-ok
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: 官方扩展(ext/)
|
||||
description: 可选包 — 不是标准库
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
ext/ 存放官方可选扩展,不属于 lib/。解析顺序:MARQDO_EXT、./ext、或可执行文件旁的 ext/。
|
||||
|
||||
- ext/llm(ext/大模型)— OpenAI 兼容聊天。设计:doc/design/ext-llm.md
|
||||
- ext/agent(ext/智能体)— 智能体开发框架(当前含布局助手;与大模型组合做编排见路线)。设计:doc/design/ext-agent.md
|
||||
- 安装器:marqdo ext list / add / remove — doc/design/ext-cli.md
|
||||
- 通用原生插件:lib/plugin + include/marqdo_abi.h — doc/design/ext-abi.md
|
||||
|
||||
> 打印 内容=扩展就绪
|
||||
@@ -10,14 +10,14 @@ Keywords: `True`, `False`, `None`, and `and` / `or` / `not`.
|
||||
*`a` = True*
|
||||
*`b` = False*
|
||||
|
||||
+ `a` and not `b`
|
||||
1. `a` and not `b`
|
||||
> print text=ok
|
||||
+ *
|
||||
2. *
|
||||
> print text=fail
|
||||
|
||||
*`probe` = 1*
|
||||
|
||||
+ None
|
||||
1. None
|
||||
> print text=none-truthy
|
||||
+ *
|
||||
2. *
|
||||
> print text=none-falsy
|
||||
@@ -10,14 +10,14 @@ description: 真 / 假 / 空 与 且 / 或 / 非
|
||||
*`a` = 真*
|
||||
*`b` = 假*
|
||||
|
||||
+ `a` 且 非 `b`
|
||||
1. `a` 且 非 `b`
|
||||
> 打印 内容=通过
|
||||
+ *
|
||||
2. *
|
||||
> 打印 内容=失败
|
||||
|
||||
*`probe` = 1*
|
||||
|
||||
+ 空
|
||||
1. 空
|
||||
> 打印 内容=空为真
|
||||
+ *
|
||||
2. *
|
||||
> 打印 内容=空为假
|
||||
@@ -11,7 +11,11 @@ English-named files export English APIs; Chinese-named files export Chinese APIs
|
||||
|
||||
No extra allow flags: importing a module means you intend to use it. Under marqdo view or static export, exit soft-fails and long sleeps are clamped so the console stays up.
|
||||
|
||||
Modules: text (text / 文本), table (table / 表), files (fs / 文件), time (time / 时间), system (sys / 系统), json (json only), net (net / 网络), math (math / 数学), foreign (foreign / 外联).
|
||||
Modules: text (text / 文本), table (table / 表), files (fs / 文件), time (time / 时间), system (sys / 系统), json (json only), net (net / 网络), math (math / 数学), foreign (foreign / 外联), plugin (plugin / 插件), writeback (writeback / 自写回), subtask (subtask / 子任务).
|
||||
|
||||
From **v0.1.2**, official `lib/*.mq.md` is **embedded in the `marqdo` binary** (disk `lib/` or `MARQDO_LIB` still overrides). Standalone `.exe` works without a separate stdlib zip.
|
||||
|
||||
Official optional extensions live under ext/ (not stdlib): ext/llm, ext/agent — see features/05-extensions.mq.md and doc/design/ext-llm.md / ext-agent.md.
|
||||
|
||||
Sibling pages in this folder document each module. Chinese overview: 00-索引.mq.md.
|
||||
|
||||
|
||||
@@ -11,7 +11,11 @@ description: 如何导入官方 lib 模块
|
||||
|
||||
导入即表示要用对应能力,无需再加允许旗标。marqdo view 或静态导出里,退出会软失败、长睡眠会被钳制,以免拖垮控制台。
|
||||
|
||||
模块:文本(text / 文本)、表(table / 表)、文件(fs / 文件)、时间(time / 时间)、系统(sys / 系统)、json(仅 json)、网络(net / 网络)、数学(math / 数学)、外联(foreign / 外联)。
|
||||
模块:文本(text / 文本)、表(table / 表)、文件(fs / 文件)、时间(time / 时间)、系统(sys / 系统)、json(仅 json)、网络(net / 网络)、数学(math / 数学)、外联(foreign / 外联)、插件(plugin / 插件)、自写回(writeback / 自写回)、子任务(subtask / 子任务)。
|
||||
|
||||
自 **v0.1.2** 起,官方 `lib/*.mq.md` **内置于 `marqdo` 二进制**(磁盘 `lib/` 或 `MARQDO_LIB` 仍可覆盖)。单独下载 `.exe` 即可导入标准库,无需再解压 stdlib 包。
|
||||
|
||||
官方可选扩展在 ext/(不是标准库):ext/llm、ext/agent — 见 features/05-扩展.mq.md。
|
||||
|
||||
各模块说明见本目录其它页。English: 00-overview.mq.md.
|
||||
|
||||
|
||||
@@ -12,7 +12,7 @@ Bare path words must not contain a slash character (parsed as division). Prefer
|
||||
|
||||
*`ok` = > exists path=demo.txt *
|
||||
|
||||
+ `ok`
|
||||
1. `ok`
|
||||
> print text=demo-present
|
||||
+ *
|
||||
2. *
|
||||
> print text=demo-missing
|
||||
@@ -6,7 +6,7 @@ description: Shared EN/ZH path; parse and stringify
|
||||
|
||||
# main
|
||||
|
||||
Import lib/json.mq.md from both English and Chinese docs (no translated twin). Functions: parse(text), stringify(value), get(value, key), keys(value). Objects become the map runtime type.
|
||||
Import lib/json.mq.md from both English and Chinese docs (no translated twin). Functions: parse(text), stringify(value), get(value, key), keys(value), quote(text) — JSON string literal with quotes (for building request bodies). Objects become the map runtime type.
|
||||
|
||||
*`obj` = > parse text={} *
|
||||
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
title: lib/net — HTTP
|
||||
description: Minimal HTTP client and URL encode
|
||||
title: lib/net — HTTP(S)
|
||||
description: Minimal HTTP(S) client and URL encode
|
||||
> lib/net.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Import lib/net.mq.md. Functions: http_get(url) returns map status/body, http_post(url, body), url_encode(text). v1 speaks cleartext http only.
|
||||
Import lib/net.mq.md. Functions: http_get(url), http_post(url, body), http_request(method, url), url_encode(text). HTTPS and optional headers= map are supported. Default post content-type is JSON.
|
||||
|
||||
*`e` = > url_encode text=hello world *
|
||||
|
||||
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: lib/plugin — native ABI
|
||||
description: Load optional shared libraries (.dll / .so / .dylib)
|
||||
> lib/plugin.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Import lib/plugin.mq.md. Functions: load(path), unload(), list(). After load, registered plugin names are callable like other functions. C ABI: include/marqdo_abi.h — see doc/design/ext-abi.md. Path must stay under the program sandbox (cwd / fs root).
|
||||
|
||||
*`names` = > list *
|
||||
|
||||
*`n` = > len `names` *
|
||||
|
||||
1. `n` >= 0
|
||||
> print text=plugin-ok
|
||||
2. *
|
||||
> print text=plugin-bad
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: lib/subtask — concurrent tasks
|
||||
description: Spawn file, function, or foreign code in parallel
|
||||
> lib/subtask.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`spawn` picks **one** mode (others default to `None`):
|
||||
|
||||
| Argument | Runs | `wait` returns |
|
||||
|----------|------|----------------|
|
||||
| `path=` | `marqdo run` child process | exit code |
|
||||
| `fn=` + optional `args=` | function in a thread (entry module) | return value |
|
||||
| `code=` | foreign ``` fence ``` subprocess | stdout text |
|
||||
| `lang=` + `source=` | foreign source subprocess | stdout text |
|
||||
|
||||
Also: `poll id=`, `kill id=`, `wait_all`. Parent exit kills file/foreign children.
|
||||
|
||||
> print text=subtask overview ok
|
||||
@@ -1,18 +1,18 @@
|
||||
---
|
||||
title: lib/sys — process
|
||||
description: Env, cwd, args, exit, exec
|
||||
description: Env, dotenv, cwd, args, exit, exec
|
||||
> lib/sys.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Import lib/sys.mq.md. Functions: env_get, env_set, args, cwd, exit(code), exec(cmd). Under view, exit soft-fails instead of killing the process.
|
||||
Import lib/sys.mq.md. Functions: env_get, env_set, load_dotenv(optional path), args, cwd, exit(code), exec(cmd). load_dotenv does not override existing variables. Under view, exit soft-fails instead of killing the process.
|
||||
|
||||
*`d` = > cwd *
|
||||
|
||||
*`n` = > len `d` *
|
||||
|
||||
+ `n` > 0
|
||||
1. `n` > 0
|
||||
> print text=cwd-ok
|
||||
+ *
|
||||
2. *
|
||||
> print text=cwd-empty
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: lib/writeback — Jupyter-style writeback
|
||||
description: Persist run output in the entry .mq.md file
|
||||
> lib/writeback.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Writeback stores output in `<!-- marqdo-out … -->` blocks in the **entry** file (the one you run).
|
||||
|
||||
- `record value=` — default: insert or replace the block **below the call**; `at_end=true` → single block at EOF
|
||||
- `get` / `clear` — read or remove the adjacent block (or EOF block when `at_end=true`)
|
||||
- `list` — all output blocks in the entry file
|
||||
|
||||
> print text=writeback overview ok
|
||||
@@ -0,0 +1,20 @@
|
||||
---
|
||||
title: lib/子任务 — 并发子任务
|
||||
description: 文件、函数或外联代码并行执行
|
||||
> lib/子任务.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`启动`(`spawn`)四选一(其余参数默认 `None`):
|
||||
|
||||
| 参数 | 方式 | `等待` 返回 |
|
||||
|------|------|-------------|
|
||||
| `路径=` | `marqdo run` 子进程 | 退出码 |
|
||||
| `函数=` + 可选 `参数=` | 入口模块中的函数(线程) | 返回值 |
|
||||
| `代码=` | 外联代码块子进程 | stdout 文本 |
|
||||
| `语言=` + `源码=` | 外联源码子进程 | stdout 文本 |
|
||||
|
||||
另有:`探测`、`终止`、`等待全部`。父进程结束会终止文件/外联子进程。
|
||||
|
||||
> 打印 内容=子任务总览就绪
|
||||
@@ -0,0 +1,18 @@
|
||||
---
|
||||
title: lib/插件 — 原生 ABI
|
||||
description: 加载可选共享库(.dll / .so / .dylib)
|
||||
> lib/插件.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
导入 lib/插件.mq.md。函数:加载(路径)、卸载()、列出()。加载后,插件注册的名称可像普通函数一样调用。C 契约见 include/marqdo_abi.h 与 doc/design/ext-abi.md。路径须落在程序沙箱内。
|
||||
|
||||
*`names` = > 列出 *
|
||||
|
||||
*`n` = > 长度 值=`names` *
|
||||
|
||||
1. `n` >= 0
|
||||
> 打印 内容=插件就绪
|
||||
2. *
|
||||
> 打印 内容=插件异常
|
||||
@@ -12,7 +12,7 @@ description: 沙箱内读写文本
|
||||
|
||||
*`ok` = > 存在 路径=demo.txt *
|
||||
|
||||
+ `ok`
|
||||
1. `ok`
|
||||
> 打印 内容=有演示文件
|
||||
+ *
|
||||
2. *
|
||||
> 打印 内容=无演示文件
|
||||
@@ -1,18 +1,18 @@
|
||||
---
|
||||
title: lib/系统 — 进程
|
||||
description: 环境变量、工作目录、参数、退出、执行
|
||||
description: 环境变量、dotenv、工作目录、参数、退出、执行
|
||||
> lib/系统.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
导入 lib/系统.mq.md。函数:取环境、设环境、参数表、工作目录、退出(码)、执行(命令)。view 下退出会软失败,不结束进程。
|
||||
导入 lib/系统.mq.md。函数:取环境、设环境、加载环境(可选路径)、参数表、工作目录、退出(码)、执行(命令)。加载环境不覆盖已有变量。view 下退出会软失败,不结束进程。
|
||||
|
||||
*`d` = > 工作目录 *
|
||||
|
||||
*`n` = > 长度 值=`d` *
|
||||
|
||||
+ `n` > 0
|
||||
1. `n` > 0
|
||||
> 打印 内容=工作目录就绪
|
||||
+ *
|
||||
2. *
|
||||
> 打印 内容=工作目录空
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
title: lib/网络 — HTTP
|
||||
description: 简易 HTTP 与地址编码
|
||||
description: HTTP(S) 与地址编码
|
||||
> lib/网络.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
导入 lib/网络.mq.md。函数:获取(地址) 返回 map status/body、提交(地址, 内容)、编码地址(内容)。本波仅明文 http。
|
||||
导入 lib/网络.mq.md。函数:获取(地址)、提交(地址, 内容;可选 content_type / headers)、编码地址(内容)。支持 HTTP 与 HTTPS(ureq)。
|
||||
|
||||
*`e` = > 编码地址 内容=你好 *
|
||||
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
title: lib/自写回 — Jupyter 式写回
|
||||
description: 把运行结果写回入口 .mq.md
|
||||
> lib/自写回.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
自写回把结果写入入口文件(你 `run` 的那份 `.mq.md`)里的 `<!-- marqdo-out … -->` 块。
|
||||
|
||||
- `记录 内容=`(`record`)— 默认写在调用下方;`at_end=真` 则在文件末尾单独一块
|
||||
- `读取` / `清除` — 读或删相邻块(`at_end` 时指 EOF 块)
|
||||
- `列表` — 列出文件中所有输出块
|
||||
|
||||
> 打印 内容=自写回总览就绪
|
||||
@@ -12,6 +12,6 @@ Call with `>` and named args `param=value`:
|
||||
> greet who=World
|
||||
|
||||
## greet
|
||||
- who
|
||||
+ `who`
|
||||
|
||||
> print text=Hello `who`!
|
||||
@@ -12,6 +12,6 @@ description: `#` 定义函数;`>` 调用;`-` 列出参数名
|
||||
> 问候 谁=世界
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
+ `谁`
|
||||
|
||||
> 打印 内容=你好 `谁`!
|
||||
@@ -14,6 +14,6 @@ Named form still works:
|
||||
> greet who=World
|
||||
|
||||
## greet
|
||||
- who
|
||||
+ `who`
|
||||
|
||||
> print text=Hello `who`!
|
||||
@@ -14,6 +14,6 @@ description: 按参数声明顺序绑定;具名写法仍然可用
|
||||
> 问候 谁=世界
|
||||
|
||||
## 问候
|
||||
- 谁
|
||||
+ `谁`
|
||||
|
||||
> 打印 内容=你好 `谁`!
|
||||
@@ -9,9 +9,9 @@ Italic lines are statements. Branches use `+`; a head that is only `*` is the el
|
||||
|
||||
*`x` = 0*
|
||||
|
||||
+ `x` > 0
|
||||
1. `x` > 0
|
||||
> print text=positive
|
||||
+ `x` < 0
|
||||
2. `x` < 0
|
||||
> print text=negative
|
||||
+ *
|
||||
3. *
|
||||
> print text=zero
|
||||
Loaded 100 of 176 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user