Files
marqdo/doc/design/ext-cli.md
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.0 KiB
Executable File

Official extension installer (marqdo ext)

Status Accepted (v0.3.5 prep) — prebuilt native download
Date 2026-09-04
Related ext-llm.md · ext-agent.md · ext-abi.md · 08-ext-deploy-coupling.md

Commands

marqdo ext list
marqdo ext add llm
marqdo ext add agent
marqdo ext add web
marqdo ext remove llm

Install root

  1. MARQDO_EXT if set
  2. Else ~/.marqdo/ext

Imports use paths like import llm:ext/ai/llm.mq.md (see load.rs).

Goal: no local Rust required

End users who install Marqdo from GitHub Releases should run:

marqdo ext add web

and get both L1 .mq.md and the matching native plugin (.dll / .so) without cargo build.

Resolution order (add with native crate)

  1. Local artifact (MARQDO_*_PLUGIN, plugins/web/build for web, target/{debug,release}, beside marqdo, MARQDO_EXT_SOURCE/native, …)
  2. Download marqdo-{VER}-native-{target}.zip from the GitHub Release for this CLI version → cache under ~/.marqdo/cache/
  3. Local rebuild fallback:
    • web → ./scripts/build-web-plugin.sh (Go c-shared libweb; requires Go 1.22+ / cgo)
    • other plugins → cargo build -p marqdo_plugin_* when Rust/cargo is available
  4. Else fail with a clear message pointing at the Release assets

L1 sources:

  1. MARQDO_EXT_SOURCE / repo ./ext / beside binary
  2. Else download marqdo-{VER}-ext.zip into ~/.marqdo/cache/ext-src-v{VER}/

Env knobs

Variable Meaning
MARQDO_EXT_VERSION Override extension pack SemVer (default: CDN latest/VERSION → embedded ext/VERSION → CLI version)
MARQDO_EXT_CDN Public CDN base (default https://ext.marqdo.com)
MARQDO_EXT_NO_DOWNLOAD=1 Never hit the network (CI / air-gap); local/cargo only
MARQDO_EXT_DOWNLOAD_BASE Optional extra base tried before CDN
MARQDO_WEB_PLUGIN / MARQDO_AGENT_PLUGIN / MARQDO_QUANTUM_PLUGIN Explicit native path

Download order for each Release asset: MARQDO_EXT_DOWNLOAD_BASE → CDN ext.marqdo.com → github.com → proxy.cflmy.top. Connect timeout 20s; read timeout 10min.

See ext-cdn.md for R2 layout, separate ext releases, and scripts/upload-ext-r2.py.

Windows Release zip also ships ext/ + ext/native/*.dll next to marqdo.exe so a portable unzip works offline after one download.

Source for add (developers)

  1. MARQDO_EXT_SOURCE — directory containing ai/llm.mq.md …
  2. Else repo ./ext near cwd / binary
  3. Else Release marqdo-*-ext.zip (see above)

Layout (ext/)

ext/
  ai/          # llm + agent L1
  web/
  quantum/

Installed tree (~/.marqdo/ext or MARQDO_EXT):

web/web.mq.md
web/网页.mq.md
native/libweb.so   # or web.dll / libweb.dylib
web.plugin         # absolute path hint

Catalog

Id Installs under MARQDO_EXT
llm ai/llm.mq.md, ai/大模型.mq.md
agent ai/agent.mq.md, ai/智能体.mq.md, native agent
web web/index.mq.md + facade/modules + layout/ · 布局/ + 网页.mq.md, native web
quantum quantum/(含 量子/ 中文树), native quantum

Release assets (native)

Asset Platform
marqdo-VER-native-x86_64-pc-windows-msvc.zip Windows x64 (native/*.dll)
marqdo-VER-native-x86_64-unknown-linux-gnu.zip Linux x64 (native/lib*.so)

macOS: use local cargo build until CI adds Darwin natives (same zip naming pattern reserved).

Tests

tests/gold.rs: ext_cli_add_list_remove_llm, ext_cli_add_agent, ext_cli_add_web (local build path; set MARQDO_EXT_NO_DOWNLOAD=1 in sandboxes if needed).

Unit: ext_fetch URL / triple tests.

Non-goals

  • Third-party registry
  • Merging domain helpers into lib/
  • Guaranteeing plugin source ABI stability (author .mq.md API is the contract)