diff --git a/.cursor/skills/marqdo-release/SKILL.md b/.cursor/skills/marqdo-release/SKILL.md index 811a8a4..b1bed6e 100644 --- a/.cursor/skills/marqdo-release/SKILL.md +++ b/.cursor/skills/marqdo-release/SKILL.md @@ -4,11 +4,13 @@ description: >- Run a full Marqdo product release: detect latest version and ask the user for the next tag, update CHANGELOG/README/skills/public docs, bump Cargo versions, sync VS Code extension on branch vscode-extension when needed, build or - trigger install assets (CLI, stdlib, ext, public zip, VSIX, wasm notes), push - tag, publish GitHub Release with detailed notes, and recover from network - failures via proxy or HK SSH jump (scripts/push-via-hk-jump.py). Use when the - user asks to release, cut a version, publish vX.Y.Z, ship a GitHub release, - 发版, 发布新版本, or tag marqdo. + trigger install assets (Windows CLI + **required Linux native/CLI zips**, + stdlib, ext, public zip, VSIX), push via origin or + https://proxy.cflmy.top/github.com/cflmy/marqdo.git, publish GitHub Release + with detailed notes, and recover from network failures via that proxy or HK + SSH jump (scripts/push-via-hk-jump.py). Use when the user asks to release, + cut a version, publish vX.Y.Z, ship a GitHub release, 发版, 发布新版本, or tag + marqdo. --- # Marqdo release @@ -22,8 +24,9 @@ Canonical release playbook for **cflmy/marqdo**. Read this skill **before** tagg 3. **Never commit `vscode-extension/` on `main`** (gitignored). Extension source lives only on branch **`vscode-extension`**. See `doc/design/vscode-extension-commit.md`. 4. **Do not release from a dirty tree** (except intentional release commits you create in this flow). 5. **Tag format** is always `vX.Y.Z` matching root `Cargo.toml` `version = "X.Y.Z"`. -6. Prefer **tag push → GitHub Actions** (`.github/workflows/release.yml`) for Windows CLI + VSIX + zips. Local packaging is fallback / verification. -7. After network errors: apply [reference.md § Proxy](reference.md); retry; do not silently skip uploads. If GitHub stays unreachable but **HK jump** (`hk.cflmy.de`) works, use `scripts/push-via-hk-jump.py` (Paramiko CONNECT) — see reference § **HK SSH jump**. +6. Prefer **tag push → GitHub Actions** (`.github/workflows/release.yml`) for **both** Windows and **Linux** install assets. Local packaging is fallback / verification. +7. After network errors: apply [reference.md § Proxy](reference.md). **First try** `https://proxy.cflmy.top/github.com/cflmy/marqdo.git` (this clone’s usual `origin`). Retry; do not silently skip uploads. If the reverse-proxy still drops long pushes, use **HK jump** (`hk.cflmy.de`) via `scripts/push-via-hk-jump.py` — see reference § **Proxy** / **HK SSH jump**. +8. **Do not ship a GitHub Release without the Linux extension/native zip.** Job `linux` must attach `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` (and the Linux CLI bundle). Missing Linux packages = release incomplete. ## Defaults (after version is confirmed) @@ -106,7 +109,16 @@ release: vVER — EOF ``` -Push `main`: `git push origin main` (with proxy/`all` perms if needed; on persistent GitHub failure use [reference § HK SSH jump](reference.md)). +Push `main` (this repo’s `origin` is usually the reverse proxy): + +```bash +# origin typically: https://proxy.cflmy.top/github.com/cflmy/marqdo.git +git push origin main +# one-shot if origin still points at github.com: +git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git HEAD:main +``` + +If that times out: [reference § HK SSH jump](reference.md). ## Phase 3 — VS Code / Cursor extension @@ -127,15 +139,19 @@ git tag -a "TAG" -m "TAG" git push origin "TAG" ``` -This runs `.github/workflows/release.yml` (Windows): CLI exe/zip, stdlib zip, ext zip, source zip, public zip, VSIX. +This runs `.github/workflows/release.yml`: -If tag push fails: [reference.md § Proxy](reference.md), retry once; then report. +- **windows** — CLI exe/zip, stdlib zip, ext zip, source zip, public zip, VSIX, Windows native zip +- **linux** (`needs: windows`) — **required** Linux native plugins zip + Linux CLI bundle (`ext/` + `native/*.so`) + +If tag push fails: [reference.md § Proxy](reference.md) (`proxy.cflmy.top` first), retry once; then HK jump. ## Phase 5 — Release notes & assets -1. Wait for Actions success: `gh run list --workflow=Release --limit 3` / open the run URL. +1. Wait for Actions success: `gh run list --workflow=Release --limit 3` / open the run URL. **Both** `windows` and `linux` jobs must be green. 2. Ensure GitHub Release for `TAG` exists with assets (workflow uses `softprops/action-gh-release`). -3. **Rewrite release body** (workflow body is a stub) with **中英双语** — see [reference.md § Notes template](reference.md). `gh release edit TAG --notes-file …`. +3. Confirm Linux assets exist: `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` and `marqdo-VER-x86_64-unknown-linux-gnu.zip`. If missing, do **not** call the release done — re-run / upload. +4. **Rewrite release body** (workflow body is a stub) with **中英双语** — see [reference.md § Notes template](reference.md). `gh release edit TAG --notes-file …`. 4. Include: Highlights, Breaking, Install (`ext add`, plugins build), Downloads table, WASM (`marqdo wasm build`), links to CHANGELOG/README, extension branch note. 5. Optional Linux local extras (not required if CI green): `marqdo wasm build` smoke; document in notes that wasm is built from source via CLI. @@ -154,11 +170,11 @@ Local Windows fallback: `scripts/release-full.ps1 -Tag TAG -Upload` (see script | Failure | Action | |---------|--------| | `gh` / git TLS or Clash `7890` refused | Unset bad proxy; `required_permissions: ["all"]`; see [reference § Proxy](reference.md) | -| GitHub blocked / `proxy.cflmy.top` push timeout | **HK SSH jump**: `scripts/push-via-hk-jump.py` (ask user for HK password/key; never commit). See reference § **HK SSH jump** | +| GitHub blocked | **`origin` via proxy.cflmy.top** (see below), then HK jump | | Tag exists | Stop; ask user to bump or delete tag (no force on shared tags without explicit order) | | CI red | Fix on main, move tag only if user explicitly allows delete+re-push tag | | VSIX missing | Fetch `vscode-extension`, build locally, `gh release upload TAG dist/*.vsix` | -| Partial assets | Re-run workflow or upload missing files only | +| Linux native/CLI zip missing | Incomplete release — fix `linux` job or `gh release upload`; do not skip | ## Do not diff --git a/.cursor/skills/marqdo-release/reference.md b/.cursor/skills/marqdo-release/reference.md index d080d62..1b7c3b7 100644 --- a/.cursor/skills/marqdo-release/reference.md +++ b/.cursor/skills/marqdo-release/reference.md @@ -25,21 +25,24 @@ gh release list --limit 3 2>/dev/null || true ## Asset matrix (CI tag `v*`) -Produced by `.github/workflows/release.yml` on **windows-latest**: +Produced by `.github/workflows/release.yml` on **windows-latest** (`windows` job) and **ubuntu-latest** (`linux` job, **required**, `needs: windows`): -| Asset | Role | -|-------|------| -| `marqdo-VER-x86_64-pc-windows-msvc.exe` | CLI (stdlib embedded) | -| `marqdo-VER-x86_64-pc-windows-msvc.zip` | `marqdo.exe` + `lib/` | -| `marqdo-VER-stdlib.zip` | `lib/` only | -| `marqdo-VER-ext.zip` | Official `ext/` L1 | -| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Prebuilt Windows plugins (`native/*.dll`) | -| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Prebuilt Linux plugins (`native/lib*.so`) | -| `marqdo-VER-source.zip` | `git archive` of tagged commit | -| `marqdo-VER.vsix` | VS Code / Cursor (from branch `vscode-extension`) | -| `marqdo-VER-public.zip` | Static user docs (`marqdo view output public`) | +| Asset | Role | Job | +|-------|------|-----| +| `marqdo-VER-x86_64-pc-windows-msvc.exe` | CLI (stdlib embedded) | windows | +| `marqdo-VER-x86_64-pc-windows-msvc.zip` | `marqdo.exe` + `lib/` + `ext/` + native DLL | windows | +| `marqdo-VER-stdlib.zip` | `lib/` only | windows | +| `marqdo-VER-ext.zip` | Official `ext/` L1 | windows | +| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Prebuilt Windows plugins (`native/*.dll`) | windows | +| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Prebuilt Linux plugins (`native/lib*.so`) — **must ship** | linux | +| `marqdo-VER-x86_64-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + native `.so` — **must ship** | linux | +| `marqdo-VER-source.zip` | `git archive` of tagged commit | windows | +| `marqdo-VER.vsix` | VS Code / Cursor (from branch `vscode-extension`) | windows | +| `marqdo-VER-public.zip` | Static user docs (`marqdo view output public`) | windows | -Not CI-uploaded (document in notes): Linux/macOS build from source; WASM via `marqdo wasm build` → `dist/wasm/`. +Not CI-uploaded (document in notes): macOS build from source; WASM via `marqdo wasm build` → `dist/wasm/`. + +A release **without** the Linux native zip is incomplete (`marqdo ext add` on Linux cannot download prebuilts). ## Doc sync checklist (Phase 2 detail) @@ -189,7 +192,9 @@ marqdo wasm build | Asset | 内容 / Contents | |-------|-----------------| | `marqdo-*-windows-msvc.exe` | CLI(内置 stdlib) | -| `marqdo-*-windows-msvc.zip` | exe + `lib/` | +| `marqdo-*-windows-msvc.zip` | exe + `lib/` + `ext/`(含 native) | +| `marqdo-*-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + `.so` | +| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`(Win + **Linux 必出**) | | `marqdo-*-stdlib.zip` | 仅 `lib/` | | `marqdo-*-ext.zip` | 官方 `ext/` | | `marqdo-*-source.zip` | 源码快照 | @@ -206,7 +211,32 @@ marqdo wasm build ## Proxy & auth (network recovery) -Symptoms seen in this project: broken local Clash on `127.0.0.1:7890`, flaky `proxy.cflmy.top` HTTPS (short GET OK, long `git push` / connect timeouts), TLS failures, `gh` needing token, Cursor agent sandbox with only `lo`. +Symptoms seen in this project: broken local Clash on `127.0.0.1:7890`, flaky GitHub TLS, `gh` needing token, Cursor agent sandbox with only `lo`. + +### `proxy.cflmy.top` (try this first) + +This machine’s `origin` is typically: + +``` +https://proxy.cflmy.top/github.com/cflmy/marqdo.git +``` + +Push / fetch / tag through that remote (HTTPS reverse proxy to GitHub): + +```bash +git remote -v # confirm origin uses proxy.cflmy.top +git push origin main +git push origin vVER +git push origin vscode-extension + +# one-shot if origin still points at github.com: +git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git HEAD:main +git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git vVER +``` + +Short GETs via the proxy often work; **long `git push` may still time out**. If push hangs or drops, skip Clash retries and go to **HK SSH jump** below. + +`gh` against `api.github.com` may still need a direct path or HK jump (the reverse proxy is for `github.com` git, not always the API). ### Diagnose diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index b6ae797..51f0ba4 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -135,7 +135,8 @@ jobs: |-------|----------| | `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib | | `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` + `ext/`(含 native DLL) | - | `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum` 插件 | + | `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`(Windows DLL + **Linux .so 必出**) | + | `marqdo-*-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + native `.so` | | `marqdo-*-stdlib.zip` | `lib/` only | | `marqdo-*-ext.zip` | Official `ext/` L1 sources | | `marqdo-*-source.zip` | Source snapshot (`git archive`) | @@ -156,8 +157,11 @@ jobs: env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - linux-native: + linux: runs-on: ubuntu-latest + # Wait until Windows has created the GitHub Release, then attach Linux zips + # (required: native plugins for `marqdo ext add` on Linux + CLI bundle). + needs: windows steps: - uses: actions/checkout@v4 @@ -169,28 +173,51 @@ jobs: with: go-version: "1.23.x" - - name: Build official plugins (release) + - name: Install zip + cgo toolchain + run: sudo apt-get update && sudo apt-get install -y zip gcc libc6-dev + + - name: Build Linux CLI + official plugins run: | + set -euo pipefail + cargo build --release cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg bash ./scripts/build-web-plugin.sh - - name: Package native zip + - name: Package Linux native zip + CLI bundle run: | set -euo pipefail VER="${GITHUB_REF_NAME#v}" TARGET="x86_64-unknown-linux-gnu" mkdir -p dist/stage-native/native - cp target/release/libweb.so dist/stage-native/native/libweb.so - cp target/release/libagent.so dist/stage-native/native/libagent.so - cp target/release/libquantum.so dist/stage-native/native/libquantum.so - cp target/release/liblinalg.so dist/stage-native/native/liblinalg.so + for lib in libweb.so libagent.so libquantum.so liblinalg.so; do + src="target/release/${lib}" + if [[ ! -f "$src" && "$lib" == libweb.so ]]; then + src="plugins/web/build/libweb.so" + fi + test -f "$src" || { echo "missing $src" >&2; exit 1; } + cp "$src" "dist/stage-native/native/${lib}" + done (cd dist/stage-native && zip -r "../marqdo-${VER}-native-${TARGET}.zip" .) echo "NATIVE=marqdo-${VER}-native-${TARGET}.zip" >> "$GITHUB_ENV" - - name: Upload Linux native plugins + stage="dist/stage-linux" + rm -rf "$stage" + mkdir -p "$stage/ext/native" "$stage/lib" + cp target/release/marqdo "$stage/marqdo" + chmod +x "$stage/marqdo" + cp -a lib/. "$stage/lib/" + cp -a ext/. "$stage/ext/" + cp dist/stage-native/native/*.so "$stage/ext/native/" + linux_zip="marqdo-${VER}-${TARGET}.zip" + (cd "$stage" && zip -r "../${linux_zip}" .) + echo "LINUX_ZIP=${linux_zip}" >> "$GITHUB_ENV" + + - name: Upload Linux packages uses: softprops/action-gh-release@v2 with: - files: dist/${{ env.NATIVE }} + files: | + dist/${{ env.NATIVE }} + dist/${{ env.LINUX_ZIP }} fail_on_unmatched_files: true env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/CHANGELOG.md b/CHANGELOG.md index 1e7d654..f59b987 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -3,10 +3,19 @@ ## Unreleased ### Added +- **Markup v0.3 运行时闭环**:粗体=`代码`、斜体=`返回`、叙述 `` `名` `` 声明与形参推断为唯一映射;金样 `tests/markup-v03/`。 +- **方括号标记调用**与前置修饰语:`礼貌 [问候] x`;取元主语法 `[键](集合)`(脚注取元过渡保留)。 +- **代码即文档叙述面 G1–G4**:模块级 `---` 跳过、装饰性强调、浮点面量、动态键。 +- **粗体表达式语句** `**n + 1**`;`--dump-lines` 标注 `[decl]/[bold]/[italic]`;`--dump-ast` 显示 inferred 形参与死绑定。 +- **Release Linux 包必出**:`linux` job 上传 `*-native-x86_64-unknown-linux-gnu.zip` 与 Linux CLI bundle。 ### Fixed +- 行首 `` `名`… `` 叙述不再当语句(修复 pages CI:`public/features/16-fs-mid2.mq.md`)。 +- 句中斜体强调(`*very important*` / `*foo.bar*`)不再误收束函数;Decl 名须为标识符;残缺粗体保持 GAP 恢复。 +- 胶合 `` `名`=default …prose `` 为 Decl 而非赋值。 ### Changed +- 教程 / Skill / `lib` / `ext` / `public` 对齐 v0.3 标记;view 推断形参 `chip inferred`。 ## v0.4.0 — 2026-09-13 diff --git a/README.md b/README.md index f82942c..b83dead 100644 --- a/README.md +++ b/README.md @@ -23,24 +23,23 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件, --- -## 语法速览(v0.2) +## 语法速览(v0.3) | 标记 | 含义 | |------|------| -| 无标记行 | 注释(空行分段) | -| `*…*` | 程序语句 | -| `**…**` | **返回值**(架构) | -| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 | +| 无标记行 | 叙述(注释);行内 `` `名` `` 可声明 | +| `**…**` | **代码**(赋值 / 调用 / 表达式) | +| `*…*` | **返回值**(整行、`返回*n*`、或表达式形) | +| `****` / 整行 `**` / `*None*` | **空返回**(`None`),并结束本函数体 | | `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 | | `#` | 对象 / 类型(构造体;`# main` = 入口) | | `##` … | 函数 / 方法(按标题深度嵌套) | | `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) | -| `+` / `1.` … | 函数头下 `` + `名` `` = 形参;体内 `1.` `2.` … = 分支(`N. *` = else) | -| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) `` / `` - [`项`](`集合`) ``) | -| 表格 | 集合 | +| 叙述 `` `名` `` / `` `名`=默认 `` | 形参由体推断(`` + `名` `` 仍可用) | +| `1.` … | 体内 `1.` `2.` … = 分支(`N. *` = else) | +| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) ``) | +| 表格 | 集合;取元优先 `[键](集合)` | | 单独一行 `---` / `***` | **叙述分隔**(跳过;不是函数收束) | -| 空返回 `*None*` / 整行 `**` / `****` | **结束本函数体**并返回 `None` | -| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入) | ```markdown # main @@ -48,16 +47,15 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件, > 问候 谁=World ## 问候 - + `谁` -> print text=Hello `谁`! +向`谁`问好。 +**print text="Hello " + 谁** *None* ## 加一 - + `n` -**`n` + 1** +对于输入变量`n`,执行**n=n+1**接着返回*n*。 ``` 完整约定:[markdown-mapping-v0.3.md](doc/design/markdown-mapping-v0.3.md)。 diff --git a/doc/roadmap/markup-v0.3.md b/doc/roadmap/markup-v0.3.md index b2badd5..1337b57 100644 --- a/doc/roadmap/markup-v0.3.md +++ b/doc/roadmap/markup-v0.3.md @@ -77,7 +77,7 @@ - [x] 更新 `.cursor/skills/marqdo/SKILL.md` 硬规则 - [x] 修订 [markdown-mapping.md](../design/markdown-mapping.md) 为 v0.3 正式正文(或声明由 v0.3 文件接任) - [x] ADR 0005 → **Accepted** -- [ ] CHANGELOG / 发版说明(破坏性:标记对调) +- [ ] CHANGELOG / 发版说明(破坏性:标记对调)— Unreleased 已起草;随下一 tag 发布 **出门:** 全量 gold 默认绿(live LLM 无钥跳过);无 v0.2 双模式。