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 *