From 2e65c055b85104f7e8bd8d8cc1f93f23998f81b9 Mon Sep 17 00:00:00 2001 From: cflmy Date: Fri, 7 Aug 2026 09:41:53 +0800 Subject: [PATCH] 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 --- .github/workflows/release.yml | 42 +++++++++++-- .gitignore | 2 +- CHANGELOG.md | 22 +++++++ Cargo.lock | 22 ++++++- Cargo.toml | 3 +- README.md | 13 ++-- doc/README.md | 1 + doc/design/stdlib.md | 3 +- doc/design/vscode-extension-commit.md | 82 ++++++++++++++++++++++++ doc/design/vscode-extension.md | 10 +-- public/README.md | 2 +- public/stdlib/00-overview.mq.md | 4 +- public/stdlib/00-索引.mq.md | 4 +- public/stdlib/subtask.mq.md | 20 ++++++ public/stdlib/writeback.mq.md | 15 +++++ public/stdlib/子任务.mq.md | 20 ++++++ public/stdlib/自写回.mq.md | 15 +++++ scripts/release-windows.ps1 | 56 +++++++++-------- src/embedded_lib.rs | 32 ++++++++++ src/lib.rs | 2 + src/load.rs | 48 +++++++++++++- src/main.rs | 13 ++++ src/version_check.rs | 91 +++++++++++++++++++++++++++ 23 files changed, 469 insertions(+), 53 deletions(-) create mode 100644 CHANGELOG.md create mode 100644 doc/design/vscode-extension-commit.md create mode 100644 public/stdlib/subtask.mq.md create mode 100644 public/stdlib/writeback.mq.md create mode 100644 public/stdlib/子任务.mq.md create mode 100644 public/stdlib/自写回.mq.md create mode 100644 src/embedded_lib.rs create mode 100644 src/version_check.rs diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index bb23d82..e275f11 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -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 }} diff --git a/.gitignore b/.gitignore index 47a3a86..806411f 100644 --- a/.gitignore +++ b/.gitignore @@ -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) diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..404ea9c --- /dev/null +++ b/CHANGELOG.md @@ -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. diff --git a/Cargo.lock b/Cargo.lock index 2df4317..f9f23cf 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -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", diff --git a/Cargo.toml b/Cargo.toml index 4bd5089..e0f6dcc 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -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"] diff --git a/README.md b/README.md index 903ab89..b09b89e 100644 --- a/README.md +++ b/README.md @@ -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) diff --git a/doc/README.md b/doc/README.md index 64c3424..af3b290 100644 --- a/doc/README.md +++ b/doc/README.md @@ -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) | diff --git a/doc/design/stdlib.md b/doc/design/stdlib.md index 3048f67..b21e0b9 100644 --- a/doc/design/stdlib.md +++ b/doc/design/stdlib.md @@ -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)): diff --git a/doc/design/vscode-extension-commit.md b/doc/design/vscode-extension-commit.md new file mode 100644 index 0000000..ad61a36 --- /dev/null +++ b/doc/design/vscode-extension-commit.md @@ -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` 只保留本约定与设计指针。 diff --git a/doc/design/vscode-extension.md b/doc/design/vscode-extension.md index f266a93..2aa2214 100644 --- a/doc/design/vscode-extension.md +++ b/doc/design/vscode-extension.md @@ -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` — 日常流程 diff --git a/public/README.md b/public/README.md index 14c07bd..0f2b6b8 100644 --- a/public/README.md +++ b/public/README.md @@ -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`。 diff --git a/public/stdlib/00-overview.mq.md b/public/stdlib/00-overview.mq.md index f370e56..d70e673 100644 --- a/public/stdlib/00-overview.mq.md +++ b/public/stdlib/00-overview.mq.md @@ -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. diff --git a/public/stdlib/00-索引.mq.md b/public/stdlib/00-索引.mq.md index 8af3b5f..5c27d25 100644 --- a/public/stdlib/00-索引.mq.md +++ b/public/stdlib/00-索引.mq.md @@ -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。 diff --git a/public/stdlib/subtask.mq.md b/public/stdlib/subtask.mq.md new file mode 100644 index 0000000..ed401cb --- /dev/null +++ b/public/stdlib/subtask.mq.md @@ -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 diff --git a/public/stdlib/writeback.mq.md b/public/stdlib/writeback.mq.md new file mode 100644 index 0000000..44bf8ef --- /dev/null +++ b/public/stdlib/writeback.mq.md @@ -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 `` 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 diff --git a/public/stdlib/子任务.mq.md b/public/stdlib/子任务.mq.md new file mode 100644 index 0000000..f74f1ba --- /dev/null +++ b/public/stdlib/子任务.mq.md @@ -0,0 +1,20 @@ +--- +title: lib/子任务 — 并发子任务 +description: 文件、函数或外联代码并行执行 +> lib/子任务.mq.md +--- + +# main + +`启动`(`spawn`)四选一(其余参数默认 `None`): + +| 参数 | 方式 | `等待` 返回 | +|------|------|-------------| +| `路径=` | `marqdo run` 子进程 | 退出码 | +| `函数=` + 可选 `参数=` | 入口模块中的函数(线程) | 返回值 | +| `代码=` | 外联代码块子进程 | stdout 文本 | +| `语言=` + `源码=` | 外联源码子进程 | stdout 文本 | + +另有:`探测`、`终止`、`等待全部`。父进程结束会终止文件/外联子进程。 + +> 打印 内容=子任务总览就绪 diff --git a/public/stdlib/自写回.mq.md b/public/stdlib/自写回.mq.md new file mode 100644 index 0000000..1cd3620 --- /dev/null +++ b/public/stdlib/自写回.mq.md @@ -0,0 +1,15 @@ +--- +title: lib/自写回 — Jupyter 式写回 +description: 把运行结果写回入口 .mq.md +> lib/自写回.mq.md +--- + +# main + +自写回把结果写入入口文件(你 `run` 的那份 `.mq.md`)里的 `` 块。 + +- `记录 内容=`(`record`)— 默认写在调用下方;`at_end=真` 则在文件末尾单独一块 +- `读取` / `清除` — 读或删相邻块(`at_end` 时指 EOF 块) +- `列表` — 列出文件中所有输出块 + +> 打印 内容=自写回总览就绪 diff --git a/scripts/release-windows.ps1 b/scripts/release-windows.ps1 index 000758c..df30a4a 100644 --- a/scripts/release-windows.ps1 +++ b/scripts/release-windows.ps1 @@ -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)" } diff --git a/src/embedded_lib.rs b/src/embedded_lib.rs new file mode 100644 index 0000000..e46e703 --- /dev/null +++ b/src/embedded_lib.rs @@ -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/` from the embedded tree (e.g. `text.mq.md`). +pub fn read_file(remainder: &str) -> Option { + 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")); + } +} diff --git a/src/lib.rs b/src/lib.rs index f913ef0..d016c7d 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -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; diff --git a/src/load.rs b/src/load.rs index 161f842..62fd6ab 100644 --- a/src/load.rs +++ b/src/load.rs @@ -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) -> Result) -> Result Result { + 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 { + lib_remainder(path).as_deref().and_then(embedded_lib::read_file) +} + +fn lib_remainder(path: &Path) -> Option { + 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 { let rel = rel.replace('\\', "/"); let direct = from_dir.join(&rel); @@ -67,8 +98,11 @@ pub fn resolve_import(from_dir: &Path, rel: &str) -> Result { 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")); + } } diff --git a/src/main.rs b/src/main.rs index 59ef4b5..3e613d1 100644 --- a/src/main.rs +++ b/src/main.rs @@ -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 { } 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) + } } } diff --git a/src/version_check.rs b/src/version_check.rs new file mode 100644 index 0000000..ce6461e --- /dev/null +++ b/src/version_check.rs @@ -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 { + 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 = a + .split('-') + .next() + .unwrap_or(a) + .split('.') + .map(|s| s.parse().unwrap_or(0)) + .collect(); + let pb: Vec = 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); + } +}