Bootstrap VS Code extension workspace and development norms.

Add Marqdo language registration, TextMate grammar stub, and docs for the vscode-extension branch workflow.

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-08-05 16:26:33 +08:00
1 parent e08cd839be
commit f4f798a4d0
11 files changed
+442 -3

No files matched your search

+1 -3
View File
@@ -1,4 +1,4 @@
/target/
/target/
/dist/
**/*.rs.bk
.idea/
@@ -11,8 +11,6 @@
/public/index.html
/public/pages/
# VS Code extension lives on branch `vscode-extension` only (see doc/design/vscode-extension.md)
/vscode-extension/
# Python spike venv (local)
spike/.venv/
+7
View File
@@ -0,0 +1,7 @@
.vscode/**
.vscode-test/**
node_modules/**
out/**
*.vsix
npm-debug.log*
.DS_Store
+9
View File
@@ -0,0 +1,9 @@
.vscode/**
.vscode-test/**
src/**
tsconfig.json
node_modules/**
.gitignore
**/*.map
**/*.ts
!out/**/*.js
+61
View File
@@ -0,0 +1,61 @@
# 架构(规范)
## 进程边界
```
┌─────────────────────────────┐
│ 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 诊断模型一致。
## 调试(P3)
- 短期:命令「在外部打开 `marqdo debug`」或 Simple Browser 打开本地 debug URL。
- 中期: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` 静态站
- 强制用户登录或云服务
+60
View File
@@ -0,0 +1,60 @@
# 开发流程
## 环境
- Node.js 20+(LTS)
- VS Code 1.85+(`engines.vscode` 在 `package.json` 收紧)
- 本机已安装 **Marqdo CLI ≥ 0.1.0**(`marqdo --version`),用于 Run / catalog 集成
## 首次
```bash
git checkout vscode-extension
cd vscode-extension
npm install
```
按 F5(「运行扩展」)打开 Extension Development Host,打开任意 `.mq.md` 验证语言 id / 高亮。
## 日常脚本(约定)
| npm script | 用途 |
|------------|------|
| `npm run compile` | `tsc -p .` → `out/` |
| `npm run watch` | 监视编译 |
| `npm run lint` | 日后 ESLint(先可空) |
| `npm run package` | `vsce package` 打 `.vsix`(发布前) |
尚未加入的脚本:落地 `package.json` 时按上表补齐,勿引入与 Marqdo 语言仓抢戏的重型框架。
## 改语法 / 高亮
1. 对照语言仓 `doc/design/markdown-mapping.md`(以 `main` 为准)。
2. 改 `syntaxes/*.tmLanguage.json`(或等价)。
3. 用 `tests/` 与 `public/` 下真实 `.mq.md` 肉眼验收(Extension Host 打开语言仓 worktree)。
## 改 CLI 集成
- 子进程调用 `marqdo`,cwd = 工作区根或文件目录(与 `marqdo run` 导入/`lib/` 解析一致)。
- 解析 stderr 的 `path:line:col: message` 写入 `DiagnosticCollection`。
- **禁止**在扩展内重新实现解释器。
## 提交与推送
只在 **`vscode-extension` 分支** 提交本目录:
```bash
git status # 确认在 vscode-extension
git add vscode-extension
git commit -m "…"
git push -u origin vscode-extension
```
不要把本目录合并进 `main`(`main` 的 `.gitignore` 会忽略它)。
## 验收清单(P0)
- [ ] `.mq.md` 打开后 Language Mode = Marqdo
- [ ] `#` / `*` / `**` / `>` / 表格 / 注释行有可区分着色
- [ ] 函数体内 `---` / `***`、空返回 `****` 不与普通 Markdown 粗体完全糊成一团(尽力)
- [ ] F5 开发宿主可重复加载,无激活期未捕获异常
+105
View File
@@ -0,0 +1,105 @@
# VS Code 扩展(分支工作区)
| | |
|---|---|
| 状态 | **规范起步**(伴随 Marqdo **v0.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 / semantic 二选一;先 TextMate |
| **P0** | 语言配置 | 注释、括号、自动缩进粗线条 |
| **P1** | 任务 / 命令 | `marqdo run` 当前文件;探测 `PATH` / 工作区 `marqdo` |
| **P1** | 问题面板 | 把 `path:line:col: message` 诊断喂给 Problems |
| **P2** | 轻量语言特性 | 大纲(`#` 函数)、跳转到定义(同文件 / 导入) |
| **P3** | DAP / 调试 | 对接 `marqdo debug` 语义;勿与 CLI debug 页抢两套语义 |
| **P3** | OKF / catalog | 调用 `marqdo 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
.vscodeignore
src/
extension.ts # activate / deactivate
syntaxes/ # TextMate 语法(P0)
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 为真相源。**
@@ -0,0 +1,26 @@
{
"comments": {
"lineComment": null,
"blockComment": null
},
"brackets": [
["{", "}"],
["[", "]"],
["(", ")"]
],
"autoClosingPairs": [
{ "open": "{", "close": "}" },
{ "open": "[", "close": "]" },
{ "open": "(", "close": ")" },
{ "open": "`", "close": "`" },
{ "open": "*", "close": "*" },
{ "open": "**", "close": "**" }
],
"surroundingPairs": [
["{", "}"],
["[", "]"],
["(", ")"],
["`", "`"],
["*", "*"]
]
}
+57
View File
@@ -0,0 +1,57 @@
{
"name": "marqdo",
"displayName": "Marqdo",
"description": "Language support for Marqdo (.mq.md) — code as documentation.",
"version": "0.0.1",
"publisher": "cflmy",
"engines": {
"vscode": "^1.85.0"
},
"categories": [
"Programming Languages"
],
"keywords": [
"marqdo",
"markdown",
"mq.md"
],
"activationEvents": [
"onLanguage:marqdo"
],
"main": "./out/extension.js",
"contributes": {
"languages": [
{
"id": "marqdo",
"aliases": [
"Marqdo",
"marqdo"
],
"extensions": [
".mq.md"
],
"filenamePatterns": [
"*.mq.md"
],
"configuration": "./language-configuration.json"
}
],
"grammars": [
{
"language": "marqdo",
"scopeName": "source.marqdo",
"path": "./syntaxes/marqdo.tmLanguage.json"
}
]
},
"scripts": {
"vscode:prepublish": "npm run compile",
"compile": "tsc -p ./",
"watch": "tsc -watch -p ./"
},
"devDependencies": {
"@types/node": "^20.11.0",
"@types/vscode": "^1.85.0",
"typescript": "^5.3.0"
}
}
+13
View File
@@ -0,0 +1,13 @@
import * as vscode from "vscode";
/**
* Marqdo VS Code extension entry.
* Keep this host thin: language contribution lives in package.json / TextMate;
* run / diagnostics / DAP come later via the marqdo CLI.
*/
export function activate(_context: vscode.ExtensionContext): void {
// P0: grammar + language id are declarative.
// P1+: register commands that spawn `marqdo`.
}
export function deactivate(): void {}
@@ -0,0 +1,89 @@
{
"$schema": "https://raw.githubusercontent.com/martinring/tmlanguage/master/tmlanguage.json",
"name": "Marqdo",
"scopeName": "source.marqdo",
"patterns": [
{ "include": "#frontmatter" },
{ "include": "#heading" },
{ "include": "#hr-end" },
{ "include": "#call" },
{ "include": "#return" },
{ "include": "#empty-return" },
{ "include": "#statement" },
{ "include": "#list-structure" },
{ "include": "#table" },
{ "include": "#code-fence" },
{ "include": "#comment" }
],
"repository": {
"frontmatter": {
"name": "meta.embedded.block.frontmatter.marqdo",
"begin": "\\A---\\s*$",
"end": "^---\\s*$",
"patterns": [
{ "name": "keyword.control.import.marqdo", "match": "^\\s*>\\s+.+$" },
{ "name": "string.unquoted.frontmatter.marqdo", "match": "^.+$" }
]
},
"heading": {
"name": "markup.heading.marqdo",
"match": "^(#{1,6})\\s+(.+)$",
"captures": {
"1": { "name": "punctuation.definition.heading.marqdo" },
"2": { "name": "entity.name.function.marqdo" }
}
},
"hr-end": {
"name": "keyword.control.function.end.marqdo",
"match": "^(---+|\\*{3,})\\s*$"
},
"call": {
"name": "meta.call.marqdo",
"match": "^(\\s*)(>)\\s+(\\S+)(.*)$",
"captures": {
"2": { "name": "keyword.operator.call.marqdo" },
"3": { "name": "entity.name.function.call.marqdo" },
"4": { "name": "meta.call.args.marqdo" }
}
},
"empty-return": {
"name": "keyword.control.return.empty.marqdo",
"match": "^\\s*(\\*{4}|\\*\\*\\s+\\*\\*)\\s*$"
},
"return": {
"name": "meta.return.marqdo",
"begin": "\\*\\*",
"end": "\\*\\*",
"name": "markup.bold.return.marqdo",
"patterns": [
{ "name": "variable.other.marqdo", "match": "`[^`]+`" }
]
},
"statement": {
"name": "meta.statement.marqdo",
"begin": "(?<!\\*)\\*(?!\\*)",
"end": "(?<!\\*)\\*(?!\\*)",
"name": "markup.italic.statement.marqdo"
},
"list-structure": {
"name": "markup.list.marqdo",
"match": "^(\\s*)([-+]|\\d+\\.)\\s+"
},
"table": {
"name": "markup.table.marqdo",
"match": "^\\s*\\|.*\\|\\s*$"
},
"code-fence": {
"name": "markup.fenced_code.block.marqdo",
"begin": "^\\s*```([\\w+-]*)\\s*$",
"end": "^\\s*```\\s*$",
"beginCaptures": {
"1": { "name": "entity.name.tag.lang.marqdo" }
}
},
"comment": {
"name": "comment.line.marqdo",
"match": "^.+$"
}
}
}
+14
View File
@@ -0,0 +1,14 @@
{
"compilerOptions": {
"module": "commonjs",
"target": "ES2020",
"outDir": "out",
"rootDir": "src",
"lib": ["ES2020"],
"sourceMap": true,
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true
},
"exclude": ["node_modules", ".vscode-test"]
}