Files
marqdo-cli/docs/developers/README.md
T
cflmy 2c7c4f31e7
Linux strict security lane (G-C) / strict isolation escape matrix (push) Waiting to run
ci/woodpecker/push/main Pipeline was successful
ci/woodpecker/manual/performance Pipeline was successful
CI / fmt + clippy + test (Linux x86_64) (push) Waiting to run
CI / schema instance validation + consumers (push) Waiting to run
CI / runtime contract (macos-latest) (push) Waiting to run
CI / runtime contract (windows-latest) (push) Waiting to run
release(3.0.0-beta.1): product version migration, beta gates, archive tooling and developer docs
REL-01: workspace/CLI/Analysis product version 3.0.0-beta.1 with updated
Cargo.lock; project.marqdo is enforced against the running core with
package.marqdo_range_invalid/package.marqdo_incompatible fail-closed
diagnostics; Tool SemVer prerelease negotiation tests; init template and
examples use the beta range. Verify init derives the project name from the
target directory instead of falling back to 'example'.

REL-02: beta support matrix is Linux x86_64 only; macOS/Windows are explicitly
experimental/unclaimed; strict policy and G4 Beta-only WARN are documented for
the release evidence.

REL-03: deterministic release packaging (tools/release/package.py) ships the
CLI and provider worker together with SOURCE_SHA, RELEASE_INFO.json,
known-limitations, specs, developer docs, examples incl. built plugin/provider
artifacts and consumers; tools/release/smoke.py cold-install tests the archive.

REL-04: docs/developers entry pages; corrected and self-contained third-party
integration handbook; stale Proposed/native-only/informational spec claims
fixed; release/status/compatibility/changelog/releasing docs updated.

REL-05: release_evidence.py gains an explicit beta profile
(BETA_RELEASE_CANDIDATE) distinct from the stable profile; Woodpecker build
step now packages and smoke-tests the archive on every pipeline.

Adds a runnable Resource Provider v2 example and corrects check --emit to
Analysis v2.
2026-11-22 02:31:32 +08:00

3.3 KiB

Marqdo developer entry point

Everything a third party needs starts here. The rule behind this page: depend only on the released CLI and public protocols, never on Marqdo's private Rust structures, marqdo-ir internals, inspect --ir, relative paths into the core checkout, or host memory layout. Adding a new domain function must not require a core commit.

Product version for these docs: 3.0.0-beta.1 (Linux x86_64 beta). Protocol versions are independent: Analysis v2, Trace v2, Tool v1, Plugin ABI v1, Foreign wire v1, Provider manifest v2, lock v4, markdown profile marqdo.md.v1.

Pick your entry point

Goal Use Deliverable
AI/math/data/quantum/SKILL libraries, pure algorithms .mq.md package index.mq.md, marqdo.yaml, README, tests
Knowledge/Proof/View/IDE/lint/analysis tools CLI Tool Protocol v1 standalone executable + tool.json + Analysis/Trace consumer
High-performance native callable functions Callable Plugin ABI v1 plugin.yaml, host-targeted library, SDK/header
New foreign language backend (R/Python/Julia/…) Foreign Kernel kernel.json, executable provider, pinned environment
Hardware/device/external-stream resources Resource Provider v2 provider.json, C ABI library, worker helper
Change @exec semantics, add keywords/types not a third-party extension core language RFC + migration + full conformance
  1. quickstart.md — install the archive and run the first project.
  2. libraries.md — publish a pure .mq.md library and consume it through a pinned Git dependency.
  3. tools.md — build an external Tool that consumes Analysis v2 and Trace v2.
  4. extensions.md — plugins, foreign kernels, resource providers, extension selection and lock v4.
  5. analysis-trace.md — the public static/dynamic data contracts and digest binding.
  6. compatibility.md — version axes, platform matrix and the prerelease policy.
  7. release-limits.md — the honest beta limitations (this file ships in the archive as KNOWN_LIMITATIONS.md).

The full worked handbook is ../MARQDO_THIRD_PARTY_INTEGRATION_GUIDE.md. Normative contracts live in ../../spec/; this directory is a task-oriented map, not a second specification.

Baseline repository

The current implementation and release entry point is git.cflmy.cn/cflmy/marqdo-cli. The earlier cflmy/marqdo repository is a different, incompatible language/product line; it is not a source of current protocol or syntax truth. See the parent repository README for the repository split.

Testing against a frozen binary

Any external repository should be testable without rebuilding the CLI:

export MARQDO_BIN=/absolute/path/to/marqdo
# Put marqdo-provider-worker next to it for provider tests, exactly as the
# release archive does.
$MARQDO_BIN --version

Compute the binary SHA-256 before and after your suite; it must not move. The reference implementation of this gate is marqdo-extension-conformance and tools/ci/verify_extension_contracts.py in the core repository.