Ship Release native zips and let ext add fetch L1/native without a local Rust toolchain. Co-authored-by: Cursor <cursoragent@cursor.com>
69 lines
2.7 KiB
Markdown
69 lines
2.7 KiB
Markdown
# 解决 8:扩展与部署耦合
|
||
|
||
| | |
|
||
|---|---|
|
||
| 问题 | [研究 §8](../../research/ext-web-customization-limits.md#8-扩展与部署耦合) |
|
||
| 优先级 | **P3** · 文档 + 发布流程 |
|
||
| 触点 | `marqdo ext add web` · ABI 版本 · Docker/发布说明 · [ext-cli.md](../ext-cli.md) · [marqdo-release](../../../.cursor/skills/marqdo-release/SKILL.md) |
|
||
|
||
---
|
||
|
||
## 1. 目标
|
||
|
||
1. 站点作者**不必 fork 插件**才能完成 P0/P1 定制(把能力收进官方参数,见 01–05)。
|
||
2. 版本耦合可预期:changelog / 扩展清单标明「web 插件需 ≥ x.y.z」。
|
||
3. 升级路径文档化:二进制、`.marqdo-ext`、Docker 镜像三者对齐检查。
|
||
|
||
---
|
||
|
||
## 2. 作者 / 运维约定(草案)
|
||
|
||
| 约定 | 说明 |
|
||
|------|------|
|
||
| 定制优先走 `.mq.md` 开关 | `admin_prefix`、`shell_css`、`layout`、`gate`… 进官方 API 后,禁止文档再教「改 plugins/web」 |
|
||
| 兼容性矩阵 | 在 [web-net-capabilities.md](../web-net-capabilities.md) 或本目录维护「Marqdo ↔ libweb 最低版本」表 |
|
||
| `marqdo ext add web` | 安装后打印当前插件路径与版本;与 CLI 版本不符时警告 |
|
||
| Docker | 示例 Dockerfile 注释:升级需同时换 `marqdo` 与 `ext add` 产物 |
|
||
| 样式引号等行为变更 | 写入 CHANGELOG **Breaking / migration** 小节(如 0.3.2 T5) |
|
||
|
||
---
|
||
|
||
## 3. 工程改动点
|
||
|
||
| 改动 | 说明 |
|
||
|------|------|
|
||
| 插件/Crate 版本可见 | `web_listen` 或 `ext list` 显示 web ABI/包版本 |
|
||
| CI | 金样使用仓库内 `plugins/web`;发布技能检查 VSIX/CLI/插件三件套 |
|
||
| 研究→设计→路线图 | C0–C4 进 [ext-web roadmap](../../roadmap/ext-web.md),避免只活在私有 fork |
|
||
|
||
---
|
||
|
||
## 4. 兼容策略
|
||
|
||
- 不承诺插件源码级稳定 API;承诺 **`.mq.md` 作者 API** 在小版本尽量兼容,破坏性变更进 CHANGELOG。
|
||
- Fork 插件仅作为「官方尚未交付」的临时手段,并在 issue/路线图留归还项。
|
||
|
||
---
|
||
|
||
## 5. 验收
|
||
|
||
| 场景 | 期望 |
|
||
|------|------|
|
||
| 升级说明文档 | 运维按清单升级后 web 金样通过 |
|
||
| C0–C2 落地 | 自研后台场景**无需**改 `plugins/web` 源码 |
|
||
| `ext list` / 文档 | 能核对版本 |
|
||
|
||
---
|
||
|
||
## 6. 过渡期 → 预编译路径(进行中)
|
||
|
||
**目标:** 用户 `marqdo ext add web` **不必**本机 Rust。
|
||
|
||
| 交付 | 说明 |
|
||
|------|------|
|
||
| Release `marqdo-*-native-*.zip` | Windows / Linux 预编译 `web`/`agent`/`quantum` |
|
||
| Windows portable zip | 内含 `ext/` + `ext/native/*.dll` |
|
||
| `ext add` 下载回退 | 本地无 `.so`/`.dll` 时从 GitHub Release 拉取(`MARQDO_EXT_NO_DOWNLOAD=1` 可关) |
|
||
|
||
仍保留开发者 `cargo build -p marqdo_plugin_*` 路径。详见 [ext-cli.md](../ext-cli.md)。
|