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>
110 lines
4.0 KiB
Markdown
110 lines
4.0 KiB
Markdown
# VS Code 扩展(分支工作区)
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | **三按钮 Run / View / Debug + CLI 检测**(扩展 v0.0.5;封面 logo;需 CLI ≥ **0.1.0**) |
|
||
| 日期 | 2026-08-05 |
|
||
| 语言仓 | [`cflmy/marqdo`](https://github.com/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(日后) |
|
||
|
||
开发扩展时:
|
||
|
||
```bash
|
||
git fetch origin
|
||
git checkout vscode-extension
|
||
cd vscode-extension
|
||
npm install
|
||
```
|
||
|
||
回到语言本体:
|
||
|
||
```bash
|
||
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](../doc/design/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` 上仅保留指针,避免扩展实现泄漏进语言历史:
|
||
|
||
- [doc/design/vscode-extension.md](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension.md)(`main` 上的分支说明)
|
||
- 语法:[markdown-mapping.md](https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping.md)
|
||
- 诊断:[pipeline-debug.md](https://github.com/cflmy/marqdo/blob/main/doc/design/pipeline-debug.md)
|
||
- CLI debug:[view-debug.md](https://github.com/cflmy/marqdo/blob/main/doc/design/view-debug.md)
|
||
- Catalog / OKF:[catalog-cli.md](https://github.com/cflmy/marqdo/blob/main/doc/design/catalog-cli.md)
|
||
|
||
---
|
||
|
||
## 6. 一句话
|
||
|
||
**语言在 `main`;编辑器宿主在 `vscode-extension` 分支。先高亮与 run/诊断,再 LSP/DAP;始终以 CLI 为真相源。**
|