Compare commits

..
4 Commits
Author SHA1 Message Date
cflmyandCursor 72777a8c74 Release v0.1.1: debug page Logo branding and packaging notes.
Bump crate version, use official Logo for marqdo debug favicon/brand, and document VS Code extension assets in the Windows release script.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 17:17:00 +08:00
cflmyandCursor e08cd839be Ignore vscode-extension on main and document the extension branch.
Point editors to the vscode-extension branch for host work, mirroring the public/gh-pages split.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 16:25:38 +08:00
cflmyandCursor 5309848292 Fix README syntax for function-end HR and document catalog CLI.
Correct ---/***/empty-return conventions and spell out marqdo catalog/sync for OKF-style YAML generation.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 16:01:22 +08:00
cflmyandCursor 1271aafcdd Package release zips with stdlib and document bare-exe limits.
Ship recommended marqdo.exe+lib bundle, a separate stdlib zip, and clear release notes that the standalone exe does not include lib/.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 15:50:10 +08:00
9 changed files with 225 additions and 36 deletions

No files matched your search

+26 -1
View File
@@ -29,17 +29,42 @@ jobs:
New-Item -ItemType Directory -Force -Path dist | Out-Null
$exe = "marqdo-$ver-$target.exe"
$zip = "marqdo-$ver-$target.zip"
$stdlib = "marqdo-$ver-stdlib.zip"
Copy-Item target/release/marqdo.exe "dist/$exe"
Compress-Archive -Path "dist/$exe" -DestinationPath "dist/$zip" -Force
$stage = "dist/stage-bundle"
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
New-Item -ItemType Directory -Force -Path $stage | Out-Null
Copy-Item target/release/marqdo.exe "$stage/marqdo.exe"
Copy-Item lib "$stage/lib" -Recurse
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
$stageLib = "dist/stage-stdlib"
if (Test-Path $stageLib) { Remove-Item $stageLib -Recurse -Force }
New-Item -ItemType Directory -Force -Path $stageLib | Out-Null
Copy-Item lib "$stageLib/lib" -Recurse
if (Test-Path "dist/$stdlib") { Remove-Item "dist/$stdlib" -Force }
Compress-Archive -Path "$stageLib/*" -DestinationPath "dist/$stdlib" -Force
echo "EXE=$exe" >> $env:GITHUB_ENV
echo "ZIP=$zip" >> $env:GITHUB_ENV
echo "STDLIB=$stdlib" >> $env:GITHUB_ENV
- name: Upload release assets
uses: softprops/action-gh-release@v2
with:
body: |
## Downloads
| Asset | Contents |
|-------|----------|
| `marqdo-*-windows-msvc.exe` | **Executable only** — does **not** include the standard library |
| `marqdo-*-windows-msvc.zip` | **Recommended**: `marqdo.exe` + `lib/` (keep them together) |
| `marqdo-*-stdlib.zip` | Standard library only — unpack next to the exe, or set `MARQDO_LIB` |
> The standalone `.exe` does **not** ship `lib/`. Use the bundle zip or stdlib zip for `lib/…` imports.
files: |
dist/${{ env.EXE }}
dist/${{ env.ZIP }}
dist/${{ env.STDLIB }}
fail_on_unmatched_files: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+3
View File
@@ -11,6 +11,9 @@
/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/
spike/__pycache__/
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "0.1.0"
version = "0.1.1"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
+47 -8
View File
@@ -6,7 +6,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · 金样例:[tests/](tests/) · 用户文档:[public/](public/)
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 `vscode-extension`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/)
---
@@ -27,20 +27,29 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
| 标记 | 含义 |
|------|------|
| 无标记行 | 注释 |
| 无标记行 | 注释(空行分段) |
| `*…*` | 程序语句 |
| `**…**` | **返回值**(架构) |
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
| `#` / `##` | 函数与作用域 |
| `+` / `1.` | 分支(臂头单独 `*` = else) |
| `-` | 循环(头下纯名则为形参) |
| 表格 | 集合 |
| `---` / `***` | 可选:框住分支/循环(不强制) |
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
```markdown
# main
> print text=Hello World!
> 问候 谁=World
## 问候
- 谁
> print text=Hello `谁`!
---
## 加一
- n
@@ -48,6 +57,8 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
**`n` + 1**
```
完整约定:[markdown-mapping.md](doc/design/markdown-mapping.md)。
---
## 理念
@@ -55,18 +66,44 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
1. **叙述默认安全**(无标记 = 注释)。
2. **返回是架构;打印只是函数。**
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
4. **计划对齐 [OKF](doc/design/generated-yaml-manifest.md) 规范**:依赖与模块清单由工具生成(`marqdo catalog` / `sync`),不是手填配置——知识图谱与仓库结构同源生长。见 [catalog-cli.md](doc/design/catalog-cli.md)。
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
---
## 现状(v0.1.0)
## OKF 风格清单(自动生成)
从源码派生 YAML / Markdown 知识包(勿手改生成物):
```bash
marqdo catalog [PATH] -o OUT_DIR
marqdo sync [PATH] -o OUT_DIR # catalog 的别名
```
| 参数 | 默认 | 说明 |
|------|------|------|
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
| `-o` / `--out` | `.marqdo` | 输出目录 |
产物示例:`catalog.yaml`、`index.md`、`modules/*.md`(`type: Marqdo Module` 等)。设计见 [generated-yaml-manifest.md](doc/design/generated-yaml-manifest.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
```bash
cargo run -- catalog public -o .marqdo
# 或已安装二进制时:
marqdo catalog public -o .marqdo
```
---
## 现状(v0.1.1)
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Source)
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430)
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
- 标准库:文本、文件、系统、时间、JSON、网络、数学(公式/绘图)、外联(Python 等)
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
- **VS Code 扩展**:分支 `vscode-extension`;Release 附带 `.vsix`(Run / View / Debug + CLI 安装助手)
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
```bash
@@ -74,11 +111,13 @@ cargo run -- run tests/structure/hello.mq.md
cargo run -- run tests/structure/hello.mq.md --backend bytecode
cargo run -- view public --no-open
cargo run -- debug public --no-open
cargo run -- catalog public -o .marqdo
cargo run -- view output public -o public
powershell -File ./scripts/build-public.ps1
cargo run -- catalog tests -o .marqdo
```
**发布包(GitHub Releases)**:单独 `.exe` **不含** `lib/`;请下载带 `lib/` 的 zip,或另下 `*-stdlib.zip` 解压到可执行文件旁(亦可设 `MARQDO_LIB`)。
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md)
---
+2
View File
@@ -34,6 +34,8 @@
| [design/view.md](design/view.md) | **`marqdo view` / `view output` 黑白极简 + 静态文档** |
| [design/user-site.md](design/user-site.md) | **用户站:`public/` → `gh-pages`** |
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
| [design/view-debug.md](design/view-debug.md) | **`marqdo debug` 独立调试页** |
| [design/vscode-extension.md](design/vscode-extension.md) | **VS Code 扩展:分支 `vscode-extension`(main 不跟踪源码)** |
| [design/bytecode.md](design/bytecode.md) | **M5 字节码 / 双后端** |
| [design/pipeline-debug.md](design/pipeline-debug.md) | **流水线 `--dump-*` 可视调试** |
| [dev-setup.md](dev-setup.md) | 开发环境配置(Rust M0) |
+31
View File
@@ -0,0 +1,31 @@
# VS Code 扩展(分支指针)
| | |
|---|---|
| 状态 | **已定分支模型** |
| 日期 | 2026-08-05 |
| 代码分支 | **`vscode-extension`**(同仓库) |
| 目录 | 工作区 `vscode-extension/`(仅在该分支跟踪;**`main` 忽略**) |
---
## 分工(类比 `public` / `gh-pages`)
| 分支 | 内容 |
|------|------|
| `main` | Marqdo 语言 / CLI / `public/*.mq.md` 源;**不**存放扩展实现 |
| `vscode-extension` | VS Code 扩展源码、开发规范、TextMate 语法 |
| `gh-pages` | 用户站生成 HTML |
```bash
git checkout vscode-extension
cd vscode-extension && npm install
```
规范入口(在该分支上阅读):
- `vscode-extension/README.md` — 目标与目录
- `vscode-extension/DEVELOPMENT.md` — 日常流程
- `vscode-extension/ARCHITECTURE.md` — 与 CLI 边界
扩展是 CLI 的薄宿主;语法真相仍是 [markdown-mapping.md](markdown-mapping.md)。
+29 -20
View File
@@ -51,19 +51,23 @@ def api(method: str, url: str, token: str, data: bytes | None = None, content_ty
raise SystemExit(f"HTTP {e.code} {url}: {err}") from e
def find_assets(stem: str) -> list[Path]:
def find_assets(stem: str, ver: str) -> list[Path]:
names = [
f"{stem}.exe",
f"{stem}.zip",
f"marqdo-{ver}-stdlib.zip",
]
assets: list[Path] = []
for base in (Path("dist"), Path("target/dist")):
for name in (f"{stem}.exe", f"{stem}.zip"):
for name in names:
found = None
for base in (Path("dist"), Path("target/dist")):
p = base / name
if p.exists() and all(p.resolve() != a.resolve() for a in assets):
assets.append(p)
if len(assets) >= 2:
break
if len(assets) < 2:
raise SystemExit(
f"missing assets for {stem}.exe/.zip under dist/ or target/dist/"
)
if p.exists():
found = p
break
if not found:
raise SystemExit(f"missing asset: {name} under dist/ or target/dist/")
assets.append(found)
return assets
@@ -71,20 +75,25 @@ def main() -> None:
ver = crate_version()
tag = f"v{ver}"
stem = f"marqdo-{ver}-x86_64-pc-windows-msvc"
assets = find_assets(stem)
assets = find_assets(stem, ver)
notes = f"""## Marqdo {tag}
### Downloads
| Asset | Contents |
|-------|----------|
| `{stem}.exe` | **Executable only** — does **not** include the standard library |
| `{stem}.zip` | **Recommended**: `marqdo.exe` + `lib/` (keep them together; `lib/` resolves next to the binary) |
| `marqdo-{ver}-stdlib.zip` | Standard library only (`lib/*.mq.md`) — unpack next to an existing exe, or set `MARQDO_LIB` |
> **Important:** the standalone `.exe` does **not** ship `lib/`. Importing `lib/text.mq.md` etc. needs the bundle zip or the stdlib zip.
### Highlights
- **Code as docs as knowledge**: `.mq.md` is narrative + program in one tree
- **`marqdo debug`**: dedicated debugger (breakpoints / step / locals); view stays docs-only
- **View**: wider layout, function outline + search
- Foreign code Run works in debug; math / stdlib / foreign as before
- Roadmap: deeper **OKF**-aligned catalog so docs grow into a knowledge base for human–AI collaboration
### Assets
- `{stem}.exe` — Windows x64 binary
- `{stem}.zip` — same binary zipped
- **`marqdo debug`**: dedicated debugger; view stays docs-only
- **View**: function outline + search
- Roadmap: deeper **OKF**-aligned catalog for human–AI knowledge bases
```text
marqdo --version
+80 -5
View File
@@ -1,7 +1,8 @@
# Build Windows release assets and upload them to an existing GitHub Release tag.
# Build Windows release assets (exe, bundle zip with lib/, stdlib zip) and upload
# to an existing GitHub Release tag.
# Usage (from repo root):
# powershell -File ./scripts/release-windows.ps1
# powershell -File ./scripts/release-windows.ps1 -Tag v0.0.4
# powershell -File ./scripts/release-windows.ps1 -Tag v0.1.1
param(
[string]$Tag = ""
)
@@ -16,6 +17,8 @@ if (-not $Tag) {
$ver = $Tag.TrimStart("v")
$target = "x86_64-pc-windows-msvc"
$dist = Join-Path (Get-Location) "dist"
$stage = Join-Path $dist "stage-bundle"
$stageLib = Join-Path $dist "stage-stdlib"
New-Item -ItemType Directory -Force -Path $dist | Out-Null
Write-Host "Building release binary for $Tag ..."
@@ -23,11 +26,33 @@ cargo build --release -q
$exeName = "marqdo-$ver-$target.exe"
$zipName = "marqdo-$ver-$target.zip"
$stdlibName = "marqdo-$ver-stdlib.zip"
$exePath = Join-Path $dist $exeName
$zipPath = Join-Path $dist $zipName
$stdlibPath = Join-Path $dist $stdlibName
Copy-Item ".\target\release\marqdo.exe" $exePath -Force
# Bundle: marqdo.exe + lib/ (stdlib resolves next to the binary)
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
New-Item -ItemType Directory -Force -Path $stage | Out-Null
Copy-Item ".\target\release\marqdo.exe" (Join-Path $stage "marqdo.exe") -Force
Copy-Item ".\lib" (Join-Path $stage "lib") -Recurse -Force
Get-ChildItem -Path (Join-Path $stage "lib") -Recurse -Filter "*.mq.md" | Out-Null
if (Test-Path $zipPath) { Remove-Item $zipPath -Force }
Compress-Archive -Path $exePath -DestinationPath $zipPath -Force
Compress-Archive -Path (Join-Path $stage "*") -DestinationPath $zipPath -Force
# Stdlib-only zip (for users who already have the exe)
if (Test-Path $stageLib) { Remove-Item $stageLib -Recurse -Force }
New-Item -ItemType Directory -Force -Path $stageLib | Out-Null
Copy-Item ".\lib" (Join-Path $stageLib "lib") -Recurse -Force
if (Test-Path $stdlibPath) { Remove-Item $stdlibPath -Force }
Compress-Archive -Path (Join-Path $stageLib "*") -DestinationPath $stdlibPath -Force
Write-Host "Packaged:"
Write-Host " $exePath (binary only — no stdlib)"
Write-Host " $zipPath (marqdo.exe + lib/)"
Write-Host " $stdlibPath (lib/ only)"
$raw = ("protocol=https`nhost=github.com`n`n" | git credential fill 2>$null) -join "`n"
$user = ([regex]::Match($raw, '(?m)^username=(.+)$')).Groups[1].Value
@@ -43,12 +68,62 @@ $headers = @{
$rel = Invoke-RestMethod -Uri "https://api.github.com/repos/cflmy/marqdo/releases/tags/$Tag" -Headers $headers
Write-Host "Uploading to release $($rel.html_url)"
foreach ($file in @($exeName, $zipName)) {
# Refresh release notes
$notes = @"
## Marqdo $Tag
### Downloads
| Asset | Contents |
|-------|----------|
| ``$exeName`` | **Executable only** — does **not** include the standard library |
| ``$zipName`` | **Recommended**: ``marqdo.exe`` + ``lib/`` (place them together; ``lib/`` is resolved next to the binary) |
| ``$stdlibName`` | Standard library only (``lib/*.mq.md``) — unpack next to an existing ``marqdo.exe``, or set ``MARQDO_LIB`` |
| ``marqdo-0.0.5.vsix`` | **VS Code / Cursor extension** — syntax highlight, Run / View / Debug toolbar, CLI+stdlib install helper. Install via ``Extensions: Install from VSIX…``. Source: branch ``vscode-extension``. |
> **Important:** the standalone ``.exe`` does **not** ship ``lib/``. Importing ``lib/text.mq.md`` etc. needs the bundle zip or the stdlib zip beside the binary (or ``MARQDO_LIB``).
### Highlights
- Code as docs as knowledge: ``.mq.md`` is narrative + program
- ``marqdo debug``: breakpoints / step / locals; page favicon and brand use the official Logo
- ``marqdo view``: docs-only Structure + outline/search + Execution
- VS Code extension v0.0.5: three editor actions (Run / View / Debug), logo cover icon, startup CLI version & stdlib detection with optional install
- ``marqdo catalog`` / ``sync``: OKF-style YAML + module pages
- Roadmap: deeper OKF-aligned catalog for human–AI knowledge bases
### Quick start
``````text
marqdo --version
marqdo run public/00-welcome.mq.md
marqdo view public
marqdo debug public
marqdo catalog public -o .marqdo
``````
### Requirements
- Windows x64 for the prebuilt ``.exe`` / zip assets above
- Extension needs Marqdo CLI ≥ 0.1.0 (this release is 0.1.1); auto-install downloads the GitHub bundle when missing
"@
$body = @{
tag_name = $Tag
name = "Marqdo $Tag"
body = $notes
draft = $false
prerelease = $false
} | ConvertTo-Json -Depth 5
Invoke-RestMethod -Method Patch -Uri "https://api.github.com/repos/cflmy/marqdo/releases/$($rel.id)" -Headers $headers -ContentType "application/json; charset=utf-8" -Body ([Text.Encoding]::UTF8.GetBytes($body)) | Out-Null
# Re-fetch assets list after patch
$rel = Invoke-RestMethod -Uri "https://api.github.com/repos/cflmy/marqdo/releases/$($rel.id)" -Headers $headers
foreach ($file in @($exeName, $zipName, $stdlibName)) {
$path = Join-Path $dist $file
# Replace existing asset with same name
$existing = $rel.assets | Where-Object { $_.name -eq $file }
if ($existing) {
Invoke-RestMethod -Method Delete -Uri $existing.url -Headers $headers | Out-Null
Write-Host " deleted old $file"
}
$uri = "https://uploads.github.com/repos/cflmy/marqdo/releases/$($rel.id)/assets?name=$([uri]::EscapeDataString($file))"
$bytes = [System.IO.File]::ReadAllBytes($path)
+6 -1
View File
@@ -76,6 +76,7 @@ window.MARQDO_FILE_PATH = {path_js};
</script>
<header class="dbg-toolbar">
<div class="dbg-brand">
<img class="dbg-logo" src="https://s3.cflmy.cn/logo/Logo.png" width="20" height="20" alt="marqdo"/>
<span class="dbg-mark">marqdo</span>
<span class="dbg-mode">debug</span>
</div>
@@ -167,6 +168,9 @@ fn layout_debug(title: &str, main: &str) -> String {
<meta charset="utf-8"/>
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<title>debug · {title} · marqdo</title>
<link rel="icon" href="https://s3.cflmy.cn/logo/Logo.ico" type="image/x-icon"/>
<link rel="shortcut icon" href="https://s3.cflmy.cn/logo/Logo.ico" type="image/x-icon"/>
<link rel="apple-touch-icon" href="https://s3.cflmy.cn/logo/Logo.png"/>
<style>{css}</style>
</head>
<body class="dbg-body">
@@ -225,7 +229,8 @@ html, body { margin: 0; height: 100%; }
border-bottom: 1px solid #000;
flex-shrink: 0;
}
.dbg-brand { display: flex; align-items: baseline; gap: 0.35rem; }
.dbg-brand { display: flex; align-items: center; gap: 0.4rem; }
.dbg-logo { display: block; border-radius: 3px; flex-shrink: 0; }
.dbg-mark { font-weight: 700; letter-spacing: -0.02em; color: #fff; font-size: 0.9rem; }
.dbg-mode {
font-size: 0.65rem;