Add Run/View/Debug title icons, logo cover art, version/stdlib install prompts, and LiveServer for view + debug hosts. Co-authored-by: Cursor <cursoragent@cursor.com>
69 lines
2.8 KiB
Markdown
69 lines
2.8 KiB
Markdown
# 架构(规范)
|
||
|
||
## 进程边界
|
||
|
||
```
|
||
┌─────────────────────────────┐
|
||
│ VS Code Extension Host │
|
||
│ · 语言配置 / TextMate │
|
||
│ · 命令、任务、Problems │
|
||
│ · (日后)LSP client │
|
||
│ · (日后)DAP client │
|
||
└─────────────┬───────────────┘
|
||
│ spawn / stdio
|
||
▼
|
||
┌─────────────────────────────┐
|
||
│ marqdo CLI(已安装) │
|
||
│ · run / catalog / debug │
|
||
│ · 诊断文案与行号真相 │
|
||
└─────────────────────────────┘
|
||
```
|
||
|
||
扩展 **不嵌入** Rust 解释器;分发上用户安装 CLI(或日后可选打包 sidecar,仍属后置决策)。
|
||
|
||
## 语言 id
|
||
|
||
- VS Code `languageId`: `marqdo`
|
||
- 文件:`*.mq.md`(必须保留 `.md` 后缀以便通用预览;用 `filename` / `filenamePattern` 关联,避免抢全部 Markdown)
|
||
|
||
## 与 Markdown 扩展共存
|
||
|
||
`.mq.md` 同时是 Markdown。策略:
|
||
|
||
1. **默认**用 Marqdo 语言模式(执行语义优先)。
|
||
2. 提供命令「以 Markdown 打开预览」调用内置 Markdown preview(不切换语言 id 也可预览时,优先不破坏高亮)。
|
||
3. 不禁用用户其它 Markdown 扩展;冲突时文档说明如何 `files.associations`。
|
||
|
||
## 诊断契约
|
||
|
||
CLI 用户可见失败:
|
||
|
||
```text
|
||
path:line:col: message
|
||
```
|
||
|
||
扩展将相对路径解析到工作区 URI,`severity` 为 0-based。与语言仓 P0 诊断模型一致。
|
||
|
||
## CLI 安装(扩展侧)
|
||
|
||
- 启动时(`onStartupFinished`)检测:**CLI 是否存在**、**版本是否 ≥ `marqdo.minCliVersion`(默认 0.1.0)**、**stdlib (`lib/`) 是否可用**。
|
||
- 任一不满足 → 提示用户,由其选择安装 / 打开 Releases / 不再询问。
|
||
- 安装物落到扩展 `globalStorage/cli/`,并写入 `marqdo.cliPath` / `marqdo.libPath`(spawn 时带 `MARQDO_LIB`)。
|
||
- 命令:`Marqdo: Install / Repair CLI`、`Marqdo: Check CLI Status`。
|
||
- 预编译自动安装以 **Windows x64** Release zip 为主。
|
||
|
||
## 调试(P3 → 现有入口)
|
||
- **已落地**:命令 `Marqdo: Open Debugger` 子进程启动 `marqdo debug --no-open`,再打开浏览器 / Simple Browser。
|
||
- **中期**:DAP 适配器包装现有 debug session API(`src/view/debug_api.rs` 语义),避免第三套断点模型。
|
||
|
||
## OKF / catalog(P3)
|
||
|
||
- 命令触发 `marqdo catalog <workspace> -o .marqdo`。
|
||
- 生成物已在语言仓 `.gitignore`(`.marqdo/`);扩展只负责调用与打开 `index.md` / `catalog.yaml`。
|
||
|
||
## 非目标(本阶段)
|
||
|
||
- 在扩展内实现完整树遍历 / 字节码
|
||
- 替代 `marqdo view` 静态站
|
||
- 强制用户登录或云服务
|