Files
marqdo/doc/design/ext-abi.md
T
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00

4.1 KiB
Executable File
Raw Blame History

Native plugin ABI (v2)

Status Accepted
Date 2026-08-07
Header include/marqdo_abi.h
Related ext-agent.md · stdlib-modules.md

Goals

  • Optional native extensions as shared libraries (.dll / .so / .dylib).
  • Not linked into the marqdo binary; load at runtime.
  • Stable C ABI only (no cross-compiler Rust ABI for plugins).
  • Official / local paths only — no third-party package registry.
  • v2: allowlisted host_query so plugins can read entry source / call site / skill without baking agent logic into the core.

Contract

MARQDO_ABI_VERSION = 2 (host accepts plugins with version 1..=2).

Every plugin exports:

Symbol Role
marqdo_plugin_abi_version 1 or 2
marqdo_plugin_init Register functions via MarqdoHostApi
marqdo_plugin_shutdown Teardown

Host provides register_fn, alloc, free, and (v2) host_query.

Wire format

Arguments and results are UTF-8 JSON:

  • Args: JSON object keyed by parameter names (from params CSV at registration).
  • Result: any JSON value mappable to Marqdo Value (same rules as lib/json).

Plugin fn returns 0 + *out_json on success; non-zero + optional *err_msg on failure. Host frees both strings with the host free.

host_query allowlist (v2)

name Result JSON Notes
module_source string Entry .mq.md text
call_site {path,function,line} Active call site
marqdo_skill string Skill pack text
cwd string Host cwd (entry file directory) for path resolution
record_plot {ok:true} Args {svg} + optional path; push SVG into host plots (view embed / CLI auto-write), same channel as math plots

Unknown names fail. Queries are only valid during a plugin function call (host sets thread-local context).

Marqdo surface (lib/plugin / lib/插件)

English Chinese Host
## load (path) ## 加载 (路径) host_plugin_load
## unload ## 卸载 host_plugin_unload
## list ## 列出 host_plugin_list
## native_path (name) ## 原生路径 (名) host_ext_native_path
---
import:
  plugin: lib/plugin.mq.md
---

# main

> load path=demo.dll

*`sum` = > demo_add a=1 b=2 *
> print text=`sum`

After load, registered names are callable like other functions (plugin registry lookup after fixed host fns, before user #/## defs).

Path sandbox: path resolves under the program’s cwd / fs_root (same as lib/fs). Absolute paths outside the root are rejected unless trusted (MARQDO_EXT / MARQDO_AGENT_PLUGIN / built libagent.*). Prefer native_path name=agent for the official agent plugin.

Demo / agent

cargo build -p marqdo_plugin_demo
cargo build -p marqdo_plugin_agent

Layering

Layer May call host_*
lib/* Yes (only L1 wrappers of generic L0.5)
ext/* No — compose lib/* or ABI plugin names via lib/plugin
Application .mq.md Prefer same as ext; do not add agent/OKF originals to src/host

Hard rule: agent / OKF domain primitives live in plugins/agent, never in HostFn / src/host/kb.rs.

Non-goals

  • Embedding plugins in the release exe by default
  • Callbacks from plugin into arbitrary Marqdo evaluation
  • Arbitrary HostFn passthrough via host_query
  • Third-party plugin / package registry