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

2.8 KiB
Raw Blame History

架构(规范)

进程边界

┌─────────────────────────────┐
│  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 用户可见失败:

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 静态站
  • 强制用户登录或云服务