docs(examples,ci): document CLI plugin invocation and add CI pipeline

- examples/plugin-demo: add plugin-call.mq.md and README sections for
  `marqdo plugin inspect` and the explicit trust flow
  (`--plugin`, `--trust-native-plugin`, `--allow-plugin`), including named-only
  plugin arguments, structured plugin errors and the in-process trust caveat.
- .github/workflows/ci.yml: fmt --check, clippy -D warnings, workspace tests,
  CLI example smoke tests (factorial, math, refs, plugin inspect + invocation).
This commit is contained in:
cflmy committed 2026-11-20 10:46:35 +08:00
1 parent 7fbd5e9ec1
commit dbecf8d019
3 files changed
+87 -3

No files matched your search

+39
View File
@@ -0,0 +1,39 @@
name: CI
on:
push:
pull_request:
env:
CARGO_TERM_COLOR: always
jobs:
test:
name: fmt + clippy + test (Linux x86_64)
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
with:
components: rustfmt, clippy
- name: Rust cache
uses: Swatinem/rust-cache@v2
- name: Formatting
run: cargo fmt --all -- --check
- name: Clippy
run: cargo clippy --workspace --all-targets -- -D warnings
- name: Tests
run: cargo test --workspace
- name: Smoke test the CLI examples
run: |
cargo build -p marqdo-cli
./target/debug/marqdo check examples/factorial.mq.md
./target/debug/marqdo call examples/factorial.mq.md 阶乘 --arg n=5
./target/debug/marqdo call examples/math.mq.md 计算圆面积
./target/debug/marqdo inspect examples/references.mq.md --refs
./examples/plugin-demo/build.sh
./target/debug/marqdo plugin inspect examples/plugin-demo
./target/debug/marqdo run examples/plugin-demo/plugin-call.mq.md \
--plugin examples/plugin-demo \
--trust-native-plugin \
--allow-plugin demo.solver
+43 -3
View File
@@ -46,9 +46,16 @@ sha256sum examples/plugin-demo/solver.so
## Inspect
Manifest validation and artifact verification are host-side library calls
(`crates/marqdo-plugin-abi`); the CLI wrappers are part of the broader
package/CLI workstream. A typical inspection flow is:
Manifest validation and artifact verification are implemented by
`crates/marqdo-plugin-abi` and exposed through `marqdo plugin inspect` (which
never loads plugin code):
```sh
./examples/plugin-demo/build.sh # builds solver.so and refreshes sha256
marqdo plugin inspect examples/plugin-demo
```
A typical inspection flow is:
1. parse `plugin.yaml`,
2. validate name, semver-ish version, `^1.0` ABI requirement, kind, exports,
@@ -109,3 +116,36 @@ only) to keep the example dependency-free. A real plugin should use a proper
JSON library and its language's SDK bindings (the Rust SDK is
`crates/marqdo-plugin-sdk`). The demo also does not request capabilities; see
`CallContext::capability_request` in the SDK for that path.
## Call from a Marqdo document (implemented)
Once the host has made the explicit in-process trust decision, plugin exports
are callable through the namespace that prefixes their export names. Plugin
calls take **named arguments only** in this build:
```markdown
## main
**结果 = solver.add(a=20, b=22)**
> 打印(结果)
```
```sh
marqdo run examples/plugin-demo/plugin-call.mq.md \
--plugin examples/plugin-demo \
--trust-native-plugin \
--allow-plugin demo.solver
# 42
```
- `--plugin <path>` loads one manifest/artifact (repeatable).
- `--allow-plugin demo.solver` grants the plugin capability; without it the
call fails with `permission.denied`.
- `--trust-native-plugin` acknowledges that in-process native code shares the
host address space and is not sandboxed. This build has no isolated worker
transport, and `--mode strict` refuses to run at all.
- Plugin failures become structured runtime errors: `plugin.abi_mismatch`,
`plugin.failure`, `symbol.unknown` (namespace not loaded), or
`permission.denied`.
+5
View File
@@ -0,0 +1,5 @@
## main
**结果 = solver.add(a=20, b=22)**
> 打印(结果)