From 1f23e2ed9366871fd2356fed89893a53c8863441 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 7 Aug 2026 13:28:32 +0800 Subject: [PATCH] Add module namespaces and harden L1/agent after the import redesign. Bind imports to library names with bare path calls (and use), forward optional host args through mq wrappers, stabilize writeback replacement newlines, and document the M1/M2 decisions. Co-authored-by: Cursor --- .cursor/skills/marqdo/SKILL.md | 19 +- doc/README.md | 3 +- doc/design/bytecode.md | 3 +- doc/design/call-arguments.md | 6 +- doc/design/examples-and-tests.md | 14 +- doc/design/ext-abi.md | 45 ++- doc/design/ext-agent.md | 410 ++++++++++++++++++----- doc/design/ext-cli.md | 17 +- doc/design/ext-llm.md | 8 +- doc/design/markdown-mapping.md | 11 +- doc/design/module-namespace.md | 264 +++++++++++++++ doc/design/stdlib-modules.md | 22 +- doc/design/stdlib-writeback.md | 37 ++- doc/design/stdlib.md | 8 +- doc/roadmap/interpreter.md | 2 +- doc/roadmap/next-phase.md | 2 +- ext/ai/agent.mq.md | 223 ++++++++----- ext/ai/llm.mq.md | 125 +++---- ext/ai/大模型.mq.md | 127 ++++---- ext/ai/智能体.mq.md | 223 ++++++++----- include/marqdo_abi.h | 16 +- lib/foreign.mq.md | 6 +- lib/json.mq.md | 3 +- lib/math.mq.md | 21 +- lib/net.mq.md | 12 +- lib/plugin.mq.md | 7 + lib/sys.mq.md | 6 +- lib/writeback.mq.md | 29 +- lib/外联.mq.md | 6 +- lib/插件.mq.md | 7 + lib/数学.mq.md | 21 +- lib/系统.mq.md | 6 +- lib/网络.mq.md | 12 +- lib/自写回.mq.md | 27 +- man-test/lib/math.mq.md | 6 +- man-test/lib/writeback.mq.md | 5 +- plugins/agent/Cargo.toml | 2 +- plugins/agent/src/lib.rs | 362 ++++++++++++++++++++- public/00-welcome.mq.md | 2 +- public/00-欢迎.mq.md | 2 +- public/stdlib/foreign.mq.md | 2 +- public/stdlib/fs.mq.md | 2 +- public/stdlib/json.mq.md | 4 +- public/stdlib/math.mq.md | 6 +- public/stdlib/net.mq.md | 2 +- public/stdlib/table.mq.md | 4 +- public/stdlib/text.mq.md | 6 +- public/stdlib/time.mq.md | 6 +- public/stdlib/外联.mq.md | 2 +- public/stdlib/数学.mq.md | 6 +- public/stdlib/文本.mq.md | 6 +- public/stdlib/时间.mq.md | 6 +- public/stdlib/网络.mq.md | 2 +- public/stdlib/表.mq.md | 4 +- public/structure/import/main.mq.md | 4 +- public/structure/import/主.mq.md | 4 +- src/aliases.rs | 43 +++ src/ast.rs | 42 ++- src/bytecode/compile.rs | 175 +++++++--- src/catalog.rs | 5 +- src/ext_cli.rs | 45 ++- src/host/agent_rt.rs | 118 +------ src/host/dispatch.rs | 114 +++---- src/host/mod.rs | 13 +- src/host/net.rs | 2 +- src/host/plugin.rs | 110 ++++++- src/host/subtask.rs | 8 +- src/host/sys.rs | 19 +- src/host/writeback.rs | 447 ++++++++++++++++++++++---- src/interp.rs | 109 ++++++- src/load.rs | 156 +++++---- src/parse/expr.rs | 29 +- src/parse/mod.rs | 144 ++++++++- src/view/render.rs | 17 +- tests/errors/ns-instance-method.mq.md | 8 + tests/ext/agent-run-live.mq.md | 56 ++++ tests/ext/agent-smoke.mq.md | 59 +++- tests/ext/llm-complete.mq.md | 8 +- tests/ext/llm-import.mq.md | 2 +- tests/gold.rs | 126 +++++++- tests/lib/foreign-python.mq.md | 2 +- tests/lib/foreign-run-lang.mq.md | 2 +- tests/lib/fs-read.mq.md | 4 +- tests/lib/json-quote.mq.md | 2 +- tests/lib/json-roundtrip.mq.md | 8 +- tests/lib/math-formula-chain.mq.md | 6 +- tests/lib/math-formula.mq.md | 6 +- tests/lib/math-plot.mq.md | 2 +- tests/lib/math-random.mq.md | 10 +- tests/lib/net-encode.mq.md | 2 +- tests/lib/plugin-demo.mq.md | 4 +- tests/lib/subtask-fn.mq.md | 6 +- tests/lib/subtask-foreign.mq.md | 4 +- tests/lib/subtask-spawn.mq.md | 4 +- tests/lib/sys-cwd.mq.md | 2 +- tests/lib/sys-dotenv.mq.md | 6 +- tests/lib/time-format.mq.md | 6 +- tests/lib/writeback-async.mq.md | 37 +++ tests/lib/writeback-get.mq.md | 2 +- tests/lib/外联-python.mq.md | 2 +- tests/lib/数学-数值.mq.md | 4 +- tests/lib/文件-读.mq.md | 4 +- tests/structure/import-lib.mq.md | 6 +- tests/structure/import/main.mq.md | 4 +- tests/structure/ns/helpers.mq.md | 19 ++ tests/structure/ns/path3.mq.md | 14 + tests/structure/ns/use.mq.md | 11 + tests/structure/object-handle.mq.md | 24 +- 108 files changed, 3228 insertions(+), 1023 deletions(-) create mode 100644 doc/design/module-namespace.md create mode 100644 tests/errors/ns-instance-method.mq.md create mode 100644 tests/ext/agent-run-live.mq.md create mode 100644 tests/lib/writeback-async.mq.md create mode 100644 tests/structure/ns/helpers.mq.md create mode 100644 tests/structure/ns/path3.mq.md create mode 100644 tests/structure/ns/use.mq.md diff --git a/.cursor/skills/marqdo/SKILL.md b/.cursor/skills/marqdo/SKILL.md index 8b1f108..a8b9a75 100644 --- a/.cursor/skills/marqdo/SKILL.md +++ b/.cursor/skills/marqdo/SKILL.md @@ -37,7 +37,9 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords. | Line `N. *` | Else arm | | `> fn args` | Call (named `k=v` or positional) | | `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) | -| Frontmatter `> path.mq.md` | Import | +| Frontmatter `> path.mq.md` [`as` / `作为` name] | Import (binds library name) | +| Frontmatter `> use lib.member` [`as` name] / `使用` | Bind short name to a library path | +| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) | | `*…*` | Statement (bind / expr) | | `**…**` | Return value | | `****` or `**` + spaces + `**` | Return `None` and end function body | @@ -109,21 +111,27 @@ Chinese builtins (same functions, no import): ## Frontmatter imports + stdlib +Imports bind a **library name** (default = file stem; optional `as` / `作为`). Members are **not** flattened into the caller. Call with a bare dotted path: + ```markdown --- title: example > lib/text.mq.md +> lib/time.mq.md as clock --- # main -*`xs` = > split value=a,b,c sep=,* +*`xs` = > text.split value=a,b,c sep=,* > print text=`xs` +*`t` = > clock.now_unix * ``` -- Import **English** or **Chinese** library file; call that file’s API names (do not mix). +- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages). +- Instance methods stay `` > `obj`.method `` (backticks on the receiver only). - `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary. -- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm` / `add agent` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — agent framework (layout + ABI; compose LLM per `doc/design/ext-agent.md`). +- Design: [module-namespace.md](../../doc/design/module-namespace.md). +- 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` — document-driven agents: **step** / **multi-step workbook** + writeback ([ext-agent.md](../../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`/`非`. @@ -146,7 +154,8 @@ Stdlib map: [reference.md](reference.md). | `if x > 0:` | `1. `x` > 0` | | `* > print text=hi *` | `> print text=hi` | | Forgetting `---` after nested `##` helper | Add `---` / `***` / `****` | -| Import `lib/text` then call `拆分` | Match file language | +| Import `lib/text` then call bare `split` | `> text.split …` (qualified) | +| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) | ## Checklist before finishing diff --git a/doc/README.md b/doc/README.md index af3b290..1f3c8a1 100644 --- a/doc/README.md +++ b/doc/README.md @@ -26,6 +26,7 @@ | [design/dependencies.md](design/dependencies.md) | 依赖详单(无 Flex/Bison) | | [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置函数** | | [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** | +| [design/module-namespace.md](design/module-namespace.md) | **模块命名空间:导入绑定库名、`库.成员` / `use`(M1+M2 已落地)** | | [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/网络/数学/外联/插件** | @@ -33,7 +34,7 @@ | [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-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(文档驱动:单步 / 多步工作簿 + 自写回;废弃 thin TOOL 循环)** | | [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/ 金样例目录布局** | diff --git a/doc/design/bytecode.md b/doc/design/bytecode.md index 249500f..2ddd86a 100644 --- a/doc/design/bytecode.md +++ b/doc/design/bytecode.md @@ -67,7 +67,8 @@ | `keywords/bool-logic` | ✅ | ✅ | | `structure/nested-call` | ✅ | ✅ | | `structure/positional-call` | ✅ | ✅ | -| `structure/import/*` | ✅ | ✅(load 合并 AST 后编译) | +| `structure/import/*` | ✅ | ✅(导入模块树后编译) | +| `structure/ns/*` | ✅ | ✅ | | `tests/errors/*` | ✅(非零退出) | 同 tree 语义(编译期/运行期诊断) | 核心金样例双后端已对齐;后续可扩展 Op、优化与更好的调试信息。 diff --git a/doc/design/call-arguments.md b/doc/design/call-arguments.md index 7bfe0db..c833c46 100644 --- a/doc/design/call-arguments.md +++ b/doc/design/call-arguments.md @@ -3,8 +3,8 @@ | | | |---|---| | 状态 | 已定(v0.1 增补) | -| 日期 | 2026-08-04 | -| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) | +| 日期 | 2026-08-07 | +| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) | --- @@ -50,4 +50,4 @@ positional ::= value_token ## 4. 金样例 -见 `tests/structure/positional-call.mq.md` 与更新后的 `tests/structure/import/`。 +见 `tests/structure/positional-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。 diff --git a/doc/design/examples-and-tests.md b/doc/design/examples-and-tests.md index 162fdfe..ab56405 100644 --- a/doc/design/examples-and-tests.md +++ b/doc/design/examples-and-tests.md @@ -3,7 +3,7 @@ | | | |---|---| | 状态 | 已定 | -| 日期 | 2026-08-04 | +| 日期 | 2026-08-07 | | 原则 | **夹具即金样例**:`tests/{structure,keywords,errors}/**/*.mq.md` 由 `cargo test` / CI 跑通;`marqdo view tests` 也可浏览 | --- @@ -26,10 +26,17 @@ tests/ import/ main.mq.md utils.mq.md + ns/ + helpers.mq.md + path3.mq.md + use.mq.md keywords/ # 关键字与内置名 print.mq.md bool-logic.mq.md + ext/ + agent-run-live.mq.md errors/ # 期望失败(诊断文案稳定后再加金样例) + ns-instance-method.mq.md … ``` @@ -42,7 +49,7 @@ tests/ | 类别 | 测什么 | 不测什么 | |------|--------|----------| -| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、位置/具名实参 | 关键字边角 | +| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、点号路径 / `use`、位置/具名实参 | 关键字边角 | | **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) | | **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 | @@ -51,7 +58,8 @@ tests/ - **流水线调试**:`--dump-lines` / `--dump-ast` / `--trace-eval` - **CLI**:默认 `index.mq.md`、退出码 - **view**:目录扫描、单文件页、执行区(见 [view.md](view.md)) -- **模块图**:循环导入拒绝 +- **模块图**:循环导入拒绝;`errors/ns-instance-method`(实例方法路径) +- **ext live**:`ext/agent-run-live`(需 `.env` + `libagent`) --- diff --git a/doc/design/ext-abi.md b/doc/design/ext-abi.md index 25ecc4c..8de51e1 100644 --- a/doc/design/ext-abi.md +++ b/doc/design/ext-abi.md @@ -1,9 +1,9 @@ -# Native plugin ABI (v1) +# Native plugin ABI (v2) | | | |---|---| | Status | Accepted | -| Date | 2026-08-06 | +| Date | 2026-08-07 | | Header | [`include/marqdo_abi.h`](../../include/marqdo_abi.h) | | Related | [ext-agent.md](ext-agent.md) · [stdlib-modules.md](stdlib-modules.md) | @@ -13,20 +13,21 @@ - **Not** linked into the `marqdo` binary; load at runtime. - Stable **C** ABI only (no cross-compiler Rust ABI for plugins). - Official / local paths only — **no** third-party package registry. +- **v2**: allowlisted `host_query` so plugins can read entry source / call site / skill without baking agent logic into the core. ## Contract -`MARQDO_ABI_VERSION = 1`. +`MARQDO_ABI_VERSION = 2` (host accepts plugins with version `1..=2`). Every plugin exports: | Symbol | Role | |--------|------| -| `marqdo_plugin_abi_version` | Must equal host’s supported version | +| `marqdo_plugin_abi_version` | `1` or `2` | | `marqdo_plugin_init` | Register functions via `MarqdoHostApi` | | `marqdo_plugin_shutdown` | Teardown | -Host provides `register_fn(name, params_csv, fn)`, `alloc`, `free`. +Host provides `register_fn`, `alloc`, `free`, and (v2) `host_query`. ### Wire format @@ -37,6 +38,16 @@ 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`. +### `host_query` allowlist (v2) + +| name | Result JSON | Notes | +|------|-------------|--------| +| `module_source` | string | Entry `.mq.md` text | +| `call_site` | `{path,function,line}` | Active call site | +| `marqdo_skill` | string | Skill pack text | + +Unknown names fail. Queries are only valid during a plugin function call (host sets thread-local context). + ## Marqdo surface (`lib/plugin` / `lib/插件`) | English | Chinese | Host | @@ -44,6 +55,7 @@ Plugin fn returns `0` + `*out_json` on success; non-zero + optional `*err_msg` o | `## load` (`path`) | `## 加载` (`路径`) | `host_plugin_load` | | `## unload` | `## 卸载` | `host_plugin_unload` | | `## list` | `## 列出` | `host_plugin_list` | +| `## native_path` (`name`) | `## 原生路径` (`名`) | `host_ext_native_path` | ```markdown --- @@ -60,26 +72,29 @@ 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). +**Path sandbox:** `path` resolves under the program’s cwd / `fs_root` (same as `lib/fs`). Absolute paths outside the root are rejected unless trusted (`MARQDO_EXT` / `MARQDO_AGENT_PLUGIN` / built `libagent.*`). Prefer `native_path name=agent` for the official agent plugin. -## Demo +## Demo / agent ```bash cargo build -p marqdo_plugin_demo -# Windows: target/debug/demo.dll -# Linux: target/debug/libdemo.so -# macOS: target/debug/libdemo.dylib +cargo build -p marqdo_plugin_agent ``` -Registers `demo_add(a,b)`, `demo_echo(text)`. Gold: [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md). +- Demo (ABI v1): `demo_add`, `demo_echo` — [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md). +- Agent (ABI v2): layout + session bag + `agent_module_source` / `agent_format_tools` / … — [`plugins/agent`](../../plugins/agent); used by [`ext/ai/agent.mq.md`](../../ext/ai/agent.mq.md). Lookup: `plugin.native_path name=agent` or [ext-cli.md](ext-cli.md) install / `MARQDO_AGENT_PLUGIN`. -Official agent layout plugin: [`plugins/agent`](../../plugins/agent) — see [ext-agent.md](ext-agent.md). +## Layering + +| Layer | May call `host_*` | +|-------|-------------------| +| `lib/*` | Yes (only L1 wrappers) | +| `ext/*` | **No** — compose `lib/*` or ABI plugin names via `lib/plugin` | +| Application `.mq.md` | Same as ext | ## Non-goals - Embedding plugins in the release exe by default - Callbacks from plugin into arbitrary Marqdo evaluation -- OS sandbox / seccomp +- Arbitrary HostFn passthrough via `host_query` - **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 index e4e85b8..82e0c4c 100644 --- a/doc/design/ext-agent.md +++ b/doc/design/ext-agent.md @@ -2,136 +2,372 @@ | | | |---|---| -| Status | Accepted · **thin agent loop locked** | -| Date | 2026-08-06 | -| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [objects.md](objects.md) | +| Status | **Accepted · redesign**(取代「thin TOOL: loop」方案) | +| Date | 2026-08-07 | +| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) | -## What we are building +## 0. 为什么要改掉旧方案 -An **agent-development framework** — smallest runtime surface for agents on Marqdo. +旧版把智能体做成「黑盒对话循环」:隐藏提示拼装、`TOOL:` 协议、host 历史袋、一次(或几次)模型往返。这是对 LangChain 类框架的平移,**背离了 Marqdo 的初衷**。 -**Not** task-dispatch, **not** bundled domain tools, **not** layout/match/ticket helpers in official ext. +Marqdo 的宪法是 **代码即文档、文档即知识库**: -| In scope | Out of scope (your runbook / your code) | -|----------|-------------------------------------------| -| `# 智能体` ctor | `## 技能匹配` · `## 分配任务` · `## 创建工单` … | -| `## 执行` | Anything task-specific in `ext/` | -| `## 清空历史` | | -| Auto context: source, position, history, Marqdo skill | | +| 旧方案的问题 | Marqdo 应有的形态 | +|--------------|-------------------| +| 提示词藏在框架字符串里,与编排源码分离 | 提示、工具、任务、结果都在 `.mq.md` 里,人与模型同读同写 | +| 执行过程是不透明的 chat transcript | 思考与行动写回文档;`view` / `debug` 可跟可审 | +| 复杂任务与简单任务同一套循环 | **单步**与**多步(工作簿)**两级模型 | +| 成功经验留在进程内存 | **自写回**做成果缓存与失败知识;同类任务可复用 | -## Repo layout (`ext/`) +本文件锁定新方向。仓库里现有的 `ext/ai/agent.mq.md` / `智能体.mq.md`(TOOL: 薄循环)视为 **待替换实现**,以本文为准。 -Official extensions for LLM + agent live under **`ext/ai/`** only. No flat `.mq.md` at `ext/` root; future domains get their own subdir. +--- + +## 1. 我们在建什么 + +一个 **文档驱动的智能体开发框架**:编排本身就是可读的 `.mq.md`;模型吃的是这份文档与调用位置;写回让思考过程可控、可调试、可沉淀。 + +**不是** 外挂任务队列、**不是** 官方捆绑领域工具、**不是** 第二套聊天栈(模型 I/O 仍用 `ext/ai/llm`)。 + +| 在范围内 | 在范围外(应用 / runbook) | +|----------|---------------------------| +| `# 智能体` / `# agent` 构造 | 领域工具:`## 查天气`、`## 分配任务` … | +| `## 单步` / `## step` | 业务表格、队列、工单流程 | +| `## 多步` / `## plan`(生成并驱动工作簿) | 具体分解策略模板库(可放用户仓) | +| 上下文:源码、调用位置、工作簿路径、Skill | 第二套 HTTP / 聊天协议 | +| 与 `lib/writeback`、**`lib/subtask`(工具执行通道)**、**`lib/plugin` + ABI v2 `plugins/agent`** 协作 | 把领域技能塞进官方 `ext/ai/`;在 `ext` 内直调 `host_*` | + +--- + +## 2. 核心理念:编排可读,过程可写回 + +1. **提示词与代码不分离** + 站立提示、工具表、任务叙述都写在 `.mq.md` 里。框架把**当前模块源码**与**调用位置**交给模型,而不是另起一套 system prompt 黑盒。 + +2. **把 Marqdo 源码交给智能体** + 每次推理可注入:入口 / 工作簿 `.mq.md` 全文(或相关切片)、`host_call_site`(路径、函数、行)、`skills/marqdo`(写 / 读 `.mq.md` 的语法纪律)。模型输出应优先是 **可解释的决策** 与 **对文档的结构化改动意图**,而不是私有 JSON 协议。 + +3. **自写回 = 思考轨迹 + 成果缓存** + 成功或失败都写回文档(见 [stdlib-writeback.md](stdlib-writeback.md))。成功块可被后续同类任务命中,避免重复失败;失败块成为可读的「避坑记录」。`marqdo view` 在语句下展示 output-card,调试面可对齐同一份真相。 + +4. **相对其他框架的优势** + 无需外挂向量库 / 状态机才能「记住」某次子任务已成功:记忆就是仓库里的 Markdown。审计、合规、复盘 = `git log` + 打开工作簿。 + +--- + +## 3. 两级执行模型 + +### 3.1 模式 A — 单步(原子任务) + +| | | +|---|---| +| **输入** | 小任务描述 + 必要上下文(工具表、站立提示、源码切片) | +| **过程** | 一次(或有限次)推理;可选调用 **runbook 内** 的工具函数;结果写回 | +| **输出** | 原子结果(文本 / 表 / 句柄字段) | +| **适用** | 问答、单一工具、确定性一步 | + +公开方法(中 / 英):`## 单步` / `## step`。 + +示意(语法外形;实现以落地代码为准): + +```markdown +--- +> ext/ai/智能体.mq.md +> ext/ai/大模型.mq.md +> lib/自写回.mq.md +> lib/时间.mq.md +--- + +## 获取时间 + +*`u` = > 时间.此刻秒 * +**> 时间.格式化 秒=`u` 格式=%Y-%m-%d** + +# main + +*`模型` = > 大模型.大模型 * +`工具表` = +| 工具 | +|------| +| 获取时间 | + +*`助手` = > 智能体 大模型=`模型` 工具=`工具表` 站立提示=你是可调试的 Marqdo 助手。 * + +*`结果` = > `助手`.单步 任务=今天日期是什么?请在需要时调用工具。 * +> 打印 内容=`结果` +``` + +单步约定: + +- 模型看到的上下文 **包含本文件源码与调用位置**,因此「有哪些 `##` 工具」对模型是可见的;行动约定写在提示里(人可读),例如单独一行 `CALL:<工具名>` / `调用:<工具名>`,最终答案则直接正文回复。 +- 工具仍是 **runbook 里的 `##` 函数**(v1 以零参为主;可经 `args=` 扩展)。 +- **调用工具走 [`lib/subtask`](stdlib-subtask.md)**:白名单校验通过后 `spawn fn=<名>`(中文面 `启动 函数=`)→ `wait` / `等待`,而不是进程内直接 `call_fn`。这样工具与主推理隔离在子任务语义下,并可与并行、超时、探测同一套主机能力对齐。 +- 结束后用自写回记录:任务摘要、选用工具、结果或错误。 + +### 3.2 模式 B — 多步 / 复杂执行(工作簿) + +| | | +|---|---| +| **输入** | 复杂目标 | +| **过程** | 见下方流水线 | +| **输出** | 汇总结果 + **一份新的 `.mq.md` 工作簿**(完整执行报告) | +| **适用** | 需分解、多工具、可复用子成果的任务 | + +公开方法:`## 多步` / `## plan`(名称可双语并列;中文面以「多步」为准)。 + +流水线: + +1. **创建工作簿** — 在约定目录(默认 `.marqdo/agent-runs/` 或参数指定)生成新的 `.mq.md`:总目标叙述、元信息、子任务表骨架。 +2. **分解** — 主智能体(或 `## 分解`)把目标写成子任务表(可要求人工确认后再跑)。 +3. **子智能体** — 每个子任务实例化一个小的 `# 智能体`(可收窄工具集与站立提示)。 +4. **执行子任务** — 子智能体走 **单步**(默认);仅当子任务仍过复杂且未触达深度上限时,才允许嵌套多步。 +5. **写回** — 成功或失败都写回该子任务区块(含输入签名、时间戳、结果 / 错误)。 +6. **汇总** — 主智能体收集子结果,写回工作簿末尾,返回汇总。 + +**缓存命中**:再次遇到签名相同的子任务时,先 `get` / 扫描工作簿中的写回块;命中且策略允许则 **不再调用模型或工具**。 + +示意(文档级外形): + +```markdown +# main + +*`模型` = > 大模型 * +*`编排` = > 智能体 大模型=`模型` 工具=`工具表` * + +*`报告` = > `编排`.多步 目标=调研并汇总三篇资料的要点 工作簿目录=.marqdo/agent-runs * +> 打印 内容=`报告` +``` + +生成的工作簿(概念形状,非最终模板): + +```markdown +--- +title: agent-run-… +goal: 调研并汇总… +--- + +# 总目标 + +(叙述) + +`子任务` = +| 标识 | 描述 | 状态 | +|------|------|------| +| t1 | … | pending | + +# main + +*`子1` = > 智能体 大模型=`模型` 工具=`窄工具表` 站立提示=只做 t1 * +*`r1` = > `子1`.单步 任务=… * +> 写回 值=`r1` +``` + +--- + +## 4. 分层与仓库布局 ```text ext/ ai/ - llm.mq.md - 大模型.mq.md - agent.mq.md - 智能体.mq.md + llm.mq.md / 大模型.mq.md # 模型 I/O + agent.mq.md / 智能体.mq.md # 本框架(按本文重写) ``` -Import: `> ext/ai/智能体.mq.md` · `> ext/ai/llm.mq.md` +| 层 | 职责 | +|----|------| +| **应用 runbook** | 领域 `##` 工具、任务表、是否人工确认分解 | +| **`ext/ai/agent`** | 单步 / 多步、工作簿生成、子智能体编排、写回约定 | +| **`ext/ai/llm`** | 补全 / 聊天 | +| **`lib/writeback`** | 持久化输出块 | +| **`lib/subtask`** | **工具调用与(多步时)子智能体并行的执行通道**;见 [stdlib-subtask.md](stdlib-subtask.md) | -## Layering +安装:[`ext-cli.md`](ext-cli.md) — `marqdo ext add agent` / `add llm`(`.mq.md` + `native/libagent.so`)。导入:`> ext/ai/智能体.mq.md`。 -| Layer | Role | -|-------|------| -| **Your runbook** | Tables, loops, **your** tools & logic | -| **`ext/ai/llm`** | Model I/O | -| **`ext/ai/agent`** | Framework: ctor + `执行` + `清空历史` | -| **`lib/*`** | Generic I/O | +**原生插件(ABI v2)**:`ext/ai/agent` 经 `lib/plugin` 加载;优先 `> plugin.native_path name=agent`,否则按序查找: -```text -> ext/ai/智能体.mq.md - ▼ -# 智能体 (大模型, 工具, 用户提示信息?) - ## 执行 - ## 清空历史 -``` +1. `MARQDO_AGENT_PLUGIN`(显式 `.so` / `.dylib` 路径) +2. `CARGO_TARGET_DIR/{debug,release}/libagent.so`(或 `.dylib`) +3. cwd `target/{debug,release}/` +4. 可执行文件旁 `libagent.*` 或 `target/debug/` +5. `MARQDO_EXT/native/libagent.*`(`marqdo ext add agent` 安装) -`工具` = caller-supplied **function catalog** (table of `##` names); framework resolves names via `call_fn` / `调用` and runs the matching zero-arg function in the runbook module. +本地开发须先 `cargo build -p marqdo_plugin_agent`(或 `ext add agent` / 设 `MARQDO_AGENT_PLUGIN`)。详见 [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md)。 -Install: [`ext-cli.md`](ext-cli.md) — `marqdo ext add agent` / `add llm`. +**分层纪律**:`ext/*` **禁止** `host_*`;用 `lib/*` 包装或插件注册名。进程退出用 `sys.exit` / `系统.退出`,不用裸 `exit`。 -### Tools (v1) +--- -Tools are **not** framework builtins — you define `## 函数名` in your runbook and list names in a table: +## 5. 公开 API(目标契约) + +| 中文 | 英文 | 角色 | +|------|------|------| +| `# 智能体` | `# agent` | 构造:`大模型`/`model`,`工具`/`tools`,可选 `站立提示`/`standing` | +| `## 单步` | `## step` | 原子执行;注入源码 + 位置;可选工具;**返回结构化 map**(不内置写回) | +| `## 多步` | `## plan` | 建工作簿 → 分解 → 子智能体 → 写回 → 汇总 | +| `## 分解` | `## decompose` |(可公开或内部)目标 → 子任务表 | +| `## 清空历史` | `## clear_history` | 若仍保留会话式辅助状态则清空;**不以隐藏 chat 袋为真相源**——真相在文档写回 | + +构造参数(v1): + +| 参数 | 说明 | +|------|------| +| `大模型` / `model` | `ext/ai/llm` 句柄 | +| `工具` / `tools` | 工具名表(单列文本,或多列且含 `工具`/`tools`/`name`) | +| `站立提示` / `standing` | 写在文档里的常驻说明(可空) | + +`## 单步` 参数:`任务` / `task`;可选深度、是否强制不用缓存等。 +`## 多步` 参数:`目标` / `goal`;可选 `工作簿目录`、`最大深度`、`是否确认分解`。 + +模块内辅助函数(组装上下文、解析模型回复、匹配写回缓存)**不是**稳定对外契约,可随实现调整。 + +--- + +## 6. 工具表与子任务调用 + +工具 **不是** 框架内置能力。在 runbook 定义 `##`,再用表登记名称: ```markdown `工具表` = | 工具 | |------| | 获取时间 | -| 分配任务 | +| 读取摘要 | ``` -- Single-column table → list of function **names** (text). -- Multi-column table → each row is a map; name from column `工具` / `tools` / `name`. -- Marqdo has no first-class function values in tables yet; the name must match a `##` in the same module (or imports). `执行` calls it with `call_fn` after the model replies `TOOL:`. -- Do **not** use `parse text=["fn"]` for the tools list — unquoted identifiers inside `parse` are evaluated as calls. +- 单列表 → 名称列表。 +- 多列表 → 从列 `工具` / `tools` / `name` 取名。 +- 名称须对应当前模块(或导入可见)的 `##`。 +- **不要** 用 `parse text=["fn"]` 列工具(未加引号的标识符会被当成调用)。 + +### 6.1 调用路径(锁定) + +```text +模型回复含 CALL:<名> / 调用:<名> + ▼ +host_tool_allowed(工具表白名单) + ▼ +lib/subtask:spawn fn=<名> → wait + ▼ +工具返回值写回上下文 / 自写回 +``` + +| | | +|---|---| +| 英文面 | `> spawn fn=`名`` → `> wait id=`…`` | +| 中文面 | `> 启动 函数=`名`` → `> 等待 id=`…`` | +| 可选 | `args=` / `参数=` 传给带形参的工具;多工具并行时多次 `spawn` 再 `wait_all` / `等待全部` | + +**非目标:** 以裸 `call_fn` 作为框架默认工具通道(应用仍可直接 `call_fn`,但官方智能体走子任务库)。 + +领域逻辑永远留在应用文件,不进官方 `ext/ai/`。 --- -## Public API (v1) +## 7. 上下文注入(每次单步 / 子步) -| | Role | -|--|------| -| `# 智能体` / `# agent` | **大模型**, **工具**, optional **用户提示信息** | -| `## 执行` / `## run` | **额外信息**; context + LLM + history append | -| `## 清空历史` / `## clear_history` | Wipe history on this handle | +必须可注入(实现可切片,但不得默默丢掉「代码即文档」): -Module-level `##` helpers (e.g. context assembly) are internal — not public contract. +| 片段 | 来源 | +|------|------| +| 站立提示 | 构造参数 / 文档正文 | +| 任务 / 目标 | 方法实参 | +| 工具表(人可读) | 构造参数 | +| **当前 `.mq.md` 源码** | 插件 `agent_module_source`(经 ABI v2 `host_query`) | +| **调用位置** | 插件 `agent_call_site` | +| **Marqdo skill** | 插件 `agent_marqdo_skill` | +| Marqdo Skill | `skills/marqdo/`(`MARQDO_SKILL` 可覆盖) | +| 相关写回块 | `lib/writeback` 的 `get` / `list` | -### Auto context (each `执行`) - -- `.mq.md` source -- Call-site / position -- Conversation history on this handle -- Marqdo skill (`skills/marqdo/`) - -### History (v1) - -- Host-backed id per handle -- Append after each successful `执行` -- `清空历史` ships with `执行` +禁止:把整份 Skill + 全文源码藏进不可审查的二进制提示且不在文档中留迹。框架拼装的提示应能在调试时落盘或写回(至少摘要)。 --- -## Example runbook (application — not framework) +## 8. 自写回与缓存语义 + +依赖 [stdlib-writeback.md](stdlib-writeback.md):`record` / `写回` → ``。 + +### 8.1 单步返回值(不内置写回) + +`单步` / `step` **不再自动写盘**。它返回一张结构化 map,由编排方决定是否、如何写回: + +| 字段 | 何时 | 含义 | +|------|------|------| +| `status` | 总是 | `ok` / `error` | +| `task` | 总是 | 本步任务 | +| `decision` | 总是 | 模型首轮输出(含 CALL 行等) | +| `tool` / `tool_result` | 成功且调了工具 | 工具名与子任务返回 | +| `result` | 成功 | 最终答复 | +| `error` | 失败 | 错误信息 | ```markdown ---- -> ext/ai/智能体.mq.md -> ext/ai/大模型.mq.md ---- - -# main - -*`模型` = > 大模型 * -*`工具名` = | 技能匹配 | 分配任务 | … | -*`助手` = > 智能体 大模型=`模型` 工具=`工具名` 用户提示信息=… * - -- [任务](任务队列) - > `助手`.清空历史 - *`结果` = > `助手`.执行 额外信息=`任务` * +*`out` = > `助手`.step task=… * +*`回复` = > json.get value=`out` key=result * +*`status` = > json.get value=`out` key=status * +*`body` = > json.stringify value=`out` * +1. `status` == ok + > writeback.record value=`body` key=ok +2. * + > writeback.record value=`body` key=error ``` -Domain `##` functions live in **this file** or your lib — never in `ext/ai/`. +命名槽 `ok` / `error` 仍建议互不覆盖;锚点由调用方的 `写回`/`record` 决定。 + +**命中规则(后续缓存)**:读 `key=ok` 且非占位时可复用。失败知识读 `key=error`。 +用户可 `clear key=ok` / `clear key=error` 强制重跑。 + +复杂执行中,写回优先落在 **工作簿** 文件。 + +### 8.2 Live 金样例 + +[`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md):`agent.step` + 子任务工具 + `writeback.record`(`key=ok` / `error`)。凭证:`tests/ext/.env`;`> llm.load_env path=.env` 相对**源文件目录**(`marqdo run` 将 cwd 设为该文件所在目录)。需已构建 agent 原生库(见 §4)。 --- -## Shipped / roadmap +## 9. 安全与边界 -| Item | Status | -|------|--------| -| `ext/ai/` + framework + context injection | in progress | -| Live `执行` test (`tests/ext/agent-run-live.mq.md` + `.env`) | shipped | -| Tool-call loop in `执行` (`TOOL:` → `call_fn`) | shipped | +| 风险 | 对策 | +|------|------| +| 无限多步递归 | `最大深度`(默认小,如 2);叶任务强制单步 | +| 工具越权 | 仅工具表白名单;子智能体可传更窄的表 | +| 工作簿爆炸 | 统一目录、命名含时间 / id;可选总超时 | +| 缓存过期 | 签名 + 时间戳;手动清块 | +| 模型乱改仓库 | 写回 API 约束写入形态;多步生成文件限于工作簿目录 | -### Non-goals +--- -- Domain tools in official ext -- Flat `ext/*.mq.md` at repo root -- Second chat stack beside llm +## 10. 相对旧 API 的迁移 + +| 旧(废弃方向) | 新 | +|----------------|----| +| 唯一的 `## 执行` / `## run` + 隐藏 TOOL: 循环 | `## 单步` / `## 多步` | +| host 历史袋为真相 | 文档写回 + 工作簿为真相;历史袋至多辅助 | +| 提示全在框架字符串 | 站立提示与任务在 `.mq.md`;源码注入 | +| `tests/ext/agent-smoke` 测 TOOL 上下文拼接 | 重写为单步离线 / 写回 / 工作簿骨架测试 | + +兼容:可短期保留 `## 执行` 作为 `## 单步` 的别名,但文档与金样例迁到新名后删除别名。 + +--- + +## 11. 实现路线(文档锁定后) + +| 阶段 | 内容 | 状态 | +|------|------|------| +| D0 | 本文 Accepted;废弃 thin TOOL 设计叙述 | **本文件** | +| D1 | 重写 `ext/ai/agent.mq.md` / `智能体.mq.md`:`单步` + 源码/位置注入 + **子任务调工具** + **结构化返回值**;运行时经 **ABI v2 agent 插件**(禁 ext 直调 host) | **done** | +| D2 | `多步`:工作簿模板、分解、子智能体(亦可 `spawn`)、缓存命中 | TODO | +| D3 | 金样例:离线单步 / 写回;**live 单步**(`tests/ext/agent-run-live.mq.md`);多步骨架(可不打网) | **live done** | +| D4 | `view` / `debug` 对工作簿与写回块的导航体验 | TODO | + +### 非目标 + +- 在官方 `ext/ai/` 捆绑领域工具或工单技能 +- 在 `ext/` 根目录摊平 `.mq.md` +- 平行再造一套 LLM HTTP 栈 +- 以不可读的私有二进制协议作为编排主界面 + +--- + +## 12. 一句话 + +**智能体框架必须让编排看起来像文档、跑起来像程序、留痕像知识库。** +单步解决原子问题;多步生成工作簿、拆分子智能体、用自写回记住成功与失败——这才是 Marqdo 相对其它智能体框架的优越性所在。 diff --git a/doc/design/ext-cli.md b/doc/design/ext-cli.md index a953eb7..914877f 100644 --- a/doc/design/ext-cli.md +++ b/doc/design/ext-cli.md @@ -3,8 +3,8 @@ | | | |---|---| | Status | **Accepted (v0.1)** | -| Date | 2026-08-06 | -| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) | +| Date | 2026-08-07 | +| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) | ## Commands @@ -48,11 +48,20 @@ Future optional ext domains get their own subdirs (e.g. `ext/foo/`), not mixed i | Id | Installs under `MARQDO_EXT` | |----|-----------------------------| | `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` | -| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md` | +| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **`native/libagent.so`** (or `.dylib`) | + +`add agent` copies the built native plugin into `MARQDO_EXT/native/`. Build it first: + +```bash +cargo build -p marqdo_plugin_agent +marqdo ext add agent +``` + +Without install, runtime resolves the plugin via `plugin.native_path name=agent` (see [ext-abi.md](ext-abi.md)): `MARQDO_AGENT_PLUGIN` → `CARGO_TARGET_DIR/{debug,release}/` → cwd `target/…` → beside `marqdo` binary → `MARQDO_EXT/native/`. ## Tests -`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` (needs `tests/ext/.env`). +`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` ([`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md); needs `tests/ext/.env` + built `libagent`). ## Non-goals diff --git a/doc/design/ext-llm.md b/doc/design/ext-llm.md index 8989e03..01e09d0 100644 --- a/doc/design/ext-llm.md +++ b/doc/design/ext-llm.md @@ -18,7 +18,7 @@ Resolution: `MARQDO_EXT/ai/…`, repo `ext/ai/…`, cwd `ext/ai/…` (see [ext-cli.md](ext-cli.md)). -Other official ext: [ext-agent.md](ext-agent.md) (**agent development framework** — layout shipped; orchestration + LLM composition on roadmap). Installer CLI (planned): [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md). +Other official ext: [ext-agent.md](ext-agent.md) (**document-driven agent** — step / multi-step workbook + writeback; thin `TOOL:` loop superseded). Installer: [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md). **Note:** Prefer `marqdo ext add llm`. Import `> ext/ai/llm.mq.md` from repo or install root. @@ -66,5 +66,7 @@ Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`. - Import smoke: `tests/ext/llm-import.mq.md` - Live complete (local): `tests/ext/llm-complete.mq.md` + `tests/ext/.env` -- Live agent `执行`: `tests/ext/agent-run-live.mq.md` + same `.env` (gold: `ext_agent_run_live`, skips if missing) -- Offline agent smoke: `tests/ext/agent-smoke.mq.md` (gold: `ext_agent_framework_smoke`) +- Live agent `## step`: `tests/ext/agent-run-live.mq.md` (DeepSeek; gold: `ext_agent_run_live`) +- Agent smoke (real `llm` handle): `tests/ext/agent-smoke.mq.md` (gold: `ext_agent_framework_smoke`) +- Live complete: `tests/ext/llm-complete.mq.md` (gold: `ext_llm_complete_live`) + diff --git a/doc/design/markdown-mapping.md b/doc/design/markdown-mapping.md index cb464d3..483bcbe 100644 --- a/doc/design/markdown-mapping.md +++ b/doc/design/markdown-mapping.md @@ -3,9 +3,9 @@ | | | |---|---| | 状态 | 已定论(修订:形参 `+`、分支 `1.`、标识符反引号、`-` 专用于循环) | -| 日期 | 2026-08-06 | +| 日期 | 2026-08-07 | | 取代 | v0.1 中「函数头 `-` 形参 / 裸名形参与遍历变量 / `+` 分支」 | -| 相关 | [objects.md](objects.md) · [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) | +| 相关 | [objects.md](objects.md) · [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) · [module-namespace.md](module-namespace.md) | Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。 @@ -47,7 +47,9 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置 | 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` | | `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) | | `` > `对象`.方法 … `` | 方法调用(实例 map 须含 `_type`) | -| frontmatter `> path.mq.md` | 跨文件导入 | +| frontmatter `> path.mq.md` [`as` / `作为` name] | 导入(绑定库名;默认 = 文件名茎) | +| frontmatter `> use lib.member` [`as` name] / `使用` | 将库路径成员绑为本地短名 | +| `> lib.member …` / `> lib.Type.member …` | 点号路径调用(路径段裸名、无反引号) | | `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) | | `**…**` | **返回值**(架构级;函数结果) | | `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 | @@ -118,7 +120,8 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置 ## 5. Frontmatter 与跨文件 -同 v0:文件头 `---` 对为元信息;其中 `> file.mq.md` 为导入。 +文件头 `---` 对为元信息。其中 `> file.mq.md` 为**导入**(绑定库名,成员不倒进全局);`> use lib.member` / `> 使用 库.成员` 引入本地短名。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法须 `` > `var`.method ``。详见 [module-namespace.md](module-namespace.md)。 + **函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。 --- diff --git a/doc/design/module-namespace.md b/doc/design/module-namespace.md new file mode 100644 index 0000000..6f8b3d6 --- /dev/null +++ b/doc/design/module-namespace.md @@ -0,0 +1,264 @@ +# 模块命名空间(import / 点号寻址) + +| | | +|---|---| +| 状态 | **Accepted;M1+M2 已落地** | +| 日期 | 2026-08-07 | +| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [ext-agent.md](ext-agent.md) | + +--- + +## 1. 动机 + +今日加载器把每个导入文件的顶层 `#` / `##` **扁平合并**进同一全局函数表;同名则**后导入静默覆盖**(`merge_top_level`)。 + +后果: + +- `lib/json` 的 `parse` 与 `lib/time` 的 `parse` 不能共存;import 顺序决定谁赢,错误表现为「缺 `pattern`」这类误导信息。 +- `lib/writeback` 的 `get` 盖住 `lib/json` 的 `get`。 +- 官方 ext / 多库编排无法按大型语言习惯书写 `time.parse` / `json.parse`。 + +**结论**:Marqdo 必须支持**模块命名空间**与**点号寻址**。扁平静默覆盖不是可保留的「兼容糖」,而是会**掩盖冲突**的缺陷行为;本设计予以废除(落地时为破坏性变更,不设双轨裸名回退)。 + +--- + +## 2. 目标与非目标 + +### 2.1 目标 + +1. **导入绑定库名**:导入一个 `.mq.md` 得到一个**库(模块)绑定**,成员不倒进全局。 +2. **点号寻址调用**:`库.成员`、并预留 `库.对象.成员` 等多段路径;`.` 表示在定义树上的寻址,不是字段运算。 +3. **库名不是变量**:寻址段为**裸标识符**,**不加**反引号。反引号只用于值槽位(变量 / 形参 / 实例句柄)。 +4. **模块内名字默认不进全局**;需要本地短名时必须**显式** `use`,且冲突**报错**。 +5. **中英对等**:路径中英分文件;`as` / `作为` 与默认库名规则双语一致。 + +### 2.2 非目标 + +- 第三方包管理 / 版本求解。 +- 在兼容期内继续支持扁平合并旧语义。 +- 「裸名仍可从最后一次导入解析」——**明确拒绝**。 +- 把库名写成 `` `time`.parse ``——**明确拒绝**(会把库名误当成变量)。 + +--- + +## 3. 核心语义 + +### 3.1 模块 / 库 + +每个可导入的 `.mq.md` 文件是一个**库模块**: + +| 内容 | 归属 | +|------|------| +| 顶层 `##` 自由函数 | 库根下的**函数** | +| 顶层 `#` 对象 | 库根下的**类型(对象)** | +| 类型下的 `##` 方法 | 该对象节点下的**成员函数**(可被路径寻址;实例调用见 §4.4) | +| 被导入文件的 `# main` | **不**作为入口执行 | + +### 3.2 导入句法(frontmatter) + +| 英文 | 中文 | 含义 | +|------|------|------| +| `> lib/time.mq.md` | `> lib/时间.mq.md` | 导入;默认库名见 §3.3 | +| `> lib/time.mq.md as time` | `> lib/时间.mq.md 作为 时间` | 导入并以给定库名绑定 | + +规则: + +- `as` / `作为` 后为**裸库名**(不加反引号)。 +- 同一文件内两个导入不得绑定同一库名 → 硬错误。 +- 禁止「只写路径、成员洒进全局」的旧语义。 + +### 3.3 默认库名 + +省略 `as` / `作为` 时,库名 = **文件名茎**(去掉 `.mq.md`): + +| 路径 | 默认库名 | +|------|----------| +| `lib/time.mq.md` | `time` | +| `lib/时间.mq.md` | `时间` | +| `ext/ai/agent.mq.md` | `agent` | +| `ext/ai/智能体.mq.md` | `智能体` | + +### 3.4 调用解析顺序 + +1. **点号路径 callee**(§4)→ 按段在导入库 / 类型树上寻址。 +2. **当前文件**顶层 `#` / `##`(无点号的短名)。 +3. **L0 内置**。 +4. **插件注册名**(`lib/plugin` 加载后的全局表)。 +5. 否则 → 未知 callee。 + +--- + +## 4. 点号寻址(核心外形) + +### 4.1 文法 + +```text +path_callee ::= ident ('.' ident)+ +``` + +- 每一段都是**裸标识符**(库名、类型名、函数名)。 +- **整条路径都不使用反引号**。 +- `.` 只表示寻址分隔,与「变量上的方法调用」分流(§4.4)。 + +### 4.2 二段:`库.成员` + +```markdown +--- +> lib/time.mq.md +> lib/json.mq.md +--- + +# main + +*`t` = > time.now_unix * +*`s` = > time.format unix=`t` pattern=%Y-%m-%d * +*`obj` = > json.parse text={"a":1} * +*`a` = > json.get value=`obj` key=a * +> print text=`s` +``` + +| 路径 | 解析 | +|------|------| +| `time.now_unix` | 库 `time` → 函数 `now_unix` | +| `json.parse` | 库 `json` → 函数 `parse` | +| `agent.agent` | 库 `agent` → **类型** `agent`(构造) | + +库根下的函数调用**不**注入 `self` / `自`。 + +### 4.3 三段及以上:`库.对象.成员`(预留并锁定语义) + +后续常见形态: + +```markdown +> agent.agent # 库 → 类型:构造 +> 某库.某对象.某函数 # 库 → 类型 → 该类型下的 ## 成员 +``` + +解析规则(锁定): + +1. 第一段必须是**已导入库名**。 +2. 第二段起在上一段节点的子表中查找:类型节点或函数节点。 +3. 若最终落在**函数**上则发起调用;若落在**类型**上则发起构造。 +4. 路径中任一段缺失 → 硬错误(禁止模糊回落到全局短名)。 + +实例方法若需要接收者,仍走 §4.4;`库.对象.方法` 表示定义树上的该成员(无接收者时:仅当该成员可作为无 `self` 的关联函数调用,否则报错「需要实例」)。这样 `.` 始终是**定义寻址**,逻辑一致。 + +中文库同理:`时间.格式化`、`智能体.智能体`、`智能体.智能体.单步`(若对类型成员做路径调用)。 + +### 4.4 变量 / 实例 vs 库路径(反引号分界) + +| 写法 | 左侧重 | 是否反引号 | +|------|--------|------------| +| `time.parse` | 库名(绑定) | 路径段皆**裸名** | +| `agent.agent` | 库名.类型名 | 裸名 | +| `` > `助手`.step `` | **变量**(实例句柄) | 接收者**必须**反引号 | +| `` > `out`.… `` | 变量 | 反引号 | + +原则: + +- **名在定义/导入空间里** → 点号路径,无 `` ` ` ``。 +- **名在值环境里**(绑定结果、形参、`self`)→ 反引号标识符;方法调用保持现有 `` > `obj`.method ``。 + +禁止混写 `` > `time`.parse ``(把库当成变量)。 + +### 4.5 应用侧完整示例 + +```markdown +--- +> lib/time.mq.md +> lib/writeback.mq.md +> ext/ai/agent.mq.md +--- + +# main + +*`助手` = > agent.agent model=… tools=… * +*`out` = > `助手`.step task=… * +*`body` = > json.stringify value=`out` * +> writeback.record value=`body` key=ok +``` + +(上例假定 `json` 已导入;`stringify` 为该库成员。) + +--- + +## 5. 导出面 + +默认:库内顶层 `#` / `##` 均可被路径访问。 + +类型下的 `##` 挂在该类型节点下,供 `库.类型.成员` 寻址;实例调用仍用 `` `变量`.成员 ``。 + +本版不引入 `private`。 + +--- + +## 6. 显式 `use`(可选短名,非静默兼容) + +| 英文 | 中文 | +|------|------| +| `> use time.format` | `> 使用 时间.格式化` | +| `> use time.format as fmt` | `> 使用 时间.格式化 作为 fmt` | + +- `use` 右侧为**点号路径**(裸名寻址)。 +- 引入后本地短名可见;与导入库名或当前文件顶层同名 → **硬错误**。 +- **禁止** `use time.*`(无通配 `use`)。 + +--- + +## 7. 与旧行为的关系(破坏性变更) + +| 旧 | 新 | +|----|----| +| 导入 = 合并进全局 | 导入 = 绑定库名 | +| 同名后写覆盖 | 无跨库扁平同名 | +| `> parse` 来源不明 | 必须 `json.parse` 或显式 `use` | +| (若曾设想)`` `time`.parse `` | **否**;库路径不加反引号 | + +不提供扁平合并过渡开关。 + +--- + +## 8. 对分层与 ext 的影响 + +| 层 | 影响 | +|----|------| +| L0 内置 | 仍为全局短名 | +| L1 / 官方 ext | 经库路径调用;`ext` 仍禁 `host_*` | +| ABI 插件 | 仍为插件注册表;不强制并入点号树 v1 | + +--- + +## 9. 实现要点 + +1. 加载返回模块树(库 → 类型 → 成员);取消跨文件 `merge_top_level` 泼洒。 +2. 调用方解析 `path_callee`:按 `.` 分段,自导入表下行。 +3. 区分路径 callee 与 `` `变量`.方法 ``(词法:首段是否反引号 / 是否含裸点号路径)。 +4. 金样例与 stdlib 文档改为 `time.parse` 形态。 + +| 阶段 | 内容 | +|------|------| +| M0 | 本文 Accepted(含本修订) | +| M1 | 二段路径 `库.成员` + 破坏旧扁平 — **已落地**(tree + bytecode;`as`/`作为`;stdlib/ext/tests 已迁) | +| M2 | 三段 `库.对象.成员`;`use` / `使用` — **已落地**(实例方法路径调用报错,须 `` `var`.method ``) | +| M3 | 诊断工具(可选) | + +**双后端**:tree 与 bytecode 均支持点号路径调用与 `use` / `使用`(与 M1/M2 同语义)。 + +**金样例**: + +| 路径 | 测什么 | +|------|--------| +| `tests/structure/ns/` | 二段/三段路径、`use`、导入 `as` | +| `tests/errors/ns-instance-method.mq.md` | `库.类型.方法` 无接收者 → 硬错误(须 `` `var`.method ``) | + +**L1 薄包装**:命名空间下 `net.http_post` 等解析到 **`lib/*.mq.md` 的 `##` 包装**,不是宿主别名。包装未声明的可选形参会被静默丢弃(曾导致 live agent 401:`headers` 未传到 `host_http_post`)。规则见 [stdlib-modules.md](stdlib-modules.md) §2.1。 + +--- + +## 10. 决议摘要 + +1. 导入绑定**库名**;成员不进全局。 +2. 调用以**裸名点号路径**寻址:`库.成员`,并支持 `库.对象.成员`;`.` = 定义树寻址。 +3. **库名 / 路径段不加反引号**;反引号只用于值变量与实例接收者。 +4. 拒绝扁平合并与裸名双轨兼容;短名仅显式单成员 `use`。 +5. M1/M2 已实现;M3 另开。 diff --git a/doc/design/stdlib-modules.md b/doc/design/stdlib-modules.md index 8e85b2d..0df5967 100644 --- a/doc/design/stdlib-modules.md +++ b/doc/design/stdlib-modules.md @@ -3,9 +3,9 @@ | | | |---|---| | 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin** | -| 日期 | 2026-08-06 | +| 日期 | 2026-08-07 | | 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 | -| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) | +| 相关 | [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) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) | --- @@ -52,9 +52,23 @@ OS / HTTP / 时钟 / 共享库 … | 层 | 谁实现 | 用户是否直接调用 | |----|--------|------------------| | **L0** | 解释器内置 | 是(`print`/`len`/…) | -| **L0.5 宿主原语** | Rust(`src/host/`) | **原则上否**;供 L1 包装 | +| **L0.5 宿主原语** | Rust(`src/host/`) | **原则上否**;供 L1 包装;ABI v2 `host_query` 仅插件可调 | | **L1 官方库** | `lib/*.mq.md` | **是** | -| **官方 ext** | `ext/*.mq.md`(+ 可选 ABI 插件) | **是**(需显式导入 `ext/`) | +| **官方 ext** | `ext/*.mq.md`(+ 可选 ABI 插件) | **是**(需显式导入 `ext/`);**禁止** `host_*`,经 `lib/*` 或插件注册名 | + +> **已变更(M1+M2)**:[module-namespace.md](module-namespace.md) — 取消跨文件扁平合并;L1/ext 经**裸名点号路径**调用(`time.parse`、`agent.agent`;M2:`库.对象.成员` + `use`),库名不加反引号;实例方法须 `` `var`.method ``;不再靠 import 顺序覆盖同名。 + +### 2.1 L1 薄包装 → 宿主(命名空间后必读) + +点号路径 `net.http_post` / `json.stringify` 等解析到 **`lib/*.mq.md` 的 `##` 函数**,再转发 `host_*`。未在包装形参表声明的可选实参会被**静默丢弃**(曾导致 live agent 401:`Authorization` 等 `headers` 从未到达宿主)。 + +| 规则 | 说明 | +|------|------| +| 每个 `host_*` 包装 | 须在 `+` 形参表声明**全部**宿主可选参数,默认 `None`,并在 `**> host_…**` 中**原样转发** | +| `http_post` / `提交` | `content_type=None` 时宿主按默认 JSON charset 处理 | +| 已对齐(2026-08-07) | `net`/`网络`(headers、content_type、body)、`sys`/`系统`(load_dotenv、exec)、`ext/ai/llm`(load_env / 加载环境 path)、`json.stringify` indent、`foreign`/`外联` stdin、`math`/`数学` plot*/solve 可选项 | + +**无**扁平合并回退;**无**裸名双轨兼容。 --- diff --git a/doc/design/stdlib-writeback.md b/doc/design/stdlib-writeback.md index f55e0b0..3507300 100644 --- a/doc/design/stdlib-writeback.md +++ b/doc/design/stdlib-writeback.md @@ -3,6 +3,7 @@ | | | |---|---| | 状态 | v1 已落地 | +| 日期 | 2026-08-07 | | 库 | `lib/writeback.mq.md` · `lib/自写回.mq.md` | ## 定位 @@ -18,19 +19,39 @@ --> ``` -- 注释内仅保留 `marqdo-out` 标识,**不存行号**(避免写回后行号漂移) -- 默认在**调用行下方**插入或替换紧邻块(中间可有空行) -- `at_end=true` / `末尾=true`:在文件末尾保留单块(替换已有末尾块) +命名槽(智能体成功/失败互不覆盖): + +```markdown + + +``` + +- 注释内为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号** +- 默认在**调用行下方**插入或替换紧邻**无键**块 +- `at_end=true`:替换文件末尾的**无键**块 +- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽(智能体单步用父调用行,即 `step` 语句下方);`ensure` 在缺失时写入占位且不覆盖已有正文。命名槽互不覆盖,也不使用文件末尾单块。 +- `line=` / `行=`:显式锚点行号。子任务 / 异步写回必须带上,否则会锚到子任务内部调用行。主机侧有全局互斥锁,写前从磁盘重读入口源,避免并发写互相覆盖。 + +### 替换跨度与空行 + +替换 `` 时,被替换跨度**包含**注释块结束 `-->` 后的**单个**换行符(不把该换行留在文件里)。这样多次 `record` **不会**在块下方累积多余空行。 + +命名槽仍锚在调用行(如 `step` / `写回`)下方;整簇结束后保留**一条**有意空行即可,且应稳定。 ## API | EN | ZH | 说明 | |----|-----|------| -| `record` | `写回` | `value=`,可选 `at_end=false` | -| `get` | `取` | 可选 `at_end=false` | -| `clear` | `清除` | 可选 `at_end=false` | -| `list` | `列出` | 全文所有输出块(含推断锚点行) | +| `record` | `写回` | `value=`;可选 `at_end`、`key`、`line` | +| `get` | `取` | 可选 `at_end`、`key`、`line` | +| `clear` | `清除` | 可选 `at_end`、`key`、`line` | +| `ensure` | `确保` | `key=` + 可选 `placeholder=`、`line=`;槽已存在则不动 | +| `list` | `列出` | 全文所有输出块(命名槽含 `key` 字段) | 可选参数语法:`` + `参数名`=默认值 ``(与现有参数列表兼容)。 -Host:`host_writeback_*`(`src/host/writeback.rs`)。 +Host:`host_writeback_*`(`src/host/writeback.rs`);智能体侧经 `lib/subtask` 异步调用写回,避免阻塞推理主路径。 diff --git a/doc/design/stdlib.md b/doc/design/stdlib.md index b21e0b9..921627d 100644 --- a/doc/design/stdlib.md +++ b/doc/design/stdlib.md @@ -3,8 +3,8 @@ | | | |---|---| | 状态 | **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) | +| 日期 | 2026-08-07 | +| 相关 | [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) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) | > **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。 > **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。 @@ -42,7 +42,7 @@ ## 3. 官方库导入(S2) -Frontmatter: +Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可改)。成员经点号路径调用(`time.parse`、`json.get`),不倒进全局短名。完整语义见 [module-namespace.md](module-namespace.md)。 ```markdown --- @@ -51,6 +51,8 @@ Frontmatter: --- ``` +调用示例:`> time.now_unix`、`> json.parse text=…`。需要本地短名时用 `> use time.format`(冲突 → 硬错误)。 + `std/text.mq.md` 等价于 `lib/text.mq.md`。解析顺序: 1. 相对当前文件 diff --git a/doc/roadmap/interpreter.md b/doc/roadmap/interpreter.md index 384c9df..830d38c 100644 --- a/doc/roadmap/interpreter.md +++ b/doc/roadmap/interpreter.md @@ -62,7 +62,7 @@ index.mq.md (+ 导入的 .mq.md) └─────────┬─────────┘ ▼ ┌───────────────────┐ -│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入合并 +│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入模块树(见 module-namespace) │ │ 作用域链、形参、未定义名诊断 └─────────┬─────────┘ ▼ diff --git a/doc/roadmap/next-phase.md b/doc/roadmap/next-phase.md index 5ce0259..33645a0 100644 --- a/doc/roadmap/next-phase.md +++ b/doc/roadmap/next-phase.md @@ -19,7 +19,7 @@ | **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 | | **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** | | **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** | -| **模块** | `> file.mq.md` 顶层函数合并,无命名空间 | 短期可继续用 | +| **模块** | [module-namespace.md](../design/module-namespace.md):**M1+M2 已落地**(库名绑定、`库.成员` / `use`;无扁平合并) | — | 用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。 diff --git a/ext/ai/agent.mq.md b/ext/ai/agent.mq.md index 70c89d2..3133424 100644 --- a/ext/ai/agent.mq.md +++ b/ext/ai/agent.mq.md @@ -1,60 +1,117 @@ --- title: ext/ai/agent -description: Thin agent framework — ctor, run, clear_history only. +description: Document-driven agent — step / plan; tools via lib/subtask; runtime via ABI v2 agent plugin. > ext/ai/llm.mq.md +> lib/json.mq.md +> lib/sys.mq.md +> lib/subtask.mq.md +> lib/plugin.mq.md --- -## build_agent_context +## build_step_context + `agent` - + `extra` + + `task` -Internal: assemble prompt (user prompt, extra, tool list, source, call site, history, Marqdo skill). +Assemble a readable prompt: standing, task, tools, call site, source, skill, and the act protocol (human-visible). -*`user_prompt` = > get value=`agent` key=user_prompt * -1. `user_prompt` - *`up` = `user_prompt`* +*`standing` = > json.get value=`agent` key=standing * +1. `standing` + *`up` = `standing`* 2. * *`up` = None* -*`tools` = > get value=`agent` key=tools * -*`tools_s` = > host_format_tools_for_llm tools=`tools` * -*`src` = > host_module_source * -*`site` = > host_call_site * -*`site_s` = > stringify value=`site` * -*`id` = > get value=`agent` key=id * -*`hist` = > host_agent_history_get id=`id` * -*`hist_s` = > stringify value=`hist` * -*`skill` = > host_marqdo_skill * -*`extra_s` = > stringify value=`extra` * +*`tools` = > json.get value=`agent` key=tools * +*`tools_s` = > agent_format_tools tools=`tools` * +*`src` = > agent_module_source * +*`site` = > agent_call_site * +*`site_s` = > json.stringify value=`site` * +*`skill` = > agent_marqdo_skill * +*`task_s` = > json.stringify value=`task` * -*`sep` = > parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- extra ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source ---\n","f":"\n\n--- history ---\n","g":"\n\n--- marqdo skill ---\n"} * -*`a` = > get value=`sep` key=a * -*`b` = > get value=`sep` key=b * -*`c` = > get value=`sep` key=c * -*`d` = > get value=`sep` key=d * -*`e` = > get value=`sep` key=e * -*`f` = > get value=`sep` key=f * -*`g` = > get value=`sep` key=g * +*`esc` = > json.parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- task ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source (.mq.md) ---\n","f":"\n\n--- marqdo skill ---\n","g":"\n\n--- how to act ---\nTools are ## functions in the source above. To call one, reply with exactly one line: CALL:\n(Chinese ok: 调用:)\nOtherwise reply with the final answer only.\nTools run via Marqdo subtask (spawn fn / wait).\n"} * +*`a` = > json.get value=`esc` key=a * +*`b` = > json.get value=`esc` key=b * +*`c` = > json.get value=`esc` key=c * +*`d` = > json.get value=`esc` key=d * +*`e` = > json.get value=`esc` key=e * +*`f` = > json.get value=`esc` key=f * +*`g` = > json.get value=`esc` key=g * -*`tool_proto` = \n\n--- tool protocol ---\nEach tool is a zero-arg Marqdo function in this module (see tools list). To call one, reply with exactly one line: TOOL:. No other text on that line.\nAfter the tool runs you will get its output and should answer the user.\n * - -*`p` = You are a Marqdo agent. Follow Marqdo skill rules when reading or writing .mq.md. * -*`p` = `p` + `a` + `up` + `b` + `extra_s` + `c` + `tool_proto` + `tools_s` + `d` + `site_s` + `e` + `src` + `f` + `hist_s` + `g` + `skill` * +*`p` = You are a Marqdo agent. The runbook source is your ground truth — code is documentation. * +*`p` = `p` + `a` + `up` + `b` + `task_s` + `c` + `tools_s` + `g` + `d` + `site_s` + `e` + `src` + `f` + `skill` * **`p`** +--- + +## extract_tool_name + + `reply` + +Find a human-readable call line: `CALL:` or `调用:` / `调用:`. + +*`esc` = > json.parse text={"nl":"\n"} * +*`nl` = > json.get value=`esc` key=nl * +*`text` = > trim value=`reply` * +*`lines` = > split value=`text` sep=`nl` * +*`found` = None* + +- [`line`](`lines`) + *`t` = > trim value=`line` * + *`parts` = > split value=`t` sep=: * + *`n` = > len value=`parts` * + 1. `n` > 1 + *`head` = > at value=`parts` index=0 * + *`head` = > trim value=`head` * + *`rest` = > at value=`parts` index=1 * + *`rest` = > trim value=`rest` * + 1. `head` == CALL + *`found` = `rest`* + 2. `head` == 调用 + *`found` = `rest`* + 3. * + *`_` = 1* + 2. * + *`_` = 1* + +**`found`** + +--- + +## run_tool + + `tools` + + `name` + +Allowlist check, then invoke the runbook `##` via `lib/subtask` (`spawn fn=` → `wait`). + +*`allowed` = > agent_tool_allowed tools=`tools` name=`name` * +1. `allowed` + *`id` = > subtask.spawn fn=`name` * + **> subtask.wait id=`id`** +2. * + *`msg` = Tool not allowed: * + **`msg` + `name`** + # agent + `model` + `tools` - + `user_prompt` + + `standing` -*`id` = > host_agent_alloc * -*`h` = > parse text={"_type":"agent"} * -*`h` = > map_set map=`h` key=id value=`id` * -*`h` = > map_set map=`h` key=model value=`model` * -*`h` = > map_set map=`h` key=tools value=`tools` * +Load ABI v2 agent plugin once (session bag + context queries). -1. `user_prompt` - *`h` = > map_set map=`h` key=user_prompt value=`user_prompt` * +*`p` = > plugin.native_path name=agent * +1. `p` + > plugin.load path=`p` +2. * + > print text=ext/ai/agent: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent) + > sys.exit code=1 + +*`id` = > agent_alloc * +*`h` = > json.parse text={"_type":"agent"} * +*`h` = > json.set map=`h` key=id value=`id` * +*`h` = > json.set map=`h` key=model value=`model` * +*`h` = > json.set map=`h` key=tools value=`tools` * + +1. `standing` + *`h` = > json.set map=`h` key=standing value=`standing` * 2. * *`_` = 1* @@ -62,50 +119,70 @@ Internal: assemble prompt (user prompt, extra, tool list, source, call site, his ## clear_history -*`id` = > get value=`self` key=id * -> host_agent_history_clear id=`id` +Clear the plugin session bag for this agent id. + +*`id` = > json.get value=`self` key=id * +> agent_history_clear id=`id` **** -## run - + `extra` +## step + + `task` -*`ctx` = > build_agent_context agent=`self` extra=`extra` * -*`id` = > get value=`self` key=id * +One atomic turn: context → LLM → optional tool via subtask. Returns a **map** (`status`, `task`, `decision`, and on success `result` plus optional `tool` / `tool_result`; on failure `error`). Does **not** write back — call `lib/writeback` yourself if you want persistence. -*`user_turn` = > parse text={"role":"user"} * -*`user_turn` = > map_set map=`user_turn` key=content value=`extra` * -> host_agent_history_append id=`id` item=`user_turn` +*`ctx` = > build_step_context agent=`self` task=`task` * +*`id` = > json.get value=`self` key=id * +*`model` = > json.get value=`self` key=model * +*`tools` = > json.get value=`self` key=tools * + +*`user_turn` = > json.parse text={"role":"user"} * +*`user_turn` = > json.set map=`user_turn` key=content value=`task` * +> agent_history_append id=`id` item=`user_turn` -*`model` = > get value=`self` key=model * *`reply` = > `model`.complete prompt=`ctx` * -*`tools` = > get value=`self` key=tools * *`reply` = > trim value=`reply` * +*`decision` = `reply`* +*`tool_name` = > extract_tool_name reply=`reply` * +*`out` = > json.parse text={"status":"ok"} * +*`out` = > json.set map=`out` key=task value=`task` * +*`out` = > json.set map=`out` key=decision value=`decision` * -*`parts` = > split value=`reply` sep=: * -*`head` = > at value=`parts` index=0 * -*`tool_name` = > at value=`parts` index=1 * -*`tool_name` = > trim value=`tool_name` * - -1. `head` == TOOL - *`allowed` = > host_tool_allowed tools=`tools` name=`tool_name` * - 1. `allowed` - *`tool_out` = > call_fn name=`tool_name` * - *`tool_s` = > stringify value=`tool_out` * - *`extra_s` = > stringify value=`extra` * - *`fp` = The user asked: * - *`fp` = `fp` + `extra_s` * - *`fp` = `fp` + . You invoked tool * - *`fp` = `fp` + `tool_name` * - *`fp` = `fp` + which returned: * - *`fp` = `fp` + `tool_s` * - *`fp` = `fp` + . Reply to the user in one brief sentence. * - *`reply` = > `model`.complete prompt=`fp` * +1. `tool_name` + *`tool_out` = > run_tool tools=`tools` name=`tool_name` * + *`tool_s` = > json.stringify value=`tool_out` * + *`deny` = > split value=`tool_s` sep=Tool not allowed * + *`deny_n` = > len value=`deny` * + 1. `deny_n` > 1 + *`out` = > json.set map=`out` key=status value=error * + *`out` = > json.set map=`out` key=error value=`tool_s` * + *`reply` = `tool_s`* 2. * - *`reply` = Tool not allowed: `tool_name` * + *`task_s` = > json.stringify value=`task` * + *`fp` = The user asked: * + *`fp` = `fp` + `task_s` * + *`fp` = `fp` + . Tool * + *`fp` = `fp` + `tool_name` * + *`fp` = `fp` + ran via subtask and returned: * + *`fp` = `fp` + `tool_s` * + *`fp` = `fp` + . Reply to the user briefly. * + *`reply` = > `model`.complete prompt=`fp` * + *`out` = > json.set map=`out` key=tool value=`tool_name` * + *`out` = > json.set map=`out` key=tool_result value=`tool_s` * + *`out` = > json.set map=`out` key=result value=`reply` * 2. * - *`_` = 1* + *`out` = > json.set map=`out` key=result value=`reply` * -*`as_turn` = > parse text={"role":"assistant"} * -*`as_turn` = > map_set map=`as_turn` key=content value=`reply` * -> host_agent_history_append id=`id` item=`as_turn` -**`reply`** +*`as_turn` = > json.parse text={"role":"assistant"} * +*`as_turn` = > json.set map=`as_turn` key=content value=`reply` * +> agent_history_append id=`id` item=`as_turn` +**`out`** + +## plan + + `goal` + + `workbook_dir` + +Multi-step workbook (D2) — not implemented yet. + +*`_` = `workbook_dir`* +*`msg` = plan (multi-step workbook) is not implemented yet; goal was: * +**`msg` + `goal`** diff --git a/ext/ai/llm.mq.md b/ext/ai/llm.mq.md index b277e11..ef3fa4b 100644 --- a/ext/ai/llm.mq.md +++ b/ext/ai/llm.mq.md @@ -7,118 +7,119 @@ description: OpenAI-compatible LLM object (English). Import ext/ai/llm.mq.md. --- ## load_env + + `path`=None Load `.env` from cwd (optional named arg `path=`). Does not override existing variables. -**> load_dotenv** +**> sys.load_dotenv path=`path`** # llm Construct an LLM handle from `OPENAI_*` / `MARQDO_LLM_*` (default base OpenAI v1, model `gpt-4o-mini`). -*`d` = > parse text={"base":"https://api.openai.com/v1","model":"gpt-4o-mini","suffix":"/chat/completions","bearer":"Bearer ","p1":"{\"model\":","p2":",\"messages\":[{\"role\":\"user\",\"content\":","p3":"}]}","h1":"{\"Authorization\":","h2":"}","a1":"{\"api_key\":","a2":",\"base_url\":","a3":",\"model\":","a4":",\"suffix\":","a5":",\"bearer\":","a6":",\"p1\":","a7":",\"p2\":","a8":",\"p3\":","a9":",\"h1\":","a10":",\"h2\":","a11":"}"} * +*`d` = > json.parse text={"base":"https://api.openai.com/v1","model":"gpt-4o-mini","suffix":"/chat/completions","bearer":"Bearer ","p1":"{\"model\":","p2":",\"messages\":[{\"role\":\"user\",\"content\":","p3":"}]}","h1":"{\"Authorization\":","h2":"}","a1":"{\"api_key\":","a2":",\"base_url\":","a3":",\"model\":","a4":",\"suffix\":","a5":",\"bearer\":","a6":",\"p1\":","a7":",\"p2\":","a8":",\"p3\":","a9":",\"h1\":","a10":",\"h2\":","a11":"}"} * -*`api_key` = > env_get name=OPENAI_API_KEY * +*`api_key` = > sys.env_get name=OPENAI_API_KEY * 1. `api_key` *`_k` = 1* 2. * - *`api_key` = > env_get name=MARQDO_LLM_API_KEY * + *`api_key` = > sys.env_get name=MARQDO_LLM_API_KEY * 3. `api_key` *`_k` = 1* 4. * > print text=ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY - > exit code=1 + > sys.exit code=1 -*`base_url` = > env_get name=OPENAI_BASE_URL * +*`base_url` = > sys.env_get name=OPENAI_BASE_URL * 1. `base_url` *`_k` = 1* 2. * - *`base_url` = > env_get name=MARQDO_LLM_BASE_URL * + *`base_url` = > sys.env_get name=MARQDO_LLM_BASE_URL * 3. `base_url` *`_k` = 1* 4. * - *`base_url` = > get value=`d` key=base * + *`base_url` = > json.get value=`d` key=base * -*`model` = > env_get name=OPENAI_MODEL * +*`model` = > sys.env_get name=OPENAI_MODEL * 1. `model` *`_k` = 1* 2. * - *`model` = > env_get name=MARQDO_LLM_MODEL * + *`model` = > sys.env_get name=MARQDO_LLM_MODEL * 3. `model` *`_k` = 1* 4. * - *`model` = > get value=`d` key=model * + *`model` = > json.get value=`d` key=model * -*`q_key` = > quote text=`api_key` * -*`q_base` = > quote text=`base_url` * -*`q_model` = > quote text=`model` * -*`suffix` = > get value=`d` key=suffix * -*`bearer` = > get value=`d` key=bearer * -*`p1` = > get value=`d` key=p1 * -*`p2` = > get value=`d` key=p2 * -*`p3` = > get value=`d` key=p3 * -*`h1` = > get value=`d` key=h1 * -*`h2` = > get value=`d` key=h2 * -*`q_suf` = > quote text=`suffix` * -*`q_br` = > quote text=`bearer` * -*`q_p1` = > quote text=`p1` * -*`q_p2` = > quote text=`p2` * -*`q_p3` = > quote text=`p3` * -*`q_h1` = > quote text=`h1` * -*`q_h2` = > quote text=`h2` * -*`a1` = > get value=`d` key=a1 * -*`a2` = > get value=`d` key=a2 * -*`a3` = > get value=`d` key=a3 * -*`a4` = > get value=`d` key=a4 * -*`a5` = > get value=`d` key=a5 * -*`a6` = > get value=`d` key=a6 * -*`a7` = > get value=`d` key=a7 * -*`a8` = > get value=`d` key=a8 * -*`a9` = > get value=`d` key=a9 * -*`a10` = > get value=`d` key=a10 * -*`a11` = > get value=`d` key=a11 * +*`q_key` = > json.quote text=`api_key` * +*`q_base` = > json.quote text=`base_url` * +*`q_model` = > json.quote text=`model` * +*`suffix` = > json.get value=`d` key=suffix * +*`bearer` = > json.get value=`d` key=bearer * +*`p1` = > json.get value=`d` key=p1 * +*`p2` = > json.get value=`d` key=p2 * +*`p3` = > json.get value=`d` key=p3 * +*`h1` = > json.get value=`d` key=h1 * +*`h2` = > json.get value=`d` key=h2 * +*`q_suf` = > json.quote text=`suffix` * +*`q_br` = > json.quote text=`bearer` * +*`q_p1` = > json.quote text=`p1` * +*`q_p2` = > json.quote text=`p2` * +*`q_p3` = > json.quote text=`p3` * +*`q_h1` = > json.quote text=`h1` * +*`q_h2` = > json.quote text=`h2` * +*`a1` = > json.get value=`d` key=a1 * +*`a2` = > json.get value=`d` key=a2 * +*`a3` = > json.get value=`d` key=a3 * +*`a4` = > json.get value=`d` key=a4 * +*`a5` = > json.get value=`d` key=a5 * +*`a6` = > json.get value=`d` key=a6 * +*`a7` = > json.get value=`d` key=a7 * +*`a8` = > json.get value=`d` key=a8 * +*`a9` = > json.get value=`d` key=a9 * +*`a10` = > json.get value=`d` key=a10 * +*`a11` = > json.get value=`d` key=a11 * *`raw` = `a1` + `q_key` + `a2` + `q_base` + `a3` + `q_model` + `a4` + `q_suf` + `a5` + `q_br` + `a6` + `q_p1` + `a7` + `q_p2` + `a8` + `q_p3` + `a9` + `q_h1` + `a10` + `q_h2` + `a11` * -**> parse text=`raw`** +**> json.parse text=`raw`** ## complete + `prompt` Chat completion using `self` / `自` handle fields. -*`api_key` = > get value=`self` key=api_key * -*`base_url` = > get value=`self` key=base_url * -*`model` = > get value=`self` key=model * -*`suffix` = > get value=`self` key=suffix * -*`bearer` = > get value=`self` key=bearer * -*`p1` = > get value=`self` key=p1 * -*`p2` = > get value=`self` key=p2 * -*`p3` = > get value=`self` key=p3 * -*`h1` = > get value=`self` key=h1 * -*`h2` = > get value=`self` key=h2 * +*`api_key` = > json.get value=`self` key=api_key * +*`base_url` = > json.get value=`self` key=base_url * +*`model` = > json.get value=`self` key=model * +*`suffix` = > json.get value=`self` key=suffix * +*`bearer` = > json.get value=`self` key=bearer * +*`p1` = > json.get value=`self` key=p1 * +*`p2` = > json.get value=`self` key=p2 * +*`p3` = > json.get value=`self` key=p3 * +*`h1` = > json.get value=`self` key=h1 * +*`h2` = > json.get value=`self` key=h2 * *`url` = `base_url` + `suffix` * *`auth` = `bearer` + `api_key` * -*`q_auth` = > quote text=`auth` * +*`q_auth` = > json.quote text=`auth` * *`hdr_raw` = `h1` + `q_auth` + `h2` * -*`headers` = > parse text=`hdr_raw` * -*`q_model` = > quote text=`model` * -*`q_prompt` = > quote text=`prompt` * +*`headers` = > json.parse text=`hdr_raw` * +*`q_model` = > json.quote text=`model` * +*`q_prompt` = > json.quote text=`prompt` * *`body` = `p1` + `q_model` + `p2` + `q_prompt` + `p3` * -*`resp` = > http_post url=`url` body=`body` headers=`headers` * -*`status` = > get value=`resp` key=status * -*`raw` = > get value=`resp` key=body * +*`resp` = > net.http_post url=`url` body=`body` headers=`headers` * +*`status` = > json.get value=`resp` key=status * +*`raw` = > json.get value=`resp` key=body * 1. `status` == 200 - *`data` = > parse text=`raw` * - *`choices` = > get value=`data` key=choices * + *`data` = > json.parse text=`raw` * + *`choices` = > json.get value=`data` key=choices * *`first` = > at value=`choices` index=0 * - *`message` = > get value=`first` key=message * - *`content` = > get value=`message` key=content * + *`message` = > json.get value=`first` key=message * + *`content` = > json.get value=`message` key=content * **`content`** 2. * > print text=ext/ai/llm: HTTP error > print text=`status` > print text=`raw` - > exit code=1 + > sys.exit code=1 --- diff --git a/ext/ai/大模型.mq.md b/ext/ai/大模型.mq.md index a1e93f6..2e41a6c 100644 --- a/ext/ai/大模型.mq.md +++ b/ext/ai/大模型.mq.md @@ -7,118 +7,119 @@ description: OpenAI 兼容大模型对象(中文)。导入 ext/ai/大模型. --- ## 加载环境 + + `路径`=None -从工作目录加载 `.env`(可选具名实参 `path=`)。不覆盖已有变量。 +从工作目录加载 `.env`(可选具名实参 `路径=`)。不覆盖已有变量。 -**> load_dotenv** +**> 系统.加载环境 路径=`路径`** # 大模型 从 `OPENAI_*` / `MARQDO_LLM_*` 构造句柄(默认 OpenAI v1 + `gpt-4o-mini`)。 -*`d` = > parse text={"base":"https://api.openai.com/v1","model":"gpt-4o-mini","suffix":"/chat/completions","bearer":"Bearer ","p1":"{\"model\":","p2":",\"messages\":[{\"role\":\"user\",\"content\":","p3":"}]}","h1":"{\"Authorization\":","h2":"}","a1":"{\"api_key\":","a2":",\"base_url\":","a3":",\"model\":","a4":",\"suffix\":","a5":",\"bearer\":","a6":",\"p1\":","a7":",\"p2\":","a8":",\"p3\":","a9":",\"h1\":","a10":",\"h2\":","a11":"}"} * +*`d` = > json.parse text={"base":"https://api.openai.com/v1","model":"gpt-4o-mini","suffix":"/chat/completions","bearer":"Bearer ","p1":"{\"model\":","p2":",\"messages\":[{\"role\":\"user\",\"content\":","p3":"}]}","h1":"{\"Authorization\":","h2":"}","a1":"{\"api_key\":","a2":",\"base_url\":","a3":",\"model\":","a4":",\"suffix\":","a5":",\"bearer\":","a6":",\"p1\":","a7":",\"p2\":","a8":",\"p3\":","a9":",\"h1\":","a10":",\"h2\":","a11":"}"} * -*`api_key` = > 取环境 名=OPENAI_API_KEY * +*`api_key` = > 系统.取环境 名=OPENAI_API_KEY * 1. `api_key` *`_k` = 1* 2. * - *`api_key` = > 取环境 名=MARQDO_LLM_API_KEY * + *`api_key` = > 系统.取环境 名=MARQDO_LLM_API_KEY * 3. `api_key` *`_k` = 1* 4. * > 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY - > 退出 码=1 + > 系统.退出 码=1 -*`base_url` = > 取环境 名=OPENAI_BASE_URL * +*`base_url` = > 系统.取环境 名=OPENAI_BASE_URL * 1. `base_url` *`_k` = 1* 2. * - *`base_url` = > 取环境 名=MARQDO_LLM_BASE_URL * + *`base_url` = > 系统.取环境 名=MARQDO_LLM_BASE_URL * 3. `base_url` *`_k` = 1* 4. * - *`base_url` = > get value=`d` key=base * + *`base_url` = > json.get value=`d` key=base * -*`model` = > 取环境 名=OPENAI_MODEL * +*`model` = > 系统.取环境 名=OPENAI_MODEL * 1. `model` *`_k` = 1* 2. * - *`model` = > 取环境 名=MARQDO_LLM_MODEL * + *`model` = > 系统.取环境 名=MARQDO_LLM_MODEL * 3. `model` *`_k` = 1* 4. * - *`model` = > get value=`d` key=model * + *`model` = > json.get value=`d` key=model * -*`q_key` = > quote text=`api_key` * -*`q_base` = > quote text=`base_url` * -*`q_model` = > quote text=`model` * -*`suffix` = > get value=`d` key=suffix * -*`bearer` = > get value=`d` key=bearer * -*`p1` = > get value=`d` key=p1 * -*`p2` = > get value=`d` key=p2 * -*`p3` = > get value=`d` key=p3 * -*`h1` = > get value=`d` key=h1 * -*`h2` = > get value=`d` key=h2 * -*`q_suf` = > quote text=`suffix` * -*`q_br` = > quote text=`bearer` * -*`q_p1` = > quote text=`p1` * -*`q_p2` = > quote text=`p2` * -*`q_p3` = > quote text=`p3` * -*`q_h1` = > quote text=`h1` * -*`q_h2` = > quote text=`h2` * -*`a1` = > get value=`d` key=a1 * -*`a2` = > get value=`d` key=a2 * -*`a3` = > get value=`d` key=a3 * -*`a4` = > get value=`d` key=a4 * -*`a5` = > get value=`d` key=a5 * -*`a6` = > get value=`d` key=a6 * -*`a7` = > get value=`d` key=a7 * -*`a8` = > get value=`d` key=a8 * -*`a9` = > get value=`d` key=a9 * -*`a10` = > get value=`d` key=a10 * -*`a11` = > get value=`d` key=a11 * +*`q_key` = > json.quote text=`api_key` * +*`q_base` = > json.quote text=`base_url` * +*`q_model` = > json.quote text=`model` * +*`suffix` = > json.get value=`d` key=suffix * +*`bearer` = > json.get value=`d` key=bearer * +*`p1` = > json.get value=`d` key=p1 * +*`p2` = > json.get value=`d` key=p2 * +*`p3` = > json.get value=`d` key=p3 * +*`h1` = > json.get value=`d` key=h1 * +*`h2` = > json.get value=`d` key=h2 * +*`q_suf` = > json.quote text=`suffix` * +*`q_br` = > json.quote text=`bearer` * +*`q_p1` = > json.quote text=`p1` * +*`q_p2` = > json.quote text=`p2` * +*`q_p3` = > json.quote text=`p3` * +*`q_h1` = > json.quote text=`h1` * +*`q_h2` = > json.quote text=`h2` * +*`a1` = > json.get value=`d` key=a1 * +*`a2` = > json.get value=`d` key=a2 * +*`a3` = > json.get value=`d` key=a3 * +*`a4` = > json.get value=`d` key=a4 * +*`a5` = > json.get value=`d` key=a5 * +*`a6` = > json.get value=`d` key=a6 * +*`a7` = > json.get value=`d` key=a7 * +*`a8` = > json.get value=`d` key=a8 * +*`a9` = > json.get value=`d` key=a9 * +*`a10` = > json.get value=`d` key=a10 * +*`a11` = > json.get value=`d` key=a11 * *`raw` = `a1` + `q_key` + `a2` + `q_base` + `a3` + `q_model` + `a4` + `q_suf` + `a5` + `q_br` + `a6` + `q_p1` + `a7` + `q_p2` + `a8` + `q_p3` + `a9` + `q_h1` + `a10` + `q_h2` + `a11` * -**> parse text=`raw`** +**> json.parse text=`raw`** ## 运行 + `提示` 使用 `自` / `self` 句柄字段做聊天补全。 -*`api_key` = > get value=`自` key=api_key * -*`base_url` = > get value=`自` key=base_url * -*`model` = > get value=`自` key=model * -*`suffix` = > get value=`自` key=suffix * -*`bearer` = > get value=`自` key=bearer * -*`p1` = > get value=`自` key=p1 * -*`p2` = > get value=`自` key=p2 * -*`p3` = > get value=`自` key=p3 * -*`h1` = > get value=`自` key=h1 * -*`h2` = > get value=`自` key=h2 * +*`api_key` = > json.get value=`自` key=api_key * +*`base_url` = > json.get value=`自` key=base_url * +*`model` = > json.get value=`自` key=model * +*`suffix` = > json.get value=`自` key=suffix * +*`bearer` = > json.get value=`自` key=bearer * +*`p1` = > json.get value=`自` key=p1 * +*`p2` = > json.get value=`自` key=p2 * +*`p3` = > json.get value=`自` key=p3 * +*`h1` = > json.get value=`自` key=h1 * +*`h2` = > json.get value=`自` key=h2 * *`url` = `base_url` + `suffix` * *`auth` = `bearer` + `api_key` * -*`q_auth` = > quote text=`auth` * +*`q_auth` = > json.quote text=`auth` * *`hdr_raw` = `h1` + `q_auth` + `h2` * -*`headers` = > parse text=`hdr_raw` * -*`q_model` = > quote text=`model` * -*`q_prompt` = > quote text=`提示` * +*`headers` = > json.parse text=`hdr_raw` * +*`q_model` = > json.quote text=`model` * +*`q_prompt` = > json.quote text=`提示` * *`body` = `p1` + `q_model` + `p2` + `q_prompt` + `p3` * -*`resp` = > http_post url=`url` body=`body` headers=`headers` * -*`status` = > get value=`resp` key=status * -*`raw` = > get value=`resp` key=body * +*`resp` = > 网络.提交 地址=`url` 内容=`body` headers=`headers` * +*`status` = > json.get value=`resp` key=status * +*`raw` = > json.get value=`resp` key=body * 1. `status` == 200 - *`data` = > parse text=`raw` * - *`choices` = > get value=`data` key=choices * + *`data` = > json.parse text=`raw` * + *`choices` = > json.get value=`data` key=choices * *`first` = > at value=`choices` index=0 * - *`message` = > get value=`first` key=message * - *`content` = > get value=`message` key=content * + *`message` = > json.get value=`first` key=message * + *`content` = > json.get value=`message` key=content * **`content`** 2. * > 打印 内容=ext/ai/大模型: HTTP 错误 > 打印 内容=`status` > 打印 内容=`raw` - > 退出 码=1 + > 系统.退出 码=1 --- diff --git a/ext/ai/智能体.mq.md b/ext/ai/智能体.mq.md index 5c430cf..811db97 100644 --- a/ext/ai/智能体.mq.md +++ b/ext/ai/智能体.mq.md @@ -1,60 +1,117 @@ --- title: ext/ai/智能体 -description: 薄智能体框架 — 仅构造、执行、清空历史。 +description: 文档驱动智能体 — 单步 / 多步;工具经 lib/子任务;运行时经 ABI v2 agent 插件。 > ext/ai/大模型.mq.md +> lib/json.mq.md +> lib/系统.mq.md +> lib/子任务.mq.md +> lib/插件.mq.md --- -## 构建上下文 +## 构建单步上下文 + `智能体` - + `额外信息` + + `任务` -内部:组装提示(用户提示、额外信息、工具列表、源码、位置、历史、Marqdo skill)。 +组装可读提示:站立提示、任务、工具、调用位置、源码、Skill,以及人可见的行动约定。 -*`user_prompt` = > get value=`智能体` key=user_prompt * -1. `user_prompt` - *`up` = `user_prompt`* +*`standing` = > json.get value=`智能体` key=standing * +1. `standing` + *`up` = `standing`* 2. * *`up` = 空* -*`tools` = > get value=`智能体` key=tools * -*`tools_s` = > host_format_tools_for_llm tools=`tools` * -*`src` = > host_module_source * -*`site` = > host_call_site * -*`site_s` = > stringify value=`site` * -*`id` = > get value=`智能体` key=id * -*`hist` = > host_agent_history_get id=`id` * -*`hist_s` = > stringify value=`hist` * -*`skill` = > host_marqdo_skill * -*`extra_s` = > stringify value=`额外信息` * +*`tools` = > json.get value=`智能体` key=tools * +*`tools_s` = > agent_format_tools tools=`tools` * +*`src` = > agent_module_source * +*`site` = > agent_call_site * +*`site_s` = > json.stringify value=`site` * +*`skill` = > agent_marqdo_skill * +*`task_s` = > json.stringify value=`任务` * -*`sep` = > parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- extra ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source ---\n","f":"\n\n--- history ---\n","g":"\n\n--- marqdo skill ---\n"} * -*`a` = > get value=`sep` key=a * -*`b` = > get value=`sep` key=b * -*`c` = > get value=`sep` key=c * -*`d` = > get value=`sep` key=d * -*`e` = > get value=`sep` key=e * -*`f` = > get value=`sep` key=f * -*`g` = > get value=`sep` key=g * +*`esc` = > json.parse text={"a":"\n\n--- standing ---\n","b":"\n\n--- task ---\n","c":"\n\n--- tools ---\n","d":"\n\n--- call site ---\n","e":"\n\n--- source (.mq.md) ---\n","f":"\n\n--- marqdo skill ---\n","g":"\n\n--- how to act ---\nTools are ## functions in the source above. To call one, reply with exactly one line: CALL:\n(Chinese ok: 调用:)\nOtherwise reply with the final answer only.\nTools run via Marqdo subtask (spawn fn / wait).\n"} * +*`a` = > json.get value=`esc` key=a * +*`b` = > json.get value=`esc` key=b * +*`c` = > json.get value=`esc` key=c * +*`d` = > json.get value=`esc` key=d * +*`e` = > json.get value=`esc` key=e * +*`f` = > json.get value=`esc` key=f * +*`g` = > json.get value=`esc` key=g * -*`tool_proto` = \n\n--- tool protocol ---\nEach tool is a zero-arg Marqdo function in this module (see tools list). To call one, reply with exactly one line: TOOL:. No other text on that line.\nAfter the tool runs you will get its output and should answer the user.\n * - -*`p` = You are a Marqdo agent. Follow Marqdo skill rules when reading or writing .mq.md. * -*`p` = `p` + `a` + `up` + `b` + `extra_s` + `c` + `tool_proto` + `tools_s` + `d` + `site_s` + `e` + `src` + `f` + `hist_s` + `g` + `skill` * +*`p` = You are a Marqdo agent. The runbook source is your ground truth — code is documentation. * +*`p` = `p` + `a` + `up` + `b` + `task_s` + `c` + `tools_s` + `g` + `d` + `site_s` + `e` + `src` + `f` + `skill` * **`p`** +--- + +## 提取工具名 + + `回复` + +解析人可读调用行:`CALL:<名>` 或 `调用:<名>` / `调用:<名>`。 + +*`esc` = > json.parse text={"nl":"\n"} * +*`nl` = > json.get value=`esc` key=nl * +*`text` = > trim value=`回复` * +*`lines` = > split value=`text` sep=`nl` * +*`found` = 空* + +- [`line`](`lines`) + *`t` = > trim value=`line` * + *`parts` = > split value=`t` sep=: * + *`n` = > len value=`parts` * + 1. `n` > 1 + *`head` = > at value=`parts` index=0 * + *`head` = > trim value=`head` * + *`rest` = > at value=`parts` index=1 * + *`rest` = > trim value=`rest` * + 1. `head` == CALL + *`found` = `rest`* + 2. `head` == 调用 + *`found` = `rest`* + 3. * + *`_` = 1* + 2. * + *`_` = 1* + +**`found`** + +--- + +## 运行工具 + + `工具` + + `名` + +白名单校验后,经 `lib/子任务`(`启动 函数=` → `等待`)调用 runbook 中的 `##`。 + +*`allowed` = > agent_tool_allowed tools=`工具` name=`名` * +1. `allowed` + *`id` = > 子任务.启动 函数=`名` * + **> 子任务.等待 id=`id`** +2. * + *`msg` = Tool not allowed: * + **`msg` + `名`** + # 智能体 + `大模型` + `工具` - + `用户提示信息` + + `站立提示` -*`id` = > host_agent_alloc * -*`h` = > parse text={"_type":"智能体"} * -*`h` = > map_set map=`h` key=id value=`id` * -*`h` = > map_set map=`h` key=model value=`大模型` * -*`h` = > map_set map=`h` key=tools value=`工具` * +加载 ABI v2 agent 插件(会话袋 + 上下文查询)。 -1. `用户提示信息` - *`h` = > map_set map=`h` key=user_prompt value=`用户提示信息` * +*`p` = > 插件.原生路径 名=agent * +1. `p` + > 插件.加载 路径=`p` +2. * + > 打印 内容=ext/ai/智能体: 未找到原生 agent 插件(请先 cargo build -p marqdo_plugin_agent 或 marqdo ext add agent) + > 系统.退出 码=1 + +*`id` = > agent_alloc * +*`h` = > json.parse text={"_type":"智能体"} * +*`h` = > json.set map=`h` key=id value=`id` * +*`h` = > json.set map=`h` key=model value=`大模型` * +*`h` = > json.set map=`h` key=tools value=`工具` * + +1. `站立提示` + *`h` = > json.set map=`h` key=standing value=`站立提示` * 2. * *`_` = 1* @@ -62,50 +119,70 @@ description: 薄智能体框架 — 仅构造、执行、清空历史。 ## 清空历史 -*`id` = > get value=`自` key=id * -> host_agent_history_clear id=`id` +清空本智能体 id 的插件会话袋。 + +*`id` = > json.get value=`自` key=id * +> agent_history_clear id=`id` **** -## 执行 - + `额外信息` +## 单步 + + `任务` -*`ctx` = > 构建上下文 智能体=`自` 额外信息=`额外信息` * -*`id` = > get value=`自` key=id * +原子一轮:上下文 → 大模型 → 可选子任务调工具。返回 **map**(`status`、`task`、`decision`;成功含 `result`,可选 `tool` / `tool_result`;失败含 `error`)。**不**自动写回——需要持久化时自行调用 `lib/自写回`。 -*`user_turn` = > parse text={"role":"user"} * -*`user_turn` = > map_set map=`user_turn` key=content value=`额外信息` * -> host_agent_history_append id=`id` item=`user_turn` +*`ctx` = > 构建单步上下文 智能体=`自` 任务=`任务` * +*`id` = > json.get value=`自` key=id * +*`model` = > json.get value=`自` key=model * +*`tools` = > json.get value=`自` key=tools * + +*`user_turn` = > json.parse text={"role":"user"} * +*`user_turn` = > json.set map=`user_turn` key=content value=`任务` * +> agent_history_append id=`id` item=`user_turn` -*`model` = > get value=`自` key=model * *`reply` = > `model`.运行 提示=`ctx` * -*`tools` = > get value=`自` key=tools * *`reply` = > trim value=`reply` * +*`decision` = `reply`* +*`tool_name` = > 提取工具名 回复=`reply` * +*`out` = > json.parse text={"status":"ok"} * +*`out` = > json.set map=`out` key=task value=`任务` * +*`out` = > json.set map=`out` key=decision value=`decision` * -*`parts` = > split value=`reply` sep=: * -*`head` = > at value=`parts` index=0 * -*`tool_name` = > at value=`parts` index=1 * -*`tool_name` = > trim value=`tool_name` * - -1. `head` == TOOL - *`allowed` = > host_tool_allowed tools=`tools` name=`tool_name` * - 1. `allowed` - *`tool_out` = > 调用 名=`tool_name` * - *`tool_s` = > stringify value=`tool_out` * - *`extra_s` = > stringify value=`额外信息` * - *`fp` = The user asked: * - *`fp` = `fp` + `extra_s` * - *`fp` = `fp` + . You invoked tool * - *`fp` = `fp` + `tool_name` * - *`fp` = `fp` + which returned: * - *`fp` = `fp` + `tool_s` * - *`fp` = `fp` + . Reply to the user in one brief sentence. * - *`reply` = > `model`.运行 提示=`fp` * +1. `tool_name` + *`tool_out` = > 运行工具 工具=`tools` 名=`tool_name` * + *`tool_s` = > json.stringify value=`tool_out` * + *`deny` = > split value=`tool_s` sep=Tool not allowed * + *`deny_n` = > len value=`deny` * + 1. `deny_n` > 1 + *`out` = > json.set map=`out` key=status value=error * + *`out` = > json.set map=`out` key=error value=`tool_s` * + *`reply` = `tool_s`* 2. * - *`reply` = Tool not allowed: `tool_name` * + *`task_s` = > json.stringify value=`任务` * + *`fp` = The user asked: * + *`fp` = `fp` + `task_s` * + *`fp` = `fp` + . Tool * + *`fp` = `fp` + `tool_name` * + *`fp` = `fp` + ran via subtask and returned: * + *`fp` = `fp` + `tool_s` * + *`fp` = `fp` + . Reply to the user briefly. * + *`reply` = > `model`.运行 提示=`fp` * + *`out` = > json.set map=`out` key=tool value=`tool_name` * + *`out` = > json.set map=`out` key=tool_result value=`tool_s` * + *`out` = > json.set map=`out` key=result value=`reply` * 2. * - *`_` = 1* + *`out` = > json.set map=`out` key=result value=`reply` * -*`as_turn` = > parse text={"role":"assistant"} * -*`as_turn` = > map_set map=`as_turn` key=content value=`reply` * -> host_agent_history_append id=`id` item=`as_turn` -**`reply`** +*`as_turn` = > json.parse text={"role":"assistant"} * +*`as_turn` = > json.set map=`as_turn` key=content value=`reply` * +> agent_history_append id=`id` item=`as_turn` +**`out`** + +## 多步 + + `目标` + + `工作簿目录` + +多步工作簿(D2)— 尚未实现。 + +*`_` = `工作簿目录`* +*`msg` = plan (multi-step workbook) is not implemented yet; goal was: * +**`msg` + `目标`** diff --git a/include/marqdo_abi.h b/include/marqdo_abi.h index 95b4f6b..c61eec5 100644 --- a/include/marqdo_abi.h +++ b/include/marqdo_abi.h @@ -1,7 +1,10 @@ -/* Marqdo plugin ABI v1 — C contract (source of truth). +/* Marqdo plugin ABI v2 — C contract (source of truth). * * Plugins are optional shared libraries (.dll / .so / .dylib), never linked * into the marqdo binary. Values cross the boundary as UTF-8 JSON. + * + * v1: register_fn, alloc, free + * v2: + host_query (allowlisted host introspection for plugins) */ #ifndef MARQDO_ABI_H #define MARQDO_ABI_H @@ -13,7 +16,8 @@ extern "C" { #endif -#define MARQDO_ABI_VERSION 1u +#define MARQDO_ABI_VERSION 2u +#define MARQDO_ABI_VERSION_MIN 1u /* Plugin function: args_json is a UTF-8 JSON object whose keys are param names. * On success: return 0, set *out_json to a heap string (host frees via free). @@ -22,6 +26,12 @@ extern "C" { */ typedef int (*MarqdoPluginFn)(const char *args_json, char **out_json, char **err_msg); +/* Host → plugin query (v2). `name` is an allowlisted query id. + * Same success/failure convention as MarqdoPluginFn. + */ +typedef int (*MarqdoHostQueryFn)(void *userdata, const char *name, const char *args_json, + char **out_json, char **err_msg); + typedef struct MarqdoHostApi { void *userdata; /* params: comma-separated param names in order, e.g. "a,b". May be "". */ @@ -29,6 +39,8 @@ typedef struct MarqdoHostApi { MarqdoPluginFn fn); void *(*alloc)(size_t n); void (*free)(void *p); + /* v2: NULL for hosts that only speak v1; required when plugin abi >= 2 */ + MarqdoHostQueryFn host_query; } MarqdoHostApi; /* Required exports from every plugin shared library. */ diff --git a/lib/foreign.mq.md b/lib/foreign.mq.md index 9a1f5a9..2963c79 100644 --- a/lib/foreign.mq.md +++ b/lib/foreign.mq.md @@ -11,14 +11,16 @@ description: Run bound code fences and inline sources via local interpreters ## run + `code` + + `stdin`=None -**> host_foreign_run code=`code`** +**> host_foreign_run code=`code` stdin=`stdin`** ## run_lang + `lang` + `source` + + `stdin`=None -**> host_foreign_run_lang lang=`lang` source=`source`** +**> host_foreign_run_lang lang=`lang` source=`source` stdin=`stdin`** ## langs diff --git a/lib/json.mq.md b/lib/json.mq.md index e6d410e..e68e3b9 100644 --- a/lib/json.mq.md +++ b/lib/json.mq.md @@ -10,8 +10,9 @@ description: JSON parse/stringify (shared EN/ZH import) ## stringify + `value` + + `indent`=None -**> host_json_stringify value=`value`** +**> host_json_stringify value=`value` indent=`indent`** ## get + `value` diff --git a/lib/math.mq.md b/lib/math.mq.md index e3fb91f..d27327c 100644 --- a/lib/math.mq.md +++ b/lib/math.mq.md @@ -176,25 +176,38 @@ description: High-school math — num, random, formula, plot ## solve + `formula` + `var` + + `min`=None + + `max`=None -**> host_solve formula=`formula` var=`var`** +**> host_solve formula=`formula` var=`var` min=`min` max=`max`** ## plot + `formula` + `var` + `min` + `max` + + `steps`=None + + `path`=None + + `derivative`=None + + `grid`=None -**> host_plot formula=`formula` var=`var` min=`min` max=`max`** +**> host_plot formula=`formula` var=`var` min=`min` max=`max` steps=`steps` path=`path` derivative=`derivative` grid=`grid`** ## plot_points + `xs` + `ys` + + `path`=None + + `grid`=None -**> host_plot_points xs=`xs` ys=`ys`** +**> host_plot_points xs=`xs` ys=`ys` path=`path` grid=`grid`** ## plot_conic + `kind` + `a` + + `b`=None + + `h`=None + + `k`=None + + `path`=None + + `grid`=None -**> host_plot_conic kind=`kind` a=`a`** +**> host_plot_conic kind=`kind` a=`a` b=`b` h=`h` k=`k` path=`path` grid=`grid`** diff --git a/lib/net.mq.md b/lib/net.mq.md index e1fa6b3..a7d0310 100644 --- a/lib/net.mq.md +++ b/lib/net.mq.md @@ -5,26 +5,32 @@ description: English HTTP(S) wrappers. Optional headers / content_type via host ## http_get + `url` + + `headers`=None HTTPS supported. Optional named arg `headers=` (map). -**> host_http_get url=`url`** +**> host_http_get url=`url` headers=`headers`** ## http_post + `url` + `body` + + `content_type`=None + + `headers`=None Default content type is JSON. Optional `content_type=` / `headers=` (map). -**> host_http_post url=`url` body=`body`** +**> host_http_post url=`url` body=`body` content_type=`content_type` headers=`headers`** ## http_request + `method` + `url` + + `body`=None + + `content_type`=None + + `headers`=None Optional `body=` / `content_type=` / `headers=`. -**> host_http_request method=`method` url=`url`** +**> host_http_request method=`method` url=`url` body=`body` content_type=`content_type` headers=`headers`** ## url_encode + `text` diff --git a/lib/plugin.mq.md b/lib/plugin.mq.md index b0bd0f1..40aa267 100644 --- a/lib/plugin.mq.md +++ b/lib/plugin.mq.md @@ -15,3 +15,10 @@ description: Load optional native ABI plugins (.dll / .so / .dylib) ## list **> host_plugin_list** + +## native_path + + `name` + +Resolve installed / local native plugin path (e.g. `agent`). + +**> host_ext_native_path name=`name`** diff --git a/lib/sys.mq.md b/lib/sys.mq.md index dd60ec7..18b0fdf 100644 --- a/lib/sys.mq.md +++ b/lib/sys.mq.md @@ -15,10 +15,11 @@ description: English system wrappers (load_dotenv accepts optional path via host **> host_env_set name=`name` value=`value`** ## load_dotenv + + `path`=None Load `.env` (optional named arg `path=`). Existing process env is not overridden. -**> host_dotenv_load** +**> host_dotenv_load path=`path`** ## args @@ -35,5 +36,6 @@ Load `.env` (optional named arg `path=`). Existing process env is not overridden ## exec + `cmd` + + `args`=None -**> host_exec cmd=`cmd`** +**> host_exec cmd=`cmd` args=`args`** diff --git a/lib/writeback.mq.md b/lib/writeback.mq.md index 446f5f2..c1e4ed8 100644 --- a/lib/writeback.mq.md +++ b/lib/writeback.mq.md @@ -6,27 +6,42 @@ description: Persist run output in .mq.md (Jupyter-style writeback) ## record + `value` + `at_end`=False + + `key`=None + + `line`=None -Write `value` to `` in the entry file. Default: insert or replace the block immediately below the call; `at_end=true` appends a single block at EOF. +Write `value` to `` in the entry file. Default: insert or replace the block immediately below the call; `at_end=true` replaces the unkeyed EOF block. With `key=` (e.g. `ok` / `error`), replace or create that **named** slot only — slots do not overwrite each other. Optional `line=` anchors the block under that source line (needed when writing from a subtask). -**> host_writeback_record value=`value` at_end=`at_end`** +**> host_writeback_record value=`value` at_end=`at_end` key=`key` line=`line`** ## get + `at_end`=False + + `key`=None + + `line`=None -Read persisted output for the current call site (adjacent block), or the EOF block when `at_end=true`. +Read persisted output for the current call site (adjacent unkeyed block), the unkeyed EOF block when `at_end=true`, or a named slot when `key=` is set. -**> host_writeback_get at_end=`at_end`** +**> host_writeback_get at_end=`at_end` key=`key` line=`line`** ## clear + `at_end`=False + + `key`=None + + `line`=None -Remove the adjacent or EOF output block. +Remove the adjacent, EOF, or named output block. -**> host_writeback_clear at_end=`at_end`** +**> host_writeback_clear at_end=`at_end` key=`key` line=`line`** + +## ensure + + `key` + + `placeholder`=pending + + `line`=None + +Create a named slot with `placeholder` if missing. Never overwrites an existing slot body. + +**> host_writeback_ensure key=`key` placeholder=`placeholder` line=`line`** ## list -List all output blocks in the entry file. +List all output blocks in the entry file (includes `key` when named). **> host_writeback_list** diff --git a/lib/外联.mq.md b/lib/外联.mq.md index fd1ac5e..c039f98 100644 --- a/lib/外联.mq.md +++ b/lib/外联.mq.md @@ -11,14 +11,16 @@ description: 通过本机解释器运行绑定的代码围栏与内联源码 ## 运行 + `代码` + + `标准输入`=None -**> host_foreign_run code=`代码`** +**> host_foreign_run code=`代码` stdin=`标准输入`** ## 按语言运行 + `语言` + `源码` + + `标准输入`=None -**> host_foreign_run_lang lang=`语言` source=`源码`** +**> host_foreign_run_lang lang=`语言` source=`源码` stdin=`标准输入`** ## 语言表 diff --git a/lib/插件.mq.md b/lib/插件.mq.md index d7a5695..9b74ab8 100644 --- a/lib/插件.mq.md +++ b/lib/插件.mq.md @@ -15,3 +15,10 @@ description: 加载可选原生 ABI 插件(.dll / .so / .dylib) ## 列出 **> host_plugin_list** + +## 原生路径 + + `名` + +解析已安装或本地原生插件路径(如 `agent`)。 + +**> host_ext_native_path name=`名`** diff --git a/lib/数学.mq.md b/lib/数学.mq.md index 979f587..fd5b477 100644 --- a/lib/数学.mq.md +++ b/lib/数学.mq.md @@ -176,25 +176,38 @@ description: 高中数学 — 数值、随机、公式、作图 ## 求解 + `formula` + `var` + + `min`=None + + `max`=None -**> host_solve formula=`formula` var=`var`** +**> host_solve formula=`formula` var=`var` min=`min` max=`max`** ## 绘图 + `formula` + `var` + `min` + `max` + + `steps`=None + + `path`=None + + `derivative`=None + + `grid`=None -**> host_plot formula=`formula` var=`var` min=`min` max=`max`** +**> host_plot formula=`formula` var=`var` min=`min` max=`max` steps=`steps` path=`path` derivative=`derivative` grid=`grid`** ## 绘点列 + `xs` + `ys` + + `path`=None + + `grid`=None -**> host_plot_points xs=`xs` ys=`ys`** +**> host_plot_points xs=`xs` ys=`ys` path=`path` grid=`grid`** ## 绘圆锥 + `kind` + `a` + + `b`=None + + `h`=None + + `k`=None + + `path`=None + + `grid`=None -**> host_plot_conic kind=`kind` a=`a`** +**> host_plot_conic kind=`kind` a=`a` b=`b` h=`h` k=`k` path=`path` grid=`grid`** diff --git a/lib/系统.mq.md b/lib/系统.mq.md index 2ba7a41..a69b729 100644 --- a/lib/系统.mq.md +++ b/lib/系统.mq.md @@ -15,10 +15,11 @@ description: 中文系统包装(加载环境 可选 路径=) **> host_env_set name=`名` value=`值`** ## 加载环境 + + `路径`=None 加载 `.env`(可选具名实参 `路径=`)。不覆盖已有进程环境变量。 -**> host_dotenv_load** +**> host_dotenv_load path=`路径`** ## 参数表 @@ -35,5 +36,6 @@ description: 中文系统包装(加载环境 可选 路径=) ## 执行 + `命令` + + `参数`=None -**> host_exec cmd=`命令`** +**> host_exec cmd=`命令` args=`参数`** diff --git a/lib/网络.mq.md b/lib/网络.mq.md index b501a95..ca059d2 100644 --- a/lib/网络.mq.md +++ b/lib/网络.mq.md @@ -5,26 +5,32 @@ description: 中文 HTTP(S) 包装。可选 headers / content_type 经宿主别 ## 获取 + `地址` + + `headers`=None 支持 HTTPS。可选具名实参 `headers=`(映射)。 -**> host_http_get url=`地址`** +**> host_http_get url=`地址` headers=`headers`** ## 提交 + `地址` + `内容` + + `content_type`=None + + `headers`=None 默认 Content-Type 为 JSON。可选 `content_type=` / `headers=`。 -**> host_http_post url=`地址` body=`内容`** +**> host_http_post url=`地址` body=`内容` content_type=`content_type` headers=`headers`** ## 请求 + `方法` + `地址` + + `body`=None + + `content_type`=None + + `headers`=None 可选 `body=` / `content_type=` / `headers=`。 -**> host_http_request method=`方法` url=`地址`** +**> host_http_request method=`方法` url=`地址` body=`body` content_type=`content_type` headers=`headers`** ## 编码地址 + `内容` diff --git a/lib/自写回.mq.md b/lib/自写回.mq.md index 039f4ae..f357194 100644 --- a/lib/自写回.mq.md +++ b/lib/自写回.mq.md @@ -6,24 +6,39 @@ description: 将运行结果写回 .mq.md(Jupyter 式自写回) ## 写回 + `值` + `末尾`=False + + `键`=None + + `行`=None -在入口文件中写入 ``。默认在调用行下方插入或替换;`末尾=true` 时在文件末尾保留单块。 +在入口文件中写入 ``。默认在调用行下方插入或替换;`末尾=true` 时替换无键末尾块。带 `键=`(如 `ok` / `error` / `成功` / `失败`)时只更新该命名槽,互不覆盖。可选 `行=` 锚定到指定源码行(子任务写回时需要)。 -**> host_writeback_record value=`值` at_end=`末尾`** +**> host_writeback_record value=`值` at_end=`末尾` key=`键` line=`行`** ## 取 + `末尾`=False + + `键`=None + + `行`=None -读取当前调用处紧邻块,或 `末尾=true` 时读取文件末尾块。 +读取当前调用处紧邻无键块、无键末尾块,或命名槽。 -**> host_writeback_get at_end=`末尾`** +**> host_writeback_get at_end=`末尾` key=`键` line=`行`** ## 清除 + `末尾`=False + + `键`=None + + `行`=None -删除紧邻块或末尾块。 +删除紧邻块、末尾块或命名槽。 -**> host_writeback_clear at_end=`末尾`** +**> host_writeback_clear at_end=`末尾` key=`键` line=`行`** + +## 确保 + + `键` + + `占位`=pending + + `行`=None + +若命名槽不存在则创建并写入占位;已存在则不改动。 + +**> host_writeback_ensure key=`键` placeholder=`占位` line=`行`** ## 列出 diff --git a/man-test/lib/math.mq.md b/man-test/lib/math.mq.md index e81b3c7..d692400 100644 --- a/man-test/lib/math.mq.md +++ b/man-test/lib/math.mq.md @@ -20,14 +20,14 @@ $$ > print text=`ty` -*`df` = > diff formula=`f` var=x * +*`df` = > math.diff formula=`f` var=x * > print text=`df` -*`roots` = > solve formula=`f` var=x * +*`roots` = > math.solve formula=`f` var=x * > print text=`roots` -*`y` = > eval formula=`f` var=x value=3 * +*`y` = > math.eval formula=`f` var=x value=3 * > print text=`y` \ No newline at end of file diff --git a/man-test/lib/writeback.mq.md b/man-test/lib/writeback.mq.md index 9722d7b..e62c901 100644 --- a/man-test/lib/writeback.mq.md +++ b/man-test/lib/writeback.mq.md @@ -10,9 +10,9 @@ description: AI禁止更改 *`name`=>input "你叫什么名字?\n"* -> record `name` +> writeback.record `name` @@ -26,3 +26,4 @@ description: AI禁止更改 + diff --git a/plugins/agent/Cargo.toml b/plugins/agent/Cargo.toml index 365ee40..858f371 100644 --- a/plugins/agent/Cargo.toml +++ b/plugins/agent/Cargo.toml @@ -3,7 +3,7 @@ name = "marqdo_plugin_agent" version = "0.1.0" edition = "2021" license = "Apache-2.0" -description = "Marqdo agent layout plugin (ABI v1 cdylib)" +description = "Marqdo agent plugin (ABI v2 cdylib)" publish = false [lib] diff --git a/plugins/agent/src/lib.rs b/plugins/agent/src/lib.rs index 430b192..47b1f92 100644 --- a/plugins/agent/src/lib.rs +++ b/plugins/agent/src/lib.rs @@ -1,11 +1,13 @@ -//! Agent layout plugin (C ABI v1): find_root, ensure_layout, probe, scaffold. +//! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query. +use std::collections::HashMap; use std::ffi::{CStr, CString}; use std::os::raw::{c_char, c_int, c_void}; use std::path::{Component, Path, PathBuf}; use std::ptr; +use std::sync::{LazyLock, Mutex}; -const ABI_VERSION: u32 = 1; +const ABI_VERSION: u32 = 2; const DEFAULT_MARKERS: &str = "agents,runbooks,marqdo.agent.json"; const LAYOUT_DIRS: &[&str] = &["agents", "runbooks", "templates", "reports"]; @@ -15,6 +17,14 @@ type PluginFn = unsafe extern "C" fn( err_msg: *mut *mut c_char, ) -> c_int; +type HostQueryFn = unsafe extern "C" fn( + userdata: *mut c_void, + name: *const c_char, + 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, @@ -28,10 +38,17 @@ pub struct MarqdoHostApi { >, pub alloc: Option *mut c_void>, pub free: Option, + pub host_query: Option, } static mut HOST_FREE: Option = None; static mut HOST_ALLOC: Option *mut c_void> = None; +static mut HOST_QUERY: Option = None; +static mut HOST_USERDATA: *mut c_void = ptr::null_mut(); + +static HISTORIES: LazyLock>>> = + LazyLock::new(|| Mutex::new(HashMap::new())); +static AGENT_SEQ: LazyLock> = LazyLock::new(|| Mutex::new(0)); unsafe fn host_strdup(s: &str) -> *mut c_char { let alloc = HOST_ALLOC.expect("host alloc"); @@ -527,6 +544,307 @@ fn register(host: &MarqdoHostApi, name: &str, params: &str, fn_ptr: PluginFn) -> unsafe { register(host.userdata, n.as_ptr(), p.as_ptr(), fn_ptr) } } +fn host_query_json(name: &str) -> Result { + let query = unsafe { HOST_QUERY }.ok_or_else(|| "host_query not available".to_string())?; + let userdata = unsafe { HOST_USERDATA }; + let c_name = CString::new(name).map_err(|e| e.to_string())?; + let c_args = CString::new("{}").unwrap(); + let mut out_ptr: *mut c_char = ptr::null_mut(); + let mut err_ptr: *mut c_char = ptr::null_mut(); + let rc = unsafe { + query( + userdata, + c_name.as_ptr(), + c_args.as_ptr(), + &mut out_ptr, + &mut err_ptr, + ) + }; + let err = take_host_string(err_ptr); + let out = take_host_string(out_ptr); + if rc != 0 { + return Err(err.unwrap_or_else(|| format!("host_query `{name}` failed"))); + } + let out = out.unwrap_or_else(|| "null".into()); + serde_json::from_str(&out).map_err(|e| format!("host_query `{name}` bad JSON: {e}")) +} + +fn take_host_string(p: *mut c_char) -> Option { + if p.is_null() { + return None; + } + let s = unsafe { CStr::from_ptr(p) } + .to_str() + .ok() + .map(|s| s.to_string()); + unsafe { + if let Some(free) = HOST_FREE { + free(p as *mut c_void); + } + } + s +} + +unsafe extern "C" fn agent_alloc( + _args_json: *const c_char, + out_json: *mut *mut c_char, + err_msg: *mut *mut c_char, +) -> c_int { + let mut seq = match AGENT_SEQ.lock() { + Ok(g) => g, + Err(_) => { + set_err(err_msg, "agent_alloc: lock poisoned"); + return 1; + } + }; + *seq = seq.wrapping_add(1); + let id = format!("agent-{seq}"); + drop(seq); + if let Ok(mut map) = HISTORIES.lock() { + map.insert(id.clone(), Vec::new()); + } + let out = serde_json::Value::String(id).to_string(); + set_out(out_json, &out); + 0 +} + +unsafe extern "C" fn agent_history_get( + 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_history_get: {e}")); + return 1; + } + }; + let id = match arg_str(&v, "id") { + Ok(s) => s.to_string(), + Err(e) => { + set_err(err_msg, &format!("agent_history_get: {e}")); + return 1; + } + }; + let list = HISTORIES + .lock() + .map(|m| m.get(&id).cloned().unwrap_or_default()) + .unwrap_or_default(); + set_out(out_json, &serde_json::Value::Array(list).to_string()); + 0 +} + +unsafe extern "C" fn agent_history_clear( + 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_history_clear: {e}")); + return 1; + } + }; + let id = match arg_str(&v, "id") { + Ok(s) => s.to_string(), + Err(e) => { + set_err(err_msg, &format!("agent_history_clear: {e}")); + return 1; + } + }; + if let Ok(mut map) = HISTORIES.lock() { + map.insert(id, Vec::new()); + } + set_out(out_json, "null"); + 0 +} + +unsafe extern "C" fn agent_history_append( + 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_history_append: {e}")); + return 1; + } + }; + let id = match arg_str(&v, "id") { + Ok(s) => s.to_string(), + Err(e) => { + set_err(err_msg, &format!("agent_history_append: {e}")); + return 1; + } + }; + let item = match v.get("item") { + Some(i) => i.clone(), + None => { + set_err(err_msg, "agent_history_append: missing item"); + return 1; + } + }; + let list = match HISTORIES.lock() { + Ok(mut map) => { + let list = map.entry(id).or_default(); + list.push(item); + list.clone() + } + Err(_) => { + set_err(err_msg, "agent_history_append: lock poisoned"); + return 1; + } + }; + set_out(out_json, &serde_json::Value::Array(list).to_string()); + 0 +} + +unsafe extern "C" fn agent_module_source( + _args_json: *const c_char, + out_json: *mut *mut c_char, + err_msg: *mut *mut c_char, +) -> c_int { + match host_query_json("module_source") { + Ok(j) => { + set_out(out_json, &j.to_string()); + 0 + } + Err(e) => { + set_err(err_msg, &e); + 1 + } + } +} + +unsafe extern "C" fn agent_call_site( + _args_json: *const c_char, + out_json: *mut *mut c_char, + err_msg: *mut *mut c_char, +) -> c_int { + match host_query_json("call_site") { + Ok(j) => { + set_out(out_json, &j.to_string()); + 0 + } + Err(e) => { + set_err(err_msg, &e); + 1 + } + } +} + +unsafe extern "C" fn agent_marqdo_skill( + _args_json: *const c_char, + out_json: *mut *mut c_char, + err_msg: *mut *mut c_char, +) -> c_int { + match host_query_json("marqdo_skill") { + Ok(j) => { + set_out(out_json, &j.to_string()); + 0 + } + Err(e) => { + set_err(err_msg, &e); + 1 + } + } +} + +fn tool_names(tools: &serde_json::Value) -> Vec { + let mut out = Vec::new(); + let rows = match tools { + serde_json::Value::Array(a) => a.as_slice(), + serde_json::Value::String(s) => { + if let Ok(serde_json::Value::Array(a)) = serde_json::from_str(s) { + return tool_names(&serde_json::Value::Array(a)); + } + return out; + } + _ => return out, + }; + for row in rows { + match row { + serde_json::Value::String(s) if !s.is_empty() => out.push(s.clone()), + serde_json::Value::Object(m) => { + for key in ["工具", "tools", "name"] { + if let Some(serde_json::Value::String(s)) = m.get(key) { + if !s.is_empty() { + out.push(s.clone()); + break; + } + } + } + } + _ => {} + } + } + out +} + +unsafe extern "C" fn agent_format_tools( + 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_format_tools: {e}")); + return 1; + } + }; + let tools = match v.get("tools") { + Some(t) => t, + None => { + set_err(err_msg, "agent_format_tools: missing tools"); + return 1; + } + }; + let mut text = + String::from("Available tools (invoke via CALL: or 调用:; runs as subtask):\n"); + for name in tool_names(tools) { + text.push_str("- "); + text.push_str(&name); + text.push('\n'); + } + set_out(out_json, &serde_json::Value::String(text).to_string()); + 0 +} + +unsafe extern "C" fn agent_tool_allowed( + 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_tool_allowed: {e}")); + return 1; + } + }; + let tools = match v.get("tools") { + Some(t) => t, + None => { + set_err(err_msg, "agent_tool_allowed: missing tools"); + return 1; + } + }; + let name = match arg_str(&v, "name") { + Ok(s) => s, + Err(_) => { + set_out(out_json, "false"); + return 0; + } + }; + let ok = tool_names(tools).iter().any(|n| n == name); + set_out(out_json, if ok { "true" } else { "false" }); + 0 +} + #[no_mangle] pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 { ABI_VERSION @@ -540,6 +858,11 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int let host = &*host; HOST_ALLOC = host.alloc; HOST_FREE = host.free; + HOST_QUERY = host.host_query; + HOST_USERDATA = host.userdata; + if host.host_query.is_none() { + return 1; + } if register(host, "agent_find_root", "start,markers", agent_find_root) != 0 { return 1; } @@ -564,6 +887,33 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int if register(host, "agent_bump_load", "member,delta", agent_bump_load) != 0 { return 1; } + if register(host, "agent_alloc", "", agent_alloc) != 0 { + return 1; + } + if register(host, "agent_history_get", "id", agent_history_get) != 0 { + return 1; + } + if register(host, "agent_history_clear", "id", agent_history_clear) != 0 { + return 1; + } + if register(host, "agent_history_append", "id,item", agent_history_append) != 0 { + return 1; + } + if register(host, "agent_module_source", "", agent_module_source) != 0 { + return 1; + } + if register(host, "agent_call_site", "", agent_call_site) != 0 { + return 1; + } + if register(host, "agent_marqdo_skill", "", agent_marqdo_skill) != 0 { + return 1; + } + if register(host, "agent_format_tools", "tools", agent_format_tools) != 0 { + return 1; + } + if register(host, "agent_tool_allowed", "tools,name", agent_tool_allowed) != 0 { + return 1; + } 0 } @@ -571,4 +921,12 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int pub unsafe extern "C" fn marqdo_plugin_shutdown() { HOST_ALLOC = None; HOST_FREE = None; + HOST_QUERY = None; + HOST_USERDATA = ptr::null_mut(); + if let Ok(mut map) = HISTORIES.lock() { + map.clear(); + } + if let Ok(mut seq) = AGENT_SEQ.lock() { + *seq = 0; + } } diff --git a/public/00-welcome.mq.md b/public/00-welcome.mq.md index 1a3a621..f45d78a 100644 --- a/public/00-welcome.mq.md +++ b/public/00-welcome.mq.md @@ -41,7 +41,7 @@ $$ Then plot it: -*`_svg` = > plot formula=`f` var=x min=-3 max=3 * +*`_svg` = > math.plot formula=`f` var=x min=-3 max=3 * The foreign library lets you call external code, for example: diff --git a/public/00-欢迎.mq.md b/public/00-欢迎.mq.md index d7ed997..808350b 100644 --- a/public/00-欢迎.mq.md +++ b/public/00-欢迎.mq.md @@ -41,7 +41,7 @@ $$ 之后让我们画个图像吧! -*`_svg` = > 绘图 formula=`f` var=x min=-3 max=3 * +*`_svg` = > 数学.绘图 formula=`f` var=x min=-3 max=3 * 外联库则允许你调用外部代码,例如: diff --git a/public/stdlib/foreign.mq.md b/public/stdlib/foreign.mq.md index 46f9814..04fe8cf 100644 --- a/public/stdlib/foreign.mq.md +++ b/public/stdlib/foreign.mq.md @@ -15,6 +15,6 @@ print("hello-from-python") Default command is python (Windows) or python3 (Unix). Override with set_cmd, env MARQDO_FOREIGN_PYTHON, or the command box in live view. Failures ask you to check that configuration. -*`out` = > run code=`hi` * +*`out` = > foreign.run code=`hi` * > print text=`out` diff --git a/public/stdlib/fs.mq.md b/public/stdlib/fs.mq.md index 89fa3ef..dac8431 100644 --- a/public/stdlib/fs.mq.md +++ b/public/stdlib/fs.mq.md @@ -10,7 +10,7 @@ Import lib/fs.mq.md. Functions: read_text, write_text, append_text, exists, list Bare path words must not contain a slash character (parsed as division). Prefer a same-folder name or a variable. -*`ok` = > exists path=demo.txt * +*`ok` = > fs.exists path=demo.txt * 1. `ok` > print text=demo-present diff --git a/public/stdlib/json.mq.md b/public/stdlib/json.mq.md index c44abd8..37378a9 100644 --- a/public/stdlib/json.mq.md +++ b/public/stdlib/json.mq.md @@ -8,12 +8,12 @@ description: Shared EN/ZH path; parse and stringify 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={} * +*`obj` = > json.parse text={} * *`ty` = > type `obj` * > print text=`ty` -*`out` = > stringify value=`obj` * +*`out` = > json.stringify value=`obj` * > print text=`out` diff --git a/public/stdlib/math.mq.md b/public/stdlib/math.mq.md index 135a687..b24a591 100644 --- a/public/stdlib/math.mq.md +++ b/public/stdlib/math.mq.md @@ -25,14 +25,14 @@ diff / simplify / expand / partial subs return formula values so you can chain ( > print text=`ty` -*`df` = > diff formula=`f` var=x * +*`df` = > math.diff formula=`f` var=x * > print text=`df` -*`roots` = > solve formula=`f` var=x * +*`roots` = > math.solve formula=`f` var=x * > print text=`roots` -*`_svg` = > plot formula=`f` var=x min=-3 max=3 * +*`_svg` = > math.plot formula=`f` var=x min=-3 max=3 * > print text=plot-ok diff --git a/public/stdlib/net.mq.md b/public/stdlib/net.mq.md index d8a934e..adc6882 100644 --- a/public/stdlib/net.mq.md +++ b/public/stdlib/net.mq.md @@ -8,6 +8,6 @@ description: Minimal HTTP(S) client and URL encode Import lib/net.mq.md. Functions: http_get(url), http_post(url, body), http_request(method, url), url_encode(text). HTTPS and optional headers= map are supported. Default post content-type is JSON. -*`e` = > url_encode text=hello world * +*`e` = > net.url_encode text=hello world * > print text=`e` diff --git a/public/stdlib/table.mq.md b/public/stdlib/table.mq.md index 4cb981d..546c16e 100644 --- a/public/stdlib/table.mq.md +++ b/public/stdlib/table.mq.md @@ -15,10 +15,10 @@ Import lib/table.mq.md. Functions: rows(xs), row_at(xs, i). Single-column Markdo | a | | b | -*`n` = > rows xs=`xs`* +*`n` = > table.rows xs=`xs`* > print text=`n` -*`r` = > row_at xs=`xs` i=0* +*`r` = > table.row_at xs=`xs` i=0* > print text=`r` diff --git a/public/stdlib/text.mq.md b/public/stdlib/text.mq.md index 384707c..c408116 100644 --- a/public/stdlib/text.mq.md +++ b/public/stdlib/text.mq.md @@ -8,12 +8,12 @@ description: Trim, split, join wrappers Import lib/text.mq.md. Functions: str_trim(s), str_split(s, sep), str_join(xs, sep). -*`t` = > str_trim s= marqdo * +*`t` = > text.str_trim s= marqdo * > print text=`t` -*`parts` = > str_split s=a,b,c sep=,* +*`parts` = > text.str_split s=a,b,c sep=,* -*`j` = > str_join xs=`parts` sep=-* +*`j` = > text.str_join xs=`parts` sep=-* > print text=`j` diff --git a/public/stdlib/time.mq.md b/public/stdlib/time.mq.md index 682407b..efc5c07 100644 --- a/public/stdlib/time.mq.md +++ b/public/stdlib/time.mq.md @@ -8,12 +8,12 @@ description: Unix time, format, parse, sleep Import lib/time.mq.md. Functions: now_unix, now_ms, format(unix, pattern), parse(text, pattern), sleep_ms(ms). Patterns use strftime. -*`s` = > format unix=0 pattern=%Y-%m-%d * +*`s` = > time.format unix=0 pattern=%Y-%m-%d * > print text=`s` -*`u` = > parse text=1970-01-01 00:00:00 pattern=%Y-%m-%d %H:%M:%S * +*`u` = > time.parse text=1970-01-01 00:00:00 pattern=%Y-%m-%d %H:%M:%S * > print text=`u` -> sleep_ms ms=0 +> time.sleep_ms ms=0 diff --git a/public/stdlib/外联.mq.md b/public/stdlib/外联.mq.md index 05c38b3..30025cc 100644 --- a/public/stdlib/外联.mq.md +++ b/public/stdlib/外联.mq.md @@ -15,6 +15,6 @@ print("hello-from-python") 默认命令可用 设置命令 或 MARQDO_FOREIGN_PYTHON 覆盖;live view 里可改命令框再点 Run。 -*`out` = > 运行 代码=`hi` * +*`out` = > 外联.运行 代码=`hi` * > print text=`out` diff --git a/public/stdlib/数学.mq.md b/public/stdlib/数学.mq.md index b18367f..b2a262c 100644 --- a/public/stdlib/数学.mq.md +++ b/public/stdlib/数学.mq.md @@ -25,14 +25,14 @@ $$ > print text=`ty` -*`df` = > 求导 formula=`f` var=x * +*`df` = > 数学.求导 formula=`f` var=x * > print text=`df` -*`roots` = > 求解 formula=`f` var=x * +*`roots` = > 数学.求解 formula=`f` var=x * > print text=`roots` -*`_svg` = > 绘图 formula=`f` var=x min=-3 max=3 * +*`_svg` = > 数学.绘图 formula=`f` var=x min=-3 max=3 * > print text=plot-ok diff --git a/public/stdlib/文本.mq.md b/public/stdlib/文本.mq.md index 14e0f53..86e944a 100644 --- a/public/stdlib/文本.mq.md +++ b/public/stdlib/文本.mq.md @@ -8,12 +8,12 @@ description: 去空白、拆分、拼接 导入 lib/文本.mq.md。函数:去空白(s)、拆分(s, sep)、拼接(xs, sep)。 -*`t` = > 去空白 s= marqdo * +*`t` = > 文本.去空白 s= marqdo * > 打印 内容=`t` -*`parts` = > 拆分 s=甲,乙,丙 sep=,* +*`parts` = > 文本.拆分 s=甲,乙,丙 sep=,* -*`j` = > 拼接 xs=`parts` sep=-* +*`j` = > 文本.拼接 xs=`parts` sep=-* > 打印 内容=`j` diff --git a/public/stdlib/时间.mq.md b/public/stdlib/时间.mq.md index 100fb0c..63db5d6 100644 --- a/public/stdlib/时间.mq.md +++ b/public/stdlib/时间.mq.md @@ -8,12 +8,12 @@ description: Unix 时间、格式化、解析、睡眠 导入 lib/时间.mq.md。函数:此刻秒、此刻毫秒、格式化(秒, 格式)、解析时间(内容, 格式)、睡眠毫秒(毫秒)。格式为 strftime。 -*`s` = > 格式化 秒=0 格式=%Y-%m-%d * +*`s` = > 时间.格式化 秒=0 格式=%Y-%m-%d * > 打印 内容=`s` -*`u` = > 解析时间 内容=1970-01-01 00:00:00 格式=%Y-%m-%d %H:%M:%S * +*`u` = > 时间.解析时间 内容=1970-01-01 00:00:00 格式=%Y-%m-%d %H:%M:%S * > 打印 内容=`u` -> 睡眠毫秒 毫秒=0 +> 时间.睡眠毫秒 毫秒=0 diff --git a/public/stdlib/网络.mq.md b/public/stdlib/网络.mq.md index 63e3fd6..f2f3581 100644 --- a/public/stdlib/网络.mq.md +++ b/public/stdlib/网络.mq.md @@ -8,6 +8,6 @@ description: HTTP(S) 与地址编码 导入 lib/网络.mq.md。函数:获取(地址)、提交(地址, 内容;可选 content_type / headers)、编码地址(内容)。支持 HTTP 与 HTTPS(ureq)。 -*`e` = > 编码地址 内容=你好 * +*`e` = > 网络.编码地址 内容=你好 * > 打印 内容=`e` diff --git a/public/stdlib/表.mq.md b/public/stdlib/表.mq.md index ee67637..6e14fb9 100644 --- a/public/stdlib/表.mq.md +++ b/public/stdlib/表.mq.md @@ -15,10 +15,10 @@ description: 行数与取行 | 甲 | | 乙 | -*`n` = > 行数 xs=`xs`* +*`n` = > 表.行数 xs=`xs`* > 打印 内容=`n` -*`r` = > 取行 xs=`xs` i=0* +*`r` = > 表.取行 xs=`xs` i=0* > 打印 内容=`r` diff --git a/public/structure/import/main.mq.md b/public/structure/import/main.mq.md index 836d0c8..c04063d 100644 --- a/public/structure/import/main.mq.md +++ b/public/structure/import/main.mq.md @@ -10,8 +10,8 @@ In the YAML header, `> utils.mq.md` imports a sibling module. Bind a return value, print it, then call greet: -*`y` = > add_one n=41* +*`y` = > utils.add_one n=41* > print text=`y` -> greet who=Marqdo +> utils.greet who=Marqdo diff --git a/public/structure/import/主.mq.md b/public/structure/import/主.mq.md index 87fd7dd..cc19e1e 100644 --- a/public/structure/import/主.mq.md +++ b/public/structure/import/主.mq.md @@ -10,8 +10,8 @@ description: frontmatter 中 `> 文件.mq.md` 合并模块 绑定返回值、打印,再调用问候: -*`y` = > 加一 n=41* +*`y` = > 工具.加一 n=41* > 打印 内容=`y` -> 问候 谁=Marqdo +> 工具.问候 谁=Marqdo diff --git a/src/aliases.rs b/src/aliases.rs index 7509eb5..b9e0ec6 100644 --- a/src/aliases.rs +++ b/src/aliases.rs @@ -53,6 +53,30 @@ pub fn canonical_param(builtin: &str, param: &str) -> String { ("at", "value" | "值") => "value".into(), ("at", "index" | "下标") => "index".into(), ("call_fn", "name" | "名") => "name".into(), + ( + "host_writeback_record" | "host_writeback_get" | "host_writeback_clear", + "key" | "键", + ) => "key".into(), + ("host_writeback_ensure", "key" | "键") => "key".into(), + ( + "host_writeback_ensure", + "placeholder" | "占位", + ) => "placeholder".into(), + ( + "host_writeback_record" | "host_writeback_get" | "host_writeback_clear", + "at_end" | "末尾", + ) => "at_end".into(), + ( + "host_writeback_record" + | "host_writeback_get" + | "host_writeback_clear" + | "host_writeback_ensure", + "line" | "行", + ) => "line".into(), + ( + "host_writeback_record", + "value" | "值", + ) => "value".into(), ( "host_plot" | "host_plot_points" | "host_plot_conic", "grid" | "网格", @@ -60,6 +84,24 @@ pub fn canonical_param(builtin: &str, param: &str) -> String { ("host_plot" | "host_plot_points" | "host_plot_conic", "path" | "路径") => { "path".into() } + ("host_dotenv_load" | "load_dotenv", "path" | "路径") => "path".into(), + ("host_exec" | "exec", "cmd" | "命令") => "cmd".into(), + ("host_exec" | "exec", "args" | "参数") => "args".into(), + ( + "host_http_get" | "http_get" | "host_http_post" | "http_post" | "host_http_request" + | "http_request", + "headers" | "头", + ) => "headers".into(), + ( + "host_http_post" | "http_post" | "host_http_request" | "http_request", + "content_type" | "类型", + ) => "content_type".into(), + ("host_http_get" | "http_get" | "host_http_post" | "http_post" | "host_http_request" + | "http_request", "url" | "地址") => "url".into(), + ("host_http_post" | "http_post" | "host_http_request" | "http_request", "body" | "内容") => { + "body".into() + } + ("host_json_stringify" | "stringify", "indent" | "缩进") => "indent".into(), ("host_plot", "steps" | "步数") => "steps".into(), ("host_plot", "derivative" | "导数") => "derivative".into(), ("host_foreign_run", "code" | "代码") => "code".into(), @@ -67,6 +109,7 @@ pub fn canonical_param(builtin: &str, param: &str) -> String { ("host_foreign_set_cmd" | "host_foreign_run_lang", "lang" | "语言") => "lang".into(), ("host_foreign_set_cmd", "cmd" | "命令") => "cmd".into(), ("host_foreign_run_lang", "source" | "源码") => "source".into(), + ("host_ext_native_path", "name" | "名") => "name".into(), _ => param.to_string(), } } diff --git a/src/ast.rs b/src/ast.rs index c512ff4..be3d527 100644 --- a/src/ast.rs +++ b/src/ast.rs @@ -1,13 +1,43 @@ //! Marqdo AST (Phase I). +use std::collections::HashMap; + use crate::diagnostics::Span; use crate::formula::Expr as FormulaExpr; use crate::value::CodeBlock; +/// Frontmatter import: path + library bind name (see `doc/design/module-namespace.md`). +#[derive(Debug, Clone)] +pub struct Import { + pub path: String, + pub bind: String, +} + +/// Frontmatter `use` / `使用`: bind a short name to a library path (`time.format`). +#[derive(Debug, Clone)] +pub struct Use { + pub path: Vec, + pub bind: String, +} + #[derive(Debug, Clone)] pub struct Module { - pub imports: Vec, + pub imports: Vec, + pub uses: Vec, pub functions: Vec, + /// Populated by the loader: bind name → imported module (not flattened). + pub import_modules: HashMap, +} + +impl Default for Module { + fn default() -> Self { + Self { + imports: Vec::new(), + uses: Vec::new(), + functions: Vec::new(), + import_modules: HashMap::new(), + } + } } #[derive(Debug, Clone)] @@ -78,6 +108,9 @@ pub struct BranchArm { #[derive(Debug, Clone)] pub struct CallExpr { pub callee: String, + /// Bare library path segments, e.g. `["time","parse"]` for `time.parse`. + /// Mutually exclusive with `receiver` (instance method). + pub path: Option>, /// When set, `` `recv`.callee `` method call; receiver is a variable name. pub receiver: Option, pub args: Vec, @@ -155,7 +188,12 @@ pub fn format_ast_dump(path: &str, module: &Module) -> String { let mut out = String::new(); out.push_str(&format!("=== marqdo: ast ({path}) ===\n")); if !module.imports.is_empty() { - out.push_str(&format!("(imports {:?})\n", module.imports)); + let specs: Vec = module + .imports + .iter() + .map(|i| format!("{} as {}", i.path, i.bind)) + .collect(); + out.push_str(&format!("(imports {:?})\n", specs)); } for fun in &module.functions { dump_fun(&mut out, fun, 0); diff --git a/src/bytecode/compile.rs b/src/bytecode/compile.rs index 069c877..f2afd77 100644 --- a/src/bytecode/compile.rs +++ b/src/bytecode/compile.rs @@ -19,13 +19,15 @@ struct FlatFun { body: Vec, children: Vec, span: Span, + /// Full path segments (`lib.member` / `lib.Type.method`) → flat index. + path_index: HashMap, usize>, + /// Short name from frontmatter `use` → path segments. + uses: HashMap>, } pub fn compile_module(path: Option<&Path>, module: &Module) -> Result { let mut flat = Vec::new(); - for fun in &module.functions { - collect_fun(fun, None, &mut flat); - } + let _exports = collect_module_tree(module, &mut flat); if flat.is_empty() { bail!("bytecode: no functions to compile"); } @@ -78,7 +80,55 @@ pub fn compile_module(path: Option<&Path>, module: &Module) -> Result { }) } -fn collect_fun(fun: &Function, parent: Option, flat: &mut Vec) -> usize { +/// Collect `module` and its imports into `flat`. +/// Returns relative export paths within this module (e.g. `["parse"]`, `["agent","step"]`). +fn collect_module_tree(module: &Module, flat: &mut Vec) -> HashMap, usize> { + let mut path_index = HashMap::new(); + for (bind, dep) in &module.import_modules { + let dep_exports = collect_module_tree(dep, flat); + for (rel, idx) in dep_exports { + let mut full = Vec::with_capacity(rel.len() + 1); + full.push(bind.clone()); + full.extend(rel); + path_index.insert(full, idx); + } + } + + let uses: HashMap> = module + .uses + .iter() + .map(|u| (u.bind.clone(), u.path.clone())) + .collect(); + + let mut exports = HashMap::new(); + for fun in &module.functions { + let id = collect_fun(fun, None, flat, &path_index, &uses); + export_tree(&mut exports, &[], id, flat); + } + exports +} + +fn export_tree( + out: &mut HashMap, usize>, + prefix: &[String], + id: usize, + flat: &[FlatFun], +) { + let mut p = prefix.to_vec(); + p.push(flat[id].name.clone()); + out.insert(p.clone(), id); + for &cid in &flat[id].children { + export_tree(out, &p, cid, flat); + } +} + +fn collect_fun( + fun: &Function, + parent: Option, + flat: &mut Vec, + path_index: &HashMap, usize>, + uses: &HashMap>, +) -> usize { let id = flat.len(); flat.push(FlatFun { name: fun.name.clone(), @@ -88,10 +138,12 @@ fn collect_fun(fun: &Function, parent: Option, flat: &mut Vec) - body: fun.body.clone(), children: Vec::new(), span: fun.span, + path_index: path_index.clone(), + uses: uses.clone(), }); let mut child_ids = Vec::new(); for child in &fun.children { - child_ids.push(collect_fun(child, Some(id), flat)); + child_ids.push(collect_fun(child, Some(id), flat, path_index, uses)); } flat[id].children = child_ids; id @@ -365,6 +417,12 @@ impl<'a> FnCompiler<'a> { fn compile_call(&mut self, call: &CallExpr, as_stmt: bool) -> Result<()> { let mut call = call.clone(); + if let Some(path) = &call.path { + return self.compile_path_call(path, &call, as_stmt); + } + if let Some(path) = self.flat[self.fn_id].uses.get(&call.callee).cloned() { + return self.compile_path_call(&path, &call, as_stmt); + } call.callee = crate::aliases::normalize_call_callee_and_args(&call.callee, &mut call.args); @@ -529,51 +587,76 @@ impl<'a> FnCompiler<'a> { } match self.resolve_call(&call.callee) { - Ok(fid) => { - let params = &self.flat[fid].params; - let mut named: HashMap = HashMap::new(); - let mut positionals = Vec::new(); - for a in &call.args { - match a { - Arg::Positional(e) => positionals.push(e), - Arg::Named { name, value } => { - named.insert(name.clone(), value); - } - } - } - let mut pos_i = 0; - for p in params { - if let Some(e) = named.get(&p.name) { - self.compile_expr(e)?; - } else if pos_i < positionals.len() { - self.compile_expr(positionals[pos_i])?; - pos_i += 1; - } else if let Some(def) = &p.default { - self.compile_expr(def)?; - } else { - return Err(self.err(format!("missing argument for parameter `{}`", p.name))); - } - } - if pos_i < positionals.len() { - return Err(self.err(format!( - "too many positional arguments ({} extra)", - positionals.len() - pos_i - ))); - } - self.emit(Op::Call(fid as u16, params.len() as u8)); - if self.flat[fid].parent.is_none() && self.flat[fid].level == 1 { - let ti = self.add_const(Value::Text(self.flat[fid].name.clone())); - self.emit(Op::TagInstance(ti)); - } - if as_stmt { - self.emit(Op::Pop); - } - Ok(()) - } + Ok(fid) => self.compile_user_call(fid, &call, as_stmt), Err(_) => self.compile_plugin_call(&call, as_stmt), } } + fn compile_path_call(&mut self, path: &[String], call: &CallExpr, as_stmt: bool) -> Result<()> { + let display = path.join("."); + if path.len() < 2 { + return Err(self.err(format!( + "library path `{display}`: need at least `lib.member`" + ))); + } + let fid = *self.flat[self.fn_id] + .path_index + .get(path) + .ok_or_else(|| self.err(format!("unknown `{display}`")))?; + if let Some(pid) = self.flat[fid].parent { + let parent = &self.flat[pid]; + if parent.level == 1 && parent.parent.is_none() && !(self.flat[fid].level == 1) { + return Err(self.err(format!( + "`{display}` is an instance method; call it as `var`.{}", + self.flat[fid].name + ))); + } + } + self.compile_user_call(fid, call, as_stmt) + } + + fn compile_user_call(&mut self, fid: usize, call: &CallExpr, as_stmt: bool) -> Result<()> { + let params = &self.flat[fid].params; + let mut named: HashMap = HashMap::new(); + let mut positionals = Vec::new(); + for a in &call.args { + match a { + Arg::Positional(e) => positionals.push(e), + Arg::Named { name, value } => { + named.insert(name.clone(), value); + } + } + } + let mut pos_i = 0; + for p in params { + if let Some(e) = named.get(&p.name) { + self.compile_expr(e)?; + } else if pos_i < positionals.len() { + self.compile_expr(positionals[pos_i])?; + pos_i += 1; + } else if let Some(def) = &p.default { + self.compile_expr(def)?; + } else { + return Err(self.err(format!("missing argument for parameter `{}`", p.name))); + } + } + if pos_i < positionals.len() { + return Err(self.err(format!( + "too many positional arguments ({} extra)", + positionals.len() - pos_i + ))); + } + self.emit(Op::Call(fid as u16, params.len() as u8)); + if self.flat[fid].parent.is_none() && self.flat[fid].level == 1 { + let ti = self.add_const(Value::Text(self.flat[fid].name.clone())); + self.emit(Op::TagInstance(ti)); + } + if as_stmt { + self.emit(Op::Pop); + } + Ok(()) + } + /// Unresolved callee → runtime plugin registry (or unknown-fn error). /// Named args: stack pairs (name, value)×N, argc = 2N, name const prefixed with `@`. /// Positional: stack values, argc = N, name const as-is. diff --git a/src/catalog.rs b/src/catalog.rs index 2c62b02..b38801d 100644 --- a/src/catalog.rs +++ b/src/catalog.rs @@ -156,9 +156,8 @@ fn extract_frontmatter_imports(source: &str) -> Vec { break; } if let Some(rest) = t.strip_prefix('>') { - let path = rest.trim(); - if path.ends_with(".mq.md") { - imports.push(path.to_string()); + if let Some(imp) = crate::parse::parse_import_spec(rest.trim()) { + imports.push(format!("{} as {}", imp.path, imp.bind)); } } } diff --git a/src/ext_cli.rs b/src/ext_cli.rs index 2d89537..3dff194 100644 --- a/src/ext_cli.rs +++ b/src/ext_cli.rs @@ -28,7 +28,7 @@ pub const CATALOG: &[ExtPackage] = &[ id: "agent", description: "Agent development framework (ext/ai/agent)", mq_files: &["ai/agent.mq.md", "ai/智能体.mq.md"], - native_crate: None, + native_crate: Some("marqdo_plugin_agent"), }, ]; @@ -151,11 +151,24 @@ fn find_source_file(name: &str) -> Result { fn find_native_plugin() -> Result { let name = native_lib_filename(); let mut candidates = Vec::new(); + if let Ok(p) = env::var("MARQDO_AGENT_PLUGIN") { + let p = PathBuf::from(p); + if p.is_file() { + return Ok(p); + } + candidates.push(p); + } 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)); } + // Honor CARGO_TARGET_DIR (sandbox / custom target roots) before cwd/target. + if let Ok(td) = env::var("CARGO_TARGET_DIR") { + let td = PathBuf::from(td); + candidates.push(td.join("debug").join(name)); + candidates.push(td.join("release").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)); @@ -164,19 +177,19 @@ fn find_native_plugin() -> Result { if let Ok(exe) = env::current_exe() { if let Some(dir) = exe.parent() { candidates.push(dir.join("ext").join("native").join(name)); + // Same directory as the marqdo binary (typical: target/debug/). 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 { + for p in &candidates { if p.is_file() { - return Ok(p); + return Ok(p.clone()); } } bail!( - "cannot find native plugin `{name}` (run `cargo build -p marqdo_plugin_agent`, or place it under MARQDO_EXT_SOURCE/native/)" + "cannot find native plugin `{name}` (run `cargo build -p marqdo_plugin_agent`, or `marqdo ext add agent`, or set MARQDO_AGENT_PLUGIN)" ); } @@ -270,6 +283,7 @@ pub fn remove_ext(id: &str) -> Result<()> { } /// Resolve installed native plugin path for `name` (currently only `agent`). +/// Also falls back to cargo `target/{debug,release}` artifacts for local runs. pub fn installed_native_path(name: &str) -> Option { if name != "agent" { return None; @@ -287,7 +301,13 @@ pub fn installed_native_path(name: &str) -> Option { return Some(p); } } - None + if let Ok(p) = env::var("MARQDO_AGENT_PLUGIN") { + let p = PathBuf::from(p); + if p.is_file() { + return Some(p); + } + } + find_native_plugin().ok() } pub fn path_is_trusted_plugin(path: &Path) -> bool { @@ -303,5 +323,18 @@ pub fn path_is_trusted_plugin(path: &Path) -> bool { return true; } } + if let Ok(p) = env::var("MARQDO_AGENT_PLUGIN") { + let p = PathBuf::from(p); + let p = p.canonicalize().unwrap_or(p); + if p == path { + return true; + } + } + if let Ok(found) = find_native_plugin() { + let found = found.canonicalize().unwrap_or(found); + if found == path { + return true; + } + } false } diff --git a/src/host/agent_rt.rs b/src/host/agent_rt.rs index e84d43b..45d74ad 100644 --- a/src/host/agent_rt.rs +++ b/src/host/agent_rt.rs @@ -1,4 +1,4 @@ -//! Runtime support for `ext/agent`: module source, call site, skill text, history store. +//! Runtime helpers for ABI `host_query` and shared map/list ops. use std::path::{Path, PathBuf}; @@ -18,13 +18,6 @@ impl HostContext { pub fn pop_call_frame(&mut self) { self.call_stack.pop(); } - - pub fn alloc_agent_id(&mut self) -> String { - self.agent_seq = self.agent_seq.wrapping_add(1); - let id = format!("agent-{}", self.agent_seq); - self.agent_histories.insert(id.clone(), Vec::new()); - id - } } pub fn module_source(ctx: &HostContext) -> Result { @@ -110,7 +103,6 @@ fn skill_search_roots(ctx: &HostContext) -> Vec { roots.push(dir.to_path_buf()); if let Some(parent) = dir.parent() { roots.push(parent.to_path_buf()); - // target/debug → repo root if let Some(repo) = parent.parent() { roots.push(repo.to_path_buf()); } @@ -121,7 +113,6 @@ fn skill_search_roots(ctx: &HostContext) -> Vec { if let Some(p) = &ctx.entry_path { if let Some(parent) = p.parent() { roots.push(parent.to_path_buf()); - // tests/ext → repo if let Some(repo) = parent.parent().and_then(|p| p.parent()) { roots.push(repo.to_path_buf()); } @@ -133,44 +124,6 @@ fn skill_search_roots(ctx: &HostContext) -> Vec { roots } -pub fn agent_alloc(ctx: &mut HostContext) -> Result { - Ok(Value::Text(ctx.alloc_agent_id())) -} - -pub fn agent_history_get(ctx: &HostContext, id: &Value) -> Result { - let id = text_id(id)?; - Ok(Value::List( - ctx.agent_histories - .get(&id) - .cloned() - .unwrap_or_default(), - )) -} - -pub fn agent_history_clear(ctx: &mut HostContext, id: &Value) -> Result { - let id = text_id(id)?; - ctx.agent_histories.insert(id, Vec::new()); - Ok(Value::None) -} - -pub fn agent_history_append( - ctx: &mut HostContext, - id: &Value, - item: &Value, -) -> Result { - let id = text_id(id)?; - let list = ctx.agent_histories.entry(id).or_default(); - list.push(item.clone()); - Ok(Value::List(list.clone())) -} - -fn text_id(id: &Value) -> Result { - match id { - Value::Text(s) if !s.is_empty() => Ok(s.clone()), - _ => Err("agent history id must be non-empty text".into()), - } -} - pub fn map_set(map: &Value, key: &Value, value: &Value) -> Result { let k = match key { Value::Text(s) => s.clone(), @@ -203,75 +156,14 @@ pub fn list_append(list: &Value, item: &Value) -> Result { } } -fn tool_name_from_row(row: &Value) -> Option { - match row { - Value::Text(s) if !s.is_empty() => Some(s.clone()), - Value::Map(entries) => ["工具", "tools", "name"] - .iter() - .find_map(|key| { - entries.iter().find(|(k, _)| k == *key).and_then(|(_, v)| { - if let Value::Text(s) = v { - (!s.is_empty()).then(|| s.clone()) - } else { - None - } - }) - }), - _ => None, - } -} - -pub fn tool_names(tools: &Value) -> Vec { - match tools { - Value::List(rows) => rows.iter().filter_map(tool_name_from_row).collect(), - _ => Vec::new(), - } -} - -pub fn format_tools_for_llm(tools: &Value) -> Result { - let mut out = String::from("Available tools (invoke via TOOL:):\n"); - for name in tool_names(tools) { - out.push_str("- "); - out.push_str(&name); - out.push('\n'); - } - Ok(Value::Text(out)) -} - -pub fn tool_allowed(tools: &Value, name: &Value) -> Result { - let name = match name { - Value::Text(s) if !s.is_empty() => s.as_str(), - _ => return Ok(Value::Bool(false)), - }; - Ok(Value::Bool( - tool_names(tools).iter().any(|n| n == name), - )) -} - #[cfg(test)] mod tests { use super::*; #[test] - fn tool_catalog_from_table() { - let tools = Value::List(vec![Value::Text("获取时间".into())]); - let text = format_tools_for_llm(&tools).unwrap(); - assert!(matches!(text, Value::Text(s) if s.contains("获取时间"))); - assert!(tool_allowed(&tools, &Value::Text("获取时间".into())).unwrap().truthy()); - assert!(!tool_allowed(&tools, &Value::Text("nope".into())).unwrap().truthy()); - } - - #[test] - fn map_set_and_history() { - let mut ctx = HostContext::default(); - let id = ctx.alloc_agent_id(); - assert!(id.starts_with("agent-")); - agent_history_append(&mut ctx, &Value::Text(id.clone()), &Value::Text("a".into())) - .unwrap(); - let h = agent_history_get(&ctx, &Value::Text(id.clone())).unwrap(); - assert_eq!(h, Value::List(vec![Value::Text("a".into())])); - agent_history_clear(&mut ctx, &Value::Text(id)).unwrap(); - let h2 = agent_history_get(&ctx, &Value::Text("agent-1".into())).unwrap(); - assert_eq!(h2, Value::List(vec![])); + fn map_set_updates() { + let m = Value::Map(vec![("a".into(), Value::Int(1))]); + let m2 = map_set(&m, &Value::Text("a".into()), &Value::Int(2)).unwrap(); + assert_eq!(m2, Value::Map(vec![("a".into(), Value::Int(2))])); } } diff --git a/src/host/dispatch.rs b/src/host/dispatch.rs index 62d7a06..af8cbf1 100644 --- a/src/host/dispatch.rs +++ b/src/host/dispatch.rs @@ -81,17 +81,8 @@ pub enum HostFn { PluginUnload = 70, PluginList = 71, ExtNativePath = 72, - ModuleSource = 73, - CallSite = 74, - MarqdoSkill = 75, MapSet = 76, ListAppend = 77, - AgentAlloc = 78, - AgentHistoryGet = 79, - AgentHistoryClear = 80, - AgentHistoryAppend = 81, - FormatToolsForLlm = 82, - ToolAllowed = 83, WritebackRecord = 84, WritebackGet = 85, WritebackClear = 86, @@ -101,6 +92,8 @@ pub enum HostFn { SubtaskJoin = 90, SubtaskKill = 91, SubtaskWaitAll = 92, + WritebackEnsure = 93, + OuterCallLine = 94, } impl HostFn { @@ -178,17 +171,8 @@ impl HostFn { 70 => Self::PluginUnload, 71 => Self::PluginList, 72 => Self::ExtNativePath, - 73 => Self::ModuleSource, - 74 => Self::CallSite, - 75 => Self::MarqdoSkill, 76 => Self::MapSet, 77 => Self::ListAppend, - 78 => Self::AgentAlloc, - 79 => Self::AgentHistoryGet, - 80 => Self::AgentHistoryClear, - 81 => Self::AgentHistoryAppend, - 82 => Self::FormatToolsForLlm, - 83 => Self::ToolAllowed, 84 => Self::WritebackRecord, 85 => Self::WritebackGet, 86 => Self::WritebackClear, @@ -198,6 +182,8 @@ impl HostFn { 90 => Self::SubtaskJoin, 91 => Self::SubtaskKill, 92 => Self::SubtaskWaitAll, + 93 => Self::WritebackEnsure, + 94 => Self::OuterCallLine, _ => return None, }) } @@ -279,21 +265,14 @@ impl HostFn { "host_plugin_unload" | "plugin_unload" => Self::PluginUnload, "host_plugin_list" | "plugin_list" => Self::PluginList, "host_ext_native_path" | "ext_native_path" => Self::ExtNativePath, - "host_module_source" | "module_source" => Self::ModuleSource, - "host_call_site" | "call_site" => Self::CallSite, - "host_marqdo_skill" | "marqdo_skill" => Self::MarqdoSkill, - "host_map_set" | "map_set" => Self::MapSet, + "host_map_set" | "map_set" => Self::MapSet, "host_list_append" | "list_append" => Self::ListAppend, - "host_agent_alloc" | "agent_alloc" => Self::AgentAlloc, - "host_agent_history_get" | "agent_history_get" => Self::AgentHistoryGet, - "host_agent_history_clear" | "agent_history_clear" => Self::AgentHistoryClear, - "host_agent_history_append" | "agent_history_append" => Self::AgentHistoryAppend, - "host_format_tools_for_llm" | "format_tools_for_llm" => Self::FormatToolsForLlm, - "host_tool_allowed" | "tool_allowed" => Self::ToolAllowed, - "host_writeback_record" | "writeback_record" => Self::WritebackRecord, + "host_writeback_record" | "writeback_record" => Self::WritebackRecord, "host_writeback_get" | "writeback_get" => Self::WritebackGet, "host_writeback_clear" | "writeback_clear" => Self::WritebackClear, "host_writeback_list" | "writeback_list" => Self::WritebackList, + "host_writeback_ensure" | "writeback_ensure" => Self::WritebackEnsure, + "host_outer_call_line" | "outer_call_line" => Self::OuterCallLine, "host_subtask_spawn" | "subtask_spawn" => Self::SubtaskSpawn, "host_subtask_poll" | "subtask_poll" => Self::SubtaskPoll, "host_subtask_join" | "subtask_join" => Self::SubtaskJoin, @@ -381,21 +360,14 @@ impl HostFn { Self::PluginUnload => "host_plugin_unload", Self::PluginList => "host_plugin_list", Self::ExtNativePath => "host_ext_native_path", - Self::ModuleSource => "host_module_source", - Self::CallSite => "host_call_site", - Self::MarqdoSkill => "host_marqdo_skill", Self::MapSet => "host_map_set", Self::ListAppend => "host_list_append", - Self::AgentAlloc => "host_agent_alloc", - Self::AgentHistoryGet => "host_agent_history_get", - Self::AgentHistoryClear => "host_agent_history_clear", - Self::AgentHistoryAppend => "host_agent_history_append", - Self::FormatToolsForLlm => "host_format_tools_for_llm", - Self::ToolAllowed => "host_tool_allowed", Self::WritebackRecord => "host_writeback_record", Self::WritebackGet => "host_writeback_get", Self::WritebackClear => "host_writeback_clear", Self::WritebackList => "host_writeback_list", + Self::WritebackEnsure => "host_writeback_ensure", + Self::OuterCallLine => "host_outer_call_line", Self::SubtaskSpawn => "host_subtask_spawn", Self::SubtaskPoll => "host_subtask_poll", Self::SubtaskJoin => "host_subtask_join", @@ -446,16 +418,13 @@ impl HostFn { Self::PluginLoad => &["path"], Self::PluginUnload | Self::PluginList => &[], Self::ExtNativePath => &["name"], - Self::ModuleSource | Self::CallSite | Self::MarqdoSkill | Self::AgentAlloc => &[], + Self::OuterCallLine => &[], Self::MapSet => &["map", "key", "value"], Self::ListAppend => &["list", "item"], - Self::AgentHistoryGet | Self::AgentHistoryClear => &["id"], - Self::AgentHistoryAppend => &["id", "item"], - Self::FormatToolsForLlm => &["tools"], - Self::ToolAllowed => &["tools", "name"], Self::WritebackRecord => &["value"], Self::WritebackGet | Self::WritebackClear => &[], Self::WritebackList => &[], + Self::WritebackEnsure => &["key"], Self::SubtaskSpawn => &[], Self::SubtaskPoll | Self::SubtaskJoin | Self::SubtaskKill => &["id"], Self::SubtaskWaitAll => &[], @@ -476,7 +445,10 @@ impl HostFn { Self::PlotConic => &["b", "h", "k", "path", "grid"], Self::ForeignSetCmd => &["args"], Self::ForeignRun | Self::ForeignRunLang => &["stdin"], - Self::WritebackRecord | Self::WritebackGet | Self::WritebackClear => &["at_end"], + Self::WritebackRecord | Self::WritebackGet | Self::WritebackClear => { + &["at_end", "key", "line"] + } + Self::WritebackEnsure => &["placeholder", "line"], Self::SubtaskSpawn => &["path", "fn", "args", "code", "lang", "source", "stdin"], _ => &[], } @@ -650,40 +622,50 @@ pub fn call_host( None => Value::None, }) } - HostFn::ModuleSource => agent_rt::module_source(ctx), - HostFn::CallSite => { - agent_rt::call_site(ctx, Some(ctx.current_line)) - } - HostFn::MarqdoSkill => agent_rt::marqdo_skill(ctx), HostFn::MapSet => { agent_rt::map_set(require(bound, "map")?, require(bound, "key")?, require(bound, "value")?) } HostFn::ListAppend => { agent_rt::list_append(require(bound, "list")?, require(bound, "item")?) } - HostFn::AgentAlloc => agent_rt::agent_alloc(ctx), - HostFn::AgentHistoryGet => agent_rt::agent_history_get(ctx, require(bound, "id")?), - HostFn::AgentHistoryClear => { - agent_rt::agent_history_clear(ctx, require(bound, "id")?) - } - HostFn::AgentHistoryAppend => { - agent_rt::agent_history_append(ctx, require(bound, "id")?, require(bound, "item")?) - } - HostFn::FormatToolsForLlm => { - agent_rt::format_tools_for_llm(require(bound, "tools")?) - } - HostFn::ToolAllowed => agent_rt::tool_allowed( - require(bound, "tools")?, - require(bound, "name")?, - ), + HostFn::OuterCallLine => Ok(Value::Int( + ctx.call_site_lines + .first() + .copied() + .unwrap_or(ctx.current_line) as i64, + )), HostFn::WritebackRecord => writeback::record( ctx, require(bound, "value")?, bound.get("at_end"), + bound.get("key"), + bound.get("line"), + ), + HostFn::WritebackGet => writeback::get( + ctx, + bound.get("at_end"), + bound.get("key"), + bound.get("line"), + ), + HostFn::WritebackClear => writeback::clear( + ctx, + bound.get("at_end"), + bound.get("key"), + bound.get("line"), ), - HostFn::WritebackGet => writeback::get(ctx, bound.get("at_end")), - HostFn::WritebackClear => writeback::clear(ctx, bound.get("at_end")), HostFn::WritebackList => writeback::list(ctx), + HostFn::WritebackEnsure => { + let placeholder = bound + .get("placeholder") + .cloned() + .unwrap_or_else(|| Value::Text("pending".into())); + writeback::ensure_slot( + ctx, + require(bound, "key")?, + &placeholder, + bound.get("line"), + ) + } HostFn::SubtaskSpawn => subtask::spawn(ctx, bound), HostFn::SubtaskPoll => subtask::poll(ctx, require(bound, "id")?), HostFn::SubtaskJoin => subtask::join(ctx, require(bound, "id")?), diff --git a/src/host/mod.rs b/src/host/mod.rs index 10e615e..dbe52ec 100644 --- a/src/host/mod.rs +++ b/src/host/mod.rs @@ -24,8 +24,6 @@ pub use plugin::PluginState; use std::collections::HashMap; use std::path::{Path, PathBuf}; -use crate::value::Value; - /// Host capability flags. Default: all enabled. #[derive(Debug, Clone)] pub struct HostCaps { @@ -68,17 +66,14 @@ pub struct HostContext { pub plots: Vec, /// lang → interpreter argv (from `set_cmd`). pub foreign_cmds: HashMap>, - /// Loaded native plugins (ABI v1). + /// Loaded native plugins (ABI v1/v2). pub plugins: PluginState, - /// Entry `.mq.md` source text (for agent context injection). + /// Entry `.mq.md` source text (for ABI host_query / context injection). pub entry_source: Option, pub entry_path: Option, /// Active function names (outer → inner) for call-site injection. pub call_stack: Vec, - /// Per-agent conversation history (id → turns). - pub agent_histories: HashMap>, - pub agent_seq: u64, - /// Last statement line (updated by interpreters for `host_call_site`). + /// Last statement line (updated by interpreters for call-site queries). pub current_line: u32, /// Entry-file line of each active user call (for writeback anchoring). pub call_site_lines: Vec, @@ -103,8 +98,6 @@ impl Default for HostContext { entry_source: None, entry_path: None, call_stack: Vec::new(), - agent_histories: HashMap::new(), - agent_seq: 0, current_line: 1, call_site_lines: Vec::new(), subtasks: HashMap::new(), diff --git a/src/host/net.rs b/src/host/net.rs index 5a6a6df..cfdd04c 100644 --- a/src/host/net.rs +++ b/src/host/net.rs @@ -117,8 +117,8 @@ pub fn http_post( let url = as_text(url, "url")?; let body = as_text(body, "body")?; let ct = match content_type { + None | Some(Value::None) => "application/json; charset=utf-8", Some(v) => as_text(v, "content_type")?, - None => "application/json; charset=utf-8", }; let hdrs = headers_from_value(headers)?; let (status, resp) = http_exchange("POST", url, Some(body), Some(ct), &hdrs)?; diff --git a/src/host/plugin.rs b/src/host/plugin.rs index a4656c6..8bed612 100644 --- a/src/host/plugin.rs +++ b/src/host/plugin.rs @@ -1,16 +1,21 @@ -//! Native plugin loader (C ABI v1). Shared libs are not linked into marqdo. +//! Native plugin loader (C ABI v1/v2). Shared libs are not linked into marqdo. +use std::cell::Cell; use std::collections::HashMap; use std::ffi::{CStr, CString}; use std::os::raw::{c_char, c_int, c_void}; use libloading::{Library, Symbol}; +use crate::host::agent_rt; use crate::host::json::{json_to_value, value_to_json}; use crate::host::HostContext; use crate::value::Value; -pub const ABI_VERSION: u32 = 1; +/// Highest ABI version this host speaks. +pub const ABI_VERSION: u32 = 2; +/// Oldest plugin ABI still accepted. +pub const ABI_VERSION_MIN: u32 = 1; type PluginFn = unsafe extern "C" fn( args_json: *const c_char, @@ -18,6 +23,14 @@ type PluginFn = unsafe extern "C" fn( err_msg: *mut *mut c_char, ) -> c_int; +type HostQueryFn = unsafe extern "C" fn( + userdata: *mut c_void, + name: *const c_char, + args_json: *const c_char, + out_json: *mut *mut c_char, + err_msg: *mut *mut c_char, +) -> c_int; + type AbiVersionFn = unsafe extern "C" fn() -> u32; type InitFn = unsafe extern "C" fn(host: *const MarqdoHostApi) -> c_int; type ShutdownFn = unsafe extern "C" fn(); @@ -35,6 +48,12 @@ struct MarqdoHostApi { >, alloc: Option *mut c_void>, free: Option, + host_query: Option, +} + +thread_local! { + /// Set around plugin calls so `host_query` can read entry source / call site. + static CURRENT_HOST: Cell<*const HostContext> = const { Cell::new(std::ptr::null()) }; } struct RegisterBuf { @@ -88,6 +107,10 @@ impl PluginState { names.sort(); names } + + pub fn has_fn(&self, name: &str) -> bool { + self.fns.contains_key(name) + } } fn as_text<'a>(v: &'a Value, label: &str) -> Result<&'a str, String> { @@ -112,6 +135,17 @@ unsafe extern "C" fn host_free(p: *mut c_void) { } } +unsafe fn host_strdup(s: &str) -> *mut c_char { + let bytes = s.as_bytes(); + let p = host_alloc(bytes.len() + 1) as *mut u8; + if p.is_null() { + return std::ptr::null_mut(); + } + std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len()); + *p.add(bytes.len()) = 0; + p as *mut c_char +} + unsafe extern "C" fn host_register( userdata: *mut c_void, name: *const c_char, @@ -167,6 +201,63 @@ unsafe extern "C" fn host_register( 0 } +/// Allowlisted host introspection for ABI v2 plugins (`host_query`). +unsafe extern "C" fn host_query( + _userdata: *mut c_void, + name: *const c_char, + _args_json: *const c_char, + out_json: *mut *mut c_char, + err_msg: *mut *mut c_char, +) -> c_int { + let set_err = |msg: &str| { + if !err_msg.is_null() { + *err_msg = host_strdup(msg); + } + }; + let set_out = |msg: &str| { + if !out_json.is_null() { + *out_json = host_strdup(msg); + } + }; + + if name.is_null() { + set_err("host_query: null name"); + return 1; + } + let name = match CStr::from_ptr(name).to_str() { + Ok(s) => s, + Err(_) => { + set_err("host_query: name not utf-8"); + return 1; + } + }; + + let ctx_ptr = CURRENT_HOST.with(|c| c.get()); + if ctx_ptr.is_null() { + set_err("host_query: no active host context (call during plugin fn)"); + return 1; + } + let ctx = &*ctx_ptr; + + let result = match name { + "module_source" => agent_rt::module_source(ctx).and_then(|v| value_to_json(&v)), + "call_site" => agent_rt::call_site(ctx, Some(ctx.current_line)).and_then(|v| value_to_json(&v)), + "marqdo_skill" => agent_rt::marqdo_skill(ctx).and_then(|v| value_to_json(&v)), + other => Err(format!("host_query: unknown `{other}`")), + }; + + match result { + Ok(j) => { + set_out(&j.to_string()); + 0 + } + Err(e) => { + set_err(&e); + 1 + } + } +} + pub fn load(ctx: &mut HostContext, path: &Value) -> Result { if !ctx.allow_plugin() { return Err("plugin_load denied by host policy".into()); @@ -200,9 +291,9 @@ pub fn load(ctx: &mut HostContext, path: &Value) -> Result { .map_err(|e| format!("plugin missing marqdo_plugin_abi_version: {e}"))? }; let ver = unsafe { version_fn() }; - if ver != ABI_VERSION { + if ver < ABI_VERSION_MIN || ver > ABI_VERSION { return Err(format!( - "plugin ABI version {ver} != host {ABI_VERSION} ({})", + "plugin ABI version {ver} not in host range {ABI_VERSION_MIN}..={ABI_VERSION} ({})", file.display() )); } @@ -221,6 +312,7 @@ pub fn load(ctx: &mut HostContext, path: &Value) -> Result { register_fn: Some(host_register), alloc: Some(host_alloc), free: Some(host_free), + host_query: Some(host_query), }; let rc = unsafe { init_fn(&api) }; @@ -235,6 +327,10 @@ pub fn load(ctx: &mut HostContext, path: &Value) -> Result { for k in buf.fns.keys() { if ctx.plugins.fns.contains_key(k) { + // Idempotent re-load of the same plugin surface (e.g. multiple `agent` ctors). + if buf.fns.keys().all(|name| ctx.plugins.fns.contains_key(name)) { + return Ok(Value::Int(0)); + } return Err(format!("plugin function `{k}` already registered")); } } @@ -282,7 +378,8 @@ pub fn call_registered( let reg = ctx .plugins .get(name) - .ok_or_else(|| format!("unknown function `{name}`"))?; + .ok_or_else(|| format!("unknown function `{name}`"))? + .clone(); let mut map = serde_json::Map::new(); for p in ®.params { @@ -299,7 +396,10 @@ pub fn call_registered( let mut out_ptr: *mut c_char = std::ptr::null_mut(); let mut err_ptr: *mut c_char = std::ptr::null_mut(); + + CURRENT_HOST.with(|c| c.set(ctx as *const HostContext)); let rc = unsafe { (reg.fn_ptr)(c_args.as_ptr(), &mut out_ptr, &mut err_ptr) }; + CURRENT_HOST.with(|c| c.set(std::ptr::null())); let err_s = take_c_string(err_ptr); let out_s = take_c_string(out_ptr); diff --git a/src/host/subtask.rs b/src/host/subtask.rs index 1355852..3ea97cf 100644 --- a/src/host/subtask.rs +++ b/src/host/subtask.rs @@ -133,12 +133,10 @@ pub fn kill_all(ctx: &mut HostContext) { let _ = task.stderr.join(); } Handle::Function(mut task) => { - if let Ok(mut st) = task.state.lock() { - if matches!(*st, FnState::Running) { - *st = FnState::Killed; - } + // Join so fire-and-forget writers (e.g. agent writeback) finish before exit. + if let Some(h) = task.handle.take() { + let _ = h.join(); } - drop(task.handle.take()); } } } diff --git a/src/host/sys.rs b/src/host/sys.rs index b9b26b6..7197d9d 100644 --- a/src/host/sys.rs +++ b/src/host/sys.rs @@ -107,18 +107,17 @@ pub fn exec(ctx: &HostContext, cmd: &Value, args: Option<&Value>) -> Result { - for x in xs { - command.arg(x.as_display()); - } + match args { + None | Some(Value::None) => {} + Some(Value::List(xs)) => { + for x in xs { + command.arg(x.as_display()); } - Value::Text(s) => { - command.arg(s); - } - _ => return Err("exec args must be list or text".into()), } + Some(Value::Text(s)) => { + command.arg(s); + } + Some(_) => return Err("exec args must be list or text".into()), } let status = command .status() diff --git a/src/host/writeback.rs b/src/host/writeback.rs index 622eaa1..4fb6c1b 100644 --- a/src/host/writeback.rs +++ b/src/host/writeback.rs @@ -1,18 +1,27 @@ //! Jupyter-style output persistence in `.mq.md` (``). +//! +//! Optional **named slots**: `` / `` +//! so success and failure results do not overwrite each other. use std::collections::HashMap; +use std::sync::Mutex; use crate::host::HostContext; use crate::value::Value; const MAGIC: &str = "marqdo-out"; +/// Serialize all writeback file mutations (sync + subtask writers). +static WRITEBACK_LOCK: Mutex<()> = Mutex::new(()); + #[derive(Debug, Clone, PartialEq, Eq)] struct BlockSpan { start: usize, end: usize, body: String, start_line: u32, + /// Named slot from header (`marqdo-out ok` → `ok`); `None` = legacy unkeyed. + key: Option, } fn display_value(v: &Value) -> String { @@ -31,6 +40,48 @@ fn is_truthy(v: Option<&Value>) -> bool { } } +fn opt_key(v: Option<&Value>) -> Result, String> { + match v { + None | Some(Value::None) => Ok(None), + Some(Value::Text(s)) => { + let t = s.trim(); + if t.is_empty() { + Ok(None) + } else { + Ok(Some(normalize_slot_key(t))) + } + } + _ => Err("writeback key must be text".into()), + } +} + +fn opt_line(v: Option<&Value>) -> Result, String> { + match v { + None | Some(Value::None) => Ok(None), + Some(Value::Int(n)) if *n > 0 => Ok(Some(*n as u32)), + Some(Value::Text(s)) => { + let t = s.trim(); + if t.is_empty() { + Ok(None) + } else { + t.parse::() + .map(|n| if n > 0 { Some(n) } else { None }) + .map_err(|_| "writeback line must be a positive int".into()) + } + } + _ => Err("writeback line must be a positive int".into()), + } +} + +/// Canonical slot ids used by the agent framework. +fn normalize_slot_key(raw: &str) -> String { + match raw { + "ok" | "success" | "成功" => "ok".into(), + "error" | "failure" | "失败" => "error".into(), + other => other.to_string(), + } +} + fn call_line(ctx: &HostContext) -> Result { ctx.call_site_lines .last() @@ -38,6 +89,28 @@ fn call_line(ctx: &HostContext) -> Result { .ok_or_else(|| "writeback: no call site line".into()) } +/// Line that should own adjacent output cards. +/// Prefer explicit `line=`, else for keyed slots the outermost call site (`step`), +/// else the parent/current call site. +fn resolve_anchor( + ctx: &HostContext, + keyed: bool, + line: Option<&Value>, +) -> Result { + if let Some(n) = opt_line(line)? { + return Ok(n); + } + if keyed { + if let Some(n) = ctx.call_site_lines.first().copied() { + return Ok(n); + } + if ctx.call_site_lines.len() >= 2 { + return Ok(ctx.call_site_lines[ctx.call_site_lines.len() - 2]); + } + } + call_line(ctx) +} + fn line_number_at(source: &str, byte: usize) -> u32 { source[..byte.min(source.len())] .bytes() @@ -46,8 +119,20 @@ fn line_number_at(source: &str, byte: usize) -> u32 { + 1 } -fn format_block(body: &str) -> String { - format!("") +fn format_block(body: &str, key: Option<&str>) -> String { + match key { + Some(k) => format!(""), + None => format!(""), + } +} + +fn parse_header_key(header: &str) -> Option { + let mut parts = header.split_whitespace(); + let first = parts.next()?; + if first != MAGIC { + return None; + } + parts.next().map(normalize_slot_key) } fn parse_one_block(block: &str, start_byte: usize, source: &str) -> Option { @@ -66,6 +151,7 @@ fn parse_one_block(block: &str, start_byte: usize, source: &str) -> Option Option String { out } +/// Byte end of a `` span, including the single newline that terminates the `-->` line. +fn span_end_including_nl(source: &str, end: usize) -> usize { + if source.as_bytes().get(end) == Some(&b'\n') { + end + 1 + } else { + end + } +} + +/// Write `block` (plus a terminating newline) over `[start, end)`, preserving blank lines after. +fn splice_block(source: &str, start: usize, end: usize, block: &str) -> String { + let end = span_end_including_nl(source, end); + let mut out = String::with_capacity(source.len() + block.len() + 1); + out.push_str(&source[..start]); + out.push_str(block); + if !block.ends_with('\n') { + out.push('\n'); + } + out.push_str(&source[end..]); + out +} + fn line_start_byte(source: &str, line_no: u32) -> Option { if line_no == 0 { return None; @@ -154,7 +263,7 @@ fn find_adjacent_block(source: &str, after_line: u32) -> Option { line += 1; } for b in scan_blocks(source) { - if b.start_line == line { + if b.start_line == line && b.key.is_none() { return Some(b); } } @@ -169,7 +278,73 @@ fn find_eof_block(source: &str) -> Option { scan_blocks(source) .into_iter() .rev() - .find(|b| is_eof_block(source, b)) + .find(|b| b.key.is_none() && is_eof_block(source, b)) +} + +fn find_keyed_block(source: &str, key: &str) -> Option { + let key = normalize_slot_key(key); + scan_blocks(source) + .into_iter() + .rev() + .find(|b| b.key.as_deref() == Some(key.as_str())) +} + +/// Consecutive `marqdo-out` blocks immediately below `after_line` (blank lines allowed). +fn cluster_after_line(source: &str, after_line: u32) -> Vec { + let total = source.bytes().filter(|b| *b == b'\n').count() as u32 + 1; + let mut line = after_line.saturating_add(1); + while line <= total && is_blank_line(source, line) { + line += 1; + } + let blocks = scan_blocks(source); + let mut cluster = Vec::new(); + while line <= total { + if let Some(b) = blocks.iter().find(|b| b.start_line == line) { + cluster.push(b.clone()); + let end_line = line_number_at(source, b.end.saturating_sub(1).max(b.start)); + line = end_line.saturating_add(1); + while line <= total && is_blank_line(source, line) { + line += 1; + } + } else { + break; + } + } + cluster +} + +fn find_keyed_in_cluster(source: &str, after_line: u32, key: &str) -> Option { + let key = normalize_slot_key(key); + cluster_after_line(source, after_line) + .into_iter() + .find(|b| b.key.as_deref() == Some(key.as_str())) +} + +/// Replace keyed block under `anchor` line, or insert into that cluster (not EOF). +fn replace_or_insert_keyed_at(source: &str, anchor: u32, key: &str, body: &str) -> Result { + let key = normalize_slot_key(key); + let block = format_block(body, Some(&key)); + if let Some(existing) = find_keyed_in_cluster(source, anchor, &key) { + return Ok(splice_block(source, existing.start, existing.end, &block)); + } + let cluster = cluster_after_line(source, anchor); + if let Some(last) = cluster.last() { + // Insert after the last block's terminating newline (or after `-->` if none). + let insert_at = span_end_including_nl(source, last.end); + let mut out = String::with_capacity(source.len() + block.len() + 1); + out.push_str(&source[..insert_at]); + if !out.ends_with('\n') { + out.push('\n'); + } + out.push_str(&block); + if !block.ends_with('\n') { + out.push('\n'); + } + out.push_str(&source[insert_at..]); + Ok(out) + } else { + insert_after_line(source, anchor, &block) + } } fn insert_after_line(source: &str, line_no: u32, block: &str) -> Result { @@ -213,6 +388,24 @@ fn persist(ctx: &mut HostContext, source: &str) -> Result<(), String> { Ok(()) } +fn load_entry_source(ctx: &HostContext) -> Result { + if let Some(path) = &ctx.entry_path { + if let Ok(text) = std::fs::read_to_string(path) { + return Ok(text); + } + } + ctx.entry_source + .clone() + .ok_or_else(|| "writeback: no entry source".to_string()) +} + +fn with_writeback_lock(f: impl FnOnce() -> Result) -> Result { + let _guard = WRITEBACK_LOCK + .lock() + .map_err(|_| "writeback lock poisoned".to_string())?; + f() +} + fn anchor_line_above(source: &str, block_start_line: u32) -> u32 { let mut line = block_start_line.saturating_sub(1); while line > 0 && is_blank_line(source, line) { @@ -225,64 +418,109 @@ pub fn record( ctx: &mut HostContext, value: &Value, at_end: Option<&Value>, + key: Option<&Value>, + line: Option<&Value>, ) -> Result { let body = display_value(value); - let source = ctx - .entry_source - .as_deref() - .ok_or_else(|| "writeback: no entry source".to_string())?; - let next = if is_truthy(at_end) { - let stripped = find_eof_block(source) - .map(|b| strip_span(source, b.start, b.end)) - .unwrap_or_else(|| source.to_string()); - append_eof(&stripped, &format_block(&body)) + let key = opt_key(key)?; + let at_end = is_truthy(at_end); + let anchor = if key.is_some() || !at_end { + Some(resolve_anchor(ctx, key.is_some(), line)?) } else { - let line = call_line(ctx)?; - let stripped = find_adjacent_block(source, line) - .map(|b| strip_span(source, b.start, b.end)) - .unwrap_or_else(|| source.to_string()); - insert_after_line(&stripped, line, &format_block(&body))? + None }; - persist(ctx, &next)?; - Ok(Value::Text(body)) -} - -pub fn get(ctx: &HostContext, at_end: Option<&Value>) -> Result { - let source = ctx - .entry_source - .as_deref() - .ok_or_else(|| "writeback: no entry source".to_string())?; - let body = if is_truthy(at_end) { - find_eof_block(source).map(|b| b.body) - } else { - let line = call_line(ctx)?; - find_adjacent_block(source, line).map(|b| b.body) - }; - Ok(match body { - Some(s) => Value::Text(s), - None => Value::None, + with_writeback_lock(|| { + let source = load_entry_source(ctx)?; + let next = if let Some(ref k) = key { + let anchor = anchor.ok_or_else(|| "writeback: missing anchor line".to_string())?; + replace_or_insert_keyed_at(&source, anchor, k, &body)? + } else if at_end { + let stripped = find_eof_block(&source) + .map(|b| strip_span(&source, b.start, span_end_including_nl(&source, b.end))) + .unwrap_or_else(|| source.clone()); + append_eof(&stripped, &format_block(&body, None)) + } else { + let line = anchor.ok_or_else(|| "writeback: missing anchor line".to_string())?; + let stripped = find_adjacent_block(&source, line) + .map(|b| strip_span(&source, b.start, span_end_including_nl(&source, b.end))) + .unwrap_or_else(|| source.clone()); + insert_after_line(&stripped, line, &format_block(&body, None))? + }; + persist(ctx, &next)?; + Ok(Value::Text(body.clone())) }) } -pub fn clear(ctx: &mut HostContext, at_end: Option<&Value>) -> Result { - let source = ctx - .entry_source - .as_deref() - .ok_or_else(|| "writeback: no entry source".to_string())?; - let next = if is_truthy(at_end) { - find_eof_block(source) - .map(|b| strip_span(source, b.start, b.end)) - .unwrap_or_else(|| source.to_string()) +pub fn get( + ctx: &HostContext, + at_end: Option<&Value>, + key: Option<&Value>, + line: Option<&Value>, +) -> Result { + let key = opt_key(key)?; + let at_end = is_truthy(at_end); + let anchor = if key.is_some() || !at_end { + resolve_anchor(ctx, key.is_some(), line).ok() } else { - let line = call_line(ctx)?; - find_adjacent_block(source, line) - .map(|b| strip_span(source, b.start, b.end)) - .unwrap_or_else(|| source.to_string()) + None }; - if next != source { - persist(ctx, &next)?; - } - Ok(Value::None) + with_writeback_lock(|| { + let source = load_entry_source(ctx)?; + let body = if let Some(ref k) = key { + let found = anchor + .and_then(|a| find_keyed_in_cluster(&source, a, k)) + .or_else(|| find_keyed_block(&source, k)); + found.map(|b| b.body) + } else if at_end { + find_eof_block(&source).map(|b| b.body) + } else { + let line = anchor.ok_or_else(|| "writeback: no call site line".to_string())?; + find_adjacent_block(&source, line).map(|b| b.body) + }; + Ok(match body { + Some(s) => Value::Text(s), + None => Value::None, + }) + }) +} + +pub fn clear( + ctx: &mut HostContext, + at_end: Option<&Value>, + key: Option<&Value>, + line: Option<&Value>, +) -> Result { + let key = opt_key(key)?; + let at_end = is_truthy(at_end); + let anchor = if key.is_some() || !at_end { + resolve_anchor(ctx, key.is_some(), line).ok() + } else { + None + }; + with_writeback_lock(|| { + let source = load_entry_source(ctx)?; + let next = if let Some(ref k) = key { + let block = anchor + .and_then(|a| find_keyed_in_cluster(&source, a, k)) + .or_else(|| find_keyed_block(&source, k)); + block + .map(|b| strip_span(&source, b.start, span_end_including_nl(&source, b.end))) + .unwrap_or_else(|| source.clone()) + } else if at_end { + find_eof_block(&source) + .map(|b| strip_span(&source, b.start, span_end_including_nl(&source, b.end))) + .unwrap_or_else(|| source.clone()) + } else { + let line = anchor.ok_or_else(|| "writeback: no call site line".to_string())?; + find_adjacent_block(&source, line) + .map(|b| strip_span(&source, b.start, span_end_including_nl(&source, b.end))) + .unwrap_or_else(|| source.clone()) + }; + if next != source { + persist(ctx, &next)?; + } + Ok(Value::None) + }) } pub fn list(ctx: &HostContext) -> Result { @@ -294,25 +532,60 @@ pub fn list(ctx: &HostContext) -> Result { .into_iter() .map(|b| { let anchor = anchor_line_above(source, b.start_line); - let at_eof = is_eof_block(source, &b); - Value::Map(vec![ + let at_eof = b.key.is_none() && is_eof_block(source, &b); + let mut entries = vec![ ("line".into(), Value::Int(anchor as i64)), ("body".into(), Value::Text(b.body)), ("at_end".into(), Value::Bool(at_eof)), - ]) + ]; + if let Some(k) = b.key { + entries.push(("key".into(), Value::Text(k))); + } + Value::Map(entries) }) .collect(); Ok(Value::List(items)) } -/// Map statement line → body for adjacent blocks; EOF blocks use key `0`. +/// Ensure named slots exist with a placeholder body; **does not** overwrite non-empty bodies. +pub fn ensure_slot( + ctx: &mut HostContext, + key: &Value, + placeholder: &Value, + line: Option<&Value>, +) -> Result { + let k = opt_key(Some(key))?.ok_or_else(|| "writeback ensure needs key".to_string())?; + let body = display_value(placeholder); + let anchor = resolve_anchor(ctx, true, line)?; + with_writeback_lock(|| { + let source = load_entry_source(ctx)?; + if find_keyed_in_cluster(&source, anchor, &k).is_some() { + return Ok(Value::Bool(false)); + } + let next = replace_or_insert_keyed_at(&source, anchor, &k, &body)?; + persist(ctx, &next)?; + Ok(Value::Bool(true)) + }) +} + +/// Map statement line → body for adjacent blocks (keyed slots included under their anchor). pub fn writeback_map(source: &str) -> HashMap { let mut map = HashMap::new(); for b in scan_blocks(source) { - if is_eof_block(source, &b) { - map.insert(0, b.body); + let anchor = anchor_line_above(source, b.start_line); + let piece = match &b.key { + Some(k) => format!("[{k}]\n{}", b.body), + None => b.body.clone(), + }; + if b.key.is_none() && is_eof_block(source, &b) { + map.insert(0, piece); } else { - map.insert(anchor_line_above(source, b.start_line), b.body); + map.entry(anchor) + .and_modify(|e| { + e.push_str("\n\n"); + e.push_str(&piece); + }) + .or_insert(piece); } } map @@ -325,7 +598,7 @@ mod tests { #[test] fn parse_and_insert_adjacent() { let src = "# main\n\n*`x` = 1*\n"; - let block = format_block("1"); + let block = format_block("1", None); let next = insert_after_line(src, 3, &block).unwrap(); assert!(next.contains("marqdo-out")); assert!(!next.contains("@line")); @@ -342,4 +615,56 @@ mod tests { let map = writeback_map(src); assert_eq!(map.get(&3), Some(&"42".to_string())); } + + #[test] + fn keyed_slots_sit_under_anchor_and_do_not_clobber() { + let src = "# main\n\n*`r` = > step *\n\n> print text=after\n"; + let with_ok = replace_or_insert_keyed_at(src, 3, "ok", "success-1").unwrap(); + let with_both = replace_or_insert_keyed_at(&with_ok, 3, "error", "fail-1").unwrap(); + let step_at = with_both.find("`r` = > step").unwrap(); + let ok_at = with_both.find("marqdo-out ok").unwrap(); + let err_at = with_both.find("marqdo-out error").unwrap(); + let after_at = with_both.find("> print text=after").unwrap(); + assert!(ok_at > step_at && ok_at < after_at); + assert!(err_at > ok_at && err_at < after_at); + let updated = replace_or_insert_keyed_at(&with_both, 3, "error", "fail-2").unwrap(); + assert!(updated.contains("success-1")); + assert!(updated.contains("fail-2")); + assert!(!updated.contains("fail-1")); + } + + #[test] + fn keyed_replace_does_not_accumulate_blank_lines() { + let src = "# main\n\n> writeback.record\n\n\n2. *\n"; + let once = replace_or_insert_keyed_at(src, 3, "ok", "new-1").unwrap(); + let twice = replace_or_insert_keyed_at(&once, 3, "ok", "new-2").unwrap(); + let thrice = replace_or_insert_keyed_at(&twice, 3, "ok", "new-3").unwrap(); + assert_eq!(once.matches("\n\n\n").count(), src.matches("\n\n\n").count()); + assert_eq!(twice, thrice.replace("new-3", "new-2")); + // Exactly one blank line between `-->` and the next statement. + let after = thrice.split("-->\n").nth(1).unwrap(); + assert!(after.starts_with("\n2. *"), "got after -->: {after:?}"); + assert!(!after.starts_with("\n\n\n"), "blank lines accumulated"); + } + + #[test] + fn unkeyed_replace_does_not_accumulate_blank_lines() { + let src = "# main\n\n*`x` = 1*\n\n\n> print text=tail\n"; + let line = 3u32; + let strip_insert = |s: &str, body: &str| { + let stripped = find_adjacent_block(s, line) + .map(|b| strip_span(s, b.start, span_end_including_nl(s, b.end))) + .unwrap_or_else(|| s.to_string()); + insert_after_line(&stripped, line, &format_block(body, None)).unwrap() + }; + let once = strip_insert(src, "a"); + let twice = strip_insert(&once, "b"); + let thrice = strip_insert(&twice, "c"); + assert_eq!( + once.matches("\n\n\n").count(), + thrice.matches("\n\n\n").count() + ); + let after = thrice.split("-->\n").nth(1).unwrap(); + assert!(after.starts_with("\n> print"), "got after -->: {after:?}"); + } } diff --git a/src/interp.rs b/src/interp.rs index 41db012..f023c4f 100644 --- a/src/interp.rs +++ b/src/interp.rs @@ -446,11 +446,13 @@ impl Interpreter { call: &CallExpr, ) -> Result { let mut call = call.clone(); - let callee = crate::aliases::normalize_call_callee_and_args( - &call.callee, - &mut call.args, - ); - call.callee = callee; + if call.path.is_none() { + let callee = crate::aliases::normalize_call_callee_and_args( + &call.callee, + &mut call.args, + ); + call.callee = callee; + } let mut ev_args = Vec::new(); for arg in &call.args { @@ -471,6 +473,14 @@ impl Interpreter { return self.eval_method_call(module, fun, env, recv_name, &call.callee, &ev_args); } + if let Some(path) = &call.path { + return self.eval_path_call(module, path, &ev_args); + } + + if let Some(u) = module.uses.iter().find(|u| u.bind == call.callee) { + return self.eval_path_call(module, &u.path, &ev_args); + } + match call.callee.as_str() { "print" => { let bound = bind_args(&["text".into()], &ev_args, false) @@ -637,6 +647,73 @@ impl Interpreter { } } + /// Resolve bare path `lib.member` / `lib.Type.member` (definition-tree addressing). + fn eval_path_call( + &mut self, + module: &Module, + path: &[String], + ev_args: &[EvArg], + ) -> Result { + let display = path.join("."); + if path.len() < 2 { + return Err(self.err(format!("library path `{display}`: need at least `lib.member`"))); + } + let lib_name = &path[0]; + let lib = module.import_modules.get(lib_name).ok_or_else(|| { + self.err(format!("unknown library `{lib_name}` (import it in frontmatter)")) + })?; + + let mut parent_is_object = false; + let mut node = lib + .functions + .iter() + .find(|f| f.name == path[1]) + .ok_or_else(|| self.err(format!("unknown `{display}`")))?; + for seg in &path[2..] { + parent_is_object = node.is_object(); + node = node + .children + .iter() + .find(|c| c.name == *seg) + .ok_or_else(|| self.err(format!("unknown `{display}`")))?; + } + + if parent_is_object && !node.is_object() { + return Err(self.err(format!( + "`{display}` is an instance method; call it as `var`.{}", + node.name + ))); + } + + let bound = { + let mut dummy_env = Env::new(); + bind_function_args( + self, + lib, + node, + &mut dummy_env, + &node.params, + ev_args, + false, + ) + .map_err(|m| self.err(m))? + }; + let mut call_env = Env::new(); + for (k, v) in bound { + call_env.set(k, v); + } + + self.host.push_call_site_line(self.host.current_line); + let result = self.run_function(lib, node, call_env, &[]); + self.host.pop_call_site_line(); + let result = result?; + if node.is_object() { + Ok(tag_instance(&node.name, result)) + } else { + Ok(result) + } + } + fn eval_method_call( &mut self, module: &Module, @@ -651,8 +728,7 @@ impl Interpreter { .cloned() .ok_or_else(|| self.err(format!("undefined variable `{recv_name}`")))?; let type_name = instance_type_name(&recv).map_err(|m| self.err(m))?; - let obj = find_top(module, &type_name) - .filter(|f| f.is_object()) + let (owner, obj) = find_object_type(module, &type_name) .ok_or_else(|| self.err(format!("unknown object type `{type_name}`")))?; let target = obj .children @@ -668,7 +744,7 @@ impl Interpreter { call_env.set("自".into(), recv.clone()); call_env.set("self".into(), recv); self.host.push_call_site_line(self.host.current_line); - let result = self.run_function(module, target, call_env, &[]); + let result = self.run_function(owner, target, call_env, &[]); self.host.pop_call_site_line(); result } @@ -821,6 +897,23 @@ fn find_top<'a>(module: &'a Module, name: &str) -> Option<&'a Function> { module.functions.iter().find(|f| f.name == name) } +/// Resolve `#` object type by name in the entry module or any imported library. +fn find_object_type<'a>(module: &'a Module, name: &str) -> Option<(&'a Module, &'a Function)> { + module + .functions + .iter() + .find(|f| f.name == name && f.is_object()) + .map(|f| (module, f)) + .or_else(|| { + module.import_modules.values().find_map(|lib| { + lib.functions + .iter() + .find(|f| f.name == name && f.is_object()) + .map(|f| (lib, f)) + }) + }) +} + fn find_function_anywhere<'a>(module: &'a Module, name: &str) -> Option<&'a Function> { for f in &module.functions { if f.name == name { diff --git a/src/load.rs b/src/load.rs index 62fd6ab..fd5cc63 100644 --- a/src/load.rs +++ b/src/load.rs @@ -1,6 +1,6 @@ -//! Load `.mq.md` files and merge frontmatter imports. +//! Load `.mq.md` files and bind frontmatter imports as library modules. -use std::collections::HashSet; +use std::collections::{HashMap, HashSet}; use std::env; use std::path::{Path, PathBuf}; @@ -11,7 +11,7 @@ use crate::diagnostics::Diagnostic; use crate::embedded_lib; use crate::parse::parse_source; -/// Load `path` and recursively merge imported modules' top-level functions. +/// Load `path` and recursively bind imported modules (no flat merge). pub fn load_module(path: &Path) -> Result { let mut visited = HashSet::new(); load_module_inner(path, &mut visited) @@ -25,21 +25,33 @@ fn load_module_inner(path: &Path, visited: &mut HashSet) -> Result Result { @@ -80,49 +92,47 @@ pub fn resolve_import(from_dir: &Path, rel: &str) -> Result { if direct.is_file() { return Ok(direct); } - - let normalized = if let Some(rest) = rel.strip_prefix("std/") { - format!("lib/{rest}") - } else { - rel.clone() - }; - - if let Some(remainder) = normalized.strip_prefix("lib/") { + if let Some(source) = read_embedded_for_path(Path::new(&rel)) { + let _ = source; + // Prefer real file under search roots; else return a virtual lib/ path for embedded read. + } + if rel.starts_with("lib/") || rel.starts_with("std/") { + let rest = rel + .strip_prefix("lib/") + .or_else(|| rel.strip_prefix("std/")) + .unwrap(); for root in lib_search_roots() { - let as_lib_dir = root.join(remainder); - if as_lib_dir.is_file() { - return Ok(as_lib_dir); - } - let as_repo_root = root.join("lib").join(remainder); - if as_repo_root.is_file() { - return Ok(as_repo_root); + let p = root.join(rest); + if p.is_file() { + return Ok(p); } } - if embedded_lib::has_file(remainder) { - return Ok(PathBuf::from("lib").join(remainder)); - } - bail!( - "cannot resolve library import `{rel}` (set MARQDO_LIB, keep lib/ next to the project, or use a binary with embedded stdlib)" - ); + // Embedded stdlib: synthesize a path under lib/ for read_module_source. + return Ok(PathBuf::from("lib").join(rest)); } - - if let Some(remainder) = normalized.strip_prefix("ext/") { + if rel.starts_with("ext/") { for root in ext_search_roots() { - let as_ext_dir = root.join(remainder); - if as_ext_dir.is_file() { - return Ok(as_ext_dir); + let p = root.join(rel.strip_prefix("ext/").unwrap_or(&rel)); + // also try full ext/rel under root + let p2 = root.join(&rel); + if p.is_file() { + return Ok(p); } - let as_repo_root = root.join("ext").join(remainder); - if as_repo_root.is_file() { - return Ok(as_repo_root); + if p2.is_file() { + return Ok(p2); + } + // MARQDO_EXT is the ext root itself (contains ai/) + let under = root.join(rel.strip_prefix("ext/").unwrap()); + if under.is_file() { + return Ok(under); } } - bail!( - "cannot resolve extension import `{rel}` (set MARQDO_EXT or keep an ext/ next to the project)" - ); } - - Ok(direct) + // Relative again with normalize + if direct.exists() { + return Ok(direct); + } + bail!("cannot resolve import `{rel}` from {}", from_dir.display()) } fn lib_search_roots() -> Vec { @@ -132,16 +142,17 @@ fn lib_search_roots() -> Vec { } if let Ok(cwd) = env::current_dir() { roots.push(cwd.join("lib")); - roots.push(cwd); } if let Ok(exe) = env::current_exe() { if let Some(dir) = exe.parent() { roots.push(dir.join("lib")); - roots.push(dir.join("../lib")); - roots.push(dir.join("../../lib")); - roots.push(dir.join("../../../lib")); + roots.push(dir.join("..").join("lib")); + roots.push(dir.join("..").join("..").join("lib")); } } + if let Ok(manifest) = env::var("CARGO_MANIFEST_DIR") { + roots.push(PathBuf::from(manifest).join("lib")); + } roots } @@ -150,41 +161,36 @@ 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); } if let Ok(exe) = env::current_exe() { if let Some(dir) = exe.parent() { roots.push(dir.join("ext")); - roots.push(dir.join("../ext")); - roots.push(dir.join("../../ext")); - roots.push(dir.join("../../../ext")); + roots.push(dir.join("..").join("ext")); + roots.push(dir.join("..").join("..").join("ext")); } } + if let Ok(manifest) = env::var("CARGO_MANIFEST_DIR") { + roots.push(PathBuf::from(manifest).join("ext")); + } roots } fn attach_path(path: &Path, err: anyhow::Error) -> anyhow::Error { - if let Some(d) = err.downcast_ref::() { - if d.path.is_none() { - return Diagnostic::at(path, d.span, d.message.clone()).into(); - } - return err; - } - let msg = err.to_string(); - if let Some((loc, rest)) = msg.split_once(": ") { - if let Some((line_s, col_s)) = loc.split_once(':') { - if let (Ok(line), Ok(col)) = (line_s.parse::(), col_s.parse::()) { - return Diagnostic::at(path, crate::diagnostics::Span::new(line, col), rest).into(); + match err.downcast::() { + Ok(mut d) => { + if d.path.is_none() { + d.path = Some(path.to_path_buf()); } + d.into() } + Err(e) => anyhow::anyhow!("{}: {e}", path.display()), } - err.context(format!("in {}", path.display())) } +/// Kept for tests / tooling that expect a flat list (local tops only). +#[allow(dead_code)] fn merge_top_level(into: &mut Vec, fun: Function) { if let Some(existing) = into.iter_mut().find(|f| f.name == fun.name) { *existing = fun; @@ -209,12 +215,4 @@ mod tests { let p2 = resolve_import(Path::new("tests/keywords"), "std/text.mq.md").unwrap(); assert!(p2.ends_with("text.mq.md")); } - - #[test] - fn resolve_embedded_lib_source() { - let p = resolve_import(Path::new("/nonexistent"), "lib/writeback.mq.md").unwrap(); - assert!(p.to_string_lossy().replace('\\', "/").contains("lib/writeback.mq.md")); - let src = read_module_source(&p).unwrap(); - assert!(src.contains("host_writeback")); - } } diff --git a/src/parse/expr.rs b/src/parse/expr.rs index 75e4b93..448878b 100644 --- a/src/parse/expr.rs +++ b/src/parse/expr.rs @@ -433,7 +433,7 @@ fn is_word_end(s: &str, len: usize) -> bool { } /// Parse `name key=val …` / positional args; returns call + bytes consumed. -/// Callee may be a bare name or method form `` `recv`.method ``. +/// Callee may be a bare name, library path `time.parse`, or method `` `recv`.method ``. pub fn parse_call_tail(s: &str) -> Result<(CallExpr, usize)> { use crate::ast::Arg; @@ -448,9 +448,14 @@ pub fn parse_call_tail(s: &str) -> Result<(CallExpr, usize)> { .to_string() }; - let (receiver, callee) = split_method_callee(&callee_tok) - .map(|(r, m)| (Some(r), m)) - .unwrap_or((None, callee_tok.clone())); + let (receiver, callee, path) = if let Some((r, m)) = split_method_callee(&callee_tok) { + (Some(r), m, None) + } else if let Some(segments) = split_lib_path_callee(&callee_tok) { + let last = segments.last().cloned().unwrap_or_default(); + (None, last, Some(segments)) + } else { + (None, callee_tok.clone(), None) + }; let after_callee_offset = { let idx = s.find(&callee_tok).unwrap(); @@ -486,6 +491,7 @@ pub fn parse_call_tail(s: &str) -> Result<(CallExpr, usize)> { Ok(( CallExpr { callee, + path, receiver, args, }, @@ -512,6 +518,21 @@ fn split_method_callee(tok: &str) -> Option<(String, String)> { Some((recv, method.to_string())) } +/// Bare `time.parse` / `agent.agent` → path segments (len ≥ 2). +fn split_lib_path_callee(tok: &str) -> Option> { + if tok.starts_with('`') || !tok.contains('.') { + return None; + } + let parts: Vec = tok.split('.').map(|s| s.to_string()).collect(); + if parts.len() < 2 { + return None; + } + if parts.iter().any(|p| p.is_empty() || p.contains('`')) { + return None; + } + Some(parts) +} + /// If `s` begins with `ident=`, return (ident, rest_after_eq). fn try_named_arg(s: &str) -> Option<(String, &str)> { let s = s.trim_start(); diff --git a/src/parse/mod.rs b/src/parse/mod.rs index 1cc362b..69a5dca 100644 --- a/src/parse/mod.rs +++ b/src/parse/mod.rs @@ -7,7 +7,7 @@ pub use expr::{parse_call_after_gt, parse_expr, parse_value_or_interp}; use anyhow::{bail, Result}; use crate::ast::{ - BranchArm, Expr, Function, Literal, Module, Stmt, + BranchArm, Expr, Function, Import, Literal, Module, Stmt, Use, }; use crate::diagnostics::{Diagnostic, Span}; use crate::lex::{classify_source, ClassifiedLine, LineKind}; @@ -22,7 +22,7 @@ pub fn parse_source(source: &str) -> Result { pub fn parse_classified(lines: &[ClassifiedLine]) -> Result { let mut cur = Cursor::new(lines); - let imports = cur.parse_frontmatter()?; + let (imports, uses) = cur.parse_frontmatter()?; let mut functions = Vec::new(); while cur.skip_noise() { let Some(line) = cur.peek() else { break }; @@ -36,7 +36,20 @@ pub fn parse_classified(lines: &[ClassifiedLine]) -> Result { ); } } - Ok(Module { imports, functions }) + for u in &uses { + if imports.iter().any(|i| i.bind == u.bind) { + bail!("use bind `{}` conflicts with import library name", u.bind); + } + if functions.iter().any(|f| f.name == u.bind) { + bail!("use bind `{}` conflicts with top-level name", u.bind); + } + } + Ok(Module { + imports, + uses, + functions, + import_modules: std::collections::HashMap::new(), + }) } struct Cursor<'a> { @@ -72,16 +85,17 @@ impl<'a> Cursor<'a> { false } - fn parse_frontmatter(&mut self) -> Result> { + fn parse_frontmatter(&mut self) -> Result<(Vec, Vec)> { let mut imports = Vec::new(); + let mut uses = Vec::new(); if !self.skip_noise() { - return Ok(imports); + return Ok((imports, uses)); } let Some(first) = self.peek() else { - return Ok(imports); + return Ok((imports, uses)); }; if first.text.trim() != "---" { - return Ok(imports); + return Ok((imports, uses)); } self.bump(); while let Some(line) = self.peek() { @@ -91,14 +105,26 @@ impl<'a> Cursor<'a> { break; } if t.starts_with('>') { - let path = t[1..].trim(); - if path.ends_with(".mq.md") { - imports.push(path.to_string()); + let rest = t[1..].trim(); + if let Some(imp) = parse_import_spec(rest) { + if imports.iter().any(|i| i.bind == imp.bind) { + bail!( + "{}:1: duplicate import bind `{}`", + line.line_no, + imp.bind + ); + } + imports.push(imp); + } else if let Some(u) = parse_use_spec(rest) { + if uses.iter().any(|x| x.bind == u.bind) { + bail!("{}:1: duplicate use bind `{}`", line.line_no, u.bind); + } + uses.push(u); } } self.bump(); } - Ok(imports) + Ok((imports, uses)) } fn parse_function(&mut self, min_level: u8) -> Result { @@ -694,6 +720,102 @@ fn parse_heading(trimmed: &str) -> Option<(u8, &str)> { Some((level, name)) } +/// Parse `lib/time.mq.md` / `lib/time.mq.md as time` / `lib/时间.mq.md 作为 时间`. +pub fn parse_import_spec(rest: &str) -> Option { + let rest = rest.trim(); + const SUFFIX: &str = ".mq.md"; + let idx = rest.find(SUFFIX)?; + let path = rest[..idx + SUFFIX.len()].trim().to_string(); + if !path.ends_with(SUFFIX) { + return None; + } + let after = rest[idx + SUFFIX.len()..].trim(); + let bind = if after.is_empty() { + default_import_bind(&path) + } else if let Some(name) = after.strip_prefix("as") { + let name = name.trim(); + if name.is_empty() || name.split_whitespace().count() != 1 { + return None; + } + name.to_string() + } else if let Some(name) = after.strip_prefix("作为") { + let name = name.trim(); + if name.is_empty() || name.split_whitespace().count() != 1 { + return None; + } + name.to_string() + } else { + return None; + }; + Some(Import { path, bind }) +} + +fn default_import_bind(path: &str) -> String { + let path = path.replace('\\', "/"); + let file = path.rsplit('/').next().unwrap_or(path.as_str()); + file.strip_suffix(".mq.md").unwrap_or(file).to_string() +} + +/// Parse `use time.format` / `use time.format as fmt` / `使用 时间.格式化` / `使用 时间.格式化 作为 fmt`. +pub fn parse_use_spec(rest: &str) -> Option { + let rest = rest.trim(); + let after = if rest.starts_with("use") + && rest + .get(3..) + .is_some_and(|s| s.starts_with(|c: char| c.is_whitespace())) + { + rest[3..].trim() + } else if let Some(a) = rest.strip_prefix("使用") { + let a = a.trim(); + if a.is_empty() { + return None; + } + a + } else { + return None; + }; + if after.is_empty() { + return None; + } + + let (path_str, bind_opt) = if let Some((left, right)) = after.split_once(" as ") { + (left.trim(), Some(right.trim())) + } else if let Some((left, right)) = after.split_once(" 作为 ") { + (left.trim(), Some(right.trim())) + } else if let Some((left, right)) = after.split_once("作为") { + let left = left.trim(); + let right = right.trim(); + if left.is_empty() || right.is_empty() { + (after, None) + } else { + (left, Some(right)) + } + } else { + (after, None) + }; + + if path_str.is_empty() || path_str.contains('`') { + return None; + } + let path: Vec = path_str + .split('.') + .map(|s| s.trim().to_string()) + .collect(); + if path.len() < 2 || path.iter().any(|p| p.is_empty()) { + return None; + } + let bind = match bind_opt { + Some(b) => { + if b.is_empty() || b.split_whitespace().count() != 1 || b.contains('.') { + return None; + } + b.to_string() + } + None => path.last()?.clone(), + }; + Some(Use { path, bind }) +} + fn is_heading(trimmed: &str) -> bool { parse_heading(trimmed).is_some() } diff --git a/src/view/render.rs b/src/view/render.rs index 5011e47..868d022 100644 --- a/src/view/render.rs +++ b/src/view/render.rs @@ -174,7 +174,16 @@ pub fn render_module_structure_mode( if !module.imports.is_empty() { out.push_str("
import"); for imp in &module.imports { - out.push_str(&format!("{}", escape(imp))); + let label = format!("{} as {}", imp.path, imp.bind); + out.push_str(&format!("{}", escape(&label))); + } + out.push_str("
"); + } + if !module.uses.is_empty() { + out.push_str("
use"); + for u in &module.uses { + let label = format!("{} as {}", u.path.join("."), u.bind); + out.push_str(&format!("{}", escape(&label))); } out.push_str("
"); } @@ -606,8 +615,12 @@ fn call_display(call: &CallExpr) -> String { s.push_str(recv); s.push('`'); s.push('.'); + s.push_str(&call.callee); + } else if let Some(path) = &call.path { + s.push_str(&path.join(".")); + } else { + s.push_str(&call.callee); } - s.push_str(&call.callee); for a in &call.args { match a { Arg::Positional(e) => { diff --git a/tests/errors/ns-instance-method.mq.md b/tests/errors/ns-instance-method.mq.md new file mode 100644 index 0000000..89dc985 --- /dev/null +++ b/tests/errors/ns-instance-method.mq.md @@ -0,0 +1,8 @@ +--- +title: path to instance method needs receiver +> ../structure/ns/helpers.mq.md +--- + +# main + +> helpers.Box.tag s=x diff --git a/tests/ext/agent-run-live.mq.md b/tests/ext/agent-run-live.mq.md new file mode 100644 index 0000000..8cb826f --- /dev/null +++ b/tests/ext/agent-run-live.mq.md @@ -0,0 +1,56 @@ +--- +title: ext/agent step (DeepSeek) +description: Real agent.step with tool via lib/subtask. Credentials from tests/ext/.env. +> lib/time.mq.md +> lib/writeback.mq.md +> lib/json.mq.md +> ext/ai/llm.mq.md +> ext/ai/agent.mq.md +--- + +## 获取时间 + +*`u` = > time.now_unix * +*`s` = > time.format unix=`u` pattern=%Y-%m-%d * +**`s`** + +# main + +> llm.load_env path=.env + +*`模型` = > llm.llm * + +`工具表` = +| 工具 | +|------| +| 获取时间 | + +*`助手` = > agent.agent model=`模型` tools=`工具表` standing=You are a Marqdo agent. When you need the current date, reply with exactly one line CALL:获取时间 and nothing else. * + +*`out` = > `助手`.step task=请调用获取时间工具,然后用一句话告诉用户今天的日期。 * + +*`status` = > json.get value=`out` key=status * +*`回复` = > json.get value=`out` key=result * +*`body` = > json.stringify value=`out` * + +> print text=`回复` + +1. `status` == ok + > writeback.record value=`body` key=ok + + +2. * + > writeback.record value=`body` key=error + +*`id` = > json.get value=`助手` key=id * +*`历史` = > agent_history_get id=`id` * +*`条数` = > len value=`历史` * +> print text=`条数` + +> `助手`.clear_history + +*`历史2` = > agent_history_get id=`id` * +*`条数2` = > len value=`历史2` * +> print text=`条数2` diff --git a/tests/ext/agent-smoke.mq.md b/tests/ext/agent-smoke.mq.md index 5018900..64679f3 100644 --- a/tests/ext/agent-smoke.mq.md +++ b/tests/ext/agent-smoke.mq.md @@ -1,22 +1,31 @@ --- -title: ext/agent framework smoke (offline) -description: Ctor, context, clear_history — no network. Gold suite. +title: ext/agent framework smoke +description: Real llm handle from tests/ext/.env; context, extract_tool_name, run_tool via subtask. +> ext/ai/llm.mq.md +> lib/json.mq.md > ext/ai/agent.mq.md --- +## 获取时间 + +*`esc` = > json.parse text={"v":"ok-time"} * +**> json.get value=`esc` key=v** + # main +> llm.load_env path=.env + `工具表` = | 工具 | |------| | 获取时间 | -*`占位模型` = > parse text={"_type":"llm"} * -*`助手` = > agent model=`占位模型` tools=`工具表` user_prompt=you are a dispatcher * +*`模型` = > llm.llm * +*`助手` = > agent.agent model=`模型` tools=`工具表` standing=you are a readable Marqdo agent * -*`id` = > get value=`助手` key=id * +*`id` = > json.get value=`助手` key=id * -*`ctx` = > build_agent_context agent=`助手` extra=probe * +*`ctx` = > agent.build_step_context agent=`助手` task=probe * *`has_skill` = > split value=`ctx` sep=Marqdo * *`sk_n` = > len value=`has_skill` * @@ -32,29 +41,47 @@ description: Ctor, context, clear_history — no network. Gold suite. 2. * > print text=tools-missing -*`src` = > host_module_source * -*`has_src` = > split value=`src` sep=probe * +*`has_src` = > split value=`ctx` sep=probe * *`src_n` = > len value=`has_src` * 1. `src_n` > 1 > print text=source-ok 2. * > print text=source-missing -*`turn` = > parse text={"role":"user","content":"one"} * -> host_agent_history_append id=`id` item=`turn` -*`turn2` = > parse text={"role":"assistant","content":"two"} * -> host_agent_history_append id=`id` item=`turn2` +*`has_act` = > split value=`ctx` sep=CALL: * +*`act_n` = > len value=`has_act` * +1. `act_n` > 1 + > print text=protocol-ok +2. * + > print text=protocol-missing -*`h1` = > host_agent_history_get id=`id` * +*`samples` = > json.parse text={"r":"CALL:获取时间","m":"think\nCALL:获取时间"} * +*`raw1` = > json.get value=`samples` key=r * +*`name1` = > agent.extract_tool_name reply=`raw1` * +> print text=`name1` + +*`raw2` = > json.get value=`samples` key=m * +*`name2` = > agent.extract_tool_name reply=`raw2` * +> print text=`name2` + +*`tool_out` = > agent.run_tool tools=`工具表` name=获取时间 * +> print text=`tool_out` + +*`turn` = > json.parse text={"role":"user","content":"one"} * +> agent_history_append id=`id` item=`turn` +*`turn2` = > json.parse text={"role":"assistant","content":"two"} * +> agent_history_append id=`id` item=`turn2` + +*`h1` = > agent_history_get id=`id` * *`n1` = > len value=`h1` * > print text=`n1` > `助手`.clear_history -*`h2` = > host_agent_history_get id=`id` * +*`h2` = > agent_history_get id=`id` * *`n2` = > len value=`h2` * > print text=`n2` -*`site` = > host_call_site * -*`fn` = > get value=`site` key=function * +*`site` = > agent_call_site * +*`fn` = > json.get value=`site` key=function * > print text=`fn` diff --git a/tests/ext/llm-complete.mq.md b/tests/ext/llm-complete.mq.md index c96fb02..d112bfa 100644 --- a/tests/ext/llm-complete.mq.md +++ b/tests/ext/llm-complete.mq.md @@ -1,14 +1,14 @@ --- -title: ext llm DeepSeek complete (live) -description: Live OpenAI-compatible chat via DeepSeek. Needs tests/ext/.env (gitignored). Not in gold suite. +title: ext llm DeepSeek complete +description: OpenAI-compatible chat via DeepSeek. Credentials from tests/ext/.env. > ext/ai/llm.mq.md --- # main -> load_env +> llm.load_env path=.env -*`model` = > llm * +*`model` = > llm.llm * *`reply` = > `model`.complete prompt=Reply with exactly one English word: pong * diff --git a/tests/ext/llm-import.mq.md b/tests/ext/llm-import.mq.md index 0a47311..4fff040 100644 --- a/tests/ext/llm-import.mq.md +++ b/tests/ext/llm-import.mq.md @@ -5,6 +5,6 @@ title: ext llm import # main -> load_env +> llm.load_env > print text=ext-ok diff --git a/tests/gold.rs b/tests/gold.rs index c3a9422..180a6bd 100644 --- a/tests/gold.rs +++ b/tests/gold.rs @@ -113,6 +113,44 @@ fn structure_import() { ); } +#[test] +fn structure_ns_path3() { + assert_out( + "tests/structure/ns/path3.mq.md", + "ok +constructed", + ); +} + +#[test] +fn structure_ns_use() { + assert_out("tests/structure/ns/use.mq.md", "hi"); +} + +#[test] +fn bytecode_ns_path3() { + assert_out_backend( + "tests/structure/ns/path3.mq.md", + "bytecode", + "ok +constructed", + ); +} + +#[test] +fn bytecode_ns_use() { + assert_out_backend("tests/structure/ns/use.mq.md", "bytecode", "hi"); +} + +#[test] +fn error_ns_instance_method() { + assert_err( + "tests/errors/ns-instance-method.mq.md", + "8:1", + "instance method", + ); +} + #[test] fn structure_fn_end_hr() { @@ -686,10 +724,12 @@ fn lib_plugin_demo() { } else { "libdemo.so" }; - let built = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")) - .join("target") - .join("debug") - .join(lib_name); + let target_dir = std::env::var_os("CARGO_TARGET_DIR") + .map(std::path::PathBuf::from) + .unwrap_or_else(|| { + std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("target") + }); + let built = target_dir.join("debug").join(lib_name); assert!( built.is_file(), "missing plugin artifact {}", @@ -775,6 +815,13 @@ fn ext_cli_add_list_remove_llm() { #[test] fn ext_cli_add_agent() { + let status = Command::new("cargo") + .args(["build", "-p", "marqdo_plugin_agent"]) + .current_dir(env!("CARGO_MANIFEST_DIR")) + .status() + .expect("build agent plugin"); + assert!(status.success(), "failed to build marqdo_plugin_agent"); + 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"); @@ -788,12 +835,32 @@ fn ext_cli_add_agent() { assert!(status.success(), "ext add agent failed"); assert!(tmp.join("ai").join("agent.mq.md").is_file()); assert!(tmp.join("ai").join("智能体.mq.md").is_file()); + assert!( + tmp.join("native").join(if cfg!(windows) { + "agent.dll" + } else if cfg!(target_os = "macos") { + "libagent.dylib" + } else { + "libagent.so" + }) + .is_file() + || tmp.join("agent.plugin").is_file(), + "agent native plugin should be installed" + ); } #[test] fn ext_agent_framework_smoke() { + let status = Command::new("cargo") + .args(["build", "-p", "marqdo_plugin_agent"]) + .current_dir(env!("CARGO_MANIFEST_DIR")) + .status() + .expect("build agent plugin"); + assert!(status.success(), "failed to build marqdo_plugin_agent"); + let output = Command::new(env!("CARGO_BIN_EXE_marqdo")) .args(["run", "tests/ext/agent-smoke.mq.md"]) + .current_dir(env!("CARGO_MANIFEST_DIR")) .output() .expect("run agent-smoke"); let code = output.status.code().unwrap_or(1); @@ -802,21 +869,40 @@ fn ext_agent_framework_smoke() { assert_eq!(code, 0, "agent-smoke stderr={stderr}"); assert_eq!( stdout.trim_end(), - "skill-ok\ntools-ok\nsource-ok\n2\n0\nmain", + "skill-ok\ntools-ok\nsource-ok\nprotocol-ok\n获取时间\n获取时间\nok-time\n2\n0\nmain", "agent-smoke" ); } +#[test] +fn ext_llm_complete_live() { + let output = Command::new(env!("CARGO_BIN_EXE_marqdo")) + .args(["run", "tests/ext/llm-complete.mq.md"]) + .output() + .expect("run llm-complete"); + 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, "llm-complete stderr={stderr}"); + let reply = stdout.trim_end().to_lowercase(); + assert!( + reply.contains("pong"), + "expected pong in reply, got {stdout:?}" + ); +} + #[test] fn ext_agent_run_live() { - let env_file = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/ext/.env"); - if !env_file.is_file() { - eprintln!("skip ext_agent_run_live: missing {}", env_file.display()); - return; - } + let status = Command::new("cargo") + .args(["build", "-p", "marqdo_plugin_agent"]) + .current_dir(env!("CARGO_MANIFEST_DIR")) + .status() + .expect("build agent plugin"); + assert!(status.success(), "failed to build marqdo_plugin_agent"); let output = Command::new(env!("CARGO_BIN_EXE_marqdo")) .args(["run", "tests/ext/agent-run-live.mq.md"]) + .current_dir(env!("CARGO_MANIFEST_DIR")) .output() .expect("run agent-run-live"); let code = output.status.code().unwrap_or(1); @@ -826,14 +912,26 @@ fn ext_agent_run_live() { let lines: Vec<&str> = stdout.trim_end().lines().collect(); assert!(lines.len() >= 3, "agent-run-live stdout={stdout}"); assert!( - lines[0].contains('-') && lines[0].chars().any(|c| c.is_ascii_digit()), - "expected time in reply, got {:?}", + lines[0].chars().any(|c| c.is_ascii_digit()), + "expected date in reply, got {:?}", lines[0] ); - assert_eq!(lines[1], "2", "history after run"); + assert_eq!(lines[1], "2", "history after step"); assert_eq!(lines[2], "0", "history after clear"); + // Caller may persist the step map via lib/writeback; agent itself does not write. + let src = std::fs::read_to_string( + std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")).join("tests/ext/agent-run-live.mq.md"), + ) + .expect("read agent-run-live after run"); + assert!( + src.contains("\"status\"") || src.contains("marqdo-out"), + "expected caller writeback of step result map" + ); + assert!( + !stdout.contains("marqdo-out"), + "writeback must not be printed to stdout" + ); } - #[test] fn lib_net_encode() { assert_out("tests/lib/net-encode.mq.md", "a+b"); diff --git a/tests/lib/foreign-python.mq.md b/tests/lib/foreign-python.mq.md index b989ad3..52352ad 100644 --- a/tests/lib/foreign-python.mq.md +++ b/tests/lib/foreign-python.mq.md @@ -10,6 +10,6 @@ title: foreign python hello print("hello-from-python") ``` -*`out` = > run code=`hi` * +*`out` = > foreign.run code=`hi` * > print text=`out` diff --git a/tests/lib/foreign-run-lang.mq.md b/tests/lib/foreign-run-lang.mq.md index b4a096c..76bc56e 100644 --- a/tests/lib/foreign-run-lang.mq.md +++ b/tests/lib/foreign-run-lang.mq.md @@ -5,6 +5,6 @@ title: foreign run_lang # main -*`out` = > run_lang lang=python source=print(2+2) * +*`out` = > foreign.run_lang lang=python source=print(2+2) * > print text=`out` diff --git a/tests/lib/fs-read.mq.md b/tests/lib/fs-read.mq.md index e0729d6..1142358 100644 --- a/tests/lib/fs-read.mq.md +++ b/tests/lib/fs-read.mq.md @@ -5,13 +5,13 @@ title: fs read/exists # main -*`ok` = > exists path=hello.txt * +*`ok` = > fs.exists path=hello.txt * 1. `ok` > print text=exists 2. * > print text=missing -*`t` = > read_text path=hello.txt * +*`t` = > fs.read_text path=hello.txt * > print text=`t` diff --git a/tests/lib/json-quote.mq.md b/tests/lib/json-quote.mq.md index 5e04afa..4bee686 100644 --- a/tests/lib/json-quote.mq.md +++ b/tests/lib/json-quote.mq.md @@ -5,6 +5,6 @@ title: json quote # main -*`q` = > quote text=hi * +*`q` = > json.quote text=hi * > print text=`q` diff --git a/tests/lib/json-roundtrip.mq.md b/tests/lib/json-roundtrip.mq.md index 81cbc0b..f39b4e8 100644 --- a/tests/lib/json-roundtrip.mq.md +++ b/tests/lib/json-roundtrip.mq.md @@ -6,18 +6,18 @@ title: json roundtrip # main -*`raw` = > read_text path=sample.json * +*`raw` = > fs.read_text path=sample.json * -*`obj` = > parse text=`raw` * +*`obj` = > json.parse text=`raw` * *`ty` = > type `obj` * > print text=`ty` -*`a` = > get value=`obj` key=a * +*`a` = > json.get value=`obj` key=a * > print text=`a` -*`out` = > stringify value=`obj` * +*`out` = > json.stringify value=`obj` * > print text=`out` diff --git a/tests/lib/math-formula-chain.mq.md b/tests/lib/math-formula-chain.mq.md index 0bb491c..5af4494 100644 --- a/tests/lib/math-formula-chain.mq.md +++ b/tests/lib/math-formula-chain.mq.md @@ -10,16 +10,16 @@ $$ x^3 $$ -*`df` = > diff formula=`f` var=x * +*`df` = > math.diff formula=`f` var=x * *`ty` = > type `df` * > print text=`ty` -*`df2` = > diff formula=`df` var=x * +*`df2` = > math.diff formula=`df` var=x * > print text=`df2` -*`y` = > eval formula=`df` var=x value=2 * +*`y` = > math.eval formula=`df` var=x value=2 * > print text=`y` diff --git a/tests/lib/math-formula.mq.md b/tests/lib/math-formula.mq.md index 5f9ffb9..2f2117c 100644 --- a/tests/lib/math-formula.mq.md +++ b/tests/lib/math-formula.mq.md @@ -14,14 +14,14 @@ $$ > print text=`ty` -*`df` = > diff formula=`f` var=x * +*`df` = > math.diff formula=`f` var=x * > print text=`df` -*`roots` = > solve formula=`f` var=x * +*`roots` = > math.solve formula=`f` var=x * > print text=`roots` -*`y` = > eval formula=`f` var=x value=3 * +*`y` = > math.eval formula=`f` var=x value=3 * > print text=`y` diff --git a/tests/lib/math-plot.mq.md b/tests/lib/math-plot.mq.md index 649db02..5d60c93 100644 --- a/tests/lib/math-plot.mq.md +++ b/tests/lib/math-plot.mq.md @@ -10,7 +10,7 @@ $$ x^2 $$ -*`svg` = > plot formula=`f` var=x min=-2 max=2 * +*`svg` = > math.plot formula=`f` var=x min=-2 max=2 * *`ok` = > type `svg` * diff --git a/tests/lib/math-random.mq.md b/tests/lib/math-random.mq.md index 6c2917e..b0ebd3d 100644 --- a/tests/lib/math-random.mq.md +++ b/tests/lib/math-random.mq.md @@ -5,15 +5,15 @@ title: math random seed # main -> seed value=42 +> math.seed value=42 -*`a` = > random_int min=1 max=10 * +*`a` = > math.random_int min=1 max=10 * -*`b` = > random_int min=1 max=10 * +*`b` = > math.random_int min=1 max=10 * -> seed value=42 +> math.seed value=42 -*`c` = > random_int min=1 max=10 * +*`c` = > math.random_int min=1 max=10 * > print text=`a` diff --git a/tests/lib/net-encode.mq.md b/tests/lib/net-encode.mq.md index 33a11f0..5f7f44c 100644 --- a/tests/lib/net-encode.mq.md +++ b/tests/lib/net-encode.mq.md @@ -5,6 +5,6 @@ title: net url_encode # main -*`e` = > url_encode text=a b * +*`e` = > net.url_encode text=a b * > print text=`e` diff --git a/tests/lib/plugin-demo.mq.md b/tests/lib/plugin-demo.mq.md index 63af6be..812b680 100644 --- a/tests/lib/plugin-demo.mq.md +++ b/tests/lib/plugin-demo.mq.md @@ -7,9 +7,9 @@ description: Loads demo cdylib; path from MARQDO_TEST_PLUGIN (set by gold harnes # main -*`p` = > env_get name=MARQDO_TEST_PLUGIN * +*`p` = > sys.env_get name=MARQDO_TEST_PLUGIN * -> load path=`p` +> plugin.load path=`p` *`sum` = > demo_add a=1 b=2 * diff --git a/tests/lib/subtask-fn.mq.md b/tests/lib/subtask-fn.mq.md index c005fae..7704569 100644 --- a/tests/lib/subtask-fn.mq.md +++ b/tests/lib/subtask-fn.mq.md @@ -6,11 +6,11 @@ title: subtask spawn fn # main -*`args` = > parse text={"n":21} * +*`args` = > json.parse text={"n":21} * -*`id` = > spawn fn=worker args=`args` * +*`id` = > subtask.spawn fn=worker args=`args` * -*`v` = > wait id=`id` * +*`v` = > subtask.wait id=`id` * > print text=`v` diff --git a/tests/lib/subtask-foreign.mq.md b/tests/lib/subtask-foreign.mq.md index 744d8cb..0b0efba 100644 --- a/tests/lib/subtask-foreign.mq.md +++ b/tests/lib/subtask-foreign.mq.md @@ -10,8 +10,8 @@ title: subtask foreign spawn print(7 + 8) ``` -*`id` = > spawn code=`py` * +*`id` = > subtask.spawn code=`py` * -*`out` = > wait id=`id` * +*`out` = > subtask.wait id=`id` * > print text=`out` diff --git a/tests/lib/subtask-spawn.mq.md b/tests/lib/subtask-spawn.mq.md index 7450095..4cee48d 100644 --- a/tests/lib/subtask-spawn.mq.md +++ b/tests/lib/subtask-spawn.mq.md @@ -5,8 +5,8 @@ title: subtask spawn join # main -*`id` = > spawn path=subtask-child.mq.md * +*`id` = > subtask.spawn path=subtask-child.mq.md * -*`code` = > wait id=`id` * +*`code` = > subtask.wait id=`id` * > print text=done diff --git a/tests/lib/sys-cwd.mq.md b/tests/lib/sys-cwd.mq.md index bfcda48..bf6f61a 100644 --- a/tests/lib/sys-cwd.mq.md +++ b/tests/lib/sys-cwd.mq.md @@ -5,7 +5,7 @@ title: sys cwd # main -*`d` = > cwd * +*`d` = > sys.cwd * *`n` = > len `d` * diff --git a/tests/lib/sys-dotenv.mq.md b/tests/lib/sys-dotenv.mq.md index c3bf72a..19a3518 100644 --- a/tests/lib/sys-dotenv.mq.md +++ b/tests/lib/sys-dotenv.mq.md @@ -6,10 +6,10 @@ title: sys dotenv # main -> write_text path=dotenv-fixture.env text=MARQDO_DOTENV_FIXTURE=loaded +> fs.write_text path=dotenv-fixture.env text=MARQDO_DOTENV_FIXTURE=loaded -> load_dotenv path=dotenv-fixture.env +> sys.load_dotenv path=dotenv-fixture.env -*`v` = > env_get name=MARQDO_DOTENV_FIXTURE * +*`v` = > sys.env_get name=MARQDO_DOTENV_FIXTURE * > print text=`v` diff --git a/tests/lib/time-format.mq.md b/tests/lib/time-format.mq.md index 71d2342..e867bb1 100644 --- a/tests/lib/time-format.mq.md +++ b/tests/lib/time-format.mq.md @@ -5,12 +5,12 @@ title: time format/parse # main -*`s` = > format unix=0 pattern=%Y-%m-%d * +*`s` = > time.format unix=0 pattern=%Y-%m-%d * > print text=`s` -*`u` = > parse text=1970-01-01 00:00:00 pattern=%Y-%m-%d %H:%M:%S * +*`u` = > time.parse text=1970-01-01 00:00:00 pattern=%Y-%m-%d %H:%M:%S * > print text=`u` -> sleep_ms ms=0 +> time.sleep_ms ms=0 diff --git a/tests/lib/writeback-async.mq.md b/tests/lib/writeback-async.mq.md new file mode 100644 index 0000000..83ff8c2 --- /dev/null +++ b/tests/lib/writeback-async.mq.md @@ -0,0 +1,37 @@ +--- +title: async writeback via subtask +description: Fire-and-forget persist_slot with explicit line=; join on exit. +> lib/writeback.mq.md +> lib/subtask.mq.md +> lib/json.mq.md +--- + +## persist_slot + + `key` + + `value` + + `line` + +> writeback.ensure key=ok placeholder=pending line=`line` +> writeback.ensure key=error placeholder=pending line=`line` +> writeback.record value=`value` key=`key` line=`line` +**** + +# main + +*`anchor` = > host_outer_call_line * + + + + + + + +*`wb` = > json.parse text={"key":"ok","value":"async-ok"} * +*`wb` = > json.set map=`wb` key=line value=`anchor` * +> subtask.spawn fn=persist_slot args=`wb` + +> print text=spawned diff --git a/tests/lib/writeback-get.mq.md b/tests/lib/writeback-get.mq.md index 41c357a..0a729f4 100644 --- a/tests/lib/writeback-get.mq.md +++ b/tests/lib/writeback-get.mq.md @@ -5,7 +5,7 @@ title: writeback get # main -*`out` = > get * +*`out` = > writeback.get *