diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md index 256638f..079ae57 100644 --- a/.cursor/skills/marqdo/SKILL.md +++ b/.cursor/skills/marqdo/SKILL.md @@ -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). diff --git a/.cursor/skills/marqdo/examples.md b/.cursor/skills/marqdo/examples.md index 0cecf8d..a4cbd17 100644 --- a/.cursor/skills/marqdo/examples.md +++ b/.cursor/skills/marqdo/examples.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 diff --git a/.cursor/skills/marqdo/reference.md b/.cursor/skills/marqdo/reference.md index e4c386d..ae4e74e 100644 --- a/.cursor/skills/marqdo/reference.md +++ b/.cursor/skills/marqdo/reference.md @@ -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 | diff --git a/.gitignore b/.gitignore index 05b9679..abc9a18 100644 --- a/.gitignore +++ b/.gitignore @@ -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/ diff --git a/Cargo.lock b/Cargo.lock index dad60e1..2df4317 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -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" diff --git a/Cargo.toml b/Cargo.toml index 7db5fc8..4bd5089 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -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] diff --git a/README.md b/README.md index 839e83d..f076efc 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/doc/README.md b/doc/README.md index 1180ecf..64c3424 100644 --- a/doc/README.md +++ b/doc/README.md @@ -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` 黑白极简 + 静态文档** | diff --git a/doc/design/ext-abi.md b/doc/design/ext-abi.md index 6dea78f..25ecc4c 100644 --- a/doc/design/ext-abi.md +++ b/doc/design/ext-abi.md @@ -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. \ No newline at end of file diff --git a/doc/design/ext-agent.md b/doc/design/ext-agent.md new file mode 100644 index 0000000..3a3682e --- /dev/null +++ b/doc/design/ext-agent.md @@ -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 diff --git a/doc/design/ext-cli.md b/doc/design/ext-cli.md new file mode 100644 index 0000000..4f79653 --- /dev/null +++ b/doc/design/ext-cli.md @@ -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/`; `## 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/` diff --git a/doc/design/ext-llm.md b/doc/design/ext-llm.md index 88d2201..d10f3a9 100644 --- a/doc/design/ext-llm.md +++ b/doc/design/ext-llm.md @@ -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 diff --git a/doc/design/markdown-mapping.md b/doc/design/markdown-mapping.md index 1607193..e386b8e 100644 --- a/doc/design/markdown-mapping.md +++ b/doc/design/markdown-mapping.md @@ -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)。 --- diff --git a/doc/design/stdlib-foreign.md b/doc/design/stdlib-foreign.md index 152061e..743be92 100644 --- a/doc/design/stdlib-foreign.md +++ b/doc/design/stdlib-foreign.md @@ -2,8 +2,8 @@ | | | |---|---| -| 状态 | **已定(v1)** | -| 日期 | 2026-08-05 | +| 状态 | **已落地(v1)** | +| 日期 | 2026-08-06 | | 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) | --- diff --git a/doc/design/stdlib-modules.md b/doc/design/stdlib-modules.md index d24941e..26eb30c 100644 --- a/doc/design/stdlib-modules.md +++ b/doc/design/stdlib-modules.md @@ -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)。** diff --git a/doc/design/stdlib.md b/doc/design/stdlib.md index e71fa8e..d8bed1d 100644 --- a/doc/design/stdlib.md +++ b/doc/design/stdlib.md @@ -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)。 --- diff --git a/doc/design/user-site.md b/doc/design/user-site.md index ada21fb..7414671 100644 --- a/doc/design/user-site.md +++ b/doc/design/user-site.md @@ -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。 diff --git a/ext/agent.mq.md b/ext/agent.mq.md new file mode 100644 index 0000000..0acf8b8 --- /dev/null +++ b/ext/agent.mq.md @@ -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`** diff --git a/ext/智能体.mq.md b/ext/智能体.mq.md new file mode 100644 index 0000000..ecf11b4 --- /dev/null +++ b/ext/智能体.mq.md @@ -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=`目标`** diff --git a/plugins/agent/Cargo.toml b/plugins/agent/Cargo.toml new file mode 100644 index 0000000..365ee40 --- /dev/null +++ b/plugins/agent/Cargo.toml @@ -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" diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs new file mode 100644 index 0000000..93c768e --- /dev/null +++ b/plugins/agent/src/lib.rs @@ -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 *mut c_void>, + pub free: Option, +} + +static mut HOST_FREE: Option = None; +static mut HOST_ALLOC: Option *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 { + 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 { + 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 { + 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 { + 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 { + 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; +} diff --git a/public/README.md b/public/README.md index e15a655..14c07bd 100644 --- a/public/README.md +++ b/public/README.md @@ -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/`。 diff --git a/public/features/04-objects.mq.md b/public/features/04-objects.mq.md new file mode 100644 index 0000000..c7ed088 --- /dev/null +++ b/public/features/04-objects.mq.md @@ -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 diff --git a/public/features/04-对象.mq.md b/public/features/04-对象.mq.md new file mode 100644 index 0000000..deee1e0 --- /dev/null +++ b/public/features/04-对象.mq.md @@ -0,0 +1,12 @@ +--- +title: 对象与方法 +description: 一级标题是类型;更深标题是函数或方法 +--- + +# main + +Marqdo 中,单个井号(#)定义对象 / 类型构造体;二级及以上(## …)定义自由函数或方法。构造得到带 _type 标记的 map 句柄。方法调用形如:反引号对象、点、方法名。 + +详见 doc/design/objects.md。金样例:tests/structure/object-handle.mq.md。官方 ext/llm 与 ext/agent 使用同一模式。 + +> 打印 内容=对象就绪 diff --git a/public/features/05-extensions.mq.md b/public/features/05-extensions.mq.md new file mode 100644 index 0000000..ffb046c --- /dev/null +++ b/public/features/05-extensions.mq.md @@ -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 diff --git a/public/features/05-扩展.mq.md b/public/features/05-扩展.mq.md new file mode 100644 index 0000000..ab9d759 --- /dev/null +++ b/public/features/05-扩展.mq.md @@ -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 + +> 打印 内容=扩展就绪 diff --git a/public/stdlib/00-overview.mq.md b/public/stdlib/00-overview.mq.md index ae65c47..f370e56 100644 --- a/public/stdlib/00-overview.mq.md +++ b/public/stdlib/00-overview.mq.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. diff --git a/public/stdlib/00-索引.mq.md b/public/stdlib/00-索引.mq.md index fe553b4..8af3b5f 100644 --- a/public/stdlib/00-索引.mq.md +++ b/public/stdlib/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. diff --git a/public/stdlib/json.mq.md b/public/stdlib/json.mq.md index fff8c93..c44abd8 100644 --- a/public/stdlib/json.mq.md +++ b/public/stdlib/json.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={} * diff --git a/public/stdlib/plugin.mq.md b/public/stdlib/plugin.mq.md new file mode 100644 index 0000000..9c0145c --- /dev/null +++ b/public/stdlib/plugin.mq.md @@ -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 diff --git a/public/stdlib/sys.mq.md b/public/stdlib/sys.mq.md index a7f15e6..84c8386 100644 --- a/public/stdlib/sys.mq.md +++ b/public/stdlib/sys.mq.md @@ -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 * diff --git a/public/stdlib/插件.mq.md b/public/stdlib/插件.mq.md new file mode 100644 index 0000000..c18b091 --- /dev/null +++ b/public/stdlib/插件.mq.md @@ -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 + > 打印 内容=插件就绪 ++ * + > 打印 内容=插件异常 diff --git a/public/stdlib/系统.mq.md b/public/stdlib/系统.mq.md index b9c46ba..c9e398e 100644 --- a/public/stdlib/系统.mq.md +++ b/public/stdlib/系统.mq.md @@ -1,12 +1,12 @@ --- title: lib/系统 — 进程 -description: 环境变量、工作目录、参数、退出、执行 +description: 环境变量、dotenv、工作目录、参数、退出、执行 > lib/系统.mq.md --- # main -导入 lib/系统.mq.md。函数:取环境、设环境、参数表、工作目录、退出(码)、执行(命令)。view 下退出会软失败,不结束进程。 +导入 lib/系统.mq.md。函数:取环境、设环境、加载环境(可选路径)、参数表、工作目录、退出(码)、执行(命令)。加载环境不覆盖已有变量。view 下退出会软失败,不结束进程。 *`d` = > 工作目录 * diff --git a/public/stdlib/网络.mq.md b/public/stdlib/网络.mq.md index b9f89f4..63e3fd6 100644 --- a/public/stdlib/网络.mq.md +++ b/public/stdlib/网络.mq.md @@ -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` = > 编码地址 内容=你好 * diff --git a/skills/marqdo/SKILL.md b/skills/marqdo/SKILL.md index 256638f..079ae57 100644 --- a/skills/marqdo/SKILL.md +++ b/skills/marqdo/SKILL.md @@ -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). diff --git a/skills/marqdo/examples.md b/skills/marqdo/examples.md index 0cecf8d..a4cbd17 100644 --- a/skills/marqdo/examples.md +++ b/skills/marqdo/examples.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 diff --git a/skills/marqdo/reference.md b/skills/marqdo/reference.md index e4c386d..ae4e74e 100644 --- a/skills/marqdo/reference.md +++ b/skills/marqdo/reference.md @@ -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 | diff --git a/src/ext_cli.rs b/src/ext_cli.rs new file mode 100644 index 0000000..d0d0392 --- /dev/null +++ b/src/ext_cli.rs @@ -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 { + 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 { + 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 { + 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 { + 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 { + 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 { + 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::>() + .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 { + 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 +} diff --git a/src/host/dispatch.rs b/src/host/dispatch.rs index ab4f448..83c6bd2 100644 --- a/src/host/dispatch.rs +++ b/src/host/dispatch.rs @@ -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, + }) + } } } diff --git a/src/host/plugin.rs b/src/host/plugin.rs index 6f33c33..a4656c6 100644 --- a/src/host/plugin.rs +++ b/src/host/plugin.rs @@ -172,7 +172,22 @@ pub fn load(ctx: &mut HostContext, path: &Value) -> Result { 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())); } diff --git a/src/lib.rs b/src/lib.rs index acf0c08..94e79c2 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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; diff --git a/src/load.rs b/src/load.rs index 397d1da..161f842 100644 --- a/src/load.rs +++ b/src/load.rs @@ -116,6 +116,8 @@ fn ext_search_roots() -> Vec { 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); diff --git a/src/main.rs b/src/main.rs index d56369e..59ef4b5 100644 --- a/src/main.rs +++ b/src/main.rs @@ -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 { })?; 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) + } } } diff --git a/tests/ext/agent-scaffold.mq.md b/tests/ext/agent-scaffold.mq.md new file mode 100644 index 0000000..e0925ac --- /dev/null +++ b/tests/ext/agent-scaffold.mq.md @@ -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` diff --git a/tests/gold.rs b/tests/gold.rs index 95efed6..fbfd8ff 100644 --- a/tests/gold.rs +++ b/tests/gold.rs @@ -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]