Release v0.1.2: embedded stdlib, docs, and extension branch policy.

Embed lib/*.mq.md in binary; marqdo version --check; public writeback/subtask pages; restore /vscode-extension/ ignore. VSIX built from branch vscode-extension only (see doc/design/vscode-extension-commit.md).

Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
cflmyandCursor committed 2026-08-07 09:41:53 +08:00
1 parent 3da7b276d3
commit 2e65c055b8
23 files changed
+469 -53

No files matched your search

+37 -5
View File
@@ -14,13 +14,33 @@ jobs:
runs-on: windows-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
- name: Install Node (VS Code extension)
uses: actions/setup-node@v4
with:
node-version: "20"
- name: Build release
run: cargo build --release
- name: Checkout extension sources (branch vscode-extension only)
run: git fetch origin vscode-extension && git checkout origin/vscode-extension -- vscode-extension
- name: Build VSIX
shell: pwsh
run: |
$ver = "${{ github.ref_name }}".TrimStart("v")
Push-Location vscode-extension
npm ci
npm run compile
npx @vscode/vsce package --no-dependencies -o "../dist/marqdo-$ver.vsix"
Pop-Location
- name: Package
shell: pwsh
run: |
@@ -30,6 +50,7 @@ jobs:
$exe = "marqdo-$ver-$target.exe"
$zip = "marqdo-$ver-$target.zip"
$stdlib = "marqdo-$ver-stdlib.zip"
$vsix = "marqdo-$ver.vsix"
Copy-Item target/release/marqdo.exe "dist/$exe"
$stage = "dist/stage-bundle"
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
@@ -47,24 +68,35 @@ jobs:
echo "EXE=$exe" >> $env:GITHUB_ENV
echo "ZIP=$zip" >> $env:GITHUB_ENV
echo "STDLIB=$stdlib" >> $env:GITHUB_ENV
echo "VSIX=$vsix" >> $env:GITHUB_ENV
- name: Upload release assets
uses: softprops/action-gh-release@v2
with:
body: |
## Downloads
## Marqdo ${{ github.ref_name }}
### Highlights
- **Embedded stdlib** (v0.1.2+): `lib/*.mq.md` built into the binary
- **writeback** + **subtask** stdlibs
- **`marqdo version --check`**
- VSIX built from branch **`vscode-extension`** (not tracked on `main`)
### 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` |
| `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib |
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` (optional disk override) |
| `marqdo-*-stdlib.zip` | `lib/` only |
| `marqdo-*.vsix` | VS Code / Cursor extension |
> The standalone `.exe` does **not** ship `lib/`. Use the bundle zip or stdlib zip for `lib/…` imports.
Extension workflow: [doc/design/vscode-extension-commit.md](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension-commit.md)
files: |
dist/${{ env.EXE }}
dist/${{ env.ZIP }}
dist/${{ env.STDLIB }}
dist/${{ env.VSIX }}
fail_on_unmatched_files: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+1 -1
View File
@@ -28,7 +28,7 @@
/public/index.html
/public/pages/
# VS Code extension lives on branch `vscode-extension` only (see doc/design/vscode-extension.md)
# VS Code extension: source only on branch `vscode-extension` (see doc/design/vscode-extension-commit.md)
/vscode-extension/
# Python spike venv (local)
+22
View File
@@ -0,0 +1,22 @@
# Changelog
## v0.1.2 — 2026-08-07
### Added
- **Embedded standard library**: official `lib/*.mq.md` ships inside the `marqdo` binary; disk `lib/` and `MARQDO_LIB` still override.
- **`lib/writeback`** / **`lib/subtask`**: Jupyter-style writeback; concurrent subtasks (file / function / foreign).
- **Surface syntax v0.2**: `` + `param` `` parameters, `1.` ordered branches, backtick identifiers, quoted strings.
- **`marqdo version --check`**: compare installed CLI with latest GitHub release.
- **VS Code extension v0.0.6** (branch **`vscode-extension` only**): v0.2 grammar, update check — see [doc/design/vscode-extension-commit.md](doc/design/vscode-extension-commit.md)
### Changed
- Subtask `spawn` accepts `path=`, `fn=`, `code=`, or `lang=`+`source=` (not file-only).
- Release notes: standalone `.exe` includes stdlib; bundle/stdlib zips remain optional for overrides.
## v0.1.1
- v0.2 syntax migration, writeback/subtask v1 (file subprocess only), view input deferral, optional parameters.
## v0.1.0
- Initial public releases: tree + bytecode backends, `view` / `debug` / `catalog`, core stdlib, `ext/` installer.
Generated
+21 -1
View File
@@ -389,6 +389,25 @@ dependencies = [
"unicode-joining-type",
]
[[package]]
name = "include_dir"
version = "0.7.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "923d117408f1e49d914f1a379a309cffe4f18c05cf4e3d12e613a15fc81bd0dd"
dependencies = [
"include_dir_macros",
]
[[package]]
name = "include_dir_macros"
version = "0.7.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7cab85a7ed0bd5f0e76d93846e0147172bed2e2d3f859bcc33a8d9699cad1a75"
dependencies = [
"proc-macro2",
"quote",
]
[[package]]
name = "is_terminal_polyfill"
version = "1.70.2"
@@ -436,13 +455,14 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "marqdo"
version = "0.1.1"
version = "0.1.2"
dependencies = [
"anyhow",
"assert_cmd",
"chrono",
"clap",
"idna_adapter",
"include_dir",
"libloading",
"predicates",
"pulldown-cmark",
+2 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "0.1.1"
version = "0.1.2"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -24,6 +24,7 @@ ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"
idna_adapter = "=1.1.0"
zeroize = "=1.8.1"
libloading = "=0.8.6"
include_dir = "0.7"
[workspace]
members = ["plugins/demo", "plugins/agent"]
+7 -6
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) · 对象:[objects.md](doc/design/objects.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`) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/)
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.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`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
---
@@ -23,7 +23,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
---
## 语法速览(v0.1)
## 语法速览(v0.2)
| 标记 | 含义 |
|------|------|
@@ -97,18 +97,19 @@ marqdo catalog public -o .marqdo
---
## 现状(v0.1.1)
## 现状(v0.1.2)
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Source)
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
- 标准库:文本、文件、系统(含 `load_dotenv`)、时间、JSON(含 `quote`)、网络(HTTPS + headers)、数学(公式/绘图)、外联(Python 等)、**插件**(`lib/plugin` 加载原生 ABI)
- **`marqdo version --check`**:与 GitHub 最新 release 对比
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**
- **官方扩展 `ext/`**(非 stdlib):[`ext/llm`](doc/design/ext-llm.md);[`ext/agent`](doc/design/ext-agent.md) 智能体开发框架。安装:`marqdo ext list` / `add llm|agent` / `remove`(见 [ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext` 或 `MARQDO_EXT`)
- **原生插件 ABI v1**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);demo `plugins/demo`
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
- **VS Code 扩展**:分支 `vscode-extension`;Release 附带 `.vsix`(Run / View / Debug + CLI 安装助手)
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
```bash
@@ -121,7 +122,7 @@ cargo run -- view output public -o public
powershell -File ./scripts/build-public.ps1
```
**发布包(GitHub Releases)**:单独 `.exe` **不含** `lib/` / `ext/` / 原生插件 `.dll`;请下载带 `lib/`(及可选 `ext/`)的 zip,或另下 `*-stdlib.zip` 解压到可执行文件旁(亦可设 `MARQDO_LIB` / `MARQDO_EXT`)。OpenAI 兼容聊天见 [ext-llm.md](doc/design/ext-llm.md)(项目目录自建 `.env`,勿提交密钥)。智能体布局见 [ext-agent.md](doc/design/ext-agent.md)(`MARQDO_AGENT_PLUGIN` 指向构建出的 `agent` 共享库)。
**发布包(GitHub Releases)**:自 **v0.1.2** 起,单独 `.exe` **已内置**官方 `lib/`(`> lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发;`ext/` 与原生插件 `.dll` 仍须单独安装。`marqdo version --check` 可查看是否有新版本。OpenAI 兼容聊天见 [ext-llm.md](doc/design/ext-llm.md)。智能体布局见 [ext-agent.md](doc/design/ext-agent.md)。
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md)
+1
View File
@@ -42,6 +42,7 @@
| [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/vscode-extension-commit.md](design/vscode-extension-commit.md) | **扩展提交约定(禁止在 main 提交 `vscode-extension/`)** |
| [design/bytecode.md](design/bytecode.md) | **M5 字节码 / 双后端** |
| [design/pipeline-debug.md](design/pipeline-debug.md) | **流水线 `--dump-*` 可视调试** |
| [dev-setup.md](dev-setup.md) | 开发环境配置(Rust M0) |
+2 -1
View File
@@ -56,7 +56,8 @@ Frontmatter:
1. 相对当前文件
2. `MARQDO_LIB`(可指向 `lib` 目录或仓库根)
3. 当前工作目录的 `lib/`
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
5. **内嵌 stdlib**(v0.1.2+,编译进二进制;无磁盘 `lib/` 时自动使用)
当前模块(API 多为 `##` 自由函数;见 [objects.md](objects.md)):
+82
View File
@@ -0,0 +1,82 @@
# VS Code 扩展 — 分支与提交约定
| | |
|---|---|
| 状态 | **强制约定**(勿在 `main` 提交扩展源码) |
| 扩展分支 | **`vscode-extension`** |
| 设计说明 | [vscode-extension.md](vscode-extension.md) |
---
## 1. 原则(必读)
| 分支 | 是否跟踪 `vscode-extension/` |
|------|-------------------------------|
| **`main`** | **否** — `.gitignore` 含 `/vscode-extension/` |
| **`vscode-extension`** | **是** — 扩展唯一源码所在分支 |
**禁止**在 `main` 上:
- 删除 `.gitignore` 里的 `/vscode-extension/`
- `git add vscode-extension/`
- 把扩展目录「合并进 main」以便发版
发版时从 **`vscode-extension` 分支检出**扩展目录打 VSIX(见 §4),**不是**把扩展提交进 `main`。
---
## 2. 日常开发(扩展)
```bash
git fetch origin
git checkout vscode-extension
cd vscode-extension && npm ci && npm run compile
```
改语法、CLI 检测、扩展版本 → **只在 `vscode-extension` 分支提交**:
```bash
git add vscode-extension/
git commit -m "vscode-extension: <简要说明>"
git push origin vscode-extension
```
---
## 3. 日常开发(CLI / 语言)
在 **`main`** 上改 `src/`、`lib/`、`public/`、`tests/` 等;**不要**顺带提交 `vscode-extension/`。
若本地为了调试 checkout 过扩展目录,工作区里可以有 `vscode-extension/` 文件夹,但应被 ignore,且 **`git status` 不应出现**该目录下文件。
---
## 4. 发版(CLI tag + VSIX)
1. **`main`**:打 tag(如 `v0.1.2`),CI 构建 `marqdo.exe` 等。
2. **VSIX**:Release 工作流在 tag 构建时执行:
```bash
git fetch origin vscode-extension
git checkout origin/vscode-extension -- vscode-extension
cd vscode-extension && npm ci && npm run compile && npx @vscode/vsce package
```
3. 本地脚本 `scripts/release-windows.ps1` 同样假定:先 `git checkout origin/vscode-extension -- vscode-extension`(或已在 `vscode-extension` 分支),再打 VSIX。
扩展版本号与最低 CLI 要求写在 **`vscode-extension/package.json`** 与分支 README,**不要**在 `main` 的 CHANGELOG 里冒充已合并扩展源码。
---
## 5. 给 Agent / 协作者
执行「更新 VS Code 插件」类任务时:
1. **切到或基于 `vscode-extension` 分支**改 `vscode-extension/**`
2. **不要**移除 `main` 上 `.gitignore` 的 `/vscode-extension/`
3. **不要**在 `main` 的 release 提交里包含 `vscode-extension/package-lock.json` 等大文件
4. 仅需在 `main` 更新时:改 `doc/design/vscode-extension.md`、Release 说明、**本文件** — 指针文档即可
---
## 6. 历史说明
v0.1.2 准备阶段曾误将 `vscode-extension/` 并入 `main`(并删除 ignore),导致推送体积过大。已恢复:**扩展仅 `vscode-extension` 分支**;`main` 只保留本约定与设计指针。
+5 -5
View File
@@ -3,9 +3,9 @@
| | |
|---|---|
| 状态 | **已定分支模型** |
| 日期 | 2026-08-05 |
| 代码分支 | **`vscode-extension`**(同仓库) |
| 目录 | 工作区 `vscode-extension/`(仅在该分支跟踪;**`main` 忽略**) |
| 目录 | 工作区 `vscode-extension/`(**仅在该分支跟踪;`main` 在 `.gitignore` 忽略**) |
| 提交约定 | **[vscode-extension-commit.md](vscode-extension-commit.md)**(必读,避免误提交到 `main`) |
---
@@ -13,8 +13,8 @@
| 分支 | 内容 |
|------|------|
| `main` | Marqdo 语言 / CLI / `public/*.mq.md` 源;**不**存放扩展实现 |
| `vscode-extension` | VS Code 扩展源码、开发规范、TextMate 语法 |
| `main` | Marqdo 语言 / CLI / `public/*.mq.md`;**不**存放扩展实现 |
| `vscode-extension` | VS Code 扩展源码、TextMate 语法、VSIX 发版 |
| `gh-pages` | 用户站生成 HTML |
```bash
@@ -22,7 +22,7 @@ git checkout vscode-extension
cd vscode-extension && npm install
```
规范入口(在该分支上阅读):
规范入口(在 **`vscode-extension` 分支**上阅读):
- `vscode-extension/README.md` — 目标与目录
- `vscode-extension/DEVELOPMENT.md` — 日常流程
+1 -1
View File
@@ -9,7 +9,7 @@
| [`00-welcome.mq.md`](00-welcome.mq.md) / [`00-欢迎.mq.md`](00-欢迎.mq.md) | 首页(英 / 中) |
| [`structure/`](structure/) | 基本结构 |
| [`keywords/`](keywords/) | 关键字与 L0 内置 |
| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联/插件) |
| [`stdlib/`](stdlib/) | **标准库**(导入方式 + text/表/文件/时间/系统/json/网络/数学/外联/插件/**自写回**/**子任务**;v0.1.2+ 内置于 CLI) |
| [`features/`](features/) | 特性迭代(含对象、官方 `ext/`) |
官方扩展(非 stdlib):`ext/llm`、`ext/agent` — 见 `features/05-extensions.mq.md` / `05-扩展.mq.md` 与 `doc/design/ext-*.md`。
+3 -1
View File
@@ -11,7 +11,9 @@ English-named files export English APIs; Chinese-named files export Chinese APIs
No extra allow flags: importing a module means you intend to use it. Under marqdo view or static export, exit soft-fails and long sleeps are clamped so the console stays up.
Modules: text (text / 文本), table (table / 表), files (fs / 文件), time (time / 时间), system (sys / 系统), json (json only), net (net / 网络), math (math / 数学), foreign (foreign / 外联), plugin (plugin / 插件).
Modules: text (text / 文本), table (table / 表), files (fs / 文件), time (time / 时间), system (sys / 系统), json (json only), net (net / 网络), math (math / 数学), foreign (foreign / 外联), plugin (plugin / 插件), writeback (writeback / 自写回), subtask (subtask / 子任务).
From **v0.1.2**, official `lib/*.mq.md` is **embedded in the `marqdo` binary** (disk `lib/` or `MARQDO_LIB` still overrides). Standalone `.exe` works without a separate stdlib zip.
Official optional extensions live under ext/ (not stdlib): ext/llm, ext/agent — see features/05-extensions.mq.md and doc/design/ext-llm.md / ext-agent.md.
+3 -1
View File
@@ -11,7 +11,9 @@ description: 如何导入官方 lib 模块
导入即表示要用对应能力,无需再加允许旗标。marqdo view 或静态导出里,退出会软失败、长睡眠会被钳制,以免拖垮控制台。
模块:文本(text / 文本)、表(table / 表)、文件(fs / 文件)、时间(time / 时间)、系统(sys / 系统)、json(仅 json)、网络(net / 网络)、数学(math / 数学)、外联(foreign / 外联)、插件(plugin / 插件)。
模块:文本(text / 文本)、表(table / 表)、文件(fs / 文件)、时间(time / 时间)、系统(sys / 系统)、json(仅 json)、网络(net / 网络)、数学(math / 数学)、外联(foreign / 外联)、插件(plugin / 插件)、自写回(writeback / 自写回)、子任务(subtask / 子任务)。
自 **v0.1.2** 起,官方 `lib/*.mq.md` **内置于 `marqdo` 二进制**(磁盘 `lib/` 或 `MARQDO_LIB` 仍可覆盖)。单独下载 `.exe` 即可导入标准库,无需再解压 stdlib 包。
官方可选扩展在 ext/(不是标准库):ext/llm、ext/agent — 见 features/05-扩展.mq.md。
+20
View File
@@ -0,0 +1,20 @@
---
title: lib/subtask — concurrent tasks
description: Spawn file, function, or foreign code in parallel
> lib/subtask.mq.md
---
# main
`spawn` picks **one** mode (others default to `None`):
| Argument | Runs | `wait` returns |
|----------|------|----------------|
| `path=` | `marqdo run` child process | exit code |
| `fn=` + optional `args=` | function in a thread (entry module) | return value |
| `code=` | foreign ``` fence ``` subprocess | stdout text |
| `lang=` + `source=` | foreign source subprocess | stdout text |
Also: `poll id=`, `kill id=`, `wait_all`. Parent exit kills file/foreign children.
> print text=subtask overview ok
+15
View File
@@ -0,0 +1,15 @@
---
title: lib/writeback — Jupyter-style writeback
description: Persist run output in the entry .mq.md file
> lib/writeback.mq.md
---
# main
Writeback stores output in `<!-- marqdo-out … -->` blocks in the **entry** file (the one you run).
- `record value=` — default: insert or replace the block **below the call**; `at_end=true` → single block at EOF
- `get` / `clear` — read or remove the adjacent block (or EOF block when `at_end=true`)
- `list` — all output blocks in the entry file
> print text=writeback overview ok
+20
View File
@@ -0,0 +1,20 @@
---
title: lib/子任务 — 并发子任务
description: 文件、函数或外联代码并行执行
> lib/子任务.mq.md
---
# main
`启动`(`spawn`)四选一(其余参数默认 `None`):
| 参数 | 方式 | `等待` 返回 |
|------|------|-------------|
| `路径=` | `marqdo run` 子进程 | 退出码 |
| `函数=` + 可选 `参数=` | 入口模块中的函数(线程) | 返回值 |
| `代码=` | 外联代码块子进程 | stdout 文本 |
| `语言=` + `源码=` | 外联源码子进程 | stdout 文本 |
另有:`探测`、`终止`、`等待全部`。父进程结束会终止文件/外联子进程。
> 打印 内容=子任务总览就绪
+15
View File
@@ -0,0 +1,15 @@
---
title: lib/自写回 — Jupyter 式写回
description: 把运行结果写回入口 .mq.md
> lib/自写回.mq.md
---
# main
自写回把结果写入入口文件(你 `run` 的那份 `.mq.md`)里的 `<!-- marqdo-out … -->` 块。
- `记录 内容=`(`record`)— 默认写在调用下方;`at_end=真` 则在文件末尾单独一块
- `读取` / `清除` — 读或删相邻块(`at_end` 时指 EOF 块)
- `列表` — 列出文件中所有输出块
> 打印 内容=自写回总览就绪
+29 -27
View File
@@ -1,8 +1,8 @@
# Build Windows release assets (exe, bundle zip with lib/, stdlib zip) and upload
# Build Windows release assets (exe, bundle zip, stdlib zip, VSIX) 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.1.1
# powershell -File ./scripts/release-windows.ps1 -Tag v0.1.2
param(
[string]$Tag = ""
)
@@ -27,22 +27,32 @@ cargo build --release -q
$exeName = "marqdo-$ver-$target.exe"
$zipName = "marqdo-$ver-$target.zip"
$stdlibName = "marqdo-$ver-stdlib.zip"
$vsixName = "marqdo-$ver.vsix"
$exePath = Join-Path $dist $exeName
$zipPath = Join-Path $dist $zipName
$stdlibPath = Join-Path $dist $stdlibName
$vsixPath = Join-Path $dist $vsixName
Copy-Item ".\target\release\marqdo.exe" $exePath -Force
# Bundle: marqdo.exe + lib/ (stdlib resolves next to the binary)
Write-Host "Building VS Code extension $vsixName (from branch vscode-extension) ..."
git fetch origin vscode-extension 2>$null
git checkout origin/vscode-extension -- vscode-extension
Push-Location vscode-extension
npm ci --silent
npm run compile
npx @vscode/vsce package --no-dependencies -o $vsixPath
Pop-Location
# Bundle: marqdo.exe + lib/ (optional disk override)
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 (Join-Path $stage "*") -DestinationPath $zipPath -Force
# Stdlib-only zip (for users who already have the exe)
# Stdlib-only zip (override / mirror)
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
@@ -50,9 +60,10 @@ 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 " $exePath (CLI with embedded stdlib)"
Write-Host " $zipPath (marqdo.exe + lib/)"
Write-Host " $stdlibPath (lib/ only)"
Write-Host " $vsixPath (VS Code extension)"
$raw = ("protocol=https`nhost=github.com`n`n" | git credential fill 2>$null) -join "`n"
$user = ([regex]::Match($raw, '(?m)^username=(.+)$')).Groups[1].Value
@@ -68,7 +79,6 @@ $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)"
# Refresh release notes
$notes = @"
## Marqdo $Tag
@@ -76,34 +86,27 @@ $notes = @"
| 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``).
| ``$exeName`` | CLI with **embedded** official stdlib (``lib/*.mq.md``) |
| ``$zipName`` | ``marqdo.exe`` + ``lib/`` (optional disk override) |
| ``$stdlibName`` | Standard library only — unpack to override embedded lib |
| ``$vsixName`` | **VS Code / Cursor extension** — built from branch ``vscode-extension`` only (see doc/design/vscode-extension-commit.md) |
### 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
- **Embedded stdlib**: standalone ``.exe`` imports ``lib/…`` without a separate zip
- **writeback** + **subtask** (file / function / foreign concurrency)
- **v0.2 syntax**: ``+`param` ``, ``1.`` branches, backtick identifiers, quoted strings
- ``marqdo version --check`` compares with GitHub latest release
### Quick start
``````text
marqdo --version
marqdo version --check
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
See [CHANGELOG.md](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md).
"@
$body = @{
@@ -115,10 +118,9 @@ $body = @{
} | 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)) {
foreach ($file in @($exeName, $zipName, $stdlibName, $vsixName)) {
$path = Join-Path $dist $file
$existing = $rel.assets | Where-Object { $_.name -eq $file }
if ($existing) {
@@ -127,7 +129,7 @@ foreach ($file in @($exeName, $zipName, $stdlibName)) {
}
$uri = "https://uploads.github.com/repos/cflmy/marqdo/releases/$($rel.id)/assets?name=$([uri]::EscapeDataString($file))"
$bytes = [System.IO.File]::ReadAllBytes($path)
$ctype = if ($file.EndsWith(".zip")) { "application/zip" } else { "application/octet-stream" }
$ctype = if ($file.EndsWith(".zip")) { "application/zip" } elseif ($file.EndsWith(".vsix")) { "application/vsix" } else { "application/octet-stream" }
$asset = Invoke-RestMethod -Method Post -Uri $uri -Headers $headers -ContentType $ctype -Body $bytes
Write-Host " $($asset.browser_download_url)"
}
+32
View File
@@ -0,0 +1,32 @@
//! Official `lib/*.mq.md` baked into the binary (fallback when disk `lib/` is absent).
use include_dir::{include_dir, Dir};
static LIB: Dir<'_> = include_dir!("$CARGO_MANIFEST_DIR/lib");
/// Read `lib/<remainder>` from the embedded tree (e.g. `text.mq.md`).
pub fn read_file(remainder: &str) -> Option<String> {
let key = remainder.replace('\\', "/");
LIB.get_file(&key)
.and_then(|f| f.contents_utf8().map(|s| s.to_string()))
}
pub fn has_file(remainder: &str) -> bool {
let key = remainder.replace('\\', "/");
LIB.get_file(&key).is_some()
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn embedded_has_core_libs() {
assert!(has_file("text.mq.md"));
assert!(has_file("subtask.mq.md"));
assert!(has_file("writeback.mq.md"));
assert!(read_file("math.mq.md")
.unwrap()
.contains("host_math_add"));
}
}
+2
View File
@@ -11,6 +11,7 @@ pub mod capture;
pub mod catalog;
pub mod debug;
pub mod diagnostics;
pub mod embedded_lib;
pub mod ext_cli;
pub mod foreign;
pub mod formula;
@@ -21,6 +22,7 @@ pub mod lex;
pub mod load;
pub mod parse;
pub mod value;
pub mod version_check;
pub mod view;
use std::path::Path;
+45 -3
View File
@@ -8,6 +8,7 @@ use anyhow::{bail, Context, Result};
use crate::ast::{Function, Module};
use crate::diagnostics::Diagnostic;
use crate::embedded_lib;
use crate::parse::parse_source;
/// Load `path` and recursively merge imported modules' top-level functions.
@@ -24,7 +25,7 @@ fn load_module_inner(path: &Path, visited: &mut HashSet<PathBuf>) -> Result<Modu
bail!("circular import involving {}", path.display());
}
let source = std::fs::read_to_string(path)
let source = read_module_source(path)
.with_context(|| format!("failed to read {}", path.display()))?;
let mut module = parse_source(&source).map_err(|e| attach_path(path, e))?;
@@ -41,8 +42,38 @@ fn load_module_inner(path: &Path, visited: &mut HashSet<PathBuf>) -> Result<Modu
Ok(module)
}
fn read_module_source(path: &Path) -> Result<String> {
if path.is_file() {
return std::fs::read_to_string(path).map_err(Into::into);
}
if let Some(source) = read_embedded_for_path(path) {
return Ok(source);
}
std::fs::read_to_string(path).map_err(Into::into)
}
fn read_embedded_for_path(path: &Path) -> Option<String> {
lib_remainder(path).as_deref().and_then(embedded_lib::read_file)
}
fn lib_remainder(path: &Path) -> Option<String> {
let s = path.to_string_lossy().replace('\\', "/");
if let Some(rest) = s.strip_prefix("lib/") {
return Some(rest.to_string());
}
// Absolute or relative paths ending in lib/foo.mq.md
let parts: Vec<&str> = s.split('/').collect();
if let Some(pos) = parts.iter().position(|&p| p == "lib") {
if pos + 1 < parts.len() {
return Some(parts[pos + 1..].join("/"));
}
}
None
}
/// Resolve an import path: relative to the importer first; `lib/…` / `std/…`
/// and `ext/…` also search official roots (`MARQDO_LIB` / `MARQDO_EXT`, cwd, near the binary).
/// and `ext/…` also search official roots (`MARQDO_LIB` / `MARQDO_EXT`, cwd, near the binary),
/// then the embedded stdlib baked into the binary.
pub fn resolve_import(from_dir: &Path, rel: &str) -> Result<PathBuf> {
let rel = rel.replace('\\', "/");
let direct = from_dir.join(&rel);
@@ -67,8 +98,11 @@ pub fn resolve_import(from_dir: &Path, rel: &str) -> Result<PathBuf> {
return Ok(as_repo_root);
}
}
if embedded_lib::has_file(remainder) {
return Ok(PathBuf::from("lib").join(remainder));
}
bail!(
"cannot resolve library import `{rel}` (set MARQDO_LIB or keep a lib/ next to the project)"
"cannot resolve library import `{rel}` (set MARQDO_LIB, keep lib/ next to the project, or use a binary with embedded stdlib)"
);
}
@@ -175,4 +209,12 @@ mod tests {
let p2 = resolve_import(Path::new("tests/keywords"), "std/text.mq.md").unwrap();
assert!(p2.ends_with("text.mq.md"));
}
#[test]
fn resolve_embedded_lib_source() {
let p = resolve_import(Path::new("/nonexistent"), "lib/writeback.mq.md").unwrap();
assert!(p.to_string_lossy().replace('\\', "/").contains("lib/writeback.mq.md"));
let src = read_module_source(&p).unwrap();
assert!(src.contains("host_writeback"));
}
}
+13
View File
@@ -115,6 +115,11 @@ enum Commands {
#[command(subcommand)]
action: ExtAction,
},
/// Print version; `--check` compares with the latest GitHub release
Version {
#[arg(long)]
check: bool,
},
}
#[derive(Subcommand, Debug)]
@@ -262,5 +267,13 @@ fn try_main() -> Result<i32> {
}
Ok(0)
}
Commands::Version { check } => {
if check {
marqdo::version_check::check_latest().map_err(|e| anyhow::anyhow!(e))?;
} else {
marqdo::version_check::print_version();
}
Ok(0)
}
}
}
+91
View File
@@ -0,0 +1,91 @@
//! Optional check against GitHub Releases (`marqdo version --check`).
use std::cmp::Ordering;
const REPO: &str = "cflmy/marqdo";
pub fn print_version() {
println!("marqdo {}", env!("CARGO_PKG_VERSION"));
}
pub fn check_latest() -> Result<(), String> {
let current = env!("CARGO_PKG_VERSION");
let url = format!("https://api.github.com/repos/{REPO}/releases/latest");
let response = ureq::get(&url)
.set("Accept", "application/vnd.github+json")
.set("User-Agent", &format!("marqdo/{current}"))
.call()
.map_err(|e| format!("version check failed: {e}"))?;
let body = response
.into_string()
.map_err(|e| format!("version check read failed: {e}"))?;
let tag = parse_tag_name(&body).ok_or_else(|| "version check: missing tag_name".to_string())?;
let latest = tag.trim_start_matches('v');
match compare_semver(latest, current) {
Ordering::Greater => {
println!("Update available: v{latest} (you have {current})");
println!("https://github.com/{REPO}/releases/latest");
}
_ => println!("marqdo {current} is up to date (latest v{latest})."),
}
Ok(())
}
fn parse_tag_name(json: &str) -> Option<String> {
let needle = "\"tag_name\"";
let start = json.find(needle)? + needle.len();
let rest = json[start..].trim_start();
if !rest.starts_with(':') {
return None;
}
let rest = rest[1..].trim_start();
if !rest.starts_with('"') {
return None;
}
let rest = &rest[1..];
let end = rest.find('"')?;
Some(rest[..end].to_string())
}
fn compare_semver(a: &str, b: &str) -> Ordering {
let pa: Vec<u32> = a
.split('-')
.next()
.unwrap_or(a)
.split('.')
.map(|s| s.parse().unwrap_or(0))
.collect();
let pb: Vec<u32> = b
.split('-')
.next()
.unwrap_or(b)
.split('.')
.map(|s| s.parse().unwrap_or(0))
.collect();
for i in 0..3 {
let da = pa.get(i).copied().unwrap_or(0);
let db = pb.get(i).copied().unwrap_or(0);
match da.cmp(&db) {
Ordering::Equal => {}
other => return other,
}
}
Ordering::Equal
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parse_release_tag() {
let json = r#"{"tag_name":"v0.1.2","name":"Marqdo"}"#;
assert_eq!(parse_tag_name(json).as_deref(), Some("v0.1.2"));
}
#[test]
fn semver_order() {
assert_eq!(compare_semver("0.1.2", "0.1.1"), Ordering::Greater);
assert_eq!(compare_semver("0.1.1", "0.1.2"), Ordering::Less);
}
}