Add ext/agent layout framework, ext CLI, and docs catch-up.
Ship ABI agent plugin helpers, marqdo ext list/add/remove, and document the agent development roadmap (compose LLM, match/assign). Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
1 parent
b0c777c480
commit
3a7e11c995
45 files changed
+1632
-204
No files matched your search
@@ -19,7 +19,7 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
|
||||
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: `+` branch, `-` loop, arm-head lone `*` = else, `#` = function, `**…**` = return.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: `+` branch, `-` loop, arm-head lone `*` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
|
||||
5. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
|
||||
6. **Paths in bare expressions:** `/` is division. Prefer `` `path` `` vars, same-dir names, or call args — not raw `a/b` in expressions.
|
||||
7. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
|
||||
@@ -121,8 +121,8 @@ title: example
|
||||
|
||||
- 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/llm.mq.md` / `ext/大模型.mq.md` — `# llm` / `# 大模型` object handles + `## complete` / `## 运行`. Free `## load_env`. See `doc/design/ext-llm.md` and `doc/design/objects.md`.
|
||||
- Native plugins (optional shared libs): `lib/plugin.mq.md` / `lib/插件.mq.md` — `## load` / `## unload` / `## list`; after load, registered names are callable directly. C ABI: `include/marqdo_abi.h`, design `doc/design/ext-abi.md`, demo `plugins/demo`.
|
||||
- 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).
|
||||
|
||||
@@ -105,7 +105,29 @@ description: loads math
|
||||
> print text=`t`
|
||||
```
|
||||
|
||||
## 9. What not to emit
|
||||
## 9. 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` / `自`.
|
||||
|
||||
## 10. 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`).
|
||||
|
||||
## 11. What not to emit
|
||||
|
||||
```markdown
|
||||
# BAD — bold is return, not print
|
||||
|
||||
@@ -11,13 +11,16 @@ 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).
|
||||
|
||||
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`、`./ext`、或可执行文件旁 `ext/`。对象原语见 `doc/design/objects.md`。LLM:`ext/llm.mq.md` / `ext/大模型.mq.md`(`# llm` 句柄 + `` `x`.complete `` / `` `x`.运行 ``;项目本地 `.env` 配密钥)。
|
||||
官方扩展(`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)
|
||||
|
||||
@@ -48,8 +51,9 @@ Import one file; use **that** file’s function names.
|
||||
| `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/` to see exact `#` function names and parameters. Gold tests: `tests/lib/`, `tests/structure/`.
|
||||
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)
|
||||
|
||||
@@ -117,7 +121,13 @@ See `doc/design/call-arguments.md`.
|
||||
| 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 |
|
||||
+10
-1
@@ -1,10 +1,19 @@
|
||||
/target/
|
||||
/dist/
|
||||
|
||||
# Copied by gold harness for ABI plugin demo
|
||||
# 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/agents/
|
||||
/tests/ext/runbooks/
|
||||
/tests/ext/templates/
|
||||
/tests/ext/reports/
|
||||
**/*.rs.bk
|
||||
.idea/
|
||||
.vscode/
|
||||
|
||||
Generated
+7
@@ -453,6 +453,13 @@ dependencies = [
|
||||
"zeroize",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_agent"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_demo"
|
||||
version = "0.1.0"
|
||||
|
||||
+1
-1
@@ -26,7 +26,7 @@ zeroize = "=1.8.1"
|
||||
libloading = "=0.8.6"
|
||||
|
||||
[workspace]
|
||||
members = ["plugins/demo"]
|
||||
members = ["plugins/demo", "plugins/agent"]
|
||||
resolver = "2"
|
||||
|
||||
[dev-dependencies]
|
||||
|
||||
@@ -6,7 +6,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
||||
|
||||
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 `vscode-extension`) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[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`) · **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/)
|
||||
|
||||
---
|
||||
|
||||
@@ -32,7 +32,9 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
| `**…**` | **返回值**(架构) |
|
||||
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
|
||||
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
|
||||
| `#` / `##` | 函数与作用域 |
|
||||
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
|
||||
| `##` … | 函数 / 方法(按标题深度嵌套) |
|
||||
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
|
||||
| `+` / `1.` | 分支(臂头单独 `*` = else) |
|
||||
| `-` | 循环(头下纯名则为形参) |
|
||||
| 表格 | 集合 |
|
||||
@@ -98,10 +100,13 @@ marqdo catalog public -o .marqdo
|
||||
## 现状(v0.1.1)
|
||||
|
||||
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Source)
|
||||
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
|
||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
|
||||
- 标准库:文本、文件、系统、时间、JSON、网络、数学(公式/绘图)、外联(Python 等)
|
||||
- 标准库:文本、文件、系统(含 `load_dotenv`)、时间、JSON(含 `quote`)、网络(HTTPS + headers)、数学(公式/绘图)、外联(Python 等)、**插件**(`lib/plugin` 加载原生 ABI)
|
||||
- **官方扩展 `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`;Release 附带 `.vsix`(Run / View / Debug + CLI 安装助手)
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
|
||||
@@ -116,7 +121,7 @@ cargo run -- view output public -o public
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
**发布包(GitHub Releases)**:单独 `.exe` **不含** `lib/` / `ext/`;请下载带 `lib/`(及可选 `ext/`)的 zip,或另下 `*-stdlib.zip` 解压到可执行文件旁(亦可设 `MARQDO_LIB` / `MARQDO_EXT`)。OpenAI 兼容聊天见 [ext-llm.md](doc/design/ext-llm.md)(在项目目录自建 `.env`,勿提交密钥)。
|
||||
**发布包(GitHub Releases)**:单独 `.exe` **不含** `lib/` / `ext/` / 原生插件 `.dll`;请下载带 `lib/`(及可选 `ext/`)的 zip,或另下 `*-stdlib.zip` 解压到可执行文件旁(亦可设 `MARQDO_LIB` / `MARQDO_EXT`)。OpenAI 兼容聊天见 [ext-llm.md](doc/design/ext-llm.md)(项目目录自建 `.env`,勿提交密钥)。智能体布局见 [ext-agent.md](doc/design/ext-agent.md)(`MARQDO_AGENT_PLUGIN` 指向构建出的 `agent` 共享库)。
|
||||
|
||||
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md)
|
||||
|
||||
|
||||
+9
-4
@@ -16,6 +16,7 @@
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [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) | 语句/返回/输出决议 |
|
||||
@@ -25,11 +26,15 @@
|
||||
| [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` 黑白极简 + 静态文档** |
|
||||
|
||||
+24
-4
@@ -5,6 +5,7 @@
|
||||
| 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
|
||||
|
||||
@@ -36,7 +37,13 @@ Arguments and results are **UTF-8 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
|
||||
## Marqdo surface (`lib/plugin` / `lib/插件`)
|
||||
|
||||
| English | Chinese | Host |
|
||||
|---------|---------|------|
|
||||
| `## load` (`path`) | `## 加载` (`路径`) | `host_plugin_load` |
|
||||
| `## unload` | `## 卸载` | `host_plugin_unload` |
|
||||
| `## list` | `## 列出` | `host_plugin_list` |
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -53,13 +60,26 @@ Plugin fn returns `0` + `*out_json` on success; non-zero + optional `*err_msg` o
|
||||
|
||||
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
|
||||
|
||||
Workspace crate `plugins/demo` (`marqdo_plugin_demo`) builds a cdylib registering `demo_add` and `demo_echo`.
|
||||
```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
|
||||
- Embedding plugins in the release exe by default
|
||||
- Callbacks from plugin into arbitrary Marqdo evaluation
|
||||
- OS sandbox / seccomp
|
||||
- Auto-download of plugins
|
||||
- **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,164 @@
|
||||
# Official agent development framework (`ext/agent`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted (v0.1 layout) · **roadmap recorded** |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [objects.md](objects.md) · [markdown-mapping.md](markdown-mapping.md) |
|
||||
|
||||
## Positioning
|
||||
|
||||
`ext/agent` / `ext/智能体` is an **official agent-development framework**, not a single chatbot wrapper.
|
||||
|
||||
| Layer | Role |
|
||||
|-------|------|
|
||||
| **Marqdo program** | Orchestration: tables, loops, branches, narration — **prompts and control flow live in the same `.mq.md`** |
|
||||
| **`ext/llm`** | Model I/O (chat / complete); agent framework **imports and uses** it |
|
||||
| **`ext/agent`** | Workspace conventions + (roadmap) match / assign / report helpers; optional **ABI** for heavy or OS-bound work |
|
||||
| **`lib/*`** | fs / json / sys / net / table — generic I/O |
|
||||
|
||||
**Why Marqdo:** an agent runbook is readable docs and executable policy at once. Skill matrices, task queues, and escalation rules stay next to the prose that explains them.
|
||||
|
||||
```text
|
||||
user agent .mq.md
|
||||
│ > ext/agent.mq.md (+ often > ext/llm.mq.md)
|
||||
▼
|
||||
framework (# agent / # 智能体 + helpers)
|
||||
├── ext/llm → model
|
||||
├── lib/fs|json|… → data / side effects
|
||||
└── plugins/agent → ABI helpers (layout today; more later)
|
||||
```
|
||||
|
||||
Install story for end users (not yet shipped): [`ext-cli.md`](ext-cli.md) — `marqdo ext add agent` / `add llm`.
|
||||
|
||||
---
|
||||
|
||||
## Shipped in v0.1 (layout)
|
||||
|
||||
**Layout framework** for agent-oriented projects:
|
||||
|
||||
- Convention dirs under a project root
|
||||
- Native helpers via **ABI v1** (`plugins/agent`)
|
||||
- Marqdo object API in `ext/agent.mq.md` / `ext/智能体.mq.md`
|
||||
|
||||
### Project layout
|
||||
|
||||
| Path | Role |
|
||||
|------|------|
|
||||
| `agents/` | Agent programs (`.mq.md`) |
|
||||
| `runbooks/` | Executable handbooks / checks |
|
||||
| `templates/` | Scaffold sources |
|
||||
| `reports/` | Generated artifacts (convention: gitignore) |
|
||||
|
||||
Root markers (any): directory `agents` or `runbooks`, or file `marqdo.agent.json`.
|
||||
|
||||
### ABI surface (`plugins/agent`)
|
||||
|
||||
| Name | Params | Result |
|
||||
|------|--------|--------|
|
||||
| `agent_find_root` | `start`, `markers` | text path |
|
||||
| `agent_ensure_layout` | `root` | int (dirs created) |
|
||||
| `agent_probe` | `root` | map (`has_agents`, …, `root`) |
|
||||
| `agent_scaffold` | `root`, `name`, `template`, `dest` | path written; body substitutes `{{name}}` |
|
||||
|
||||
Path safety: under `root`; reject `..`. Build: `cargo build -p marqdo_plugin_agent`.
|
||||
|
||||
### Marqdo surface (v0.1)
|
||||
|
||||
| English | Chinese | Role |
|
||||
|---------|---------|------|
|
||||
| `## load_native` | `## 加载原生` | Env `MARQDO_AGENT_PLUGIN` → `lib/plugin` load |
|
||||
| `# agent` | `# 智能体` | Workspace handle; optional `root=` |
|
||||
| `## probe` | `## 探测` | Layout probe |
|
||||
| `## ensure_layout` | `## 确保布局` | Create convention dirs |
|
||||
| `## scaffold` | `## 脚手架` | `name=` `template=` `dest=` |
|
||||
|
||||
Gold: `tests/ext/agent-scaffold.mq.md`.
|
||||
|
||||
---
|
||||
|
||||
## Target product (record — not all implemented)
|
||||
|
||||
Framework should make it natural to write agents like **task assignment**: read queues and skill tables, match people, assign or escalate — with optional LLM for soft matching / message drafting.
|
||||
|
||||
### Orchestration sketch (illustrative)
|
||||
|
||||
Syntax below is **aspirational**; names need not match final APIs. Point is: **tables + loop + framework methods + narration**.
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/agent.mq.md
|
||||
> ext/llm.mq.md
|
||||
> lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load_env
|
||||
> load_native
|
||||
|
||||
*`model` = > llm *
|
||||
*`bot` = > agent *
|
||||
|
||||
团队成员技能表
|
||||
|
||||
*`技能表` =
|
||||
| 成员 | 技能 | 负载 |
|
||||
|------|------|------|
|
||||
| 张三 | Python, ML | 2 |
|
||||
| 李四 | 前端, UX | 1 |
|
||||
| 王五 | 后端, 运维 | 3 |
|
||||
| 赵六 | 数据分析 | 0 |
|
||||
|
||||
*`任务队列` =
|
||||
| 任务ID | 所需技能 | 优先级 |
|
||||
|--------|----------|--------|
|
||||
| T001 | Python | 高 |
|
||||
| T002 | 前端 | 中 |
|
||||
| T003 | 安全审计 | 高 |
|
||||
|
||||
> 分配策略 任务队列=`任务队列` 技能表=`技能表` model=`model` bot=`bot`
|
||||
|
||||
## 分配策略
|
||||
- 任务队列
|
||||
- 技能表
|
||||
- model
|
||||
- bot
|
||||
|
||||
- [任务](任务队列)
|
||||
*`匹配` = > `bot`.技能匹配 技能=`任务`.所需技能 成员表=`技能表` model=`model` *
|
||||
|
||||
+ `匹配`
|
||||
*`结果` = > `bot`.分配任务 任务ID=`任务`.任务ID 分配给=`匹配` *
|
||||
+ …
|
||||
> `bot`.通知 … # or lib/net / future channel helpers
|
||||
+ *
|
||||
> `bot`.创建工单 标题=… 详情=…
|
||||
|
||||
> 完成报告
|
||||
```
|
||||
|
||||
Marqdo strengths here:
|
||||
|
||||
1. **Prompt next to policy** — escalation wording and match rules sit in the same file as the loop.
|
||||
2. **Tables as data** — skill matrix / queue are first-class collections.
|
||||
3. **LLM as a tool** — `ext/llm` for fuzzy skill match or message text; deterministic path when tables suffice.
|
||||
4. **Objects** — `# agent` / `# llm` handles; methods keep the runbook short.
|
||||
|
||||
Exact helper names (`技能匹配` / `match_skill`, `分配任务` / `assign`, …) to be fixed when implementing; may be pure Marqdo over `lib/table` + `ext/llm`, with ABI only where native code helps.
|
||||
|
||||
### Roadmap slices (ordered)
|
||||
|
||||
| Slice | Content |
|
||||
|-------|---------|
|
||||
| **A — Install** | [`ext-cli.md`](ext-cli.md): **shipped** `marqdo ext list` / `add` / `remove` |
|
||||
| **B — Compose LLM** | `ext/agent` frontmatter imports `ext/llm`; helpers that take a model handle or call `complete` internally |
|
||||
| **C — Match / assign** | Table-oriented match (substring / tag) + optional LLM rerank; assign + load update; escalate / ticket stubs (print or `reports/` files first) |
|
||||
| **D — Channels** | Optional notify hooks (mail/chat) via `lib/net` or thin ABI — still no third-party marketplace |
|
||||
| **E — Multi-agent** | Later: handoff between agent programs; out of scope until C is solid |
|
||||
|
||||
### Non-goals (still)
|
||||
|
||||
- Third-party plugin registry / arbitrary remote packages
|
||||
- Embedding native plugins inside the main `marqdo` exe by default
|
||||
- Replacing `ext/llm` with a second chat stack inside agent
|
||||
@@ -0,0 +1,48 @@
|
||||
# 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) · [ext-abi.md](ext-abi.md) |
|
||||
|
||||
## Commands
|
||||
|
||||
```text
|
||||
marqdo ext list # official catalog + installed?
|
||||
marqdo ext add llm # install into local ext directory
|
||||
marqdo ext add agent # .mq.md + platform native plugin
|
||||
marqdo ext remove llm
|
||||
```
|
||||
|
||||
## Install root
|
||||
|
||||
1. `MARQDO_EXT` if set
|
||||
2. Else `~/.marqdo/ext` (`%USERPROFILE%\.marqdo\ext` on Windows)
|
||||
|
||||
`ext/…` import resolution also searches this default user dir (see [`load.rs`](../../src/load.rs)).
|
||||
|
||||
## Source for `add`
|
||||
|
||||
1. `MARQDO_EXT_SOURCE` — directory containing `llm.mq.md` / `agent.mq.md` …
|
||||
2. Else `./ext` near cwd / next to the binary (dev: Marqdo repo `ext/`)
|
||||
|
||||
Native plugin for `agent`: `target/debug|release/agent.dll` (or `libagent.so` / `libagent.dylib`), or `MARQDO_EXT_SOURCE/native/`.
|
||||
|
||||
`ext add agent` also writes `agent.plugin` (absolute path) and `native/<lib>`; `## load_native` uses `host_ext_native_path` when `MARQDO_AGENT_PLUGIN` is unset. Plugin load may open trusted paths under the install root (sandbox allowlist).
|
||||
|
||||
## Catalog
|
||||
|
||||
| Id | Ships |
|
||||
|----|-------|
|
||||
| `llm` | `llm.mq.md`, `大模型.mq.md` |
|
||||
| `agent` | `agent.mq.md`, `智能体.mq.md` + native |
|
||||
|
||||
## Tests
|
||||
|
||||
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent_with_native`.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Third-party registry / arbitrary download URLs as default
|
||||
- Merging into `lib/`
|
||||
+12
-3
@@ -1,10 +1,10 @@
|
||||
# Official extensions (`ext/`)
|
||||
# Official extensions (`ext/`) — LLM
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | Accepted (v0.1.x) |
|
||||
| Date | 2026-08-06 |
|
||||
| Related | [objects.md](objects.md) · native plugins later → [ext-abi.md](ext-abi.md) |
|
||||
| Related | [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) |
|
||||
|
||||
## Scope
|
||||
|
||||
@@ -18,12 +18,16 @@
|
||||
|
||||
Resolution: `MARQDO_EXT`, `./ext`, `ext/` next to the binary (same pattern as `MARQDO_LIB`).
|
||||
|
||||
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` for end-user install ([ext-cli.md](ext-cli.md)). Resolving `> ext/llm.mq.md` from a repo checkout or local `ext/` still works without the installer.
|
||||
|
||||
## Platform prerequisites
|
||||
|
||||
| Capability | Surface |
|
||||
|------------|---------|
|
||||
| HTTPS + headers | `lib/net` → `http_post` / `headers=` map |
|
||||
| Dotenv | `## load_env` in ext (or `load_dotenv` host) |
|
||||
| Dotenv | `## load_env` in ext (or `load_dotenv` / `lib/sys`) |
|
||||
| JSON quote | `lib/json` → `quote` |
|
||||
|
||||
## `ext/llm` / `ext/大模型` (object handles)
|
||||
@@ -57,3 +61,8 @@ 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 only): `tests/ext/llm-complete.mq.md` + gitignored `tests/ext/.env` — do not commit API keys
|
||||
@@ -2,10 +2,10 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定论(修订:语句 / 返回 / 输出职责分离) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 状态 | 已定论(修订:语句 / 返回 / 输出职责分离;`#` = 对象) |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 取代 | v0 中「`**`=输出、`*`=返回」 |
|
||||
| 相关 | [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) |
|
||||
| 相关 | [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))。
|
||||
|
||||
@@ -16,7 +16,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
1. `.mq.md`:打开即文档,运行即程序。
|
||||
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
|
||||
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` 表…)与 **斜体语句** / **粗体返回**。
|
||||
4. 作用域 = `#` 层数;入口 = `index.mq.md`。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
||||
4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -2,8 +2,8 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已定(v1)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 状态 | **已落地(v1)** |
|
||||
| 日期 | 2026-08-06 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
|
||||
|
||||
---
|
||||
|
||||
+84
-139
@@ -1,32 +1,32 @@
|
||||
# 标准库下一波(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 共享库) |
|
||||
|
||||
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` — 见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -34,35 +34,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,23 +98,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` | 新写入的键数量;缺文件 → `0`;不覆盖已有环境变量 |
|
||||
| `load_dotenv` | `加载环境` | 可选 `path` | 见上 |
|
||||
| `args` | `参数表` | (无) | 文本列表 |
|
||||
| `cwd` | `工作目录` | (无) | 文本 |
|
||||
| `exit` | `退出` | `code` / `码` | 不返回 |
|
||||
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码(实现时写死语义) |
|
||||
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码 |
|
||||
|
||||
`exec` 默认关(`--allow-exec`);view / 静态站永不开放。
|
||||
|
||||
### 3.3 时间 — `time` / `时间`
|
||||
#### 时间 — `time` / `时间`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
@@ -100,133 +120,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 字符串字面量(含引号,便于拼请求体) |
|
||||
| `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**(ureq);短超时、响应体上限;默认 CLI 开网络。可选具名实参 `headers=`(map)、`content_type=`;`http_post` 默认 JSON Content-Type。
|
||||
|
||||
**路径字面量:** 具名实参里 `path=a/b` 会被解析成除法。请用无斜杠文件名,或先赋给变量再传入。
|
||||
|
||||
官方可选扩展(非 stdlib):[`ext-llm.md`](ext-llm.md)(`ext/llm` OpenAI 兼容聊天)。
|
||||
|
||||
---
|
||||
|
||||
## 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)。**
|
||||
+18
-13
@@ -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` | 拼接文本 |
|
||||
@@ -56,21 +58,24 @@ Frontmatter:
|
||||
3. 当前工作目录的 `lib/`
|
||||
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
|
||||
|
||||
当前模块:
|
||||
当前模块(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/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,58 @@
|
||||
---
|
||||
title: ext/agent
|
||||
description: Agent project layout via ABI plugin (English). Not stdlib — import ext/agent.mq.md.
|
||||
> lib/plugin.mq.md
|
||||
> lib/sys.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## load_native
|
||||
|
||||
Load `plugins/agent` shared library. Order: env `MARQDO_AGENT_PLUGIN`, then installed path from `marqdo ext add agent` (`host_ext_native_path`).
|
||||
|
||||
*`envp` = > env_get name=MARQDO_AGENT_PLUGIN *
|
||||
+ `envp`
|
||||
**> load path=`envp`**
|
||||
+ *
|
||||
*`np` = > host_ext_native_path name=agent *
|
||||
+ `np`
|
||||
**> load path=`np`**
|
||||
+ *
|
||||
> print text=ext/agent: set MARQDO_AGENT_PLUGIN or run marqdo ext add agent
|
||||
> exit code=1
|
||||
|
||||
# agent
|
||||
- root
|
||||
|
||||
Construct a workspace handle. Optional `root=`; otherwise `agent_find_root` from cwd.
|
||||
|
||||
+ `root`
|
||||
*`r` = `root`*
|
||||
+ *
|
||||
*`start` = > cwd *
|
||||
*`r` = > agent_find_root start=`start` markers=agents,runbooks,marqdo.agent.json *
|
||||
|
||||
*`t` = > parse text={"p":"{\"_type\":\"agent\",\"root\":","s":"}"} *
|
||||
*`qr` = > quote text=`r` *
|
||||
*`p` = > get value=`t` key=p *
|
||||
*`s` = > get value=`t` key=s *
|
||||
*`raw` = `p` + `qr` + `s` *
|
||||
**> parse text=`raw`**
|
||||
|
||||
## probe
|
||||
|
||||
*`root` = > get value=`self` key=root *
|
||||
**> agent_probe root=`root`**
|
||||
|
||||
## ensure_layout
|
||||
|
||||
*`root` = > get value=`self` key=root *
|
||||
**> agent_ensure_layout root=`root`**
|
||||
|
||||
## scaffold
|
||||
- name
|
||||
- template
|
||||
- dest
|
||||
|
||||
*`root` = > get value=`self` key=root *
|
||||
**> agent_scaffold root=`root` name=`name` template=`template` dest=`dest`**
|
||||
@@ -0,0 +1,58 @@
|
||||
---
|
||||
title: ext/智能体
|
||||
description: 经 ABI 插件的智能体项目布局(中文)。非标准库 — 导入 ext/智能体.mq.md。
|
||||
> lib/插件.mq.md
|
||||
> lib/系统.mq.md
|
||||
> lib/json.mq.md
|
||||
---
|
||||
|
||||
## 加载原生
|
||||
|
||||
加载 `plugins/agent` 共享库。顺序:环境变量 `MARQDO_AGENT_PLUGIN`,否则 `marqdo ext add agent` 安装路径(`host_ext_native_path`)。
|
||||
|
||||
*`环境路径` = > 取环境 名=MARQDO_AGENT_PLUGIN *
|
||||
+ `环境路径`
|
||||
**> 加载 路径=`环境路径`**
|
||||
+ *
|
||||
*`原生` = > host_ext_native_path name=agent *
|
||||
+ `原生`
|
||||
**> 加载 路径=`原生`**
|
||||
+ *
|
||||
> 打印 内容=ext/智能体: 请设置 MARQDO_AGENT_PLUGIN 或执行 marqdo ext add agent
|
||||
> 退出 码=1
|
||||
|
||||
# 智能体
|
||||
- 根
|
||||
|
||||
构造工作区句柄。可选 `根=`;否则从工作目录向上 `agent_find_root`。
|
||||
|
||||
+ `根`
|
||||
*`r` = `根`*
|
||||
+ *
|
||||
*`起点` = > 工作目录 *
|
||||
*`r` = > agent_find_root start=`起点` markers=agents,runbooks,marqdo.agent.json *
|
||||
|
||||
*`t` = > parse text={"p":"{\"_type\":\"智能体\",\"root\":","s":"}"} *
|
||||
*`qr` = > quote text=`r` *
|
||||
*`p` = > get value=`t` key=p *
|
||||
*`s` = > get value=`t` key=s *
|
||||
*`raw` = `p` + `qr` + `s` *
|
||||
**> parse text=`raw`**
|
||||
|
||||
## 探测
|
||||
|
||||
*`root` = > get value=`自` key=root *
|
||||
**> agent_probe root=`root`**
|
||||
|
||||
## 确保布局
|
||||
|
||||
*`root` = > get value=`自` key=root *
|
||||
**> agent_ensure_layout root=`root`**
|
||||
|
||||
## 脚手架
|
||||
- 名
|
||||
- 模板
|
||||
- 目标
|
||||
|
||||
*`root` = > get value=`自` key=root *
|
||||
**> agent_scaffold root=`root` name=`名` template=`模板` dest=`目标`**
|
||||
@@ -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,386 @@
|
||||
//! 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())
|
||||
}
|
||||
|
||||
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
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
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;
|
||||
}
|
||||
0
|
||||
}
|
||||
|
||||
#[no_mangle]
|
||||
pub unsafe extern "C" fn marqdo_plugin_shutdown() {
|
||||
HOST_ALLOC = None;
|
||||
HOST_FREE = None;
|
||||
}
|
||||
+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/网络/数学/外联/插件) |
|
||||
| [`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
|
||||
|
||||
> 打印 内容=扩展就绪
|
||||
@@ -11,7 +11,9 @@ 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 / 插件).
|
||||
|
||||
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,9 @@ 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 / 插件)。
|
||||
|
||||
官方可选扩展在 ext/(不是标准库):ext/llm、ext/agent — 见 features/05-扩展.mq.md。
|
||||
|
||||
各模块说明见本目录其它页。English: 00-overview.mq.md.
|
||||
|
||||
|
||||
@@ -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={} *
|
||||
|
||||
|
||||
@@ -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` *
|
||||
|
||||
+ `n` >= 0
|
||||
> print text=plugin-ok
|
||||
+ *
|
||||
> print text=plugin-bad
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
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 *
|
||||
|
||||
|
||||
@@ -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` *
|
||||
|
||||
+ `n` >= 0
|
||||
> 打印 内容=插件就绪
|
||||
+ *
|
||||
> 打印 内容=插件异常
|
||||
@@ -1,12 +1,12 @@
|
||||
---
|
||||
title: lib/系统 — 进程
|
||||
description: 环境变量、工作目录、参数、退出、执行
|
||||
description: 环境变量、dotenv、工作目录、参数、退出、执行
|
||||
> lib/系统.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
导入 lib/系统.mq.md。函数:取环境、设环境、参数表、工作目录、退出(码)、执行(命令)。view 下退出会软失败,不结束进程。
|
||||
导入 lib/系统.mq.md。函数:取环境、设环境、加载环境(可选路径)、参数表、工作目录、退出(码)、执行(命令)。加载环境不覆盖已有变量。view 下退出会软失败,不结束进程。
|
||||
|
||||
*`d` = > 工作目录 *
|
||||
|
||||
|
||||
@@ -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` = > 编码地址 内容=你好 *
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
|
||||
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: `+` branch, `-` loop, arm-head lone `*` = else, `#` = function, `**…**` = return.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: `+` branch, `-` loop, arm-head lone `*` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
|
||||
5. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
|
||||
6. **Paths in bare expressions:** `/` is division. Prefer `` `path` `` vars, same-dir names, or call args — not raw `a/b` in expressions.
|
||||
7. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
|
||||
@@ -121,8 +121,8 @@ title: example
|
||||
|
||||
- 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/llm.mq.md` / `ext/大模型.mq.md` — `# llm` / `# 大模型` object handles + `## complete` / `## 运行`. Free `## load_env`. See `doc/design/ext-llm.md` and `doc/design/objects.md`.
|
||||
- Native plugins (optional shared libs): `lib/plugin.mq.md` / `lib/插件.mq.md` — `## load` / `## unload` / `## list`; after load, registered names are callable directly. C ABI: `include/marqdo_abi.h`, design `doc/design/ext-abi.md`, demo `plugins/demo`.
|
||||
- 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).
|
||||
|
||||
@@ -105,7 +105,29 @@ description: loads math
|
||||
> print text=`t`
|
||||
```
|
||||
|
||||
## 9. What not to emit
|
||||
## 9. 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` / `自`.
|
||||
|
||||
## 10. 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`).
|
||||
|
||||
## 11. What not to emit
|
||||
|
||||
```markdown
|
||||
# BAD — bold is return, not print
|
||||
|
||||
@@ -11,13 +11,16 @@ 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).
|
||||
|
||||
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`、`./ext`、或可执行文件旁 `ext/`。对象原语见 `doc/design/objects.md`。LLM:`ext/llm.mq.md` / `ext/大模型.mq.md`(`# llm` 句柄 + `` `x`.complete `` / `` `x`.运行 ``;项目本地 `.env` 配密钥)。
|
||||
官方扩展(`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)
|
||||
|
||||
@@ -48,8 +51,9 @@ Import one file; use **that** file’s function names.
|
||||
| `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/` to see exact `#` function names and parameters. Gold tests: `tests/lib/`, `tests/structure/`.
|
||||
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)
|
||||
|
||||
@@ -117,7 +121,13 @@ See `doc/design/call-arguments.md`.
|
||||
| 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 |
|
||||
+303
@@ -0,0 +1,303 @@
|
||||
//! Official extension installer (`marqdo ext list|add|remove`).
|
||||
|
||||
use std::env;
|
||||
use std::fs;
|
||||
use std::path::{Path, PathBuf};
|
||||
|
||||
use anyhow::{bail, Context, Result};
|
||||
|
||||
/// Official extension catalog entry.
|
||||
#[derive(Debug, Clone)]
|
||||
pub struct ExtPackage {
|
||||
pub id: &'static str,
|
||||
pub description: &'static str,
|
||||
/// Files relative to a source `ext/` directory (UTF-8 paths).
|
||||
pub mq_files: &'static [&'static str],
|
||||
/// If set, also install native plugin named by [`native_lib_filename`].
|
||||
pub native_crate: Option<&'static str>,
|
||||
}
|
||||
|
||||
pub const CATALOG: &[ExtPackage] = &[
|
||||
ExtPackage {
|
||||
id: "llm",
|
||||
description: "OpenAI-compatible chat object (ext/llm)",
|
||||
mq_files: &["llm.mq.md", "大模型.mq.md"],
|
||||
native_crate: None,
|
||||
},
|
||||
ExtPackage {
|
||||
id: "agent",
|
||||
description: "Agent development framework (ext/agent + ABI plugin)",
|
||||
mq_files: &["agent.mq.md", "智能体.mq.md"],
|
||||
native_crate: Some("marqdo_plugin_agent"),
|
||||
},
|
||||
];
|
||||
|
||||
pub fn find_package(id: &str) -> Option<&'static ExtPackage> {
|
||||
let id = id.trim();
|
||||
CATALOG.iter().find(|p| p.id == id)
|
||||
}
|
||||
|
||||
/// Default install root: `MARQDO_EXT` if set, else `~/.marqdo/ext`.
|
||||
pub fn install_root() -> Result<PathBuf> {
|
||||
if let Ok(h) = env::var("MARQDO_EXT") {
|
||||
let p = PathBuf::from(h);
|
||||
if !p.as_os_str().is_empty() {
|
||||
return Ok(p);
|
||||
}
|
||||
}
|
||||
Ok(default_user_ext_dir())
|
||||
}
|
||||
|
||||
pub fn default_user_ext_dir() -> PathBuf {
|
||||
dirs_next_home()
|
||||
.unwrap_or_else(|| PathBuf::from("."))
|
||||
.join(".marqdo")
|
||||
.join("ext")
|
||||
}
|
||||
|
||||
fn dirs_next_home() -> Option<PathBuf> {
|
||||
env::var_os("USERPROFILE")
|
||||
.or_else(|| env::var_os("HOME"))
|
||||
.map(PathBuf::from)
|
||||
}
|
||||
|
||||
/// Trusted roots for native plugins (sandbox bypass for `host_plugin_load`).
|
||||
pub fn trusted_plugin_roots() -> Vec<PathBuf> {
|
||||
let mut roots = Vec::new();
|
||||
if let Ok(h) = env::var("MARQDO_EXT") {
|
||||
roots.push(PathBuf::from(h));
|
||||
}
|
||||
roots.push(default_user_ext_dir());
|
||||
if let Ok(exe) = env::current_exe() {
|
||||
if let Some(dir) = exe.parent() {
|
||||
roots.push(dir.join("ext"));
|
||||
}
|
||||
}
|
||||
roots
|
||||
}
|
||||
|
||||
pub fn native_lib_filename() -> &'static str {
|
||||
if cfg!(windows) {
|
||||
"agent.dll"
|
||||
} else if cfg!(target_os = "macos") {
|
||||
"libagent.dylib"
|
||||
} else {
|
||||
"libagent.so"
|
||||
}
|
||||
}
|
||||
|
||||
pub fn is_installed(root: &Path, pkg: &ExtPackage) -> bool {
|
||||
pkg.mq_files
|
||||
.iter()
|
||||
.all(|f| root.join(f).is_file())
|
||||
}
|
||||
|
||||
pub fn list_ext() -> Result<()> {
|
||||
let root = install_root()?;
|
||||
println!("Install root: {}", root.display());
|
||||
println!();
|
||||
println!(
|
||||
"{:<10} {:<8} {}",
|
||||
"ID", "STATUS", "DESCRIPTION"
|
||||
);
|
||||
println!("{:-<10} {:-<8} {:-<40}", "", "", "");
|
||||
for pkg in CATALOG {
|
||||
let status = if is_installed(&root, pkg) {
|
||||
"yes"
|
||||
} else {
|
||||
"no"
|
||||
};
|
||||
println!("{:<10} {:<8} {}", pkg.id, status, pkg.description);
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Directories that may contain source `ext/*.mq.md` for `add` (dev / release layout).
|
||||
pub fn source_ext_roots() -> Vec<PathBuf> {
|
||||
let mut roots = Vec::new();
|
||||
if let Ok(h) = env::var("MARQDO_EXT_SOURCE") {
|
||||
roots.push(PathBuf::from(h));
|
||||
}
|
||||
if let Ok(cwd) = env::current_dir() {
|
||||
roots.push(cwd.join("ext"));
|
||||
// cargo test / run from repo root
|
||||
roots.push(cwd.join("..").join("ext"));
|
||||
}
|
||||
if let Ok(exe) = env::current_exe() {
|
||||
if let Some(dir) = exe.parent() {
|
||||
roots.push(dir.join("ext"));
|
||||
roots.push(dir.join("..").join("ext"));
|
||||
roots.push(dir.join("..").join("..").join("ext"));
|
||||
roots.push(dir.join("..").join("..").join("..").join("ext"));
|
||||
// target/debug → repo ext
|
||||
roots.push(dir.join("..").join("..").join("..").join("ext"));
|
||||
}
|
||||
}
|
||||
roots
|
||||
}
|
||||
|
||||
fn find_source_file(name: &str) -> Result<PathBuf> {
|
||||
for root in source_ext_roots() {
|
||||
let p = root.join(name);
|
||||
if p.is_file() {
|
||||
return Ok(p);
|
||||
}
|
||||
}
|
||||
bail!(
|
||||
"cannot find source `{name}` for install (set MARQDO_EXT_SOURCE to an ext/ directory, or run from the Marqdo repo)"
|
||||
);
|
||||
}
|
||||
|
||||
fn find_native_plugin() -> Result<PathBuf> {
|
||||
let name = native_lib_filename();
|
||||
let mut candidates = Vec::new();
|
||||
if let Ok(h) = env::var("MARQDO_EXT_SOURCE") {
|
||||
let base = PathBuf::from(h);
|
||||
candidates.push(base.join("native").join(name));
|
||||
candidates.push(base.join(name));
|
||||
}
|
||||
if let Ok(cwd) = env::current_dir() {
|
||||
candidates.push(cwd.join("target").join("debug").join(name));
|
||||
candidates.push(cwd.join("target").join("release").join(name));
|
||||
candidates.push(cwd.join("ext").join("native").join(name));
|
||||
}
|
||||
if let Ok(exe) = env::current_exe() {
|
||||
if let Some(dir) = exe.parent() {
|
||||
candidates.push(dir.join("ext").join("native").join(name));
|
||||
candidates.push(dir.join(name));
|
||||
// target/debug/deps → target/debug
|
||||
candidates.push(dir.join(name));
|
||||
candidates.push(dir.join("..").join(name));
|
||||
}
|
||||
}
|
||||
for p in candidates {
|
||||
if p.is_file() {
|
||||
return Ok(p);
|
||||
}
|
||||
}
|
||||
bail!(
|
||||
"cannot find native plugin `{name}` (run `cargo build -p marqdo_plugin_agent`, or place it under MARQDO_EXT_SOURCE/native/)"
|
||||
);
|
||||
}
|
||||
|
||||
pub fn add_ext(id: &str) -> Result<()> {
|
||||
let pkg = find_package(id).with_context(|| {
|
||||
format!(
|
||||
"unknown extension `{id}` (official: {})",
|
||||
CATALOG
|
||||
.iter()
|
||||
.map(|p| p.id)
|
||||
.collect::<Vec<_>>()
|
||||
.join(", ")
|
||||
)
|
||||
})?;
|
||||
let root = install_root()?;
|
||||
fs::create_dir_all(&root)
|
||||
.with_context(|| format!("create install root {}", root.display()))?;
|
||||
|
||||
for f in pkg.mq_files {
|
||||
let src = find_source_file(f)?;
|
||||
let dest = root.join(f);
|
||||
fs::copy(&src, &dest)
|
||||
.with_context(|| format!("copy {} → {}", src.display(), dest.display()))?;
|
||||
println!("installed {}", dest.display());
|
||||
}
|
||||
|
||||
if pkg.native_crate.is_some() {
|
||||
let src = find_native_plugin()?;
|
||||
let native_dir = root.join("native");
|
||||
fs::create_dir_all(&native_dir)?;
|
||||
let dest = native_dir.join(native_lib_filename());
|
||||
fs::copy(&src, &dest)
|
||||
.with_context(|| format!("copy {} → {}", src.display(), dest.display()))?;
|
||||
println!("installed {}", dest.display());
|
||||
// Absolute path hint for loaders / env
|
||||
let abs = dest
|
||||
.canonicalize()
|
||||
.unwrap_or_else(|_| dest.clone());
|
||||
let hint = root.join("agent.plugin");
|
||||
fs::write(&hint, abs.to_string_lossy().as_bytes())?;
|
||||
println!("wrote {}", hint.display());
|
||||
println!(
|
||||
"hint: import works via install root; set MARQDO_AGENT_PLUGIN={} if load_native needs it",
|
||||
abs.display()
|
||||
);
|
||||
}
|
||||
|
||||
if env::var_os("MARQDO_EXT").is_none() {
|
||||
println!(
|
||||
"hint: imports resolve via {} automatically; or set MARQDO_EXT to this directory",
|
||||
root.display()
|
||||
);
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
pub fn remove_ext(id: &str) -> Result<()> {
|
||||
let pkg = find_package(id).with_context(|| format!("unknown extension `{id}`"))?;
|
||||
let root = install_root()?;
|
||||
let mut removed = 0usize;
|
||||
for f in pkg.mq_files {
|
||||
let dest = root.join(f);
|
||||
if dest.is_file() {
|
||||
fs::remove_file(&dest)
|
||||
.with_context(|| format!("remove {}", dest.display()))?;
|
||||
println!("removed {}", dest.display());
|
||||
removed += 1;
|
||||
}
|
||||
}
|
||||
if pkg.native_crate.is_some() {
|
||||
let dest = root.join("native").join(native_lib_filename());
|
||||
if dest.is_file() {
|
||||
fs::remove_file(&dest)?;
|
||||
println!("removed {}", dest.display());
|
||||
removed += 1;
|
||||
}
|
||||
let hint = root.join("agent.plugin");
|
||||
if hint.is_file() {
|
||||
fs::remove_file(&hint)?;
|
||||
removed += 1;
|
||||
}
|
||||
}
|
||||
if removed == 0 {
|
||||
println!("nothing to remove for `{id}` under {}", root.display());
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
|
||||
/// Resolve installed native plugin path for `name` (currently only `agent`).
|
||||
pub fn installed_native_path(name: &str) -> Option<PathBuf> {
|
||||
if name != "agent" {
|
||||
return None;
|
||||
}
|
||||
for root in trusted_plugin_roots() {
|
||||
let hint = root.join("agent.plugin");
|
||||
if let Ok(s) = fs::read_to_string(&hint) {
|
||||
let p = PathBuf::from(s.trim());
|
||||
if p.is_file() {
|
||||
return Some(p);
|
||||
}
|
||||
}
|
||||
let p = root.join("native").join(native_lib_filename());
|
||||
if p.is_file() {
|
||||
return Some(p);
|
||||
}
|
||||
}
|
||||
None
|
||||
}
|
||||
|
||||
pub fn path_is_trusted_plugin(path: &Path) -> bool {
|
||||
let path = path.canonicalize().unwrap_or_else(|_| path.to_path_buf());
|
||||
for root in trusted_plugin_roots() {
|
||||
let root = root.canonicalize().unwrap_or(root);
|
||||
if crate::host::path_under_root(&path, &root) {
|
||||
return true;
|
||||
}
|
||||
let native = root.join("native");
|
||||
let native = native.canonicalize().unwrap_or(native);
|
||||
if crate::host::path_under_root(&path, &native) {
|
||||
return true;
|
||||
}
|
||||
}
|
||||
false
|
||||
}
|
||||
@@ -80,6 +80,7 @@ pub enum HostFn {
|
||||
PluginLoad = 69,
|
||||
PluginUnload = 70,
|
||||
PluginList = 71,
|
||||
ExtNativePath = 72,
|
||||
}
|
||||
|
||||
impl HostFn {
|
||||
@@ -156,6 +157,7 @@ impl HostFn {
|
||||
69 => Self::PluginLoad,
|
||||
70 => Self::PluginUnload,
|
||||
71 => Self::PluginList,
|
||||
72 => Self::ExtNativePath,
|
||||
_ => return None,
|
||||
})
|
||||
}
|
||||
@@ -236,6 +238,7 @@ impl HostFn {
|
||||
"host_plugin_load" | "plugin_load" => Self::PluginLoad,
|
||||
"host_plugin_unload" | "plugin_unload" => Self::PluginUnload,
|
||||
"host_plugin_list" | "plugin_list" => Self::PluginList,
|
||||
"host_ext_native_path" | "ext_native_path" => Self::ExtNativePath,
|
||||
_ => return None,
|
||||
})
|
||||
}
|
||||
@@ -317,6 +320,7 @@ impl HostFn {
|
||||
Self::PluginLoad => "host_plugin_load",
|
||||
Self::PluginUnload => "host_plugin_unload",
|
||||
Self::PluginList => "host_plugin_list",
|
||||
Self::ExtNativePath => "host_ext_native_path",
|
||||
}
|
||||
}
|
||||
|
||||
@@ -361,6 +365,7 @@ impl HostFn {
|
||||
Self::ForeignLangs => &[],
|
||||
Self::PluginLoad => &["path"],
|
||||
Self::PluginUnload | Self::PluginList => &[],
|
||||
Self::ExtNativePath => &["name"],
|
||||
}
|
||||
}
|
||||
|
||||
@@ -539,6 +544,17 @@ pub fn call_host(
|
||||
HostFn::PluginLoad => plugin::load(ctx, require(bound, "path")?),
|
||||
HostFn::PluginUnload => plugin::unload(ctx),
|
||||
HostFn::PluginList => plugin::list(ctx),
|
||||
HostFn::ExtNativePath => {
|
||||
let name = require(bound, "name")?;
|
||||
let s = match name {
|
||||
Value::Text(t) => t.as_str(),
|
||||
_ => return Err("name must be text".into()),
|
||||
};
|
||||
Ok(match crate::ext_cli::installed_native_path(s) {
|
||||
Some(p) => Value::Text(p.to_string_lossy().into_owned()),
|
||||
None => Value::None,
|
||||
})
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
+16
-1
@@ -172,7 +172,22 @@ pub fn load(ctx: &mut HostContext, path: &Value) -> Result<Value, String> {
|
||||
return Err("plugin_load denied by host policy".into());
|
||||
}
|
||||
let rel = as_text(path, "path")?;
|
||||
let file = ctx.resolve_path(rel)?;
|
||||
let file = match ctx.resolve_path(rel) {
|
||||
Ok(p) => p,
|
||||
Err(e) => {
|
||||
let p = std::path::Path::new(rel);
|
||||
let abs = if p.is_absolute() {
|
||||
p.to_path_buf()
|
||||
} else {
|
||||
ctx.cwd.join(p)
|
||||
};
|
||||
if abs.is_file() && crate::ext_cli::path_is_trusted_plugin(&abs) {
|
||||
abs
|
||||
} else {
|
||||
return Err(e);
|
||||
}
|
||||
}
|
||||
};
|
||||
if !file.is_file() {
|
||||
return Err(format!("plugin_load: not a file: {}", file.display()));
|
||||
}
|
||||
|
||||
@@ -11,6 +11,7 @@ pub mod capture;
|
||||
pub mod catalog;
|
||||
pub mod debug;
|
||||
pub mod diagnostics;
|
||||
pub mod ext_cli;
|
||||
pub mod foreign;
|
||||
pub mod formula;
|
||||
pub mod host;
|
||||
|
||||
@@ -116,6 +116,8 @@ fn ext_search_roots() -> Vec<PathBuf> {
|
||||
if let Ok(h) = env::var("MARQDO_EXT") {
|
||||
roots.push(PathBuf::from(h));
|
||||
}
|
||||
// Official installer default (`marqdo ext add`)
|
||||
roots.push(crate::ext_cli::default_user_ext_dir());
|
||||
if let Ok(cwd) = env::current_dir() {
|
||||
roots.push(cwd.join("ext"));
|
||||
roots.push(cwd);
|
||||
|
||||
+31
-1
@@ -5,12 +5,13 @@ use anyhow::Result;
|
||||
use clap::{Parser, Subcommand, ValueEnum};
|
||||
|
||||
use marqdo::catalog::{write_catalog, CatalogOptions};
|
||||
use marqdo::ext_cli::{add_ext, list_ext, remove_ext};
|
||||
use marqdo::input_feed::load_stdin_file;
|
||||
use marqdo::view::{serve, serve_debug, write_static, DebugOptions, OutputOptions, ViewOptions};
|
||||
use marqdo::{Backend, RunOptions};
|
||||
|
||||
#[derive(Parser, Debug)]
|
||||
#[command(name = "marqdo", version, about = "Marqdo interpreter — run, view, debug, and catalog .mq.md")]
|
||||
#[command(name = "marqdo", version, about = "Marqdo interpreter — run, view, debug, catalog, and ext")]
|
||||
struct Cli {
|
||||
#[command(subcommand)]
|
||||
command: Commands,
|
||||
@@ -109,6 +110,27 @@ enum Commands {
|
||||
#[arg(short = 'o', long = "out", default_value = ".marqdo")]
|
||||
out: PathBuf,
|
||||
},
|
||||
/// Official extension installer (`list` / `add` / `remove`)
|
||||
Ext {
|
||||
#[command(subcommand)]
|
||||
action: ExtAction,
|
||||
},
|
||||
}
|
||||
|
||||
#[derive(Subcommand, Debug)]
|
||||
enum ExtAction {
|
||||
/// List official extensions and install status
|
||||
List,
|
||||
/// Install an official extension into the local ext root
|
||||
Add {
|
||||
#[arg(value_name = "NAME")]
|
||||
name: String,
|
||||
},
|
||||
/// Remove an installed official extension
|
||||
Remove {
|
||||
#[arg(value_name = "NAME")]
|
||||
name: String,
|
||||
},
|
||||
}
|
||||
|
||||
#[derive(Subcommand, Debug)]
|
||||
@@ -232,5 +254,13 @@ fn try_main() -> Result<i32> {
|
||||
})?;
|
||||
Ok(0)
|
||||
}
|
||||
Commands::Ext { action } => {
|
||||
match action {
|
||||
ExtAction::List => list_ext()?,
|
||||
ExtAction::Add { name } => add_ext(&name)?,
|
||||
ExtAction::Remove { name } => remove_ext(&name)?,
|
||||
}
|
||||
Ok(0)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
---
|
||||
title: ext/agent layout scaffold
|
||||
description: Requires MARQDO_AGENT_PLUGIN (set by gold harness).
|
||||
> ext/agent.mq.md
|
||||
> lib/fs.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load_native
|
||||
|
||||
*`cwd` = > cwd *
|
||||
|
||||
*`ws` = > agent root=`cwd` *
|
||||
|
||||
*`_n` = > `ws`.ensure_layout *
|
||||
|
||||
*`info` = > `ws`.probe *
|
||||
|
||||
*`ok` = > get value=`info` key=has_agents *
|
||||
|
||||
> print text=`ok`
|
||||
|
||||
> write_text path=skel.mq.md text={{name}}
|
||||
|
||||
*`_p` = > `ws`.scaffold name=demo template=skel.mq.md dest=out-demo.mq.md *
|
||||
|
||||
*`body` = > read_text path=out-demo.mq.md *
|
||||
|
||||
> print text=`body`
|
||||
+131
-2
@@ -639,8 +639,137 @@ fn lib_plugin_demo() {
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ext_llm_import() {
|
||||
assert_out("tests/ext/llm-import.mq.md", "ext-ok");
|
||||
fn ext_cli_add_list_remove_llm() {
|
||||
let tmp = tempfile_dir("marqdo-ext-cli");
|
||||
let src = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("ext");
|
||||
assert!(src.join("llm.mq.md").is_file());
|
||||
|
||||
let bin = env!("CARGO_BIN_EXE_marqdo");
|
||||
let status = Command::new(bin)
|
||||
.args(["ext", "add", "llm"])
|
||||
.env("MARQDO_EXT", &tmp)
|
||||
.env("MARQDO_EXT_SOURCE", &src)
|
||||
.env_remove("USERPROFILE")
|
||||
.env_remove("HOME")
|
||||
.status()
|
||||
.expect("ext add");
|
||||
assert!(status.success(), "ext add llm failed");
|
||||
assert!(tmp.join("llm.mq.md").is_file());
|
||||
assert!(tmp.join("大模型.mq.md").is_file());
|
||||
|
||||
let out = Command::new(bin)
|
||||
.args(["ext", "list"])
|
||||
.env("MARQDO_EXT", &tmp)
|
||||
.output()
|
||||
.expect("ext list");
|
||||
assert_eq!(out.status.code().unwrap_or(1), 0);
|
||||
let list = String::from_utf8_lossy(&out.stdout);
|
||||
assert!(list.contains("llm") && list.contains("yes"), "list={list}");
|
||||
|
||||
let mq = tmp.join("smoke.mq.md");
|
||||
std::fs::write(
|
||||
&mq,
|
||||
"---\n> ext/llm.mq.md\n---\n\n# main\n\n> print text=ext-cli-ok\n",
|
||||
)
|
||||
.unwrap();
|
||||
let run = Command::new(bin)
|
||||
.args(["run", mq.to_str().unwrap()])
|
||||
.env("MARQDO_EXT", &tmp)
|
||||
.output()
|
||||
.expect("run smoke");
|
||||
assert_eq!(
|
||||
run.status.code().unwrap_or(1),
|
||||
0,
|
||||
"stderr={}",
|
||||
String::from_utf8_lossy(&run.stderr)
|
||||
);
|
||||
assert_eq!(
|
||||
String::from_utf8_lossy(&run.stdout).trim_end(),
|
||||
"ext-cli-ok"
|
||||
);
|
||||
|
||||
let status = Command::new(bin)
|
||||
.args(["ext", "remove", "llm"])
|
||||
.env("MARQDO_EXT", &tmp)
|
||||
.status()
|
||||
.expect("ext remove");
|
||||
assert!(status.success());
|
||||
assert!(!tmp.join("llm.mq.md").is_file());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ext_cli_add_agent_with_native() {
|
||||
let status = Command::new(env!("CARGO"))
|
||||
.args(["build", "-p", "marqdo_plugin_agent"])
|
||||
.status()
|
||||
.expect("build agent plugin");
|
||||
assert!(status.success());
|
||||
|
||||
let tmp = tempfile_dir("marqdo-ext-agent");
|
||||
let src = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("ext");
|
||||
let bin = env!("CARGO_BIN_EXE_marqdo");
|
||||
let status = Command::new(bin)
|
||||
.args(["ext", "add", "agent"])
|
||||
.env("MARQDO_EXT", &tmp)
|
||||
.env("MARQDO_EXT_SOURCE", &src)
|
||||
.current_dir(env!("CARGO_MANIFEST_DIR"))
|
||||
.status()
|
||||
.expect("ext add agent");
|
||||
assert!(status.success(), "ext add agent failed");
|
||||
assert!(tmp.join("agent.mq.md").is_file());
|
||||
let lib_name = if cfg!(windows) {
|
||||
"agent.dll"
|
||||
} else if cfg!(target_os = "macos") {
|
||||
"libagent.dylib"
|
||||
} else {
|
||||
"libagent.so"
|
||||
};
|
||||
assert!(tmp.join("native").join(lib_name).is_file());
|
||||
assert!(tmp.join("agent.plugin").is_file());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn ext_agent_scaffold() {
|
||||
let status = Command::new(env!("CARGO"))
|
||||
.args(["build", "-p", "marqdo_plugin_agent"])
|
||||
.status()
|
||||
.expect("cargo build plugin agent");
|
||||
assert!(status.success(), "failed to build marqdo_plugin_agent");
|
||||
|
||||
let lib_name = if cfg!(windows) {
|
||||
"agent.dll"
|
||||
} else if cfg!(target_os = "macos") {
|
||||
"libagent.dylib"
|
||||
} else {
|
||||
"libagent.so"
|
||||
};
|
||||
let built = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("target")
|
||||
.join("debug")
|
||||
.join(lib_name);
|
||||
assert!(
|
||||
built.is_file(),
|
||||
"missing plugin artifact {}",
|
||||
built.display()
|
||||
);
|
||||
let ext_dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"))
|
||||
.join("tests")
|
||||
.join("ext");
|
||||
let plugin = ext_dir.join(lib_name);
|
||||
std::fs::copy(&built, &plugin).expect("copy agent plugin into tests/ext");
|
||||
let _ = std::fs::remove_file(ext_dir.join("skel.mq.md"));
|
||||
let _ = std::fs::remove_file(ext_dir.join("out-demo.mq.md"));
|
||||
|
||||
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
|
||||
.args(["run", "tests/ext/agent-scaffold.mq.md"])
|
||||
.env("MARQDO_AGENT_PLUGIN", lib_name)
|
||||
.output()
|
||||
.expect("failed to run marqdo");
|
||||
let code = output.status.code().unwrap_or(1);
|
||||
let stdout = String::from_utf8_lossy(&output.stdout);
|
||||
let stderr = String::from_utf8_lossy(&output.stderr);
|
||||
assert_eq!(code, 0, "agent-scaffold stderr={stderr}");
|
||||
assert_eq!(stdout.trim_end(), "True\ndemo", "agent-scaffold");
|
||||
}
|
||||
|
||||
#[test]
|
||||
|
||||
Reference in new issue
Block a user