Files
marqdo/vscode-extension/ARCHITECTURE.md
T
cflmyandCursor d1b75d88c5 Polish VS Code extension: three toolbar actions and CLI checks.
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>
2026-08-05 17:13:58 +08:00

69 lines
2.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 架构(规范)
## 进程边界
```
┌─────────────────────────────┐
│ 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` 静态站
- 强制用户登录或云服务