Files
marqdo/vscode-extension
2026-09-13 15:10:21 +08:00
..

VS Code 扩展(分支工作区)

状态 三按钮 Run / View / Debug + CLI 检测(扩展 v0.0.5;封面 logo;需 CLI ≥ 0.1.0)
日期 2026-08-05
语言仓 cflmy/marqdo main
扩展仓形态 同仓库专用分支 vscode-extension(本目录);main 不跟踪本目录

1. 与 public / gh-pages 的类比

public/ 用户站 vscode-extension/
main 跟踪可执行 .mq.md 源 忽略本目录(不进 main 历史)
专用分支 gh-pages:生成 HTML vscode-extension:扩展源码与规范
消费者 浏览器 / Pages VS Code / Open VSX / Marketplace(日后)

开发扩展时:

git fetch origin
git checkout vscode-extension
cd vscode-extension
npm install

回到语言本体:

git checkout main

可选:git worktree add ../marqdo-vscode vscode-extension,语言与扩展并行目录开发。


2. 目标(对齐 v0.1.0 分发)

v0.1.0 已是「可解释 + view + debug CLI + catalog」的阶段性稳定小版本。扩展的第一阶段目标是 编辑体验,而不是一次做满 IDE:

优先级 能力 说明
P0 .mq.md 语言登记 + 基础语法高亮 TextMate(已落地)
P0 语言配置 括号 / 自动成对(已落地)
P1 任务 / 命令 Marqdo: Run File → marqdo run(已落地)
P1 问题面板 CLI path:line:col → Problems(已落地)
P2 轻量语言特性 大纲(# 函数)、跳转到定义(同文件 / 导入)
P3 DAP / 调试 现已:Marqdo: Open Debugger 拉起 CLI debug 页;日后 DAP
P3 OKF / catalog Marqdo: Generate Catalog(已落地轻量入口)

原则:扩展是 Marqdo CLI 的薄宿主;语义以解释器与 markdown-mapping.md 为准,扩展不发明第二套语法。


3. 目录约定(本分支)

vscode-extension/
  README.md                 # 本文件:分支模型与目标
  DEVELOPMENT.md            # 日常开发流程、脚本、验收
  ARCHITECTURE.md           # 进程边界、与 CLI 的契约
  package.json              # 扩展清单(Marketplace id 待定)
  tsconfig.json
  .vscode/                  # F5:Run Extension
  .vscodeignore
  src/
    extension.ts            # activate:命令 / 诊断
    cli.ts                  # spawn marqdo
    diagnostics.ts          # path:line:col → Problems
  syntaxes/                 # TextMate 语法(P0)
    marqdo.tmLanguage.json
  language-configuration.json

生成物(out/、node_modules/、*.vsix)不入库;见本目录 .gitignore。


4. 命名与发布(待拍板)

项 建议(可改)
扩展显示名 Marqdo
publisher cflmy(或组织账号)
name(包名) marqdo
语言 id marqdo
文件关联 *.mq.md

发布渠道:先私有 / Open VSX,再 VS Marketplace。版本号与语言仓 不必锁死同一 semver,但发行说明应写明「需要 Marqdo CLI ≥ 0.1.0」。


5. 文档索引(语言仓 main)

在 main 上仅保留指针,避免扩展实现泄漏进语言历史:


6. 一句话

语言在 main;编辑器宿主在 vscode-extension 分支。先高亮与 run/诊断,再 LSP/DAP;始终以 CLI 为真相源。