Compare commits

...
13 Commits
Author SHA1 Message Date
cflmyandCursor 33f8b94bb0 release: v1.1.1 AI stack (llm/agent/metadata) + ship plugins/llm
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:34:08 +08:00
cflmyandCursor 0ed57b6d54 feat(agent): ext APIs, goldens, and docs for MCP/resume/small-llm routing
Wire mcp_connect/list/call, resume_*, and demote Jev in author docs.
Offline goldens cover MCP client, resume, and small-llm/jev-alias route.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:26:55 +08:00
cflmyandCursor c29d48f38c feat(agent): MCP stdio client, resume checkpoints, small-llm router alias
Add agent_mcp_client and agent_resume_* plugin APIs. Treat jev as a
compat alias of small-llm; auto cascade no longer probes MARQDO_JEV.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:26:55 +08:00
cflmyandCursor f1e82ce4e5 feat(llm): optional plugins/llm Transport ABI for chat completions
OpenAI transport prefers llm_chat_completions when the native plugin is
resolvable, and falls back to lib/net HTTP/SSE so CI stays green without the .so.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:26:55 +08:00
cflmyandCursor 2d412e3bba feat(llm): LLMResult.tool_calls from OpenAI-shaped responses
Parse choices[0].message.tool_calls into the ask Result; empty list when
absent. Offline gold covers tool_calls_from.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:07:59 +08:00
cflmyandCursor 46d78c6e15 feat(core): Phase 2 Metadata scope lift (no body ${})
Inject bound frontmatter keys into the entry env as ordinary variables.
Reject body ${env…}; bytecode entry prologue seeds the same locals.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:05:25 +08:00
cflmyandCursor 81a14f9b38 feat(llm): sys.module_source + entry prompt / meta offline paths
Expose entry source via sys.module_source; ask/stream fall back to
prompt_body of the entry document. Add meta-binding and entry-prompt golds.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 19:52:57 +08:00
cflmyandCursor 88dc6d5a54 feat(core): Artifact Metadata Binding (${env|arg|sys|secret})
Load-time resolve of frontmatter bindings into Module.metadata; Secret
masking; sys.meta / --bind; llm ctor prefers meta over env_get.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 19:51:24 +08:00
cflmyandCursor 4a2d89406b fix(agent): preserve llm_free resources under plan force
Stop plan from clobbering an existing resources workbook with an explore
skeleton. Add llm.prompt helpers and agent-plan-preserve gold.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 19:34:05 +08:00
cflmyandCursor d8d435fead feat(ai-stack): metrics, named handles, prompt docs, backends, zero-LLM
Finish ai-stack steps 1–5: model_turn usage, fast/reasoning, type:prompt
load, openai/ollama split, and agent-zero-llm gold. Fix compiled-skill
Marqdo syntax so llm_free await no longer falls through to plan+HTTP.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 19:30:25 +08:00
cflmyandCursor 1f8e61f3bf feat(llm): semantic ask/stream/collect surface (005)
Lift ext/ai/llm from OpenAI HTTP client to an intelligence primitive;
keep complete as compat. Add unified ai-stack roadmap linking agent + llm.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 13:35:38 +08:00
cflmyandCursor a9ee858f53 feat(agent): Skill Compilation + Adaptive Routing (v2/P4)
Episode → maybe_learn → llm_free skills, plus abstract router backends
(marqdo/small-llm/jev?/llm/auto) via plugins/agent; no core host changes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 13:28:50 +08:00
cflmyandCursor 8489d90926 docs(public): 新增 feature 18 —— AI 原生闭环(契约 + MLSP)中英各一篇
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 13:46:03 +08:00
81 changed files with 12328 additions and 281 deletions

No files matched your search

+5 -3
View File
@@ -201,7 +201,7 @@ import clock:lib/time.mq.md
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum|linalg` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below); **`ext/linalg`** — formula-first linear algebra (see below).
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum|linalg` (see `doc/design/ext-cli.md`). **`ext/llm`** — intelligence primitive (`ask` / `stream` / `collect`; `complete` is compat); **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below); **`ext/linalg`** — formula-first linear algebra (see below).
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`).
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
@@ -217,10 +217,12 @@ Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --releas
1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag.
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only.
4. **Skill Compilation (v2)** — successful runs become `.mq.md` episodes; after enough evidence, `maybe_learn` compiles an executable skill (`llm_free`). Prefer `## run` over bare `## plan` when you want learning.
5. **Adaptive Routing (P4)** — router is abstract (`marqdo` / `small-llm` / `llm` / `auto`); `jev` is a compat alias of `small-llm`. Decision via `router_model` (any llm handle). Policy Compilation writes `policies/router.mq.md`.
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import).
APIs: `# agent` / `# 智能体` → `## run` / `## route` / `## step` / `## plan` (+ `resolve` / `record_episode` / `maybe_learn` / `compile` / `compile_policy` / `metrics`). Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import).
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) · v2: [doc/next/003.md](../../doc/next/003.md) · P4: [doc/next/004.md](../../doc/next/004.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
## Official extension: `ext/web` (dynamic sites)
+12 -10
View File
@@ -38,7 +38,7 @@ jobs:
run: |
export PATH="/c/ProgramData/mingw64/mingw64/bin:/c/ProgramData/chocolatey/lib/mingw/tools/install/mingw64/bin:$PATH"
cargo build --release
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm
bash ./scripts/build-web-plugin.sh
- name: Checkout extension sources (branch vscode-extension only)
@@ -87,6 +87,7 @@ jobs:
Copy-Item target/release/agent.dll "$stageNative/native/agent.dll"
Copy-Item target/release/quantum.dll "$stageNative/native/quantum.dll"
Copy-Item target/release/linalg.dll "$stageNative/native/linalg.dll"
Copy-Item target/release/llm.dll "$stageNative/native/llm.dll"
if (Test-Path "dist/$nativeZip") { Remove-Item "dist/$nativeZip" -Force }
Compress-Archive -Path "$stageNative/*" -DestinationPath "dist/$nativeZip" -Force
$stage = "dist/stage-bundle"
@@ -100,6 +101,7 @@ jobs:
Copy-Item target/release/agent.dll "$stage/ext/native/agent.dll"
Copy-Item target/release/quantum.dll "$stage/ext/native/quantum.dll"
Copy-Item target/release/linalg.dll "$stage/ext/native/linalg.dll"
Copy-Item target/release/llm.dll "$stage/ext/native/llm.dll"
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
$stageLib = "dist/stage-stdlib"
@@ -124,12 +126,12 @@ jobs:
## Marqdo ${{ github.ref_name }}
### 亮点 / Highlights
- **v1.1.0**:AI 原生闭环三件套——核心表面守卫(问题一)· 渐进式契约 + `marqdo check`(问题二)· **MLSP for AI**(`marqdo mlsp`:locate/syntax/validate/repair_targets/repair_apply/schema,AI 按需查语法而非背诵)(问题三)· `run --json` 结构化诊断
- **v1.1.0**: AI-native loop — core-surface guard, progressive contracts + `marqdo check`, **MLSP for AI** (`marqdo mlsp`: query syntax on demand instead of memorizing), `run --json` structured diagnostics
- **v1.0.7**:WS/网络边界加固(同源握手、require_auth/需要登录、消息上限、HTTP 8 MiB 截断);`url_encode` `%20`
- **v1.0.3**:Ubuntu PPA + 扩展 CDN(ext.marqdo.com);CLI/扩展可分发;noble 捆绑 Rust 工具链
- **v1.0.3**: Ubuntu PPA + extension CDN; independent CLI/ext packs; bundled Rust for noble
- **v1.0.1**:修复 Go `libweb` 动态路由 `{param}` 查询代入、详情 Markdown、CSS 数字误报
- **v1.1.1**:AI 栈收口——llm `ask`/`stream`/`collect` · Metadata Binding · Skill Compilation + Adaptive Routing · MCP 客户端 + resume · 可选 `plugins/llm`
- **v1.1.1**: AI stack — llm ask/stream/collect, Metadata Binding, Skill Compilation + Adaptive Routing, MCP client + resume, optional plugins/llm
- **v1.1.0**:AI 原生闭环三件套——核心表面守卫 · 渐进式契约 + `marqdo check` · **MLSP for AI** · `run --json`
- **v1.1.0**: AI-native loop — core-surface guard, progressive contracts + `marqdo check`, **MLSP for AI**, `run --json`
- **v1.0.7**:WS/网络边界加固;`url_encode` `%20`
- **v1.0.3**:Ubuntu PPA + 扩展 CDN(ext.marqdo.com)
- **Linux 包必出**:`*-native-x86_64-unknown-linux-gnu.zip` + Linux CLI bundle
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [mapping v0.3](https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping-v0.3.md)
@@ -139,7 +141,7 @@ jobs:
|-------|----------|
| `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib |
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` + `ext/`(含 native DLL) |
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`(Windows DLL + **Linux .so 必出**) |
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`/`llm`(Windows DLL + **Linux .so 必出**) |
| `marqdo-*-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + native `.so` |
| `marqdo-*-stdlib.zip` | `lib/` only |
| `marqdo-*-ext.zip` | Official `ext/` L1 sources |
@@ -184,7 +186,7 @@ jobs:
run: |
set -euo pipefail
cargo build --release
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm
bash ./scripts/build-web-plugin.sh
- name: Package Linux native zip + CLI bundle
@@ -193,7 +195,7 @@ jobs:
VER="${GITHUB_REF_NAME#v}"
TARGET="x86_64-unknown-linux-gnu"
mkdir -p dist/stage-native/native
for lib in libweb.so libagent.so libquantum.so liblinalg.so; do
for lib in libweb.so libagent.so libquantum.so liblinalg.so libllm.so; do
src="target/release/${lib}"
if [[ ! -f "$src" && "$lib" == libweb.so ]]; then
src="plugins/web/build/libweb.so"
+45
View File
@@ -1,5 +1,50 @@
# Changelog
## Unreleased
### Added
### Fixed
### Changed
## v1.1.1 — 2026-09-24
### Highlights
**AI 栈收口(agent + llm)**:语义 `ask`/`stream`/`collect`、Artifact Metadata Binding、Skill Compilation + Adaptive Routing、MCP 客户端与 resume 检查点、可选 `plugins/llm` Transport ABI。
本版 CLI 与扩展包 **同步为 1.1.1**。
- **LLM 原语**:`ext/ai/llm` 从 OpenAI HTTP 客户端提升为 `ask`/`stream`/`collect` 智能原语(`complete` 保留兼容);`LLMResult.tool_calls`;可选原生 `llm_chat_completions`(无 `.so` 时回退 `lib/net`)。
- **Metadata Binding**:frontmatter `${env|arg|sys|secret}` 加载期解析;Phase 2 将绑定键注入入口 env(正文禁止 `${…}`);`sys.meta` / `--bind`;llm ctor 优先 meta。
- **Agent**:Skill Compilation(episode → llm_free skills)+ Adaptive Routing(`marqdo` / `small-llm` / `llm` / `auto`;`jev` 为 `small-llm` 兼容别名);MCP **stdio 客户端**;resume 检查点;零 LLM 金样路径。
- **度量与后端**:`model_turn` usage、named handles(fast/reasoning)、`type:prompt` 加载、openai/ollama 分流。
```bash
# Ubuntu PPA / 源码
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
git checkout v1.1.1 && cargo build --release
marqdo ext add llm && marqdo ext add agent
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime**(Metadata Binding、LLM/agent 插件与扩展)变更,不触碰语言标记。
### Added
- **`ext/ai/llm` 语义表面**:`ask` / `stream` / `collect`(`complete` 兼容);`LLMResult.tool_calls`(OpenAI-shaped `choices[0].message.tool_calls`);`sys.module_source` + 入口文档 `prompt_body` 离线路径。
- **`plugins/llm` Transport ABI**(`llm_chat_completions`):`ext/ai/llm/openai` 优先原生插件,否则 `lib/net` HTTP/SSE。
- **Artifact Metadata Binding**:frontmatter `${env|arg|sys|secret}` → `Module.metadata`;Secret 掩码;`sys.meta` / `--bind`;Phase 2 入口 env 注入(正文拒绝 `${…}`;字节码 prologue 同源)。
- **Agent Skill Compilation + Adaptive Routing**:episode → `maybe_learn` → llm_free skills;路由后端 `marqdo` / `small-llm` / `llm` / `auto`(`jev` = `small-llm` 兼容别名,不再探测 `MARQDO_JEV`)。
- **Agent MCP stdio 客户端**(`agent_mcp_client` / `mcp_connect` / `mcp_client_list` / `mcp_client_call`)+ Python mock 离线金样。
- **Agent resume 检查点**(`.marqdo/agent-resume/<id>.json` — save/load/clear/list;`run` 可设 `resume_id=`)。
- **AI 栈度量与后端**:`model_turn` usage、named handles(fast/reasoning)、`type:prompt` 加载、openai/ollama 分流、agent-zero-llm 金样。
### Fixed
- **plan force 不再冲掉已有 `resources` workbook**(保留 llm_free 资源;金样 `agent-plan-preserve`)。
- **compiled-skill Marqdo 语法**:llm_free await 不再误落到 plan+HTTP。
### Changed
- Adaptive Routing:决策面为 `router_model`(任意 llm handle);`jev` 降为 `small-llm` 文档/兼容别名。
## v1.1.0 — 2026-09-23
### Highlights
Generated
+12 -2
View File
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "marqdo"
version = "1.1.0"
version = "1.1.1"
dependencies = [
"anyhow",
"assert_cmd",
@@ -603,7 +603,7 @@ dependencies = [
[[package]]
name = "marqdo-wasm"
version = "1.1.0"
version = "1.1.1"
dependencies = [
"marqdo",
"serde_json",
@@ -632,6 +632,16 @@ dependencies = [
"serde_json",
]
[[package]]
name = "marqdo_plugin_llm"
version = "0.1.0"
dependencies = [
"idna_adapter",
"serde_json",
"ureq",
"zeroize",
]
[[package]]
name = "marqdo_plugin_quantum"
version = "0.1.0"
+2 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "1.1.0"
version = "1.1.1"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -58,6 +58,7 @@ getrandom = { version = "=0.2.17", default-features = false, features = ["custom
members = [
"plugins/demo",
"plugins/agent",
"plugins/llm",
"plugins/quantum",
"plugins/linalg",
"crates/marqdo-wasm",
+12 -11
View File
@@ -142,9 +142,10 @@ marqdo catalog public -o .marqdo
---
## 现状(v1.1.0)
## 现状(v1.1.1)
- **AI 原生闭环(v1.1.0 新增)**:核心表面守卫(19 构造,单边改动 CI 必红)· **渐进式契约**(文档内嵌 `参数`/`返回`/`字段` 表 + 四边界校验 + `marqdo check` 防漂移)· **MLSP for AI**(`marqdo mlsp`:`locate`/`syntax`/`validate`/`repair_targets`/`repair_apply`/`schema`,AI 按需查语法而非背诵)· **结构化诊断**(`run --json`,错误即数据);验证见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)
- **AI 栈(v1.1.1)**:`ext/ai/llm` 语义 `ask`/`stream`/`collect` · Artifact Metadata Binding(`${env|arg|sys|secret}`)· Agent Skill Compilation + Adaptive Routing · MCP stdio 客户端 + resume 检查点 · 可选 `plugins/llm` Transport ABI
- **AI 原生闭环(v1.1.0)**:核心表面守卫(19 构造,单边改动 CI 必红)· **渐进式契约**(文档内嵌 `参数`/`返回`/`字段` 表 + 四边界校验 + `marqdo check` 防漂移)· **MLSP for AI**(`marqdo mlsp`:`locate`/`syntax`/`validate`/`repair_targets`/`repair_apply`/`schema`,AI 按需查语法而非背诵)· **结构化诊断**(`run --json`,错误即数据);验证见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)
- 映射与解释器:**v0.3 语法宪法**(`**` 代码 / `*` 返回 / 叙述声明);Phase I 树遍历 + 字节码后端;金样例在 `tests/` 与 `tests/markup-v03/`
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
@@ -156,16 +157,16 @@ marqdo catalog public -o .marqdo
- **`web`**:W0–W7 + P3 + **W8**;**定制 C0–C4**;**宿主 H1–H2**(`proxy`/`invoke`,见 [ext-hosting.md](doc/roadmap/ext-hosting.md));**表驱动引言**(`compose_intro` / `引言装配`);原生层默认 **Go `libweb`**([ADR 0004](doc/adr/0004-web-plugin-go.md),`scripts/build-web-plugin.sh`);示例 [web-site](examples/web-site/) · [web-site-zh](examples/web-site-zh/) · [marqdo-blog](examples/marqdo-blog/) · [anlian-mq](examples/anlian-mq/);生产路径见 [web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)
- **`quantum`**:Q0–Q7 + Q8a/b 主题 SVG;示例 [quantum-entanglement](examples/quantum-entanglement/)
- **`linalg`**:L0–L6 + 公式文档面(中缀 / `declare` / 展示化简);示例 [linalg-transpose](examples/linalg-transpose/) · [linalg-svd](examples/linalg-svd/) · [linalg-least-squares](examples/linalg-least-squares/)
- **`agent`**:A1–A4 + **MCP Server stdio**(`mcp_server`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
- **`llm`**:OpenAI 兼容对话
- **`agent`**:A1–A4 + **MCP Server/Client stdio** + Skill Compilation + Adaptive Routing + resume;宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
- **`llm`**:语义 `ask`/`stream`/`collect`(OpenAI/Ollama;可选原生 `plugins/llm`)
- 安装:`marqdo ext list` / `add …` / `remove`([ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum,linalg}`(`web` 为 Go;其余为 Rust)
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum,linalg,llm}`(`web` 为 Go;其余为 Rust)
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
### 如何使用最新 Marqdo(v1.1.0)
### 如何使用最新 Marqdo(v1.1.1)
**安装解释器(任选其一)**
@@ -180,7 +181,7 @@ marqdo catalog public -o .marqdo
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v1.1.0 # 或留在 main
git checkout v1.1.1 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -193,7 +194,7 @@ marqdo view public --no-open
marqdo debug public --no-open
marqdo catalog public -o .marqdo
# 2b) AI 原生闭环(v1.1.0):契约检查 / 结构化诊断 / MLSP 查询
# 2b) AI 原生闭环(v1.1.0+):契约检查 / 结构化诊断 / MLSP 查询
marqdo check tests/contracts/ok_contract.mq.md # 静态契约防漂移
marqdo run tests/structure/hello.mq.md --json # 结构化诊断(错误即数据)
printf '{"id":1,"method":"syntax","params":{"query":"返回"}}\n' | marqdo mlsp
@@ -203,8 +204,8 @@ marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native(
marqdo ext add agent # 或:智能体
marqdo ext add quantum # 或:量子
marqdo ext add linalg # 或:线性代数
marqdo ext add llm # 或:大模型(纯 .mq.md)
# 开发者:cargo build --release -p marqdo_plugin_{agent,quantum,linalg}
marqdo ext add llm # 或:大模型(.mq.md + 可选 native llm)
# 开发者:cargo build --release -p marqdo_plugin_{agent,quantum,linalg,llm}
# bash ./scripts/build-web-plugin.sh # 需 Go + cgo → libweb
# 离线:解压 Windows zip(已含 ext/native)或手动放下 native zip;MARQDO_EXT_NO_DOWNLOAD=1
@@ -219,7 +220,7 @@ marqdo wasm build
# → dist/wasm/ … 见 examples/browser-hello/
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
# https://github.com/cflmy/marqdo/releases/tag/v1.1.0
# https://github.com/cflmy/marqdo/releases/tag/v1.1.1
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo-wasm"
version = "1.1.0"
version = "1.1.1"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
+8
View File
@@ -1,3 +1,11 @@
marqdo (1.1.1-1ppa1) noble; urgency=medium
* Marqdo 1.1.1: AI stack closure — llm ask/stream/collect, Metadata Binding,
Skill Compilation + Adaptive Routing, MCP stdio client + resume checkpoints,
optional plugins/llm Transport ABI (fallback lib/net).
-- cflmy <pingan@cflmy.cn> Thu, 24 Sep 2026 20:32:00 +0800
marqdo (1.1.0-1ppa1) noble; urgency=medium
* Marqdo 1.1.0: core surface guard + progressive contracts + MLSP for AI.
+42
View File
@@ -0,0 +1,42 @@
# ADR 0006:Artifact Metadata Binding(`${…}` 进核心 · Metadata-only)
| | |
|---|---|
| Status | **Accepted** |
| Date | 2026-09-24 |
| Related | [binding.md](../design/binding.md) · [core-surface.md](../design/core-surface.md) · [layers.md](../design/layers.md) · [doc/next/006.md](../next/006.md) |
## Context
- Executable Document 需要声明「依赖哪些外部运行时资源」(模型名、API 密钥、base URL),而不是在 `ext/*` 里各自 `sys.env_get`。
- [doc/next/006.md](../next/006.md) 提出 **Marqdo Binding**(`${namespace.name}`)与 Artifact Metadata 统一解析。
- [layers.md](../design/layers.md):Language 层变更须 ADR;核心构造计数只许持平或下降;默认进 ext。
- 正文插值会与 `$$…$$` 公式面冲突,且会新增内联构造压力。
## Decision
1. 采纳 **Artifact Metadata Binding** 为 Language 层能力;正式规范见 [binding.md](../design/binding.md)。
2. **`${…}` 仅**在文件头 `---` Metadata 中生效;正文 / 粗体 / 调用 / 表 / 叙述 **永不**写 Binding Expression(否决 [006 §17](../next/006.md))。
3. **不**把 Binding 记入 [core-surface.md](../design/core-surface.md) 的 19 构造守卫表——与 `import` 同属 §4「其它语言面」。
4. 核心只做声明与解析;扩展(如 `ext/ai/llm`)消费已绑定的 `Module.metadata` / `sys.meta*` / 入口提升变量。
5. 第一版 namespace:`env` · `arg` · `sys` · `secret`。`config` / `file` 推迟。
6. 加载期一次 resolve → Bound Artifact;`Value::Secret` 遮掩展示;`sys.env_get` 保留为逃逸口。
7. **Phase 2**:入口执行前把 metadata 键提升为普通变量(形参/赋值可覆盖);正文用 `` `model` ``,不再 `${env…}`。
## Consequences
### Positive
- 配置成为文档的一部分;LLM / agent / 其它 ext 共用同一套 Binding,避免各写一套 getenv。
- 缺失 `!` 在加载期失败,而不是运行到 HTTP 401。
- 不膨胀 CORE_CONSTRUCTS;与公式 `$$` 无冲突。
- 正文保持普通变量语义,不引入第二套环境变量语法。
### Negative / Risks
- Secret 在 `Text + Secret` 拼接时会揭示明文(供 Authorization);须约束日志面。
- metadata 键与业务变量同名时依赖「形参/赋值覆盖」规则,作者需注意命名。
### Neutral
- `#` / `##` / `**` / `*` 等核心标记不变;frontmatter `import` 句法不变。
+186
View File
@@ -0,0 +1,186 @@
# Marqdo Binding · Artifact Metadata
| | |
|---|---|
| 状态 | **Accepted · Phase 1 + Phase 2(scope lift)** |
| 日期 | 2026-09-24 |
| ADR | [0006-artifact-metadata-binding.md](../adr/0006-artifact-metadata-binding.md) |
| 讨论稿 | [doc/next/006.md](../next/006.md) |
| 实现 | `src/binding/` · `Module.metadata` · entry env lift · `sys.meta` / `sys.meta_get` · `marqdo run --bind` |
> **边界**:核心负责「声明与解析配置」;扩展负责「解释配置的语义」。
> **`${…}` 只出现在文件头 Artifact Metadata**——正文 / 粗体 / 调用 / 表 **永不**写 `${env…}`(否决讨论稿 §17)。正文使用已绑定的普通名字。
---
## 1. Artifact Metadata
文件开头成对 `---` 之间为 **Artifact Metadata**(声明式元信息环境),不是「随便贴的 YAML」。
```text
.mq.md
├── Metadata ← Identity / Configuration / Dependencies / Bindings
└── Executable Body
```
- `import bind:…` / `导入` 行:模块依赖(既有语义不变)。
- 其它 `key: value` 行:元信息;值可为字面量或 **Binding Expression**。
- Phase 1 仅支持 **flat** 键(同级 `key: value`);块标量 `>` / `|` 收成 Text。
例:
```yaml
---
title: demo
type: llm
model: ${env.OPENAI_MODEL ?? "gpt-4o-mini"}
api_key: ${secret.OPENAI_API_KEY!}
base_url: ${env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}
import sys:lib/sys.mq.md
---
```
加载后内部为已绑定的 `Module.metadata`(确定性快照),执行期不再对同一键反复 `getenv`。
---
## 2. Binding Expression
外形:
```text
${expression}
```
### 2.1 路径
```text
${namespace.name}
```
| Namespace | 意义 | Phase 1 |
|-----------|------|---------|
| `env` | 进程环境变量 | ✅ |
| `arg` | CLI / Runtime 绑定(`marqdo run --bind KEY=VALUE`) | ✅ |
| `sys` | 系统信息:`cwd` · `platform` | ✅ |
| `secret` | 敏感环境变量 → `Value::Secret` | ✅ |
| `config` | 配置 Artifact | 推迟 |
| `file` | 外部文件内容 | 推迟 |
### 2.2 默认与必需
```text
${env.OPENAI_MODEL ?? "gpt-4o-mini"}
${secret.OPENAI_API_KEY!}
```
- `A ?? B`:A 缺失(未设置 / 空)则用 B。
- `A!`:A 必须存在,否则加载失败(`config.required_binding_missing`)。
### 2.3 类型转换
```text
${int(env.MAX_TOKENS ?? "4096")}
${float(env.TEMPERATURE ?? "0.2")}
${bool(env.STREAM ?? "false")}
```
### 2.4 独占 value vs 插值
| 形态 | 语义 |
|------|------|
| `model: ${env.OPENAI_MODEL}` | **Value binding** — 保留解析后的类型(含 Secret) |
| `title: "Hello ${env.USER}"` | **Interpolation** — 结果为 Text |
| `model: gpt-4o-mini` | **Literal** — 字面量;**不会**被环境变量静默覆盖 |
---
## 3. Resolution Policy
对每个 metadata 键:
1. 解析该键的字面量 / Binding / 插值(字面量定稿后不受 env 覆盖)。
2. 若 CLI 提供了同名 `--bind KEY=VALUE`,**覆盖**该键的最终值(Text)。
3. Binding 内部查找顺序(仅当表达式写出时):`arg` / `env` / `secret` / `sys` 按表达式 namespace;`??` 链从左到右。
推荐作者意图:
```text
CLI --bind
→ Artifact 字面量 / 已写死的 Binding 结果
→ Binding 源(env / secret / …)
→ ?? 默认
```
---
## 4. Secret
`${secret.NAME}` → `Value::Secret`。
- `print` / `str` / Display → `<secret>`(不泄露)。
- `type` → `secret`。
- 与 Text 拼接(如 `bearer + api_key`)时**揭示**明文,供 HTTP Authorization。
- 不得进入普通 episode / 错误信息明文(扩展作者责任;核心 Display 已遮掩)。
---
## 5. Runtime API
| API | 语义 |
|-----|------|
| `sys.meta` / `系统.元信息` | 入口模块已绑定 metadata(map) |
| `sys.meta_get` / `系统.取元信息` | `key=` → 值或 `None` |
| `marqdo run FILE --bind KEY=VALUE` | 可重复;写入 `arg` 并覆盖同名 metadata 键 |
| `sys.env_get` | **保留**逃逸口;新代码优先 Metadata Binding |
---
## 6. 错误
| code | 何时 |
|------|------|
| `config.required_binding_missing` | `${ns.name!}` 且源缺失 |
| `config.unknown_binding_ns` | 未知 namespace |
| `config.bad_binding` | 表达式非法 / cast 失败 |
诊断尽量带 frontmatter 行号。
---
## 7. 与扩展的分工
- **核心**:解析 Metadata、resolve Binding、暴露 `Module.metadata` / `sys.meta*`,并在入口把 metadata **提升为普通变量**。
- **`ext/ai/llm`**:构造次序为 **显式实参 → 入口作用域同名变量 / `sys.meta_get` → `sys.env_get` 回退 → 默认**。
---
## 8. Phase 2 · Metadata scope lift(Accepted)
加载期绑定完成后,入口执行(`# main` 或唯一无参顶层对象)前,把 `Module.metadata` 的每个键注入 entry 环境,成为**普通变量**:
```yaml
---
model: ${env.ModelName ?? "gpt-4o-mini"}
---
```
```marqdo
# main
> print text=`model`
```
### 规则
1. 注入时机:进入入口函数之前。
2. 冲突:形参 / 调用实参 **覆盖** 同名 metadata;程序内赋值亦然。metadata **不**覆盖已存在的绑定。
3. `sys.meta` / `sys.meta_get` 仍可用(显式通道)。
4. **拒绝** 正文 / 粗体 / 表 / 叙述中的 `${…}`(讨论稿 006 §17 否决)。普通语言也不在语句里 `${ENV}`。
### 仍推迟(P3+)
- `config` / `file` namespace
- 嵌套 YAML map
- 显式 `override:` 糖
- 计入 `CORE_CONSTRUCTS`
+1 -1
View File
@@ -44,4 +44,4 @@
## 4. 范围外(进 Language 层,但不在本守卫)
frontmatter YAML(元信息)与 `import` 行(模块装载)属于 Language 层的其它语言面,随 [layers.md](layers.md) 准入流程登记,暂不进本清单守卫;如需一并守卫,走 ADR 扩表。
frontmatter / Artifact Metadata(元信息)、`import` 行(模块装载)、以及 Metadata 内的 **Binding Expression**(`${ns.name}`,见 [binding.md](binding.md) · [ADR 0006](../adr/0006-artifact-metadata-binding.md))属于 Language 层的其它语言面,随 [layers.md](layers.md) 准入流程登记,**暂不进本清单守卫**(不增 CORE_CONSTRUCTS 计数)。Phase 2 将已绑定 metadata **提升为入口普通变量**(仍非新标记)。如需一并守卫,走 ADR 扩表。
+15
View File
@@ -180,11 +180,26 @@ ext/
| 中文 | 英文 | 角色 |
|------|------|------|
| `# 智能体` | `# agent` | 构造:`大模型`/`model`,`工具`/`tools`,可选 `站立提示`/`standing` |
| `## 运行` | `## run` | **v2 主入口**:Adaptive `route` → execute → record episode → maybe_learn(技能 + 策略) |
| `## 单步` | `## step` | 原子执行;注入源码 + 位置;可选工具;返回结构化 map;**默认自动写回**(`写回=` / `writeback=` 可关) |
| `## 多步` | `## plan` | 建/续工作簿 → subtask 跑文件 → 修订循环 → 汇总(见 [ext-agent-plan.md](ext-agent-plan.md)) |
| `## 解析` | `## resolve` | 技能解析:exact → alias → canonical → near |
| `## 路由` | `## route` | **P4 Adaptive Routing**:`marqdo` \| `small-llm` \| `llm` \| `auto`(`jev` 为 `small-llm` 兼容别名) |
| `## 应用路由` | `## route_apply` | 将小模型/大模型路由回复(`SKILL:<slug>` / `EXPLORE`)落到 kb 技能 |
| `## 编译策略` | `## compile_policy` | Policy Compilation → `policies/router.mq.md` |
| `## 记录情景` | `## record_episode` | 每次执行沉淀为 `.mq.md` episode(`.marqdo/agent-memory/`) |
| `## 尝试学习` | `## maybe_learn` | 情景足够时归纳 → 合成 → 编译技能,并尝试编译策略 |
| `## 编译` | `## compile` | 候选技能 → 版本化 `skills/<slug>/vN.mq.md` + 可选 OKF promote |
| `## 指标` | `## metrics` | Reasoning amortization(`avg_llm_calls` / `compiled_runs`) |
| `## 分解` | `## decompose` |(可公开或内部)目标 → 子任务表 |
| `## 清空历史` | `## clear_history` | 若仍保留会话式辅助状态则清空;**不以隐藏 chat 袋为真相源**——真相在文档写回 |
**Skill Compilation(v2)**:Agent 的记忆不是向量袋,而是可执行 `.mq.md`。路径:`episodes/` → `experiences/` → `candidates/` → `skills/vN.mq.md` → OKF `agent-kb`(`llm_free`)。编译技能正文为合法 Marqdo(`**result = …**` + 斜体返回);金样 `tests/ext/agent-zero-llm.mq.md` 验收 policy+skill 全路径 `execution.llm_calls=0`。`plan` 对已存在的 `resources/<slug>.mq.md` **不覆盖**(`agent-plan-preserve`)。
**LLM 成本**:`model_turn` 走 `model.ask` / `stream`+`collect`,把 `LLMResult.tokens` 写入 episode / `execution`。
**Adaptive Routing(P4)**:Router 是抽象能力,backend = `marqdo`(已编译 `policies/router.mq.md`)/ `small-llm`(`router_model` 任意 llm 句柄)/ `llm` / `auto` 级联。`jev` 仅为 `small-llm` 兼容别名,**不进入框架专属设计**。热路径在 **`plugins/agent`**(`route.rs`);**禁止**向 `src/host/` 加领域原语。设计:[doc/next/003.md](../next/003.md) · [doc/next/004.md](../next/004.md)。
构造参数(v1):
| 参数 | 说明 |
+74 -51
View File
@@ -2,13 +2,21 @@
| | |
|---|---|
| Status | Accepted (v0.1.x) |
| Date | 2026-08-06 |
| Related | [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) |
| Status | **Accepted · v0.3 semantic**(005:Intelligence Primitive) |
| Date | 2026-09-24 |
| Related | [objects.md](objects.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) · [ai-stack.md](../roadmap/ai-stack.md) · [doc/next/005.md](../next/005.md) |
## Scope
`ext/ai/` holds **official LLM + agent** extensions. Import paths:
`ext/ai/llm` is Marqdo’s **intelligence primitive**, not an OpenAI SDK wrapper.
```text
Author surface: ask / stream / collect / create / fast / reasoning / prompt_load
Transport: ext/ai/llm/openai.mq.md (+ ollama defaults)
Compat: complete / chat
```
Import:
```markdown
---
@@ -16,70 +24,85 @@ import llm:ext/ai/llm.mq.md
---
```
Resolution: `MARQDO_EXT/ai/…`, repo `ext/ai/…`, cwd `ext/ai/…` (see [ext-cli.md](ext-cli.md)).
Other official ext: [ext-agent.md](ext-agent.md) / [ext-agent-plan.md](ext-agent-plan.md) (**document-driven agent** — step with default writeback / plan workbook; thin `TOOL:` loop superseded). Installer: [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md).
Streaming: `complete stream=True` returns an event list (`reasoning` / `delta` / `done` / `error`); `echo=True` prints thinking (`reasoning_content`) and answer tokens as they arrive. See [agent-streaming.md](../roadmap/agent-streaming.md). Default (`stream=False`) is unchanged (answer string).
**Note:** Prefer `marqdo ext add llm`. Import `import llm:ext/ai/llm.mq.md` from repo or install root.
## Platform prerequisites
| Capability | Surface |
|------------|---------|
| HTTPS + headers | `lib/net` → `http_post` / `headers=` map |
| Dotenv | `## load_env` in ext (or `load_dotenv` / `lib/sys`) |
| JSON quote | `lib/json` → `quote` |
## `ext/ai/llm` / `ext/ai/大模型` (object handles)
## Public API
| English | Chinese | Role |
|---------|---------|------|
| `## load_env` | `## 加载环境` | Free function: load `.env` |
| `## stream_result` | `## 流式结果` | Collapse event list → final text |
| `# llm` | `# 大模型` | Object ctor → handle map |
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Methods; optional `stream` / `流式`, `echo` / `打印增量` |
| `## load_env` | `## 加载环境` | Load `.env` |
| `## create` | `## 创建` | Factory → LLM handle |
| `## fast` / `## reasoning` | `## 快速` / `## 推理` | Named handles |
| `## prompt_load` / `## prompt` / `## prompt_body` | `## 加载提示` / `## 提示` / `## 提示正文` | Prompt artifacts (`type: prompt` → body) |
| `## ask` (module) | `## 提问` | Convenience → **text** (`prompt=` or `path=`) |
| `## collect` | `## 收集` | Events → text |
| `## stream_result` | `## 流式结果` | Alias of `collect` |
| `# llm` | `# 大模型` | Handle ctor (`backend=` openai-compatible \| ollama) |
| `## ask` (method) | `## 提问` | → **LLMResult** map |
| `## stream` | `## 流式` | → event list |
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Compat / transport primitive |
### Preferred
```markdown
---
import llm:ext/ai/llm.mq.md
---
**answer = > llm.ask prompt="What is Marqdo?"**
*answer*
# main
**model = > llm.create**
**result = > `model`.ask prompt=`prompt`**
*[text](result)*
> load_env
**fast = > llm.fast**
**events = > `fast`.stream prompt=`prompt`**
**text = > llm.collect events=`events`**
*`model` = > llm *
*`reply` = > `model`.complete prompt=Say hi in one word *
> print text=`reply`
*`events` = > `model`.complete prompt=Say hi stream=True *
- [`ev`](`events`)
*`t` = > json.get value=`ev` key=type *
1. `t` == "delta"
*`chunk` = > json.get value=`ev` key=text *
> print text=`chunk`
2. *
*`_` = 1*
**body = > llm.prompt path="fixtures/prompt-marqdo.md"**
**body2 = > llm.prompt text=`raw`**
```
Environment (create a **project-local** `.env`; do not commit secrets):
### LLMResult
| Field | Meaning |
|-------|---------|
| `text` | Answer string |
| `model` | Model id |
| `finish` | Finish reason (`stop`, …) |
| `backend` | e.g. `openai-compatible` / `ollama` |
| `usage` | `{prompt_tokens,completion_tokens,total_tokens}` |
| `tokens` | Alias of `usage.total_tokens` (agent metrics) |
| `name` | Optional handle tag (`fast` / `reasoning`) |
| `llm_calls` | `1` per ask |
| `tool_calls` | List of OpenAI-shaped tool call objects (empty when none) |
### Compat
`complete` / `chat` still return a bare string (or event list when `stream=True`) so `ext/ai/agent` and older runbooks keep working. **New code should use `ask` / `stream` / `collect`.**
## Environment
```env
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
MARQDO_LLM_FAST_MODEL=...
MARQDO_LLM_REASONING_MODEL=...
OLLAMA_HOST=http://127.0.0.1:11434/v1
```
Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`.
Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`. Ctor also accepts `api_key=` / `base_url=` / `model=` / `backend=`.
## Backends
| `backend=` | Module | Notes |
|------------|--------|-------|
| `openai-compatible` (default) | `ext/ai/llm/openai.mq.md` | Chat Completions HTTP + SSE |
| `ollama` | defaults in ctor + same transport | Key defaults to `ollama`; host from `OLLAMA_HOST` |
## Tests
- Import smoke: `tests/ext/llm-import.mq.md`
- Offline stream: `tests/ext/llm-stream-offline.mq.md` + `tests/lib/net-openai-sse.mq.md`
- Live complete (local): `tests/ext/llm-complete.mq.md` + `tests/ext/.env`
- 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`)
- `tests/ext/llm-import.mq.md`
- `tests/ext/llm-ctor-offline.mq.md`
- `tests/ext/llm-ask-offline.mq.md` (create + collect)
- `tests/ext/llm-stream-offline.mq.md`
- `tests/ext/llm-named-offline.mq.md` (fast/reasoning + prompt_load)
- `tests/ext/llm-tool-calls-offline.mq.md` (`tool_calls_from` / Result field)
- `tests/ext/llm-meta-offline.mq.md` · `llm-entry-prompt-offline.mq.md`
- Live: `llm-complete.mq.md` · `llm-stream-live.mq.md`
+1
View File
@@ -616,3 +616,4 @@ FnDef.params:
| 2026-09-13 | 决议空返回(§7.2)与提及性反引号(§4.4);形参改为「升参」与绑定图分离(§8.2) |
| 2026-09-14 | §7.2:`---` 不再收束;返回语句结束函数体解析;空返回首选 `*None*` |
| 2026-09-14 | 取元主语法改为 `[键](集合)`;脚注取元过渡保留 |
| 2026-09-24 | Artifact Metadata Binding(`${…}` Phase 1,仅 frontmatter):见 [binding.md](binding.md) · ADR 0006 |
+1 -1
View File
@@ -130,7 +130,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
## 5. Frontmatter 与跨文件
文件头 `---` 对为元信息。其中 `import bind:path.mq.md` / `导入` 为**文件导入**;`import bind:lib.member` 为**短名**(废除独立 `use` 与 frontmatter `>` 导入)。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法在独立 `>` 调用须 `` > `var`.method ``(`*…*` 段内接收者裸名)。详见 [module-namespace.md](module-namespace.md)。
文件头 `---` 对为 **Artifact Metadata**。其中 `import bind:path.mq.md` / `导入` 为**文件导入**;`import bind:lib.member` 为**短名**(废除独立 `use` 与 frontmatter `>` 导入)。其它 `key: value` 可为字面量或 **Binding**(`${env.NAME}` 等,加载期解析);见 [binding.md](binding.md)。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法在独立 `>` 调用须 `` > `var`.method ``(`*…*` 段内接收者裸名)。详见 [module-namespace.md](module-namespace.md)。
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
+2626
View File
File diff suppressed because it is too large. Load diff
+541
View File
@@ -0,0 +1,541 @@
有时候可能用户不太好接入Jev,所以阶段4应该要允许用户使用小参数的模型代替,你认为呢?
我非常赞同,而且我甚至建议**不要把 Jev 作为阶段 4 的必选组件**。
更准确的设计应该是:
> **Jev 是一种可选的决策器(Decision Engine),小参数模型是另一种可选实现;Marqdo Agent 本身只规定“需要一个 Router/Policy”,而不规定 Router 必须由什么实现。**
这样会让整个框架开放很多。
### 1. 阶段 4 应该改成“Adaptive Routing”
原来的:
```text
Phase 4
↓
Jev Router
```
我建议改成:
```text
Phase 4: Adaptive Routing
│
┌─────────┼─────────┐
↓ ↓ ↓
Marqdo Rule Jev Small LLM
│ │ │
└─────────┼─────────┘
↓
Route Policy
```
甚至还可以允许:
```text
Rule
Small Model
Jev
Full LLM
```
混合使用。
---
# 2. 为什么这个设计更合理
因为用户真正需要的不是:
> “我要接入 Jev。”
而是:
> “我希望 Agent 学会以后,不要每次都调用大模型。”
这两个概念应该分开。
所以 Marqdo 只定义接口:
```text
agent.route(task, candidates)
```
至于内部怎么实现,可以是:
### A. 纯 Marqdo
```text
if task.type == "json":
return json-repair
if task.type == "search":
return corpus-search
```
完全不需要模型。
---
### B. 小参数模型
比如用户已经有:
```text
Qwen 0.5B
Qwen 1.5B
Llama 1B
某个本地模型
```
就可以:
```text
task
↓
small model
↓
"json-repair"
```
甚至可以让用户直接配置:
```yaml
router:
type: llm
provider: openai-compatible
base_url: ...
api_key: ...
model: ...
```
这和你之前设计 AI 斗蛐蛐时提出的 **OpenAI-compatible URL + Key** 思路其实也很契合。
---
### C. Jev
如果用户安装了 Jev:
```text
task
↓
Jev
↓
policy
```
那么就用 Jev。
---
### D. 大模型
甚至最开始没有任何 Router:
```text
task
↓
large LLM
↓
decide
```
也是合法的。
所以:
> **Router 是抽象能力,不是具体模型。**
---
# 3. 更重要的是:Router 本身也可以被学习
这里我觉得还能进一步提升你的设计。
一开始:
```text
Task
↓
Large LLM
↓
选择 skill
```
系统观察:
```text
task A → json-repair
task B → json-repair
task C → json-repair
task D → corpus-search
```
之后可以自动生成:
```text
router.mq.md
```
例如:
```markdown
---
type: policy
status: compiled
---
## route
1. `task.type` == "json"
*"json-repair"*
2. `task.type` == "search"
*"corpus-search"*
3. *
*"llm"*
```
那么你甚至不需要 Jev。
**Marqdo 自己的控制流就是 Router。**
---
# 4. 所以我会重新设计 Cost Ladder
之前的:
```text
L0 deterministic
L1 rule
L2 small model
L3 small LLM
L4 large LLM
L5 exploration
```
我建议改成:
```text
┌────────────────────────┐
│ Adaptive Router │
└───────────┬────────────┘
│
┌─────────────────┼─────────────────┐
↓ ↓ ↓
Deterministic Small Model Large LLM
│ │ │
↓ ↓ ↓
L0/L1 L2/L3 L4
│
↓
Exploration L5
```
这里最关键的是:
> **L2/L3 不应该规定具体模型。**
可以是:
```text
Marqdo rules
OR
Jev
OR
0.5B model
OR
1B model
OR
3B model
```
---
# 5. 我甚至建议用户可以配置多个 Router
例如:
```yaml
router:
candidates:
- name: rules
type: marqdo
- name: local
type: llm
model: qwen-0.5b
- name: jev
type: jev
- name: cloud
type: llm
model: ...
```
然后 Agent 自己选择:
```text
Task
↓
Router Resolver
↓
rules?
↓
confidence insufficient
↓
small model?
↓
confidence insufficient
↓
Jev?
↓
confidence insufficient
↓
large LLM
```
这就形成一个**分级决策系统**。
---
# 6. 最漂亮的地方:Router 也可以被编译
最终甚至可以:
```text
第一次:
LLM
↓
决定调用 Skill A
第二次:
LLM
↓
决定调用 Skill A
第三次:
LLM
↓
决定调用 Skill A
Learning
↓
发现稳定模式
Compile
↓
router.mq.md
```
以后:
```text
Task
↓
router.mq.md
↓
skill A
↓
execute
```
**0 LLM。**
于是整个 Agent 的学习就不只是:
```text
学习如何解决任务
```
而是同时学习:
```text
1. 学习如何解决任务
2. 学习什么时候使用什么技能
3. 学习什么时候需要大模型
```
这三个层次组合起来,我认为比单纯引入 Jev 更有意思。
---
# 7. 最终可以形成三级编译
我现在反而觉得你的 Agent Framework 可以把整个“学习”定义成三个阶段:
```text
Experience
↓
Skill Compilation
↓
Policy Compilation
↓
Execution Compilation
```
### 第一层:Skill Compilation
```text
LLM experience
↓
skill.mq.md
```
解决:
> **怎么做?**
### 第二层:Policy Compilation
```text
many task → skill mappings
↓
policy.mq.md
```
解决:
> **什么时候做什么?**
### 第三层:Execution Compilation
```text
skill + policy
↓
pure Marqdo execution
```
解决:
> **能不能完全不思考直接执行?**
这时候整个 Agent 就变成:
```text
Large LLM
│
Exploration
↓
Experience
↓
┌───────────────┐
│ Skill Compile │
└───────┬───────┘
↓
Skill MQ
│
┌───────┴───────┐
↓ ↓
Policy Compile Direct Execute
↓
Router MQ
│
↓
Skill Selection
│
↓
Execute
```
---
# 8. 因此 Phase 4 我建议正式改名
不要叫:
> Jev Router
而叫:
> **Adaptive Policy / Routing Layer**
然后提供四种 backend:
```text
router.backend = marqdo
router.backend = small-llm
router.backend = jev
router.backend = llm
```
甚至:
```text
router.backend = auto
```
让 Agent 根据可用环境自动选择。
---
## 9. 用户体验也会好很多
用户第一次安装 Marqdo:
```text
marqdo agent run ...
```
没有 Jev,也没有小模型。
完全没问题:
```text
→ 使用配置的大模型
```
用户后来配置:
```yaml
router:
backend: small-llm
provider: openai-compatible
model: qwen-0.5b
```
Agent 就自动变成:
```text
大模型:负责复杂推理 / 学习
小模型:负责日常路由
Marqdo:负责确定性执行
```
如果用户安装 Jev:
```yaml
router:
backend: jev
```
则:
```text
Jev:负责路由
大模型:负责复杂任务
Marqdo:负责执行
```
**用户完全不需要改变 Agent 的上层 API。**
---
我认为这个调整非常重要,因为它让 **Marqdo Agent 的核心创新从“依赖某个新模型”变成“模型无关的认知编译架构”**。
最终可以浓缩成一句话:
> **大模型负责探索,小模型/Jev 负责决策,Marqdo 负责执行;随着经验积累,探索和决策逐渐被编译成可执行的 `.mq.md`。**
这其实比“接入 Jev”本身更符合你最开始提出的 **Think → Execute → Learn → Compile → Reuse** 路线。
+1173
View File
File diff suppressed because it is too large. Load diff
+1335
View File
File diff suppressed because it is too large. Load diff
+77
View File
@@ -0,0 +1,77 @@
# Marqdo AI 栈统一开发方案(llm + agent)
| | |
|---|---|
| Status | **Active** |
| Date | 2026-09-24 |
| Source | [doc/next/002–005](../next/) · [ext-llm.md](../design/ext-llm.md) · [ext-agent.md](../design/ext-agent.md) |
## 1. 一句话
> **Document → Prompt → LLM → Agent → Skill → Policy → Executable Knowledge**
大模型负责探索,小模型(`router_model` / 任意 llm 句柄)负责决策,Marqdo 负责执行;经验编译进 `.mq.md` 后推理成本下降。
## 2. 分层(勿混)
| 层 | 职责 | 落点 |
|----|------|------|
| **Intelligence primitive** | `ask` / `stream` / `collect`;结果对象 | `ext/ai/llm` |
| **Agent runtime** | `run` / `step` / `plan` / `route` | `ext/ai/agent` |
| **Memory / compile** | episode → skill → policy | `plugins/agent`(ABI;**不进** `src/host`) |
| **Transport** | HTTP / SSE / provider | `ext/ai/llm/openai` · `ollama`;用户不可见 |
硬规则:`ext/**` 不调 `host_*`;agent/OKF/路由热路径只进 `plugins/agent`。
## 3. LLM(005)— 已/待
| 项 | 状态 |
|----|------|
| 语义 API:`ask` / `stream` / `collect`(`complete` 降为兼容原语) | **done** |
| `create` 工厂;handle 带 `backend` | **done** |
| LLMResult:`text` / `model` / `finish` / `backend` / `usage` / `tokens` | **done** |
| Named models(`llm.fast` / `llm.reasoning`) | **done** |
| Prompt document:`prompt` / `prompt_load` + `type: prompt` 正文 | **done**(无参 `ask`/`stream` → `sys.module_source` + `prompt_body`) |
| 拆 `ext/ai/llm/openai.mq.md` + `ollama` 后端 | **done** |
| tool_calls 完整 Result | **done**(`openai.tool_calls_from` + `LLMResult.tool_calls`;`llm-tool-calls-offline`) |
| Transport → 可选 ABI 插件 (`plugins/llm`) | **done** |
| Artifact Metadata Binding(`${env.*}` / `secret` · `sys.meta`) | **done**(Phase 1 Metadata-only + Phase 2 scope lift;[binding.md](../design/binding.md)) |
作者面优先:
```marqdo
**answer = > llm.ask prompt="What is Marqdo?"**
**events = > model.stream prompt=`p`**
**text = > llm.collect events=`events`**
**fast = > llm.fast**
**prompt = > llm.prompt path="prompts/task.md"**
```
## 4. Agent(002–004)— 已/待
| 项 | 状态 |
|----|------|
| Skill Compilation:episode → maybe_learn → `llm_free` | **done** |
| Adaptive Routing:`marqdo` \| `small-llm` \| `llm` \| `auto`(`jev`→`small-llm` 别名) | **done** |
| Policy Compilation → `policies/router.mq.md` | **done** |
| `run` 串联 route → execute → record → learn | **done** |
| Agent 默认走 `model.ask` + Result.usage 记成本 | **done**(`model_turn`) |
| Prompt artifact / document-as-prompt | **done**(经 llm `path=` / `prompt`) |
| 零 LLM 执行(policy+skill → `llm_calls=0`) | **done** |
| `plan` 不覆盖已有 `llm_free` resource | **done** |
| 真 MCP client(stdio) / resume checkpoint / 小模型路由请求面 | **done**(live 路由仍可选 skip) |
## 5. 联调顺序
1. **LLM Result → Agent metrics** — **done**
2. **Named handles** — **done**
3. **Prompt document** — **done**(`type: prompt` 剥 frontmatter;无参 `ask`/`stream` 经 `sys.module_source`)
4. **Backend split** — **done**
5. **Execution compilation** — **done**(`agent-zero-llm` 金样 + harness)
6. **Metadata Binding** — **done**(Phase 1 + Phase 2 scope lift;`llm-meta-offline` · `meta-lift`)
## 6. 验收金样
- Agent:`tests/ext/agent-v2-learn.mq.md` · `agent-p4-route.mq.md` · `agent-zero-llm.mq.md` · `agent-plan-preserve.mq.md` · `agent-mcp-client.mq.md` · `agent-resume.mq.md` · `agent-small-llm-route.mq.md` · `scripts/agent-harness.sh`
- LLM:`tests/ext/llm-ask-offline.mq.md` · `llm-stream-offline.mq.md` · `llm-ctor-offline.mq.md` · `llm-named-offline.mq.md` · `llm-meta-offline.mq.md` · `llm-entry-prompt-offline.mq.md` · `llm-tool-calls-offline.mq.md`
- Binding:`tests/structure/meta-binding.mq.md` · `meta-lift.mq.md`
+8 -2
View File
@@ -39,6 +39,12 @@
| **B0** | 官方示例演示 call_site/源码/OKF;Skill/文档;上下文管道可读 | **done** |
| **B0.5** | 本机 live(`.env` → 开发模型)验证「模型用上了文档」 | **done**(`AGENT_LIVE` / `AGENT_HARNESS_LIVE`) |
| **B1** | 评测 harness 锁差异化指标(constitution / dump / writeback 遮蔽) | **Active** |
| **B2–B5** | 真 MCP / resume+HITL / stats / 并行 | 暂缓 |
| **B1.5** | **Skill Compilation v2(Phase 1–3)**:episode → maybe_learn → compile → `llm_free`;`agent.run` / `resolve` / `metrics`;ABI 在 `plugins/agent`(`memory.rs`);金样 `agent-v2-learn` | **done** |
| **B1.6 / P4** | **Adaptive Routing**(原 Jev Router 更名):`route` backends = `marqdo` \| `small-llm` \| `jev?` \| `llm` \| `auto`;Policy Compilation → `policies/router.mq.md`;金样 `agent-p4-route`;设计 [004.md](../next/004.md) | **done** |
| **L0** | **LLM semantic surface(005)**:`ask` / `stream` / `collect` / `create`;`complete` 降为兼容;统一方案 [ai-stack.md](ai-stack.md) | **done** |
| **B2** | 真 MCP stdio client(`agent_mcp_client` + fixture 仍作离线证据) | **done** |
| **B3** | resume checkpoint(`.marqdo/agent-resume/`;HITL view 仍暂缓) | **done**(HITL 暂缓) |
| **B4–B5** | stats / 并行;小模型 live 路由金样(无 key skip) | 部分 |
| — | LLM named models / prompt-document | **done** |
示例:`examples/agent-pong/` · `examples/agent-okf-flywheel/`。
示例:`examples/agent-pong/` · `examples/agent-okf-flywheel/`。v2 设计:[doc/next/002.md](../next/002.md) · [doc/next/003.md](../next/003.md) · P4:[doc/next/004.md](../next/004.md) · LLM:[doc/next/005.md](../next/005.md)。
+1 -1
View File
@@ -1 +1 @@
1.1.0
1.1.1
+518 -24
View File
@@ -1,6 +1,6 @@
---
title: ext/ai/agent
description: Document-driven agent — step / plan; tools via lib/subtask; runtime via ABI v2 agent plugin.
description: Document-driven agent v2 — step / plan / run; Skill Compilation via ABI plugin (episodes → learn → llm_free).
import llm:ext/ai/llm.mq.md
import json:lib/json.mq.md
import sys:lib/sys.mq.md
@@ -49,6 +49,37 @@ The runbook `.mq.md` is ground truth (code as documentation). Default budgets ke
---
## model_turn
+ `model`
+ `prompt`
+ `stream`=False
+ `echo`=False
One LLM turn via the semantic surface (`ask` / `stream`+`collect`). Returns `{text,llm_calls,tokens}` for episode metrics.
1. `stream`
**evs = > model.stream prompt=`prompt` echo=`echo`**
**text = > llm.collect events=`evs`**
**tokens = 0**
2. *
**r = > model.ask prompt=`prompt`**
**text = [text](r)**
**tokens = [tokens](r)**
1. `tokens`
**_ = 1**
2. *
**tokens = 0**
`out` =
| text | llm_calls | tokens |
|------|-----------|--------|
| `text` | 1 | `tokens` |
*out*
---
## dump_step_context
+ `agent`
+ `task`=""
@@ -424,6 +455,128 @@ Call a named tool from a MCP-shaped fixture (`results` / `calls` map). Optional
---
## mcp_connect
+ `command`
+ `args`=None
+ `session`="default"
+ `name`="mcp"
Open a stdio MCP client session (spawn `command` + `args`, JSON-RPC initialize). Evidence only — workbook remains authority.
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
1. `args`
*> agent_mcp_client action="connect" command=`command` args=`args` session=`session` name=`name`*
2. *
*> agent_mcp_client action="connect" command=`command` session=`session` name=`name`*
## mcp_client_list
+ `session`="default"
+ `command`=None
+ `args`=None
List tools from an open MCP session, or one-shot when `command=` is set (no session retained).
1. `command`
1. `args`
*> agent_mcp_client action="list" command=`command` args=`args`*
2. *
*> agent_mcp_client action="list" command=`command`*
2. *
*> agent_mcp_client action="list" session=`session`*
## mcp_client_call
+ `name`=None
+ `session`="default"
+ `arguments`=None
+ `command`=None
+ `args`=None
+ `tool`=None
Call a tool on an open MCP session, or one-shot when `command=` is set. Prefer `tool=` for oneshot when `name` would collide with server name.
1. `command`
1. `tool`
**tn = tool**
2. *
**tn = name**
1. `args`
*> agent_mcp_client action="call" command=`command` args=`args` tool=`tn` arguments=`arguments`*
2. *
*> agent_mcp_client action="call" command=`command` tool=`tn` arguments=`arguments`*
2. *
*> agent_mcp_client action="call" session=`session` name=`name` arguments=`arguments`*
## mcp_disconnect
+ `session`="default"
Close a stdio MCP client session.
*> agent_mcp_client action="close" session=`session`*
---
## resume_save
+ `id`
+ `goal`=None
+ `task`=None
+ `status`=running
+ `round`=0
+ `workbook`=None
+ `events`=None
+ `route`=None
+ `result`=None
+ `resume_dir`=.marqdo/agent-resume
Persist a plan/run checkpoint as `.marqdo/agent-resume/<id>.json`.
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/agent: native agent plugin not found
> sys.exit code=1
*> agent_resume_save id=`id` goal=`goal` task=`task` status=`status` round=`round` workbook=`workbook` events=`events` route=`route` result=`result` resume_dir=`resume_dir`*
## resume_load
+ `id`
+ `resume_dir`=.marqdo/agent-resume
Load a resume checkpoint (or `{ok:false,found:false}`).
*> agent_resume_load id=`id` resume_dir=`resume_dir`*
## resume_clear
+ `id`
+ `resume_dir`=.marqdo/agent-resume
Delete a resume checkpoint.
*> agent_resume_clear id=`id` resume_dir=`resume_dir`*
## resume_list
+ `resume_dir`=.marqdo/agent-resume
List checkpoint ids under `resume_dir`.
*> agent_resume_list resume_dir=`resume_dir`*
## resume
+ `id`
+ `resume_dir`=.marqdo/agent-resume
Author entry: load checkpoint for continuation. Returns the checkpoint map (`found`/`round`/`workbook`/…). Callers continue with `plan`/`run` using saved fields; clear when done.
*> resume_load id=`id` resume_dir=`resume_dir`*
---
## extract_call_args
+ `reply`=None
@@ -1264,7 +1417,7 @@ Parent Plan-and-Move prompt. Short protocol only — no long monologues.
+ `events`
+ `max_acts`=6
LLM Plan → CALL/READ/DECISION loop. Returns `{decision,reply,observation,events}`.
LLM Plan → CALL/READ/DECISION loop. Returns `{decision,reply,observation,events,llm_calls,tokens}`.
**model = > json.get value=`agent` key="model"**
**last_obs = observation**
@@ -1272,6 +1425,8 @@ LLM Plan → CALL/READ/DECISION loop. Returns `{decision,reply,observation,event
**decision = None**
**last_reply = None**
**evs_all = events**
**llm_calls = 0**
**tokens = 0**
- `left` > 0
1. `decision`
@@ -1279,11 +1434,17 @@ LLM Plan → CALL/READ/DECISION loop. Returns `{decision,reply,observation,event
2. *
**ctx = > build_plan_context agent=`agent` goal=`goal` observation=`last_obs` explore_attempt=`explore_attempt` explore_n=`explore_n` phase=`phase`**
1. `stream`
**evs = > model.complete prompt=`ctx` stream=True echo=`echo`**
**last_reply = > llm.stream_result events=`evs`**
**evs = > model.stream prompt=`ctx` echo=`echo`**
**last_reply = > llm.collect events=`evs`**
**evs_all = > plan_merge_deltas events=`evs_all` from=`evs` stream=`stream`**
**llm_calls = llm_calls + 1**
2. *
**last_reply = > model.complete prompt=`ctx`**
**turn = > model_turn model=`model` prompt=`ctx` stream=False echo=`echo`**
**last_reply = > json.get value=`turn` key="text"**
**c = > json.get value=`turn` key="llm_calls"**
**t = > json.get value=`turn` key="tokens"**
**llm_calls = llm_calls + c**
**tokens = tokens + t**
**last_reply = > trim value=`last_reply`**
**act = > extract_plan_act reply=`last_reply`**
**kind = > json.get value=`act` key="kind"**
@@ -1314,6 +1475,8 @@ LLM Plan → CALL/READ/DECISION loop. Returns `{decision,reply,observation,event
**out = > json.set map=`out` key="reply" value=`last_reply`**
**out = > json.set map=`out` key="observation" value=`last_obs`**
**out = > json.set map=`out` key="events" value=`evs_all`**
**out = > json.set map=`out` key="llm_calls" value=`llm_calls`**
**out = > json.set map=`out` key="tokens" value=`tokens`**
*out*
---
@@ -1515,6 +1678,316 @@ Clear the plugin session bag for this agent id.
> agent_history_clear id=`id`
****
## resolve
+ `task`
+ `kb_dir`=.marqdo/agent-kb
+ `near_match`=True
+ `near_threshold`=0.78
Skill resolver (v2): exact → alias → canonical → near. Returns `mode` / `resource` / `llm_free` / `confidence`. Plugin ABI — no core host_* calls.
**tools = > json.get value=`self` key="tools"**
*> agent_resolve task=`task` kb_dir=`kb_dir` near_match=`near_match` near_threshold=`near_threshold` tools=`tools`*
## route
+ `task`
+ `backend`=auto
+ `kb_dir`=.marqdo/agent-kb
+ `memory_dir`=.marqdo/agent-memory
+ `threshold`=0.78
Adaptive Routing (Phase 4): abstract router — `marqdo` | `small-llm` | `llm` | `auto`. `jev` is accepted as a **compat alias** of `small-llm` (not a first-class backend). `auto` cascades policy → kb → small-llm request. May return `needs_llm=True` + `prompt` for the caller to complete with `router_model` (any llm handle), then `route_apply`.
**tools = > json.get value=`self` key="tools"**
*> agent_route task=`task` backend=`backend` kb_dir=`kb_dir` memory_dir=`memory_dir` threshold=`threshold` tools=`tools`*
## route_apply
+ `task`
+ `reply`
+ `kb_dir`=.marqdo/agent-kb
+ `backend`=small-llm
Apply a router model line (`SKILL:<slug>` / `EXPLORE`) to a kb skill hit.
*> agent_route_apply task=`task` reply=`reply` kb_dir=`kb_dir` backend=`backend`*
## compile_policy
+ `memory_dir`=.marqdo/agent-memory
+ `min_evidence`=3
+ `force`=False
Policy Compilation: stable episode skill selections → `policies/router.mq.md` (deterministic Marqdo rules).
*> agent_compile_policy memory_dir=`memory_dir` min_evidence=`min_evidence` force=`force`*
## maybe_compile_policy
+ `memory_dir`=.marqdo/agent-memory
+ `min_evidence`=3
Learn gate for the Adaptive Router policy layer.
*> agent_maybe_compile_policy memory_dir=`memory_dir` min_evidence=`min_evidence`*
## record_episode
+ `task`
+ `status`=ok
+ `result`=None
+ `mode`=explore
+ `skill`=none
+ `observation`=None
+ `workbook`=None
+ `cache`=None
+ `match`=None
+ `llm_calls`=0
+ `tool_calls`=0
+ `error`=None
+ `memory_dir`=.marqdo/agent-memory
Persist one run as `.mq.md` under `memory_dir/episodes/YYYY/MM/` (v2 Phase 1). Memory is executable documentation, not a vector bag.
*> agent_record_episode task=`task` status=`status` result=`result` mode=`mode` skill=`skill` observation=`observation` workbook=`workbook` cache=`cache` match=`match` llm_calls=`llm_calls` tool_calls=`tool_calls` error=`error` memory_dir=`memory_dir`*
## maybe_learn
+ `task`
+ `kb_dir`=.marqdo/agent-kb
+ `memory_dir`=.marqdo/agent-memory
+ `improve_every`=3
+ `promote`=True
Offline learn gate: when ≥ `improve_every` successful episodes share a task hash, generalize → synthesize → compile → optional OKF promote (`llm_free`). Also attempts Policy Compilation for Adaptive Routing.
**skill_learn = > agent_maybe_learn task=`task` kb_dir=`kb_dir` memory_dir=`memory_dir` improve_every=`improve_every` promote=`promote`**
**policy_learn = > agent_maybe_compile_policy memory_dir=`memory_dir` min_evidence=`improve_every`**
**out = > json.parse text={"learned":false}**
**sl = > json.get value=`skill_learn` key="learned"**
**out = > json.set map=`out` key="learned" value=`sl`**
**out = > json.set map=`out` key="skill" value=`skill_learn`**
**out = > json.set map=`out` key="policy" value=`policy_learn`**
*out*
## compile
+ `task`
+ `kb_dir`=.marqdo/agent-kb
+ `memory_dir`=.marqdo/agent-memory
+ `min_evidence`=3
+ `promote`=True
+ `force`=False
Compile a candidate skill into versioned `skills/<slug>/vN.mq.md` and optionally promote into agent-kb.
*> agent_compile_skill task=`task` kb_dir=`kb_dir` memory_dir=`memory_dir` min_evidence=`min_evidence` promote=`promote` force=`force`*
## metrics
+ `memory_dir`=.marqdo/agent-memory
Reasoning amortization stats over recorded episodes (`avg_llm_calls`, `compiled_runs`, …).
*> agent_metrics memory_dir=`memory_dir`*
## run
+ `task`
+ `kb_dir`=.marqdo/agent-kb
+ `memory_dir`=.marqdo/agent-memory
+ `learn`=True
+ `verify`=True
+ `writeback`=True
+ `reuse`=True
+ `near_match`=True
+ `near_threshold`=0.78
+ `promote`=True
+ `improve_every`=3
+ `explore_n`=3
+ `max_rounds`=4
+ `stream`=False
+ `echo`=False
+ `trace`=False
+ `force`=False
+ `router`=auto
+ `router_model`=None
+ `resume_id`=None
+ `resume_dir`=.marqdo/agent-resume
Primary author entry (v2 + P4): Adaptive `route` → execute (policy/kb skill) or `plan` → record episode → maybe_learn (skill + policy). `router` = `auto`|`marqdo`|`small-llm`|`llm` (`jev`→`small-llm` alias). Optional `router_model` (llm handle) answers `needs_llm` prompts — small models welcome.
**routed = > `self`.route task=`task` backend=`router` kb_dir=`kb_dir` memory_dir=`memory_dir` threshold=`near_threshold`**
**route_matched = > json.get value=`routed` key="matched"**
**needs_llm = > json.get value=`routed` key="needs_llm"**
**exec_mode = "explore"**
**llm_calls = 0**
**tokens = 0**
**out = None**
**route_backend = > json.get value=`routed` key="backend"**
1. `route_matched`
**path = > json.get value=`routed` key="resource"**
1. `path`
**aw = > await_workbook path=`path`**
**code = > json.get value=`aw` key="code"**
**child_val = > json.get value=`aw` key="value"**
**last_obs = > json.get value=`aw` key="observation"**
1. `code` == 0
> agent_kb_record_hit kb_dir=`kb_dir` goal=`task` improve_every=`improve_every`
**lf = > json.get value=`routed` key="llm_free"**
1. `lf`
**exec_mode = "compiled"**
2. *
**exec_mode = "routed"**
**out = > json.parse text={"status":"ok"}**
**out = > json.set map=`out` key="status" value="ok"**
**out = > json.set map=`out` key="goal" value=`task`**
**out = > json.set map=`out` key="result" value=`child_val`**
**out = > json.set map=`out` key="workbook" value=`path`**
**out = > json.set map=`out` key="cache" value="hit"**
**rmode = > json.get value=`routed` key="mode"**
**out = > json.set map=`out` key="match" value=`rmode`**
**sk = > json.get value=`routed` key="skill"**
**out = > json.set map=`out` key="skill" value=`sk`**
**out = > json.set map=`out` key="observation" value=`last_obs`**
**out = > json.set map=`out` key="summary" value="adaptive route hit"**
**out = > json.set map=`out` key="route" value=`routed`**
**llm_calls = 0**
2. *
**route_matched = False**
2. *
**route_matched = False**
2. *
**_ = 1**
1. `route_matched`
**_ = 1**
2. `needs_llm`
1. `router_model`
**prompt = > json.get value=`routed` key="prompt"**
**turn = > model_turn model=`router_model` prompt=`prompt` stream=`stream` echo=`echo`**
**reply = > json.get value=`turn` key="text"**
**llm_calls = > json.get value=`turn` key="llm_calls"**
**tokens = > json.get value=`turn` key="tokens"**
**applied = > `self`.route_apply task=`task` reply=`reply` kb_dir=`kb_dir` backend=`router`**
**am = > json.get value=`applied` key="matched"**
1. `am`
**path = > json.get value=`applied` key="resource"**
**aw = > await_workbook path=`path`**
**code = > json.get value=`aw` key="code"**
**child_val = > json.get value=`aw` key="value"**
**last_obs = > json.get value=`aw` key="observation"**
1. `code` == 0
**exec_mode = "routed"**
**out = > json.parse text={"status":"ok"}**
**out = > json.set map=`out` key="status" value="ok"**
**out = > json.set map=`out` key="goal" value=`task`**
**out = > json.set map=`out` key="result" value=`child_val`**
**out = > json.set map=`out` key="workbook" value=`path`**
**out = > json.set map=`out` key="cache" value="soft-hit"**
**out = > json.set map=`out` key="match" value="routed"**
**sk = > json.get value=`applied` key="skill"**
**out = > json.set map=`out` key="skill" value=`sk`**
**out = > json.set map=`out` key="observation" value=`last_obs`**
**out = > json.set map=`out` key="summary" value="router model selected skill"**
**out = > json.set map=`out` key="route" value=`applied`**
**route_matched = True**
2. *
**route_matched = False**
2. *
**route_matched = False**
2. *
**route_matched = False**
3. *
**_ = 1**
1. `route_matched`
**_ = 1**
2. *
**resolved = > `self`.resolve task=`task` kb_dir=`kb_dir` near_match=`near_match` near_threshold=`near_threshold`**
**mode = > json.get value=`resolved` key="mode"**
**llm_free = > json.get value=`resolved` key="llm_free"**
1. `llm_free`
**path = > json.get value=`resolved` key="resource"**
**aw = > await_workbook path=`path`**
**code = > json.get value=`aw` key="code"**
**child_val = > json.get value=`aw` key="value"**
**last_obs = > json.get value=`aw` key="observation"**
1. `code` == 0
> agent_kb_record_hit kb_dir=`kb_dir` goal=`task` improve_every=`improve_every`
**exec_mode = "compiled"**
**out = > json.parse text={"status":"ok"}**
**out = > json.set map=`out` key="status" value="ok"**
**out = > json.set map=`out` key="goal" value=`task`**
**out = > json.set map=`out` key="result" value=`child_val`**
**out = > json.set map=`out` key="workbook" value=`path`**
**out = > json.set map=`out` key="cache" value="hit"**
**out = > json.set map=`out` key="match" value=`mode`**
**sk = > json.get value=`resolved` key="skill"**
**out = > json.set map=`out` key="skill" value=`sk`**
**out = > json.set map=`out` key="observation" value=`last_obs`**
**out = > json.set map=`out` key="summary" value="compiled skill (llm_free)"**
**llm_calls = 0**
2. *
**out = > `self`.plan goal=`task` kb_dir=`kb_dir` writeback=`writeback` reuse=`reuse` near_match=`near_match` near_threshold=`near_threshold` promote=`promote` improve_every=`improve_every` explore_n=`explore_n` max_rounds=`max_rounds` stream=`stream` echo=`echo` trace=`trace` force=`force`**
**exec_mode = "explore"**
**llm_calls = 1**
2. *
**out = > `self`.plan goal=`task` kb_dir=`kb_dir` writeback=`writeback` reuse=`reuse` near_match=`near_match` near_threshold=`near_threshold` promote=`promote` improve_every=`improve_every` explore_n=`explore_n` max_rounds=`max_rounds` stream=`stream` echo=`echo` trace=`trace` force=`force`**
**cache = > json.get value=`out` key="cache"**
1. `cache` == hit
**exec_mode = "compiled"**
**llm_calls = 0**
2. `cache` == soft-hit
**exec_mode = "near"**
**llm_calls = 0**
3. *
**exec_mode = "explore"**
**llm_calls = 1**
**st = > json.get value=`out` key="status"**
**res = > json.get value=`out` key="result"**
**wb_path = > json.get value=`out` key="workbook"**
**obs = > json.get value=`out` key="observation"**
**sk2 = > json.get value=`out` key="skill"**
**cache2 = > json.get value=`out` key="cache"**
**match2 = > json.get value=`out` key="match"**
**err = > json.get value=`out` key="error"**
1. `verify`
1. `st` == "ok"
**verification = "status: passed"**
2. *
**verification = "status: failed"**
2. *
**verification = "status: skipped"**
**ep = > `self`.record_episode task=`task` status=`st` result=`res` mode=`exec_mode` skill=`sk2` observation=`obs` workbook=`wb_path` cache=`cache2` match=`match2` llm_calls=`llm_calls` tokens=`tokens` error=`err` memory_dir=`memory_dir`**
**learning = None**
1. `learn`
1. `st` == "ok"
**learning = > `self`.maybe_learn task=`task` kb_dir=`kb_dir` memory_dir=`memory_dir` improve_every=`improve_every` promote=`promote`**
2. *
**learning = None**
2. *
**_ = 1**
**execution = > json.parse text={"mode":"explore","llm_calls":0,"tokens":0}**
**execution = > json.set map=`execution` key="mode" value=`exec_mode`**
**execution = > json.set map=`execution` key="llm_calls" value=`llm_calls`**
**execution = > json.set map=`execution` key="tokens" value=`tokens`**
**execution = > json.set map=`execution` key="skill" value=`sk2`**
**execution = > json.set map=`execution` key="router" value=`route_backend`**
**out = > json.set map=`out` key="execution" value=`execution`**
**out = > json.set map=`out` key="episode" value=`ep`**
**out = > json.set map=`out` key="route" value=`routed`**
1. `learning`
**out = > json.set map=`out` key="learning" value=`learning`**
2. *
**_ = 1**
1. `resume_id`
**_ckpt = > resume_save id=`resume_id` goal=`task` task=`task` status=`st` round=1 workbook=`wb_path` result=`res` route=`routed` resume_dir=`resume_dir`**
**out = > json.set map=`out` key="resume" value=`_ckpt`**
2. *
**_ = 1**
*out*
## step
+ `task`
+ `writeback`=True
@@ -1539,17 +2012,20 @@ With `stream=True`, the model call uses SSE; `echo=True` prints delta text to st
**reads_left = max_reads**
**reply = None**
**decision = None**
**llm_calls = 0**
**tokens = 0**
- `reads_left` > 0
1. `decision`
**reads_left = 0**
2. *
**ctx = > build_step_context agent=`self` task=`task` source_depth=`source_depth` skill_depth=`skill_depth`**
1. `stream`
**evs = > model.complete prompt=`ctx` stream=True echo=`echo`**
**reply = > llm.stream_result events=`evs`**
2. *
**reply = > model.complete prompt=`ctx`**
**turn = > model_turn model=`model` prompt=`ctx` stream=`stream` echo=`echo`**
**reply = > json.get value=`turn` key="text"**
**c = > json.get value=`turn` key="llm_calls"**
**t = > json.get value=`turn` key="tokens"**
**llm_calls = llm_calls + c**
**tokens = tokens + t**
**reply = > trim value=`reply`**
**rk = > extract_plan_read reply=`reply`**
1. `rk` == source
@@ -1578,11 +2054,12 @@ With `stream=True`, the model call uses SSE; `echo=True` prints delta text to st
**task_s = > json.stringify value=`task`**
**fp = "Tool CALL was rejected (not on the tools whitelist). Do NOT emit CALL. Answer the user task directly with the final answer only.\n\nUser task:\n"**
**fp = fp + task_s**
1. `stream`
**evs_retry = > model.complete prompt=`fp` stream=True echo=`echo`**
**reply = > llm.stream_result events=`evs_retry`**
2. *
**reply = > model.complete prompt=`fp`**
**turn2 = > model_turn model=`model` prompt=`fp` stream=`stream` echo=`echo`**
**reply = > json.get value=`turn2` key="text"**
**c = > json.get value=`turn2` key="llm_calls"**
**t = > json.get value=`turn2` key="tokens"**
**llm_calls = llm_calls + c**
**tokens = tokens + t**
**out = > json.set map=`out` key="status" value="ok"**
**out = > json.set map=`out` key="decision" value=`decision`**
**out = > json.set map=`out` key="denied_tool" value=`tool_name`**
@@ -1596,17 +2073,21 @@ With `stream=True`, the model call uses SSE; `echo=True` prints delta text to st
**fp = fp + "ran via subtask and returned:"**
**fp = fp + tool_s**
**fp = fp + ". Reply to the user briefly."**
1. `stream`
**evs2 = > model.complete prompt=`fp` stream=True echo=`echo`**
**reply = > llm.stream_result events=`evs2`**
2. *
**reply = > model.complete prompt=`fp`**
**turn2 = > model_turn model=`model` prompt=`fp` stream=`stream` echo=`echo`**
**reply = > json.get value=`turn2` key="text"**
**c = > json.get value=`turn2` key="llm_calls"**
**t = > json.get value=`turn2` key="tokens"**
**llm_calls = llm_calls + c**
**tokens = tokens + t**
**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. *
**out = > json.set map=`out` key="result" value=`reply`**
**out = > json.set map=`out` key="llm_calls" value=`llm_calls`**
**out = > json.set map=`out` key="tokens" value=`tokens`**
**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`
@@ -1644,6 +2125,8 @@ With `stream=True`, the model call uses SSE; `echo=True` prints delta text to st
+ `stream`=False
+ `echo`=False
+ `trace`=False
+ `resume_id`=None
+ `resume_dir`=.marqdo/agent-resume
Multi-step with OKF agent-kb. Default workbook is `kb_dir/resources/<slug>.mq.md`. While task file count `< explore_n` and skill is not llm_free, force a new explore variant under `kb_dir/explore/<slug>/`. Code-first: llm_free hits skip parent LLM. File children return via `# main`; `plan` exposes that as `result`.
@@ -1799,11 +2282,12 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near`
**soft_prompt = > build_soft_match_prompt goal=`goal` tasks=`tasks`**
**model = > json.get value=`self` key="model"**
1. `stream`
**evs = > model.complete prompt=`soft_prompt` stream=True echo=`echo`**
**soft_reply = > llm.stream_result events=`evs`**
**evs = > model.stream prompt=`soft_prompt` echo=`echo`**
**soft_reply = > llm.collect events=`evs`**
**events = > plan_merge_deltas events=`events` from=`evs` stream=`stream`**
2. *
**soft_reply = > model.complete prompt=`soft_prompt`**
**soft_turn = > model_turn model=`model` prompt=`soft_prompt` stream=False echo=`echo`**
**soft_reply = > json.get value=`soft_turn` key="text"**
**soft_reply = > trim value=`soft_reply`**
**soft_dec = > extract_plan_decision reply=`soft_reply`**
**events = > plan_append_decision events=`events` decision=`soft_dec` stream=`stream`**
@@ -1898,18 +2382,28 @@ Reuse lookup: exact → alias → canonicalize → optional local n-gram `near`
**b = > json.get value=`parts` key="b"**
**c = > json.get value=`parts` key="c"**
**path = workbook_dir + a + slug + b + ts + c**
> fs.write_text path=`path` text=`skel`
2. `explore`
**parts = > json.parse text={"a":"/explore/","b":"/","c":".mq.md"}**
**a = > json.get value=`parts` key="a"**
**b = > json.get value=`parts` key="b"**
**c = > json.get value=`parts` key="c"**
**path = kb_dir + a + slug + b + explore_attempt + c**
**ex = > fs.exists path=`path`**
1. `ex`
**_ = 1**
2. *
> fs.write_text path=`path` text=`skel`
3. *
**parts = > json.parse text={"a":"/resources/","b":".mq.md"}**
**a = > json.get value=`parts` key="a"**
**b = > json.get value=`parts` key="b"**
**path = kb_dir + a + slug + b**
> fs.write_text path=`path` text=`skel`
**ex = > fs.exists path=`path`**
1. `ex`
**_ = 1**
2. *
> fs.write_text path=`path` text=`skel`
1. `confirm`
**out = > json.parse text={"status":"pending"}**
+295 -68
View File
@@ -1,23 +1,26 @@
---
title: ext/ai/llm
description: OpenAI-compatible LLM object (English). Import ext/ai/llm.mq.md.
description: >-
Marqdo LLM intelligence primitive — ask / stream / collect / named handles.
OpenAI-compatible and Ollama HTTP stay behind the semantic surface.
import sys:lib/sys.mq.md
import net:lib/net.mq.md
import json:lib/json.mq.md
import table:lib/table.mq.md
import fs:lib/fs.mq.md
import text:lib/text.mq.md
import openai:ext/ai/llm/openai.mq.md
---
## load_env
+ `path`=None
Load `.env` from cwd (optional named arg `path=`). Does not override existing variables.
Load `.env` from cwd (optional `path=`). Does not override existing variables.
*> sys.load_dotenv path=`path`*
## stream_result
## collect
+ `events`
Reduce a `complete stream=True` event list to the final `done.result` text (or `error.message`). Unknown types (e.g. `reasoning`) are ignored.
Collapse a stream event list to final answer text (`done.result` or `error.message`). Prefer this over raw SSE fields. Alias: `stream_result`.
**answer = ""**
@@ -28,97 +31,321 @@ Reduce a `complete stream=True` event list to the final `done.result` text (or `
2. `t` == "error"
**answer = [message](ev)**
3. `t` == "delta"
4. *
4. `t` == "text"
**chunk = [text](ev)**
1. `chunk`
**answer = answer + chunk**
2. *
**_ = 1**
5. *
**_ = 1**
*answer*
# llm
## stream_result
+ `events`
Construct an LLM handle from `OPENAI_*` / `MARQDO_LLM_*`.
Compatibility alias for `collect`.
**api_key = > sys.env_get name="OPENAI_API_KEY"**
1. not `api_key`
**api_key = > sys.env_get name="MARQDO_LLM_API_KEY"**
*> collect events=`events`*
1. not `api_key`
> print text=ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY
## usage_from
+ `data`
Extract `{prompt_tokens,completion_tokens,total_tokens}` from an OpenAI-shaped response map (or empty zeros).
*> openai.usage_from data=`data`*
## create
+ `model`=None
+ `base_url`=None
+ `api_key`=None
+ `backend`=openai-compatible
+ `name`=None
Factory for an LLM handle (same as constructing `# llm`). Env fallbacks apply inside the constructor. Optional `name=` tags the handle (`fast` / `reasoning`).
**h = > llm model=`model` base_url=`base_url` api_key=`api_key` backend=`backend` name=`name`**
*h*
## fast
+ `model`=None
+ `base_url`=None
+ `api_key`=None
Named small/fast handle. Model from arg, else `MARQDO_LLM_FAST_MODEL`, else default create model.
1. `model`
**mdl = model**
2. *
**mdl = > sys.env_get name="MARQDO_LLM_FAST_MODEL"**
*> create model=`mdl` base_url=`base_url` api_key=`api_key` name="fast" backend="openai-compatible"*
## reasoning
+ `model`=None
+ `base_url`=None
+ `api_key`=None
Named strong/reasoning handle. Model from arg, else `MARQDO_LLM_REASONING_MODEL`, else default create model.
1. `model`
**mdl = model**
2. *
**mdl = > sys.env_get name="MARQDO_LLM_REASONING_MODEL"**
*> create model=`mdl` base_url=`base_url` api_key=`api_key` name="reasoning" backend="openai-compatible"*
## prompt_body
+ `src`
If `src` starts with YAML frontmatter declaring `type: prompt` / `类型: 提示`, return the body after the closing `---`; otherwise return `src` unchanged.
**sw = > text.starts_with text=`src` prefix="---"**
1. not `sw`
*src*
2. *
**parts = > split value=`src` sep="\n---\n"**
**n = > len value=`parts`**
1. `n` < 2
*src*
2. *
**fm = > at value=`parts` index=0**
**is_p = > text.contains text=`fm` sub="type: prompt"**
1. not `is_p`
**is_p = > text.contains text=`fm` sub="类型: 提示"**
2. *
**_ = 1**
1. `is_p`
**body = > at value=`parts` index=1**
*> text.str_trim s=`body`*
2. *
*src*
## prompt_load
+ `path`
Load a prompt artifact (`.mq.md` / `.md`) from disk for `ask`.
**raw = > fs.read_text path=`path`**
*> prompt_body src=`raw`*
## prompt
+ `path`=None
+ `text`=None
Prompt artifact helper: `path=` loads a file; `text=` strips `type: prompt` frontmatter from an in-memory string.
1. `path`
*> prompt_load path=`path`*
2. `text`
*> prompt_body src=`text`*
3. *
> print text=ext/ai/llm.prompt: pass path= or text=
> sys.exit code=1
**base_url = > sys.env_get name="OPENAI_BASE_URL"**
1. not `base_url`
**base_url = > sys.env_get name="MARQDO_LLM_BASE_URL"**
1. not `base_url`
**base_url = "https://api.openai.com/v1"**
## ask
+ `prompt`=None
+ `path`=None
+ `model`=None
+ `base_url`=None
+ `api_key`=None
**model = > sys.env_get name="OPENAI_MODEL"**
1. not `model`
**model = > sys.env_get name="MARQDO_LLM_MODEL"**
1. not `model`
**model = "gpt-4o-mini"**
Module convenience: create a default handle and return **answer text**. Pass `path=` to load a prompt document, `prompt=` text, or omit both to use the entry `.mq.md` as a prompt artifact (`type: prompt` body via `sys.module_source`).
1. `path`
**p = > prompt_load path=`path`**
2. `prompt`
**p = prompt**
3. *
**raw = > sys.module_source**
1. not `raw`
> print text=ext/ai/llm.ask: pass prompt= or path= (or run a prompt document as entry)
> sys.exit code=1
2. *
**p = > prompt_body src=`raw`**
**m = > create model=`model` base_url=`base_url` api_key=`api_key`**
**r = > m.ask prompt=`p`**
*[text](r)*
# llm
+ `model`=None
+ `base_url`=None
+ `api_key`=None
+ `backend`=openai-compatible
+ `name`=None
LLM handle — intelligence primitive, not an HTTP client.
Resolution: explicit args → entry-scope / Artifact Metadata (`sys.meta_get`) → `sys.env_get` → defaults.
Prefer declaring `model` / `api_key` / `base_url` in frontmatter Binding, then use the lifted names.
1. `api_key`
**key = api_key**
2. *
**key = > sys.meta_get key="api_key"**
1. not `key`
**key = > sys.env_get name="OPENAI_API_KEY"**
1. not `key`
**key = > sys.env_get name="MARQDO_LLM_API_KEY"**
2. *
**_ = 1**
2. *
**_ = 1**
1. `backend` == ollama
1. not `key`
**key = "ollama"**
2. *
**_ = 1**
2. not `key`
> print text=ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY (or pass api_key= / metadata api_key)
> sys.exit code=1
3. *
**_ = 1**
1. `base_url`
**url = base_url**
2. *
**url = > sys.meta_get key="base_url"**
1. `url`
**_ = 1**
2. `backend` == ollama
**url = > sys.env_get name="OLLAMA_HOST"**
1. not `url`
**url = "http://127.0.0.1:11434/v1"**
2. *
**_ = 1**
3. *
**url = > sys.env_get name="OPENAI_BASE_URL"**
1. not `url`
**url = > sys.env_get name="MARQDO_LLM_BASE_URL"**
2. *
**_ = 1**
1. not `url`
**url = "https://api.openai.com/v1"**
2. *
**_ = 1**
1. `model`
**mdl = model**
2. *
**mdl = > sys.meta_get key="model"**
1. `mdl`
**_ = 1**
2. *
**mdl = > sys.env_get name="OPENAI_MODEL"**
1. not `mdl`
**mdl = > sys.env_get name="MARQDO_LLM_MODEL"**
2. *
**_ = 1**
1. not `mdl`
1. `backend` == ollama
**mdl = "llama3.2"**
2. *
**mdl = "gpt-4o-mini"**
2. *
**_ = 1**
1. `name`
**nm = name**
2. *
**nm = None**
`h` =
| api_key | base_url | model | suffix | bearer |
|---------|----------|-------|--------|--------|
| `api_key` | `base_url` | `model` | /chat/completions | "Bearer " |
| _type | backend | api_key | base_url | model | suffix | bearer | name |
|-------|---------|---------|----------|-------|--------|--------|------|
| llm | `backend` | `key` | `url` | `mdl` | /chat/completions | "Bearer " | `nm` |
*h*
## ask
+ `prompt`=None
+ `path`=None
Semantic ask → **LLMResult** (`text`, `model`, `finish`, `backend`, `usage`, `name`, `tool_calls`). Prefer `[text](result)` for the answer string. Omit `prompt=` / `path=` to use the entry document (`sys.module_source` + `prompt_body`).
1. `path`
**p = > prompt_load path=`path`**
2. `prompt`
**p = prompt**
3. *
**raw = > sys.module_source**
1. not `raw`
> print text=ext/ai/llm: ask needs prompt= or path= (or entry prompt document)
> sys.exit code=1
2. *
**p = > prompt_body src=`raw`**
**pack = > self.complete_result prompt=`p` stream=False echo=False**
**text = > json.get value=`pack` key="text"**
**usage = > json.get value=`pack` key="usage"**
**finish = > json.get value=`pack` key="finish"**
**tc = > json.get value=`pack` key="tool_calls"**
1. not `tc`
**tc = > json.parse text=[]**
2. *
**_ = 1**
`result` =
| text | model | finish | backend | usage | name | llm_calls | tokens | tool_calls |
|------|-------|--------|---------|-------|------|-----------|--------|------------|
| `text` | [model](self) | `finish` | [backend](self) | `usage` | [name](self) | 1 | [total_tokens](usage) | `tc` |
*result*
## stream
+ `prompt`=None
+ `path`=None
+ `echo`=False
Semantic stream: return the event list (use `llm.collect` to reduce to text). Omit `prompt=` / `path=` to use the entry document.
1. `path`
**p = > prompt_load path=`path`**
2. `prompt`
**p = prompt**
3. *
**raw = > sys.module_source**
1. not `raw`
> print text=ext/ai/llm: stream needs prompt= or path= (or entry prompt document)
> sys.exit code=1
2. *
**p = > prompt_body src=`raw`**
*> self.complete prompt=`p` stream=True echo=`echo`*
## complete_result
+ `prompt`
+ `stream`=False
+ `echo`=False
Transport pack via `ext/ai/llm/openai` (Ollama uses the same OpenAI-compatible path). Non-stream → `{text,usage,finish}`; stream → `{events}`.
*> openai.chat_completions base_url=[base_url](self) api_key=[api_key](self) model=[model](self) prompt=`prompt` stream=`stream` echo=`echo` suffix=[suffix](self) bearer=[bearer](self)*
## complete
+ `prompt`
+ `stream`=False
+ `echo`=False
Chat completion using `self` handle fields.
Wire body is `{model, messages:[{role,content}], stream?}`. Messages are an `@` row table; headers and optional `stream` use `table.put`. `json` is only for stringify/parse.
**url = [base_url](self) + [suffix](self)**
**auth = [bearer](self) + [api_key](self)**
**headers = > table.put in=None at="Authorization" value=`auth`**
`messages` =
| @ | role | content |
|---|------|---------|
| 1 | user | `prompt` |
`req` =
| model | messages |
|-------|----------|
| [model](self) | `messages` |
Internal / compatibility primitive. Prefer `ask` / `stream` in new code.
1. `stream`
**req = > table.put in=`req` at="stream" value=True**
**body = > json.stringify value=`req`**
**resp = > net.http_post_sse url=`url` body=`body` headers=`headers` echo=`echo`**
1. [status](resp) == 200
*[events](resp)*
2. *
> print text=ext/ai/llm: HTTP error (stream)
> print text=[status](resp)
> sys.exit code=1
**pack = > self.complete_result prompt=`prompt` stream=True echo=`echo`**
*[events](pack)*
2. *
**body = > json.stringify value=`req`**
**resp = > net.http_post url=`url` body=`body` headers=`headers`**
1. [status](resp) == 200
**data = > json.parse text=[body](resp)**
*[content]([message]([1]([choices](data))))*
2. *
> print text=ext/ai/llm: HTTP error
> print text=[status](resp)
> print text=[body](resp)
> sys.exit code=1
---
**pack = > self.complete_result prompt=`prompt` stream=False echo=`echo`**
*[text](pack)*
## chat
+ `prompt`
+ `stream`=False
+ `echo`=False
Alias for `complete`.
Alias for `complete` (compat).
*> self.complete prompt=`prompt` stream=`stream` echo=`echo`*
+55
View File
@@ -0,0 +1,55 @@
---
title: ext/ai/llm/ollama
description: >-
Ollama backend defaults. Transport reuses openai-compatible /v1 chat completions.
import openai:ext/ai/llm/openai.mq.md
import sys:lib/sys.mq.md
---
## resolve
+ `model`=None
+ `base_url`=None
+ `api_key`=None
Resolve Ollama handle fields: default host `http://127.0.0.1:11434/v1`, key `ollama`, model `llama3.2`.
1. `api_key`
**key = api_key**
2. *
**key = "ollama"**
1. `base_url`
**url = base_url**
2. *
**url = > sys.env_get name="OLLAMA_HOST"**
1. not `url`
**url = "http://127.0.0.1:11434/v1"**
2. *
**_ = 1**
1. `model`
**mdl = model**
2. *
**mdl = > sys.env_get name="MARQDO_LLM_MODEL"**
1. not `mdl`
**mdl = "llama3.2"**
2. *
**_ = 1**
`cfg` =
| backend | api_key | base_url | model |
|---------|---------|----------|-------|
| ollama | `key` | `url` | `mdl` |
*cfg*
## chat_completions
+ `base_url`
+ `api_key`
+ `model`
+ `prompt`
+ `stream`=False
+ `echo`=False
*> openai.chat_completions base_url=`base_url` api_key=`api_key` model=`model` prompt=`prompt` stream=`stream` echo=`echo`*
+145
View File
@@ -0,0 +1,145 @@
---
title: ext/ai/llm/openai
description: >-
OpenAI-compatible chat completions transport (HTTP + SSE).
Prefers optional plugins/llm ABI when present; falls back to lib/net.
Used by ext/ai/llm; authors should prefer llm.ask / llm.stream.
import net:lib/net.mq.md
import json:lib/json.mq.md
import table:lib/table.mq.md
import sys:lib/sys.mq.md
import plugin:lib/plugin.mq.md
---
## usage_from
+ `data`
Extract `{prompt_tokens,completion_tokens,total_tokens}` from an OpenAI-shaped response map.
**u = > json.get value=`data` key="usage"**
1. `u`
**pt = > json.get value=`u` key="prompt_tokens"**
**ct = > json.get value=`u` key="completion_tokens"**
**tt = > json.get value=`u` key="total_tokens"**
1. not `pt`
**pt = 0**
2. *
**_ = 1**
1. not `ct`
**ct = 0**
2. *
**_ = 1**
1. not `tt`
**tt = pt + ct**
2. *
**_ = 1**
2. *
**pt = 0**
**ct = 0**
**tt = 0**
`usage` =
| prompt_tokens | completion_tokens | total_tokens |
|---------------|-------------------|--------------|
| `pt` | `ct` | `tt` |
*usage*
## tool_calls_from
+ `data`
Extract OpenAI-shaped `choices[0].message.tool_calls` as a list (or empty list).
**choices = > json.get value=`data` key="choices"**
1. not `choices`
**empty = > json.parse text=[]**
*empty*
2. *
**c0 = [1](choices)**
**msg = > json.get value=`c0` key="message"**
1. not `msg`
**empty = > json.parse text=[]**
*empty*
2. *
**tc = > json.get value=`msg` key="tool_calls"**
1. `tc`
*tc*
2. *
**empty = > json.parse text=[]**
*empty*
## chat_completions
+ `base_url`
+ `api_key`
+ `model`
+ `prompt`
+ `stream`=False
+ `echo`=False
+ `suffix`=/chat/completions
+ `bearer`="Bearer "
POST `/chat/completions` (or stream SSE). Prefers `plugins/llm` ABI (`llm_chat_completions`) when the native plugin is resolvable; otherwise `lib/net` HTTP/SSE. Non-stream → `{text,usage,finish,tool_calls}`; stream → `{events,finish}`.
**p = > plugin.native_path name="llm"**
1. `p`
> plugin.load path=`p`
*> llm_chat_completions base_url=`base_url` api_key=`api_key` model=`model` prompt=`prompt` stream=`stream` echo=`echo` suffix=`suffix` bearer=`bearer`*
2. *
**url = base_url + suffix**
**auth = bearer + api_key**
**headers = > table.put in=None at="Authorization" value=`auth`**
`messages` =
| @ | role | content |
|---|------|---------|
| 1 | user | `prompt` |
`req` =
| model | messages |
|-------|----------|
| `model` | `messages` |
1. `stream`
**req = > table.put in=`req` at="stream" value=True**
**body = > json.stringify value=`req`**
**resp = > net.http_post_sse url=`url` body=`body` headers=`headers` echo=`echo`**
1. [status](resp) == 200
**pack = > json.parse text={"finish":"stop"}**
**pack = > json.set map=`pack` key="events" value=[events](resp)**
*pack*
2. *
> print text=ext/ai/llm/openai: HTTP error (stream)
> print text=[status](resp)
> sys.exit code=1
2. *
**body = > json.stringify value=`req`**
**resp = > net.http_post url=`url` body=`body` headers=`headers`**
1. [status](resp) == 200
**data = > json.parse text=[body](resp)**
**msg = [message]([1]([choices](data)))**
**text = > json.get value=`msg` key="content"**
1. not `text`
**text = ""**
2. *
**_ = 1**
**usage = > usage_from data=`data`**
**fr = > json.get value=[1]([choices](data)) key="finish_reason"**
1. not `fr`
**fr = "stop"**
2. *
**_ = 1**
**tc = > tool_calls_from data=`data`**
**pack = > json.parse text={"finish":"stop"}**
**pack = > json.set map=`pack` key="text" value=`text`**
**pack = > json.set map=`pack` key="usage" value=`usage`**
**pack = > json.set map=`pack` key="finish" value=`fr`**
**pack = > json.set map=`pack` key="tool_calls" value=`tc`**
*pack*
2. *
> print text=ext/ai/llm/openai: HTTP error
> print text=[status](resp)
> print text=[body](resp)
> sys.exit code=1
+238 -72
View File
@@ -1,24 +1,23 @@
---
title: ext/ai/大模型
description: OpenAI 兼容大模型对象(中文)。导入 ext/ai/大模型.mq.md。
description: >-
Marqdo 大模型智能原语 — 提问 / 流式 / 收集 / 命名句柄。
OpenAI 兼容与 Ollama HTTP 藏在语义面之后。
导入 系统:lib/系统.mq.md
导入 网络:lib/网络.mq.md
import json:lib/json.mq.md
导入 表:lib/表.mq.md
导入 文件:lib/文件.mq.md
导入 文本:lib/文本.mq.md
import openai:ext/ai/llm/openai.mq.md
---
## 加载环境
+ `路径`=None
从工作目录加载 `.env`(可选命名实参 `路径=`)。不覆盖已有变量。
*> 系统.加载环境 路径=`路径`*
## 流式结果
## 收集
+ `事件`
把 `运行 流式=真` 的事件列表收成最终 `done.result`(或 `error.message`)。未知类型(如 `reasoning`)忽略。
**answer = ""**
- [ev](事件)
@@ -28,97 +27,264 @@ import json:lib/json.mq.md
2. `t` == "error"
**answer = [message](ev)**
3. `t` == "delta"
4. *
4. `t` == "text"
**chunk = [text](ev)**
1. `chunk`
**answer = answer + chunk**
2. *
**_ = 1**
5. *
**_ = 1**
*answer*
# 大模型
## 流式结果
+ `事件`
从 `OPENAI_*` / `MARQDO_LLM_*` 构造句柄。
*> 收集 事件=`事件`*
**api_key = > 系统.取环境 名="OPENAI_API_KEY"**
1. 非 `api_key`
**api_key = > 系统.取环境 名="MARQDO_LLM_API_KEY"**
## 用量
+ `数据`
1. 非 `api_key`
> 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY
*> openai.usage_from data=`数据`*
## 创建
+ `模型`=None
+ `基址`=None
+ `密钥`=None
+ `后端`=openai-compatible
+ `名`=None
**h = > 大模型 模型=`模型` 基址=`基址` 密钥=`密钥` 后端=`后端` 名=`名`**
*h*
## 快速
+ `模型`=None
+ `基址`=None
+ `密钥`=None
1. `模型`
**mdl = 模型**
2. *
**mdl = > 系统.取环境 名="MARQDO_LLM_FAST_MODEL"**
*> 创建 模型=`mdl` 基址=`基址` 密钥=`密钥` 名="fast" 后端="openai-compatible"*
## 推理
+ `模型`=None
+ `基址`=None
+ `密钥`=None
1. `模型`
**mdl = 模型**
2. *
**mdl = > 系统.取环境 名="MARQDO_LLM_REASONING_MODEL"**
*> 创建 模型=`mdl` 基址=`基址` 密钥=`密钥` 名="reasoning" 后端="openai-compatible"*
## 提示正文
+ `源`
**sw = > 文本.开头是 内容=`源` 前缀="---"**
1. 非 `sw`
*源*
2. *
**parts = > split value=`源` sep="\n---\n"**
**n = > len value=`parts`**
1. `n` < 2
*源*
2. *
**fm = > at value=`parts` index=0**
**is_p = > 文本.包含 内容=`fm` 子串="type: prompt"**
1. 非 `is_p`
**is_p = > 文本.包含 内容=`fm` 子串="类型: 提示"**
2. *
**_ = 1**
1. `is_p`
**body = > at value=`parts` index=1**
*> 文本.去空白 s=`body`*
2. *
*源*
## 加载提示
+ `路径`
**raw = > 文件.读文本 路径=`路径`**
*> 提示正文 源=`raw`*
## 提示
+ `路径`=None
+ `文本`=None
1. `路径`
*> 加载提示 路径=`路径`*
2. `文本`
*> 提示正文 源=`文本`*
3. *
> 打印 内容=ext/ai/大模型.提示: 请传 路径= 或 文本=
> 系统.退出 码=1
**base_url = > 系统.取环境 名="OPENAI_BASE_URL"**
1. 非 `base_url`
**base_url = > 系统.取环境 名="MARQDO_LLM_BASE_URL"**
1. 非 `base_url`
**base_url = "https://api.openai.com/v1"**
## 提问
+ `提示`=None
+ `路径`=None
+ `模型`=None
+ `基址`=None
+ `密钥`=None
**model = > 系统.取环境 名="OPENAI_MODEL"**
1. 非 `model`
**model = > 系统.取环境 名="MARQDO_LLM_MODEL"**
1. 非 `model`
**model = "gpt-4o-mini"**
1. `路径`
**p = > 加载提示 路径=`路径`**
2. `提示`
**p = 提示**
3. *
> 打印 内容=ext/ai/大模型.提问: 请传 提示= 或 路径=
> 系统.退出 码=1
**m = > 创建 模型=`模型` 基址=`基址` 密钥=`密钥`**
**r = > m.提问 提示=`p`**
*[text](r)*
# 大模型
+ `模型`=None
+ `基址`=None
+ `密钥`=None
+ `后端`=openai-compatible
+ `名`=None
1. `密钥`
**key = 密钥**
2. *
**key = > 系统.取环境 名="OPENAI_API_KEY"**
1. 非 `key`
**key = > 系统.取环境 名="MARQDO_LLM_API_KEY"**
2. *
**_ = 1**
1. `后端` == ollama
1. 非 `key`
**key = "ollama"**
2. *
**_ = 1**
2. 非 `key`
> 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY
> 系统.退出 码=1
3. *
**_ = 1**
1. `基址`
**url = 基址**
2. `后端` == ollama
**url = > 系统.取环境 名="OLLAMA_HOST"**
1. 非 `url`
**url = "http://127.0.0.1:11434/v1"**
2. *
**_ = 1**
3. *
**url = > 系统.取环境 名="OPENAI_BASE_URL"**
1. 非 `url`
**url = > 系统.取环境 名="MARQDO_LLM_BASE_URL"**
2. *
**_ = 1**
1. 非 `url`
**url = "https://api.openai.com/v1"**
2. *
**_ = 1**
1. `模型`
**mdl = 模型**
2. *
**mdl = > 系统.取环境 名="OPENAI_MODEL"**
1. 非 `mdl`
**mdl = > 系统.取环境 名="MARQDO_LLM_MODEL"**
2. *
**_ = 1**
1. 非 `mdl`
1. `后端` == ollama
**mdl = "llama3.2"**
2. *
**mdl = "gpt-4o-mini"**
2. *
**_ = 1**
1. `名`
**nm = 名**
2. *
**nm = None**
`h` =
| api_key | base_url | model | suffix | bearer |
|---------|----------|-------|--------|--------|
| `api_key` | `base_url` | `model` | /chat/completions | "Bearer " |
| _type | backend | api_key | base_url | model | suffix | bearer | name |
|-------|---------|---------|----------|-------|--------|--------|------|
| 大模型 | `后端` | `key` | `url` | `mdl` | /chat/completions | "Bearer " | `nm` |
*h*
## 提问
+ `提示`=None
+ `路径`=None
1. `路径`
**p = > 加载提示 路径=`路径`**
2. `提示`
**p = 提示**
3. *
> 打印 内容=ext/ai/大模型: 提问需要 提示= 或 路径=
> 系统.退出 码=1
**pack = > 自.完整结果 提示=`p` 流式=False 打印增量=False**
**text = > json.get value=`pack` key="text"**
**usage = > json.get value=`pack` key="usage"**
**finish = > json.get value=`pack` key="finish"**
**tc = > json.get value=`pack` key="tool_calls"**
1. not `tc`
**tc = > json.parse text=[]**
2. *
**_ = 1**
`result` =
| text | model | finish | backend | usage | name | llm_calls | tokens | tool_calls |
|------|-------|--------|---------|-------|------|-----------|--------|------------|
| `text` | [model](自) | `finish` | [backend](自) | `usage` | [name](自) | 1 | [total_tokens](usage) | `tc` |
*result*
## 流式
+ `提示`=None
+ `路径`=None
+ `打印增量`=False
1. `路径`
**p = > 加载提示 路径=`路径`**
2. `提示`
**p = 提示**
3. *
> 打印 内容=ext/ai/大模型: 流式需要 提示= 或 路径=
> 系统.退出 码=1
*> 自.运行 提示=`p` 流式=True 打印增量=`打印增量`*
## 完整结果
+ `提示`
+ `流式`=False
+ `打印增量`=False
*> openai.chat_completions base_url=[base_url](自) api_key=[api_key](自) model=[model](自) prompt=`提示` stream=`流式` echo=`打印增量` suffix=[suffix](自) bearer=[bearer](自)*
## 运行
+ `提示`
+ `流式`=False
+ `打印增量`=False
使用 `自` 句柄字段做聊天补全。
线上 body 为 `{model, messages:[{role,content}], stream?}`。消息用 `@` 行向表;headers 与可选 `stream` 用 `表.改`。`json` 只做 stringify/parse。
**url = [base_url](自) + [suffix](自)**
**auth = [bearer](自) + [api_key](自)**
**headers = > 表.改 入=None 于="Authorization" 值=`auth`**
`messages` =
| @ | role | content |
|---|------|---------|
| 1 | user | `提示` |
`req` =
| model | messages |
|-------|----------|
| [model](自) | `messages` |
1. `流式`
**req = > 表.改 入=`req` 于="stream" 值=True**
**body = > json.stringify value=`req`**
**resp = > 网络.提交流式 地址=`url` 内容=`body` headers=`headers` 打印增量=`打印增量`**
1. [status](resp) == 200
*[events](resp)*
2. *
> 打印 内容=ext/ai/大模型: HTTP 错误(流式)
> 打印 内容=[status](resp)
> 系统.退出 码=1
**pack = > 自.完整结果 提示=`提示` 流式=True 打印增量=`打印增量`**
*[events](pack)*
2. *
**body = > json.stringify value=`req`**
**resp = > 网络.提交 地址=`url` 内容=`body` headers=`headers`**
1. [status](resp) == 200
**data = > json.parse text=[body](resp)**
*[content]([message]([1]([choices](data))))*
2. *
> 打印 内容=ext/ai/大模型: HTTP 错误
> 打印 内容=[status](resp)
> 打印 内容=[body](resp)
> 系统.退出 码=1
---
**pack = > 自.完整结果 提示=`提示` 流式=False 打印增量=`打印增量`**
*[text](pack)*
## 聊天
+ `提示`
+ `流式`=False
+ `打印增量`=False
运行 的别名。
*> 自.运行 提示=`提示` 流式=`流式` 打印增量=`打印增量`*
+110 -1
View File
@@ -1,6 +1,6 @@
---
title: ext/ai/智能体
description: 文档驱动智能体 — 单步 / 多步;工具经 lib/子任务;运行时经 ABI v2 agent 插件。
description: 文档驱动智能体 v2 — 单步 / 多步 / 运行;技能编译经 ABI v2 agent 插件(情景 → 学习 → llm_free)。
导入 大模型:ext/ai/大模型.mq.md
import agent:ext/ai/agent.mq.md
import json:lib/json.mq.md
@@ -212,3 +212,112 @@ import json:lib/json.mq.md
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.plan goal=`目标` workbook_dir=`工作簿目录` workbook=`工作簿` max_rounds=`最大轮次` confirm=`确认分解` writeback=`写回` skeleton=`骨架` reuse=`复用` optimize=`优化` force=`强制` soft_match=`软命中` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` kb_dir=`知识库目录` improve_every=`改进周期` explore_n=`探索次数` stream=`流式` echo=`打印增量` trace=`轨迹`*
## 解析
+ `任务`
+ `知识库目录`=.marqdo/agent-kb
+ `近义命中`=True
+ `近义阈值`=0.78
技能解析(v2):exact → alias → canonical → near。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.resolve task=`任务` kb_dir=`知识库目录` near_match=`近义命中` near_threshold=`近义阈值`*
## 记录情景
+ `任务`
+ `状态`=ok
+ `结果`=None
+ `模式`=explore
+ `技能`=none
+ `观察`=None
+ `工作簿`=None
+ `缓存`=None
+ `匹配`=None
+ `大模型次数`=0
+ `工具次数`=0
+ `错误`=None
+ `记忆目录`=.marqdo/agent-memory
将一次执行沉淀为 `.mq.md` 情景记忆。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.record_episode task=`任务` status=`状态` result=`结果` mode=`模式` skill=`技能` observation=`观察` workbook=`工作簿` cache=`缓存` match=`匹配` llm_calls=`大模型次数` tool_calls=`工具次数` error=`错误` memory_dir=`记忆目录`*
## 尝试学习
+ `任务`
+ `知识库目录`=.marqdo/agent-kb
+ `记忆目录`=.marqdo/agent-memory
+ `改进周期`=3
+ `晋升`=True
情景足够时:归纳 → 合成候选 → 编译 → 可选晋升为 `llm_free` 技能。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.maybe_learn task=`任务` kb_dir=`知识库目录` memory_dir=`记忆目录` improve_every=`改进周期` promote=`晋升`*
## 运行
+ `任务`
+ `知识库目录`=.marqdo/agent-kb
+ `记忆目录`=.marqdo/agent-memory
+ `学习`=True
+ `校验`=True
+ `写回`=True
+ `复用`=True
+ `近义命中`=True
+ `近义阈值`=0.78
+ `晋升`=True
+ `改进周期`=3
+ `探索次数`=3
+ `最大轮次`=4
+ `流式`=False
+ `打印增量`=False
+ `轨迹`=False
+ `强制`=False
+ `路由`=auto
+ `路由模型`=None
v2+P4 主入口:自适应路由 → 执行 → 记录情景 → 尝试学习(技能 + 策略)。`路由`=`auto`|`marqdo`|`small-llm`|`llm`(`jev` 为 `small-llm` 兼容别名);决策器用 `路由模型`(任意 llm 句柄)。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.run task=`任务` kb_dir=`知识库目录` memory_dir=`记忆目录` learn=`学习` verify=`校验` writeback=`写回` reuse=`复用` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` improve_every=`改进周期` explore_n=`探索次数` max_rounds=`最大轮次` stream=`流式` echo=`打印增量` trace=`轨迹` force=`强制` router=`路由` router_model=`路由模型`*
## 路由
+ `任务`
+ `后端`=auto
+ `知识库目录`=.marqdo/agent-kb
+ `记忆目录`=.marqdo/agent-memory
+ `阈值`=0.78
自适应路由(阶段 4):`marqdo` / `small-llm` / `llm` / `auto`(`jev`→别名)。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.route task=`任务` backend=`后端` kb_dir=`知识库目录` memory_dir=`记忆目录` threshold=`阈值`*
## 编译策略
+ `记忆目录`=.marqdo/agent-memory
+ `最少证据`=3
+ `强制`=False
策略编译:稳定的 task→skill 映射 → `policies/router.mq.md`。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.compile_policy memory_dir=`记忆目录` min_evidence=`最少证据` force=`强制`*
+19
View File
@@ -39,6 +39,25 @@ Current working directory.
*> host_cwd*
## meta
Bound Artifact Metadata from the entry `.mq.md` (map). See `doc/design/binding.md`.
*> host_meta*
## meta_get
+ `key`
Lookup one metadata key; missing → None.
*> host_meta_get key=`key`*
## module_source
Entry `.mq.md` source text (for document-as-prompt). Empty string if unset.
*> host_module_source*
## exit
+ `code`
+19
View File
@@ -39,6 +39,25 @@ description: 中文系统包装(加载环境 可选 路径=)
*> host_cwd*
## 元信息
入口 `.mq.md` 已绑定的 Artifact Metadata(映射)。见 `doc/design/binding.md`。
*> host_meta*
## 取元信息
+ `键`
按键取一条元信息;缺失 → None。
*> host_meta_get key=`键`*
## 模块源码
入口 `.mq.md` 全文(供 document-as-prompt)。未设置时为空文本。
*> host_module_source*
## 退出
+ `码`
+1 -1
View File
@@ -1269,7 +1269,7 @@ pub fn workbook_solidify(args: &Value) -> Result<Value, String> {
};
let lit = marqdo_quoted_text(&result);
let body = format!(
"---\ntitle: agent workbook\n---\n\n# main\n\n*`result` = {lit} *\n**`result`**\n"
"---\ntitle: agent workbook\n---\n\n# main\n\n**`result` = {lit}**\n*`result`*\n"
);
fs::write(&p, body).map_err(|e| format!("solidify write: {e}"))?;
Ok(json!({
+134 -1
View File
@@ -1,8 +1,12 @@
//! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query + agent-kb.
//! Agent plugin (C ABI v2): layout helpers + session bag + context via host_query + agent-kb + v2 memory + adaptive route.
mod corpus;
mod kb;
mod mcp_client;
mod mcp_server;
mod memory;
mod resume;
mod route;
use std::collections::HashMap;
use std::ffi::{CStr, CString};
@@ -902,6 +906,30 @@ kb_ffi!(
"agent_workbook_solidify"
);
kb_ffi!(agent_kb_task_files, kb::kb_task_files, "agent_kb_task_files");
kb_ffi!(agent_memory_ensure, memory::memory_ensure, "agent_memory_ensure");
kb_ffi!(agent_record_episode, memory::record_episode, "agent_record_episode");
kb_ffi!(agent_list_episodes, memory::list_episodes, "agent_list_episodes");
kb_ffi!(agent_get_episode, memory::get_episode, "agent_get_episode");
kb_ffi!(agent_cluster_episodes, memory::cluster_episodes, "agent_cluster_episodes");
kb_ffi!(agent_extract_pattern, memory::extract_pattern, "agent_extract_pattern");
kb_ffi!(agent_generalize, memory::generalize, "agent_generalize");
kb_ffi!(agent_synthesize_skill, memory::synthesize_skill, "agent_synthesize_skill");
kb_ffi!(agent_compile_skill, memory::compile_skill, "agent_compile_skill");
kb_ffi!(agent_maybe_learn, memory::maybe_learn, "agent_maybe_learn");
kb_ffi!(agent_metrics, memory::metrics, "agent_metrics");
kb_ffi!(agent_resolve, memory::resolve_task, "agent_resolve");
kb_ffi!(agent_route, route::route, "agent_route");
kb_ffi!(agent_route_apply, route::route_apply, "agent_route_apply");
kb_ffi!(agent_compile_policy, route::compile_policy, "agent_compile_policy");
kb_ffi!(
agent_maybe_compile_policy,
route::maybe_compile_policy,
"agent_maybe_compile_policy"
);
kb_ffi!(agent_resume_save, resume::resume_save, "agent_resume_save");
kb_ffi!(agent_resume_load, resume::resume_load, "agent_resume_load");
kb_ffi!(agent_resume_clear, resume::resume_clear, "agent_resume_clear");
kb_ffi!(agent_resume_list, resume::resume_list, "agent_resume_list");
#[no_mangle]
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
@@ -1001,6 +1029,27 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
{
return 1;
}
if register(
host,
"agent_mcp_client",
"action,command",
mcp_client::agent_mcp_client,
) != 0
{
return 1;
}
if register(host, "agent_resume_save", "id,goal,status,round", agent_resume_save) != 0 {
return 1;
}
if register(host, "agent_resume_load", "id,resume_dir", agent_resume_load) != 0 {
return 1;
}
if register(host, "agent_resume_clear", "id,resume_dir", agent_resume_clear) != 0 {
return 1;
}
if register(host, "agent_resume_list", "resume_dir", agent_resume_list) != 0 {
return 1;
}
if register(host, "agent_kb_add_alias", "kb_dir,slug,alias", agent_kb_add_alias) != 0 {
return 1;
}
@@ -1022,6 +1071,90 @@ pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int
if register(host, "agent_kb_task_files", "kb_dir,goal", agent_kb_task_files) != 0 {
return 1;
}
if register(host, "agent_memory_ensure", "memory_dir", agent_memory_ensure) != 0 {
return 1;
}
if register(
host,
"agent_record_episode",
"task,status,result,mode",
agent_record_episode,
) != 0
{
return 1;
}
if register(host, "agent_list_episodes", "memory_dir,task", agent_list_episodes) != 0 {
return 1;
}
if register(host, "agent_get_episode", "id", agent_get_episode) != 0 {
return 1;
}
if register(
host,
"agent_cluster_episodes",
"memory_dir,task,threshold",
agent_cluster_episodes,
) != 0
{
return 1;
}
if register(host, "agent_extract_pattern", "task", agent_extract_pattern) != 0 {
return 1;
}
if register(host, "agent_generalize", "task", agent_generalize) != 0 {
return 1;
}
if register(host, "agent_synthesize_skill", "task", agent_synthesize_skill) != 0 {
return 1;
}
if register(
host,
"agent_compile_skill",
"task,kb_dir,min_evidence",
agent_compile_skill,
) != 0
{
return 1;
}
if register(
host,
"agent_maybe_learn",
"task,kb_dir,improve_every",
agent_maybe_learn,
) != 0
{
return 1;
}
if register(host, "agent_metrics", "memory_dir", agent_metrics) != 0 {
return 1;
}
if register(host, "agent_resolve", "task,kb_dir", agent_resolve) != 0 {
return 1;
}
if register(host, "agent_route", "task,backend,kb_dir,memory_dir", agent_route) != 0 {
return 1;
}
if register(host, "agent_route_apply", "task,reply,kb_dir", agent_route_apply) != 0 {
return 1;
}
if register(
host,
"agent_compile_policy",
"memory_dir,min_evidence",
agent_compile_policy,
) != 0
{
return 1;
}
if register(
host,
"agent_maybe_compile_policy",
"memory_dir,min_evidence",
agent_maybe_compile_policy,
) != 0
{
return 1;
}
0
}
+327
View File
@@ -0,0 +1,327 @@
//! MCP Client (stdio JSON-RPC) — spawn a server process, initialize, list/call tools.
use serde_json::{json, Value};
use std::ffi::CStr;
use std::io::{BufRead, BufReader, Write};
use std::os::raw::{c_char, c_int};
use std::process::{Child, Command, Stdio};
use std::sync::Mutex;
use std::time::Duration;
use crate::{parse_args, set_err, set_out};
struct Session {
child: Child,
stdin: std::process::ChildStdin,
reader: BufReader<std::process::ChildStdout>,
next_id: i64,
server_name: String,
}
static SESSIONS: Mutex<Vec<(String, Session)>> = Mutex::new(Vec::new());
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
args.get(key).and_then(|v| v.as_str()).filter(|s| !s.is_empty())
}
fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
opt_text(args, key).ok_or_else(|| format!("missing text `{key}`"))
}
fn write_rpc(stdin: &mut impl Write, msg: &Value) -> Result<(), String> {
let s = serde_json::to_string(msg).map_err(|e| e.to_string())?;
writeln!(stdin, "{s}").map_err(|e| format!("mcp client write: {e}"))?;
stdin.flush().map_err(|e| format!("mcp client flush: {e}"))?;
Ok(())
}
fn read_rpc(reader: &mut impl BufRead) -> Result<Value, String> {
let mut line = String::new();
loop {
line.clear();
let n = reader
.read_line(&mut line)
.map_err(|e| format!("mcp client read: {e}"))?;
if n == 0 {
return Err("mcp client: server closed stdout".into());
}
let t = line.trim();
if t.is_empty() {
continue;
}
return serde_json::from_str(t).map_err(|e| format!("mcp client json: {e}"));
}
}
fn rpc_call(session: &mut Session, method: &str, params: Value) -> Result<Value, String> {
let id = session.next_id;
session.next_id += 1;
let req = json!({
"jsonrpc": "2.0",
"id": id,
"method": method,
"params": params,
});
write_rpc(&mut session.stdin, &req)?;
// Read until matching id (skip notifications).
for _ in 0..64 {
let resp = read_rpc(&mut session.reader)?;
if resp.get("id") == Some(&json!(id)) {
if let Some(err) = resp.get("error") {
let msg = err
.get("message")
.and_then(|v| v.as_str())
.unwrap_or("rpc error");
return Err(msg.to_string());
}
return Ok(resp.get("result").cloned().unwrap_or(Value::Null));
}
}
Err("mcp client: no matching response".into())
}
fn spawn_session(command: &str, args: &[String], name: &str) -> Result<Session, String> {
let mut cmd = Command::new(command);
for a in args {
cmd.arg(a);
}
cmd.stdin(Stdio::piped())
.stdout(Stdio::piped())
.stderr(Stdio::inherit());
let mut child = cmd
.spawn()
.map_err(|e| format!("mcp client spawn `{command}`: {e}"))?;
let stdin = child
.stdin
.take()
.ok_or_else(|| "mcp client: no stdin".to_string())?;
let stdout = child
.stdout
.take()
.ok_or_else(|| "mcp client: no stdout".to_string())?;
let mut session = Session {
child,
stdin,
reader: BufReader::new(stdout),
next_id: 1,
server_name: name.to_string(),
};
// initialize
let _ = rpc_call(
&mut session,
"initialize",
json!({
"protocolVersion": "2024-11-05",
"capabilities": {},
"clientInfo": { "name": "marqdo-agent", "version": "0.1.0" }
}),
)?;
// optional initialized notification
let _ = write_rpc(
&mut session.stdin,
&json!({
"jsonrpc": "2.0",
"method": "notifications/initialized",
"params": {}
}),
);
let _ = session.server_name;
// Give slow servers a beat (ignore).
let _ = Duration::from_millis(1);
Ok(session)
}
fn command_args(args: &Value) -> Result<(String, Vec<String>), String> {
let command = arg_text(args, "command")?;
let mut argv = Vec::new();
if let Some(arr) = args.get("args").and_then(|v| v.as_array()) {
for a in arr {
if let Some(s) = a.as_str() {
argv.push(s.to_string());
} else {
argv.push(a.to_string());
}
}
} else if let Some(s) = opt_text(args, "args") {
// space-split simple args
for part in s.split_whitespace() {
argv.push(part.to_string());
}
}
Ok((command.to_string(), argv))
}
fn session_id_of(args: &Value) -> String {
opt_text(args, "session")
.or_else(|| opt_text(args, "id"))
.unwrap_or("default")
.to_string()
}
fn with_session<F>(args: &Value, f: F) -> Result<Value, String>
where
F: FnOnce(&mut Session) -> Result<Value, String>,
{
let sid = session_id_of(args);
let mut guard = SESSIONS
.lock()
.map_err(|_| "mcp client: session lock poisoned".to_string())?;
let idx = guard
.iter()
.position(|(id, _)| id == &sid)
.ok_or_else(|| format!("mcp client: no session `{sid}` (call connect first)"))?;
f(&mut guard[idx].1)
}
fn action_connect(args: &Value) -> Result<Value, String> {
let (command, argv) = command_args(args)?;
let name = opt_text(args, "name").unwrap_or("mcp");
let sid = session_id_of(args);
let session = spawn_session(&command, &argv, name)?;
let mut guard = SESSIONS
.lock()
.map_err(|_| "mcp client: session lock poisoned".to_string())?;
// Replace existing
guard.retain(|(id, _)| id != &sid);
guard.push((sid.clone(), session));
Ok(json!({
"ok": true,
"session": sid,
"transport": "stdio",
"command": command,
}))
}
fn action_list(args: &Value) -> Result<Value, String> {
with_session(args, |s| {
let result = rpc_call(s, "tools/list", json!({}))?;
let mut out = result;
if let Some(obj) = out.as_object_mut() {
obj.insert("authority".into(), json!("workbook"));
obj.insert("session".into(), json!(session_id_of(args)));
}
Ok(out)
})
}
fn action_call(args: &Value) -> Result<Value, String> {
let name = arg_text(args, "name")?;
let arguments = args.get("arguments").cloned().unwrap_or(json!({}));
with_session(args, |s| {
let result = rpc_call(
s,
"tools/call",
json!({ "name": name, "arguments": arguments }),
)?;
let mut out = if result.is_object() {
result
} else {
json!({ "result": result })
};
if let Some(obj) = out.as_object_mut() {
obj.insert("authority".into(), json!("workbook"));
obj.insert("session".into(), json!(session_id_of(args)));
}
Ok(out)
})
}
fn action_close(args: &Value) -> Result<Value, String> {
let sid = session_id_of(args);
let mut guard = SESSIONS
.lock()
.map_err(|_| "mcp client: session lock poisoned".to_string())?;
if let Some(idx) = guard.iter().position(|(id, _)| id == &sid) {
let (_, mut session) = guard.remove(idx);
let _ = session.child.kill();
let _ = session.child.wait();
Ok(json!({ "ok": true, "session": sid, "closed": true }))
} else {
Ok(json!({ "ok": true, "session": sid, "closed": false }))
}
}
/// One-shot: connect → list or call → close (no persistent session).
fn action_oneshot(args: &Value, kind: &str) -> Result<Value, String> {
let (command, argv) = command_args(args)?;
let name = opt_text(args, "name").unwrap_or("mcp");
let mut session = spawn_session(&command, &argv, name)?;
let result = match kind {
"list" => {
let r = rpc_call(&mut session, "tools/list", json!({}))?;
Ok(r)
}
"call" => {
let tname = arg_text(args, "tool").or_else(|_| arg_text(args, "name"))?;
// When oneshot call, `name` may be server name — prefer `tool=`.
let tname = opt_text(args, "tool").unwrap_or(tname);
let arguments = args.get("arguments").cloned().unwrap_or(json!({}));
rpc_call(
&mut session,
"tools/call",
json!({ "name": tname, "arguments": arguments }),
)
}
_ => Err(format!("unknown oneshot kind `{kind}`")),
};
let _ = session.child.kill();
let _ = session.child.wait();
let mut out = result?;
if let Some(obj) = out.as_object_mut() {
obj.insert("authority".into(), json!("workbook"));
obj.insert("transport".into(), json!("stdio"));
}
Ok(out)
}
pub fn mcp_client(args: &Value) -> Result<Value, String> {
let action = opt_text(args, "action").unwrap_or("list");
match action {
"connect" => action_connect(args),
"list" => {
if opt_text(args, "command").is_some() && opt_text(args, "session").is_none() {
action_oneshot(args, "list")
} else {
action_list(args)
}
}
"call" => {
if opt_text(args, "command").is_some() && opt_text(args, "session").is_none() {
action_oneshot(args, "call")
} else {
action_call(args)
}
}
"close" | "disconnect" => action_close(args),
other => Err(format!(
"mcp client: unknown action `{other}` (connect|list|call|close)"
)),
}
}
pub unsafe extern "C" fn agent_mcp_client(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int {
let args = match parse_args(args_json) {
Ok(v) => v,
Err(e) => {
set_err(err_msg, &e);
return 1;
}
};
match mcp_client(&args) {
Ok(v) => {
set_out(out_json, &v.to_string());
0
}
Err(e) => {
set_err(err_msg, &e);
1
}
}
}
#[allow(dead_code)]
fn _unused(_: &CStr) {}
File diff suppressed because it is too large. Load diff
+181
View File
@@ -0,0 +1,181 @@
//! Agent plan/run resume checkpoints under `.marqdo/agent-resume/`.
use std::fs;
use std::path::{Path, PathBuf};
use serde_json::{json, Value};
const DEFAULT_RESUME_DIR: &str = ".marqdo/agent-resume";
fn resolve_path(rel: &str) -> PathBuf {
let p = PathBuf::from(rel);
if p.is_absolute() {
return p;
}
if p.exists() {
return p;
}
let base = (|| {
let q = crate::host_query_json("cwd")?;
q.as_str()
.map(PathBuf::from)
.ok_or_else(|| "cwd not text".to_string())
})()
.or_else(|_| std::env::current_dir().map_err(|e| e.to_string()))
.unwrap_or_else(|_| PathBuf::from("."));
base.join(p)
}
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
args.get(key).and_then(|v| v.as_str()).filter(|s| !s.is_empty())
}
fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
opt_text(args, key).ok_or_else(|| format!("missing text `{key}`"))
}
fn opt_i64(args: &Value, key: &str, default: i64) -> i64 {
match args.get(key) {
None | Some(Value::Null) => default,
Some(Value::Number(n)) => n.as_i64().unwrap_or(default),
Some(Value::String(s)) => s.parse().unwrap_or(default),
_ => default,
}
}
fn resume_root(args: &Value) -> PathBuf {
let rel = opt_text(args, "resume_dir").unwrap_or(DEFAULT_RESUME_DIR);
resolve_path(rel)
}
fn checkpoint_path(root: &Path, id: &str) -> PathBuf {
let safe: String = id
.chars()
.map(|c| {
if c.is_ascii_alphanumeric() || c == '-' || c == '_' {
c
} else {
'_'
}
})
.collect();
root.join(format!("{safe}.json"))
}
fn now_rfc3339() -> String {
chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true)
}
fn ensure_dir(root: &Path) -> Result<(), String> {
fs::create_dir_all(root).map_err(|e| format!("resume mkdir: {e}"))
}
pub fn resume_save(args: &Value) -> Result<Value, String> {
let id = arg_text(args, "id")?;
let root = resume_root(args);
ensure_dir(&root)?;
let path = checkpoint_path(&root, id);
let mut doc = json!({
"id": id,
"updated_at": now_rfc3339(),
});
if let Some(obj) = doc.as_object_mut() {
for key in [
"goal", "task", "status", "workbook", "events", "route", "result", "round", "meta",
] {
if let Some(v) = args.get(key) {
if !v.is_null() {
obj.insert(key.to_string(), v.clone());
}
}
}
if !obj.contains_key("round") {
obj.insert("round".into(), json!(opt_i64(args, "round", 0)));
}
if !obj.contains_key("status") {
obj.insert("status".into(), json!("running"));
}
}
let text = serde_json::to_string_pretty(&doc).map_err(|e| e.to_string())?;
fs::write(&path, text).map_err(|e| format!("resume save: {e}"))?;
Ok(json!({
"ok": true,
"id": id,
"path": path.to_string_lossy(),
"updated_at": doc.get("updated_at").cloned().unwrap_or(Value::Null),
}))
}
pub fn resume_load(args: &Value) -> Result<Value, String> {
let id = arg_text(args, "id")?;
let root = resume_root(args);
let path = checkpoint_path(&root, id);
if !path.is_file() {
return Ok(json!({
"ok": false,
"found": false,
"id": id,
"path": path.to_string_lossy(),
}));
}
let text = fs::read_to_string(&path).map_err(|e| format!("resume load: {e}"))?;
let mut doc: Value = serde_json::from_str(&text).map_err(|e| format!("resume json: {e}"))?;
if let Some(obj) = doc.as_object_mut() {
obj.insert("ok".into(), json!(true));
obj.insert("found".into(), json!(true));
obj.insert("path".into(), json!(path.to_string_lossy()));
}
Ok(doc)
}
pub fn resume_clear(args: &Value) -> Result<Value, String> {
let id = arg_text(args, "id")?;
let root = resume_root(args);
let path = checkpoint_path(&root, id);
let existed = path.is_file();
if existed {
fs::remove_file(&path).map_err(|e| format!("resume clear: {e}"))?;
}
Ok(json!({
"ok": true,
"id": id,
"cleared": existed,
"path": path.to_string_lossy(),
}))
}
pub fn resume_list(args: &Value) -> Result<Value, String> {
let root = resume_root(args);
if !root.is_dir() {
return Ok(json!({ "ok": true, "items": [], "resume_dir": root.to_string_lossy() }));
}
let mut items = Vec::new();
let rd = fs::read_dir(&root).map_err(|e| format!("resume list: {e}"))?;
for ent in rd.flatten() {
let p = ent.path();
if p.extension().and_then(|e| e.to_str()) != Some("json") {
continue;
}
let id = p
.file_stem()
.and_then(|s| s.to_str())
.unwrap_or("")
.to_string();
let meta = fs::metadata(&p).ok();
items.push(json!({
"id": id,
"path": p.to_string_lossy(),
"len": meta.map(|m| m.len()).unwrap_or(0),
}));
}
items.sort_by(|a, b| {
let ai = a.get("id").and_then(|v| v.as_str()).unwrap_or("");
let bi = b.get("id").and_then(|v| v.as_str()).unwrap_or("");
ai.cmp(bi)
});
Ok(json!({
"ok": true,
"items": items,
"resume_dir": root.to_string_lossy(),
}))
}
+719
View File
@@ -0,0 +1,719 @@
//! Adaptive Routing / Policy Compilation (Phase 4).
//! Router is abstract: marqdo | small-llm | llm | auto.
//! `jev` is accepted as an alias of `small-llm` (compat); not a first-class backend.
use std::collections::HashMap;
use std::fs;
use std::path::{Path, PathBuf};
use serde_json::{json, Value};
use crate::kb::{goal_sig_hex, goal_slug_str, normalize_goal};
use crate::memory::{self};
const DEFAULT_MEMORY_DIR: &str = ".marqdo/agent-memory";
const DEFAULT_KB_DIR: &str = ".marqdo/agent-kb";
const POLICY_NAME: &str = "router.mq.md";
fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
args.get(key)
.and_then(|v| v.as_str())
.ok_or_else(|| format!("missing text `{key}`"))
}
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
args.get(key).and_then(|v| v.as_str()).filter(|s| !s.is_empty())
}
fn opt_i64(args: &Value, key: &str, default: i64) -> i64 {
match args.get(key) {
None | Some(Value::Null) => default,
Some(Value::Number(n)) => n.as_i64().unwrap_or(default),
Some(Value::String(s)) => s.parse().unwrap_or(default),
_ => default,
}
}
fn opt_f64(args: &Value, key: &str, default: f64) -> f64 {
match args.get(key) {
None | Some(Value::Null) => default,
Some(Value::Number(n)) => n.as_f64().unwrap_or(default),
Some(Value::String(s)) => s.parse().unwrap_or(default),
_ => default,
}
}
fn opt_bool(args: &Value, key: &str, default: bool) -> bool {
match args.get(key) {
None | Some(Value::Null) => default,
Some(Value::Bool(b)) => *b,
Some(Value::String(s)) => matches!(s.as_str(), "true" | "True" | "1" | "yes"),
Some(Value::Number(n)) => n.as_i64().unwrap_or(0) != 0,
_ => default,
}
}
fn now_rfc3339() -> String {
chrono::Utc::now().to_rfc3339_opts(chrono::SecondsFormat::Secs, true)
}
fn yaml_escape(s: &str) -> String {
if s.is_empty()
|| s.contains(':')
|| s.contains('#')
|| s.contains('|')
|| s.contains('"')
|| s.contains('\n')
{
format!("\"{}\"", s.replace('\\', "\\\\").replace('"', "\\\""))
} else {
s.to_string()
}
}
fn resolve_path(rel: &str) -> PathBuf {
let p = PathBuf::from(rel);
if p.is_absolute() {
return p;
}
if p.exists() {
return p;
}
let base = (|| {
let q = crate::host_query_json("cwd")?;
q.as_str()
.map(PathBuf::from)
.ok_or_else(|| "cwd not text".to_string())
})()
.or_else(|_| std::env::current_dir().map_err(|e| e.to_string()))
.unwrap_or_else(|_| PathBuf::from("."));
base.join(p)
}
fn memory_root(args: &Value) -> PathBuf {
let rel = opt_text(args, "memory_dir").unwrap_or(DEFAULT_MEMORY_DIR);
resolve_path(rel)
}
fn policy_path(root: &Path) -> PathBuf {
root.join("policies").join(POLICY_NAME)
}
#[derive(Clone, Debug)]
struct PolicyRule {
task_hash: String,
slug: String,
skill: String,
task: String,
count: i64,
confidence: f64,
}
fn parse_policy(src: &str) -> Vec<PolicyRule> {
let mut rules = Vec::new();
let mut in_table = false;
let mut header_ok = false;
for line in src.lines() {
let t = line.trim();
if t.starts_with("|") && t.contains("task_hash") {
in_table = true;
header_ok = true;
continue;
}
if in_table && t.starts_with("|") && t.contains("---") {
continue;
}
if in_table && t.starts_with("|") {
let cols: Vec<&str> = t
.trim_matches('|')
.split('|')
.map(|c| c.trim().trim_matches('"'))
.collect();
if cols.len() >= 5 {
let count = cols[4].parse().unwrap_or(1);
let confidence = if cols.len() >= 6 {
cols[5].parse().unwrap_or(0.9)
} else {
0.9
};
let task = if cols.len() >= 7 {
cols[6].to_string()
} else {
String::new()
};
rules.push(PolicyRule {
task_hash: cols[0].to_string(),
slug: cols[1].to_string(),
skill: cols[2].to_string(),
count,
confidence,
task,
});
}
continue;
}
if in_table && header_ok && !t.starts_with('|') && !t.is_empty() {
break;
}
}
rules
}
fn write_policy(root: &Path, rules: &[PolicyRule]) -> Result<PathBuf, String> {
fs::create_dir_all(root.join("policies")).map_err(|e| format!("mkdir policies: {e}"))?;
let path = policy_path(root);
let ts = now_rfc3339();
let mut body = format!(
"---\ntype: policy\nstatus: compiled\nbackend: marqdo\ngenerated_at: {ts}\nrules: {}\n---\n\n# Adaptive router (compiled Marqdo policy)\n\nDeterministic task → skill routing. No LLM required.\n\n# Rules\n\n| task_hash | slug | skill | resource | count | confidence | task |\n|-----------|------|-------|----------|------:|-----------:|------|\n",
rules.len()
);
for r in rules {
body.push_str(&format!(
"| {} | {} | {} | {} | {} | {:.2} | {} |\n",
r.task_hash,
yaml_escape(&r.slug),
yaml_escape(&r.skill),
yaml_escape(&r.skill), // resource often == skill path for OKF
r.count,
r.confidence,
yaml_escape(&r.task),
));
}
body.push_str("\n# Fallback\n\nllm\n");
fs::write(&path, body).map_err(|e| format!("write policy: {e}"))?;
Ok(path)
}
fn load_rules(root: &Path) -> Vec<PolicyRule> {
let path = policy_path(root);
let Ok(src) = fs::read_to_string(&path) else {
return Vec::new();
};
parse_policy(&src)
}
fn match_policy(rules: &[PolicyRule], task: &str, threshold: f64) -> Option<PolicyRule> {
let th = goal_sig_hex(&normalize_goal(task));
if let Some(r) = rules.iter().find(|r| r.task_hash == th) {
return Some(r.clone());
}
// Near-match on stored task text / slug.
let mut best: Option<(f64, PolicyRule)> = None;
for r in rules {
let score = memory::task_near_score(task, &r.task);
if score >= threshold {
if best.as_ref().map(|(s, _)| score > *s).unwrap_or(true) {
best = Some((score, r.clone()));
}
}
let slug_score = memory::task_near_score(task, &r.slug);
if slug_score >= threshold {
if best.as_ref().map(|(s, _)| slug_score > *s).unwrap_or(true) {
let mut rr = r.clone();
rr.confidence = slug_score;
best = Some((slug_score, rr));
}
}
}
best.map(|(s, mut r)| {
r.confidence = s;
r
})
}
fn build_route_prompt(task: &str, candidates: &[Value]) -> String {
let mut s = String::from(
"You are a Marqdo Agent router. Pick the best skill slug for the task, or say EXPLORE.\n\nReply with exactly one line:\nSKILL:<slug>\nor\nEXPLORE\n\nTask:\n",
);
s.push_str(task);
s.push_str("\n\nCandidates:\n");
for (i, c) in candidates.iter().enumerate() {
let slug = c
.get("slug")
.or_else(|| c.get("title"))
.and_then(|v| v.as_str())
.unwrap_or("?");
let title = c
.get("title")
.or_else(|| c.get("goal"))
.and_then(|v| v.as_str())
.unwrap_or("");
s.push_str(&format!("{}. {slug} — {title}\n", i + 1));
}
s
}
fn candidate_list(args: &Value) -> Result<Vec<Value>, String> {
if let Some(Value::Array(items)) = args.get("candidates") {
return Ok(items.clone());
}
let kb = opt_text(args, "kb_dir").unwrap_or(DEFAULT_KB_DIR);
let listed = crate::kb::kb_list_tasks(&json!({ "kb_dir": kb }))?;
let tasks = listed
.get("tasks")
.and_then(|v| v.as_array())
.cloned()
.unwrap_or_default();
if !tasks.is_empty() {
return Ok(tasks);
}
let goal = arg_text(args, "task").or_else(|_| arg_text(args, "goal"))?;
let near = crate::kb::kb_near_match(&json!({
"kb_dir": kb,
"goal": goal,
}))?;
Ok(near
.get("candidates")
.and_then(|v| v.as_array())
.cloned()
.unwrap_or_default())
}
fn enrich_with_kb(rule: &PolicyRule, kb: &str, task: &str) -> Result<Value, String> {
let hit = crate::kb::kb_lookup(&json!({
"kb_dir": kb,
"goal": task,
"slug": rule.slug,
"near_match": true,
"near_threshold": 0.5,
}))
.unwrap_or(Value::Null);
let resource = hit
.get("resource")
.cloned()
.unwrap_or_else(|| Value::String(rule.skill.clone()));
let skill = hit
.get("skill")
.cloned()
.unwrap_or_else(|| Value::String(rule.skill.clone()));
let llm_free = hit
.get("llm_free")
.and_then(|v| v.as_bool())
.unwrap_or(true);
Ok(json!({
"backend": "marqdo",
"mode": "policy",
"matched": true,
"needs_llm": false,
"slug": rule.slug,
"skill": skill,
"resource": resource,
"task_hash": rule.task_hash,
"confidence": rule.confidence,
"llm_free": llm_free,
"count": rule.count,
}))
}
fn route_marqdo(args: &Value) -> Result<Value, String> {
let root = memory_root(args);
let _ = memory::memory_ensure(&json!({
"memory_dir": opt_text(args, "memory_dir").unwrap_or(DEFAULT_MEMORY_DIR),
}));
let task = arg_text(args, "task").or_else(|_| arg_text(args, "goal"))?;
let threshold = opt_f64(args, "threshold", 0.78);
let kb = opt_text(args, "kb_dir").unwrap_or(DEFAULT_KB_DIR);
let rules = load_rules(&root);
if let Some(rule) = match_policy(&rules, task, threshold) {
if rule.confidence >= threshold {
return enrich_with_kb(&rule, kb, task);
}
}
Ok(json!({
"backend": "marqdo",
"mode": "miss",
"matched": false,
"needs_llm": false,
"confidence": 0.0,
}))
}
fn route_resolve_fallback(args: &Value) -> Result<Value, String> {
let resolved = memory::resolve_task(args)?;
let conf = resolved
.get("confidence")
.and_then(|v| v.as_f64())
.unwrap_or(0.0);
let llm_free = resolved
.get("llm_free")
.and_then(|v| v.as_bool())
.unwrap_or(false);
if conf >= opt_f64(args, "threshold", 0.78) || llm_free {
return Ok(json!({
"backend": "kb",
"mode": resolved.get("mode").cloned().unwrap_or(Value::String("near".into())),
"matched": true,
"needs_llm": false,
"slug": resolved.get("slug").cloned().unwrap_or(Value::Null),
"skill": resolved.get("skill").cloned().unwrap_or(Value::Null),
"resource": resolved.get("resource").cloned().unwrap_or(Value::Null),
"confidence": conf,
"llm_free": llm_free,
}));
}
Ok(json!({
"backend": "kb",
"mode": "miss",
"matched": false,
"needs_llm": false,
"confidence": conf,
"resolve": resolved,
}))
}
fn route_model_request(args: &Value, level: &str) -> Result<Value, String> {
let task = arg_text(args, "task").or_else(|_| arg_text(args, "goal"))?;
let cands = candidate_list(args)?;
let prompt = build_route_prompt(task, &cands);
Ok(json!({
"backend": level,
"mode": "needs_llm",
"matched": false,
"needs_llm": true,
"level": level,
"prompt": prompt,
"candidates": cands,
"confidence": 0.0,
}))
}
/// Cascade Adaptive Router (Phase 4).
///
/// `backend`: `auto` | `marqdo` | `small-llm` | `llm` (`jev` → alias of `small-llm`).
///
/// `auto` order: marqdo policy → kb resolve → small-llm request.
pub fn route(args: &Value) -> Result<Value, String> {
let backend = opt_text(args, "backend").unwrap_or("auto");
let threshold = opt_f64(args, "threshold", 0.78);
match backend {
"marqdo" => {
let hit = route_marqdo(args)?;
if hit.get("matched").and_then(|v| v.as_bool()) == Some(true) {
return Ok(hit);
}
route_resolve_fallback(args)
}
"small-llm" | "small_llm" | "small" | "jev" => route_model_request(args, "small-llm"),
"llm" | "large" | "large-llm" => route_model_request(args, "llm"),
"auto" | _ => {
let mut trace: Vec<Value> = Vec::new();
let m = route_marqdo(args)?;
trace.push(json!({"try": "marqdo", "matched": m.get("matched")}));
if m.get("matched").and_then(|v| v.as_bool()) == Some(true)
&& m.get("confidence").and_then(|v| v.as_f64()).unwrap_or(0.0) >= threshold
{
let mut out = m;
if let Some(obj) = out.as_object_mut() {
obj.insert("trace".into(), Value::Array(trace));
obj.insert("backend".into(), Value::String("auto/marqdo".into()));
}
return Ok(out);
}
let kb = route_resolve_fallback(args)?;
trace.push(json!({"try": "kb", "matched": kb.get("matched")}));
if kb.get("matched").and_then(|v| v.as_bool()) == Some(true) {
let mut out = kb;
if let Some(obj) = out.as_object_mut() {
obj.insert("trace".into(), Value::Array(trace));
obj.insert("backend".into(), Value::String("auto/kb".into()));
}
return Ok(out);
}
// Prefer small-llm request in auto when nothing matched (caller may use large).
let mut req = route_model_request(args, "small-llm")?;
if let Some(obj) = req.as_object_mut() {
obj.insert("trace".into(), Value::Array(trace));
obj.insert("backend".into(), Value::String("auto/small-llm".into()));
}
Ok(req)
}
}
}
/// Apply a router model reply (`SKILL:<slug>` / `EXPLORE`) to a concrete skill hit.
pub fn route_apply(args: &Value) -> Result<Value, String> {
let reply = arg_text(args, "reply")?;
let kb = opt_text(args, "kb_dir").unwrap_or(DEFAULT_KB_DIR);
let task = arg_text(args, "task").or_else(|_| arg_text(args, "goal"))?;
let line = reply
.lines()
.map(|l| l.trim())
.find(|l| !l.is_empty())
.unwrap_or("");
let upper = line.to_ascii_uppercase();
if upper.starts_with("EXPLORE") || upper == "LLM" || upper == "NEW" {
return Ok(json!({
"matched": false,
"mode": "explore",
"decision": "EXPLORE",
"needs_llm": false,
}));
}
let slug = if let Some(rest) = line.strip_prefix("SKILL:") {
rest.trim()
} else if let Some(rest) = line.strip_prefix("skill:") {
rest.trim()
} else if let Some(rest) = line.strip_prefix("调用:") {
rest.trim()
} else {
line.trim()
};
if slug.is_empty() {
return Ok(json!({
"matched": false,
"mode": "explore",
"decision": "EXPLORE",
"reason": "empty_slug",
}));
}
let hit = crate::kb::kb_lookup(&json!({
"kb_dir": kb,
"goal": task,
"slug": slug,
"near_match": true,
"near_threshold": 0.5,
}))?;
if hit.is_null() {
return Ok(json!({
"matched": false,
"mode": "miss",
"decision": "SKILL",
"slug": slug,
"reason": "slug_not_in_kb",
}));
}
Ok(json!({
"matched": true,
"mode": "routed",
"decision": "SKILL",
"backend": opt_text(args, "backend").unwrap_or("llm"),
"slug": slug,
"skill": hit.get("skill").cloned().unwrap_or(Value::Null),
"resource": hit.get("resource").cloned().unwrap_or(Value::Null),
"llm_free": hit.get("llm_free").cloned().unwrap_or(Value::Bool(false)),
"confidence": 0.85,
"needs_llm": false,
}))
}
/// Compile policy from successful episode skill selections (Policy Compilation).
pub fn compile_policy(args: &Value) -> Result<Value, String> {
let root = memory_root(args);
let mem_arg = opt_text(args, "memory_dir").unwrap_or(DEFAULT_MEMORY_DIR);
let _ = memory::memory_ensure(&json!({ "memory_dir": mem_arg }));
let min_evidence = opt_i64(args, "min_evidence", opt_i64(args, "improve_every", 3));
let listed = memory::list_episodes(&json!({
"memory_dir": mem_arg,
"status": "success",
"limit": 500,
}))?;
let eps = listed
.get("episodes")
.and_then(|v| v.as_array())
.cloned()
.unwrap_or_default();
// task_hash → (slug → count, sample task, skill path)
let mut by_hash: HashMap<String, HashMap<String, (i64, String, String)>> = HashMap::new();
for e in &eps {
let id = e.get("id").and_then(|v| v.as_str()).unwrap_or("");
if id.is_empty() {
continue;
}
let full = memory::get_episode(&json!({
"memory_dir": mem_arg,
"id": id,
}))?;
if full.is_null() {
continue;
}
let src = full.get("source").and_then(|v| v.as_str()).unwrap_or("");
let skill = extract_fm(src, "skill").unwrap_or_default();
if skill.is_empty() || skill == "none" || skill == "null" {
continue;
}
let task_hash = extract_fm(src, "task_hash")
.or_else(|| e.get("task_hash").and_then(|v| v.as_str()).map(|s| s.to_string()))
.unwrap_or_default();
if task_hash.is_empty() {
continue;
}
let task = full
.get("task")
.and_then(|v| v.as_str())
.unwrap_or("")
.to_string();
let slug = extract_fm(src, "slug")
.filter(|s| !s.is_empty())
.unwrap_or_else(|| goal_slug_str(&task));
// Prefer skill path as key when it looks like a path; else slug.
let key = if skill.contains('/') || skill.ends_with(".md") {
skill.clone()
} else {
slug.clone()
};
let entry = by_hash.entry(task_hash).or_default();
let cell = entry.entry(key).or_insert((0, task, skill));
cell.0 += 1;
}
let mut rules: Vec<PolicyRule> = Vec::new();
for (task_hash, skills) in by_hash {
let Some((skill_key, (count, task, skill_path))) =
skills.into_iter().max_by_key(|(_, (c, _, _))| *c)
else {
continue;
};
if count < min_evidence {
continue;
}
let slug = if skill_key.contains('/') {
Path::new(&skill_key)
.file_stem()
.and_then(|s| s.to_str())
.unwrap_or(&skill_key)
.trim_end_matches(".mq")
.to_string()
} else {
skill_key
};
let confidence = (count as f64 / (count as f64 + 1.0)).min(0.99);
rules.push(PolicyRule {
task_hash,
slug,
skill: skill_path,
task,
count,
confidence,
});
}
rules.sort_by(|a, b| b.count.cmp(&a.count));
if rules.is_empty() && !opt_bool(args, "force", false) {
return Ok(json!({
"ok": false,
"compiled": false,
"reason": "insufficient_stable_mappings",
"min_evidence": min_evidence,
}));
}
let path = write_policy(&root, &rules)?;
Ok(json!({
"ok": true,
"compiled": true,
"path": path.to_string_lossy(),
"rules": rules.len() as i64,
"min_evidence": min_evidence,
}))
}
fn extract_fm(source: &str, key: &str) -> Option<String> {
let source = source.strip_prefix('\u{feff}').unwrap_or(source);
let lines: Vec<&str> = source.lines().collect();
if lines.first().map(|l| l.trim()) != Some("---") {
return None;
}
let prefix = format!("{key}:");
for line in lines.iter().skip(1) {
let t = line.trim();
if t == "---" {
break;
}
if let Some(rest) = t.strip_prefix(&prefix) {
return Some(rest.trim().trim_matches('"').to_string());
}
}
None
}
/// Learn gate for policy: compile when enough skill-tagged episodes exist.
pub fn maybe_compile_policy(args: &Value) -> Result<Value, String> {
let compiled = compile_policy(args)?;
Ok(json!({
"policy_learned": compiled.get("ok").and_then(|v| v.as_bool()).unwrap_or(false),
"compile": compiled,
}))
}
#[cfg(test)]
mod tests {
use super::*;
use serde_json::json;
#[test]
fn compile_and_route_marqdo() {
let dir = std::env::temp_dir().join(format!("marqdo-route-{}", std::process::id()));
let _ = fs::remove_dir_all(&dir);
fs::create_dir_all(&dir).unwrap();
let mem = dir.join("agent-memory");
let kb = dir.join("agent-kb");
let mem_s = mem.to_string_lossy().into_owned();
let kb_s = kb.to_string_lossy().into_owned();
let task = "Reply with exactly the word pong and nothing else.";
// Seed a solidified skill via memory compile path.
for _ in 0..3 {
memory::record_episode(&json!({
"memory_dir": mem_s,
"task": task,
"status": "ok",
"mode": "explore",
"result": "pong",
"skill": "concepts/skills/reply-with-exactly-the-word-pong-and-nothing-els.md",
"llm_calls": 1,
}))
.unwrap();
}
let learned = memory::maybe_learn(&json!({
"memory_dir": mem_s,
"kb_dir": kb_s,
"task": task,
"improve_every": 3,
"promote": true,
}))
.unwrap();
assert_eq!(learned.get("learned").and_then(|v| v.as_bool()), Some(true));
// Tag episodes with skill path for policy mining (re-record with skill).
for _ in 0..3 {
memory::record_episode(&json!({
"memory_dir": mem_s,
"task": task,
"status": "ok",
"mode": "compiled",
"result": "pong",
"skill": "concepts/skills/reply-with-exactly-the-word-pong-and-nothing-els.md",
"llm_calls": 0,
}))
.unwrap();
}
let pol = compile_policy(&json!({
"memory_dir": mem_s,
"min_evidence": 3,
}))
.unwrap();
assert_eq!(pol.get("ok").and_then(|v| v.as_bool()), Some(true), "{pol}");
let routed = route(&json!({
"memory_dir": mem_s,
"kb_dir": kb_s,
"task": task,
"backend": "auto",
}))
.unwrap();
assert_eq!(
routed.get("matched").and_then(|v| v.as_bool()),
Some(true),
"{routed}"
);
assert_eq!(
routed.get("needs_llm").and_then(|v| v.as_bool()),
Some(false),
"{routed}"
);
let _ = fs::remove_dir_all(&dir);
}
}
+18
View File
@@ -0,0 +1,18 @@
[package]
name = "marqdo_plugin_llm"
version = "0.1.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo LLM transport plugin (ABI v2) — OpenAI-compatible chat completions"
publish = false
[lib]
name = "llm"
crate-type = ["cdylib"]
[dependencies]
serde_json = "1"
# Pin with host (edition2024-safe for rustc 1.81).
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"] }
idna_adapter = { version = "=1.1.0" }
zeroize = { version = "=1.8.1" }
+369
View File
@@ -0,0 +1,369 @@
//! Marqdo LLM transport plugin (C ABI v2): OpenAI-compatible chat completions.
use std::ffi::{CStr, CString};
use std::io::{BufRead, BufReader, Read};
use std::os::raw::{c_char, c_int, c_void};
use std::ptr;
use std::time::Duration;
use serde_json::{json, Map, Value};
const ABI_VERSION: u32 = 2;
const MAX_BODY: usize = 32 * 1024 * 1024;
type PluginFn = unsafe extern "C" fn(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int;
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,
pub register_fn: Option<
unsafe extern "C" fn(
userdata: *mut c_void,
name: *const c_char,
params: *const c_char,
fn_ptr: PluginFn,
) -> c_int,
>,
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
pub host_query: Option<HostQueryFn>,
}
static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
unsafe fn host_strdup(s: &str) -> *mut c_char {
let alloc = HOST_ALLOC.expect("host alloc");
let bytes = s.as_bytes();
let p = alloc(bytes.len() + 1) as *mut u8;
if p.is_null() {
return ptr::null_mut();
}
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
*p.add(bytes.len()) = 0;
p as *mut c_char
}
fn set_out(out: *mut *mut c_char, s: &str) {
if out.is_null() {
return;
}
unsafe {
*out = host_strdup(s);
}
}
fn set_err(err: *mut *mut c_char, s: &str) {
if err.is_null() {
return;
}
unsafe {
*err = host_strdup(s);
}
}
fn parse_args(args_json: *const c_char) -> Result<Value, String> {
if args_json.is_null() {
return Ok(json!({}));
}
let s = unsafe { CStr::from_ptr(args_json) }
.to_str()
.map_err(|_| "args not utf-8".to_string())?;
if s.trim().is_empty() {
return Ok(json!({}));
}
serde_json::from_str(s).map_err(|e| e.to_string())
}
fn reply(out_json: *mut *mut c_char, err_msg: *mut *mut c_char, r: Result<Value, String>) -> c_int {
match r {
Ok(v) => {
set_out(out_json, &v.to_string());
0
}
Err(e) => {
set_err(err_msg, &e);
1
}
}
}
fn opt_text<'a>(args: &'a Value, key: &str) -> Option<&'a str> {
args.get(key).and_then(|v| v.as_str()).filter(|s| !s.is_empty())
}
fn arg_text<'a>(args: &'a Value, key: &str) -> Result<&'a str, String> {
opt_text(args, key).ok_or_else(|| format!("missing text `{key}`"))
}
fn opt_bool(args: &Value, key: &str, default: bool) -> bool {
match args.get(key) {
None | Some(Value::Null) => default,
Some(Value::Bool(b)) => *b,
Some(Value::String(s)) => matches!(s.as_str(), "true" | "True" | "1" | "yes"),
Some(Value::Number(n)) => n.as_i64().unwrap_or(0) != 0,
_ => default,
}
}
fn read_limited(mut r: impl Read) -> Result<String, String> {
let mut buf = Vec::new();
let mut chunk = [0u8; 8192];
loop {
let n = r.read(&mut chunk).map_err(|e| e.to_string())?;
if n == 0 {
break;
}
if buf.len() + n > MAX_BODY {
return Err("response body too large".into());
}
buf.extend_from_slice(&chunk[..n]);
}
String::from_utf8(buf).map_err(|e| e.to_string())
}
fn usage_from(data: &Value) -> Value {
let u = data.get("usage").cloned().unwrap_or(Value::Null);
let pt = u.get("prompt_tokens").and_then(|v| v.as_i64()).unwrap_or(0);
let ct = u
.get("completion_tokens")
.and_then(|v| v.as_i64())
.unwrap_or(0);
let tt = u
.get("total_tokens")
.and_then(|v| v.as_i64())
.unwrap_or(pt + ct);
json!({
"prompt_tokens": pt,
"completion_tokens": ct,
"total_tokens": tt,
})
}
fn tool_calls_from(data: &Value) -> Value {
data.get("choices")
.and_then(|c| c.as_array())
.and_then(|a| a.first())
.and_then(|c0| c0.get("message"))
.and_then(|m| m.get("tool_calls"))
.cloned()
.unwrap_or_else(|| json!([]))
}
fn parse_sse_events(reader: impl BufRead, echo: bool) -> Result<Vec<Value>, String> {
let mut events = Vec::new();
let mut data_lines: Vec<String> = Vec::new();
for line in reader.lines() {
let line = line.map_err(|e| e.to_string())?;
if echo {
eprint!("{line}\n");
}
if line.is_empty() {
if !data_lines.is_empty() {
let data = data_lines.join("\n");
data_lines.clear();
if data.trim() == "[DONE]" {
events.push(json!({"type": "done", "data": "[DONE]"}));
break;
}
events.push(json!({"type": "data", "data": data}));
}
continue;
}
if let Some(rest) = line.strip_prefix("data:") {
data_lines.push(rest.trim_start().to_string());
}
}
if !data_lines.is_empty() {
let data = data_lines.join("\n");
if data.trim() == "[DONE]" {
events.push(json!({"type": "done", "data": "[DONE]"}));
} else {
events.push(json!({"type": "data", "data": data}));
}
}
Ok(events)
}
fn chat_completions(args: &Value) -> Result<Value, String> {
let base_url = arg_text(args, "base_url")?;
let api_key = arg_text(args, "api_key").unwrap_or("");
let model = arg_text(args, "model")?;
let prompt = arg_text(args, "prompt")?;
let stream = opt_bool(args, "stream", false);
let echo = opt_bool(args, "echo", false);
let suffix = opt_text(args, "suffix").unwrap_or("/chat/completions");
let bearer = opt_text(args, "bearer").unwrap_or("Bearer ");
let url = format!("{}{}", base_url.trim_end_matches('/'), suffix);
if !(url.starts_with("http://") || url.starts_with("https://")) {
return Err("url must start with http:// or https://".into());
}
let mut req_body = Map::new();
req_body.insert("model".into(), Value::String(model.to_string()));
req_body.insert(
"messages".into(),
json!([{"role": "user", "content": prompt}]),
);
if stream {
req_body.insert("stream".into(), Value::Bool(true));
}
let body = Value::Object(req_body).to_string();
let auth = format!("{bearer}{api_key}");
let agent = ureq::AgentBuilder::new()
.timeout_connect(Duration::from_secs(15))
.timeout_read(Duration::from_secs(120))
.build();
let mut req = agent
.post(&url)
.set("User-Agent", "marqdo-plugin-llm")
.set("Content-Type", "application/json; charset=utf-8");
if stream {
req = req.set("Accept", "text/event-stream");
}
if !api_key.is_empty() {
req = req.set("Authorization", &auth);
}
if stream {
match req.send_string(&body) {
Ok(r) => {
let status = r.status();
if status != 200 {
let text = read_limited(r.into_reader())?;
return Err(format!("HTTP {status}: {text}"));
}
let events = parse_sse_events(BufReader::new(r.into_reader()), echo)?;
Ok(json!({
"events": events,
"finish": "stop",
"transport": "plugin",
}))
}
Err(ureq::Error::Status(code, r)) => {
let text = read_limited(r.into_reader()).unwrap_or_default();
Err(format!("HTTP {code}: {text}"))
}
Err(e) => Err(format!("http POST sse {url}: {e}")),
}
} else {
match req.send_string(&body) {
Ok(r) => {
let status = r.status();
let text = read_limited(r.into_reader())?;
if status != 200 {
return Err(format!("HTTP {status}: {text}"));
}
let data: Value = serde_json::from_str(&text).map_err(|e| e.to_string())?;
let msg = data
.get("choices")
.and_then(|c| c.as_array())
.and_then(|a| a.first())
.and_then(|c0| c0.get("message"))
.cloned()
.unwrap_or(json!({}));
let content = msg
.get("content")
.and_then(|v| v.as_str())
.unwrap_or("")
.to_string();
let fr = data
.get("choices")
.and_then(|c| c.as_array())
.and_then(|a| a.first())
.and_then(|c0| c0.get("finish_reason"))
.and_then(|v| v.as_str())
.unwrap_or("stop")
.to_string();
Ok(json!({
"text": content,
"usage": usage_from(&data),
"finish": fr,
"tool_calls": tool_calls_from(&data),
"transport": "plugin",
}))
}
Err(ureq::Error::Status(code, r)) => {
let text = read_limited(r.into_reader()).unwrap_or_default();
Err(format!("HTTP {code}: {text}"))
}
Err(e) => Err(format!("http POST {url}: {e}")),
}
}
}
unsafe extern "C" fn llm_chat_completions(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int {
let r = (|| {
let args = parse_args(args_json)?;
chat_completions(&args)
})();
reply(out_json, err_msg, r)
}
unsafe extern "C" fn llm_ping(
_args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int {
reply(out_json, err_msg, Ok(json!({"ok": true, "plugin": "llm"})))
}
fn register(host: &MarqdoHostApi, name: &str, params: &str, fn_ptr: PluginFn) -> c_int {
let register = match host.register_fn {
Some(f) => f,
None => return 1,
};
let n = CString::new(name).unwrap();
let p = CString::new(params).unwrap();
unsafe { register(host.userdata, n.as_ptr(), p.as_ptr(), fn_ptr) }
}
#[no_mangle]
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
ABI_VERSION
}
#[no_mangle]
pub unsafe extern "C" fn marqdo_plugin_shutdown() {}
#[no_mangle]
pub unsafe extern "C" fn marqdo_plugin_init(host: *const MarqdoHostApi) -> c_int {
if host.is_null() {
return 1;
}
let host = &*host;
HOST_ALLOC = host.alloc;
HOST_FREE = host.free;
let regs = [
("llm_ping", "", llm_ping as PluginFn),
(
"llm_chat_completions",
"base_url,api_key,model,prompt,stream,echo,suffix,bearer",
llm_chat_completions as PluginFn,
),
];
for (name, params, f) in regs {
if register(host, name, params, f) != 0 {
return 1;
}
}
0
}
+38
View File
@@ -0,0 +1,38 @@
---
title: AI 原生闭环(契约 + MLSP)
description: 渐进式契约、结构化诊断与面向 AI 的 Marqdo 语言服务
---
# main
里程碑(v1.1.0):AI 原生闭环——让 AI 不仅能写 Marqdo,还能验证 Marqdo。
三件套。核心表面守卫(`doc/design/core-surface.md`)钉住 19 个核心构造,任一侧(清单 / 文档 / 金样)单边改动,CI 必红。渐进式契约是可选的 `参数` / `返回` / `字段` 表,直接嵌在叙述里,四边界校验:调用实参、返回值、表绑定、键访问。MLSP for AI(`marqdo mlsp`)是行分隔 JSON 的语言服务,AI 按需查询语法,而不是背诵整部语法。
静态契约检查:
```bash
marqdo check tests/contracts/ok_contract.mq.md
```
结构化诊断——错误即数据:
```bash
marqdo run tests/structure/hello.mq.md --json
```
按需查询语法(MLSP):
```bash
printf '%s\n' '{"id":1,"method":"syntax","params":{"query":"返回"}}' | marqdo mlsp
```
MLSP 方法:`locate`(查符号 / 构造卡片)、`syntax`(戒律原文 + 样例 + 文档锚点)、`validate`(结构化诊断)、`repair_targets`(有界靶点)、`repair_apply`(有界行编辑,越界必拒)、`schema`(单元契约)。
> print text=契约是可选的:不写契约表,文件保持全动态。
> print text=诊断自带 code / severity / suggestion / doc_anchor / doc_quote。
> print text=MLSP 语法卡片内嵌戒律原文与样例,AI 无需预学语法。
验证结果见:`doc/roadmap/perf-validation-report-2026-09-23.md`。
+38
View File
@@ -0,0 +1,38 @@
---
title: AI-native loop (contracts + MLSP)
description: Progressive contracts, structured diagnostics, and the Marqdo Language Server for AI
---
# main
Milestone (v1.1.0): the AI-native loop — so an AI can verify Marqdo, not just write it.
Three pieces. A core surface guard (`doc/design/core-surface.md`) pins the 19 core constructs, so a single-sided change (list / doc / golden sample) turns CI red. Progressive contracts are optional `参数` / `返回` / `字段` tables embedded in the narrative, checked at four boundaries: call argument, return, table bind, key access. MLSP for AI (`marqdo mlsp`) is a line-delimited JSON language service; the AI queries syntax on demand instead of memorizing the whole grammar.
Static contract check:
```bash
marqdo check tests/contracts/ok_contract.mq.md
```
Structured diagnostics — errors as data:
```bash
marqdo run tests/structure/hello.mq.md --json
```
Query syntax on demand (MLSP):
```bash
printf '%s\n' '{"id":1,"method":"syntax","params":{"query":"返回"}}' | marqdo mlsp
```
MLSP methods: `locate` (find a symbol / construct card), `syntax` (rule text + sample + doc anchor), `validate` (structured diagnostics), `repair_targets` (bounded span), `repair_apply` (bounded line edits, out-of-scope refused), `schema` (contract of one unit).
> print text=Contracts are optional: with no contract table, a file stays fully dynamic.
> print text=Diagnostics carry code, severity, suggestion, doc_anchor and doc_quote.
> print text=MLSP syntax cards embed the rule text and a sample, so AI need not pre-learn the grammar.
See validation results: `doc/roadmap/perf-validation-report-2026-09-23.md`.
+11 -2
View File
@@ -4,8 +4,10 @@ set -euo pipefail
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
cd "$ROOT"
MQ="${MARQDO_BIN:-$ROOT/target/release/marqdo}"
export MARQDO_EXT="${MARQDO_EXT:-$ROOT/.marqdo-ext}"
export MARQDO_AGENT_PLUGIN="${MARQDO_AGENT_PLUGIN:-$ROOT/.marqdo-ext/native/libagent.so}"
export MARQDO_EXT="${MARQDO_EXT:-$ROOT/ext}"
export MARQDO_AGENT_PLUGIN="${MARQDO_AGENT_PLUGIN:-$ROOT/target/release/libagent.so}"
# Offline golds that construct an llm handle need a dummy key (no network).
export OPENAI_API_KEY="${OPENAI_API_KEY:-sk-test}"
if [[ ! -x "$MQ" ]]; then
echo "missing $MQ — run: cargo build --release -p marqdo -p marqdo_plugin_agent" >&2
@@ -28,6 +30,13 @@ run tests/ext/agent-writeback-shadow.mq.md
run tests/ext/agent-kb-plan-hit.mq.md
run tests/ext/agent-context-budget-a3.mq.md
run tests/ext/agent-workbook-patch-a0.mq.md
run tests/ext/agent-v2-learn.mq.md
run tests/ext/agent-p4-route.mq.md
run tests/ext/agent-small-llm-route.mq.md
run tests/ext/agent-mcp-client.mq.md
run tests/ext/agent-resume.mq.md
run tests/ext/agent-zero-llm.mq.md
run tests/ext/agent-plan-preserve.mq.md
run examples/agent-okf-flywheel/index.mq.md
run examples/agent-pong/index.mq.md
+1
View File
@@ -85,6 +85,7 @@ pub fn canonical_param(builtin: &str, param: &str) -> String {
"path".into()
}
("host_dotenv_load" | "load_dotenv", "path" | "路径") => "path".into(),
("host_meta_get" | "meta_get", "key" | "键") => "key".into(),
("host_exec" | "exec", "cmd" | "命令") => "cmd".into(),
("host_exec" | "exec", "args" | "参数") => "args".into(),
("host_exec" | "exec", "capture" | "捕获") => "capture".into(),
+6
View File
@@ -27,6 +27,10 @@ pub struct Module {
pub functions: Vec<Function>,
/// Populated by the loader: bind name → imported module (not flattened).
pub import_modules: HashMap<String, Module>,
/// Unresolved Artifact Metadata (from frontmatter); filled by parse.
pub metadata_raw: Vec<(String, crate::binding::MetaValue)>,
/// Bound metadata after load-time Binding resolve (insertion order).
pub metadata: Vec<(String, crate::value::Value)>,
}
impl Default for Module {
@@ -36,6 +40,8 @@ impl Default for Module {
uses: Vec::new(),
functions: Vec::new(),
import_modules: HashMap::new(),
metadata_raw: Vec::new(),
metadata: Vec::new(),
}
}
}
+531
View File
@@ -0,0 +1,531 @@
//! Artifact Metadata Binding (`${ns.name}`) — Phase 1: frontmatter only.
//!
//! Spec: `doc/design/binding.md` · ADR 0006.
use std::collections::HashMap;
use std::path::{Path, PathBuf};
use anyhow::{bail, Result};
use crate::diagnostics::{bail_at, Span};
use crate::value::Value;
/// Unresolved frontmatter value (literal, sole binding, or interpolated text).
#[derive(Debug, Clone)]
pub enum MetaValue {
/// Already typed literal (no `${}`).
Literal(Value),
/// Whole value is one `${…}` expression.
Binding(BindingExpr),
/// Quoted/bare string containing `${…}` interpolations → Text after resolve.
Interpolated(String),
}
/// Parsed binding expression (inside `${…}`).
#[derive(Debug, Clone)]
pub struct BindingExpr {
pub cast: Option<CastKind>,
pub primary: BindingRef,
pub default: Option<DefaultVal>,
pub required: bool,
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum CastKind {
Int,
Float,
Bool,
}
#[derive(Debug, Clone)]
pub struct BindingRef {
pub ns: String,
pub name: String,
}
#[derive(Debug, Clone)]
pub enum DefaultVal {
Text(String),
/// Nested `${…}` not supported in Phase 1 defaults; only quoted/bare literals.
Binding(Box<BindingExpr>),
}
/// Sources available while resolving metadata at load time.
#[derive(Debug, Clone, Default)]
pub struct BindingContext {
/// `--bind KEY=VALUE` → `arg.KEY` and post-resolve overlay.
pub args: HashMap<String, String>,
pub cwd: PathBuf,
}
impl BindingContext {
pub fn from_binds(binds: &[(String, String)], cwd: PathBuf) -> Self {
let mut args = HashMap::new();
for (k, v) in binds {
args.insert(k.clone(), v.clone());
}
Self { args, cwd }
}
}
/// Parse a frontmatter RHS into a [`MetaValue`].
pub fn parse_meta_value(raw: &str) -> Result<MetaValue> {
let t = raw.trim();
if t.is_empty() {
return Ok(MetaValue::Literal(Value::Text(String::new())));
}
// Sole binding: entire value is `${…}`
if let Some(inner) = sole_binding(t) {
let expr = parse_binding_expr(inner)?;
return Ok(MetaValue::Binding(expr));
}
// Quoted string (may interpolate)
if (t.starts_with('"') && t.ends_with('"') && t.len() >= 2)
|| (t.starts_with('\'') && t.ends_with('\'') && t.len() >= 2)
{
let inner = &t[1..t.len() - 1];
if inner.contains("${") {
return Ok(MetaValue::Interpolated(unquote_escapes(inner)));
}
return Ok(MetaValue::Literal(Value::Text(unquote_escapes(inner))));
}
// Bare with interpolation
if t.contains("${") {
return Ok(MetaValue::Interpolated(t.to_string()));
}
Ok(MetaValue::Literal(parse_scalar_literal(t)))
}
fn sole_binding(t: &str) -> Option<&str> {
let t = t.trim();
if !t.starts_with("${") || !t.ends_with('}') {
return None;
}
// Ensure matching: first `${` closes at last `}` and nothing outside
let inner = &t[2..t.len() - 1];
// Reject if another `${` appears that would mean concatenation (not sole)
// Allow nested parens inside cast: ${int(env.X ?? "1")}
Some(inner)
}
fn unquote_escapes(s: &str) -> String {
let mut out = String::with_capacity(s.len());
let mut chars = s.chars().peekable();
while let Some(c) = chars.next() {
if c == '\\' {
match chars.next() {
Some('n') => out.push('\n'),
Some('t') => out.push('\t'),
Some('\\') => out.push('\\'),
Some('"') => out.push('"'),
Some('\'') => out.push('\''),
Some(o) => {
out.push('\\');
out.push(o);
}
None => out.push('\\'),
}
} else {
out.push(c);
}
}
out
}
fn parse_scalar_literal(t: &str) -> Value {
match t {
"true" | "True" | "TRUE" => Value::Bool(true),
"false" | "False" | "FALSE" => Value::Bool(false),
"null" | "Null" | "None" | "~" => Value::None,
_ => {
if let Ok(n) = t.parse::<i64>() {
return Value::Int(n);
}
if let Ok(n) = t.parse::<f64>() {
if !n.is_nan() && !n.is_infinite() {
return Value::Num(n);
}
}
Value::Text(t.to_string())
}
}
}
/// Parse inside `${…}` (without braces).
pub fn parse_binding_expr(inner: &str) -> Result<BindingExpr> {
let s = inner.trim();
// cast: int(…) / float(…) / bool(…)
if let Some((cast, rest)) = parse_cast_wrap(s)? {
let mut expr = parse_binding_expr(rest)?;
if expr.cast.is_some() {
bail!("nested casts are not allowed in binding expressions");
}
expr.cast = Some(cast);
return Ok(expr);
}
let (body, required) = if let Some(b) = s.strip_suffix('!') {
(b.trim(), true)
} else {
(s, false)
};
let (primary_s, default) = if let Some((left, right)) = split_default(body) {
(left.trim(), Some(parse_default_val(right.trim())?))
} else {
(body, None)
};
if required && default.is_some() {
bail!("binding cannot combine `!` with `??` default");
}
let primary = parse_binding_ref(primary_s)?;
Ok(BindingExpr {
cast: None,
primary,
default,
required,
})
}
fn parse_cast_wrap(s: &str) -> Result<Option<(CastKind, &str)>> {
for (name, kind) in [
("int", CastKind::Int),
("float", CastKind::Float),
("bool", CastKind::Bool),
] {
let prefix = format!("{name}(");
if let Some(rest) = s.strip_prefix(&prefix) {
if let Some(inner) = strip_trailing_paren(rest) {
return Ok(Some((kind, inner)));
}
bail!("unclosed `{name}(` in binding expression");
}
}
Ok(None)
}
fn strip_trailing_paren(s: &str) -> Option<&str> {
let s = s.trim_end();
if !s.ends_with(')') {
return None;
}
Some(s[..s.len() - 1].trim())
}
fn split_default(s: &str) -> Option<(&str, &str)> {
// Split on top-level `??`
let bytes = s.as_bytes();
let mut i = 0;
let mut depth = 0i32;
while i + 1 < bytes.len() {
match bytes[i] {
b'(' => depth += 1,
b')' => depth -= 1,
b'?' if depth == 0 && bytes[i + 1] == b'?' => {
return Some((&s[..i], &s[i + 2..]));
}
_ => {}
}
i += 1;
}
None
}
fn parse_default_val(s: &str) -> Result<DefaultVal> {
let s = s.trim();
if let Some(inner) = sole_binding(s) {
return Ok(DefaultVal::Binding(Box::new(parse_binding_expr(inner)?)));
}
if (s.starts_with('"') && s.ends_with('"') && s.len() >= 2)
|| (s.starts_with('\'') && s.ends_with('\'') && s.len() >= 2)
{
return Ok(DefaultVal::Text(unquote_escapes(&s[1..s.len() - 1])));
}
// bare default token
Ok(DefaultVal::Text(s.to_string()))
}
fn parse_binding_ref(s: &str) -> Result<BindingRef> {
let s = s.trim();
let Some((ns, name)) = s.split_once('.') else {
bail!("binding path must be `namespace.name` (got `{s}`)");
};
let ns = ns.trim();
let name = name.trim();
if ns.is_empty() || name.is_empty() {
bail!("binding path must be `namespace.name` (got `{s}`)");
}
match ns {
"env" | "arg" | "sys" | "secret" => {}
"config" | "file" => {
bail!("binding namespace `{ns}` is not available in Phase 1 (Metadata-only)")
}
other => bail!("unknown binding namespace `{other}`"),
}
if name.contains('.') {
// Phase 1: single segment name only
bail!("binding name must be a single segment (got `{s}`)");
}
Ok(BindingRef {
ns: ns.to_string(),
name: name.to_string(),
})
}
/// Resolve raw metadata entries; then overlay `--bind` keys.
pub fn resolve_metadata(
raw: &[(String, MetaValue)],
ctx: &BindingContext,
span: Span,
) -> Result<Vec<(String, Value)>> {
let mut out: Vec<(String, Value)> = Vec::with_capacity(raw.len());
for (k, mv) in raw {
let v = resolve_meta_value(mv, ctx, span)
.map_err(|e| bail_at(None, span, e.to_string()))?;
out.push((k.clone(), v));
}
// CLI overlay
for (k, v) in &ctx.args {
if let Some(slot) = out.iter_mut().find(|(mk, _)| mk == k) {
slot.1 = Value::Text(v.clone());
} else {
out.push((k.clone(), Value::Text(v.clone())));
}
}
Ok(out)
}
fn resolve_meta_value(mv: &MetaValue, ctx: &BindingContext, span: Span) -> Result<Value> {
match mv {
MetaValue::Literal(v) => Ok(v.clone()),
MetaValue::Binding(expr) => resolve_expr(expr, ctx, span),
MetaValue::Interpolated(s) => {
let text = interpolate(s, ctx, span)?;
Ok(Value::Text(text))
}
}
}
fn interpolate(s: &str, ctx: &BindingContext, span: Span) -> Result<String> {
let mut out = String::new();
let mut rest = s;
while let Some(start) = rest.find("${") {
out.push_str(&rest[..start]);
let after = &rest[start + 2..];
let end = find_binding_close(after).ok_or_else(|| {
anyhow::anyhow!("{}:{}: unclosed `${{` in metadata interpolation", span.line, span.col)
})?;
let inner = &after[..end];
let expr = parse_binding_expr(inner)?;
let v = resolve_expr(&expr, ctx, span)?;
out.push_str(&v.as_display());
rest = &after[end + 1..];
}
out.push_str(rest);
Ok(out)
}
fn find_binding_close(s: &str) -> Option<usize> {
let mut depth = 0i32;
for (i, c) in s.char_indices() {
match c {
'(' => depth += 1,
')' => depth -= 1,
'}' if depth == 0 => return Some(i),
_ => {}
}
}
None
}
fn resolve_expr(expr: &BindingExpr, ctx: &BindingContext, span: Span) -> Result<Value> {
let got = lookup(&expr.primary, ctx)?;
let value = match got {
Some(v) => v,
None if expr.required => {
bail!(
"required binding `{}.{}` is missing",
expr.primary.ns,
expr.primary.name
)
}
None => match &expr.default {
Some(DefaultVal::Text(t)) => Value::Text(t.clone()),
Some(DefaultVal::Binding(inner)) => resolve_expr(inner, ctx, span)?,
None => Value::None,
},
};
apply_cast(expr.cast, value)
}
fn lookup(r: &BindingRef, ctx: &BindingContext) -> Result<Option<Value>> {
match r.ns.as_str() {
"env" => Ok(std::env::var(&r.name).ok().map(Value::Text)),
"arg" => Ok(ctx.args.get(&r.name).cloned().map(Value::Text)),
"secret" => Ok(std::env::var(&r.name).ok().map(Value::Secret)),
"sys" => Ok(lookup_sys(&r.name, ctx)),
other => bail!("unknown binding namespace `{other}`"),
}
}
fn lookup_sys(name: &str, ctx: &BindingContext) -> Option<Value> {
match name {
"cwd" => Some(Value::Text(ctx.cwd.display().to_string())),
"platform" => Some(Value::Text(std::env::consts::OS.to_string())),
_ => None,
}
}
fn apply_cast(cast: Option<CastKind>, v: Value) -> Result<Value> {
let Some(c) = cast else {
return Ok(v);
};
let text = match &v {
Value::None => {
bail!("cannot cast None to {:?}", c);
}
Value::Text(s) => s.clone(),
Value::Secret(s) => s.clone(),
Value::Int(n) => n.to_string(),
Value::Num(n) => n.to_string(),
Value::Bool(b) => {
if *b {
"true".into()
} else {
"false".into()
}
}
other => bail!("cannot cast {} to {:?}", other.as_display(), c),
};
match c {
CastKind::Int => {
let n: i64 = text
.trim()
.parse()
.map_err(|_| anyhow::anyhow!("cannot cast `{text}` to int"))?;
Ok(Value::Int(n))
}
CastKind::Float => {
let n: f64 = text
.trim()
.parse()
.map_err(|_| anyhow::anyhow!("cannot cast `{text}` to float"))?;
Ok(Value::Num(n))
}
CastKind::Bool => {
let t = text.trim().to_ascii_lowercase();
match t.as_str() {
"1" | "true" | "yes" | "on" => Ok(Value::Bool(true)),
"0" | "false" | "no" | "off" => Ok(Value::Bool(false)),
_ => bail!("cannot cast `{text}` to bool"),
}
}
}
}
/// Split `KEY=VALUE` from CLI `--bind`.
pub fn parse_bind_kv(s: &str) -> Result<(String, String)> {
let Some((k, v)) = s.split_once('=') else {
bail!("--bind expects KEY=VALUE (got `{s}`)");
};
let k = k.trim();
if k.is_empty() {
bail!("--bind key must be non-empty");
}
Ok((k.to_string(), v.to_string()))
}
pub fn cwd_for_path(path: Option<&Path>) -> PathBuf {
path.and_then(|p| p.parent())
.map(|p| {
if p.as_os_str().is_empty() {
PathBuf::from(".")
} else {
p.to_path_buf()
}
})
.unwrap_or_else(|| std::env::current_dir().unwrap_or_else(|_| PathBuf::from(".")))
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn sole_env_default() {
let mv = parse_meta_value(r#"${env.NO_SUCH_MARQDO_VAR_XYZ ?? "gpt"}"#).unwrap();
let ctx = BindingContext::default();
let v = resolve_meta_value(&mv, &ctx, Span::new(1, 1)).unwrap();
assert_eq!(v, Value::Text("gpt".into()));
}
#[test]
fn required_missing_errors() {
let mv = parse_meta_value("${env.NO_SUCH_MARQDO_REQ_XYZ!}").unwrap();
let ctx = BindingContext::default();
let err = resolve_meta_value(&mv, &ctx, Span::new(1, 1)).unwrap_err();
assert!(err.to_string().contains("required binding"));
}
#[test]
fn secret_masks_display() {
std::env::set_var("MARQDO_TEST_SECRET_BIND", "s3cr3t");
let mv = parse_meta_value("${secret.MARQDO_TEST_SECRET_BIND}").unwrap();
let ctx = BindingContext::default();
let v = resolve_meta_value(&mv, &ctx, Span::new(1, 1)).unwrap();
assert_eq!(v.as_display(), "<secret>");
match v {
Value::Secret(s) => assert_eq!(s, "s3cr3t"),
other => panic!("expected Secret, got {other:?}"),
}
std::env::remove_var("MARQDO_TEST_SECRET_BIND");
}
#[test]
fn literal_not_overridden_by_env() {
std::env::set_var("OPENAI_MODEL", "from-env");
let raw = vec![(
"model".into(),
MetaValue::Literal(Value::Text("gpt-literal".into())),
)];
let ctx = BindingContext::default();
let meta = resolve_metadata(&raw, &ctx, Span::new(1, 1)).unwrap();
assert_eq!(meta[0].1, Value::Text("gpt-literal".into()));
std::env::remove_var("OPENAI_MODEL");
}
#[test]
fn bind_overlay_wins() {
let raw = vec![(
"model".into(),
MetaValue::Literal(Value::Text("gpt-literal".into())),
)];
let ctx = BindingContext::from_binds(&[("model".into(), "from-cli".into())], PathBuf::from("."));
let meta = resolve_metadata(&raw, &ctx, Span::new(1, 1)).unwrap();
assert_eq!(meta[0].1, Value::Text("from-cli".into()));
}
#[test]
fn int_cast() {
std::env::set_var("MARQDO_TEST_MAX_TOKENS", "2048");
let mv = parse_meta_value("${int(env.MARQDO_TEST_MAX_TOKENS)}").unwrap();
let v = resolve_meta_value(&mv, &BindingContext::default(), Span::new(1, 1)).unwrap();
assert_eq!(v, Value::Int(2048));
std::env::remove_var("MARQDO_TEST_MAX_TOKENS");
}
#[test]
fn interpolate_string() {
std::env::set_var("MARQDO_TEST_USER", "Ada");
let mv = parse_meta_value(r#""Hello ${env.MARQDO_TEST_USER}""#).unwrap();
let v = resolve_meta_value(&mv, &BindingContext::default(), Span::new(1, 1)).unwrap();
assert_eq!(v, Value::Text("Hello Ada".into()));
std::env::remove_var("MARQDO_TEST_USER");
}
}
+1
View File
@@ -41,6 +41,7 @@ pub fn builtin_type(v: &Value) -> Value {
Value::Int(_) => "int",
Value::Num(_) => "num",
Value::Text(_) => "text",
Value::Secret(_) => "secret",
Value::List(_) => "list",
Value::Map(_) => "map",
Value::Formula(_) => "formula",
+31 -2
View File
@@ -79,7 +79,12 @@ pub fn compile_module(path: Option<&Path>, module: &Module) -> Result<Program> {
let path_buf = path.map(|p| p.to_path_buf());
let mut functions = Vec::new();
for i in 0..flat.len() {
functions.push(compile_function(i, &flat, path_buf.as_deref())?);
let meta = if i == entry {
Some(module.metadata.as_slice())
} else {
None
};
functions.push(compile_function(i, &flat, path_buf.as_deref(), meta)?);
}
let parents: Vec<Option<usize>> = flat.iter().map(|f| f.parent).collect();
@@ -175,7 +180,12 @@ struct FnCompiler<'a> {
stmt_span: Span,
}
fn compile_function(fn_id: usize, flat: &[FlatFun], path: Option<&Path>) -> Result<FnChunk> {
fn compile_function(
fn_id: usize,
flat: &[FlatFun],
path: Option<&Path>,
metadata: Option<&[(String, Value)]>,
) -> Result<FnChunk> {
let fun = &flat[fn_id];
let mut locals = HashMap::new();
for (i, p) in fun.params.iter().enumerate() {
@@ -193,6 +203,15 @@ fn compile_function(fn_id: usize, flat: &[FlatFun], path: Option<&Path>) -> Resu
}
}
}
// Phase 2: reserve locals for entry metadata keys before body compile.
if let Some(meta) = metadata {
for (k, _) in meta {
if !locals.contains_key(k) {
let s = locals.len() as u8;
locals.insert(k.clone(), s);
}
}
}
let mut c = FnCompiler {
path,
flat,
@@ -208,6 +227,16 @@ fn compile_function(fn_id: usize, flat: &[FlatFun], path: Option<&Path>) -> Resu
locals,
stmt_span: fun.span,
};
// Prologue: seed entry locals from bound metadata.
if let Some(meta) = metadata {
for (k, v) in meta {
let slot = *c.locals.get(k).expect("metadata local reserved");
let ci = c.add_const(v.clone());
c.emit(Op::Constant(ci));
c.emit(Op::SetLocal(slot));
c.emit(Op::Pop);
}
}
for stmt in &fun.body {
c.compile_stmt(stmt)?;
}
+3
View File
@@ -698,6 +698,9 @@ fn add(a: Value, b: Value) -> Result<Value, String> {
(Value::Int(x), Value::Num(y)) => Ok(Value::Num(x as f64 + y)),
(Value::Num(x), Value::Int(y)) => Ok(Value::Num(x + y as f64)),
(Value::Text(x), Value::Text(y)) => Ok(Value::Text(format!("{x}{y}"))),
(Value::Text(x), Value::Secret(y)) => Ok(Value::Text(format!("{x}{y}"))),
(Value::Secret(x), Value::Text(y)) => Ok(Value::Text(format!("{x}{y}"))),
(Value::Secret(x), Value::Secret(y)) => Ok(Value::Text(format!("{x}{y}"))),
(Value::Text(x), y) => Ok(Value::Text(format!("{x}{}", y.as_display()))),
(x, Value::Text(y)) => Ok(Value::Text(format!("{}{y}", x.as_display()))),
(Value::Int(x), y) => Ok(Value::Text(format!("{}{}", x, y.as_display()))),
+1
View File
@@ -108,6 +108,7 @@ pub fn type_of(v: &Value) -> &'static str {
Value::Int(_) => "int",
Value::Num(_) => "num",
Value::Text(_) => "text",
Value::Secret(_) => "secret",
Value::List(_) => "list",
Value::Map(_) => "map",
Value::Formula(_) => "formula",
+12 -4
View File
@@ -21,8 +21,13 @@ pub const CATALOG: &[ExtPackage] = &[
ExtPackage {
id: "llm",
description: "OpenAI-compatible chat object (ext/ai/llm)",
mq_files: &["ai/llm.mq.md", "ai/大模型.mq.md"],
native_crate: None,
mq_files: &[
"ai/llm.mq.md",
"ai/大模型.mq.md",
"ai/llm/openai.mq.md",
"ai/llm/ollama.mq.md",
],
native_crate: Some("marqdo_plugin_llm"),
},
ExtPackage {
id: "agent",
@@ -98,6 +103,7 @@ pub fn native_short_name(crate_or_id: &str) -> &str {
match crate_or_id {
"marqdo_plugin_agent" | "agent" => "agent",
"marqdo_plugin_web" | "web" => "web",
"marqdo_plugin_llm" | "llm" => "llm",
"marqdo_plugin_quantum" | "quantum" => "quantum",
"marqdo_plugin_linalg" | "linalg" => "linalg",
other => other,
@@ -118,6 +124,7 @@ pub fn native_lib_filename(short: &str) -> String {
pub fn native_env_var(short: &str) -> &'static str {
match native_short_name(short) {
"web" => "MARQDO_WEB_PLUGIN",
"llm" => "MARQDO_LLM_PLUGIN",
"quantum" => "MARQDO_QUANTUM_PLUGIN",
"linalg" => "MARQDO_LINALG_PLUGIN",
_ => "MARQDO_AGENT_PLUGIN",
@@ -507,7 +514,7 @@ pub fn remove_ext(id: &str) -> Result<()> {
/// point at a freshly built plugin path.
pub fn installed_native_path(name: &str) -> Option<PathBuf> {
let short = native_short_name(name);
if !matches!(short, "agent" | "web" | "quantum" | "linalg") {
if !matches!(short, "agent" | "web" | "llm" | "quantum" | "linalg") {
return None;
}
let lib_name = native_lib_filename(short);
@@ -549,6 +556,7 @@ pub fn path_is_trusted_plugin(path: &Path) -> bool {
for key in [
"MARQDO_AGENT_PLUGIN",
"MARQDO_WEB_PLUGIN",
"MARQDO_LLM_PLUGIN",
"MARQDO_QUANTUM_PLUGIN",
"MARQDO_LINALG_PLUGIN",
] {
@@ -560,7 +568,7 @@ pub fn path_is_trusted_plugin(path: &Path) -> bool {
}
}
}
for short in ["agent", "web", "quantum", "linalg"] {
for short in ["agent", "web", "llm", "quantum", "linalg"] {
if let Ok(found) = find_native_plugin(short) {
let found = found.canonicalize().unwrap_or(found);
if found == path {
+19 -1
View File
@@ -198,6 +198,9 @@ pub enum HostFn {
StatsMean = 189,
StatsMedian = 190,
StatsStdev = 191,
Meta = 192,
MetaGet = 193,
ModuleSource = 194,
}
@@ -386,6 +389,9 @@ impl HostFn {
189 => Self::StatsMean,
190 => Self::StatsMedian,
191 => Self::StatsStdev,
192 => Self::Meta,
193 => Self::MetaGet,
194 => Self::ModuleSource,
_ => return None,
})
}
@@ -577,6 +583,9 @@ impl HostFn {
"host_stats_mean" | "stats_mean" => Self::StatsMean,
"host_stats_median" | "stats_median" => Self::StatsMedian,
"host_stats_stdev" | "stats_stdev" => Self::StatsStdev,
"host_meta" | "meta" => Self::Meta,
"host_meta_get" | "meta_get" => Self::MetaGet,
"host_module_source" | "module_source" => Self::ModuleSource,
_ => return None,
})
}
@@ -755,6 +764,9 @@ impl HostFn {
Self::StatsMean => "host_stats_mean",
Self::StatsMedian => "host_stats_median",
Self::StatsStdev => "host_stats_stdev",
Self::Meta => "host_meta",
Self::MetaGet => "host_meta_get",
Self::ModuleSource => "host_module_source",
Self::WritebackRecord => "host_writeback_record",
Self::WritebackGet => "host_writeback_get",
Self::WritebackClear => "host_writeback_clear",
@@ -778,11 +790,14 @@ impl HostFn {
&["path"]
}
Self::WriteText | Self::AppendText => &["path", "text"],
Self::NowUnix | Self::NowMs | Self::Args | Self::Cwd => &[],
Self::NowUnix | Self::NowMs | Self::Args | Self::Cwd | Self::Meta | Self::ModuleSource => {
&[]
}
Self::FormatTime => &["unix", "pattern"],
Self::ParseTime => &["text", "pattern"],
Self::SleepMs => &["ms"],
Self::EnvGet => &["name"],
Self::MetaGet => &["key"],
Self::EnvSet => &["name", "value"],
Self::Exit => &["code"],
Self::Exec => &["cmd"],
@@ -980,6 +995,9 @@ pub fn call_host(
HostFn::DotenvLoad => sys::dotenv_load(ctx, bound.get("path")),
HostFn::Args => sys::args(ctx),
HostFn::Cwd => sys::cwd(ctx),
HostFn::Meta => sys::meta(ctx),
HostFn::MetaGet => sys::meta_get(ctx, require(bound, "key")?),
HostFn::ModuleSource => crate::host::agent_rt::module_source(ctx),
HostFn::Exit => sys::exit(ctx, require(bound, "code")?),
HostFn::Exec => sys::exec(
ctx,
+1
View File
@@ -146,6 +146,7 @@ pub(crate) fn value_to_json(v: &Value) -> Result<serde_json::Value, String> {
}
},
Value::Code(c) => serde_json::Value::String(c.source.clone()),
Value::Secret(_) => serde_json::Value::String("<secret>".into()),
})
}
+3
View File
@@ -103,6 +103,8 @@ pub struct HostContext {
pub current_line: u32,
/// Entry-file line of each active user call (for writeback anchoring).
pub call_site_lines: Vec<u32>,
/// Bound Artifact Metadata from the entry `.mq.md` (Phase 1 Binding).
pub entry_metadata: Vec<(String, crate::value::Value)>,
/// Concurrent subtasks (`lib/subtask`): file / function / foreign.
#[cfg_attr(not(feature = "exec-host"), allow(dead_code))]
pub(crate) subtasks: HashMap<u64, subtask::Handle>,
@@ -129,6 +131,7 @@ impl Default for HostContext {
call_stack: Vec::new(),
current_line: 1,
call_site_lines: Vec::new(),
entry_metadata: Vec::new(),
subtasks: HashMap::new(),
subtask_seq: 0,
log_min_level: 20, // Info
+1
View File
@@ -408,6 +408,7 @@ fn spawn_fn(
host.argv = argv;
host.foreign_cmds = foreign_cmds;
host.set_entry_source(Some(&module_path), &source);
host.entry_metadata = module.metadata.clone();
let mut interp = Interpreter::with_capture(Some(&module_path), false).with_host(host);
interp
.invoke_function(&module, &name, &call_args)
+16
View File
@@ -93,6 +93,22 @@ pub fn cwd(ctx: &HostContext) -> Result<Value, String> {
Ok(Value::Text(ctx.cwd.display().to_string()))
}
/// Bound entry Artifact Metadata (map).
pub fn meta(ctx: &HostContext) -> Result<Value, String> {
Ok(Value::Map(ctx.entry_metadata.clone()))
}
/// Lookup one metadata key; missing → None.
pub fn meta_get(ctx: &HostContext, key: &Value) -> Result<Value, String> {
let k = as_text(key, "key")?;
Ok(ctx
.entry_metadata
.iter()
.find(|(name, _)| name == k)
.map(|(_, v)| v.clone())
.unwrap_or(Value::None))
}
pub fn exit(ctx: &HostContext, code: &Value) -> Result<Value, String> {
let c = as_i64(code, "code")?;
if ctx.soft_side_effects {
+22 -3
View File
@@ -46,6 +46,16 @@ impl Env {
}
}
/// Phase 2: lift resolved Artifact Metadata into the entry environment.
/// Existing keys are left unchanged (`or_insert` semantics).
fn with_metadata(module: &Module) -> Self {
let mut env = Self::new();
for (k, v) in &module.metadata {
env.vars.entry(k.clone()).or_insert_with(|| v.clone());
}
env
}
fn get(&self, name: &str) -> Option<&Value> {
self.vars.get(name)
}
@@ -162,7 +172,7 @@ impl Interpreter {
) -> Result<Value> {
let fun = find_function_anywhere(module, name)
.ok_or_else(|| self.err(format!("unknown function `{name}`")))?;
let mut env = Env::new();
let mut env = Env::with_metadata(module);
for (k, v) in &self.entry_bindings {
env.set(k.clone(), v.clone());
}
@@ -178,7 +188,7 @@ impl Interpreter {
self.site_module = Some(module as *const Module);
let result = (|| {
if let Some(main) = find_top(module, "main") {
return self.run_function(module, main, Env::new(), &[], true);
return self.run_function(module, main, Env::with_metadata(module), &[], true);
}
// Document-as-entry: sole top-level `#` object with no params (e.g. `# Hello World`).
let entries: Vec<&Function> = module
@@ -187,7 +197,13 @@ impl Interpreter {
.filter(|f| f.is_object() && f.params.is_empty())
.collect();
if entries.len() == 1 {
return self.run_function(module, entries[0], Env::new(), &[], true);
return self.run_function(
module,
entries[0],
Env::with_metadata(module),
&[],
true,
);
}
bail!("no `# main` object to run");
})();
@@ -1285,6 +1301,9 @@ fn eval_binary(op: BinaryOp, l: &Value, r: &Value) -> Result<Value> {
(Value::Int(a), Value::Num(b)) => Ok(Value::Num(*a as f64 + b)),
(Value::Num(a), Value::Int(b)) => Ok(Value::Num(a + *b as f64)),
(Value::Text(a), Value::Text(b)) => Ok(Value::Text(format!("{a}{b}"))),
(Value::Text(a), Value::Secret(b)) => Ok(Value::Text(format!("{a}{b}"))),
(Value::Secret(a), Value::Text(b)) => Ok(Value::Text(format!("{a}{b}"))),
(Value::Secret(a), Value::Secret(b)) => Ok(Value::Text(format!("{a}{b}"))),
(Value::Text(a), b) => Ok(Value::Text(format!("{a}{}", b.as_display()))),
(a, Value::Text(b)) => Ok(Value::Text(format!("{}{b}", a.as_display()))),
_ => bail!("`+` needs ints, nums, or text"),
+17 -3
View File
@@ -5,6 +5,7 @@
pub mod aliases;
pub mod ast;
pub mod binding;
pub mod browser_session;
pub mod builtin;
pub mod bytecode;
@@ -51,7 +52,8 @@ use crate::bytecode::{compile_module, Vm};
use crate::capture::RunCapture;
use crate::interp::Interpreter;
use crate::lex::classify_source;
use crate::load::{load_module, load_module_from_source};
use crate::load::{load_module_from_source, load_module_with_ctx};
use crate::binding::{cwd_for_path, BindingContext};
pub use browser_session::{value_as_json, BrowserSession};
@@ -95,6 +97,8 @@ pub struct RunOptions {
pub sleep_limit_ms: Option<u64>,
/// When set, write `# main` return value as JSON to this path (file subtasks).
pub emit_result: Option<std::path::PathBuf>,
/// CLI `--bind KEY=VALUE` pairs for Artifact Metadata Binding (`arg` + overlay).
pub binds: Vec<(String, String)>,
}
impl Default for RunOptions {
@@ -115,6 +119,7 @@ impl Default for RunOptions {
fs_root: None,
sleep_limit_ms: None,
emit_result: None,
binds: Vec::new(),
}
}
}
@@ -173,7 +178,8 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result<i32> {
println!("=== marqdo: end tokens ===");
}
let module = load_module(path)?;
let bind_ctx = BindingContext::from_binds(&opts.binds, cwd_for_path(Some(path)));
let module = load_module_with_ctx(path, &bind_ctx)?;
if opts.dump_ast {
print!("{}", format_ast_dump(&path_label, &module));
@@ -189,6 +195,7 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result<i32> {
.collect::<Vec<_>>()
);
println!("imports: {:?}", module.imports);
println!("metadata: {:?}", module.metadata.iter().map(|(k, v)| (k, v.as_display())).collect::<Vec<_>>());
println!("=== marqdo: end sema ===");
}
@@ -196,6 +203,7 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result<i32> {
Backend::Tree => {
let mut host = HostContext::for_run(Some(path), opts.host_caps(), opts.argv.clone());
host.set_entry_source(Some(path), &source);
host.entry_metadata = module.metadata.clone();
let mut interp = Interpreter::new(Some(path), opts.trace_eval)
.with_stdin(stdin_lines.clone())
.with_host(host);
@@ -217,6 +225,7 @@ pub fn run_file(path: &Path, opts: &RunOptions) -> Result<i32> {
}
let mut host = HostContext::for_run(Some(path), opts.host_caps(), opts.argv.clone());
host.set_entry_source(Some(path), &source);
host.entry_metadata = module.metadata.clone();
let mut vm = Vm::new(Some(path))
.with_stdin(stdin_lines)
.with_trace(opts.trace_eval)
@@ -261,12 +270,14 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result<RunCapture> {
let source = std::fs::read_to_string(path)
.map_err(|e| anyhow::anyhow!("failed to read {}: {e}", path.display()))?;
let stdin_lines = crate::input_feed::effective_stdin(&source, &opts.stdin_lines);
let module = load_module(path)?;
let bind_ctx = BindingContext::from_binds(&opts.binds, cwd_for_path(Some(path)));
let module = load_module_with_ctx(path, &bind_ctx)?;
match opts.backend {
Backend::Tree => {
let mut host = HostContext::for_capture(Some(path), opts.host_caps());
host.set_entry_source(Some(path), &source);
host.argv = opts.argv.clone();
host.entry_metadata = module.metadata.clone();
if let Some(root) = &opts.fs_root {
host.fs_root = Some(root.clone());
}
@@ -290,6 +301,7 @@ pub fn run_file_capture(path: &Path, opts: &RunOptions) -> Result<RunCapture> {
let mut host = HostContext::for_capture(Some(path), opts.host_caps());
host.set_entry_source(Some(path), &source);
host.argv = opts.argv.clone();
host.entry_metadata = module.metadata.clone();
if let Some(root) = &opts.fs_root {
host.fs_root = Some(root.clone());
}
@@ -323,6 +335,7 @@ pub fn run_source(source: &str, opts: &RunOptions) -> Result<RunCapture> {
let mut host = HostContext::for_capture(None, opts.host_caps());
host.set_entry_source(None, source);
host.argv = opts.argv.clone();
host.entry_metadata = module.metadata.clone();
if let Some(root) = &opts.fs_root {
host.fs_root = Some(root.clone());
}
@@ -346,6 +359,7 @@ pub fn run_source(source: &str, opts: &RunOptions) -> Result<RunCapture> {
let mut host = HostContext::for_capture(None, opts.host_caps());
host.set_entry_source(None, source);
host.argv = opts.argv.clone();
host.entry_metadata = module.metadata.clone();
if let Some(root) = &opts.fs_root {
host.fs_root = Some(root.clone());
}
+35 -9
View File
@@ -7,17 +7,27 @@ use std::path::{Path, PathBuf};
use anyhow::{bail, Context, Result};
use crate::ast::Module;
use crate::diagnostics::Diagnostic;
use crate::binding::{cwd_for_path, resolve_metadata, BindingContext};
use crate::diagnostics::{Diagnostic, Span};
use crate::embedded_lib;
use crate::parse::parse_source;
/// Load `path` and recursively bind imported modules (no flat merge).
pub fn load_module(path: &Path) -> Result<Module> {
let mut visited = HashSet::new();
load_module_inner(path, &mut visited)
load_module_with_ctx(path, &BindingContext::from_binds(&[], cwd_for_path(Some(path))))
}
fn load_module_inner(path: &Path, visited: &mut HashSet<PathBuf>) -> Result<Module> {
/// Load with BindingContext (CLI `--bind`, cwd for `sys.cwd`).
pub fn load_module_with_ctx(path: &Path, ctx: &BindingContext) -> Result<Module> {
let mut visited = HashSet::new();
load_module_inner(path, &mut visited, ctx)
}
fn load_module_inner(
path: &Path,
visited: &mut HashSet<PathBuf>,
ctx: &BindingContext,
) -> Result<Module> {
let canon = path
.canonicalize()
.unwrap_or_else(|_| path.to_path_buf());
@@ -30,12 +40,20 @@ fn load_module_inner(path: &Path, visited: &mut HashSet<PathBuf>) -> Result<Modu
.with_context(|| format!("failed to read {}", path.display()))?;
let mut module = parse_source(&source).map_err(|e| attach_path(path, e))?;
// Resolve Artifact Metadata bindings (entry and imports share the same ctx).
let file_ctx = BindingContext {
args: ctx.args.clone(),
cwd: cwd_for_path(Some(path)),
};
module.metadata = resolve_metadata(&module.metadata_raw, &file_ctx, Span::new(1, 1))
.map_err(|e| attach_path(path, e))?;
let base = path.parent().unwrap_or_else(|| Path::new("."));
let imports = module.imports.clone();
let mut import_modules = HashMap::new();
for imp in imports {
let dep_path = resolve_import(base, &imp.path)?;
let dep = load_module_inner(&dep_path, visited)?;
let dep = load_module_inner(&dep_path, visited, ctx)?;
if import_modules.contains_key(&imp.bind) {
bail!(
"duplicate import bind `{}` while loading {}",
@@ -249,7 +267,8 @@ fn attach_path(path: &Path, err: anyhow::Error) -> anyhow::Error {
/// `lib/…` stdlib (no filesystem / `ext/` for this MVP path).
pub fn load_module_from_source(source: &str) -> Result<Module> {
let mut visited = HashSet::new();
load_module_from_source_inner(source, "<memory>", &mut visited)
let ctx = BindingContext::default();
load_module_from_source_inner(source, "<memory>", &mut visited, &ctx)
}
/// 给错误打上文件标签,**保留**结构化诊断(错误出口唯一;AI/MLSP 面不许拍平成字符串)。
@@ -270,6 +289,7 @@ fn load_module_from_source_inner(
source: &str,
label: &str,
visited: &mut HashSet<PathBuf>,
ctx: &BindingContext,
) -> Result<Module> {
let key = PathBuf::from(label);
if !visited.insert(key.clone()) {
@@ -278,10 +298,12 @@ fn load_module_from_source_inner(
let result = (|| {
let mut module = parse_source(source).map_err(|e| label_error(label, e))?;
module.metadata = resolve_metadata(&module.metadata_raw, ctx, Span::new(1, 1))
.map_err(|e| label_error(label, e))?;
let imports = module.imports.clone();
let mut import_modules = HashMap::new();
for imp in imports {
let dep = load_embedded_import(&imp.path, visited)?;
let dep = load_embedded_import(&imp.path, visited, ctx)?;
if import_modules.contains_key(&imp.bind) {
bail!("duplicate import bind `{}` while loading {label}", imp.bind);
}
@@ -296,7 +318,11 @@ fn load_module_from_source_inner(
result
}
fn load_embedded_import(rel: &str, visited: &mut HashSet<PathBuf>) -> Result<Module> {
fn load_embedded_import(
rel: &str,
visited: &mut HashSet<PathBuf>,
ctx: &BindingContext,
) -> Result<Module> {
let rel = rel.replace('\\', "/");
let rest = if let Some(r) = rel.strip_prefix("lib/") {
r.to_string()
@@ -314,7 +340,7 @@ fn load_embedded_import(rel: &str, visited: &mut HashSet<PathBuf>) -> Result<Mod
bail!("embedded lib not found: lib/{rest}");
};
let label = format!("lib/{rest}");
load_module_from_source_inner(&dep_source, &label, visited)
load_module_from_source_inner(&dep_source, &label, visited, ctx)
}
#[cfg(test)]
+11
View File
@@ -66,6 +66,10 @@ enum Commands {
#[arg(long, value_name = "FILE")]
emit_result: Option<PathBuf>,
/// Artifact Metadata Binding: `KEY=VALUE` (repeatable). Feeds `arg.KEY` and overlays metadata.
#[arg(long = "bind", value_name = "KEY=VALUE")]
binds: Vec<String>,
/// Emit diagnostics as JSON on stderr (machine-readable; AI/MLSP 面).
#[arg(long)]
json: bool,
@@ -228,6 +232,7 @@ fn try_main(cli: Cli) -> Result<i32> {
dump_all,
stdin_file,
emit_result,
binds,
json: _,
} => {
let path = file.unwrap_or_else(|| PathBuf::from("index.mq.md"));
@@ -235,10 +240,15 @@ fn try_main(cli: Cli) -> Result<i32> {
Some(p) => load_stdin_file(&p)?,
None => Vec::new(),
};
let mut bind_pairs = Vec::new();
for b in &binds {
bind_pairs.push(marqdo::binding::parse_bind_kv(b)?);
}
let mut opts = if dump_all {
RunOptions {
stdin_lines: stdin_lines.clone(),
emit_result: emit_result.clone(),
binds: bind_pairs.clone(),
..RunOptions::dump_all()
}
} else {
@@ -252,6 +262,7 @@ fn try_main(cli: Cli) -> Result<i32> {
backend: backend.into(),
stdin_lines,
emit_result,
binds: bind_pairs,
..RunOptions::default()
}
};
+121 -6
View File
@@ -28,7 +28,7 @@ pub fn parse_source(source: &str) -> Result<Module> {
pub fn parse_classified(lines: &[ClassifiedLine]) -> Result<Module> {
let mut cur = Cursor::new(lines);
let (imports, uses) = cur.parse_frontmatter()?;
let (imports, uses, metadata_raw) = cur.parse_frontmatter()?;
let mut functions = Vec::new();
while cur.skip_noise() {
let Some(line) = cur.peek() else { break };
@@ -65,6 +65,8 @@ pub fn parse_classified(lines: &[ClassifiedLine]) -> Result<Module> {
uses,
functions,
import_modules: std::collections::HashMap::new(),
metadata_raw,
metadata: Vec::new(),
})
}
@@ -134,17 +136,24 @@ impl<'a> Cursor<'a> {
})
}
fn parse_frontmatter(&mut self) -> Result<(Vec<Import>, Vec<Use>)> {
fn parse_frontmatter(
&mut self,
) -> Result<(
Vec<Import>,
Vec<Use>,
Vec<(String, crate::binding::MetaValue)>,
)> {
let mut imports = Vec::new();
let mut uses = Vec::new();
let mut metadata_raw = Vec::new();
if !self.skip_noise() {
return Ok((imports, uses));
return Ok((imports, uses, metadata_raw));
}
let Some(first) = self.peek() else {
return Ok((imports, uses));
return Ok((imports, uses, metadata_raw));
};
if first.text.trim() != "---" {
return Ok((imports, uses));
return Ok((imports, uses, metadata_raw));
}
self.bump();
while let Some(line) = self.peek() {
@@ -169,6 +178,8 @@ impl<'a> Cursor<'a> {
));
}
imports.push(imp);
self.bump();
continue;
}
Ok(Some(ImportLine::Member(u))) => {
if imports.iter().any(|i| i.bind == u.bind)
@@ -181,13 +192,43 @@ impl<'a> Cursor<'a> {
));
}
uses.push(u);
self.bump();
continue;
}
Ok(None) => {}
Err(e) => return Err(bail_at(None, span, e.to_string())),
}
// Artifact metadata key: value (flat Phase 1)
if let Some((key, rest)) = split_frontmatter_key(t) {
self.bump();
let value_raw = if rest.is_empty()
|| rest == "|"
|| rest == "|-"
|| rest == "|+"
|| rest == ">"
|| rest == ">-"
|| rest == ">+"
{
collect_block_scalar(self, rest)?
} else {
rest.to_string()
};
let mv = crate::binding::parse_meta_value(&value_raw)
.map_err(|e| bail_at(None, span, e.to_string()))?;
if metadata_raw.iter().any(|(k, _)| k == key) {
return Err(bail_at(
None,
span,
format!("duplicate metadata key `{key}`"),
));
}
metadata_raw.push((key.to_string(), mv));
continue;
}
// Unknown / non-key line: skip (compat with freeform frontmatter notes)
self.bump();
}
Ok((imports, uses))
Ok((imports, uses, metadata_raw))
}
fn parse_function(&mut self, min_level: u8) -> Result<Function> {
@@ -1169,6 +1210,80 @@ pub enum ImportLine {
Member(Use),
}
fn split_frontmatter_key(trimmed: &str) -> Option<(&str, &str)> {
let t = trimmed.trim();
if t.is_empty() || t.starts_with('#') {
return None;
}
// import lines are handled earlier
let Some((key, rest)) = t.split_once(':') else {
return None;
};
let key = key.trim();
if key.is_empty() || key.contains(' ') {
return None;
}
// Avoid treating `http://…` style as key (no spaces in key already; also reject if key has `/`)
if key.contains('/') {
return None;
}
Some((key, rest.trim()))
}
fn collect_block_scalar(cur: &mut Cursor<'_>, indicator: &str) -> Result<String> {
let mut lines = Vec::new();
while let Some(line) = cur.peek() {
let raw = line.text.trim_end_matches(['\r', '\n']);
let bt = raw.trim();
if bt == "---" {
break;
}
// Next top-level key or import ends the block
if !raw.starts_with(' ') && !raw.starts_with('\t') && !bt.is_empty() {
if split_frontmatter_key(bt).is_some() || parse_import_line(bt).ok().flatten().is_some()
{
break;
}
if indicator.is_empty() {
// empty rest on key line without block indicator: no body
break;
}
}
if indicator.is_empty() {
break;
}
cur.bump();
if raw.starts_with(' ') || raw.starts_with('\t') {
lines.push(strip_yaml_indent(raw));
} else if bt.is_empty() {
lines.push(String::new());
} else {
// folded content without indent — take as-is once
lines.push(bt.to_string());
break;
}
}
if indicator.starts_with('>') {
Ok(lines
.into_iter()
.filter(|l| !l.is_empty())
.collect::<Vec<_>>()
.join(" "))
} else {
Ok(lines.join("\n"))
}
}
fn strip_yaml_indent(line: &str) -> String {
if line.starts_with(" ") {
line[2..].to_string()
} else if line.starts_with('\t') {
line[1..].to_string()
} else {
line.trim_start_matches([' ', '\t']).to_string()
}
}
fn legacy_frontmatter_import_hint(trimmed: &str) -> Option<String> {
let t = trimmed.trim();
if !t.starts_with('>') {
+12
View File
@@ -27,6 +27,8 @@ pub enum Value {
Formula(FormulaExpr),
/// External language source from ```lang fence (`type` → `code`).
Code(CodeBlock),
/// Sensitive text from `${secret.*}` — Display shows `<secret>`; reveal on Text concat.
Secret(String),
}
impl Value {
@@ -37,6 +39,7 @@ impl Value {
Value::Int(n) => *n != 0,
Value::Num(n) => *n != 0.0 && !n.is_nan(),
Value::Text(s) => !s.is_empty(),
Value::Secret(s) => !s.is_empty(),
Value::List(xs) => !xs.is_empty(),
Value::Map(xs) => !xs.is_empty(),
Value::Formula(_) => true,
@@ -44,6 +47,14 @@ impl Value {
}
}
/// Plaintext for Text / Secret (Authorization etc.). Prefer [`as_display`] for logs.
pub fn reveal_text(&self) -> Option<&str> {
match self {
Value::Text(s) | Value::Secret(s) => Some(s.as_str()),
_ => None,
}
}
pub fn as_display(&self) -> String {
match self {
Value::None => "None".into(),
@@ -52,6 +63,7 @@ impl Value {
Value::Int(n) => n.to_string(),
Value::Num(n) => crate::formula::format_num(*n),
Value::Text(s) => s.clone(),
Value::Secret(_) => "<secret>".into(),
Value::List(xs) => {
let parts: Vec<String> = xs.iter().map(|v| v.as_display()).collect();
format!("[{}]", parts.join(", "))
+1
View File
@@ -98,6 +98,7 @@ pub fn api_debug_start(root: &Path, body: &str) -> serde_json::Value {
};
let mut host = HostContext::for_capture(Some(&path_for_thread), opts.host_caps());
host.fs_root = Some(root_for_thread);
host.entry_metadata = module.metadata.clone();
if let Some(lim) = opts.sleep_limit_ms {
host.sleep_limit_ms = Some(lim);
}
+1
View File
@@ -415,6 +415,7 @@ fn value_kind_label(v: &crate::value::Value) -> String {
Value::Int(_) => "int".into(),
Value::Num(_) => "num".into(),
Value::Text(_) => "text".into(),
Value::Secret(_) => "secret".into(),
Value::Formula(crate::formula::Expr::Matrix { rows, .. }) => {
format!("formula · {}×{}", rows.len(), rows.first().map(|r| r.len()).unwrap_or(0))
}
+36
View File
@@ -0,0 +1,36 @@
---
title: agent MCP stdio client (offline)
description: Oneshoot list+call against python mock MCP server.
import agent:ext/ai/agent.mq.md
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
import json:lib/json.mq.md
---
# main
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=no-agent-plugin
> sys.exit code=1
**argv = > json.parse text=["tests/ext/fixtures/mcp-stdio-mock.py"]**
**listed = > agent.mcp_client_list command="python3" args=`argv`**
**tools = > json.get value=`listed` key="tools"**
**n = > len value=`tools`**
1. `n` == 1
> print text=mcp-client-list-ok
2. *
> print text=mcp-client-list-fail
> print text=`listed`
**call_args = > json.parse text={"msg":"hi"}**
**called = > agent.mcp_client_call command="python3" args=`argv` tool="echo" arguments=`call_args`**
**auth = > json.get value=`called` key="authority"**
1. `auth` == "workbook"
> print text=mcp-client-call-ok
2. *
> print text=mcp-client-call-fail
> print text=`called`
+63
View File
@@ -0,0 +1,63 @@
---
title: Agent Framework P4 — Adaptive Routing + Policy Compilation (offline)
description: Learn skill, compile policy from skill-tagged episodes, route via marqdo backend without Jev/LLM.
import fs:lib/fs.mq.md
import json:lib/json.mq.md
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
---
# main
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=no-agent-plugin
> sys.exit code=1
**paths = > json.parse text={"mem":".marqdo/agent-memory-p4-test","kb":".marqdo/agent-kb-p4-test","task":"Reply with exactly the word pong and nothing else.","skill":"concepts/skills/reply-with-exactly-the-word-pong-and-nothing-els.md"}**
**mem = > json.get value=`paths` key="mem"**
**kb = > json.get value=`paths` key="kb"**
**task = > json.get value=`paths` key="task"**
**skill = > json.get value=`paths` key="skill"**
> fs.remove_tree path=`mem`
> fs.remove_tree path=`kb`
> agent_memory_ensure memory_dir=`mem`
**ep1 = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" skill=`skill` llm_calls=2 memory_dir=`mem`**
**ep2 = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" skill=`skill` llm_calls=2 memory_dir=`mem`**
**ep3 = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" skill=`skill` llm_calls=2 memory_dir=`mem`**
**learned = > agent_maybe_learn task=`task` memory_dir=`mem` kb_dir=`kb` improve_every=3 promote=True**
**did = > json.get value=`learned` key="learned"**
1. `did`
> print text=skill-learned
2. *
> print text=skill-skip
**ep4 = > agent_record_episode task=`task` status="ok" result="pong" mode="compiled" skill=`skill` llm_calls=0 memory_dir=`mem`**
**ep5 = > agent_record_episode task=`task` status="ok" result="pong" mode="compiled" skill=`skill` llm_calls=0 memory_dir=`mem`**
**ep6 = > agent_record_episode task=`task` status="ok" result="pong" mode="compiled" skill=`skill` llm_calls=0 memory_dir=`mem`**
**pol = > agent_compile_policy memory_dir=`mem` min_evidence=3**
**pok = > json.get value=`pol` key="ok"**
1. `pok`
> print text=policy-ok
2. *
> print text=policy-fail
**routed = > agent_route task=`task` backend="auto" memory_dir=`mem` kb_dir=`kb`**
**matched = > json.get value=`routed` key="matched"**
**needs = > json.get value=`routed` key="needs_llm"**
1. `matched`
1. not `needs`
> print text=route-hit
2. *
> print text=route-needs-llm
2. *
> print text=route-miss
**backend = > json.get value=`routed` key="backend"**
> print text=`backend`
+54
View File
@@ -0,0 +1,54 @@
---
title: plan must not overwrite existing llm_free resources
description: force+confirm plan keeps a pre-seeded compiled skill workbook intact (offline).
import agent:ext/ai/agent.mq.md
import fs:lib/fs.mq.md
import json:lib/json.mq.md
import llm:ext/ai/llm.mq.md
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
import text:lib/text.mq.md
---
# main
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=no-agent-plugin
> sys.exit code=1
**kb = ".marqdo/agent-kb-preserve-test"**
**ex = > fs.exists path=`kb`**
1. `ex`
> fs.remove_tree path=`kb`
2. *
**_ = 1**
> fs.make_dirs path=`kb`
**parts = > json.parse text={"res":"/resources/","ext":".mq.md","dir":"/resources"}**
**res_dir = kb + [dir](`parts`)**
> fs.make_dirs path=`res_dir`
**goal = "Preserve compiled skill body under force plan"**
**slug = > agent_goal_slug goal=`goal`**
**res = kb + [res](`parts`) + slug + [ext](`parts`)**
**body = > fs.read_text path="fixtures/preserve-skill.mq.md"**
> fs.write_text path=`res` text=`body`
**model = > llm.create**
`tools` =
| 工具 |
|------|
**ag = > agent.agent model=`model` tools=`tools` standing="preserve probe"**
**out = > `ag`.plan goal=`goal` kb_dir=`kb` force=True confirm=True writeback=False reuse=False**
**st = > json.get value=`out` key="status"**
> print text=`st`
**after = > fs.read_text path=`res`**
**kept = > text.contains text=`after` sub="kept"**
**no_skel = > text.contains text=`after` sub="worker.step"**
> print text=`kept`
> print text=`no_skel`
+65
View File
@@ -0,0 +1,65 @@
---
title: agent resume checkpoint (offline)
description: save / load / list / clear under .marqdo/agent-resume-test
import agent:ext/ai/agent.mq.md
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
import json:lib/json.mq.md
import fs:lib/fs.mq.md
---
# main
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=no-agent-plugin
> sys.exit code=1
**dir = ".marqdo/agent-resume-test"**
**exists = > fs.exists path=`dir`**
1. `exists`
> fs.remove_tree path=`dir`
2. *
**_ = 1**
**saved = > agent.resume_save id="demo1" goal="ping" status="running" round=2 resume_dir=`dir`**
**ok = > json.get value=`saved` key="ok"**
1. `ok`
> print text=resume-save-ok
2. *
> print text=resume-save-fail
**loaded = > agent.resume id="demo1" resume_dir=`dir`**
**found = > json.get value=`loaded` key="found"**
**round = > json.get value=`loaded` key="round"**
1. `found`
1. `round` == 2
> print text=resume-load-ok
2. *
> print text=resume-round-fail
2. *
> print text=resume-load-fail
**listed = > agent.resume_list resume_dir=`dir`**
**items = > json.get value=`listed` key="items"**
**n = > len value=`items`**
1. `n` == 1
> print text=resume-list-ok
2. *
> print text=resume-list-fail
**cleared = > agent.resume_clear id="demo1" resume_dir=`dir`**
**c = > json.get value=`cleared` key="cleared"**
1. `c`
> print text=resume-clear-ok
2. *
> print text=resume-clear-fail
**loaded2 = > agent.resume_load id="demo1" resume_dir=`dir`**
**found2 = > json.get value=`loaded2` key="found"**
1. not `found2`
> print text=resume-gone-ok
2. *
> print text=resume-gone-fail
+43
View File
@@ -0,0 +1,43 @@
---
title: agent small-llm route request (offline)
description: router=small-llm returns needs_llm + prompt; jev alias same shape.
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
import json:lib/json.mq.md
---
# main
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=no-agent-plugin
> sys.exit code=1
**r = > agent_route task="say hello" backend="small-llm" kb_dir=".marqdo/agent-kb-route-test" memory_dir=".marqdo/agent-memory-route-test"**
**needs = > json.get value=`r` key="needs_llm"**
**backend = > json.get value=`r` key="backend"**
**prompt = > json.get value=`r` key="prompt"**
1. `needs`
1. `backend` == "small-llm"
1. `prompt`
> print text=small-llm-ok
2. *
> print text=small-llm-no-prompt
2. *
> print text=small-llm-backend-fail
2. *
> print text=small-llm-fail
**j = > agent_route task="say hello" backend="jev" kb_dir=".marqdo/agent-kb-route-test" memory_dir=".marqdo/agent-memory-route-test"**
**jb = > json.get value=`j` key="backend"**
**jn = > json.get value=`j` key="needs_llm"**
1. `jn`
1. `jb` == "small-llm"
> print text=jev-alias-ok
2. *
> print text=jev-alias-backend-fail
> print text=`jb`
2. *
> print text=jev-alias-fail
+58
View File
@@ -0,0 +1,58 @@
---
title: Agent Framework v2 — episode → learn → compile (offline)
description: Record three identical successes, maybe_learn compiles llm_free skill, resolve hits compiled path.
import agent:ext/ai/agent.mq.md
import fs:lib/fs.mq.md
import json:lib/json.mq.md
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
---
# main
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=no-agent-plugin
> sys.exit code=1
**paths = > json.parse text={"mem":".marqdo/agent-memory-v2-test","kb":".marqdo/agent-kb-v2-test","task":"Reply with exactly the word pong and nothing else."}**
**mem = > json.get value=`paths` key="mem"**
**kb = > json.get value=`paths` key="kb"**
**task = > json.get value=`paths` key="task"**
> fs.remove_tree path=`mem`
> fs.remove_tree path=`kb`
> agent_memory_ensure memory_dir=`mem`
**ep1 = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" llm_calls=2 memory_dir=`mem`**
**ep2 = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" llm_calls=2 memory_dir=`mem`**
**ep3 = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" llm_calls=2 memory_dir=`mem`**
**ok = > json.get value=`ep3` key="ok"**
1. `ok`
> print text=ep-ok
2. *
> print text=ep-fail
**listed = > agent_list_episodes memory_dir=`mem` task=`task`**
**n = > json.get value=`listed` key="count"**
> print text=`n`
**learned = > agent_maybe_learn task=`task` memory_dir=`mem` kb_dir=`kb` improve_every=3 promote=True**
**did = > json.get value=`learned` key="learned"**
1. `did`
> print text=learned
2. *
> print text=learn-skip
**resolved = > agent_resolve task=`task` kb_dir=`kb`**
**lf = > json.get value=`resolved` key="llm_free"**
1. `lf`
> print text=llm-free
2. *
> print text=not-free
**m = > agent_metrics memory_dir=`mem`**
**eps = > json.get value=`m` key="episodes"**
> print text=`eps`
+60
View File
@@ -0,0 +1,60 @@
---
title: Agent zero-LLM execution after policy/skill compile
description: After Skill+Policy compilation, run with router=marqdo records llm_calls=0.
import agent:ext/ai/agent.mq.md
import fs:lib/fs.mq.md
import json:lib/json.mq.md
import llm:ext/ai/llm.mq.md
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
---
# main
**p = > plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=no-agent-plugin
> sys.exit code=1
**paths = > json.parse text={"mem":".marqdo/agent-memory-zero-llm","kb":".marqdo/agent-kb-zero-llm","task":"Reply with exactly the word pong and nothing else.","skill":"concepts/skills/reply-with-exactly-the-word-pong-and-nothing-els.md"}**
**mem = > json.get value=`paths` key="mem"**
**kb = > json.get value=`paths` key="kb"**
**task = > json.get value=`paths` key="task"**
**skill = > json.get value=`paths` key="skill"**
**ex_m = > fs.exists path=`mem`**
1. `ex_m`
> fs.remove_tree path=`mem`
2. *
**_ = 1**
**ex_k = > fs.exists path=`kb`**
1. `ex_k`
> fs.remove_tree path=`kb`
2. *
**_ = 1**
> agent_memory_ensure memory_dir=`mem`
**_ = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" skill=`skill` llm_calls=2 tokens=100 memory_dir=`mem`**
**_ = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" skill=`skill` llm_calls=2 tokens=80 memory_dir=`mem`**
**_ = > agent_record_episode task=`task` status="ok" result="pong" mode="explore" skill=`skill` llm_calls=1 tokens=40 memory_dir=`mem`**
**_ = > agent_maybe_learn task=`task` memory_dir=`mem` kb_dir=`kb` improve_every=3 promote=True**
**_ = > agent_record_episode task=`task` status="ok" result="pong" mode="compiled" skill=`skill` llm_calls=0 tokens=0 memory_dir=`mem`**
**_ = > agent_record_episode task=`task` status="ok" result="pong" mode="compiled" skill=`skill` llm_calls=0 tokens=0 memory_dir=`mem`**
**_ = > agent_record_episode task=`task` status="ok" result="pong" mode="compiled" skill=`skill` llm_calls=0 tokens=0 memory_dir=`mem`**
**_ = > agent_compile_policy memory_dir=`mem` min_evidence=3**
**model = > llm.create**
`tools` =
| 工具 |
|------|
**ag = > agent.agent model=`model` tools=`tools` standing="zero-llm compiled run"**
**out = > `ag`.run task=`task` kb_dir=`kb` memory_dir=`mem` learn=False router="marqdo" writeback=False**
**ex = > json.get value=`out` key="execution"**
**calls = > json.get value=`ex` key="llm_calls"**
**mode = > json.get value=`ex` key="mode"**
> print text=`mode`
> print text=`calls`
+73
View File
@@ -0,0 +1,73 @@
#!/usr/bin/env python3
"""Minimal stdio MCP server for offline client goldens."""
import json
import sys
def read_msg():
line = sys.stdin.readline()
if not line:
return None
line = line.strip()
if not line:
return read_msg()
return json.loads(line)
def write_msg(msg):
sys.stdout.write(json.dumps(msg, separators=(",", ":")) + "\n")
sys.stdout.flush()
TOOLS = [
{
"name": "echo",
"description": "echo arguments",
"inputSchema": {"type": "object", "properties": {}, "additionalProperties": True},
}
]
while True:
msg = read_msg()
if msg is None:
break
mid = msg.get("id")
method = msg.get("method") or ""
params = msg.get("params") or {}
if mid is None and str(method).startswith("notifications/"):
continue
if method == "initialize":
write_msg({
"jsonrpc": "2.0",
"id": mid,
"result": {
"protocolVersion": "2024-11-05",
"capabilities": {"tools": {}},
"serverInfo": {"name": "mock", "version": "0.1.0"},
},
})
elif method in ("tools/list", "list_tools"):
write_msg({"jsonrpc": "2.0", "id": mid, "result": {"tools": TOOLS}})
elif method in ("tools/call", "call_tool"):
name = params.get("name") or ""
args = params.get("arguments") or {}
if name != "echo":
write_msg({
"jsonrpc": "2.0",
"id": mid,
"error": {"code": -32000, "message": f"unknown tool {name}"},
})
else:
write_msg({
"jsonrpc": "2.0",
"id": mid,
"result": {
"content": [{"type": "text", "text": json.dumps(args, separators=(",", ":"))}],
"isError": False,
},
})
elif method == "ping":
write_msg({"jsonrpc": "2.0", "id": mid, "result": {}})
else:
write_msg({
"jsonrpc": "2.0",
"id": mid,
"error": {"code": -32601, "message": f"method not found: {method}"},
})
+10
View File
@@ -0,0 +1,10 @@
---
type: skill
status: compiled
llm_free: true
---
# main
**`result` = "kept"**
*`result`*
+11
View File
@@ -0,0 +1,11 @@
---
type: prompt
model: gpt-4o-mini
---
Explain Marqdo as an AI-native programming language.
## Requirements
- Be concise.
- Mention executable documents.
+6
View File
@@ -0,0 +1,6 @@
---
type: prompt
title: marqdo-one-liner
---
Reply with exactly one English word: pong
+19
View File
@@ -0,0 +1,19 @@
---
title: llm create + collect offline
description: Factory create + collect alias; no network.
import llm:ext/ai/llm.mq.md
import net:lib/net.mq.md
---
# main
**model = > llm.create**
> print text=[model](`model`)
> print text=[backend](`model`)
**fixture = "data: {\"choices\":[{\"delta\":{\"content\":\"Hi\"}}]}\n\ndata: {\"choices\":[{\"delta\":{\"content\":\"!\"}}]}\n\ndata: [DONE]\n"**
**events = > net.openai_sse_parse text=`fixture`**
**answer = > llm.collect events=`events`**
> print text=`answer`
**alias = > llm.stream_result events=`events`**
> print text=`alias`
+14
View File
@@ -0,0 +1,14 @@
---
type: prompt
title: entry prompt offline
import llm:ext/ai/llm.mq.md
import sys:lib/sys.mq.md
---
Say hello to Marqdo.
# main
**raw = > sys.module_source**
**p = > llm.prompt_body src=`raw`**
> print text=`p`
+14
View File
@@ -0,0 +1,14 @@
---
title: llm meta binding offline
description: Create handle from Artifact Metadata (model / api_key); no network.
type: llm
model: ${env.MARQDO_LLM_META_MODEL ?? "meta-model"}
api_key: ${secret.OPENAI_API_KEY ?? "sk-test"}
import llm:ext/ai/llm.mq.md
---
# main
**h = > llm.llm**
> print text=[model](`h`)
> print text=[api_key](`h`)
+26
View File
@@ -0,0 +1,26 @@
---
title: llm named handles + prompt_load offline
description: fast/reasoning names, ollama backend tag, and type:prompt body load; no network.
import llm:ext/ai/llm.mq.md
import text:lib/text.mq.md
---
# main
**fast = > llm.fast model="qwen-fast-test"**
> print text=[name](`fast`)
> print text=[model](`fast`)
**reason = > llm.reasoning model="gpt-reason-test"**
> print text=[name](`reason`)
> print text=[model](`reason`)
**ollama = > llm.create backend="ollama" model="llama3.2"**
> print text=[backend](`ollama`)
> print text=[model](`ollama`)
**prompt = > llm.prompt_load path="fixtures/prompt-marqdo.md"**
**has = > text.contains text=`prompt` sub="Explain Marqdo"**
**no_fm = > text.contains text=`prompt` sub="type: prompt"**
> print text=`has`
> print text=`no_fm`
+24
View File
@@ -0,0 +1,24 @@
---
title: llm tool_calls offline
description: Parse OpenAI-shaped tool_calls into a list; no network.
import openai:ext/ai/llm/openai.mq.md
import json:lib/json.mq.md
---
# main
**raw = "{\"choices\":[{\"finish_reason\":\"tool_calls\",\"message\":{\"role\":\"assistant\",\"content\":null,\"tool_calls\":[{\"id\":\"call_1\",\"type\":\"function\",\"function\":{\"name\":\"lookup\",\"arguments\":\"{\\\"q\\\":\\\"marqdo\\\"}\"}}]}}]}"**
**data = > json.parse text=`raw`**
**tc = > openai.tool_calls_from data=`data`**
**n = > len value=`tc`**
> print text=`n`
**first = [1](tc)**
> print text=[id](`first`)
> print text=[type](`first`)
**fn = [function](first)**
> print text=[name](`fn`)
**empty_data = > json.parse text={"choices":[{"message":{"role":"assistant","content":"hi"}}]}**
**empty = > openai.tool_calls_from data=`empty_data`**
**en = > len value=`empty`**
> print text=`en`
+316
View File
@@ -31,6 +31,19 @@ fn run_with_stdin(args: &[&str], stdin: &str) -> (i32, String, String) {
(code, stdout, stderr)
}
fn run_with_env(args: &[&str], env: &[(&str, &str)]) -> (i32, String, String) {
let mut cmd = Command::new(env!("CARGO_BIN_EXE_marqdo"));
cmd.args(args);
for (k, v) in env {
cmd.env(k, v);
}
let output = cmd.output().expect("failed to run marqdo");
let code = output.status.code().unwrap_or(1);
let stdout = String::from_utf8_lossy(&output.stdout).into_owned();
let stderr = String::from_utf8_lossy(&output.stderr).into_owned();
(code, stdout, stderr)
}
fn assert_out(path: &str, expect: &str) {
let (code, stdout, stderr) = run(&["run", path]);
assert_eq!(code, 0, "{path} stderr={stderr}");
@@ -96,6 +109,61 @@ fn ensure_web_plugin_built() {
}
/// Build `libagent` once per test process and prefer it over a stale `~/.marqdo/ext`.
fn ensure_agent_plugin_built() {
use std::sync::Once;
static ONCE: Once = Once::new();
ONCE.call_once(|| {
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let status = Command::new("cargo")
.args(["build", "-p", "marqdo_plugin_agent"])
.current_dir(&root)
.status()
.expect("build marqdo_plugin_agent");
assert!(status.success(), "failed to build marqdo_plugin_agent");
let lib = if cfg!(windows) {
root.join("target").join("debug").join("agent.dll")
} else if cfg!(target_os = "macos") {
root.join("target").join("debug").join("libagent.dylib")
} else {
root.join("target").join("debug").join("libagent.so")
};
// Prefer release if newer / present (local `cargo build --release -p …`).
let release = if cfg!(windows) {
root.join("target").join("release").join("agent.dll")
} else if cfg!(target_os = "macos") {
root.join("target").join("release").join("libagent.dylib")
} else {
root.join("target").join("release").join("libagent.so")
};
// Prefer the debug artifact we just built; only fall back to release if
// debug is missing (or release is strictly newer — local release workflows).
let chosen = if lib.is_file() {
if release.is_file() {
let lib_m = std::fs::metadata(&lib).and_then(|m| m.modified()).ok();
let rel_m = std::fs::metadata(&release).and_then(|m| m.modified()).ok();
match (lib_m, rel_m) {
(Some(l), Some(r)) if r > l => release,
_ => lib,
}
} else {
lib
}
} else {
release
};
assert!(chosen.is_file(), "missing agent plugin at {}", chosen.display());
// SAFETY: single-threaded Once; children inherit for the rest of the test process.
std::env::set_var("MARQDO_AGENT_PLUGIN", &chosen);
if std::env::var_os("MARQDO_EXT").is_none() {
let ext = root.join("ext");
if ext.join("ai").join("agent.mq.md").is_file() {
std::env::set_var("MARQDO_EXT", &ext);
}
}
});
}
/// Assert failure with `path:line:col:` prefix and message substring (both backends).
fn assert_err(path: &str, line_col: &str, substr: &str) {
for backend in ["tree", "bytecode"] {
@@ -118,10 +186,16 @@ fn assert_err(path: &str, line_col: &str, substr: &str) {
/// Like [`assert_out`], but sets a dummy OpenAI key so offline LLM/agent paths
/// that only check for the env var (no live HTTP) can proceed.
/// Also points `MARQDO_EXT` at the repo `ext/` so tests do not pick up a stale
/// `~/.marqdo/ext` pack ahead of in-tree sources.
fn assert_out_llm_offline(path: &str, expect: &str) {
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let ext = root.join("ext");
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["run", path])
.env("OPENAI_API_KEY", "sk-test")
.env("MARQDO_EXT", &ext)
.current_dir(&root)
.output()
.expect("failed to run marqdo");
let code = output.status.code().unwrap_or(1);
@@ -458,6 +532,67 @@ fn structure_optional_param() {
);
}
#[test]
fn structure_meta_binding() {
let (code, stdout, stderr) = run(&[
"run",
"tests/structure/meta-binding.mq.md",
"--bind",
"extra=from-cli",
]);
assert_eq!(code, 0, "meta-binding stderr={stderr}");
assert_eq!(
stdout.trim_end(),
"default-model\nHello World\n16\nsk-test\nfrom-cli"
);
}
#[test]
fn structure_meta_binding_env_and_secret() {
let (code, stdout, stderr) = run_with_env(
&[
"run",
"tests/structure/meta-binding.mq.md",
"--bind",
"model=from-bind",
],
&[
("MARQDO_META_MODEL", "from-env"),
("MARQDO_META_USER", "Ada"),
("MARQDO_META_TOKENS", "32"),
("MARQDO_META_SECRET", "s3cr3t"),
],
);
assert_eq!(code, 0, "meta-binding-env stderr={stderr}");
// --bind overlays model; secret displays as <secret>
assert_eq!(
stdout.trim_end(),
"from-bind\nHello Ada\n32\n<secret>\nno-extra"
);
}
#[test]
fn structure_meta_lift() {
let (code, stdout, stderr) = run(&["run", "tests/structure/meta-lift.mq.md"]);
assert_eq!(code, 0, "meta-lift stderr={stderr}");
assert_eq!(stdout.trim_end(), "lifted-model\nhi\nsk-lift");
}
#[test]
fn structure_meta_lift_secret_and_bytecode() {
let (code, stdout, stderr) = run_with_env(
&[
"run",
"--backend",
"bytecode",
"tests/structure/meta-lift.mq.md",
],
&[("MARQDO_LIFT_SECRET", "top-secret")],
);
assert_eq!(code, 0, "meta-lift-bc stderr={stderr}");
assert_eq!(stdout.trim_end(), "lifted-model\nhi\n<secret>");
}
#[test]
fn keywords_print() {
assert_out(
@@ -2378,6 +2513,39 @@ mcp-fn-ok",
);
}
#[test]
fn ext_agent_mcp_client() {
ensure_agent_plugin_built();
assert_out(
"tests/ext/agent-mcp-client.mq.md",
"mcp-client-list-ok
mcp-client-call-ok",
);
}
#[test]
fn ext_agent_resume() {
ensure_agent_plugin_built();
assert_out(
"tests/ext/agent-resume.mq.md",
"resume-save-ok
resume-load-ok
resume-list-ok
resume-clear-ok
resume-gone-ok",
);
}
#[test]
fn ext_agent_small_llm_route() {
ensure_agent_plugin_built();
assert_out(
"tests/ext/agent-small-llm-route.mq.md",
"small-llm-ok
jev-alias-ok",
);
}
#[test]
fn ext_web_security_smoke() {
ensure_web_plugin_built();
@@ -3733,6 +3901,84 @@ callable-ok",
);
}
#[test]
fn ext_agent_v2_learn() {
ensure_agent_plugin_built();
assert_out(
"tests/ext/agent-v2-learn.mq.md",
"ep-ok
3
learned
llm-free
3",
);
}
#[test]
fn ext_agent_p4_route() {
ensure_agent_plugin_built();
assert_out(
"tests/ext/agent-p4-route.mq.md",
"skill-learned
policy-ok
route-hit
auto/marqdo",
);
}
#[test]
fn ext_agent_plan_preserve() {
ensure_agent_plugin_built();
assert_out_llm_offline(
"tests/ext/agent-plan-preserve.mq.md",
"pending
True
False",
);
}
#[test]
fn ext_agent_zero_llm() {
ensure_agent_plugin_built();
assert_out_llm_offline(
"tests/ext/agent-zero-llm.mq.md",
"compiled
0",
);
}
#[test]
fn ext_llm_named_offline() {
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["run", "tests/ext/llm-named-offline.mq.md"])
.env("OPENAI_API_KEY", "sk-test")
.env("MARQDO_EXT", root.join("ext"))
.env_remove("OPENAI_MODEL")
.env_remove("MARQDO_LLM_MODEL")
.env_remove("MARQDO_LLM_FAST_MODEL")
.env_remove("MARQDO_LLM_REASONING_MODEL")
.current_dir(&root)
.output()
.expect("run llm-named-offline");
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-named-offline stderr={stderr}");
assert_eq!(
stdout.trim_end(),
"fast
qwen-fast-test
reasoning
gpt-reason-test
ollama
llama3.2
True
False",
"stdout={stdout}"
);
}
#[test]
fn lib_net_encode() {
assert_out("tests/lib/net-encode.mq.md", "a%20b");
@@ -3791,13 +4037,83 @@ fn ext_llm_stream_offline() {
assert_out("tests/ext/llm-stream-offline.mq.md", "Hi!");
}
#[test]
fn ext_llm_ask_offline() {
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["run", "tests/ext/llm-ask-offline.mq.md"])
.env("OPENAI_API_KEY", "sk-test")
.env("MARQDO_EXT", root.join("ext"))
.env_remove("OPENAI_MODEL")
.env_remove("MARQDO_LLM_MODEL")
.current_dir(&root)
.output()
.expect("run llm-ask-offline");
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-ask-offline stderr={stderr}");
assert_eq!(
stdout.trim_end(),
"gpt-4o-mini\nopenai-compatible\nHi!\nHi!",
"stdout={stdout}"
);
}
#[test]
fn ext_llm_meta_offline() {
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["run", "tests/ext/llm-meta-offline.mq.md"])
.env("OPENAI_API_KEY", "sk-test")
.env("MARQDO_EXT", root.join("ext"))
.env_remove("OPENAI_MODEL")
.env_remove("MARQDO_LLM_MODEL")
.env_remove("MARQDO_LLM_META_MODEL")
.current_dir(&root)
.output()
.expect("run llm-meta-offline");
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-meta-offline stderr={stderr}");
assert_eq!(
stdout.trim_end(),
"meta-model\n<secret>",
"stdout={stdout}"
);
}
#[test]
fn ext_llm_tool_calls_offline() {
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["run", "tests/ext/llm-tool-calls-offline.mq.md"])
.env("MARQDO_EXT", root.join("ext"))
.current_dir(&root)
.output()
.expect("run llm-tool-calls-offline");
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-tool-calls-offline stderr={stderr}");
assert_eq!(
stdout.trim_end(),
"1\ncall_1\nfunction\nlookup\n0",
"stdout={stdout}"
);
}
#[test]
fn ext_llm_ctor_offline() {
let root = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR"));
let output = Command::new(env!("CARGO_BIN_EXE_marqdo"))
.args(["run", "tests/ext/llm-ctor-offline.mq.md"])
.env("OPENAI_API_KEY", "sk-test")
.env("MARQDO_EXT", root.join("ext"))
.env_remove("OPENAI_MODEL")
.env_remove("MARQDO_LLM_MODEL")
.current_dir(&root)
.output()
.expect("run llm-ctor-offline");
let code = output.status.code().unwrap_or(1);
+28
View File
@@ -0,0 +1,28 @@
---
title: meta-binding
model: ${env.MARQDO_META_MODEL ?? "default-model"}
greeting: "Hello ${env.MARQDO_META_USER ?? "World"}"
tokens: ${int(env.MARQDO_META_TOKENS ?? "16")}
api_key: ${secret.MARQDO_META_SECRET ?? "sk-test"}
import sys:lib/sys.mq.md
---
# main
**m = > sys.meta_get key="model"**
> print text=`m`
**g = > sys.meta_get key="greeting"**
> print text=`g`
**t = > sys.meta_get key="tokens"**
> print text=`t`
**k = > sys.meta_get key="api_key"**
> print text=`k`
**ov = > sys.meta_get key="extra"**
1. `ov`
> print text=`ov`
2. *
> print text=no-extra
+14
View File
@@ -0,0 +1,14 @@
---
title: meta-lift
model: ${env.MARQDO_LIFT_MODEL ?? "lifted-model"}
api_key: ${secret.MARQDO_LIFT_SECRET ?? "sk-lift"}
greeting: "hi"
---
# main
Metadata keys are ordinary variables after Phase 2 lift.
> print text=`model`
> print text=`greeting`
> print text=`api_key`