From dbecf8d0198045a70012a9fcd19f4c1703dfef53 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 20 Nov 2026 10:46:35 +0800 Subject: [PATCH] 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). --- .github/workflows/ci.yml | 39 ++++++++++++++++++++++ examples/plugin-demo/README.md | 46 ++++++++++++++++++++++++-- examples/plugin-demo/plugin-call.mq.md | 5 +++ 3 files changed, 87 insertions(+), 3 deletions(-) create mode 100644 .github/workflows/ci.yml create mode 100644 examples/plugin-demo/plugin-call.mq.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..f6c9959 --- /dev/null +++ b/.github/workflows/ci.yml @@ -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 diff --git a/examples/plugin-demo/README.md b/examples/plugin-demo/README.md index 899176e..d79dce1 100644 --- a/examples/plugin-demo/README.md +++ b/examples/plugin-demo/README.md @@ -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 ` 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`. diff --git a/examples/plugin-demo/plugin-call.mq.md b/examples/plugin-demo/plugin-call.mq.md new file mode 100644 index 0000000..0be661d --- /dev/null +++ b/examples/plugin-demo/plugin-call.mq.md @@ -0,0 +1,5 @@ +## main + +**结果 = solver.add(a=20, b=22)** + +> 打印(结果)