Files
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

107 lines
4.1 KiB
Markdown
Executable File
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Native plugin ABI (v2)
| | |
|---|---|
| Status | Accepted |
| Date | 2026-08-07 |
| Header | [`include/marqdo_abi.h`](../../include/marqdo_abi.h) |
| Related | [ext-agent.md](ext-agent.md) · [stdlib-modules.md](stdlib-modules.md) |
## 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` |
```markdown
---
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
```bash
cargo build -p marqdo_plugin_demo
cargo build -p marqdo_plugin_agent
```
- Demo (ABI v1): `demo_add`, `demo_echo` — [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md).
- Agent (ABI v2): … **OKF agent-kb** …
- Web (ABI v2): HTTP listen + SQLite/Postgres + page render (`web_listen`, `web_render`, `web_db_*`, …) — [`plugins/web`](../../plugins/web)(**Go 全量重写**,见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md) · [ADR 0004](../adr/0004-web-plugin-go.md));作者面 [`ext/web/web.mq.md`](../../ext/web/web.mq.md)。Lookup: `plugin.native_path name=web` / `MARQDO_WEB_PLUGIN` / `marqdo ext add web`.
## 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