Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
3287799959 | ||
|
|
f95e5d3339 | ||
|
|
52b4bae423 | ||
|
|
037592087c | ||
|
|
3eb8e732ea | ||
|
|
761b92afce | ||
|
|
b5f43ee993 | ||
|
|
76da97f090 | ||
|
|
7554e45f60 | ||
|
|
6994acb91d | ||
|
|
bccfec86ba | ||
|
|
114fd53cd1 | ||
|
|
c8f41164c5 | ||
|
|
6f303ff957 | ||
|
|
95a49697f7 | ||
|
|
8846f5f070 | ||
|
|
4f09e515ee | ||
|
|
551f4ff322 | ||
|
|
d5a9301c7f | ||
|
|
34915e3b16 | ||
|
|
c55aad775e | ||
|
|
ac3f0633cd | ||
|
|
d55567a634 | ||
|
|
abcb141737 | ||
|
|
8d97adc1dc | ||
|
|
5c37d54070 | ||
|
|
fecaacd5be | ||
|
|
53bc3538da | ||
|
|
0e0655b316 | ||
|
|
5058f5ddcf | ||
|
|
4a1c9c48a2 | ||
|
|
5e74ff39f2 | ||
|
|
b5c07385e9 | ||
|
|
bfb10d172b | ||
|
|
00a77181ef | ||
|
|
e13468dc43 | ||
|
|
d3b137c919 | ||
|
|
e292c8a7c7 | ||
|
|
ce195998c1 | ||
|
|
e20cf8b386 | ||
|
|
c4a726397d | ||
|
|
7fab85b389 | ||
|
|
12d2c7be69 | ||
|
|
26955f4f36 | ||
|
|
56df0736fa | ||
|
|
695939ac74 | ||
|
|
4c06851e0e | ||
|
|
23e4bc406e | ||
|
|
fe18c4d1d6 | ||
|
|
e6fdeb0b31 | ||
|
|
5ec4b3c17d | ||
|
|
6e94d0a179 | ||
|
|
4357045904 | ||
|
|
1ef71d7492 | ||
|
|
1fc985db7e | ||
|
|
364428ca1e | ||
|
|
09b549a862 | ||
|
|
2d238a8c36 | ||
|
|
7a0309284a | ||
|
|
fd3f1724e6 | ||
|
|
ca40c698a2 | ||
|
|
fb6254e501 | ||
|
|
cf9d96477b | ||
|
|
493d0ad91a | ||
|
|
a0e88919a6 | ||
|
|
237962c3be | ||
|
|
1637acce6e | ||
|
|
68c4f8c822 | ||
|
|
784d5ec346 | ||
|
|
955834e453 | ||
|
|
435f36b6e9 | ||
|
|
08c48f3acb | ||
|
|
ff1870cedc | ||
|
|
5e51ee1bb2 | ||
|
|
55f1a37b3d | ||
|
|
58dff0a1e9 | ||
|
|
fc543f1ca5 | ||
|
|
2e068e66d4 | ||
|
|
a4c346d4a2 | ||
|
|
fe14d1f7e3 | ||
|
|
f4b39dfe80 | ||
|
|
7d86ed1d9c | ||
|
|
506de65dae | ||
|
|
08384c7540 | ||
|
|
94ae6713aa | ||
|
|
838a2b425a | ||
|
|
1a5ee57a6f | ||
|
|
d539e6b96b | ||
|
|
3ade036d34 | ||
|
|
f3c49e86ae | ||
|
|
b2401b8458 | ||
|
|
51bb8767e3 | ||
|
|
c0fbe9b182 | ||
|
|
01287d9e7e | ||
|
|
70fb2fbfb2 | ||
|
|
b6f116108c | ||
|
|
03aca7cdac | ||
|
|
96da88e168 | ||
|
|
b6cceab218 | ||
|
|
95b16be714 | ||
|
|
d31ad79bc0 | ||
|
|
5745805a5d | ||
|
|
590f7a58fa | ||
|
|
027b19c5db | ||
|
|
7670673a39 | ||
|
|
824b9bf607 | ||
|
|
155183eb30 | ||
|
|
b10a84466b | ||
|
|
0aa0f47a9d | ||
|
|
5f91be7c21 | ||
|
|
e3e2cfa9d1 | ||
|
|
d1b4e62d4d |
No files matched your search
@@ -63,22 +63,22 @@ Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = tex
|
||||
**Single dynamic key** — one `table.put` (or a helper), not a json chain:
|
||||
|
||||
```markdown
|
||||
*`set_text` = > table.put in=None at="#log" value=msg*
|
||||
**> table.put in=None at="set_text" value=set_text**
|
||||
**`set_text` = table.put in=None at="#log" value=msg**
|
||||
**table.put in=None at="set_text" value=set_text**
|
||||
```
|
||||
|
||||
Better still — call a named helper:
|
||||
|
||||
```markdown
|
||||
**> browser.set_text sel="#log" text=msg**
|
||||
**browser.set_text sel="#log" text=msg**
|
||||
```
|
||||
|
||||
### 3. Bad pattern (do not write)
|
||||
|
||||
```markdown
|
||||
*`ret` = > json.set map=None key="set_text" value=…*
|
||||
*`ret` = > json.set map=ret key="canvas" value=…*
|
||||
*`cmds` = > json.append list=cmds item=c0*
|
||||
**`ret` = json.set map=None key="set_text" value=…**
|
||||
**`ret` = json.set map=ret key="canvas" value=…**
|
||||
**`cmds` = json.append list=cmds item=c0**
|
||||
```
|
||||
|
||||
## Writing application `.mq.md`
|
||||
@@ -88,23 +88,31 @@ Better still — call a named helper:
|
||||
3. `##` handlers: short prose OK; data as tables; return via `browser.*` / `web.*` / one `table.put`.
|
||||
4. Blank line between comment paragraphs and code.
|
||||
5. Run `marqdo run path.mq.md` from repo root.
|
||||
6. **Calls in narrative:** prefer `**结果 = 某函数 名=`x`**` (no `>` on the RHS). Bracket form `礼貌 [问候] "x"` / `**出 = [put] …**` is fine when modifiers help. Use `> …` for standalone step lists. See `examples/code-as-docs/`.
|
||||
7. **Do not use `##` inside `# main` for document sectioning** — those become nested functions. Use paragraphs / `---` breaks instead.
|
||||
8. **Index:** prefer `[键](集合)` / `` [`名`](集合) `` over footnote `` m[^k] ``.
|
||||
|
||||
Browser client programs: prefer `import browser:lib/browser.mq.md` (no native plugin). Server sites: `ext/web` + GFM page/style tables.
|
||||
|
||||
## Developing libraries (`lib/*`, `ext/*`)
|
||||
|
||||
Canonical thin-template + waves: [lib-code-as-docs.md](../../doc/design/lib-code-as-docs.md) · [roadmap/lib-ext-code-as-docs.md](../../doc/roadmap/lib-ext-code-as-docs.md).
|
||||
|
||||
### Goals
|
||||
|
||||
- **Authors** see tables and short calls; **library** may hide `table.put` / host calls.
|
||||
- One concern per helper; name the effect (`set_text`, `canvas`, …), do not expose bag surgery.
|
||||
- EN + ZH pair when shipping user-facing libs (`lib/browser.mq.md` ↔ `lib/浏览器.mq.md`, `ext/web` ↔ `ext/web/网页.mq.md`).
|
||||
- `ext/**` never calls `host_*` — use plugins / public lib only (`doc/design/ext-agent.md`).
|
||||
- Collection get: **`[key](coll)`** (no new footnote indexes). Calls in examples may use `修饰 [fn] …` or classic `>` / bold.
|
||||
|
||||
### Library checklist
|
||||
|
||||
- [ ] Purpose sentence + prose params + one example + short body
|
||||
- [ ] Public examples use **tables + helpers**, not json glue
|
||||
- [ ] Index with `[k](c)`; foreach `- [item](coll)`
|
||||
- [ ] Helpers documented with a one-line purpose above `##`
|
||||
- [ ] Defaults on `+` params; omit `None` fields in merged maps
|
||||
- [ ] Defaults on params; omit `None` fields in merged maps
|
||||
- [ ] No `json.set` chains in new code — use `table.put` / `table.merge` / GFM
|
||||
- [ ] `marqdo run` on a tiny demo under `examples/` or inline smoke
|
||||
|
||||
|
||||
@@ -4,10 +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. 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
|
||||
@@ -21,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.
|
||||
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)
|
||||
|
||||
@@ -105,7 +109,16 @@ release: vVER — <one-line highlight>
|
||||
EOF
|
||||
```
|
||||
|
||||
Push `main`: `git push origin main` (with proxy/`all` perms if needed).
|
||||
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
|
||||
|
||||
@@ -126,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.
|
||||
|
||||
@@ -152,11 +169,12 @@ Local Windows fallback: `scripts/release-full.ps1 -Tag TAG -Upload` (see script
|
||||
|
||||
| Failure | Action |
|
||||
|---------|--------|
|
||||
| `gh` / git TLS or proxy `7890` refused | Unset bad proxy; use working `HTTP(S)_PROXY` or `required_permissions: ["all"]`; see reference |
|
||||
| `gh` / git TLS or Clash `7890` refused | Unset bad proxy; `required_permissions: ["all"]`; see [reference § Proxy](reference.md) |
|
||||
| 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
|
||||
|
||||
|
||||
@@ -25,19 +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-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)
|
||||
|
||||
@@ -164,7 +169,7 @@ git checkout vVER
|
||||
cargo build --release
|
||||
./target/release/marqdo version
|
||||
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
|
||||
marqdo ext add web && marqdo ext add agent && marqdo ext add quantum
|
||||
# 中文 id:网页 / 智能体 / 量子
|
||||
```
|
||||
@@ -187,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` | 源码快照 |
|
||||
@@ -204,14 +211,41 @@ marqdo wasm build
|
||||
|
||||
## Proxy & auth (network recovery)
|
||||
|
||||
Symptoms seen in this project: broken local proxy on `127.0.0.1:7890`, TLS failures, `gh` needing token, Cursor sandbox blocking git/gh.
|
||||
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
|
||||
|
||||
```bash
|
||||
env | grep -iE 'proxy|PROXY' || true
|
||||
curl -sI https://github.com | head -5
|
||||
curl -sI --max-time 15 https://github.com | head -5
|
||||
curl -sS --max-time 15 -o /dev/null -w 'proxy=%{http_code}\n' https://proxy.cflmy.top/ || true
|
||||
gh auth status
|
||||
ip -br addr | head -5 # agent may lack enp*; use required_permissions: ["all"]
|
||||
```
|
||||
|
||||
### Fix order
|
||||
@@ -220,6 +254,7 @@ gh auth status
|
||||
|
||||
```bash
|
||||
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy
|
||||
# also clear for one git call: git -c http.proxy= -c https.proxy= …
|
||||
```
|
||||
|
||||
2. **Set a working proxy** only if the user provides one (or known working):
|
||||
@@ -235,13 +270,15 @@ export HTTP_PROXY=http://HOST:PORT
|
||||
|
||||
5. **Git remote**: prefer `https://github.com/cflmy/marqdo.git`; SSH needs keys.
|
||||
|
||||
6. **Partial upload**:
|
||||
6. **HK SSH jump (preferred when GitHub is blocked but HK is reachable)** — see next subsection.
|
||||
|
||||
7. **Partial upload**:
|
||||
|
||||
```bash
|
||||
gh release upload "vVER" dist/FILE --clobber
|
||||
```
|
||||
|
||||
7. **Re-run CI** without retagging (if tag already correct):
|
||||
8. **Re-run CI** without retagging (if tag already correct):
|
||||
|
||||
```bash
|
||||
gh workflow run Release --ref "vVER" # only if workflow_dispatch exists; else fix + new patch tag
|
||||
@@ -249,6 +286,43 @@ gh workflow run Release --ref "vVER" # only if workflow_dispatch exists; else f
|
||||
|
||||
Current Release workflow is **tag-push only**. Red CI after tag → fix on `main`, then either new patch tag or **user-approved** delete+recreate tag (dangerous; prefer patch).
|
||||
|
||||
### HK SSH jump (Paramiko CONNECT)
|
||||
|
||||
**When to use:** local → GitHub fails (timeout / TLS / Clash flaky / reverse-proxy `proxy.cflmy.top` connect drops), but this host can reach an overseas box that has stable GitHub (default `hk.cflmy.de`). Proven path for v0.3.9 push/tag/`gh`.
|
||||
|
||||
**Do not** rely on OpenSSH + `sshpass` here — password auth has hung; use **Paramiko** (`python3-paramiko`).
|
||||
|
||||
**Never** commit the HK root password or tokens. Ask the user for the password (or a key), put it in env / a `600` temp file, scrub after.
|
||||
|
||||
```bash
|
||||
# one-shot password file (example — use the secret the user gave this session)
|
||||
printf '%s' "$HK_PASSWORD_FROM_USER" > /tmp/.hk_ssh_pw && chmod 600 /tmp/.hk_ssh_pw
|
||||
|
||||
export HK_SSH_HOST=hk.cflmy.de # or 83.229.126.119
|
||||
export HK_SSH_USER=root
|
||||
export HK_SSH_PASSWORD_FILE=/tmp/.hk_ssh_pw
|
||||
# optional: HK_JUMP_PORT=18081
|
||||
|
||||
SCRIPT=.cursor/skills/marqdo-release/scripts/push-via-hk-jump.py
|
||||
|
||||
# push / tag / extension (git gets CONNECT proxy + github.com askpass)
|
||||
python3 "$SCRIPT" -- git push origin main
|
||||
python3 "$SCRIPT" -- git push origin vscode-extension
|
||||
python3 "$SCRIPT" -- git push origin vVER
|
||||
|
||||
# gh (sets GH_TOKEN from git credential fill if unset)
|
||||
python3 "$SCRIPT" -- gh release edit vVER --notes-file /tmp/notes.md
|
||||
python3 "$SCRIPT" -- gh run list --workflow=Release --limit 3
|
||||
|
||||
# leave proxy up for manual commands
|
||||
python3 "$SCRIPT" --serve # then: export https_proxy=http://127.0.0.1:18081
|
||||
|
||||
rm -f /tmp/.hk_ssh_pw
|
||||
```
|
||||
|
||||
Script behavior: SSH to HK → local `http://127.0.0.1:$HK_JUMP_PORT` HTTP CONNECT via `direct-tcpip` → run `git`/`gh`/`curl` with that proxy. Git auth uses local `git credential` via `http.extraHeader` (Basic) — **not** `GIT_ASKPASS` (askpass has hung under agent/no TTY). Tokens never go to the jump host disk.
|
||||
|
||||
Optional path reverse-proxy (`https://proxy.cflmy.top/github.com/…` `insteadOf`) may work for short GETs; treat long `git push` failures as a signal to use the HK jump instead of retrying Clash forever.
|
||||
## Local Windows fallback
|
||||
|
||||
```powershell
|
||||
|
||||
+284
@@ -0,0 +1,284 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Push / run git|gh through an HK SSH jump host (Paramiko HTTP CONNECT).
|
||||
|
||||
When this machine cannot reach GitHub reliably but can SSH to a host that can
|
||||
(e.g. hk.cflmy.de), open a local HTTP CONNECT proxy over Paramiko and run the
|
||||
remaining command with http(s).proxy pointed at it.
|
||||
|
||||
Why Paramiko: OpenSSH/`sshpass` has hung on password auth in this environment;
|
||||
Paramiko password + direct-tcpip works.
|
||||
|
||||
Credentials (never commit):
|
||||
HK_SSH_PASSWORD password string
|
||||
HK_SSH_PASSWORD_FILE file containing password (mode 600 recommended)
|
||||
or SSH key via Paramiko agent/keys if password unset and key works
|
||||
|
||||
Optional env:
|
||||
HK_SSH_HOST default hk.cflmy.de
|
||||
HK_SSH_USER default root
|
||||
HK_JUMP_PORT default 18081 (local CONNECT listen)
|
||||
|
||||
Usage:
|
||||
HK_SSH_PASSWORD_FILE=/tmp/hk.pw \\
|
||||
python3 .cursor/skills/marqdo-release/scripts/push-via-hk-jump.py -- \\
|
||||
git push origin main
|
||||
|
||||
# keep proxy only (Ctrl+C to stop)
|
||||
... push-via-hk-jump.py --serve
|
||||
|
||||
# wrap gh
|
||||
... push-via-hk-jump.py -- gh release view v0.3.9
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import os
|
||||
import select
|
||||
import socket
|
||||
import socketserver
|
||||
import subprocess
|
||||
import sys
|
||||
import threading
|
||||
import time
|
||||
from pathlib import Path
|
||||
|
||||
try:
|
||||
import paramiko
|
||||
except ImportError as e: # pragma: no cover
|
||||
raise SystemExit(
|
||||
"paramiko required: apt install python3-paramiko (or pip install paramiko)"
|
||||
) from e
|
||||
|
||||
ROOT = Path(__file__).resolve().parents[4]
|
||||
|
||||
|
||||
class _Server(socketserver.ThreadingMixIn, socketserver.TCPServer):
|
||||
allow_reuse_address = True
|
||||
daemon_threads = True
|
||||
|
||||
|
||||
def load_password() -> str | None:
|
||||
path = os.environ.get("HK_SSH_PASSWORD_FILE")
|
||||
if path:
|
||||
return Path(path).read_text(encoding="utf-8").strip()
|
||||
pw = os.environ.get("HK_SSH_PASSWORD")
|
||||
return pw.strip() if pw else None
|
||||
|
||||
|
||||
def connect_hk() -> paramiko.SSHClient:
|
||||
host = os.environ.get("HK_SSH_HOST", "hk.cflmy.de")
|
||||
user = os.environ.get("HK_SSH_USER", "root")
|
||||
pw = load_password()
|
||||
client = paramiko.SSHClient()
|
||||
client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
|
||||
kwargs: dict = {
|
||||
"hostname": host,
|
||||
"username": user,
|
||||
"timeout": 20,
|
||||
"auth_timeout": 25,
|
||||
"banner_timeout": 25,
|
||||
}
|
||||
if pw:
|
||||
kwargs.update(password=pw, allow_agent=False, look_for_keys=False)
|
||||
else:
|
||||
kwargs.update(allow_agent=True, look_for_keys=True)
|
||||
print(f"== HK jump {user}@{host} ==", flush=True)
|
||||
client.connect(**kwargs)
|
||||
_, stdout, stderr = client.exec_command(
|
||||
"hostname; curl -sS --max-time 20 -o /dev/null -w gh=%{http_code} https://github.com/; echo"
|
||||
)
|
||||
out = stdout.read().decode()
|
||||
err = stderr.read().decode()
|
||||
print(out, end="" if out.endswith("\n") else "\n", flush=True)
|
||||
if err.strip():
|
||||
print(err, file=sys.stderr, flush=True)
|
||||
return client
|
||||
|
||||
|
||||
def make_proxy(transport: paramiko.Transport, port: int) -> _Server:
|
||||
class Handler(socketserver.StreamRequestHandler):
|
||||
def handle(self) -> None:
|
||||
try:
|
||||
first = self.rfile.readline(65536)
|
||||
if not first:
|
||||
return
|
||||
parts = first.decode("latin1", "replace").split()
|
||||
if len(parts) < 2 or parts[0].upper() != "CONNECT":
|
||||
self.wfile.write(b"HTTP/1.1 405 Method Not Allowed\r\n\r\n")
|
||||
return
|
||||
while True:
|
||||
line = self.rfile.readline(65536)
|
||||
if line in (b"\r\n", b"\n", b""):
|
||||
break
|
||||
host, _, port_s = parts[1].partition(":")
|
||||
chan = transport.open_channel(
|
||||
"direct-tcpip",
|
||||
(host, int(port_s or "443")),
|
||||
self.connection.getpeername(),
|
||||
)
|
||||
self.wfile.write(b"HTTP/1.1 200 Connection Established\r\n\r\n")
|
||||
sock = self.connection
|
||||
sock.setblocking(False)
|
||||
chan.setblocking(False)
|
||||
try:
|
||||
while True:
|
||||
r, _, x = select.select([sock, chan], [], [sock, chan], 120)
|
||||
if x:
|
||||
break
|
||||
if sock in r:
|
||||
data = sock.recv(65536)
|
||||
if not data:
|
||||
break
|
||||
chan.sendall(data)
|
||||
if chan in r:
|
||||
data = chan.recv(65536)
|
||||
if not data:
|
||||
break
|
||||
sock.sendall(data)
|
||||
finally:
|
||||
try:
|
||||
chan.close()
|
||||
except Exception:
|
||||
pass
|
||||
except Exception:
|
||||
pass
|
||||
|
||||
return _Server(("127.0.0.1", port), Handler)
|
||||
|
||||
|
||||
def github_basic_auth_header() -> str:
|
||||
"""Authorization: Basic … from local git credential store (no askpass; askpass can hang)."""
|
||||
import base64
|
||||
|
||||
out = subprocess.check_output(
|
||||
["git", "credential", "fill"],
|
||||
input=b"protocol=https\nhost=github.com\n\n",
|
||||
).decode()
|
||||
data = dict(line.split("=", 1) for line in out.splitlines() if "=" in line)
|
||||
user = data.get("username") or "x-access-token"
|
||||
password = data.get("password") or ""
|
||||
if not password:
|
||||
raise SystemExit("no github.com credential in git credential store")
|
||||
token = base64.b64encode(f"{user}:{password}".encode()).decode()
|
||||
return f"Authorization: Basic {token}"
|
||||
|
||||
|
||||
def github_token() -> str | None:
|
||||
out = subprocess.check_output(
|
||||
["git", "credential", "fill"],
|
||||
input=b"protocol=https\nhost=github.com\n\n",
|
||||
).decode()
|
||||
data = dict(line.split("=", 1) for line in out.splitlines() if "=" in line)
|
||||
return data.get("password") or None
|
||||
|
||||
|
||||
def run_with_proxy(proxy: str, argv: list[str]) -> int:
|
||||
env = os.environ.copy()
|
||||
for k in (
|
||||
"http_proxy",
|
||||
"https_proxy",
|
||||
"HTTP_PROXY",
|
||||
"HTTPS_PROXY",
|
||||
"ALL_PROXY",
|
||||
"all_proxy",
|
||||
):
|
||||
env.pop(k, None)
|
||||
|
||||
cmd = list(argv)
|
||||
if cmd and cmd[0] == "git":
|
||||
# Prefer http.extraHeader over GIT_ASKPASS (askpass has hung under agent/no TTY).
|
||||
# Do not also set env http_proxy for git — only -c (avoids double-proxy quirks).
|
||||
auth = github_basic_auth_header()
|
||||
cmd = [
|
||||
"git",
|
||||
"-c",
|
||||
f"http.proxy={proxy}",
|
||||
"-c",
|
||||
f"https.proxy={proxy}",
|
||||
"-c",
|
||||
"credential.helper=",
|
||||
"-c",
|
||||
f"http.extraHeader={auth}",
|
||||
"-c",
|
||||
"http.version=HTTP/1.1",
|
||||
"-c",
|
||||
"http.postBuffer=524288000",
|
||||
*cmd[1:],
|
||||
]
|
||||
print(
|
||||
"+",
|
||||
" ".join(
|
||||
c if not str(c).startswith("http.extraHeader=") else "http.extraHeader=<redacted>"
|
||||
for c in cmd
|
||||
),
|
||||
flush=True,
|
||||
)
|
||||
return subprocess.call(cmd, cwd=ROOT, env=env)
|
||||
|
||||
env["http_proxy"] = proxy
|
||||
env["https_proxy"] = proxy
|
||||
env["HTTP_PROXY"] = proxy
|
||||
env["HTTPS_PROXY"] = proxy
|
||||
|
||||
if cmd and cmd[0] == "gh" and not env.get("GH_TOKEN"):
|
||||
tok = github_token()
|
||||
if tok:
|
||||
env["GH_TOKEN"] = tok
|
||||
|
||||
print("+", " ".join(cmd), flush=True)
|
||||
return subprocess.call(cmd, cwd=ROOT, env=env)
|
||||
|
||||
|
||||
def main(argv: list[str]) -> int:
|
||||
args = argv[1:]
|
||||
if not args or args[0] in ("-h", "--help"):
|
||||
print(__doc__)
|
||||
return 0 if args else 1
|
||||
|
||||
serve_only = args == ["--serve"]
|
||||
if args[0] == "--":
|
||||
args = args[1:]
|
||||
if not serve_only and not args:
|
||||
print("missing command after --", file=sys.stderr)
|
||||
return 2
|
||||
|
||||
port = int(os.environ.get("HK_JUMP_PORT", "18081"))
|
||||
client = connect_hk()
|
||||
transport = client.get_transport()
|
||||
assert transport is not None
|
||||
server = make_proxy(transport, port)
|
||||
threading.Thread(target=server.serve_forever, daemon=True).start()
|
||||
proxy = f"http://127.0.0.1:{port}"
|
||||
print(f"== CONNECT proxy {proxy} ==", flush=True)
|
||||
# smoke
|
||||
subprocess.call(
|
||||
[
|
||||
"curl",
|
||||
"-sS",
|
||||
"--connect-timeout",
|
||||
"10",
|
||||
"--max-time",
|
||||
"25",
|
||||
"--proxy",
|
||||
proxy,
|
||||
"-o",
|
||||
"/dev/null",
|
||||
"-w",
|
||||
"github=%{http_code}\\n",
|
||||
"https://github.com/",
|
||||
]
|
||||
)
|
||||
|
||||
try:
|
||||
if serve_only:
|
||||
print("serving; Ctrl+C to stop", flush=True)
|
||||
while transport.is_active():
|
||||
time.sleep(5)
|
||||
return 1
|
||||
return run_with_proxy(proxy, args)
|
||||
finally:
|
||||
server.shutdown()
|
||||
client.close()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main(sys.argv))
|
||||
@@ -4,17 +4,18 @@ description: >-
|
||||
Author and edit Marqdo programs (.mq.md): Markdown markers are executable
|
||||
syntax (functions, calls, statements, returns, control flow). Use when writing
|
||||
or modifying .mq.md files, teaching Marqdo, generating Marqdo from prose,
|
||||
importing lib/* or ext/web or ext/quantum, running marqdo CLI, building dynamic
|
||||
sites with ext/web, quantum circuits with ext/quantum, or when the user
|
||||
mentions Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, or
|
||||
quantum/量子 extension.
|
||||
importing lib/* or ext/web or ext/quantum or ext/linalg, running marqdo CLI,
|
||||
building dynamic sites with ext/web, quantum circuits with ext/quantum,
|
||||
formula-first linear algebra with ext/linalg, or when the user mentions
|
||||
Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, quantum/量子,
|
||||
or linalg/线性代数 extension.
|
||||
---
|
||||
|
||||
# Marqdo development
|
||||
|
||||
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
|
||||
|
||||
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
Canonical design (repo): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-mapping-v0.3.md) (**v0.3 · runtime**), `doc/design/keywords.md`. Legacy v0.2 notes: `doc/design/markdown-mapping.md` (historical). Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
|
||||
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
|
||||
|
||||
@@ -23,19 +24,19 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
|
||||
## Hard rules (do not violate)
|
||||
|
||||
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
|
||||
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
|
||||
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
|
||||
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are **variables** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
|
||||
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
|
||||
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division.
|
||||
8. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
|
||||
2. **`**…**` = code** (assign / call). **`*…*` = return value**. Output is **not** either marker — use `> print text=…` / `**print text="…"**` / `> 打印 内容=…`.
|
||||
3. **Prose:** unmarked narrative may contain `` `名` `` (declare/ref), inline `**code**`, and `*return*`. Soft Markdown emphasis that is **not** code-shaped (`**说明**`, mid-line `*only*`) is ignored — see [code-as-docs-gaps.md](../../doc/design/code-as-docs-gaps.md). Dead `` `名` `` (never read) is OK and does not become a param.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**. Params: prefer prose `` `名` `` / `` `名`=默认 `` (inferred); `` + `名` `` still accepted.
|
||||
5. **Identifiers:** `` `名` `` in prose; inside `*…*` / `**…**`, bare ids are **variables**. **Text literals must be quoted** in bold/italic: `**print text="hi"**`. Standalone `>` calls: bare words = text; vars need ticks: `` > str `n` ``.
|
||||
6. **Structure lines** (`#` `>` `+` `-` `|` `1.`) need not be wrapped in bold.
|
||||
7. **Paths:** In bare expressions `/` is division. In call args / defaults / table cells, unspaced `a/b` and quoted paths are text.
|
||||
8. Prefer ending side-effect-only bodies with `*None*` / `*无*` / whole-line `**` / `****` when the next lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped everywhere), not function end.
|
||||
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
|
||||
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
|
||||
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug.
|
||||
12. **Bracket-marked calls:** Function name may be marked with `[函数名]`; bare words before `[` are boolean modifiers (`礼貌 [问候] x` → `礼貌=True`). `]` immediately followed by `(` is **index** `[key](coll)`, not a call. Prefer `[k](c)` over footnote index in new code. See [bracket-call-modifiers.md](../../doc/design/bracket-call-modifiers.md).
|
||||
|
||||
|
||||
## Markup → meaning (v0.2)
|
||||
## Markup → meaning (v0.3)
|
||||
|
||||
| Marker | Meaning |
|
||||
|--------|---------|
|
||||
@@ -46,15 +47,17 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
|
||||
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
|
||||
| Line `N. *` | Else arm |
|
||||
| `> fn args` | Call (named `k=v` or positional) |
|
||||
| `修饰 [fn] args` | Bracket-marked call; leading words → `名=True` |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
|
||||
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
|
||||
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
|
||||
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `****` or `**` + spaces + `**` | Return `None` and end function body |
|
||||
| Lone `---` / `***` in function body | End function body (no value) |
|
||||
| GFM table after empty RHS bind | Collection (1-col list / ≥2-col map / `@`·`行`·`row` → list of maps); `` `x`[^1] `` / `` `m`[^key] `` |
|
||||
| `**…**` | **Code** (assign / call) — closing `**` touches last token; bare ids are variables; quote text literals |
|
||||
| `*…*` | **Return value** — closing `*` touches last token; bare ids are variables |
|
||||
| `****` / whole-line `**` / `*None*` | Return `None` and end function body |
|
||||
| Lone `---` / `***` | Markdown thematic break (skip; not function end) |
|
||||
| GFM table after empty RHS bind | Collection; get with `[key](coll)` (preferred) or legacy `` `m`[^key] `` |
|
||||
| `- [item](coll)` | Foreach (unchanged) |
|
||||
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
|
||||
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
|
||||
| Unmarked prose | Comment |
|
||||
@@ -89,27 +92,28 @@ Chinese builtins (same functions, no import):
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
*None*
|
||||
```
|
||||
|
||||
- Call: `> name key=value` or `> name value`.
|
||||
- Nested helpers use deeper `#` (`##`, `###`, …).
|
||||
- After a helper with only side effects, end with `---` / `***`.
|
||||
- After a helper with only side effects, end with `*None*` / whole-line `**` / `****` when later lines must stay in the outer function. Lone `---` is only a thematic break (skipped).
|
||||
- In bold assigns, prefer bare calls: `**摘要 = 结账摘要 …**` (omit `>`).
|
||||
|
||||
## Statements, returns, branches
|
||||
|
||||
```markdown
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
**x = 1**
|
||||
**y = x + 2**
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
*n + 1*
|
||||
```
|
||||
|
||||
```markdown
|
||||
*n = 0*
|
||||
**n = 0**
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
@@ -132,22 +136,36 @@ import clock:lib/time.mq.md
|
||||
|
||||
# main
|
||||
|
||||
*xs = > text.split value="a,b,c" sep=","*
|
||||
**xs = > text.str_split s="a,b,c" sep=","**
|
||||
> print text=`xs`
|
||||
*t = > clock.now_unix*
|
||||
**t = > clock.now_unix**
|
||||
```
|
||||
|
||||
- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages).
|
||||
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
|
||||
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
|
||||
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — document-driven agents: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)); **`ext/web`** — dynamic sites (W0–W7 + P3 complete; see below); **`ext/quantum`** — circuits + Q7 density/viz + Q8 themed SVG (see below).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum|linalg` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below); **`ext/linalg`** — formula-first linear algebra (see below).
|
||||
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
|
||||
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`).
|
||||
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
|
||||
Stdlib map: [reference.md](reference.md).
|
||||
|
||||
## Official extension: `ext/agent` (document-driven)
|
||||
|
||||
Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --release -p marqdo_plugin_agent`.
|
||||
|
||||
**Constitution (do not dilute):**
|
||||
|
||||
1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag.
|
||||
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
|
||||
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only.
|
||||
|
||||
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import).
|
||||
|
||||
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
|
||||
|
||||
## Official extension: `ext/web` (dynamic sites)
|
||||
|
||||
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin first: `cargo build --release -p marqdo_plugin_web`.
|
||||
@@ -162,7 +180,7 @@ Import **one language file** — never mix EN/ZH API names in the same `.mq.md`:
|
||||
- Authors use **GFM tables + `#` classes** — no `json.parse` / `json.set` glue, no hand-built part JSON.
|
||||
- Table cells stay **literal strings**; path text like `` `posts`.`title` `` is resolved by web classes.
|
||||
- **Quote path/MIME cells** that contain `/` (T5 cell expressions treat bare `/` as division): `"/static/logo.svg"`, `"image/png"`.
|
||||
- **`ext/**` never calls `host_*`** — hot path is native `plugins/web` ABI.
|
||||
- **`ext/**` never calls `host_*`** — hot path is native `plugins/web` ABI (default **Go `libweb`**, build via `scripts/build-web-plugin.sh`).
|
||||
- HTTPS: terminate at reverse proxy; set `cookie_secure=True` on auth (no in-process TLS).
|
||||
|
||||
**Typical layout:**
|
||||
@@ -181,7 +199,7 @@ data/ # sqlite runtime (gitignore)
|
||||
|
||||
**Typical flow:** `db.init` → `page.compose_*` → `app` + `static` / `listen`. Client: `marqdo wasm build -o static` + `web.client_embed source="/static/client.mq.md"` — **no author JS**; bridge may implement rich host effects ([browser-wasm-e.md](../../doc/roadmap/browser-wasm-e.md) · [browser-app](../../examples/browser-app/)).
|
||||
|
||||
**Shipped surface (W0–W7 + P3 + W8 + route D mount):** middleware + JSON API (`app.configure`); transactions, pagination, FTS search (`db.migrate`, `db.fts`, `db.search`); security (argon2, CSRF, SQLite sessions, login rate limit); SEO / RSS / Markdown (`page.meta`, `route_rss`, `lib/net.markdown_parse`); upload / download / gallery; sitemap / robots / error pages / redirects; RBAC (`app.gate`, user `role`); audit timestamps + FK in `db.init`; ETag on downloads; **W8** site icons (`app.icons` → `/favicon.ico`), head resource tables (`page.head`), image assembly (`make_images` / `page.images`); **D** `client_embed` auto-mount + DOM effect helpers (`text_patch` / `dom_patch`).
|
||||
**Shipped surface (W0–W7 + P3 + W8 + route D mount):** middleware + JSON API (`app.configure`); transactions, pagination, FTS search (`db.migrate`, `db.fts`, `db.search`); security (argon2, CSRF, SQLite sessions, login rate limit); SEO / RSS / Markdown (`page.meta`, `route_rss`, `lib/net.markdown_parse`); upload / download / gallery; sitemap / robots / error pages / redirects; RBAC (`app.gate`, user `role`); audit timestamps + FK in `db.init`; ETag on downloads; **W8** site icons (`app.icons` → `/favicon.ico`), head resource tables (`page.head`), image assembly (`make_images` / `page.images`); **表驱动引言** `page.compose_intro` / `页面.引言装配`(属性/值/样式表 → `.main-intro`,避免手写 HTML 字符串);**D** `client_embed` auto-mount + DOM effect helpers (`text_patch` / `dom_patch`).
|
||||
|
||||
Design: [ext-web.md](../../doc/design/ext-web.md) · assets: [web-assets-and-images.md](../../doc/design/web-assets-and-images.md) · capability matrix: [web-net-capabilities.md](../../doc/design/web-net-capabilities.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/) · client: [examples/web-client-site/](../../examples/web-client-site/).
|
||||
|
||||
@@ -211,6 +229,19 @@ Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --relea
|
||||
|
||||
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
|
||||
|
||||
## Official extension: `ext/linalg` (formula-first LA)
|
||||
|
||||
Install: `marqdo ext add linalg` (ZH id: `线性代数`). Build: `cargo build --release -p marqdo_plugin_linalg`, then **`marqdo ext add linalg` again** so view loads the new native lib.
|
||||
|
||||
- EN: `import la:ext/linalg/linalg.mq.md`
|
||||
- ZH: `导入 la:ext/linalg/线性代数.mq.md`
|
||||
|
||||
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; prefer top-level `la.symbol` (not `matrix.symbol` without a receiver); quote `kind=` strings; dense `explicit` / factorize obey size guards.
|
||||
|
||||
APIs (EN): `symbol` → `# matrix`;中缀 `+`/`-`/`*`;方法 `` `A`.T `` / ``.simplify`` / ``.ascii`` · `from_formula` / `explicit` / `factorize` / `draw` · `lstsq` / `norm` / `cond` / `rank`.
|
||||
|
||||
Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../../examples/linalg-least-squares/). Design: [ext-linalg.md](../../doc/design/ext-linalg.md) · formula-doc: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
|
||||
|
||||
## AI authoring workflow
|
||||
|
||||
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
@@ -229,7 +260,7 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
|
||||
| `* > print text=hi *` | `> print text=hi` |
|
||||
| `` *`a` = 1 * `` (trailing space + backticks) | `*a = 1*` — bare bind, no trailing space before `*` / `**` |
|
||||
| `*xs = > text.split value=a,b sep=,*` (bare text args) | `*xs = > text.split value="a,b" sep=","*` — quote text literals; bare words are variables |
|
||||
| Forgetting `---` after nested `##` helper | Add `---` / `***` / `****` |
|
||||
| Forgetting empty return after nested `##` helper when outer continues | Add `*None*` / `**` / `****` (not `---`) |
|
||||
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
|
||||
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
|
||||
| `json.set` / `json.append` to build maps or lists | GFM tables; sparse `table.put`; named helpers (`browser.*`, `web.*`) |
|
||||
@@ -238,7 +269,8 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
|
||||
| Mix `web.page` and `网页.页面` in one file | One import language per `.mq.md` |
|
||||
| Call `host_web_*` from `ext/web` | Use `# app` / `# db` methods; plugin ABI only |
|
||||
| Call `host_*` from `ext/quantum` | Use `# circuit` / `# density` methods; plugin ABI only |
|
||||
| Bare `kind=hinton` inside `*…*` | `kind="hinton"` — quote text literals |
|
||||
| Call `host_*` from `ext/linalg` | Use `la.*` L1 wrappers; plugin ABI only |
|
||||
| Bare `kind=eig` inside `*…*` | `kind="eig"` — quote text literals |
|
||||
| Bare `theme=dark` inside `*…*` | `theme="dark"` — quote; ZH `主题="dark"` |
|
||||
| Rebuild plugin but skip `ext add` | `cargo build -p marqdo_plugin_quantum` then `marqdo ext add quantum` (or set `MARQDO_QUANTUM_PLUGIN`) |
|
||||
|
||||
@@ -248,7 +280,7 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
|
||||
- [ ] Print via `print` / `打印`, not bold
|
||||
- [ ] Blank lines separate comment paragraphs from code
|
||||
- [ ] `# main` exists when the file is an entry program
|
||||
- [ ] Nested functions ended with `---` / `***` / `****` when needed
|
||||
- [ ] Nested side-effect helpers ended with `*None*` / `**` / `****` when the outer function continues
|
||||
- [ ] Imports and call names share the same language file
|
||||
- [ ] Data shaped as **GFM tables** (or short helpers) — no `json.set` / `json.append` glue
|
||||
- [ ] Web sites: tables + web classes only (no JSON glue); `data/` gitignored
|
||||
|
||||
@@ -1,5 +1,7 @@
|
||||
# Marqdo examples (AI)
|
||||
|
||||
v0.3: `**…**` = code (assign / call); `*…*` = return. Prefer `[key](coll)` over footnote get. Bracket calls: `礼貌 [问候] x`.
|
||||
|
||||
## 1. Hello (English)
|
||||
|
||||
```markdown
|
||||
@@ -16,7 +18,7 @@
|
||||
> 打印 内容=你好,世界!
|
||||
```
|
||||
|
||||
## 3. Function + named call + body end
|
||||
## 3. Function + named call + empty return
|
||||
|
||||
```markdown
|
||||
# main
|
||||
@@ -30,22 +32,24 @@ Greeting via a nested function:
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
*None*
|
||||
```
|
||||
|
||||
Or end with a whole-line empty bold return: `**` / `****`. Lone `---` is a thematic break (skipped), not function end.
|
||||
|
||||
## 4. Bindings and return
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*a = 2*
|
||||
*b = > add_one n=`a`*
|
||||
> print text=`b`
|
||||
**a = 2**
|
||||
**b = add_one n=`a`**
|
||||
**打印 内容=`b`**
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
*n + 1*
|
||||
```
|
||||
|
||||
## 5. Branch with else
|
||||
@@ -53,7 +57,7 @@ Greeting via a nested function:
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*n = 0*
|
||||
**n = 0**
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
@@ -78,8 +82,7 @@ Greeting via a nested function:
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
|
||||
## 6b. Map table + footnote get
|
||||
## 6b. Map table + link-index get
|
||||
|
||||
```markdown
|
||||
# main
|
||||
@@ -90,13 +93,20 @@ Greeting via a nested function:
|
||||
|------|------|
|
||||
| 水果 | 蔬菜 |
|
||||
|
||||
*种 = 分类[^苹果]*
|
||||
> print text=`种`
|
||||
**种 = [苹果](分类)**
|
||||
**打印 内容=`种`**
|
||||
|
||||
*第一 = 篮子[^1]*
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
|
||||
**第一 = [1](篮子)**
|
||||
**打印 内容=`第一`**
|
||||
```
|
||||
|
||||
One column → list; ≥2 columns + one data row → map; ≥2 columns + many rows → map of lists. Data cells are expressions (same as call-arg values): bare words, numbers, `` `var` ``, quoted strings; URLs and `gpt-4o-mini` stay text via path/hyphen folding. Footnotes: lists use 1-based digit indices; maps use key text (including digit keys like `[^00]`). Foreach on a map walks **keys**.
|
||||
One column → list; ≥2 columns + one data row → map; ≥2 columns + many rows → map of lists. Prefer `[key](coll)` (lists are 1-based). Legacy `` coll[^key] `` still parses. Foreach on a map walks **keys**.
|
||||
|
||||
Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of maps (marker column excluded):
|
||||
|
||||
@@ -107,10 +117,27 @@ Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of ma
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
|
||||
*名 = 订单[^1][^品名]*
|
||||
**名 = [品名]([1](订单))**
|
||||
```
|
||||
|
||||
## 6c. Browser effects — tables + lib/browser (not json.set)
|
||||
## 6c. Bracket-marked call + modifiers
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
**打印 内容=(礼貌 [问候] "Marqdo")**
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
+ `礼貌`=False
|
||||
|
||||
**出 = `礼貌` + ", " + `谁` + "!"**
|
||||
*出*
|
||||
```
|
||||
|
||||
`礼貌 [问候] …` → `礼貌=True`. `]` immediately followed by `(` is index, not a call.
|
||||
|
||||
## 6d. Browser effects — tables + lib/browser (not json.set)
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -128,8 +155,8 @@ import browser:lib/browser.mq.md
|
||||
**`wire`**
|
||||
|
||||
## bump
|
||||
*`count` = count + 1*
|
||||
*`label` = > str count*
|
||||
**count = count + 1**
|
||||
**label = str count**
|
||||
**> browser.set_text sel="#count" text=label**
|
||||
```
|
||||
|
||||
@@ -145,8 +172,41 @@ import text:lib/text.mq.md
|
||||
|
||||
# main
|
||||
|
||||
*parts = > split value=a,b,c sep=,*
|
||||
> print text=`parts`
|
||||
**parts = [text.str_split] s="a,b,c" sep=","**
|
||||
**打印 内容=`parts`**
|
||||
```
|
||||
|
||||
## 7b. Mid M1 — regex + encoding (no plugin)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import re:lib/re.mq.md
|
||||
import enc:lib/encoding.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**`ok` = [re.is_match] text="a@b.c" pattern="@"**
|
||||
**`b64` = [enc.base64_encode] text="hi"**
|
||||
**打印 内容=`ok`**
|
||||
**打印 内容=`b64`**
|
||||
```
|
||||
|
||||
## 7c. Mid M6 — log + uuid
|
||||
|
||||
```markdown
|
||||
---
|
||||
import log:lib/log.mq.md
|
||||
import uuid:lib/uuid.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> log.info text="start"
|
||||
> log.set_level level="debug"
|
||||
> log.debug text="detail"
|
||||
**id = [uuid.v4]**
|
||||
**打印 内容=`id`**
|
||||
```
|
||||
|
||||
## 8. Comment paragraphs (blank-line rule)
|
||||
@@ -155,7 +215,7 @@ import text:lib/text.mq.md
|
||||
# main
|
||||
|
||||
This whole paragraph is a comment, including lines that look like code:
|
||||
*not_executed = 1*
|
||||
**not_executed = 1**
|
||||
> print text=also still comment
|
||||
|
||||
After a blank line, code runs:
|
||||
@@ -173,13 +233,13 @@ import math:lib/math.mq.md
|
||||
|
||||
# main
|
||||
|
||||
*t = > num value=3.5*
|
||||
> print text=`t`
|
||||
**t = > num value=3.5**
|
||||
**打印 内容=`t`**
|
||||
```
|
||||
|
||||
## 10. Object handle + method
|
||||
|
||||
See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` constructs a map with `_type`; methods use `` > `obj`.method `` and read `self` / `自`.
|
||||
See `tests/structure/object-handle.mq.md` and `ext/ai/llm.mq.md`: `# Type` constructs a map with `_type`; methods use `` > `obj`.method `` and read `self` / `自`.
|
||||
|
||||
## 10b. Object inheritance
|
||||
|
||||
@@ -189,16 +249,16 @@ See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` construc
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*msg = "Hello, `who`!"*
|
||||
**msg**
|
||||
**msg = "Hello, `who`!"**
|
||||
*msg*
|
||||
|
||||
# Loud = > Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*msg = "HELLO, `who`!"*
|
||||
**msg**
|
||||
**msg = "HELLO, `who`!"**
|
||||
*msg*
|
||||
```
|
||||
|
||||
`_type` stays the most specific name (`Loud`). Methods walk the base chain; same-name `##` on the child overrides. **No implicit super** — if the child needs parent fields, call the parent explicitly:
|
||||
@@ -207,9 +267,9 @@ See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` construc
|
||||
# Child = > Parent
|
||||
+ `name`
|
||||
|
||||
*self = > Parent name=`name`*
|
||||
*self = > json.set map=`self` key=extra value=1*
|
||||
**self**
|
||||
**self = > Parent name=`name`**
|
||||
**self = [table.put] in=`self` at="extra" value=1**
|
||||
*self*
|
||||
```
|
||||
|
||||
## 11. Agent layout (ABI)
|
||||
@@ -223,9 +283,9 @@ import agent:ext/agent.mq.md
|
||||
|
||||
> load_native
|
||||
|
||||
*ws = > agent*
|
||||
*n = > `ws`.ensure_layout*
|
||||
> print text=`n`
|
||||
**ws = > agent**
|
||||
**n = > `ws`.ensure_layout**
|
||||
**打印 内容=`n`**
|
||||
```
|
||||
|
||||
Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see `doc/design/ext-agent.md`).
|
||||
@@ -233,14 +293,14 @@ Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see
|
||||
## 12. What not to emit
|
||||
|
||||
```markdown
|
||||
# BAD — bold is return, not print
|
||||
# BAD — bare bold that is not code-shaped (decorative OK); do not use bold/italic as print
|
||||
**Hello**
|
||||
|
||||
# BAD — Python control keywords
|
||||
if x > 0:
|
||||
print(x)
|
||||
|
||||
# BAD — wrapping a call in italics
|
||||
# BAD — wrapping a call in italics as if it were a statement
|
||||
*> print text=hi*
|
||||
|
||||
# BAD — old branch syntax (removed)
|
||||
@@ -257,6 +317,10 @@ if x > 0:
|
||||
> print text=y-pos
|
||||
2. *
|
||||
> print text=y-other
|
||||
|
||||
# GOOD — print / return
|
||||
**打印 内容="hi"**
|
||||
*n + 1*
|
||||
```
|
||||
|
||||
## 13. Dynamic site (ext/web, minimal)
|
||||
@@ -283,14 +347,14 @@ import db:db/index.mq.md
|
||||
| title | posts.title | |
|
||||
| body | posts.summary | |
|
||||
|
||||
*store = > db.open*
|
||||
*css = "body{font-family:sans-serif}"*
|
||||
*page = > web.page title="Hello"*
|
||||
*page = > page.compose_components components=`shell`*
|
||||
*page = > page.compose_main main=`main`*
|
||||
*page = > page.css css=`css`*
|
||||
*app = > web.app page=`page` port=8080*
|
||||
*app = > app.static prefix="/static" dir="static"*
|
||||
**store = > db.open**
|
||||
**css = "body{font-family:sans-serif}"**
|
||||
**page = > web.page title="Hello"**
|
||||
**page = > page.compose_components components=`shell`**
|
||||
**page = > page.compose_main main=`main`**
|
||||
**page = > page.css css=`css`**
|
||||
**app = > web.app page=`page` port=8080**
|
||||
**app = > app.static prefix="/static" dir="static"**
|
||||
> listen app=`app`
|
||||
```
|
||||
|
||||
@@ -314,15 +378,42 @@ import quantum:ext/quantum/quantum.mq.md
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
|
||||
*qc = > quantum.circuit qubits=2 steps=`steps`*
|
||||
*rho = > `qc`.density*
|
||||
*red = > `rho`.partial_trace keep=0*
|
||||
*sch = > `qc`.schmidt cut=1*
|
||||
*_ = > `qc`.draw kind="circuit" theme="dark"*
|
||||
*_ = > `qc`.draw kind="hinton"*
|
||||
> print text=`red`
|
||||
**qc = > quantum.circuit qubits=2 steps=`steps`**
|
||||
**rho = > `qc`.density**
|
||||
**red = > `rho`.partial_trace keep=0**
|
||||
**sch = > `qc`.schmidt cut=1**
|
||||
**_ = > `qc`.draw kind="circuit" theme="dark"**
|
||||
**_ = > `qc`.draw kind="hinton"**
|
||||
**打印 内容=`red`**
|
||||
```
|
||||
|
||||
- Full lab: `examples/quantum-entanglement/`. Bell-only: `examples/quantum-bell/`.
|
||||
- `theme="dark"|"light"|"bw"` (default dark) on `circuit` / `probs` / `bloch`. Quote `kind=` / `theme=`.
|
||||
- After rebuilding the plugin: `marqdo ext add quantum` so view loads the new native lib.
|
||||
|
||||
## 15. Linear algebra (ext/linalg)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**`A` = > la.symbol name="A" rows=2 cols=2**
|
||||
**`B` = > la.symbol name="B" rows=2 cols=2**
|
||||
**`C` = `A` + `B`**
|
||||
**`P` = `A` * `B`**
|
||||
```
|
||||
|
||||
Prefer:
|
||||
|
||||
```markdown
|
||||
**`env` = > la.declare table=`shapes`**
|
||||
**`P` = [A](env) * [B](env)**
|
||||
**`t` = > `P`.T_ascii**
|
||||
```
|
||||
|
||||
- Infix `+` / `-` / `*`;`ascii` / `T_ascii` 默认化简(`raw=True` 可关)。
|
||||
- Formula-doc design: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
|
||||
- Examples: `examples/linalg-transpose/`, `examples/linalg-svd/`, `examples/linalg-least-squares/`.
|
||||
@@ -12,13 +12,13 @@ marqdo view PATH # docs browser, default port 7429
|
||||
marqdo debug PATH # debugger UI, default port 7430
|
||||
marqdo catalog PATH -o .marqdo
|
||||
marqdo ext list
|
||||
marqdo ext add llm|agent|web|quantum
|
||||
marqdo ext remove llm|agent|web|quantum
|
||||
marqdo ext add llm|agent|web|quantum|linalg
|
||||
marqdo ext remove llm|agent|web|quantum|linalg
|
||||
```
|
||||
|
||||
Diagnostics look like `path:line:col: message` (1-based line/col).
|
||||
|
||||
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * `` (same-indent restart at `1.` = **new** branch statement); loops `` - [item](coll) `` or `` - [`item`](`coll`) ``; identifiers in backticks (foreach header may omit ticks). See `doc/design/markdown-mapping.md`.
|
||||
**v0.3 surface:** `**…**` = code; `*…*` = return; parameters `` + `name` `` (or prose-inferred); branches `` 1. `cond` `` / `` 2. * `` (same-indent restart at `1.` = **new** branch statement); loops `` - [item](coll) ``; get `` [key](coll) ``; bracket calls `` mod [fn] args ``. See `doc/design/markdown-mapping-v0.3.md`.
|
||||
|
||||
Stdlib search order for `lib/…` imports: `MARQDO_LIB`, `./lib`, directory of the `marqdo` executable (and a few parents). Prefer the **bundle zip** (`marqdo.exe` + `lib/`) over a bare exe.
|
||||
|
||||
@@ -44,6 +44,15 @@ Import one file; use **that** file’s function names.
|
||||
|-----------|-----------|-------------------------|
|
||||
| `lib/text.mq.md` | `lib/文本.mq.md` | text helpers / 去空白·拆分·拼接… |
|
||||
| `lib/table.mq.md` | `lib/表.mq.md` | `put`/`改` + list/map(见 `doc/design/stdlib-table.md`) |
|
||||
| `lib/re.mq.md` | `lib/正则.mq.md` | Mid:`is_match`/`find`/`replace`/… |
|
||||
| `lib/encoding.mq.md` | `lib/编码.mq.md` | Mid:base64/hex |
|
||||
| `lib/path.mq.md` | `lib/路径.mq.md` | Mid:join/normalize/… |
|
||||
| `lib/hash.mq.md` | `lib/哈希.mq.md` | Mid:sha256/hmac/… |
|
||||
| `lib/secrets.mq.md` | `lib/机密.mq.md` | Mid:token_hex/urlsafe |
|
||||
| `lib/csv.mq.md` | `lib/逗号表.mq.md` | Mid:parse/stringify |
|
||||
| `lib/cli.mq.md` | `lib/命令行.mq.md` | Mid:`parse` flags |
|
||||
| `lib/log.mq.md` | `lib/日志.mq.md` | Mid:level-filtered one-line logs |
|
||||
| `lib/uuid.mq.md` | `lib/标识.mq.md` | Mid:UUID v4 |
|
||||
| `lib/browser.mq.md` | `lib/浏览器.mq.md` | WASM client effect helpers(GFM + `set_text`/`canvas`/…;见 marqdo-dev) |
|
||||
| `lib/fs.mq.md` | `lib/文件.mq.md` | filesystem |
|
||||
| `lib/sys.mq.md` | `lib/系统.mq.md` | process / cwd / load_dotenv |
|
||||
@@ -54,9 +63,10 @@ Import one file; use **that** file’s function names.
|
||||
| `lib/math.mq.md` | `lib/数学.mq.md` | num, trig, random, formula, plot |
|
||||
| `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks |
|
||||
| `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods |
|
||||
| `ext/agent.mq.md` | `ext/智能体.mq.md` | agent **framework** (layout now; LLM orchestration roadmap in `ext-agent.md`) |
|
||||
| `ext/agent.mq.md` | `ext/智能体.mq.md` | document-driven **step** / **plan** + OKF;示例 `examples/agent-pong` · `agent-okf-flywheel`;Wave B:[agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) |
|
||||
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | dynamic sites — see **ext/web** section below |
|
||||
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below |
|
||||
| `ext/linalg/linalg.mq.md` | `ext/linalg/线性代数.mq.md` | formula MatExpr + factorize/draw — see **ext/linalg** below |
|
||||
|
||||
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
|
||||
|
||||
@@ -98,6 +108,16 @@ Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p
|
||||
|
||||
Examples: `examples/quantum-bell/`, `examples/quantum-entanglement/`. Design: `doc/design/ext-quantum.md` · Q7: `doc/design/ext-quantum-q7.md` · Q8: `doc/design/ext-quantum-viz-style.md`.
|
||||
|
||||
## ext/linalg (formula-first linear algebra)
|
||||
|
||||
Install: `marqdo ext add linalg` (`线性代数`). Native: `cargo build --release -p marqdo_plugin_linalg`, then re-run `ext add`.
|
||||
|
||||
| EN import | ZH import | Notes |
|
||||
|-----------|-----------|-------|
|
||||
| `ext/linalg/linalg.mq.md` | `ext/linalg/线性代数.mq.md` | Top-level `symbol`/`mul`/`factorize`/`draw` |
|
||||
|
||||
Examples: `examples/linalg-svd/`, `examples/linalg-least-squares/`. Design: `doc/design/ext-linalg.md` · formula-doc: `doc/design/ext-linalg-formula-doc.md` · roadmap: `doc/roadmap/ext-linalg.md`.
|
||||
|
||||
## Formula + plot (math)
|
||||
|
||||
```markdown
|
||||
@@ -163,7 +183,8 @@ See `doc/design/call-arguments.md`.
|
||||
|
||||
| Doc | Topic |
|
||||
|-----|--------|
|
||||
| `doc/design/markdown-mapping.md` | Syntax constitution |
|
||||
| `doc/design/markdown-mapping-v0.3.md` | Syntax constitution (runtime) |
|
||||
| `doc/design/markdown-mapping.md` | Legacy v0.2 notes |
|
||||
| `doc/design/objects.md` | `#` objects / `##` methods |
|
||||
| `doc/design/keywords.md` | Builtins / keywords |
|
||||
| `doc/design/return-hr-and-code-surface.md` | Function end / surfaces |
|
||||
@@ -178,4 +199,6 @@ See `doc/design/call-arguments.md`.
|
||||
| `doc/design/ext-quantum.md` | `ext/quantum` circuits |
|
||||
| `doc/design/ext-quantum-q7.md` | Q7 density linear algebra + advanced SVG |
|
||||
| `doc/design/ext-quantum-viz-style.md` | Q8 themed SVG (`dark`/`light`/`bw`; circuit/probs/bloch) |
|
||||
| `doc/design/ext-linalg.md` | `ext/linalg` formula MatExpr + factorize/draw |
|
||||
| `doc/design/ext-linalg-formula-doc.md` | 公式文档面:跑通即正确 · 代数/计算两面 |
|
||||
| `doc/design/view-debug.md` | view / debug hosts |
|
||||
@@ -0,0 +1,12 @@
|
||||
# Local LLM for Marqdo agent / ext/ai/llm development.
|
||||
# Copy to `.env` in the repo root (gitignored) and fill secrets.
|
||||
# Never commit real keys.
|
||||
|
||||
OPENAI_API_KEY=
|
||||
OPENAI_BASE_URL=https://llm.cflmy.cn/v1
|
||||
OPENAI_MODEL=cflmy
|
||||
|
||||
# Aliases also accepted by ext/ai/llm:
|
||||
# MARQDO_LLM_API_KEY=
|
||||
# MARQDO_LLM_BASE_URL=
|
||||
# MARQDO_LLM_MODEL=
|
||||
+109
-13
@@ -20,13 +20,26 @@ jobs:
|
||||
- name: Install Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Install Go (web plugin)
|
||||
uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: "1.23.x"
|
||||
|
||||
- name: Install Node (VS Code extension)
|
||||
uses: actions/setup-node@v4
|
||||
with:
|
||||
node-version: "20"
|
||||
|
||||
- name: Build release
|
||||
run: cargo build --release
|
||||
- name: Install MinGW for cgo (web.dll)
|
||||
run: choco install mingw -y
|
||||
|
||||
- name: Build release CLI + official plugins
|
||||
shell: bash
|
||||
run: |
|
||||
export PATH="/c/ProgramData/mingw64/mingw64/bin:/c/ProgramData/chocolatey/lib/mingw/tools/install/mingw64/bin:$PATH"
|
||||
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: Checkout extension sources (branch vscode-extension only)
|
||||
run: git fetch origin vscode-extension && git checkout origin/vscode-extension -- vscode-extension
|
||||
@@ -55,6 +68,7 @@ jobs:
|
||||
$vsix = "marqdo-$ver.vsix"
|
||||
$public = "marqdo-$ver-public.zip"
|
||||
$extZip = "marqdo-$ver-ext.zip"
|
||||
$nativeZip = "marqdo-$ver-native-$target.zip"
|
||||
Copy-Item target/release/marqdo.exe "dist/$exe"
|
||||
git archive --format=zip -o "dist/$source" HEAD
|
||||
./target/release/marqdo view output public -o public
|
||||
@@ -65,11 +79,27 @@ jobs:
|
||||
Copy-Item ext "$stageExt/ext" -Recurse
|
||||
if (Test-Path "dist/$extZip") { Remove-Item "dist/$extZip" -Force }
|
||||
Compress-Archive -Path "$stageExt/*" -DestinationPath "dist/$extZip" -Force
|
||||
# Prebuilt native plugins (no Rust required for `marqdo ext add`)
|
||||
$stageNative = "dist/stage-native"
|
||||
if (Test-Path $stageNative) { Remove-Item $stageNative -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path "$stageNative/native" | Out-Null
|
||||
Copy-Item target/release/web.dll "$stageNative/native/web.dll"
|
||||
Copy-Item target/release/agent.dll "$stageNative/native/agent.dll"
|
||||
Copy-Item target/release/quantum.dll "$stageNative/native/quantum.dll"
|
||||
Copy-Item target/release/linalg.dll "$stageNative/native/linalg.dll"
|
||||
if (Test-Path "dist/$nativeZip") { Remove-Item "dist/$nativeZip" -Force }
|
||||
Compress-Archive -Path "$stageNative/*" -DestinationPath "dist/$nativeZip" -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
|
||||
Copy-Item ext "$stage/ext" -Recurse
|
||||
New-Item -ItemType Directory -Force -Path "$stage/ext/native" | Out-Null
|
||||
Copy-Item target/release/web.dll "$stage/ext/native/web.dll"
|
||||
Copy-Item target/release/agent.dll "$stage/ext/native/agent.dll"
|
||||
Copy-Item target/release/quantum.dll "$stage/ext/native/quantum.dll"
|
||||
Copy-Item target/release/linalg.dll "$stage/ext/native/linalg.dll"
|
||||
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
|
||||
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
|
||||
$stageLib = "dist/stage-stdlib"
|
||||
@@ -85,6 +115,7 @@ jobs:
|
||||
echo "SOURCE=$source" >> $env:GITHUB_ENV
|
||||
echo "PUBLIC=$public" >> $env:GITHUB_ENV
|
||||
echo "EXT=$extZip" >> $env:GITHUB_ENV
|
||||
echo "NATIVE=$nativeZip" >> $env:GITHUB_ENV
|
||||
|
||||
- name: Upload release assets
|
||||
uses: softprops/action-gh-release@v2
|
||||
@@ -92,24 +123,23 @@ jobs:
|
||||
body: |
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights — v0.3.3
|
||||
- **浏览器作者零业务 JS(D/E/F)**:bridge 自启;DOM/路由/storage/ws/文件/Canvas/音频/Observer/拖放;`lib/browser` + GFM
|
||||
- **Browser author-zero-JS (routes D/E/F)**: host effects + `lib/browser`; examples `browser-hello` / `browser-app` / `browser-media`
|
||||
- Skill: `marqdo-dev`(代码即文档 / 禁止 json.set 胶水)
|
||||
- Install: `marqdo ext list` / `marqdo ext add llm|agent|web|quantum`
|
||||
- Native plugins: `cargo build --release -p marqdo_plugin_*` then `ext add`
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [README](https://github.com/cflmy/marqdo/blob/main/README.md)
|
||||
|
||||
Also: embedded stdlib, writeback/subtask, Variables modal in `view`, VSIX from branch **`vscode-extension`**.
|
||||
### 亮点 / Highlights
|
||||
- **v1.0.2**:表驱动页面引言 `compose_intro` / `引言装配`;web-site Demo 与后台门禁加固
|
||||
- **v1.0.2**: table-bound page intro (`compose_intro`); web-site demo + desk auth polish
|
||||
- **v1.0.1**:修复 Go `libweb` 动态路由 `{param}` 查询代入、详情 Markdown、CSS 数字误报
|
||||
- **Linux 包必出**:`*-native-x86_64-unknown-linux-gnu.zip` + Linux CLI bundle
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [mapping v0.3](https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping-v0.3.md)
|
||||
|
||||
### Downloads
|
||||
|
||||
| Asset | Contents |
|
||||
|-------|----------|
|
||||
| `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib |
|
||||
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` (optional disk override) |
|
||||
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` + `ext/`(含 native DLL) |
|
||||
| `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 (for `MARQDO_EXT_SOURCE` / local `./ext`) |
|
||||
| `marqdo-*-ext.zip` | Official `ext/` L1 sources |
|
||||
| `marqdo-*-source.zip` | Source snapshot (`git archive`) |
|
||||
| `marqdo-*.vsix` | VS Code / Cursor extension |
|
||||
| `marqdo-*-public.zip` | Static user docs site |
|
||||
@@ -120,9 +150,75 @@ jobs:
|
||||
dist/${{ env.ZIP }}
|
||||
dist/${{ env.STDLIB }}
|
||||
dist/${{ env.EXT }}
|
||||
dist/${{ env.NATIVE }}
|
||||
dist/${{ env.VSIX }}
|
||||
dist/${{ env.SOURCE }}
|
||||
dist/${{ env.PUBLIC }}
|
||||
fail_on_unmatched_files: true
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
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
|
||||
|
||||
- name: Install Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Install Go (web plugin)
|
||||
uses: actions/setup-go@v5
|
||||
with:
|
||||
go-version: "1.23.x"
|
||||
|
||||
- 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 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
|
||||
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"
|
||||
|
||||
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 }}
|
||||
dist/${{ env.LINUX_ZIP }}
|
||||
fail_on_unmatched_files: true
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
+12
@@ -23,6 +23,7 @@
|
||||
.DS_Store
|
||||
.marqdo/
|
||||
**/.marqdo/
|
||||
.marqdo-ext/
|
||||
.env
|
||||
|
||||
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
|
||||
@@ -59,11 +60,22 @@ plugins/*/tmp/
|
||||
/examples/web-net-site/data/
|
||||
/examples/web-net-site-zh/data/
|
||||
/examples/marqdo-blog/data/
|
||||
/examples/anlian-mq/data/
|
||||
|
||||
# Quantum draw/SVG runtime outputs (sources & gold .mq.md stay tracked)
|
||||
/tests/ext/quantum-*.svg
|
||||
/tests/ext/linalg-*.svg
|
||||
/examples/quantum-*/**/*.svg
|
||||
/examples/quantum-*/*.svg
|
||||
/examples/linalg-*/**/*.svg
|
||||
/examples/linalg-*/*.svg
|
||||
/examples/linalg-*.svg
|
||||
|
||||
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
|
||||
/ext/native/
|
||||
|
||||
# Go web plugin c-shared build output (./scripts/build-web-plugin.sh)
|
||||
/plugins/web/build/
|
||||
|
||||
# ephemeral sqlite / test artifacts
|
||||
tests/ext/:memory:
|
||||
+251
@@ -8,6 +8,257 @@
|
||||
|
||||
### Changed
|
||||
|
||||
## v1.0.2 — 2026-09-16
|
||||
|
||||
### Highlights
|
||||
|
||||
**表驱动页面引言(`compose_intro` / `引言装配`)**:英雄区用 GFM「属性 / 值 / 样式」表声明,不再手写 HTML 字符串;WWW Demo 样站与后台门禁一并加固。
|
||||
|
||||
```bash
|
||||
git checkout v1.0.2
|
||||
cargo build --release
|
||||
bash ./scripts/build-web-plugin.sh
|
||||
# 或:解压 Release 的 marqdo-1.0.2-*-native-*.zip / Linux CLI zip
|
||||
marqdo run examples/web-site-zh/index.mq.md
|
||||
```
|
||||
|
||||
### Added
|
||||
- Go `libweb`:`web_compose_intro` — 将引言表装配为 `.main-intro` HTML;中英 API `页面.引言装配` / `page.compose_intro`(`ext/web`)。
|
||||
- 验收样例:`tests/ext/web-intro-compose.mq.md`;`examples/web-site` / `web-site-zh` 升级为表驱动引言 + 文学风壳层 + 卡片→详情路由。
|
||||
|
||||
### Fixed
|
||||
- 后台样站:导航/侧栏/页脚槽位与门禁登录挂载对齐;表单字段加宽便于创建。
|
||||
|
||||
### Changed
|
||||
- Demo 叙述与种子数据面向 WWW Industry / 可复现演示;作者仍零业务 JS、零手写 `.css`。
|
||||
|
||||
## v1.0.1 — 2026-09-15
|
||||
|
||||
### Highlights
|
||||
|
||||
**ext/web(Go libweb)回归修复**:动态路由查询条件恢复 `{param}` 代入;详情 SSR + Markdown;样式表数字不再误报。
|
||||
|
||||
```bash
|
||||
git checkout v1.0.1
|
||||
cargo build --release
|
||||
bash ./scripts/build-web-plugin.sh
|
||||
# 或:解压 Release 的 marqdo-1.0.1-*-native-*.zip / Linux CLI zip
|
||||
marqdo run examples/marqdo-blog/index.mq.md
|
||||
```
|
||||
|
||||
### Added
|
||||
- Go web plugin:详情页正文 Markdown(goldmark GFM),对齐 Rust `pulldown-cmark` 路径。
|
||||
|
||||
### Fixed
|
||||
- **动态路由 `{param}` 未代入查询条件**(`ext/web` Go):`selectPageData` 递归展开 `query` 全部字符串叶子;`data-slot-src` / `_route` 同步替换。`examples/marqdo-blog` `/post/{slug}` 详情 SSR 恢复。
|
||||
- **样式表数字单元格误报「可疑 `/` 除法」**:`cssValueSuspicious` 不再把合法 `z-index`/`opacity` 等 number 当警告。
|
||||
- Go 1.22+ ServeMux:`/static/` 与 `/static/favicon.svg` 的 GET/HEAD 注册冲突导致博客启动 panic。
|
||||
- Rust archive 同步:`resolve_placeholders` 递归 + CSS number 误报收窄(非默认构建路径)。
|
||||
|
||||
## v1.0.0 — 2026-09-14
|
||||
|
||||
### Highlights
|
||||
|
||||
**Markdown 语法映射 v0.3 成为 1.0 宪法**:`**粗体**` = 代码,`*斜体*` = 返回,叙述里的 `` `名` `` 声明并推断形参。这是相对 v0.4 / 旧 `*语句*`/`**返回**` 的破坏性对调。Linux 预编译拓展包与 CLI bundle 为 Release 必出资产。
|
||||
|
||||
```bash
|
||||
git checkout v1.0.0
|
||||
cargo build --release
|
||||
# Linux:也可直接解压 Release 的 marqdo-1.0.0-x86_64-unknown-linux-gnu.zip
|
||||
marqdo run tests/markup-v03/inc-prose.mq.md
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
### Highlights
|
||||
|
||||
**Go `libweb` 默认落地(W-G0–W-G14)**:官方网页原生插件改为 Go C ABI;CLI / gold / Release 走 `scripts/build-web-plugin.sh`;Rust 源码归档。另附 **anlian-mq** 验收站与表单插槽 / `MARQDO_EXT` 提示修复。
|
||||
|
||||
```bash
|
||||
git checkout v0.4.0
|
||||
# 构建 web 原生插件(需 Go + cgo):
|
||||
bash ./scripts/build-web-plugin.sh
|
||||
marqdo ext add web
|
||||
marqdo run examples/anlian-mq/index.mq.md
|
||||
```
|
||||
|
||||
### Added
|
||||
- **`plugins/web` Go 全量重写(W-G0–W-G13)**:C ABI 对等装配/DB/表单/listen/鉴权/上传/SEO/WS/驱动/proxy·invoke/定制壳;`scripts/build-web-plugin.sh` → `libweb.so` / `web.dll`;ADR [0004](doc/adr/0004-web-plugin-go.md) · 施工 [ext-web-go-rewrite.md](doc/design/ext-web-go-rewrite.md)。
|
||||
- **W-G14 验收**:`examples/anlian-mq/`(暗恋见君风格论坛:路由/登录/粉玻璃主题/片段 API;SQLite 本地可跑)。
|
||||
- **GAP-11**:`compose_form` / `表单装配` 支持 `target` / `表单插槽`(如 `#id`),把表单注入引言 HTML 内的挂载点。
|
||||
|
||||
### Fixed
|
||||
- **GAP-12**:`ext/…` import 解析失败且未设置 `MARQDO_EXT` 时,错误附带 `hint: set MARQDO_EXT to the directory that contains web/`。
|
||||
- **listen 会话 / CSRF**:登录后 `IssueCookie` 不再误设 `Max-Age=0`;页面 ABIs(`query`/`order`/`link_prefix`/`css`/`detail`)与 `web_page_chrome`、`invoke return=html` 对齐 anlian 需求。
|
||||
|
||||
### Changed
|
||||
- **默认 `libweb` 为 Go**:Release / gold / `ext add web` 不再构建 Rust `marqdo_plugin_web`;旧 Rust 树移至 `plugins/web-rust-archive/`(非 workspace 成员)。作者面 `ext/web` ABI 名保持兼容。
|
||||
|
||||
## v0.3.9 — 2026-09-09
|
||||
|
||||
### Highlights
|
||||
|
||||
**业务联调缺口 GAP-06–10**:解析器不再吞掉嵌套反引号/`text=[…]` 后的函数体;`invoke` 的 `Null` 不再伪装成功;`sys.exec capture=` 可取 stdout;流式 proxy 反缓冲头。
|
||||
|
||||
```bash
|
||||
git checkout v0.3.9
|
||||
```
|
||||
|
||||
### Added
|
||||
- **`sys.exec` / `系统.执行`**:可选 `capture=` / `捕获=`;为真时返回 `{code, stdout, stderr}`(GAP-09)。
|
||||
|
||||
### Fixed
|
||||
- **GAP-06/07**:`*…*` 分类对反引号/字符串内的 `*` 不再误判;错误收尾的赋值行不再吞掉后续 `##` 体(`>` / 合法 `*…*` 可脱出注释段);命名参数边界尊重 `[…]`/`{…}`。
|
||||
- **GAP-08**:`app.invoke` 对 `Null`/`None` 返回不再伪装成 `{"ok":true}`,改为 500 + `{"ok":false,"error":"null result"}`。
|
||||
- **GAP-10**:`app.proxy` `stream=true` 响应补齐 `Cache-Control: no-cache, no-transform` 与 `X-Accel-Buffering: no`。
|
||||
|
||||
### Changed
|
||||
|
||||
## v0.3.8 — 2026-09-09
|
||||
|
||||
### Highlights
|
||||
|
||||
**中层标准库 Mid2(M7–M10)收口**:日历/时区、URL、TOML、HTML 转义、base32、实用 fs、薄统计与日志字段——日常脚本与工具配置不再依赖外联或插件。另修复嵌套插件调用后 `GLOBAL_HOST` 被清空导致 `invoke` 失败。
|
||||
|
||||
```bash
|
||||
git checkout v0.3.8
|
||||
# 或下载 Release 的 exe / zip
|
||||
marqdo run public/features/14-datetime-url.mq.md
|
||||
marqdo run public/features/17-stats-log.mq.md
|
||||
```
|
||||
|
||||
### Added
|
||||
- **中层标准库 Mid2 M10**:`lib/stats` / `统计`(mean/median/stdev)与 `log`/`日志` 可选 `fields=`;金样与 public `17-stats-log`。**Mid2 M7–M10 收口**(zip 跳过)。设计 [stdlib-stats-log.md](doc/design/stdlib-stats-log.md)。
|
||||
- **中层标准库 Mid2 M9**:`fs.make_dirs` / `remove_tree` / `stat` / `walk`(中英);金样与 public `16-fs-mid2`。设计 [stdlib-fs-mid2.md](doc/design/stdlib-fs-mid2.md)。
|
||||
- **中层标准库 Mid2 M8**:`lib/toml` / `配置表`(只读子集)、`lib/html` / `超文本`(escape/unescape)、`encoding` base32;金样与 public `15-toml-html-encoding`。设计 [stdlib-toml.md](doc/design/stdlib-toml.md) · [stdlib-html.md](doc/design/stdlib-html.md)。
|
||||
- **中层标准库 Mid2 M7**:`lib/datetime` / `日期时间`(`{unix,zone,iso}` · parse/format/add/in_zone)与 `lib/url` / `地址`(parse · query_parse/stringify);金样与 public `14-datetime-url`。设计 [stdlib-datetime.md](doc/design/stdlib-datetime.md) · [stdlib-url.md](doc/design/stdlib-url.md)。
|
||||
- **文档**:中层标准库 Mid 之后缺口盘点与 Mid2(M7–M10)设计/路线——[stdlib-gaps-after-mid.md](doc/research/stdlib-gaps-after-mid.md) · [stdlib-mid2.md](doc/design/stdlib-mid2.md) · [stdlib-mid2.md](doc/roadmap/stdlib-mid2.md)。
|
||||
|
||||
### Fixed
|
||||
- **`host_query` / GLOBAL_HOST**:嵌套 `call_registered` 结束后恢复外层宿主指针,不再清空;`web_listen` 多轮 `invoke`(中间再调插件)不再报 `no active host context`。
|
||||
|
||||
### Changed
|
||||
|
||||
|
||||
## v0.3.7 — 2026-09-07
|
||||
|
||||
### Highlights
|
||||
|
||||
**宿主集成 H1–H4**:浏览器同域 SSE/HTTP 流式中继(`app.proxy`)、HTTP→用户 `##`(`app.invoke`)、跨模块 db 方法分发、`corpus_search` 可发现、MCP Server stdio——下游可去掉 Python 旁路。
|
||||
|
||||
```bash
|
||||
git checkout v0.3.7
|
||||
# 或下载 Release 的 exe / zip
|
||||
marqdo ext add web && marqdo ext add agent
|
||||
# *app*.proxy / *app*.invoke · agent.mcp_server
|
||||
```
|
||||
|
||||
### Added
|
||||
- **宿主集成 H1–H4**:`ext/web` `app.proxy`(同域 SSE/HTTP 流式中继)与 `app.invoke`(HTTP→`lib.member`);跨模块 `#` 对象方法查找;`agent.corpus_search` 自动加载插件;`agent.mcp_server` stdio。金样 `web-proxy-invoke-smoke` · `web-hosting-live` · `web-db-cross-module-smoke` · `agent-mcp-server-smoke`。设计 [ext-hosting-fill.md](doc/design/ext-hosting-fill.md) · [ext-hosting.md](doc/roadmap/ext-hosting.md)。
|
||||
- **文档**:宿主集成缺口盘点——[ext-hosting-gaps.md](doc/research/ext-hosting-gaps.md)。
|
||||
|
||||
### Fixed
|
||||
- **方法分发**:`find_object_type` 沿导入树传递查找,跨模块拿到的 `web.db` 等句柄可再调方法。
|
||||
|
||||
### Changed
|
||||
|
||||
## v0.3.6 — 2026-09-07
|
||||
|
||||
### Highlights
|
||||
|
||||
**中层标准库 Mid M1–M6 收口**:通用原语沉入 `lib/`(正则、编解码、路径、哈希、机密、CSV、加厚文本/集合、CLI、日志、UUID),写日常脚本与多数扩展库不再需要原生插件。另含 `ext/linalg` 公式文档面与 agent/llm 稳健性修复。
|
||||
|
||||
```bash
|
||||
git checkout v0.3.6
|
||||
# 或下载 Release 的 exe / zip
|
||||
marqdo run public/features/13-log-uuid.mq.md
|
||||
marqdo ext add linalg # 可选:公式文档 / 线性代数
|
||||
```
|
||||
|
||||
|
||||
### Added
|
||||
- **中层标准库 M6**:`lib/log` / `日志`(级别过滤的一行日志)与 `lib/uuid` / `标识`(v4);金样与 public `13-log-uuid`。设计 [stdlib-log-uuid.md](doc/design/stdlib-log-uuid.md)。**Mid M1–M6 收口。**
|
||||
- **中层标准库 M5**:`table`/`表` 加厚(sort/sort_by/unique/chunk/zip/flatten)与 `lib/cli`/`命令行`(parse);金样与 public `12-list-cli`。设计 [stdlib-list-cli.md](doc/design/stdlib-list-cli.md)。
|
||||
- **中层标准库 M4**:`lib/csv` / `逗号表`(parse/stringify)与 `lib/text` / `文本` 加厚(contains/replace/case/pad/…);金样与 public `11-csv-text`。设计 [stdlib-csv.md](doc/design/stdlib-csv.md) · [stdlib-text-mid.md](doc/design/stdlib-text-mid.md)。
|
||||
- **中层标准库 M3**:`lib/hash` / `哈希`(sha256/sha1/md5/hmac_sha256)与 `lib/secrets` / `机密`(token_hex/token_urlsafe);金样与 public `10-hash-secrets`。设计 [stdlib-hash.md](doc/design/stdlib-hash.md) · [stdlib-secrets.md](doc/design/stdlib-secrets.md)。
|
||||
- **中层标准库 M2**:`lib/path` / `lib/路径`(join/split/normalize/…)与 `fs`/`文件` 加厚(`copy_file`/`move`/`make_temp`);金样与 public `09-path-fs`。设计 [stdlib-path.md](doc/design/stdlib-path.md) · [stdlib-fs-mid.md](doc/design/stdlib-fs-mid.md)。
|
||||
- **中层标准库 M1**:`lib/re` / `lib/正则`(`is_match`/`find`/`find_all`/`replace`/`split`)与 `lib/encoding` / `lib/编码`(base64/hex);host `host_re_*` + `host_encoding_*`;金样与 public `08-re-encoding`。设计 [stdlib-mid.md](doc/design/stdlib-mid.md) · [stdlib-re.md](doc/design/stdlib-re.md) · [stdlib-encoding.md](doc/design/stdlib-encoding.md)。
|
||||
- **`ext/linalg`**:L0–L6 + 公式文档面 **F1–F3**(中缀、`declare`、展示/`explicit` 默认化简、`T_ascii`、public「如何写公式文档」);示例 `linalg-transpose` · `linalg-svd` · `linalg-least-squares`。设计:[ext-linalg-formula-doc.md](doc/design/ext-linalg-formula-doc.md)。
|
||||
|
||||
### Fixed
|
||||
- **`ext/agent`**:写回改走 `wb.record`(避免 `writeback` 形参遮蔽模块名),不再直调 `host_*`。
|
||||
- **`ext/llm`**:`stream_result` 忽略未知 SSE 类型(如 `reasoning`),不再因此退出。
|
||||
|
||||
### Changed
|
||||
|
||||
## v0.3.5 — 2026-09-04
|
||||
|
||||
### Highlights
|
||||
|
||||
**`marqdo ext add` 无需本机 Rust**:Release 发布预编译 native 插件;CLI 可自动下载 L1(`*-ext.zip`)与 `*-native-*.zip`。Windows 便携包内含 `ext/native/*.dll`。
|
||||
|
||||
```bash
|
||||
git checkout v0.3.5
|
||||
# 或下载 Release 的 exe / zip
|
||||
marqdo ext add web
|
||||
marqdo ext add agent
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
### Added
|
||||
- **预编译原生插件资产**:`marqdo-*-native-x86_64-pc-windows-msvc.zip`、`marqdo-*-native-x86_64-unknown-linux-gnu.zip`;Windows zip 捆绑 `ext/` + native DLL。
|
||||
- **`ext add` 下载回退**:本地无 `target/` 时从 GitHub Release 拉取;`MARQDO_EXT_NO_DOWNLOAD=1` / `MARQDO_EXT_VERSION` 可配置。
|
||||
|
||||
### Changed
|
||||
- 文档:[ext-cli.md](doc/design/ext-cli.md)、[08-ext-deploy-coupling](doc/design/ext-web-customization/08-ext-deploy-coupling.md)、README 安装步骤以预编译为默认路径。
|
||||
- Release workflow:Windows 编插件并上传 native zip;新增 Linux native job。
|
||||
|
||||
## v0.3.4 — 2026-09-04
|
||||
|
||||
### Highlights
|
||||
|
||||
**`ext/web` 定制波次 C0–C4 收口**:可配置 admin 前缀与登录回跳、段边界 gates、shell/layout、样式单元格 strict、脚本 defer/version/`asset_version`、条件导航 when/media。附智能体 Wave B0 示例与写回遮蔽修复。
|
||||
|
||||
```bash
|
||||
git checkout v0.3.4
|
||||
cargo build --release
|
||||
cargo build --release -p marqdo_plugin_web
|
||||
marqdo ext add web
|
||||
# golds: tests/ext/web-c0-admin-prefix … web-c4-nav-when
|
||||
```
|
||||
|
||||
### Added
|
||||
- **智能体 Wave B0**:宪法优先示例 [agent-pong](examples/agent-pong/)(call_site/源码注入)· [agent-okf-flywheel](examples/agent-okf-flywheel/)(OKF `cache=hit`);调研 [agent-framework-2026-09.md](doc/research/agent-framework-2026-09.md);离线 harness [`scripts/agent-harness.sh`](scripts/agent-harness.sh);金样 `agent-constitution-b0`。
|
||||
- **`.env.example`**:开发期 OpenAI 兼容网关变量模板(密钥仅本地 `.env`)。
|
||||
|
||||
### Fixed
|
||||
- **`agent.step` / `plan` 写回**:参数名 `writeback` 遮蔽 `lib/writeback` import,导致 `writeback=True` 时 `method receiver must be an object map`;改为 `host_writeback_record`。金样 `agent-writeback-shadow`。
|
||||
- **`ext/web` C0**:`admin=False` 不再挂载/保留 `/admin*`;可配 `admin_prefix` / `login_redirect` / `logout_redirect`;金样 `web-c0-admin-prefix`。
|
||||
- **`ext/web` C1**:门禁段边界匹配(不再误伤 `/admin-publish`);`gate` 支持 `match` / `on_deny` / `exclude`;`auth` 默认 `on_deny=redirect` + `login_path`;金样 `web-c1-gates`。
|
||||
- **`ext/web` C2**:`shell_css=full|minimal|off`;`layout=sidebar|stacked|bare|rail`;full 壳含小屏单列 media;金样 `web-c2-shell-layout`。
|
||||
- **`ext/web` C3**:样式装配对数字/布尔值单元格告警,`strict`/`strict_css_cells` 硬错误;`page.css` 作 raw CSS;head 表支持 `defer`/`async`/`version`,`asset_version` 统一 `?v=`;金样 `web-c3-style-head`。
|
||||
- **`ext/web` C4**:导航表 `当`/`when`(`auth`/`guest`/`hide`)与 `媒体`/`media`(响应式显隐);listen 注入 `_logged_in`;金样 `web-c4-nav-when`。
|
||||
|
||||
### Changed
|
||||
- `build_step_context`:call site 提前到 task 之后;开场白强调 code-as-documentation。
|
||||
- 中文 `构建单步上下文` 委托英文版(含预算 / READ);新增 `dump_step_context`;live 用例改用仓库根 `.env`。
|
||||
- 文档:[ext-web 定制限制](doc/research/ext-web-customization-limits.md) + [解决设计 C0–C4](doc/design/ext-web-customization/)。
|
||||
|
||||
## v0.3.3 — 2026-09-04
|
||||
|
||||
### Highlights
|
||||
|
||||
Generated
+61
-1115
File diff suppressed because it is too large.
Load diff
+14
-3
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.3.3"
|
||||
version = "1.0.2"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -17,7 +17,7 @@ default = ["native"]
|
||||
native = ["cli", "view", "net-host", "plugin-host", "exec-host", "fs-host", "tty"]
|
||||
cli = ["dep:clap"]
|
||||
view = ["dep:tiny_http"]
|
||||
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize"]
|
||||
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize", "dep:zip"]
|
||||
plugin-host = ["dep:libloading"]
|
||||
exec-host = []
|
||||
fs-host = []
|
||||
@@ -32,10 +32,19 @@ pulldown-cmark = "0.12"
|
||||
serde_json = "1"
|
||||
thiserror = "1"
|
||||
tiny_http = { version = "0.12", optional = true }
|
||||
sha2 = { version = "=0.10.9", default-features = false }
|
||||
sha1 = { version = "=0.10.6", default-features = false }
|
||||
md-5 = { version = "=0.10.6", default-features = false }
|
||||
hmac = { version = "=0.12.1", default-features = false }
|
||||
getrandom = { version = "=0.2.17", default-features = false, features = ["std"] }
|
||||
# Mid M1: Unicode regex for lib/re (no backrefs; RE2-like).
|
||||
regex = { version = "=1.13.1", default-features = false, features = ["std", "unicode"] }
|
||||
# Pin for Cargo/rustc 1.81 (newer rustls/idna/zeroize need edition2024).
|
||||
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"], optional = true }
|
||||
idna_adapter = { version = "=1.1.0", optional = true }
|
||||
zeroize = { version = "=1.8.1", optional = true }
|
||||
# Extract GitHub Release ext/native zips (`marqdo ext add` without local Rust).
|
||||
zip = { version = "=0.6.6", default-features = false, features = ["deflate"], optional = true }
|
||||
libloading = { version = "=0.8.6", optional = true }
|
||||
include_dir = "0.7"
|
||||
libc = { version = "0.2", optional = true }
|
||||
@@ -48,10 +57,12 @@ chrono = { version = "0.4", default-features = false, features = ["alloc", "std"
|
||||
members = [
|
||||
"plugins/demo",
|
||||
"plugins/agent",
|
||||
"plugins/web",
|
||||
"plugins/quantum",
|
||||
"plugins/linalg",
|
||||
"crates/marqdo-wasm",
|
||||
]
|
||||
# Official web plugin is Go (`plugins/web/`); Rust sources kept as
|
||||
# `plugins/web-rust-archive/` for reference (not a workspace member).
|
||||
resolver = "2"
|
||||
|
||||
[dev-dependencies]
|
||||
|
||||
@@ -23,23 +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) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) `` / `` - [`项`](`集合`) ``) |
|
||||
| 表格 | 集合 |
|
||||
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
|
||||
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
|
||||
| 叙述 `` `名` `` / `` `名`=默认 `` | 形参由体推断(`` + `名` `` 仍可用) |
|
||||
| `1.` … | 体内 `1.` `2.` … = 分支(`N. *` = else) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) ``) |
|
||||
| 表格 | 集合;取元优先 `[键](集合)` |
|
||||
| 单独一行 `---` / `***` | **叙述分隔**(跳过;不是函数收束) |
|
||||
|
||||
```markdown
|
||||
# main
|
||||
@@ -47,19 +47,18 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello `谁`!
|
||||
向`谁`问好。
|
||||
|
||||
---
|
||||
**print text="Hello " + 谁**
|
||||
*None*
|
||||
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
对于输入变量`n`,执行**n=n+1**接着返回*n*。
|
||||
```
|
||||
|
||||
完整约定:[markdown-mapping.md](doc/design/markdown-mapping.md)。
|
||||
完整约定:[markdown-mapping-v0.3.md](doc/design/markdown-mapping-v0.3.md)。
|
||||
|
||||
---
|
||||
|
||||
@@ -99,33 +98,34 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v0.3.3)
|
||||
## 现状(v1.0.2)
|
||||
|
||||
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
|
||||
- 映射与解释器:**v0.3 语法宪法**(`**` 代码 / `*` 返回 / 叙述声明);Phase I 树遍历 + 字节码后端;金样例在 `tests/` 与 `tests/markup-v03/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
|
||||
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
|
||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
|
||||
- **`marqdo version --check`**:与 GitHub 最新 release 对比
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**;**中层 Mid M1–M6** + **Mid2 M7–M10**(datetime/url/toml/html/fs++/stats/log.fields 等,见 [stdlib-mid.md](doc/design/stdlib-mid.md) · [stdlib-mid2.md](doc/design/stdlib-mid2.md))
|
||||
- **官方扩展库 `ext/`**(**非** stdlib,本版收口):
|
||||
- **`web`**:W0–W7 + P3 + **W8**(favicon / Head 资源 / 图片装配,见 [web-assets-and-images.md](doc/design/web-assets-and-images.md));示例 [marqdo-blog](examples/marqdo-blog/);生产路径见 [web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)(反向代理 → 嵌入式 `listen`,非 Daphne/Uvicorn)
|
||||
- **`web`**:W0–W7 + P3 + **W8**;**定制 C0–C4**;**宿主 H1–H2**(`proxy`/`invoke`,见 [ext-hosting.md](doc/roadmap/ext-hosting.md));**表驱动引言**(`compose_intro` / `引言装配`);原生层默认 **Go `libweb`**([ADR 0004](doc/adr/0004-web-plugin-go.md),`scripts/build-web-plugin.sh`);示例 [web-site](examples/web-site/) · [web-site-zh](examples/web-site-zh/) · [marqdo-blog](examples/marqdo-blog/) · [anlian-mq](examples/anlian-mq/);生产路径见 [web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)
|
||||
- **`quantum`**:Q0–Q7 + Q8a/b 主题 SVG;示例 [quantum-entanglement](examples/quantum-entanglement/)
|
||||
- **`agent`**:A1–A4(OKF 复用、过程事件、上下文预算、RAG/MCP fixture);下一波缺口 [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
|
||||
- **`linalg`**:L0–L6 + 公式文档面(中缀 / `declare` / 展示化简);示例 [linalg-transpose](examples/linalg-transpose/) · [linalg-svd](examples/linalg-svd/) · [linalg-least-squares](examples/linalg-least-squares/)
|
||||
- **`agent`**:A1–A4 + **MCP Server stdio**(`mcp_server`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
|
||||
- **`llm`**:OpenAI 兼容对话
|
||||
- 安装:`marqdo ext list` / `add …` / `remove`([ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`
|
||||
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum}`
|
||||
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum,linalg}`(`web` 为 Go;其余为 Rust)
|
||||
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
|
||||
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
|
||||
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
|
||||
|
||||
### 如何使用最新 Marqdo(v0.3.3)
|
||||
### 如何使用最新 Marqdo(v1.0.2)
|
||||
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v0.3.3 # 或留在 main
|
||||
git checkout v1.0.2 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
@@ -138,23 +138,28 @@ marqdo view public --no-open
|
||||
marqdo debug public --no-open
|
||||
marqdo catalog public -o .marqdo
|
||||
|
||||
# 3) 安装官方扩展(需先编原生插件)
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
|
||||
marqdo ext add web # 或:网页
|
||||
# 3) 安装官方扩展(Release 用户:无需本机 Rust/Go)
|
||||
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native(Go libweb)
|
||||
marqdo ext add agent # 或:智能体
|
||||
marqdo ext add quantum # 或:量子
|
||||
marqdo ext add llm # 或:大模型
|
||||
marqdo ext add linalg # 或:线性代数
|
||||
marqdo ext add llm # 或:大模型(纯 .mq.md)
|
||||
# 开发者:cargo build --release -p marqdo_plugin_{agent,quantum,linalg}
|
||||
# bash ./scripts/build-web-plugin.sh # 需 Go + cgo → libweb
|
||||
# 离线:解压 Windows zip(已含 ext/native)或手动放下 native zip;MARQDO_EXT_NO_DOWNLOAD=1
|
||||
|
||||
# 4) 动态站示例(扩展装好后)
|
||||
marqdo run examples/web-site-zh/index.mq.md # 表驱动引言 Demo
|
||||
marqdo run examples/marqdo-blog/index.mq.md
|
||||
marqdo run examples/anlian-mq/index.mq.md # W-G14 验收站
|
||||
# 浏览器打开终端打印的 listen 地址;/favicon.ico 与 logo 装配见 W8
|
||||
|
||||
# 5) 浏览器 WASM(可选)
|
||||
marqdo wasm build
|
||||
# → dist/wasm/ … 见 examples/browser-hello/
|
||||
|
||||
# 6) Windows:也可从 GitHub Releases 下载 exe / zip / vsix
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v0.3.3
|
||||
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v1.0.2
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "0.3.3"
|
||||
version = "1.0.2"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
|
||||
+25
-3
@@ -15,7 +15,10 @@
|
||||
|
||||
| 文档 | 摘要 |
|
||||
|------|------|
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.1 语法宪法** |
|
||||
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.2 语法宪法(现行运行时)** |
|
||||
| [design/markdown-mapping-v0.3.md](design/markdown-mapping-v0.3.md) | **v0.3 草案:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断** |
|
||||
| [adr/0005-prose-unified-markup.md](adr/0005-prose-unified-markup.md) | **Proposed:采纳 mapping v0.3** |
|
||||
| [roadmap/markup-v0.3.md](roadmap/markup-v0.3.md) | **Markup v0.3 实现路线(M0–M5)** |
|
||||
| [design/objects.md](design/objects.md) | **`#` 对象 / `##` 函数与方法** |
|
||||
| [design/ai-skill.md](design/ai-skill.md) | **AI 接入 Skill**([`skills/marqdo/`](../skills/marqdo/)) |
|
||||
| [design/code-vs-comment.md](design/code-vs-comment.md) | 叙述 / 可执行 / 外联 |
|
||||
@@ -32,6 +35,17 @@
|
||||
| [design/stdlib.md](design/stdlib.md) | **标准库:内置 + `lib/` + 错误约定** |
|
||||
| [design/stdlib-i18n.md](design/stdlib-i18n.md) | **标准库中英命名:靠库文件名区分,无 lang 开关** |
|
||||
| [design/stdlib-modules.md](design/stdlib-modules.md) | **L1:文件/系统/时间/JSON/网络/数学/外联/插件** |
|
||||
| [design/stdlib-mid.md](design/stdlib-mid.md) | **中层 Mid M1–M6(已落地)** |
|
||||
| [design/stdlib-mid2.md](design/stdlib-mid2.md) | **中层 Mid2:datetime / url / toml / html / fs++** |
|
||||
| [design/stdlib-datetime.md](design/stdlib-datetime.md) | **`lib/datetime`(Mid2 M7)** |
|
||||
| [design/stdlib-url.md](design/stdlib-url.md) | **`lib/url`(Mid2 M7)** |
|
||||
| [design/stdlib-toml.md](design/stdlib-toml.md) | **`lib/toml`(Mid2 M8)** |
|
||||
| [design/stdlib-html.md](design/stdlib-html.md) | **`lib/html`(Mid2 M8)** |
|
||||
| [design/stdlib-fs-mid2.md](design/stdlib-fs-mid2.md) | **`lib/fs` Mid2 M9 加厚** |
|
||||
| [design/stdlib-stats-log.md](design/stdlib-stats-log.md) | **`lib/stats` + log.fields(Mid2 M10)** |
|
||||
| [research/stdlib-gaps-after-mid.md](research/stdlib-gaps-after-mid.md) | **Mid 之后缺口盘点**(对照 Python/Go) |
|
||||
| [roadmap/stdlib-mid.md](roadmap/stdlib-mid.md) | **Mid M1–M6 路线(done)** |
|
||||
| [roadmap/stdlib-mid2.md](roadmap/stdlib-mid2.md) | **Mid2 M7–M10 路线(规划)** |
|
||||
| [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** |
|
||||
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** |
|
||||
| [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) |
|
||||
@@ -40,6 +54,10 @@
|
||||
| [design/ext-agent-plan.md](design/ext-agent-plan.md) | **`## 多步` / `## plan` 锁定设计**(工作簿文件、subtask 执行、修订循环、`step` 默认写回) |
|
||||
| [design/ext-cli.md](design/ext-cli.md) | **`marqdo ext list/add/remove` 官方扩展安装器** |
|
||||
| [design/ext-web.md](design/ext-web.md) | **官方扩展 `ext/web`(页面/库表/绑定/后台;ABI + CLI;设计锁定)** |
|
||||
| [design/ext-web-go-rewrite.md](design/ext-web-go-rewrite.md) | **`plugins/web` Go 全量重写**(多语言 ABI · 网页制备完备 · anlian 验收) |
|
||||
| [adr/0004-web-plugin-go.md](adr/0004-web-plugin-go.md) | **Accepted:web 原生插件实现语言为 Go** |
|
||||
| [research/ext-web-customization-limits.md](research/ext-web-customization-limits.md) | **`ext/web` 定制限制踩坑盘点**(路由/壳 CSS/鉴权/样式/部署) |
|
||||
| [design/ext-web-customization/](design/ext-web-customization/) | **对应解决设计**(C0–C4:前缀可让出、shell_css、gate、布局…) |
|
||||
| [design/web-assets-and-images.md](design/web-assets-and-images.md) | **W8:favicon / Head 资源表 / 图片装配**(一次补齐) |
|
||||
| [design/web-asgi-servers-and-marqdo.md](design/web-asgi-servers-and-marqdo.md) | **Daphne/Uvicorn 等 vs Marqdo**:不能直接托管;反代 + axum `listen` |
|
||||
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
|
||||
@@ -67,8 +85,12 @@
|
||||
| [roadmap/ext-quantum.md](roadmap/ext-quantum.md) | **规划:`ext/quantum` 量子模拟**(基础门·电路·ABI·`ext add`) |
|
||||
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
|
||||
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
|
||||
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点**(产品化 / 评测 / MCP / resume) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` 深入优化 A0–A4**(已完成) |
|
||||
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** |
|
||||
| [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** |
|
||||
| [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus |
|
||||
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
|
||||
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
|
||||
@@ -0,0 +1,28 @@
|
||||
# ADR 0004:网络拓展库原生实现改为 Go
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted** |
|
||||
| Date | 2026-09-10 |
|
||||
| Related | [ext-web-go-rewrite.md](../design/ext-web-go-rewrite.md) · [ext-abi.md](../design/ext-abi.md) · [0001-implementation-language.md](0001-implementation-language.md) |
|
||||
|
||||
## Context
|
||||
|
||||
- Marqdo **宿主/解释器**仍为 Rust(ADR 0001 不变)。
|
||||
- 官方插件契约是稳定 **C ABI**(`include/marqdo_abi.h`),不绑定 Rust ABI。
|
||||
- `plugins/web`(Rust/axum)已具备 W0–W8 等能力,但迭代成本高;且需验证多语言插件生态。
|
||||
- 产品目标:网络拓展库支撑完整网页制备,并以暗恋见君(外接 PostgreSQL + Redis)验收;应用层前后端均为 Marqdo 脚本。
|
||||
|
||||
## Decision
|
||||
|
||||
1. **重写** `plugins/web` 为 **Go** 共享库(`-buildmode=c-shared`),产物名仍为 `libweb.so` / `web.dll` / `libweb.dylib`。
|
||||
2. **ABI 全量兼容**(函数名、参数、语义);`ext/web` 作者面默认不动。
|
||||
3. 施工图:[ext-web-go-rewrite.md](../design/ext-web-go-rewrite.md)。禁止在旧 Rust 插件上继续打补丁演进(ext-web C5)。
|
||||
4. 其它官方插件(agent / quantum / linalg)**暂不**强制改语言;Go web 作为多语言样板。
|
||||
|
||||
## Consequences
|
||||
|
||||
- 构建与发版需安装 Go;CI/`marqdo ext add web` 增加 `go build` 回退。
|
||||
- 根 Cargo workspace 不再包含 `plugins/web` Rust crate(切换完成后)。
|
||||
- cgo/共享库生命周期与 `shutdown` 需严格测试。
|
||||
- 金样例 `tests/ext/web-*` 为门禁。
|
||||
@@ -0,0 +1,53 @@
|
||||
# ADR 0005:叙述统一的 Markup 映射(粗体即代码 · 斜体即返回 · 形参体推断)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted** |
|
||||
| Date | 2026-09-13 |
|
||||
| Related | [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) · [markdown-mapping.md](../design/markdown-mapping.md) · [return-hr-and-code-surface.md](../design/return-hr-and-code-surface.md) · [roadmap/markup-v0.3.md](../roadmap/markup-v0.3.md) |
|
||||
|
||||
## Context
|
||||
|
||||
- Marqdo 的产品承诺是「代码即文档 / 文档即代码」:`.mq.md` 打开是文章,运行是程序。
|
||||
- v0.2([markdown-mapping.md](../design/markdown-mapping.md))为消歧做了硬隔离:无标记 = 注释;`*…*` = 语句;`**…**` = 返回;调用必须 `>`;形参必须 `` + `名` ``。
|
||||
- 该隔离使叙述与程序**视觉割裂**;且与 AI/Markdown 习惯相反(模型偏好用 `**` 强调「要做的事」)。
|
||||
- 产品方重新审视后,希望合法化如下写法:
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
|
||||
|
||||
# main
|
||||
> 加一函数 37
|
||||
或者可以直接这么调用**加一函数 37**
|
||||
```
|
||||
|
||||
## Decision
|
||||
|
||||
1. 采纳 **Markup 映射 v0.3** 为下一版语言宪法草案,全文见 [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md)。
|
||||
2. **角色对调**:`**…**` = 代码段(含可省略 `>` 的调用);`*…*` = 返回值。
|
||||
3. **叙述中的** `` `名` ``:**首次未赋值 = 声明变量**;未使用不报错;**仅当可执行面读取时升为形参**(见设计 §4.4 · §8.2)。不设「提及性」专用语法。
|
||||
4. **形参默认由函数体/叙述推断**(升参);`` + `名` `` 仅作迁移兼容。
|
||||
5. **`>` 调用面保留**(可选)。
|
||||
6. **空返回**用标记而非关键字:推荐 `---` / `***`;显式 `*None*` / `*无*`;整行 `**`;兼容 `****`(设计 §7.2)。
|
||||
7. **不做 v0.2 双模式兼容**(摸索阶段允许破坏性变更);旧 `.mq.md` 须改写。
|
||||
8. 金样例门禁:`tests/markup-v03/`;存量 suite 随后迁移。
|
||||
|
||||
## Consequences
|
||||
|
||||
### Positive
|
||||
|
||||
- 叙述与代码共用 Markdown 习惯,文档可读性上升。
|
||||
- 更贴合 AI 生成粗体「操作」的偏好,降低错用标记。
|
||||
- 去掉形参表仪式,函数更像「带名字的说明段落」。
|
||||
|
||||
### Negative / Risks
|
||||
|
||||
- **破坏性**:与 v0.2 金样例、Skill、教程、大量 `lib/`/`ext/` 源码不兼容,必须分波迁移或双模式。
|
||||
- 段内扫描与形参推断增加解析/语义复杂度——空返回与升参规则已在设计 §7.2 / §8.2 钉死;其余 §12 项用金样例收口。
|
||||
- view/catalog/LSP 高亮规则需同步。
|
||||
|
||||
### Neutral
|
||||
|
||||
- `#` / `##` 对象体系、标准库、插件 ABI、关键字最小集不变。
|
||||
- 输出仍是 `print` / `打印`,不是粗体/斜体。
|
||||
@@ -0,0 +1,54 @@
|
||||
# 方括号标记调用与前置修饰语
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-09-14 |
|
||||
| 相关 | [call-arguments.md](call-arguments.md) · [collection-access-link.md](collection-access-link.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
无标记时,修饰语+函数名与函数名+实参都是词列,**无法消歧**。消歧标记必须来自 Marqdo 语法,**不能**依赖任一自然语言词法(「的」、形容词位置等)。
|
||||
|
||||
## 2. 形状
|
||||
|
||||
```text
|
||||
修饰语… [函数名] 实参…
|
||||
```
|
||||
|
||||
| 例子 | 含义 |
|
||||
|------|------|
|
||||
| `[问候] marqdo` | 调用 `问候`,位置实参 |
|
||||
| `礼貌 [问候] marqdo` | 另加 `礼貌=True` |
|
||||
| `正式 礼貌 [问候] marqdo` | `正式=True` `礼貌=True` |
|
||||
| `[结账摘要] 品名="拿铁" 杯数=2` | 仅具名实参 |
|
||||
| `[问候] ([格式化] `名字`)` | 嵌套:内层整段用 `()` |
|
||||
|
||||
旧形保留:`> 问候 …`、`**问候 …**`、`礼貌=True` 显式具名。
|
||||
|
||||
## 3. 与取元 / foreach
|
||||
|
||||
| 形状 | 语义 |
|
||||
|------|------|
|
||||
| `[X](Y)`(`]` 后**紧邻** `(`) | 取元 |
|
||||
| `[X]`(`]` 后不是 `(`) | 函数名标记 |
|
||||
| `- [X](Y)` | foreach |
|
||||
|
||||
## 4. 修饰语绑定
|
||||
|
||||
- `[` 前按空白切开;每段为标识(可 `` `名` ``)。
|
||||
- 降为 `Named(名, Bool(true))`,再与 `]` 后实参合并。
|
||||
- 与显式同名具名冲突 → 诊断。
|
||||
- **核心不剥语言词缀**;形参叫 `礼貌` 则写 `礼貌 [问候]`。
|
||||
|
||||
## 5. AST
|
||||
|
||||
`CallExpr.pre_modifiers: Vec<String>`;求值/字节码在绑参前展开。
|
||||
|
||||
## 6. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-09-14 | 初稿并落地 |
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.1 增补) |
|
||||
| 状态 | 已定(v0.1 增补;2026-09-14:方括号标记调用) |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md) |
|
||||
|
||||
---
|
||||
|
||||
@@ -16,20 +16,26 @@
|
||||
|------|------|------|
|
||||
| **具名**(保留) | `> 问候 谁=Marqdo` | `名=值`;值可含空格(至下一 `名=`) |
|
||||
| **位置**(新增) | `> 问候 Marqdo` | 按形参声明顺序绑定 |
|
||||
| **方括号标记**(增补) | `礼貌 [问候] Marqdo` | `[函数名]` 消歧;`[` 前裸词 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md) |
|
||||
|
||||
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。具名不可绑定同一形参两次;位置实参不得出现在「已出现具名实参」之后(对齐常见「位置在前、关键字在后」习惯)。
|
||||
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。具名不可绑定同一形参两次;位置实参不得出现在「已出现具名实参」之后(对齐常见「位置在前、关键字在后」习惯)。前置修饰语与显式同名具名冲突则报错。
|
||||
|
||||
---
|
||||
|
||||
## 2. 文法(调用尾部)
|
||||
|
||||
```
|
||||
call_tail ::= callee arg*
|
||||
call_tail ::= bracket_call | classic_call
|
||||
bracket_call ::= modifier* '[' callee ']' arg*
|
||||
classic_call ::= callee arg*
|
||||
arg ::= named | positional
|
||||
named ::= ident '=' value
|
||||
positional ::= value_token
|
||||
positional ::= value_token | '(' call_tail ')'
|
||||
modifier ::= ident # 展开为 ident=True;核心不剥语言词缀
|
||||
```
|
||||
|
||||
- `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记(见 [collection-access-link.md](collection-access-link.md))。
|
||||
- 嵌套调用:把内层整段放进 `()`,例如 `[问候] ([格式化] "x")`。
|
||||
- `value`(具名右侧):可含空格与 `` `var` `` 插值,直到下一个 `ident=` 边界。
|
||||
- `value_token`(位置):空白分隔的一个词法单元——数字、`` `名` ``、标识/文本词;**不含空格**。多词字符串请用具名,例如 `> print text=Hello World!`。
|
||||
- 实参值中 `` `变量` `` 后**紧跟** `[^…]` 时按**脚注取元**解析(可链式),而非文本:`> print text=苹果单价:`水果价格`[^苹果]`、`> print text=`订单`[^2][^品名]`。
|
||||
@@ -44,13 +50,14 @@ positional ::= value_token
|
||||
|
||||
## 3. 绑定算法
|
||||
|
||||
1. 收集具名 → 映射;冲突则报错。
|
||||
2. 按函数形参表顺序:若具名已提供则用之,否则取下一个位置实参。
|
||||
3. 位置实参有余、或必填形参仍缺 → 报错(内置 `input` 的 `prompt` 可缺省)。
|
||||
4. 用户函数:额外具名键仍写入调用环境(便于扩展);位置实参不可超过形参数目。
|
||||
1. 将前置修饰语展开为 `名=True` 具名(与显式具名冲突则报错)。
|
||||
2. 收集具名 → 映射;冲突则报错。
|
||||
3. 按函数形参表顺序:若具名已提供则用之,否则取下一个位置实参。
|
||||
4. 位置实参有余、或必填形参仍缺 → 报错(内置 `input` 的 `prompt` 可缺省)。
|
||||
5. 用户函数:额外具名键仍写入调用环境(便于扩展);位置实参不可超过形参数目。
|
||||
|
||||
---
|
||||
|
||||
## 4. 金样例
|
||||
|
||||
见 `tests/structure/positional-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。
|
||||
见 `tests/structure/positional-call.mq.md`、`tests/structure/bracket-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。
|
||||
@@ -0,0 +1,119 @@
|
||||
# 代码即文档 · 叙述面摩擦(v0.3 实测)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Done** |
|
||||
| 日期 | 2026-09-14 |
|
||||
| 触发 | `examples/code-as-docs/index.mq.md` 试跑 |
|
||||
| 宪法 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) |
|
||||
| 路线 | [code-as-docs-gaps.md](../roadmap/code-as-docs-gaps.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 原则
|
||||
|
||||
修复必须同时服务:
|
||||
|
||||
1. **代码即文档**:人读 Markdown 时自然段落、分隔线、强调不应被误伤。
|
||||
2. **适配 LLM 输出**:模型习惯写 `---` 分段、`**加粗强调**`、`0.85` 小数、`` map[^`key`] `` 动态键——运行时应尽量「写出来就能跑」。
|
||||
3. **可执行标记仍清晰**:真正的赋值 / 调用 / 返回不被误判成装饰。
|
||||
|
||||
---
|
||||
|
||||
## 1. 四个问题(实测)
|
||||
|
||||
### G1 — 模块级 `---` 被当成结构错误
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | 文件标题段落后写 Markdown 分隔线 `---`,报 `expected heading … got: ---` |
|
||||
| 根因 | 词法上整行 `-`/`*` 为 Code;旧实现把函数体内 `---` 当收束,模块顶却当非法。现统一为叙述跳过 |
|
||||
| 人/LLM 期望 | 任意处 `---` = GFM thematic break = **叙述噪音** |
|
||||
| 决议 | **处处** frame 行 skip;副作用收束用 `*None*` / `**` / `****`(返回即结束函数体解析) |
|
||||
|
||||
### G2 — 叙述里的 `**强调**` / `*斜体强调*` 被当成代码/返回
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | 「本文件既是**说明**也是**程序**」→ 粗体 `说明` 不是赋值/调用,解析失败;`*only*` 类英文强调升成返回/`only` 变量 |
|
||||
| 根因 | v0.3 叙述扫描凡 `**…**` / `*…*` 一律可执行([prose.rs](../../src/parse/prose.rs));Skill 曾禁止强调,但与 LLM/Markdown 习惯冲突 |
|
||||
| 人/LLM 期望 | 装饰性强调可出现;**像代码的**粗体/斜体仍执行 |
|
||||
| 决议 | **形状启发式**(见 §2):像代码则执行,否则当作叙述装饰(不产生 Stmt,不升参) |
|
||||
|
||||
### G3 — 小数面量 `0.85` 不可用
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | `**x = 0.85**` → `trailing input: ".85"`;`28 * 0.85` 解析错乱;即便进到求值,`*` 仍只接受 int |
|
||||
| 根因 | 表达式主词只吃整数字面量(`Literal` 无 `Num`);运行时已有 `Value::Num`,二元运算未接浮点 |
|
||||
| 人/LLM 期望 | `0.85`、`3.14`、`折扣=0.85` 可写可算 |
|
||||
| 决议 | 解析 `数字.数字` → `Literal::Num`;`*` `/` `+` `-` 及比较在 `Int`/`Num` 间提升(与已有 `cmp_ord` 一致) |
|
||||
|
||||
### G4 — 动态脚注键 `` 菜单[^`名`] ``
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 现象 | `` 菜单[^`名`] `` → `missing map key ``名`` `(把字面 `` `名` `` 当键,或解析失败) |
|
||||
| 根因 | `[^label]` 的 label 仅为**静态字符串**;AST `Expr::Index { label: String }` 无变量槽 |
|
||||
| 人/LLM 期望 | 表/映射按变量取键:`` `菜单`[^`品名`] `` 或 `菜单[^`品名`]` |
|
||||
| 决议 | 支持 `` [^`ident`] `` → 运行时用变量值作键(文本化后走现有 footnote get);静态 `[^拿铁]` 不变 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 粗体/斜体「像代码」启发式
|
||||
|
||||
### 粗体 `**inner**` → 可执行,当且仅当
|
||||
|
||||
满足任一:
|
||||
|
||||
- 含 `=`(赋值 / 命名参数调用);或
|
||||
- 以 `>` 开头(显式调用);或
|
||||
- 含运算符 / 索引 / 调用形:`+ - * / ( ) [ ]`;或
|
||||
- 空白分词 ≥2 段,且其后段含数字面量、引号串、或 `=`(如 `**加一 37**`、`**print text="hi"**`)
|
||||
|
||||
否则(如 `**说明**`、`**代码即文档**`)→ **装饰,忽略**。
|
||||
|
||||
### 斜体 `*inner*` → 返回,当且仅当
|
||||
|
||||
满足任一:
|
||||
|
||||
- 空 / `None` / `无` / `空` / bool 字面;或
|
||||
- 以 `>` 开头;或
|
||||
- 含 `=` 或运算符 / 索引;或
|
||||
- **整行**仅为 `*…*`(含缩进)——整行返回 `*总额*` / `*n*`;或
|
||||
- 行内且前方紧邻「返回」二字(叙述「接着返回*n*」)
|
||||
|
||||
否则行内简单词(如 `*only*`、`*named*`)→ **装饰,忽略**。
|
||||
|
||||
> 整行 `*n*` 仍是返回;行内「返回*n*。」仍是返回。英文强调词在句中被忽略。
|
||||
|
||||
---
|
||||
|
||||
## 3. 非目标
|
||||
|
||||
- 不恢复 v0.2 双模式
|
||||
- 不引入 `if`/`return` 关键字
|
||||
- 不把任意 `**任意自然语言句子**` 都当代码(必须过 §2)
|
||||
- 动态键第一期只做 `` [^`ident`] ``,不做完整表达式 `[^a+b]`
|
||||
|
||||
---
|
||||
|
||||
## 4. 验收
|
||||
|
||||
| 用例 | 期望 |
|
||||
|------|------|
|
||||
| 顶层段落之间的 `---` | 可解析、可运行 |
|
||||
| 「既是**说明**也是**程序**」 | 可解析;无 Stmt |
|
||||
| `**应付 = 原价 * 0.85**` / `折扣`=0.85 | 数值正确(浮点) |
|
||||
| `` **价 = 菜单[^`名`]** ``(`名` 已绑定) | 取到对应价 |
|
||||
| `examples/code-as-docs/index.mq.md` | 用回浮点折扣与动态键后仍绿 |
|
||||
| 既有 `tests/markup-v03/*` 与 gold | 不回归 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-09-14 | 初稿:四缝 + 启发式 + 验收 |
|
||||
| 2026-09-14 | 落地:G1–G4 实现 + 金样;顶层 Comment 引言 skip |
|
||||
@@ -2,8 +2,12 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 与 mapping v0.1 / keywords 对齐(成段注释) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 状态 | 与 mapping **v0.3** 对齐(现行运行时) |
|
||||
| 日期 | 2026-09-14 |
|
||||
| 取代 | 本文曾按 v0.2(`*语句*` / `**返回**`)叙述;旧对照见 [markdown-mapping.md](markdown-mapping.md) |
|
||||
| 相关 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) §4 |
|
||||
|
||||
「Markup」在此仓库 = Marqdo **把 Markdown 标记映射成语法** 的那一层,不是另一个语言。
|
||||
|
||||
---
|
||||
|
||||
@@ -11,19 +15,18 @@
|
||||
|
||||
| 层 | 形态 | 角色 |
|
||||
|----|------|------|
|
||||
| **叙述面** | 成段注释(空行分段) | 注释;段内任意标记无语义 |
|
||||
| **Marqdo 可执行面** | 结构标记 + `*语句*` + `**返回**` | 本语言程序 |
|
||||
| **叙述面** | 普通段落 | 注释;行内 `` `名` `` 可声明/引用;装饰性 `**强调**` / `*斜体*` 不执行 |
|
||||
| **Marqdo 可执行面** | 结构标记 + **`**代码**`** + **`*返回*`** | 本语言程序 |
|
||||
| **外联面** | ` ```lang ` | 其它语言(FFI) |
|
||||
|
||||
输出属于可执行面里的**函数调用**(`> print …`),见 [keywords.md](keywords.md)。
|
||||
输出属于可执行面里的**函数调用**(`> print …` / `**print …**`),见 [keywords.md](keywords.md)。
|
||||
|
||||
### 成段注释
|
||||
|
||||
- 以**空行**划分段落。
|
||||
- 段首行:首字符非标记 → 注释。
|
||||
- 段内续行:一律注释(即使以 `` ` `` / `-` / `**` 等开头)。
|
||||
- **例外**:整行仅为 `**expr**`(或 `****`)→ Marqdo **返回**;`**强调**` 后还有文字 → 仍是叙述注释。
|
||||
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
|
||||
- 段首行:首字符非标记 → 注释段;段内续行一律叙述(即使以 `` ` `` / `-` 开头)。
|
||||
- 段内仍扫描行内可执行位:`` `名` ``、代码形 `**…**`、返回形 `*…*`。
|
||||
- 叙述段与独立结构行(`>` `#`)之间**建议空一行**,否则 `> print` 可能被吞进注释段。
|
||||
|
||||
---
|
||||
|
||||
@@ -31,8 +34,8 @@
|
||||
|
||||
| 标记/形式 | 角色 | 是否架构级 |
|
||||
|-----------|------|------------|
|
||||
| `*…*` | 程序语句 | 是 |
|
||||
| `**…**` | 返回值 | 是 |
|
||||
| `****` / 空粗体 | 空返回 + 结束函数体 | 是 |
|
||||
| `**…**` | 代码(赋值 / 调用 / 表达式语句) | 是 |
|
||||
| `*…*` | 返回值(整行、`返回*n*`、或表达式形) | 是 |
|
||||
| `****` / 整行 `**` / `*None*` | 空返回 + 结束函数体 | 是 |
|
||||
| `> print …` | 打印副作用 | 否(内置函数) |
|
||||
| 函数体 `---` / `***` | 结束函数体 | 是(边界) |
|
||||
| 函数体 `---` / `***` | 叙述分隔(跳过,**不**结束函数体) | 否 |
|
||||
@@ -0,0 +1,64 @@
|
||||
# 集合取元:GFM 链接形
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active(运行时)** |
|
||||
| 日期 | 2026-09-14 |
|
||||
| 相关 | [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 决议
|
||||
|
||||
表达式取元的**主语法**为 Markdown 链接外形,与 foreach 同构:
|
||||
|
||||
| 角色 | 写法 |
|
||||
|------|------|
|
||||
| **取元(表达式)** | `[键](集合)` |
|
||||
| **遍历(语句)** | `- [项](集合)`(不变) |
|
||||
| **脚注取元(过渡)** | `` 集合[^键] `` 仍解析,新代码勿写 |
|
||||
|
||||
心智:**方括号 = 取出的名字,圆括号 = 从哪取。**
|
||||
|
||||
```markdown
|
||||
**价 = [拿铁](菜单)**
|
||||
**价 = [`名`](菜单)**
|
||||
**第一 = [1](篮子)**
|
||||
|
||||
- [行](今日订单)
|
||||
**名 = [品名](行)**
|
||||
```
|
||||
|
||||
## 2. 细则
|
||||
|
||||
| 写法 | 语义 |
|
||||
|------|------|
|
||||
| `[拿铁](菜单)` | 静态键;`菜单` 为变量(粗体/斜体内) |
|
||||
| `` [`名`](菜单) `` | 动态键(求值 `名` 再作键) |
|
||||
| `[1](篮子)` | List **1-based** 下标(同脚注约定) |
|
||||
| `[1]([苹果](货架))` | 嵌套链式 |
|
||||
|
||||
与 `- [项](集合)` 消歧:仅 **表达式位置** 的 `[…](…)` 为取元;`-` 行头仍为 foreach。
|
||||
|
||||
## 3. 迁移
|
||||
|
||||
`` `菜单`[^拿铁] `` / `菜单[^拿铁]` → `[拿铁](菜单)`(**基与键左右对调**)。
|
||||
|
||||
| 区域 | 约定 |
|
||||
|------|------|
|
||||
| 新代码 / examples / public | **只用**链接形 |
|
||||
| `tests/structure/footnote*` · `interp-footnote*` | 脚注兼容门禁(保留) |
|
||||
| 其余 structure / ext / lib 金样 | 已迁链接形 |
|
||||
|
||||
脚注路径保留至另行决定移除之日;Skill / 教程 / 新示例只用链接形。
|
||||
|
||||
## 4. 非目标
|
||||
|
||||
- 点号 map 访问、`在`、箭头取元、`(键)[集合]`
|
||||
- 循环语法糖(`←` / `in` / 自然语言)
|
||||
|
||||
## 5. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-09-14 | 初稿并落地主语法 |
|
||||
@@ -82,6 +82,9 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`import x:x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
|
||||
| **regex** (=1.13.1) | 正则 | Mid M1 `lib/re`;`default-features=false` + `std`/`unicode`;无回溯引用 |
|
||||
| **sha2** (=0.10.9) / **sha1** (=0.10.6) / **md-5** (=0.10.6) / **hmac** (=0.12.1) | 摘要 | Mid M3 `lib/hash` |
|
||||
| **getrandom** (=0.2.17) | OS 熵 | Mid M3 `lib/secrets` |
|
||||
|
||||
#### 强烈建议
|
||||
|
||||
|
||||
@@ -16,27 +16,17 @@
|
||||
tests/
|
||||
README.md
|
||||
gold.rs # 集成测试入口
|
||||
structure/ # 代码基础结构(Markup 架构)
|
||||
hello.mq.md
|
||||
nested-call.mq.md
|
||||
positional-call.mq.md
|
||||
branch.mq.md
|
||||
loop.mq.md
|
||||
collection.mq.md
|
||||
import/
|
||||
main.mq.md
|
||||
utils.mq.md
|
||||
ns/
|
||||
helpers.mq.md
|
||||
path3.mq.md
|
||||
use.mq.md
|
||||
structure/ # 代码基础结构(Markup 架构 · v0.2)
|
||||
…
|
||||
keywords/ # 关键字与内置名
|
||||
print.mq.md
|
||||
bool-logic.mq.md
|
||||
…
|
||||
markup-v03/ # Markup 映射 v0.3 草案金样例(实现前 ignore)
|
||||
README.md
|
||||
inc-prose.mq.md
|
||||
…
|
||||
ext/
|
||||
agent-run-live.mq.md
|
||||
…
|
||||
errors/ # 期望失败(诊断文案稳定后再加金样例)
|
||||
ns-instance-method.mq.md
|
||||
…
|
||||
```
|
||||
|
||||
@@ -51,6 +41,7 @@ tests/
|
||||
|------|--------|----------|
|
||||
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、点号路径 / `use`、位置/具名实参 | 关键字边角 |
|
||||
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
|
||||
| **markup-v03** | v0.3:叙述声明、粗体代码、斜体返回、升参、空返回、双调用面(见 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)) | 在 `--markup v0.3` 落地前 `#[ignore]` |
|
||||
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
|
||||
|
||||
未单独建夹、但应覆盖的其它测试(`src/**` 单测或日后 `tests/runtime/`):
|
||||
|
||||
@@ -85,7 +85,7 @@ cargo build -p marqdo_plugin_agent
|
||||
|
||||
- Demo (ABI v1): `demo_add`, `demo_echo` — [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md).
|
||||
- Agent (ABI v2): … **OKF agent-kb** …
|
||||
- Web (ABI v2): HTTP listen + SQLite + page render (`web_listen`, `web_render`, `web_db_*`) — [`plugins/web`](../../plugins/web); used by [`ext/web/web.mq.md`](../../ext/web/web.mq.md). Lookup: `plugin.native_path name=web` / `MARQDO_WEB_PLUGIN` / `marqdo ext add web`.
|
||||
- Web (ABI v2): HTTP listen + SQLite/Postgres + page render (`web_listen`, `web_render`, `web_db_*`, …) — [`plugins/web`](../../plugins/web)(**Go 全量重写**,见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md) · [ADR 0004](../adr/0004-web-plugin-go.md));作者面 [`ext/web/web.mq.md`](../../ext/web/web.mq.md)。Lookup: `plugin.native_path name=web` / `MARQDO_WEB_PLUGIN` / `marqdo ext add web`.
|
||||
|
||||
## Layering
|
||||
|
||||
|
||||
+66
-33
@@ -2,9 +2,9 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted (v0.1)** |
|
||||
| Date | 2026-08-07 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) |
|
||||
| Status | **Accepted (v0.3.5 prep)** — prebuilt native download |
|
||||
| Date | 2026-09-04 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) · [08-ext-deploy-coupling.md](ext-web-customization/08-ext-deploy-coupling.md) |
|
||||
|
||||
## Commands
|
||||
|
||||
@@ -12,8 +12,8 @@
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext remove llm
|
||||
marqdo ext remove agent
|
||||
```
|
||||
|
||||
## Install root
|
||||
@@ -23,57 +23,90 @@ marqdo ext remove agent
|
||||
|
||||
Imports use paths like `import llm:ext/ai/llm.mq.md` (see [`load.rs`](../../src/load.rs)).
|
||||
|
||||
## Source for `add`
|
||||
## Goal: no local Rust required
|
||||
|
||||
End users who install Marqdo from **GitHub Releases** should run:
|
||||
|
||||
```bash
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
and get both L1 `.mq.md` **and** the matching native plugin (`.dll` / `.so`) **without** `cargo build`.
|
||||
|
||||
### Resolution order (`add` with native crate)
|
||||
|
||||
1. Local artifact (`MARQDO_*_PLUGIN`, `plugins/web/build` for **web**, `target/{debug,release}`, beside `marqdo`, `MARQDO_EXT_SOURCE/native`, …)
|
||||
2. **Download** `marqdo-{VER}-native-{target}.zip` from the GitHub Release for this CLI version → cache under `~/.marqdo/cache/`
|
||||
3. Local rebuild fallback:
|
||||
- **web** → `./scripts/build-web-plugin.sh` (Go c-shared `libweb`; requires Go 1.22+ / cgo)
|
||||
- other plugins → `cargo build -p marqdo_plugin_*` when Rust/`cargo` is available
|
||||
4. Else fail with a clear message pointing at the Release assets
|
||||
|
||||
L1 sources:
|
||||
|
||||
1. `MARQDO_EXT_SOURCE` / repo `./ext` / beside binary
|
||||
2. Else download `marqdo-{VER}-ext.zip` into `~/.marqdo/cache/ext-src-v{VER}/`
|
||||
|
||||
### Env knobs
|
||||
|
||||
| Variable | Meaning |
|
||||
|----------|---------|
|
||||
| `MARQDO_EXT_VERSION` | Override SemVer used for Release asset names (default: CLI `CARGO_PKG_VERSION`) |
|
||||
| `MARQDO_EXT_NO_DOWNLOAD=1` | Never hit the network (CI / air-gap); local/cargo only |
|
||||
| `MARQDO_WEB_PLUGIN` / `MARQDO_AGENT_PLUGIN` / `MARQDO_QUANTUM_PLUGIN` | Explicit native path |
|
||||
|
||||
Windows Release **zip** also ships `ext/` + `ext/native/*.dll` next to `marqdo.exe` so a portable unzip works offline after one download.
|
||||
|
||||
## Source for `add` (developers)
|
||||
|
||||
1. `MARQDO_EXT_SOURCE` — directory containing `ai/llm.mq.md` …
|
||||
2. Else repo `./ext` near cwd / binary
|
||||
2. Else repo `./ext` near cwd / binary
|
||||
3. Else Release `marqdo-*-ext.zip` (see above)
|
||||
|
||||
## Layout (`ext/`)
|
||||
|
||||
Official extensions live under **`ext/ai/`** (LLM + agent framework only). Do not add flat `.mq.md` files at `ext/` root — keeps the tree from accumulating unrelated modules.
|
||||
|
||||
```text
|
||||
ext/
|
||||
ai/
|
||||
llm.mq.md
|
||||
大模型.mq.md
|
||||
agent.mq.md
|
||||
智能体.mq.md
|
||||
ai/ # llm + agent L1
|
||||
web/
|
||||
quantum/
|
||||
```
|
||||
|
||||
Future optional ext domains get their own subdirs (e.g. `ext/web/`, `ext/quantum/`), not mixed into `ai/`.
|
||||
Installed tree (`~/.marqdo/ext` or `MARQDO_EXT`):
|
||||
|
||||
```text
|
||||
web/web.mq.md
|
||||
web/网页.mq.md
|
||||
native/libweb.so # or web.dll / libweb.dylib
|
||||
web.plugin # absolute path hint
|
||||
```
|
||||
|
||||
## Catalog
|
||||
|
||||
| Id | Installs under `MARQDO_EXT` |
|
||||
|----|-----------------------------|
|
||||
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **`native/libagent.so`** (or `.dylib`) |
|
||||
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **`native/libweb.so`** — 见 [ext-web.md](ext-web.md) · [roadmap](../roadmap/ext-web.md) |
|
||||
| `quantum` | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **`native/libquantum.so`** — 见 [ext-quantum.md](ext-quantum.md) · [roadmap](../roadmap/ext-quantum.md) |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **native `agent`** |
|
||||
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **native `web`** |
|
||||
| `quantum` | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **native `quantum`** |
|
||||
|
||||
`add agent` / `add web` / `add quantum` **先定位原生插件**,再复制 `.mq.md`:
|
||||
## Release assets (native)
|
||||
|
||||
1. 在 `CARGO_TARGET_DIR`、`target/{debug,release}`、源码 `ext` 旁的 `target/`、可执行文件旁等路径查找 `lib{name}.so`(或 `.dll` / `.dylib`)
|
||||
2. 找不到则自动执行 `cargo build -p marqdo_plugin_{name}`,再安装到 `MARQDO_EXT/native/`
|
||||
3. 写入 `{name}.plugin` 绝对路径提示,供 `plugin.native_path` 解析
|
||||
| Asset | Platform |
|
||||
|-------|----------|
|
||||
| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Windows x64 (`native/*.dll`) |
|
||||
| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Linux x64 (`native/lib*.so`) |
|
||||
|
||||
这样不会出现「只装了 `.mq.md`、运行时报 native plugin not found」的半安装状态。
|
||||
|
||||
```bash
|
||||
# 推荐:在仓库根目录
|
||||
marqdo ext add web
|
||||
# 等价于找到或编好 libweb.so 后拷入 ~/.marqdo/ext/native/
|
||||
```
|
||||
|
||||
Without a prior install, runtime still resolves via `plugin.native_path name=web` (see [ext-abi.md](ext-abi.md)): `MARQDO_WEB_PLUGIN` → `CARGO_TARGET_DIR/{debug,release}/` → cwd `target/…` → beside `marqdo` binary → `MARQDO_EXT/native/`.
|
||||
macOS: use local `cargo build` until CI adds Darwin natives (same zip naming pattern reserved).
|
||||
|
||||
## Tests
|
||||
|
||||
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` ([`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md); needs `tests/ext/.env` + built `libagent`).
|
||||
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_cli_add_web` (local build path; set `MARQDO_EXT_NO_DOWNLOAD=1` in sandboxes if needed).
|
||||
|
||||
Unit: `ext_fetch` URL / triple tests.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Third-party registry
|
||||
- Merging into `lib/`
|
||||
- Bundling domain/task helpers in official ext
|
||||
- Merging domain helpers into `lib/`
|
||||
- Guaranteeing plugin **source** ABI stability (author `.mq.md` API is the contract)
|
||||
@@ -0,0 +1,306 @@
|
||||
# 设计:宿主集成缺口补齐(`ext/web` · `ext/ai`)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · H1–H4 stdio 已落地**(H4b HTTP 可选) |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 缺口盘点 | [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) |
|
||||
| 路线图 | [ext-hosting.md](../roadmap/ext-hosting.md) |
|
||||
| 边界 | [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) |
|
||||
| 目标 | 用**扩展库一等 API**关闭 GAP-01–05,取代下游 Python 旁路 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**服务器中继与「请求→`##`」进 `ext/web`;MCP Server 与 corpus 可发现进 `ext/ai`;标准库只保留已有客户端 SSE。** 作者用 GFM 表声明路由/工具,不写 JS、不启第二语言运行时。
|
||||
|
||||
---
|
||||
|
||||
## 1. 分层与禁止项
|
||||
|
||||
| 层 | 职责 | 落点 |
|
||||
|----|------|------|
|
||||
| 作者面 | 声明路径、上游、函数名、工具表 | `ext/web/web.mq.md` · `ext/ai/agent.mq.md`(+ 中文对偶) |
|
||||
| ABI | axum 流式代理、每请求 interp 调用、MCP 传输 | `plugins/web` · `plugins/agent` |
|
||||
| 标准库 | 不变:缓冲客户端 SSE / 解析 | `lib/net`(**不**加中继) |
|
||||
| 核心 host | **禁止**新增 agent/web 领域 `host_*` | 见 Skill 硬规则 9 |
|
||||
|
||||
**禁止:**
|
||||
|
||||
1. 为中继在浏览器手写业务 JS。
|
||||
2. `json=` 继续塞「任意 `##`」语义(保持 DB-only;新能力用独立装配名)。
|
||||
3. MCP Server 把向量库升为权威真相(工具结果可带 `authority=workbook`)。
|
||||
4. 无白名单的「任意文件系统路径 + 任意 `##`」远程触发。
|
||||
|
||||
---
|
||||
|
||||
## 2. GAP-01 · `app.proxy` 流式反向代理
|
||||
|
||||
### 2.1 作者 API
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.proxy path="/v1/chat/completions" upstream=$OPENAI_BASE_URL*
|
||||
*应用 = > `应用`.proxy path="/llm/stream" upstream="https://api.example.com" strip_prefix="/llm" stream=True*
|
||||
```
|
||||
|
||||
或装配表(一次挂多条):
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.configure proxy=`代理表`*
|
||||
|
||||
| path | upstream | stream | strip_prefix | headers_from_env |
|
||||
|------|----------|--------|--------------|------------------|
|
||||
| /proxy/chat | $OPENAI_BASE_URL | True | | OPENAI_API_KEY=Authorization |
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 含义 |
|
||||
|------|------|------|
|
||||
| `path` | 必填 | 浏览器同域路径 |
|
||||
| `upstream` | 必填 | 上游根或完整 URL;支持 `$ENV` |
|
||||
| `stream` | `True` | `True`:响应按上游 `Content-Type` 管道转发(含 `text/event-stream`) |
|
||||
| `strip_prefix` | 空 | 转发前去掉本站前缀 |
|
||||
| `methods` | `POST` | 允许方法 |
|
||||
| `headers_from_env` | 空 | `ENV=Header-Name` 注入(密钥不进前端) |
|
||||
| `timeout_ms` | 插件默认 | 上游超时 |
|
||||
|
||||
中文:`## 代理` / `流式=` / `上游=` / `去前缀=`。
|
||||
|
||||
### 2.2 ABI / 插件行为
|
||||
|
||||
| 步骤 | 行为 |
|
||||
|------|------|
|
||||
| 注册 | `web_app_proxy` 写入 `AppState` 路由表 |
|
||||
| 请求 | 读 body + 过滤危险 hop-by-hop 头;合并 env 注入头 |
|
||||
| 上游 | `reqwest`/`hyper` 流式客户端(插件内,不进核心) |
|
||||
| 响应 | 复制状态码与 `content-type`;`body` 为 stream;SSE 不整段缓冲 |
|
||||
| CORS | 仍走既有 `configure cors=`(同域调用时浏览器不依赖上游 CORS) |
|
||||
|
||||
### 2.3 与 `lib/net.http_post_sse` 关系
|
||||
|
||||
| API | 角色 |
|
||||
|-----|------|
|
||||
| `http_post_sse` | **出站消费者**(CLI/agent 侧收齐 events) |
|
||||
| `app.proxy` | **入站中继**(浏览器 ← Marqdo ← 上游) |
|
||||
|
||||
二者互补,不互相替代。
|
||||
|
||||
### 2.4 验收
|
||||
|
||||
- 金样:mock 上游发两帧 SSE,浏览器侧(或 `curl -N`)收到两帧且中间无全缓冲延迟门槛。
|
||||
- 密钥仅出现在服务端 env 注入头。
|
||||
- 金样名建议:`tests/ext/web-proxy-sse-smoke.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 3. GAP-02 · `app.invoke` / `configure invoke=`(HTTP → `##`)
|
||||
|
||||
### 3.1 作者 API
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.invoke path="/api/沉淀" method=POST fn="run.沉淀"*
|
||||
```
|
||||
|
||||
表形式:
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.configure invoke=`调用表`*
|
||||
|
||||
| path | method | fn | body | return |
|
||||
|------|--------|-----|------|--------|
|
||||
| /api/note | POST | run.写出 | json | json |
|
||||
| /api/search | GET | db.recent | query | json |
|
||||
```
|
||||
|
||||
| 列 / 参数 | 含义 |
|
||||
|-----------|------|
|
||||
| `path` / `method` | HTTP 路由 |
|
||||
| `fn` | `库.成员`(入口模块已 `import`)或 `模块路径##标题`(白名单前缀内) |
|
||||
| `body` | `json` \| `form` \| `query` \| `raw` → 映射到 `##` 形参(同名优先;其余进 `payload` 袋) |
|
||||
| `return` | `json`(默认)\| `text` \| `status` |
|
||||
|
||||
中文:`## 调用` / `函数=` / `正文=` / `返回=`。
|
||||
|
||||
### 3.2 安全默认(锁定)
|
||||
|
||||
1. **仅**解析入口 workbook 已导入的 `bind` 路径,或 `invoke_allow=` 显式前缀列表。
|
||||
2. 单请求超时 + 可选并发上限(防 listen 线程饿死)。
|
||||
3. 默认不启;作者显式 `invoke` / `configure invoke=`。
|
||||
4. 错误:`{ok:false, error}` + HTTP 4xx/5xx;不把内部路径栈默认回传生产模式。
|
||||
|
||||
### 3.3 ABI / 插件行为
|
||||
|
||||
| 步骤 | 行为 |
|
||||
|------|------|
|
||||
| 注册 | `web_app_invoke` 存 `(path, method, FnRef)` |
|
||||
| 命中 | 解析 body → Value 袋;`call_lib_path` / 等价「同步调用已加载模块的 `##`」 |
|
||||
| 返回 | Value → JSON(复用现有 host JSON 通路);侧效(写盘)在同一解释器事务语义内尽最大努力 |
|
||||
|
||||
**不**把 `json=` DB 路由改语义;`invoke` 是平行装配。
|
||||
|
||||
### 3.4 与 compose 期 `call_lib_path` 关系
|
||||
|
||||
| 时机 | API |
|
||||
|------|-----|
|
||||
| 装配页 | 现有 compose / `call_lib_path` |
|
||||
| **每个 HTTP 请求** | 本设计 `invoke` |
|
||||
|
||||
### 3.5 验收
|
||||
|
||||
- `POST` JSON → 用户 `##` 写入临时文件 + 返回 `{ok:true,…}`。
|
||||
- 未导入路径 → 4xx,不执行。
|
||||
- 金样:`tests/ext/web-invoke-smoke.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 4. GAP-03 · MCP Server(`ext/ai`)
|
||||
|
||||
### 4.1 作者 API
|
||||
|
||||
```markdown
|
||||
*服务 = > agent.mcp_server name="marqdo-qd"*
|
||||
*服务 = > `服务`.tool name="qd_search" fn="求道.搜索" description="关键词检索"*
|
||||
*服务 = > `服务`.tool name="qd_capture" fn="求道.捕捉"*
|
||||
*服务 = > `服务`.serve transport=stdio*
|
||||
# 或
|
||||
*服务 = > `服务`.serve transport=http host=127.0.0.1 port=7433*
|
||||
```
|
||||
|
||||
工具表:
|
||||
|
||||
| name | fn | description |
|
||||
|------|-----|-------------|
|
||||
| qd_search | 求道.搜索 | … |
|
||||
| qd_list | 求道.列出 | … |
|
||||
|
||||
### 4.2 传输
|
||||
|
||||
| transport | 用途 |
|
||||
|-----------|------|
|
||||
| `stdio` | Cursor / Claude Desktop 拉起 |
|
||||
| `http` | Streamable HTTP(与官方 MCP 演进对齐;首版可先 SSE+POST 子集) |
|
||||
|
||||
### 4.3 与 A4 fixture 客户端关系
|
||||
|
||||
| API | 方向 |
|
||||
|-----|------|
|
||||
| `mcp_list_tools` / `mcp_call` | **出站**(Agent 调外部 MCP;现 fixture) |
|
||||
| `mcp_server` + `serve` | **入站**(外部调 Marqdo) |
|
||||
|
||||
客户端「真 MCP」仍见 agent 缺口文;本设计先交 Server,fixture 可保留测客户端。
|
||||
|
||||
### 4.4 ABI
|
||||
|
||||
- `plugins/agent`:`agent_mcp_server_*`(注册工具、stdio loop、可选 HTTP)。
|
||||
- 工具实现:复用 GAP-02 同款「调用 `##`」内核(可抽共享 `invoke_fn`),避免两套分发。
|
||||
- 返回包装:可含 `authority=workbook`。
|
||||
|
||||
### 4.5 验收
|
||||
|
||||
- 金样:stdio 夹具发 `tools/list` + `tools/call`,断言 JSON-RPC 形结果。
|
||||
- 可选:`tests/ext/agent-mcp-server-smoke.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 5. GAP-04 · 同寿副端口
|
||||
|
||||
### 5.1 关闭策略(优先)
|
||||
|
||||
GAP-01 + GAP-02 挂在**同一** `app.listen` → **不实现副端口**,文档宣布 GAP-04 关闭。
|
||||
|
||||
### 5.2 备选 API(仅当必须隔离)
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.listen host=127.0.0.1 port=18081 also_port=7432 also_routes=`中继表`*
|
||||
```
|
||||
|
||||
`also_routes` 仅允许 `proxy` / `invoke` 已注册子集。实现成本高,**默认不做**。
|
||||
|
||||
---
|
||||
|
||||
## 6. GAP-05 · 跨模块 `db` 与 corpus 可发现
|
||||
|
||||
### 6.1 `db` 句柄(扩展约定 + 运行时)
|
||||
|
||||
**作者约定(立即文档化):**
|
||||
|
||||
1. 跨模块优先传 **`url` 字符串**,调用方 `*store = > web.db url=…*` 再 `select`。
|
||||
2. 若传对象:必须保留 `_type` 为插件注册名(与 `web.db` 构造一致)。
|
||||
|
||||
**运行时修补(H 波次):**
|
||||
|
||||
| 选项 | 做法 | 选用 |
|
||||
|------|------|------|
|
||||
| A | 跨模块返回插件对象时规范 `_type` + 全局方法表查找 | **首选**(一次修好所有插件对象) |
|
||||
| B | `db.open` 只返回 `{url}` 朴素 map,禁止「裸 select」跨文件 | 文档契约;体验较差 |
|
||||
|
||||
金样:模块 A `open` → 返回 → 模块 B `select` 成功。
|
||||
`tests/ext/web-db-cross-module-smoke.mq.md`。
|
||||
|
||||
### 6.2 `corpus_search` 可发现
|
||||
|
||||
```markdown
|
||||
## corpus_search
|
||||
+ `query`
|
||||
+ `root`=".marqdo/agent-kb"
|
||||
|
||||
* > plugin.load name=agent *
|
||||
** > agent_corpus_search query=`query` root=`root` **
|
||||
```
|
||||
|
||||
或在 `# agent` / `## corpus_search` 入口统一 `ensure_plugin`(与现 `agent` 构造对齐),保证 **纯 `marqdo run` + import agent** 即可用。
|
||||
|
||||
**不**把 `agent_corpus_search` 搬进 `src/host/`。
|
||||
|
||||
### 6.3 验收
|
||||
|
||||
- 无显式手工 ABI 名的情况下,`marqdo run` 金样调用 `agent.corpus_search` 成功。
|
||||
- 跨模块 `db.select` 金样绿。
|
||||
|
||||
---
|
||||
|
||||
## 7. 扩展库表面清单(落地时改这些文件)
|
||||
|
||||
| 文件 | 增补 |
|
||||
|------|------|
|
||||
| `ext/web/web.mq.md` · `网页.mq.md` | `## proxy` / `## invoke`;`configure` 增 `proxy`/`invoke` 列 |
|
||||
| `plugins/web/src/http.rs` · `middleware.rs` · 新 `proxy.rs` / `invoke.rs` | 路由注册与流式/调用 |
|
||||
| `ext/ai/agent.mq.md` · `智能体.mq.md` | `# mcp_server` · `## tool` · `## serve`;`corpus_search` ensure_plugin |
|
||||
| `plugins/agent/` | MCP Server 传输 + 共享 invoke |
|
||||
| `tests/ext/web-proxy-sse-smoke.mq.md` 等 | 见上 |
|
||||
| `doc/roadmap/ext-web.md` | 链到 H 波次(不重开 W0–W7) |
|
||||
| `public/` / Skill | 发版时补「同域 LLM 代理 / HTTP 调用 ##」短节 |
|
||||
|
||||
**不**新增 `lib/run` 作为核心依赖:用户业务 `##` 仍在其自己的 `lib/*.mq.md`;Marqdo 只提供 **invoke 管道**。
|
||||
|
||||
---
|
||||
|
||||
## 8. 迁移:下游旁路 → 扩展 API
|
||||
|
||||
| 旁路(下游) | 替换为 |
|
||||
|--------------|--------|
|
||||
| `llm_proxy.py` `/proxy/stream` | `app.proxy` / `configure proxy=` |
|
||||
| `llm_proxy.py` `/store/*` + `marqdo run` | `app.invoke` → 用户 `##` |
|
||||
| `mq_bridge.py` 仅过滤 | 用户 `##` 内 `table`/`re` 过滤,或修复后的 `corpus_search` |
|
||||
| `qdagent_mcp.py` | `agent.mcp_server` + `serve` |
|
||||
| `mq.sh` 双进程 | 单 `marqdo run index.mq.md`(proxy+invoke 同端口) |
|
||||
|
||||
---
|
||||
|
||||
## 9. 开放点(实现前拍板)
|
||||
|
||||
| # | 问题 | 默认倾向 |
|
||||
|---|------|----------|
|
||||
| 1 | `invoke` 的 `fn` 是否允许 `path.mq.md##标题` 字面量 | 允许但必须 `invoke_allow` 前缀 |
|
||||
| 2 | MCP HTTP 首版范围 | stdio 先交;HTTP 跟一波 |
|
||||
| 3 | 代理是否缓冲「非 SSE」大 body | 非流式可限长缓冲;SSE 禁止整段缓冲 |
|
||||
| 4 | GAP-05 选项 A vs B | **A** |
|
||||
|
||||
---
|
||||
|
||||
## 10. 完成定义(整包)
|
||||
|
||||
1. 无 Python 旁路即可:浏览器同域 SSE 对话 + HTTP 触发沉淀 `##` +(可选)MCP stdio 暴露同一批 `##`。
|
||||
2. 金样覆盖 proxy / invoke / cross-db / corpus / mcp-server(stdio)。
|
||||
3. `doc/research/ext-hosting-gaps.md` 各 GAP 标为关闭或降级为「备选副端口不做」。
|
||||
4. 发版说明指向 `ext/web` · `ext/ai` 新作者面,不指向 `scripts/*.py`。
|
||||
@@ -0,0 +1,235 @@
|
||||
# `ext/linalg` — 公式文档面(跑通即正确)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Draft · 锁定作者面哲学与分期** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 父设计 | [ext-linalg.md](ext-linalg.md) |
|
||||
| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) |
|
||||
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
|
||||
| 对照 | [stdlib-math.md](stdlib-math.md)(高中标量公式) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**`.mq.md` 里的线性代数应当读起来像一份可运行的公式讲义**:式子能跑通,就在库承诺的规则与维数下代表正确;`lib/math` 守高中边界,大学符号矩阵与更深层计算由 **`ext/linalg` 正当承担**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 产品哲学
|
||||
|
||||
### 1.1 与 Marqdo 总原则对齐
|
||||
|
||||
| Marqdo | 在线性代数上的含义 |
|
||||
|--------|-------------------|
|
||||
| 代码即文档 | 矩阵代数段落用数学式书写,而不是 API 调用清单 |
|
||||
| 标记即语法 | `$$`、中缀、`# matrix` 方法都是可读标记,不是「库胶水」 |
|
||||
| 跑通可验收 | 金样 / 课堂作业:文件 exit 0 + 断言化简结果 = 式子合法 |
|
||||
|
||||
### 1.2 「跑通即正确」的精确定义
|
||||
|
||||
**不是**「任意高深定理自动证明」。
|
||||
**是**在声明的能力边界内,下列任一成立则文档该段视为正确:
|
||||
|
||||
1. **形状层**:不相容维数的乘加在构造时硬错误(写不出可运行的坏式)。
|
||||
2. **恒等式层**:文档断言的规范形(如 `(AB)^\top → B^\top A^\top`)经规则集得到。
|
||||
3. **数值核对层**(可选):小 `$$` 数值阵 `explicit` 后与手算一致——验算,不是符号证明。
|
||||
|
||||
更高深主题(矩阵微积分、表示、特殊函数矩阵等)通过**扩展同一公式面的规则表**分期加入,而不是另起一套函数库叙事。
|
||||
|
||||
### 1.3 与 `lib/math` 的边界(再次锁定)
|
||||
|
||||
| | `lib/math` | `ext/linalg` |
|
||||
|--|------------|--------------|
|
||||
| 教育边界 | 高中标量公式 | 大学经典线性代数及更深(官方 ext) |
|
||||
| 值类型 | `Value::Formula`(标量 AST) | `_type=matrix` / `矩阵`(MatExpr + 稠密) |
|
||||
| 作者感觉 | `$$sin(x)+x$$` + `diff` / `plot` | `A*B`、`(AB)^T`、分块、分解图 |
|
||||
| 是否「数学库」 | 是(stdlib) | **是数学库的官方扩展**,不是旁路工具箱 |
|
||||
|
||||
把大学 LA 塞进 `lib/math` ❌;在 `ext/linalg` 做大学符号计算乃至更深 ✅。
|
||||
|
||||
---
|
||||
|
||||
## 2. 两面模型:代数面 vs 计算面
|
||||
|
||||
文档里应能一眼分清「推导」与「动手算」。
|
||||
|
||||
### 2.1 代数面(默认;公式文档)
|
||||
|
||||
| 意图 | 写法(目标) | 语义 |
|
||||
|------|--------------|------|
|
||||
| 引入符号阵 | 见 §3 | 惰性 `MatrixSymbol` |
|
||||
| 加减乘 | `` `C` = `A` + `B` `` · `` `P` = `A` * `B` `` | 建树 + 形状检查 |
|
||||
| 转置 / 逆 | `` `At` = > `A`.T `` · `` `Ai` = > `A`.inv `` | 惰性节点 |
|
||||
| 化简 / 展示 | 见 §4(默认化简策略) | 规则不动点 → ASCII / KaTeX |
|
||||
| 分块 / Kronecker | 表或 `block` / `kron`(可保留具名,但结果仍是公式) | 惰性 |
|
||||
|
||||
**读者感受**:像在抄黑板,而不是在调 `la.mul`。
|
||||
|
||||
### 2.2 计算面(显式步骤;可单独成段)
|
||||
|
||||
| 意图 | 写法 | 语义 |
|
||||
|------|------|------|
|
||||
| 稠密求值 | `` `E` = > `A`.explicit `` / `la.explicit` | 展开数值 |
|
||||
| 分解 | `` `f` = > la.factorize matrix=`A` kind="svd" `` | `linalg_factor` |
|
||||
| 求解 / 最小二乘 | `solve` / `lstsq` | 数值解 |
|
||||
| 度量 | `norm` / `cond` / `rank` / `det`(数值路径) | 标量或条件对象 |
|
||||
| 作图 | `draw` / `show` | SVG / 公式卡 |
|
||||
|
||||
**读者感受**:「于是我们计算 / 画出…」——与纯代数叙述分段书写。
|
||||
|
||||
---
|
||||
|
||||
## 3. 目标作者语法(公式文档优先)
|
||||
|
||||
### 3.1 已落地(v1 中缀 / 方法)
|
||||
|
||||
```markdown
|
||||
*`A` = > la.symbol name="A" rows=2 cols=2*
|
||||
*`B` = > la.symbol name="B" rows=2 cols=2*
|
||||
*`C` = `A` + `B`*
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
*`s` = > `Pt`.simplify*
|
||||
*`t` = > `s`.ascii*
|
||||
```
|
||||
|
||||
数值 `$$` 矩阵可直接参与 `+` / `*`(经插件吸收为稠密叶)。
|
||||
|
||||
### 3.2 目标形态(文档感更强;分期实现)
|
||||
|
||||
**叙事理想(不必一次做完):**
|
||||
|
||||
```markdown
|
||||
# 正规方程
|
||||
|
||||
令 \(A\) 为 \(m\times n\) 设计矩阵,\(b\) 为观测。
|
||||
|
||||
*`AtA` = > `A`.T * `A`* # 或未来更紧凑的 postfix / 混合写法
|
||||
*`xty` = > `A`.T * `b`*
|
||||
*`xhat` = > `AtA`.solve b=`xty`* # 计算面
|
||||
```
|
||||
|
||||
**符号引入(减少 `la.symbol` 噪音)——候选(F2 选定一种):**
|
||||
|
||||
| 候选 | 例 | 利 | 弊 |
|
||||
|------|----|----|-----|
|
||||
| A. 构造糖 | `` `A` = > la.matrix name=A rows=m cols=n `` | 已有 `# matrix` | 仍是调用 |
|
||||
| B. 维数表 | GFM 表声明符号与形状,一行绑定 | 很「文档」 | 需新约定 |
|
||||
| C. `$$` 符号方言 | `$$A_{m\times n}$$` → MatExpr | 最像讲义 | 解析歧义;勿污染标量 formula |
|
||||
| D. 保持 `symbol` + 短别名 | `` `A` = > la.A rows=m cols=n `` | 实现便宜 | 文档感一般 |
|
||||
|
||||
**锁定倾向:** 短期 **A + 默认化简(F1)**;**F2 采用 B(GFM `@` 表 + `la.declare`)**;受限 C(`$$` 符号方言)仍待评估且不得污染核心 formula。
|
||||
|
||||
### 3.3 明确不做(本波语法)
|
||||
|
||||
- 把符号 MatExpr 塞进核心 `formula::Expr`
|
||||
- 发明与 Markdown 列表冲突的行首 `+` 矩阵语法
|
||||
- 用未定义的 `$$矩阵A$$` 伪方言冒充已实现语义
|
||||
|
||||
---
|
||||
|
||||
## 4. 默认化简与「写出即规范」
|
||||
|
||||
### 4.1 策略
|
||||
|
||||
| 操作 | 是否自动 `simplify` | 理由 |
|
||||
|------|---------------------|------|
|
||||
| `ascii` / `latex` / `show` | **是(F1 done)** | 展示面应接近讲义规范形;`raw=True` 可关 |
|
||||
| 中缀 `+` `*` `-` 的构造结果 | **否** | 保留用户书写结构;需要时再化简 |
|
||||
| `.simplify` | 显式不动点 | 文档断言 / 金样 |
|
||||
| `explicit` 前 | 可选先 simplify(F1.1) | 减少无效稠密路径 |
|
||||
|
||||
### 4.2 验收句式(金样)
|
||||
|
||||
```markdown
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
*`t` = > `Pt`.ascii* # F1:无需再 .simplify 即得 B^T*A^T
|
||||
1. `t` == "B^T*A^T"
|
||||
> print text=ok
|
||||
```
|
||||
|
||||
「跑通 + 断言」= 这段公式文档正确。
|
||||
|
||||
---
|
||||
|
||||
## 5. 正确性分层与错误体验
|
||||
|
||||
| 层 | 失败时 | 作者应看到 |
|
||||
|----|--------|------------|
|
||||
| 形状 | `A*B` 列行不配 | 含双方 shape 的硬错误,指向调用点 |
|
||||
| 规则 | 无法化到文档期望形 | 金样失败;或 `ascii` 仍为未化简形(需补规则) |
|
||||
| 插件未加载 | 中缀矩阵运算 | 提示 `ext add linalg` / `ensure_plugin` |
|
||||
| 超维 | `explicit` / 分解 | 护栏错误,建议保持符号 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 与实现现状的对照
|
||||
|
||||
| 能力 | 状态 |
|
||||
|------|------|
|
||||
| MatExpr 惰性树 + R1–R5 / 分块 / kron | done(L1–L3) |
|
||||
| 稠密 / 分解 / 度量 / draw theme | done(L2–L6) |
|
||||
| 中缀 `+` `-` `*` + `# matrix` 方法 | done(v1) |
|
||||
| `ascii`/`latex`/`show` 默认 simplify | **done(F1)** |
|
||||
| 更少噪音的符号引入 | **done(F2:`declare` + 表)** |
|
||||
| 更紧凑转置 / 混合公式书写 | **done(F3:`T_ascii`)** |
|
||||
| `explicit` 前可选 auto-simplify | **done(F3,默认开)** |
|
||||
| public「如何写公式文档」 | **done(F3)** |
|
||||
| 矩阵微积分等 | L7+ / 规则表扩展 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 分期(公式文档面)
|
||||
|
||||
| 阶段 | 内容 | 出口 |
|
||||
|------|------|------|
|
||||
| **F1** | 展示路径默认 simplify;金样「`.T` + `ascii` → 规范形」;设计本文落地 | **done** |
|
||||
| **F2** | 符号引入降噪(选定 §3.2 候选);更新 examples 使其读起来像讲义 | **done**(`declare` + `linalg-transpose`) |
|
||||
| **F3** | 可选 postfix / 链式糖;`explicit` 前可选 auto-simplify;public 短文「如何写公式文档」 | **done** |
|
||||
| **F4+** | 新规则(伴随、多项式矩阵…);矩阵微积分仅当明确需要 | 规则表可测 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 示例叙事(目标文档骨架)
|
||||
|
||||
````markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# 转置反序
|
||||
|
||||
*`A` = > la.symbol name="A" rows=2 cols=3*
|
||||
*`B` = > la.symbol name="B" rows=3 cols=2*
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
|
||||
叙述:\((AB)^\top = B^\top A^\top\)。
|
||||
|
||||
*`t` = > `Pt`.ascii*
|
||||
1. `t` == "B^T*A^T"
|
||||
> print text=identity-ok
|
||||
2. *
|
||||
> print text=identity-fail
|
||||
````
|
||||
|
||||
计算面示例保持 `examples/linalg-least-squares/`(`lstsq` + heatmap),与代数面示例分目录或分章节。
|
||||
|
||||
---
|
||||
|
||||
## 9. 开放问题
|
||||
|
||||
1. **自动 simplify 是否改变 `ascii` 金样**——凡依赖「未化简乘积串」的测试需改期望或改调 `repr_raw`(若提供)。
|
||||
2. **中文 `_type=矩阵` 与展示**——方法链已 retag;view 是否统一显示英文 kind。
|
||||
3. **`$$` 符号方言**——若做,必须经 `from_formula` 扩展,禁止改核心高中 formula 语义。
|
||||
|
||||
---
|
||||
|
||||
## 10. 收束
|
||||
|
||||
`ext/linalg` 的北极星不是「功能最多的矩阵库」,而是:
|
||||
|
||||
> **让大学线性代数(及更深)以可运行公式文档的形式存在于 Marqdo;跑通即在规则集内正确;计算与作图是显式步骤,不淹没代数叙述。**
|
||||
@@ -0,0 +1,345 @@
|
||||
# `ext/linalg` — 公式优先的线性代数扩展
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Draft · L0–L6 + 中缀 v1 · 公式文档面见专文** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
|
||||
| **公式文档面** | [ext-linalg-formula-doc.md](ext-linalg-formula-doc.md)(跑通即正确 · 代数面/计算面) |
|
||||
| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) |
|
||||
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [view.md](view.md) · [ext-quantum-q7.md](ext-quantum-q7.md) |
|
||||
| 安装(规划) | `marqdo ext add linalg`(`linalg` / `线性代数`) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**经典线性代数以「矩阵公式」为一等公民**:抽象表达式可化简、可展示、可选求值;稠密数值与分解图走 ABI 插件——**不**并入 `lib/math`,**不**挂在 `ext/quantum` 作者面。
|
||||
|
||||
作者面北极星见 **[ext-linalg-formula-doc.md](ext-linalg-formula-doc.md)**:跑通即正确;代数面像讲义,计算面是显式步骤。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标与非目标
|
||||
|
||||
### 1.1 目标
|
||||
|
||||
1. **公式类扩展**:在现有标量 `formula` 之上,引入 **矩阵表达式(MatExpr)**——`MatrixSymbol`、乘加、转置、逆、迹、行列式、分块、Kronecker——默认**不展开**。
|
||||
2. **大规模优化**:形状检查 + 重写规则 + 惰性求值 + 分解对象复用(见 §5)。
|
||||
3. **易于展示**:KaTeX 公式卡、结构 SVG(SVD/QR/消元/特征)、数值热力图;CLI 可断言的 ASCII。
|
||||
4. **文档即实验**:GFM 表声明矩阵 / 步骤;`.mq.md` 可读可跑。
|
||||
|
||||
### 1.2 非目标(首版)
|
||||
|
||||
| 不做 | 原因 |
|
||||
|------|------|
|
||||
| 塞进 `lib/math` | 高中标量范围已锁定;大学 LA 属官方 ext |
|
||||
| 复用 `quantum.*` 作者 API | 领域混淆;量子 Q7 保持量子语义 |
|
||||
| 完整 SymPy / Mathematica | 规则表可控子集即可 |
|
||||
| 稀疏格式 / GPU / 分布式 | 超出文档语言定位 |
|
||||
| 矩阵微积分闭式(Jacobian 积木) | 记入路线图远期 |
|
||||
| 在 `ext/**` 调 `host_*` | 硬约束;数值走插件名 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层架构
|
||||
|
||||
```text
|
||||
作者 .mq.md
|
||||
│ import la:ext/linalg/linalg.mq.md
|
||||
▼
|
||||
L1 官方 ext(GFM + ## 包装,中英分文件)
|
||||
│ plugin.load name=linalg
|
||||
▼
|
||||
plugins/linalg(ABI v2)
|
||||
├── matexpr:符号树构造 / 重写 / latex
|
||||
├── dense:稠密 f64(可选复数)运算与分解
|
||||
└── draw:结构 SVG / heatmap
|
||||
│
|
||||
▼(可选)
|
||||
核心 Value::Formula 仅保留「数值矩阵字面量」现状;
|
||||
符号 MatExpr 以 **map `_type=matrix`(中文构造为 `矩阵`)** 承载,避免撑爆高中 formula AST;遗留标签 `linalg_expr` / `linalg_dense` 仍可解析。
|
||||
```
|
||||
|
||||
### 2.1 为何 MatExpr 不直接塞进 `formula::Expr`
|
||||
|
||||
| 方案 | 利 | 弊 | 决策 |
|
||||
|------|----|----|------|
|
||||
| 扩展 `formula::Expr` | 与 `$$` 一体 | 核心膨胀;高中/大学边界糊 | ❌ |
|
||||
| 插件侧表达式 + L1 对象 | 核心干净;可独立发版 | 需稳定 `_type` 与 latex 桥 | ✅ **采用** |
|
||||
| 仅 list-of-list 数值 | 简单 | 无法公式优化与符号展示 | ❌ 仅作 `explicit` 结果 |
|
||||
|
||||
**既有** `formula::Expr::Matrix`(数值 `$$`)继续服务量子门 / 小例子;`ext/linalg` 通过 `la.matrix` / `la.from_formula` 吸收为稠密叶子。
|
||||
|
||||
### 2.2 与量子的边界
|
||||
|
||||
| | `ext/linalg` | `ext/quantum` Q7 |
|
||||
|--|--------------|------------------|
|
||||
| 域 | 经典实/复矩阵 | 态 / 密度 / Pauli |
|
||||
| Kronecker | 经典 ⊗ | 复合量子系统 |
|
||||
| 图 | SVD/QR/GE/heatmap | hinton/city/qsphere/… |
|
||||
| 复用 | 插件**私有**可共享 Jacobi/SVD 代码 | 作者面 API **分离** |
|
||||
|
||||
---
|
||||
|
||||
## 3. 运行时对象(锁定草案)
|
||||
|
||||
全部经插件构造,L1 返回 **map**(`_type` 稳定,金样可断言):
|
||||
|
||||
| `_type`(英) | 中文标签 | 字段(最小) | 含义 |
|
||||
|---------------|----------|--------------|------|
|
||||
| `linalg_expr` | `线性式` | `repr`(S-expr 或内部 id)、`shape`=`[m,n]` 或符号维、`latex`、`ascii` | 抽象矩阵公式 |
|
||||
| `linalg_dense` | `稠密阵` | `rows`, `cols`, `data`(行主 list[list])、`dtype`=`real`\|`complex` | 显式数值 |
|
||||
| `linalg_factor` | `分解` | `kind`=`lu`\|`qr`\|`svd`\|`eig`\|`chol`,因子字段,`latex`,可选 `svg` | 分解结果 |
|
||||
| `linalg_svg` | — | `kind`, `svg` 文本 | 与 quantum_svg 同构展示约定 |
|
||||
| `linalg_solve` | `求解` | `x`, `residual`, `method` | 线性系 / 最小二乘 |
|
||||
|
||||
形状:`shape` 允许整数或符号维名(字符串 `"n"`);不相容 → 硬错误。
|
||||
|
||||
---
|
||||
|
||||
## 4. 作者面 API(英文 `ext/linalg/linalg.mq.md`)
|
||||
|
||||
中文镜像:`ext/linalg/线性代数.mq.md`(`矩阵` / `化简` / `求值` / `绘图`…)。
|
||||
|
||||
### 4.1 构造
|
||||
|
||||
```markdown
|
||||
# matrix
|
||||
|
||||
## symbol
|
||||
+ `name`
|
||||
+ `rows`
|
||||
+ `cols`
|
||||
# → linalg_expr MatrixSymbol
|
||||
|
||||
## eye / zeros / ones / diag
|
||||
+ …
|
||||
|
||||
## from_list
|
||||
+ `data` # list[list] 或 table
|
||||
|
||||
## from_formula
|
||||
+ `formula` # 吸收 Value::Formula Matrix 字面量
|
||||
|
||||
## block
|
||||
+ `blocks` # 表或嵌套 list of expr
|
||||
```
|
||||
|
||||
文档写法偏好:
|
||||
|
||||
````markdown
|
||||
`A` = > la.symbol name=A rows=n cols=n
|
||||
|
||||
`b` =
|
||||
$$
|
||||
\begin{pmatrix}1\\0\\0\end{pmatrix}
|
||||
$$
|
||||
|
||||
*`b` = > la.from_formula formula=`b` *
|
||||
````
|
||||
|
||||
作者面优先顶层 `la.symbol` / `la.mul`(`la.matrix.symbol` 无接收者会硬错误,见 [module-namespace.md](module-namespace.md) §4.3)。
|
||||
### 4.2 公式代数(返回 `linalg_expr`,惰性)
|
||||
|
||||
| 英文 | 中文 | 语义 |
|
||||
|------|------|------|
|
||||
| `mul` / `add` / `sub` | `乘` / `加` / `减` | 形状检查后建树 |
|
||||
| `transpose` / `T` | `转置` | |
|
||||
| `inv` | `逆` | 符号逆;不立即求数值 |
|
||||
| `pow` | `幂` | 整数幂 |
|
||||
| `trace` / `det` | `迹` / `行列式` | 可得到标量 expr 或数值 |
|
||||
| `kron` | `克罗内克` | **禁止**默认 expand |
|
||||
| `simplify` | `化简` | 应用 §5 规则集 |
|
||||
| `collapse` | `分块化简` | 对标 `block_collapse` |
|
||||
| `latex` / `ascii` | `乳胶` / `文本` | 展示字符串 |
|
||||
| `shape` | `形状` | |
|
||||
|
||||
链式 / 中缀(v1 已落地):
|
||||
|
||||
```markdown
|
||||
*`C` = `A` + `B`*
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
*`s` = > `Pt`.simplify*
|
||||
```
|
||||
|
||||
运行时对双方为 `matrix` / `矩阵` / 数值 `$$` 矩阵 / 遗留 `linalg_expr` 的 `+` `-` `*` 分派到插件;结果保留左操作数 `_type` 以便中英方法链。
|
||||
### 4.3 求值与分解(热路径 → 稠密)
|
||||
|
||||
| 英文 | 说明 |
|
||||
|------|------|
|
||||
| `eval` / `explicit` | 符号树 + 绑定表 → `linalg_dense`;超维硬错误 |
|
||||
| `factorize` | `kind=lu\|qr\|svd\|eig\|chol` → `linalg_factor` |
|
||||
| `solve` | `A`,`b`;或 `factor` + `b` |
|
||||
| `lstsq` | 最小二乘 |
|
||||
| `rank` / `norm` / `cond` | 数值度量 |
|
||||
| `matmul` | 稠密乘(已 explicit 时) |
|
||||
|
||||
维数上限(草案,可配置):
|
||||
|
||||
| 操作 | 默认上限 |
|
||||
|------|----------|
|
||||
| `explicit` 稠密元素总数 | \(n\cdot m \le 10^4\)(如 100×100) |
|
||||
| SVD / eig 方阵边长 | \(\le 64\)(与 quantum 密度同级) |
|
||||
| 结构 SVG(无元素) | 边长示意可达数百(只画框) |
|
||||
| KaTeX 完整数字阵 | \(\le 8\times 8\);更大只出摘要 + 结构图 |
|
||||
|
||||
### 4.4 展示
|
||||
|
||||
| 英文 | `kind` | 说明 |
|
||||
|------|--------|------|
|
||||
| `show` | — | 写入 view:优先 `latex` 公式卡 |
|
||||
| `draw` | `structure` | 形状/分块矩形(drawmatrix 风格) |
|
||||
| `draw` | `heatmap` / `hinton` | 数值幅度 |
|
||||
| `draw` | `svd` / `qr` / `ge` / `eig` | 分解结构图(对标 LAFigureSpecs) |
|
||||
| `draw` | `path`= | 可选落盘 SVG |
|
||||
|
||||
`show` 应对符号式**始终可用**(无需 `eval`)。
|
||||
|
||||
### 4.5 最小可运行示例(设计验收叙事)
|
||||
|
||||
````markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`A` = > la.symbol name=A rows=3 cols=3 *
|
||||
*`x` = > la.symbol name=x rows=3 cols=1 *
|
||||
*`b` = > la.mul a=`A` b=`x` *
|
||||
|
||||
*`s` = > la.simplify expr=`b` *
|
||||
> la.show expr=`s`
|
||||
|
||||
`M` =
|
||||
$$
|
||||
\begin{bmatrix}2&0\\0&3\end{bmatrix}
|
||||
$$
|
||||
|
||||
*`M` = > la.from_list data=[[2,0],[0,3]] *
|
||||
*`f` = > la.factorize matrix=`M` kind=eig *
|
||||
> la.draw factor=`f` kind=eig path=eig.svg
|
||||
````
|
||||
---
|
||||
|
||||
## 5. 公式重写与「大规模优化」(核心)
|
||||
|
||||
### 5.1 原则
|
||||
|
||||
1. **构造便宜,展开昂贵**——乘加只分配节点。
|
||||
2. **形状是类型系统**——`(m×k)·(k×n)` 合法;否则错误指向调用点。
|
||||
3. **化简是规则不动点**——有限规则表,可测、可文档化。
|
||||
4. **expand 显式开启**——`expand=True` 才对 Kronecker / 多项式矩阵做爆炸性展开。
|
||||
5. **数值路径旁路符号**——已 `explicit` 的叶子用稠密核,不再走规则。
|
||||
|
||||
### 5.2 v1 规则集(最小够用)
|
||||
|
||||
| ID | 规则 | 例 |
|
||||
|----|------|-----|
|
||||
| R1 | 单位元 | `I*A → A`,`A*I → A`,`A+0 → A` |
|
||||
| R2 | 双逆 | `(A^{-1})^{-1} → A` |
|
||||
| R3 | 转置反序 | `(AB)^\top → B^\top A^\top`,`(A^\top)^\top → A` |
|
||||
| R4 | 逆转置 | `(A^{-1})^\top → (A^\top)^{-1}` |
|
||||
| R5 | 结合扁平 | `MatMul` 链扁平化 |
|
||||
| R6 | 分块塌缩 | 对标 `block_collapse`(乘/加在块级分配) |
|
||||
| R7 | Kronecker 结合 | `(A⊗B)⊗C → A⊗B⊗C`;**不**展开成元素 |
|
||||
| R8 | 标量提出 | `c*(A+B) → c*A+c*B`(可选;默认关以免树变宽) |
|
||||
|
||||
### 5.3 数值侧优化
|
||||
|
||||
| 策略 | 说明 |
|
||||
|------|------|
|
||||
| `factorize` 一次 | 多 RHS `solve` 复用 |
|
||||
| 小阵专用核 | 2×2 / 3×3 闭式逆 / det(教学友好、可对照公式) |
|
||||
| 复杂度护栏 | 超限错误信息建议「保持符号 / 降维 / 分块」 |
|
||||
| 禁止静默降精度 | 病态 `cond` 可警告(stderr 或结果字段) |
|
||||
|
||||
---
|
||||
|
||||
## 6. 展示设计(效果)
|
||||
|
||||
### 6.1 通道
|
||||
|
||||
| 通道 | 符号 MatExpr | 稠密 | 分解 |
|
||||
|------|--------------|------|------|
|
||||
| view Structure | KaTeX `latex` 卡 | 小阵 KaTeX;大阵摘要 | 公式 + 可选 SVG |
|
||||
| view Execution plots | — | heatmap SVG | `kind=svd|…` SVG |
|
||||
| CLI `print` | `ascii` | `[[…],…]` 或摘要 | `svd(U,S,V)` 摘要 |
|
||||
| writeback | 可选记录 latex | 可选 | 可选 |
|
||||
|
||||
### 6.2 LaTeX 约定
|
||||
|
||||
- 符号:`A`,`A^{\top}`,`A^{-1}`,`AB`,`A \otimes B`
|
||||
- 数值小阵:`\begin{bmatrix}…\end{bmatrix}`
|
||||
- 分块:`\begin{bmatrix} A & B \\ C & D \end{bmatrix}`
|
||||
- 喂给既有 view:与 `formula-card` / KaTeX 同源路径(L1 `show` → `host_query("record_plot")` 或扩展「record_math」若已有;无则复用 writeback + plot 列表)
|
||||
|
||||
### 6.3 结构 SVG(教学主视觉)
|
||||
|
||||
对标 LAFigureSpecs / drawmatrix,**不**依赖 Matplotlib:
|
||||
|
||||
| `kind` | 画什么 |
|
||||
|--------|--------|
|
||||
| `structure` | 矩形块 + 标签(零块灰色) |
|
||||
| `svd` | \(U\Sigma V^{\top}\) 块布局 + 秩分隔 |
|
||||
| `qr` | 瘦/胖 QR 示意 |
|
||||
| `ge` | 消元后上三角高亮 |
|
||||
| `eig` | \(A=PDP^{-1}\) 或谱列表 + 对角 |
|
||||
| `heatmap` | 单元填色(实数蓝红;复数幅值) |
|
||||
|
||||
主题:`theme=light|dark|bw`(与 quantum Q8 令牌对齐;默认 `light`)。
|
||||
|
||||
---
|
||||
|
||||
## 7. L1 / 插件 / CLI 约定
|
||||
|
||||
1. **`ext/linalg/**` 禁止 `host_*`**;只调 `plugin.*` 注册名(如 `linalg_simplify`)。
|
||||
2. **中英分文件**,CATALOG 双 id:`linalg` / `线性代数`。
|
||||
3. **`marqdo ext add linalg`**:与 web/agent/quantum 相同——优先 Release 预编译 native zip。
|
||||
4. **金样**:离线、确定性;SVG 断言含关键子串或稳定 hash 前缀。
|
||||
5. **依赖**:插件内自研稠密核(或慎重引入单一 crate,如 `nalgebra`——**实现期再议**;设计默认「可自研小维 + 可选 crate」)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 分期(摘要;细节见路线图)
|
||||
|
||||
| 阶段 | 交付 |
|
||||
|------|------|
|
||||
| **L0** | CATALOG + ping + L1 `ensure_plugin` |
|
||||
| **L1** | `matrix.symbol` / dense 构造 / `mul`·`T`·`inv` 树 + `simplify` R1–R5 + `latex`/`show` |
|
||||
| **L2** | `explicit` / 小阵运算 / `solve` / `det`·`trace` 数值 |
|
||||
| **L3** | 分块 + `collapse`;Kronecker 惰性 |
|
||||
| **L4** | `factorize` LU/QR/SVD/eig + 结构 SVG |
|
||||
| **L5** | heatmap/hinton;examples + public 文档 + skill 摘要 |
|
||||
| **L6+** | 矩阵微积分 / 更大 BLAS(仅当用户明确要求);复数全路径算子 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 验收标准(设计级)
|
||||
|
||||
1. 符号式 `(AB)^\top` 经 `simplify` 得 `B^\top A^\top`,**不**产生稠密数据。
|
||||
2. 不相容形状在符号 `mul` 即失败。
|
||||
3. `$$` 数值阵 → `from_formula` → `factorize kind=eig` → view 含 SVG 或 latex。
|
||||
4. Kronecker 默认不 expand;显式 `expand` 受维数护栏。
|
||||
5. 中英 L1 金样各至少一条;`ext add linalg` 路径文档化。
|
||||
6. 与 `ext/quantum` 无作者面符号冲突。
|
||||
|
||||
---
|
||||
|
||||
## 10. 风险与开放问题
|
||||
|
||||
| 项 | 备注 |
|
||||
|----|------|
|
||||
| MatExpr 序列化 | 金样 / write:倾向可打印 S-expr 或稳定 latex+shape,避免不透明指针跨进程 |
|
||||
| 与标量 `formula` 混运算 | v1:标量只作 `c*A` 系数;`det` 结果若符号则另型或降为 `formula` 文本 |
|
||||
| nalgebra 等依赖 | 实现 L2 时评估二进制体积与 ABI 体积 |
|
||||
| record_math vs plot | 若仅 SVG/KaTeX 字符串,可先复用 plot/writeback |
|
||||
|
||||
---
|
||||
|
||||
## 11. 一句话(收束)
|
||||
|
||||
**`ext/linalg` 让线性代数公式保持可优化的表达式,用规则与结构图服务文档阅读,用受控稠密核服务验算——公式优先,数值可选,展示分层。**
|
||||
@@ -210,7 +210,7 @@
|
||||
- >6 qubit 稠密 ρ 的谱 / Hinton(请用态向量 API)
|
||||
- Matplotlib / WebGL / 交互拖拽
|
||||
- 量子线性系统算法(HHL)、QSVT 电路构造
|
||||
- 把线性代数并入 `lib/math`
|
||||
- 把线性代数并入 `lib/math`(经典公式优先的 LA 见规划 [ext-linalg.md](ext-linalg.md),作者面与 quantum 分离)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
# 解决 1:路由与 `/admin` 前缀可让出
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §1](../../research/ext-web-customization-limits.md#1-路由与路径被框架强占) |
|
||||
| 优先级 | **P0** · 波次 **C0** |
|
||||
| 触点 | `plugins/web/src/lib.rs`(`normalize_route_path`、`web_app_new`、redirect)· `plugins/web/src/http.rs`(admin 路由挂载、login redirect)· `ext/web/web.mq.md` / `网页.mq.md` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 关闭内置后台后,**整段前缀可被站点路由占用**(含自研 `/admin`)。
|
||||
2. 开启内置后台时,前缀**可配置**(默认仍 `/admin`),登录成功/登出落地页可配置。
|
||||
3. `app.route` / `app.redirect` 只禁止**当前生效**的框架保留段,不再永久霸占 `/admin`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
```markdown
|
||||
*应用 = > web.app page=`首页` db=`库` admin=False*
|
||||
|
||||
# 或:仍用内置 CRUD,但挂到旁路前缀 + 自定义回跳
|
||||
*应用 = > web.app page=`首页` db=`库` admin=True*
|
||||
*应用 = > `应用`.auth users=`用户表` admin_prefix="/desk" login_redirect="/desk" logout_redirect="/desk/login"*
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 含义 |
|
||||
|------|------|------|
|
||||
| `admin` / `后台` | `False` | `False`:**不注册**任何内置 admin HTTP 路由 |
|
||||
| `admin_prefix` / `后台前缀` | `"/admin"` | 内置 CRUD + 登录页挂载根;仅 `admin=True` 时生效 |
|
||||
| `login_redirect` / `登录回跳` | `{admin_prefix}` | 登录成功 303 目标 |
|
||||
| `logout_redirect` / `登出回跳` | `{admin_prefix}/login` | 登出后目标 |
|
||||
|
||||
中文别名与英文一一对应,写进 `网页.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| `normalize_route_path(app)` | reserved 列表改为:`/_form`、`/_part`、`/static` + **当前** `admin_prefix`(仅当 `admin=True`) |
|
||||
| `listen` 路由表 | `admin=False` → **不** `.route("/admin…")`;为真则用 `admin_prefix` 拼路径 |
|
||||
| `admin_login_post` / `admin_logout` | 使用配置的 redirect,禁止写死 `"/admin"` |
|
||||
| `web_app_redirect` | 校验目标时用同一套动态 reserved,允许指向已让出的 `/admin` |
|
||||
| disabled 文案路径 | 删除「挂路由但只显示 Admin is disabled」;无路由则 404 或落入站点自定义页 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 缺省参数下:现有 `examples/web-site`、`web-net-site`、`marqdo-blog` 行为不变(仍 `/admin` + 跳 `/admin`)。
|
||||
- 文档明确:`admin=False` 后若仍要登录能力,用 §3 的通用 `auth`/`gate`,不必再依赖内置 admin 壳。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 金样 / 手工 | 期望 |
|
||||
|-------------|------|
|
||||
| `admin=False` + `route path="/admin/news"` | 注册成功;GET 渲染站点页,**不是** Admin is disabled |
|
||||
| `admin_prefix="/desk"` | 内置登录在 `/desk/login`;成功跳 `login_redirect` |
|
||||
| 默认 `admin=True` 无新参数 | 与现网一致 |
|
||||
| `redirect` 到已让出的 `/admin` | 允许 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 已落地
|
||||
|
||||
~~继续用 `/desk` 旁路 + JS 调 `/admin/login`。~~
|
||||
|
||||
**C0 已落地(2026-09):** `admin=False` 可直接 `route path="/admin/…"`;或 `admin=True` + `admin_prefix="/desk"` + `login_redirect` / `logout_redirect`。见金样 `tests/ext/web-c0-admin-prefix.mq.md`。
|
||||
@@ -0,0 +1,72 @@
|
||||
# 解决 2:`SHELL_CSS` 可关 / 可分层
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §2](../../research/ext-web-customization-limits.md#2-内置-shell_css-难以彻底覆盖) |
|
||||
| 优先级 | **P1** · 波次 **C2** |
|
||||
| 触点 | `plugins/web/src/render.rs`(`SHELL_CSS`、`<style>` 拼接)· page/app 元数据 · `ext/web` 样式装配 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 站点主题可选择:**不要**框架栅格/卡片默认,或只要 reset 级变量。
|
||||
2. 壳 CSS 与主题 CSS 的级联顺序**可声明、可文档化**。
|
||||
3. 默认仍注入完整壳(兼容旧站);新主题显式 `shell_css=off` 即可干净起步。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
```markdown
|
||||
*应用 = > web.app page=`首页` … shell_css="minimal"*
|
||||
# 或页面级覆盖
|
||||
*页 = > `页`.meta …* # 或 page 选项 shell_css=
|
||||
```
|
||||
|
||||
| 值 | 行为 |
|
||||
|----|------|
|
||||
| `full`(默认) | 现网 `SHELL_CSS` 全文 |
|
||||
| `minimal` | 仅 `:root` 变量 + `body` margin/字体;**不含** `has-sidebar` 双列栅格与卡片表单皮肤 |
|
||||
| `off` / `none` | 不注入框架壳样式;只输出站点 `style` / 外链 CSS |
|
||||
|
||||
级联顺序锁定为文档约定:
|
||||
|
||||
1. (可选)框架 `SHELL_CSS`
|
||||
2. 站点全局 style 表 / `site.css`
|
||||
3. 页面级 style
|
||||
|
||||
禁止再出现「主题写在 extra,却被同特异性壳规则在小屏打穿且无媒体查询」而无开关可关的情况。
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| 拆分 `SHELL_CSS` | `SHELL_VARS` / `SHELL_LAYOUT` / `SHELL_WIDGETS` 三段;`full`=`all`,`minimal`=vars(+极简 layout) |
|
||||
| `render` 读 `app.shell_css` / `page.shell_css` | 页面覆盖应用 |
|
||||
| 为 `has-sidebar` 布局加基础媒体查询 | 即使 `full`,小屏改为单列(减轻幽灵双列);`minimal`/`off` 不负责响应式 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 默认 `full`:视觉与现网一致。
|
||||
- Tutorial 增加一节「品牌主题请用 `shell_css=minimal|off`」。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| `shell_css=off` + 站点只写单列 grid | 响应里**无** `grid-template-columns:14rem` |
|
||||
| `minimal` | 有 CSS 变量;无 `.content.cards article` 边框默认(或等价皮肤段) |
|
||||
| 默认示例站 | HTML 仍含完整壳 CSS |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 已落地
|
||||
|
||||
**C2 已落地(2026-09):** `shell_css=full|minimal|off`;页面/应用可设;`full` 含 `@media (max-width:720px)` 单列。金样 `tests/ext/web-c2-shell-layout.mq.md`。
|
||||
@@ -0,0 +1,72 @@
|
||||
# 解决 3:鉴权 / 门禁可配置且行为一致
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §3](../../research/ext-web-customization-limits.md#3-鉴权--门禁模型偏固定) |
|
||||
| 优先级 | **P0** · 波次 **C1**(依赖 [01](01-routes-and-admin-prefix.md) 的 prefix) |
|
||||
| 触点 | `plugins/web/src/http.rs`(`rbac_middleware`、`path_matches`、login 表单)· `lib.rs`(`web_app_auth` / `web_app_gate`)· `ext/web` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. **未登录策略一致**:可配置 `redirect`(303 登录)或 `forbid`(403),对任意 gate 路径生效,不再「仅 `/admin*` 会跳登录」。
|
||||
2. **匹配语义清晰**:支持精确路径、前缀、以及排除列表;`/desk` 默认**不**误伤 `/desk/login`。
|
||||
3. 默认 admin gate 使用 **路径段边界**(`/admin` 与 `/admin/…`),不匹配 `/admin-publish`。
|
||||
4. 登录 URL、表单 `action`、成功/失败回跳均可配置(与 C0 对齐)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.auth users=`用户表` login_path="/desk/login" login_redirect="/desk"*
|
||||
*应用 = > `应用`.gate path="/desk" roles="admin" match="prefix" on_deny="redirect" exclude="/desk/login"*
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `login_path` | 登录页 URL(GET 表单 + POST 处理);默认 `{admin_prefix}/login` |
|
||||
| `match` | `exact` \| `prefix`(默认对自定义 gate 建议 `prefix` + `exclude`) |
|
||||
| `on_deny` | `redirect` \| `forbid`;`redirect` 时跳 `login_path`(可带 `?next=`) |
|
||||
| `exclude` | 逗号分隔或表列:匹配前缀时放行的路径 |
|
||||
|
||||
`auth` 注册默认 gate 时:
|
||||
|
||||
- 使用 `{admin_prefix}` + 段边界,**不要** `starts_with("/admin")` 裸前缀。
|
||||
- 自动把 `login_path` 加入放行列表。
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| `path_matches` | 增加 `exact`;`prefix` 要求下一字符为 `/` 或结尾;可选 exclude |
|
||||
| `rbac_middleware` | 按 gate 的 `on_deny` 分支;通用放行 `login_path`,不写死 `/admin/login` |
|
||||
| 登录 HTML | `action={login_path}`;hidden `next` 可选 |
|
||||
| Session/CSRF | 短期仍用框架实现;文档标明字段名;中期再开放 `login_form` 自定义字段映射(非本波次必做) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 未传新字段:行为对齐现网(`/admin*` → redirect 登录;其它自定义 gate → 403)。
|
||||
- 新增金样:`/desk` gate + `/desk/login` 可匿名打开。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| visitor 访问 `/desk`(`on_deny=redirect`) | 303 → `/desk/login`,不是 403 |
|
||||
| visitor 访问 `/desk/login`(exclude) | 200 登录页 |
|
||||
| `/admin-publish` 无显式 gate | **不**被默认 admin gate 拦住 |
|
||||
| 旧站仅 `app.auth` | 仍保护 `/admin*` |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 已落地
|
||||
|
||||
**C1 已落地(2026-09):** `auth` 默认段边界 prefix + `on_deny=redirect` + 排除 `login_path`;自定义 `gate` 可设 `match` / `on_deny` / `exclude`。金样 `tests/ext/web-c1-gates.mq.md`;单元测试 `http::gate_tests`。
|
||||
@@ -0,0 +1,69 @@
|
||||
# 解决 4:样式表作者体验
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §4](../../research/ext-web-customization-limits.md#4-样式作者体验受限) |
|
||||
| 优先级 | **P2** · 波次 **C3** |
|
||||
| 触点 | 表单元格表达式(T5)· `ext/web` style 装配 · 教程 / Skill · 可选校验 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 含 `/`、`,`、括号的 CSS 值**不易被静默算坏**。
|
||||
2. 复杂选择器 / `@keyframes` / 多层 media 有**官方推荐写法**(表内 vs 外链 vs raw 块)。
|
||||
3. 与壳 CSS 的层叠关系在文档中一句话写清(并链到 [02](02-shell-css.md))。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API / 约定(草案)
|
||||
|
||||
### 2.1 立即固化的文档约定(可不改代码)
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| 含 `/` 的值必须引号 | `"1 / 5"`、`"image/png"`(已有;Skill/教程加醒目反例) |
|
||||
| 复杂皮肤优先外链 | `static/theme.css` + `page.head` / `app.icons` 同类资源表 |
|
||||
| `@keyframes` / 长 media | 放外链 CSS,不塞进 GFM 单元格 |
|
||||
| 调试 | `shell_css=off` 后只看主题文件,避免同页双源 |
|
||||
|
||||
### 2.2 产品增强(C3)
|
||||
|
||||
| 能力 | 说明 |
|
||||
|------|------|
|
||||
| `style` 装配时对可疑单元格告警 | 未加引号且含 `/` → listen/assemble 警告或硬错误(可开关) |
|
||||
| 可选 `##` raw CSS 块绑定 | 例如页面附属 ````css` 具名块,**不经**表表达式求值 |
|
||||
| 文档示例 | `min-width` + `max-width` 外链表;引用 [table-cell-expressions.md](../table-cell-expressions.md) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件 / 核心改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| web style 编译 | 可选 `strict_css_cells=True`:裸 `/` 报错 |
|
||||
| (可选)`web_page_css_raw` | 把文本 CSS 追加到页面,跳过 T5 |
|
||||
| Skill `marqdo` / tutorial 14 | 增加「样式踩坑」小节 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 默认不硬错误(避免打碎旧表);新 scaffold 默认 `strict_css_cells` 或文档强制引号。
|
||||
- 不把完整 CSS 语法塞进表格方言——复杂内容走文件。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| 文档反例 `grid-column` 裸 `1 / 5` | 在 strict 模式下失败或警告 |
|
||||
| 外链 `theme.css` + `shell_css=off` | 无壳栅格串扰 |
|
||||
| 现有 web 示例 | 默认模式仍绿 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 workaround
|
||||
|
||||
全部敏感值加引号;响应式与 keyframes 只写在 `static/*.css`;小屏问题优先关壳([02](02-shell-css.md))再调主题。
|
||||
@@ -0,0 +1,85 @@
|
||||
# 解决 5:页面壳与插槽松绑
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §5](../../research/ext-web-customization-limits.md#5-页面壳与插槽约定僵硬) |
|
||||
| 优先级 | **P1** · 波次 **C2/C4** |
|
||||
| 触点 | `plugins/web/src/render.rs`(body class、四区 HTML)· page 槽位装配 · nav 组件表 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 作者可选**非侧栏栅格**布局,而不必用 CSS 硬怼掉 `has-sidebar`。
|
||||
2. 侧栏存在 ≠ 强制桌面双列;提供 stacked / bare 等预设。
|
||||
3. 为「条件导航」留扩展点(先文档 + 简单 hook,完整运行时条件可后置)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
```markdown
|
||||
*首页 = > web.page … layout="stacked"*
|
||||
*应用 = > web.app page=`首页` … layout="bare"*
|
||||
```
|
||||
|
||||
| `layout` | DOM / class | 说明 |
|
||||
|----------|-------------|------|
|
||||
| `sidebar`(默认,有 side 槽时) | `body.has-sidebar` | 现网行为 |
|
||||
| `stacked` | `body.layout-stacked`;side 在 main 上或折叠区 | 单列流式,适合杂志/营销 |
|
||||
| `bare` | 无 top/side/foot 强制栅格;只渲染 `main`(+ 显式槽) | 登录页、落地页 |
|
||||
| `rail`(可选) | 保留站点已有 `has-rail` 约定并文档化 | 避免「只有首页有 class」 |
|
||||
|
||||
规则:**有 side 组件但 `layout=stacked|bare` 时,不自动加 `has-sidebar`。**
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| `render` 读 `page.layout` / `app.layout` | 决定 body class 与 HTML 骨架 |
|
||||
| `SHELL_LAYOUT`(见 [02](02-shell-css.md)) | 为 `layout-stacked` / `layout-bare` 提供最小样式;`shell_css=off` 时不注入 |
|
||||
| Nav 表 | 短期保持声明式;文档说明「条件项用两套 nav 组件 + 媒体查询隐藏」 |
|
||||
| 中期 hook(非阻断) | `navigate` 已有字段可扩展 `when`/`media` 列(单独 RFC) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 未设 `layout`:有 side → 与现网 `has-sidebar` 相同。
|
||||
- 金样增加 `layout=bare` 登录页(可与 C0 自研 `/desk/login` 共用)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| 有 side + `layout=stacked` | body **无** `has-sidebar`;无 `14rem` 双列(在 full 壳下用 stacked 规则) |
|
||||
| `layout=bare` | 输出不含 `<aside class="side">`(或 empty 不占栅格) |
|
||||
| 默认站 | 不变 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 已落地
|
||||
|
||||
**C2 已落地(2026-09):** `layout=sidebar|stacked|bare|rail`;有 side 时 `stacked`/`bare` 不再强制 `has-sidebar`。金样 `web-c2-shell-layout`。
|
||||
|
||||
**C4 已落地(2026-09):** 导航 / 侧栏 / 页脚绑定表可选列:
|
||||
|
||||
| 列 | 说明 |
|
||||
|----|------|
|
||||
| `媒体` / `media` | CSS media;不匹配时 `display:none`(生成 `nav-mq-*` + `@media not …`) |
|
||||
| `当` / `when` | `hide` 省略;`auth` / `guest` 按登录态过滤;空 = 总是显示 |
|
||||
|
||||
```markdown
|
||||
| 属性 | 值 | 样式 | 媒体 | 当 |
|
||||
|------|-----|------|------|-----|
|
||||
| Home | / | | | |
|
||||
| Menu | /m | | (max-width: 720px) | |
|
||||
| Admin | /admin | | | auth |
|
||||
| Login | /login | | | guest |
|
||||
```
|
||||
|
||||
Listen 渲染时写入 `_logged_in` / `_nav_user`(来自 session)。离线 `page.render` 可自行 `table.put` `_logged_in`。金样 `web-c4-nav-when`。
|
||||
@@ -0,0 +1,67 @@
|
||||
# 解决 6:后台 CRUD 与表单能力边界
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §6](../../research/ext-web-customization-limits.md#6-后台-crud-与表单能力边界) |
|
||||
| 优先级 | **P3** · 随 C0 文档化;增强可选 |
|
||||
| 触点 | `plugins/web/src/http.rs` / `form.rs`(内置 admin)· 站点自研页 + `db.*` · `/_form` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. **产品叙事澄清**:内置 `/admin`(或可配置前缀)= 通用表浏览器,**不是** CMS;关则彻底让路(见 [01](01-routes-and-admin-prefix.md))。
|
||||
2. 自研后台的推荐路径写清楚:`page` + `form` + `db` + gate,而不是改插件壳。
|
||||
3. 对「链接前缀 / new / edit」给出约定或薄辅助,减少前端状态机拼装。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API / 文档(草案)
|
||||
|
||||
### 2.1 推荐架构(文档为主)
|
||||
|
||||
| 需求 | 做法 |
|
||||
|------|------|
|
||||
| 产品级编辑器、专栏联动 | 自研 `# page` + 组件;写库用 `db.insert`/`update`;鉴权用 `gate` |
|
||||
| 简单表维护 | 开 `admin=True`(可换前缀) |
|
||||
| 关内置仍要 CRUD | 自研列表/编辑页;**不要**依赖 disabled 壳 |
|
||||
|
||||
### 2.2 可选薄增强(非 CMS)
|
||||
|
||||
| 能力 | 说明 |
|
||||
|------|------|
|
||||
| `form` 支持 `mode=new\|edit` 查询参数约定 | 文档 + 示例;必要时 `web.form` 读 `id`/`new` |
|
||||
| `list` 组件 `link_prefix` | 已有则补示例;缺失则加一列「详情路径模板」 |
|
||||
| Markdown 字段 | 继续「存库 + 前台渲染」;分栏编辑器保持外挂 JS(明确不做进 ABI) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 优先级 |
|
||||
|------|--------|
|
||||
| C0:disabled 不占路径 | 必需(属 [01](01-routes-and-admin-prefix.md)) |
|
||||
| 示例 `examples/web-custom-desk/` | 展示自研列表/编辑,零内置 admin |
|
||||
| form 查询参数助手 | 可选 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 不扩展内置 admin 成 CMS(避免范围爆炸)。
|
||||
- Tutorial 增加「何时用内置 admin / 何时自研」。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| 文档 + 示例 desk | 无 `/admin` 也能完成一文增删改 |
|
||||
| 内置 admin 金样 | 仍绿 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 workaround
|
||||
|
||||
自研 `/desk` + 调用 `/_form` 或直接 DB API;复杂编辑器继续外挂 JS。
|
||||
@@ -0,0 +1,71 @@
|
||||
# 解决 7:静态资源与脚本生命周期
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §7](../../research/ext-web-customization-limits.md#7-静态资源与脚本生命周期) |
|
||||
| 优先级 | **P2** · 波次 **C3** |
|
||||
| 触点 | `web_page_head` / `web_head` · `render.rs` head 输出 · static 挂载 · [web-assets-and-images.md](../web-assets-and-images.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 默认脚本加载方式**不假设**作者手写 IIFE 抢在 DOM 前执行成功;提供 `defer` / `module` 一等约定。
|
||||
2. 静态资源变更可发现:文档化 `?v=`,并提供可选自动指纹或 listen 时 mtime 查询参数。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
Head 资源表扩展列(向后兼容):
|
||||
|
||||
| 列 | 说明 |
|
||||
|----|------|
|
||||
| `rel` / `关系` | 已有;`script` / `module` |
|
||||
| `defer` / `推迟` | `真` → `<script defer>`(**建议默认对 script 为真**) |
|
||||
| `async` / `异步` | 可选 |
|
||||
| `version` / `版本` | 非空则自动追加 `?v=` |
|
||||
|
||||
```markdown
|
||||
`头` =
|
||||
| 关系 | 地址 | 推迟 | 版本 |
|
||||
|------|------|------|------|
|
||||
| script | /static/theme.js | 真 | 2026-09-04 |
|
||||
| module | /static/desk.js | 真 | 3 |
|
||||
```
|
||||
|
||||
全局:`app.asset_version="2026-09-04"` 为所有 static 链接统一 bump(可选)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| head 渲染 | 尊重 defer/async;`module` → `type="module"`(已有则核对) |
|
||||
| 默认 | 新建 scaffold 的 script 行带 `defer` |
|
||||
| (可选)`asset_version` | listen 时重写 head / 页面内 static URL |
|
||||
| 文档 | 「禁止在同步 head 脚本里直接 `getElementById` 主节点;用 defer 或 `DOMContentLoaded`」 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 旧表无 `defer` 列:保持现网同步行为(或仅对 scaffold/新文档默认 defer,避免静默改变旧站时序)。
|
||||
- 更安全:缺省仍同步;**Skill 与 scaffold 默认写 defer=真**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| defer 脚本读 DOM | 登录跳转逻辑在 DOM 就绪后执行 |
|
||||
| `version` 列 | HTML 中出现 `theme.js?v=…` |
|
||||
| 旧示例无新列 | 仍通过 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 workaround
|
||||
|
||||
脚本改 `type=module` 或放 body 末;手动 `?v=` bump;登录逻辑用 `DOMContentLoaded`。
|
||||
@@ -0,0 +1,68 @@
|
||||
# 解决 8:扩展与部署耦合
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §8](../../research/ext-web-customization-limits.md#8-扩展与部署耦合) |
|
||||
| 优先级 | **P3** · 文档 + 发布流程 |
|
||||
| 触点 | `marqdo ext add web` · ABI 版本 · Docker/发布说明 · [ext-cli.md](../ext-cli.md) · [marqdo-release](../../../.cursor/skills/marqdo-release/SKILL.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 站点作者**不必 fork 插件**才能完成 P0/P1 定制(把能力收进官方参数,见 01–05)。
|
||||
2. 版本耦合可预期:changelog / 扩展清单标明「web 插件需 ≥ x.y.z」。
|
||||
3. 升级路径文档化:二进制、`.marqdo-ext`、Docker 镜像三者对齐检查。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 / 运维约定(草案)
|
||||
|
||||
| 约定 | 说明 |
|
||||
|------|------|
|
||||
| 定制优先走 `.mq.md` 开关 | `admin_prefix`、`shell_css`、`layout`、`gate`… 进官方 API 后,禁止文档再教「改 plugins/web」 |
|
||||
| 兼容性矩阵 | 在 [web-net-capabilities.md](../web-net-capabilities.md) 或本目录维护「Marqdo ↔ libweb 最低版本」表 |
|
||||
| `marqdo ext add web` | 安装后打印当前插件路径与版本;与 CLI 版本不符时警告 |
|
||||
| Docker | 示例 Dockerfile 注释:升级需同时换 `marqdo` 与 `ext add` 产物 |
|
||||
| 样式引号等行为变更 | 写入 CHANGELOG **Breaking / migration** 小节(如 0.3.2 T5) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 工程改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| 插件/Crate 版本可见 | `web_listen` 或 `ext list` 显示 web ABI/包版本 |
|
||||
| CI | 金样使用仓库内 `plugins/web`;发布技能检查 VSIX/CLI/插件三件套 |
|
||||
| 研究→设计→路线图 | C0–C4 进 [ext-web roadmap](../../roadmap/ext-web.md),避免只活在私有 fork |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 不承诺插件源码级稳定 API;承诺 **`.mq.md` 作者 API** 在小版本尽量兼容,破坏性变更进 CHANGELOG。
|
||||
- Fork 插件仅作为「官方尚未交付」的临时手段,并在 issue/路线图留归还项。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| 升级说明文档 | 运维按清单升级后 web 金样通过 |
|
||||
| C0–C2 落地 | 自研后台场景**无需**改 `plugins/web` 源码 |
|
||||
| `ext list` / 文档 | 能核对版本 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 预编译路径(进行中)
|
||||
|
||||
**目标:** 用户 `marqdo ext add web` **不必**本机 Rust。
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| Release `marqdo-*-native-*.zip` | Windows / Linux 预编译 `web`/`agent`/`quantum` |
|
||||
| Windows portable zip | 内含 `ext/` + `ext/native/*.dll` |
|
||||
| `ext add` 下载回退 | 本地无 `.so`/`.dll` 时从 GitHub Release 拉取(`MARQDO_EXT_NO_DOWNLOAD=1` 可关) |
|
||||
|
||||
仍保留开发者 `cargo build -p marqdo_plugin_*` 路径。详见 [ext-cli.md](../ext-cli.md)。
|
||||
@@ -0,0 +1,50 @@
|
||||
# `ext/web` 定制修复:解决文档索引
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **C0–C4 done** |
|
||||
| 日期 | 2026-09-04 |
|
||||
| 问题盘点 | [../../research/ext-web-customization-limits.md](../../research/ext-web-customization-limits.md) |
|
||||
| 相关 | [../ext-web.md](../ext-web.md) · [../ext-web-net.md](../ext-web-net.md) · [../../roadmap/ext-web.md](../../roadmap/ext-web.md) |
|
||||
|
||||
对应研究文 §1–§8,每项一份解决文档:**目标 → 作者 API → 插件改动点 → 兼容策略 → 验收**。
|
||||
|
||||
实现时优先 **不破坏现有金样**(`tests/ext/web-*`、`examples/web-*`);新能力用显式 opt-in 参数打开。
|
||||
|
||||
---
|
||||
|
||||
## 文档一览
|
||||
|
||||
| # | 主题 | 文档 | 建议优先级 |
|
||||
|---|------|------|------------|
|
||||
| 1 | 路由与 `/admin` 前缀可让出 | [01-routes-and-admin-prefix.md](01-routes-and-admin-prefix.md) | P0 |
|
||||
| 2 | `SHELL_CSS` 可关 / 可层 | [02-shell-css.md](02-shell-css.md) | P1 |
|
||||
| 3 | 鉴权门禁可配置且行为一致 | [03-auth-gates.md](03-auth-gates.md) | P0 |
|
||||
| 4 | 样式表作者体验 | [04-stylesheet-authoring.md](04-stylesheet-authoring.md) | P2 |
|
||||
| 5 | 页面壳与插槽松绑 | [05-page-shell-slots.md](05-page-shell-slots.md) | P1 |
|
||||
| 6 | 后台 CRUD / 表单边界 | [06-admin-crud-forms.md](06-admin-crud-forms.md) | P3 |
|
||||
| 7 | 静态资源与脚本生命周期 | [07-assets-script-lifecycle.md](07-assets-script-lifecycle.md) | P2 |
|
||||
| 8 | 扩展与部署耦合 | [08-ext-deploy-coupling.md](08-ext-deploy-coupling.md) | P3 |
|
||||
|
||||
---
|
||||
|
||||
## 波次建议(实现用)
|
||||
|
||||
| 波次 | 内容 | 依赖 |
|
||||
|------|------|------|
|
||||
| **C0** | 可配置 `admin_prefix`;`admin=False` 时不挂内置路由;`login_redirect` / `logout_redirect` | — |
|
||||
| **C1** | gate:统一未登录策略;精确/前缀匹配;登录页自动放行;默认 gate 不再误伤 `/admin-*` | C0 |
|
||||
| **C2** | `shell_css=off\|minimal\|full`;主题在壳前或隔离层;可选 `layout=bare` | — |
|
||||
| **C3** | 样式:校验警告 / `strict`;`page.css` raw;脚本 `defer`/`async`/`version` + `asset_version` | **done** |
|
||||
| **C4** | 壳:`layout` 预设(C2);条件导航 `when` / `media` | **done** |
|
||||
|
||||
路线图入口可在 [ext-web.md](../../roadmap/ext-web.md) 增补「定制波次 C0–C4」行,落地后再改状态。
|
||||
|
||||
---
|
||||
|
||||
## 产品原则(解法共同约束)
|
||||
|
||||
1. **`.mq.md` 仍是真相源** — 能声明的不进隐藏默认;新开关写在 `app` / `page` / `listen` 参数表。
|
||||
2. **内置 admin 是可选产品**,不是不可替换的内核路由命名空间。
|
||||
3. **默认行为保持兼容** — 现有 tutorial / 示例零改动仍能跑;新站显式打开定制。
|
||||
4. **禁止**为单站需求永久硬编码第二套旁路(如永远推荐 `/desk` + JS fetch 登录)。
|
||||
@@ -0,0 +1,454 @@
|
||||
# `plugins/web` Go 全量重写(多语言 ABI 生态 · 网页制备完备)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Completed(W-G0…W-G14 · v0.4.0)** |
|
||||
| 日期 | 2026-09-10 |
|
||||
| 相关 | [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) · [web-net-capabilities.md](web-net-capabilities.md) · [ext-web-drivers.md](ext-web-drivers.md) · [web-assets-and-images.md](web-assets-and-images.md) · [ext-hosting-fill.md](ext-hosting-fill.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [web-asgi-servers-and-marqdo.md](web-asgi-servers-and-marqdo.md) |
|
||||
| 实现目录 | `plugins/web/`(**Go module**;产物仍为 `libweb.so` / `web.dll` / `libweb.dylib`) |
|
||||
| 作者面 | `ext/web/web.mq.md` · `ext/web/网页.mq.md`(**ABI 名与方法面保持兼容**;非另起一套 API) |
|
||||
| 验收应用 | 工作区 `anlian`(暗恋见君):用 Marqdo 前后端脚本完整重写;**PostgreSQL + Redis 外接** |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
用 **Go** 重写官方网络拓展库原生层(`plugins/web`),在 **C ABI v2 全量兼容** 前提下提供「网页制备」所需的全部服务端能力;`ext/web` 继续用 GFM 表 + `#` 类做作者面;应用(含暗恋见君)的前后端脚本全部用 Marqdo 书写。此举同时验证 **多语言 ABI 插件生态**(首个非 Rust 官方插件)。
|
||||
|
||||
**不是**最小 hello 插件;**不是**在旧 Rust 代码上打补丁(对齐 [ext-web.md](ext-web.md) **C5**)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机与目标
|
||||
|
||||
### 1.1 为何重写
|
||||
|
||||
| 动机 | 说明 |
|
||||
|------|------|
|
||||
| 开发/编译节奏 | Rust 插件迭代慢,网络域能力长期「半成品感」来自堆叠依赖与慢反馈,而非语言绝对性能 |
|
||||
| 多语言生态 | ABI 已是稳定 C 契约;需要第一个 **Go** 官方插件证明「宿主 Rust ≠ 插件必须 Rust」 |
|
||||
| 网页制备完备 | 目标是支持 **完整动态站点制备**(装配、CRUD、鉴权、实时、上传、SEO、代理、驱动…),并以真实论坛项目验收 |
|
||||
| 性能与拉起 | Go `net/http` 生态成熟、单二进制友好;论坛级 IO 密集负载下足够「极致可用」 |
|
||||
|
||||
### 1.2 成功标准(全部满足才算完成)
|
||||
|
||||
1. **ABI 全量对等**:下文 §5 列出的每一个已注册 `web_*` 符号,参数 CSV、JSON 形、语义与现网 gold 一致(中英参数别名保留)。
|
||||
2. **作者面可用**:现有 `ext/web` 示例与 `tests/ext/web-*`(含 live-server)在换 Go `.so` 后通过;无需作者改业务脚本(除非文档标明的 **G 增强**)。
|
||||
3. **网页制备完备**:单站点可完成页面装配、样式/头/图、库表、表单、路由、中间件、鉴权/RBAC、上传下载、SEO/RSS/sitemap、WS、缓存、对象存储、反代、invoke——即 W0–W8 + P3 + C0–C4 + H1/H2 能力面。
|
||||
4. **驱动外接**:`postgres://`、`redis://`、`s3://` 为正式一等能力(与 [ext-web-drivers.md](ext-web-drivers.md) 一致);SQLite / memory / file 仍支持本地与测试。
|
||||
5. **暗恋见君可写完**:用 Marqdo 后端脚本 + 浏览器 WASM 前端脚本重写 anlian 核心模块(见 §8);运行时仅依赖 `marqdo` + `libweb` + **外接 PostgreSQL + Redis**(可选 S3/RustFS)。
|
||||
6. **安装路径不变**:`marqdo ext add web`、`plugin.native_path name=web`、`MARQDO_WEB_PLUGIN`、产物文件名 `libweb.so` 等与 [ext-cli.md](ext-cli.md) 兼容。
|
||||
|
||||
### 1.3 非目标
|
||||
|
||||
| 非目标 | 说明 |
|
||||
|--------|------|
|
||||
| 改 Marqdo 核心语法 | 仍遵守 ext-web **C1** |
|
||||
| 把服务器搬进浏览器 WASM | 仍遵守 ADR 0002 |
|
||||
| 进程内 TLS | HTTPS 由反代;`cookie_secure` 保留 |
|
||||
| 第三方插件市场 | 仍无 registry |
|
||||
| 把论坛业务写进 Go 插件 | 帖子/新闻/聊天室规则在 `.mq.md`;插件只提供原语 |
|
||||
| 强制嵌入式替代 PG/Redis | 本项目明确 **允许并依赖外接** PG/Redis |
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层架构(锁定)
|
||||
|
||||
```text
|
||||
┌──────────────────────────────────────────────────────────────────┐
|
||||
│ 应用(anlian / 任意站点) │
|
||||
│ · 后端 .mq.md:路由、业务、装配、invoke 处理函数 │
|
||||
│ · 前端 .mq.md:WASM + lib/browser(作者零业务 JS) │
|
||||
└────────────────────────────┬─────────────────────────────────────┘
|
||||
│ import web / 网页
|
||||
┌────────────────────────────▼─────────────────────────────────────┐
|
||||
│ ext/web(L1 · Marqdo) │
|
||||
│ # page # db # app # form # auth # cache # storage # media # ws │
|
||||
│ make_style / make_head / make_images / client_embed … │
|
||||
└────────────────────────────┬─────────────────────────────────────┘
|
||||
│ lib/plugin → dlopen
|
||||
┌────────────────────────────▼─────────────────────────────────────┐
|
||||
│ plugins/web(L0 · Go · C ABI v2) ← 本文件重写对象 │
|
||||
│ net/http + 驱动适配 + HTML 装配 + WS hub + 中间件 … │
|
||||
└──────────┬─────────────────┬─────────────────┬───────────────────┘
|
||||
│ │ │
|
||||
PostgreSQL Redis S3/MinIO/RustFS
|
||||
(外接) (外接) (可选外接)
|
||||
```
|
||||
|
||||
| 层 | 语言 | 职责 |
|
||||
|----|------|------|
|
||||
| 应用脚本 | Marqdo | 前后端业务、页面表、领域模型 |
|
||||
| `ext/web` | Marqdo | 双语作者 API;禁止直接 `host_*` |
|
||||
| `plugins/web` | **Go** | 全部 `web_*` ABI;高性能网络与驱动 |
|
||||
| `lib/net` | Marqdo + Rust host | **仅**客户端 HTTP / cookie / multipart / markdown **解析**;不进本重写范围(边界不变) |
|
||||
| 宿主 | Rust | `dlopen`、JSON Value、`host_query`(`entry_dir` / `call_lib_path` …) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 硬约束(继承 + 本重写追加)
|
||||
|
||||
### 3.1 继承 ext-web C1–C7
|
||||
|
||||
| ID | 约束 |
|
||||
|----|------|
|
||||
| C1 | 不为 web 改核心语法 |
|
||||
| C2 | 作者面禁止 json 袋胶水拼装页面 |
|
||||
| C3 | 中英 API 分文件;禁止混排 |
|
||||
| C4 | 首页 `index.mq.md`;组件可拆 |
|
||||
| C5 | **禁止在旧 Rust 插件上打补丁演进**;清空/替换后用 Go 重写 |
|
||||
| C6 | `# db` 完整 CRUD;`select`/`查询`;admin 与表单共用写库 API |
|
||||
| C7 | 表单字段+规则;**写库前服务端校验** |
|
||||
|
||||
### 3.2 本重写追加(G 系列)
|
||||
|
||||
| ID | 约束 |
|
||||
|----|------|
|
||||
| **G1** | 产物仍为 C ABI v2;`MARQDO_ABI_VERSION = 2`;导出符号名与 [include/marqdo_abi.h](../../include/marqdo_abi.h) 一致 |
|
||||
| **G2** | **ABI 函数名与参数名向后兼容**:§5 清单中每个 `web_*` 必须注册;参数 CSV 与现 Rust 插件一致(含中文别名) |
|
||||
| **G3** | Go 使用 `-buildmode=c-shared`;**禁止**把 Go runtime 假设成唯一线程——跨 FFI 调用必须可重入或明确串行化文档 |
|
||||
| **G4** | `marqdo_plugin_shutdown` 必须停止 HTTP/WS、关闭 DB/Redis 连接、释放 hub |
|
||||
| **G5** | 字符串跨界:成功时 `*out_json` / 失败时 `*err_msg` 必须用 **host `alloc`** 分配(与现插件相同),由宿主 `free` |
|
||||
| **G6** | 相对路径(sqlite 文件、静态目录、上传根)一律相对 `host_query("entry_dir")` |
|
||||
| **G7** | 多语言样板:仓库内保留可复用的 Go ABI 脚手架注释/包结构,供后续其它语言插件参考 |
|
||||
| **G8** | 金样例不过 = 未完成;切换默认 `libweb` 到 Go 后,既有 `tests/ext/web-*` 必须绿 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 技术选型(Go)
|
||||
|
||||
| 能力 | 选型 | 备注 |
|
||||
|------|------|------|
|
||||
| HTTP 服务器 | 标准库 `net/http` | 路由可用轻量自研 mux 或 `chi`/`http.ServeMux`(Go 1.22+ 模式) |
|
||||
| 中间件 | 自研链式 `func(http.Handler) http.Handler` | 对等 CORS / 安全头 / gzip / body limit / access_log / cache-control |
|
||||
| WebSocket | `gorilla/websocket` 或 `coder/websocket` | 对等 echo / broadcast / drain;**G 增强**:命名房间(§7) |
|
||||
| SQLite | `modernc.org/sqlite`(纯 Go)或 `mattn/go-sqlite3`(cgo) | 优先纯 Go 以便交叉编译;FTS5/migrate 行为对齐 |
|
||||
| PostgreSQL | `jackc/pgx/v5` | `postgres://` / `postgresql://` |
|
||||
| Redis | `redis/go-redis/v9` | `# cache`;**G 增强**:可选 session/WS 后端 |
|
||||
| S3 | `aws-sdk-go-v2` 或 MinIO SDK | `s3://`;兼容 RustFS |
|
||||
| 密码 | `golang.org/x/crypto/argon2` | argon2id 参数对齐现实现 |
|
||||
| Markdown | `goldmark`(GFM 扩展) | 对等 `pulldown-cmark` 用途(正文 HTML) |
|
||||
| JSON | `encoding/json` | ABI 边界 |
|
||||
| 构建 | `go build -buildmode=c-shared -o libweb.so` | 见 §9 |
|
||||
|
||||
**不引入**完整 Web 框架(Gin/Echo 业务层)以免作者面旁路;框架能力用 Marqdo `# app` 表达。
|
||||
|
||||
---
|
||||
|
||||
## 5. ABI 全量清单(必须注册 · 兼容)
|
||||
|
||||
> 参数列为注册时 `params` CSV(英;实现须同时接受设计中已有的中文键别名,与现 `lib.rs` 一致)。
|
||||
> 状态列:`P0` = 首波必须与 gold 对齐;实现顺序见 §10。
|
||||
|
||||
### 5.1 Page / compose / assets / render
|
||||
|
||||
| ABI | params(摘要) | 域 |
|
||||
|-----|----------------|-----|
|
||||
| `web_page_new` | (空或 title 等,对齐现实现) | page |
|
||||
| `web_compose_components` | page, components, … | compose |
|
||||
| `web_compose_main` | page, main, … | compose |
|
||||
| `web_page_query` | page, query | page |
|
||||
| `web_page_order` | page, order | page |
|
||||
| `web_page_link_prefix` | page, prefix | page |
|
||||
| `web_page_css` | page, css | page |
|
||||
| `web_page_detail` | page, … | page |
|
||||
| `web_page_meta` | page, meta | SEO |
|
||||
| `web_page_head` | page, head | W8 |
|
||||
| `web_page_images` | page, images | W8 |
|
||||
| `web_page_paginate` | page, … | content |
|
||||
| `web_head` | table / … | W8 |
|
||||
| `web_images` | table / … | W8 |
|
||||
| `web_app_icons` | app, icons | W8 |
|
||||
| `web_style` | table, strict? | CSS |
|
||||
| `web_compose_form` | page, form, target? | form embed |
|
||||
| `web_render` | page | HTML |
|
||||
|
||||
### 5.2 SEO / ops routes
|
||||
|
||||
| ABI | 域 |
|
||||
|-----|-----|
|
||||
| `web_rss_build` | RSS |
|
||||
| `web_app_route_rss` | app |
|
||||
| `web_app_redirect` | app |
|
||||
| `web_app_error_page` | app |
|
||||
| `web_app_sitemap` | app |
|
||||
| `web_app_robots` | app |
|
||||
| `web_sitemap_build` | sitemap |
|
||||
|
||||
### 5.3 Upload / media
|
||||
|
||||
| ABI | 域 |
|
||||
|-----|-----|
|
||||
| `web_app_upload` | app |
|
||||
| `web_app_download` | app |
|
||||
| `web_upload_validate` | media |
|
||||
| `web_upload_save` | media |
|
||||
| `web_media_new` | media |
|
||||
| `web_app_gallery` | app |
|
||||
|
||||
### 5.4 Database
|
||||
|
||||
| ABI | 备注 |
|
||||
|-----|------|
|
||||
| `web_db_new` | `sqlite:` / `postgres://` |
|
||||
| `web_db_init` | unique / index / fk / 审计时间戳 |
|
||||
| `web_db_insert` / `select` / `get` / `update` / `delete` / `exec` | CRUD |
|
||||
| `web_db_query` / `count` | 原生 / 计数 |
|
||||
| `web_db_migrate` | **SQLite only**(对等) |
|
||||
| `web_db_fts_create` / `web_db_search` | **SQLite only** |
|
||||
| `web_db_begin` / `commit` / `rollback` | 事务句柄 |
|
||||
| `web_db_list_tables` / `web_db_table_info` | admin 内部 |
|
||||
|
||||
Where 语义:等值 map、filter 表、OR / IN / BETWEEN、分页 offset/limit——行为对齐现 `db.rs` / `db_pg.rs`。
|
||||
|
||||
### 5.5 Cache / storage
|
||||
|
||||
| ABI | URL |
|
||||
|-----|-----|
|
||||
| `web_cache_new` / `get` / `set` / `del` / `exists` / `ttl` | `memory:` / `redis://` |
|
||||
| `web_storage_new` / `put` / `get` / `delete` / `list` | `file:` / `s3://` |
|
||||
|
||||
### 5.6 App / HTTP / hosting
|
||||
|
||||
| ABI | 域 |
|
||||
|-----|-----|
|
||||
| `web_app_new` | app |
|
||||
| `web_app_route` | 动态 `{param}` + `/_part` |
|
||||
| `web_app_mount_form` | `/_form` |
|
||||
| `web_app_static` | 静态目录 |
|
||||
| `web_app_middleware` | `configure`:CORS、安全头、gzip、body_limit、JSON API、access_log、cache_control |
|
||||
| `web_app_proxy` | 流式反代 / SSE(H1) |
|
||||
| `web_app_invoke` | HTTP → `lib.member`(H2;经 `host_query call_lib_path`) |
|
||||
| `web_listen` | 阻塞监听;组装全部路由 |
|
||||
| `web_app_route_ws` | WS 端点 |
|
||||
| `web_ws_connect` | 客户端单次请求-响应式 |
|
||||
| `web_app_auth` | `/admin` 门禁 |
|
||||
| `web_app_gate` | RBAC 段前缀 |
|
||||
|
||||
### 5.7 Form
|
||||
|
||||
| ABI |
|
||||
|-----|
|
||||
| `web_form_new` / `fields` / `rules` / `validate` / `render` / `submit` / `from_schema` |
|
||||
|
||||
规则:`required`、`min:N`、`max:N`、`email`、`url`、`match:field`、`in:a,b,c`。
|
||||
|
||||
### 5.8 Session / auth
|
||||
|
||||
| ABI |
|
||||
|-----|
|
||||
| `web_session_new` / `set` / `get` / `del` / `destroy` |
|
||||
| `web_auth_new` / `login` / `check` / `logout` |
|
||||
| `web_password_hash` |
|
||||
|
||||
安全对等:argon2id、CSRF、登录限速、CSPRNG session id、cookie Secure(配置)、滑动 TTL、持久化会话(默认 SQLite 会话表;见 §7 Redis 可选)。
|
||||
|
||||
### 5.9 HTTP 挂载面(`web_listen` 必须复现)
|
||||
|
||||
- `GET /`,`GET /_part/{id}`,`GET|POST /_form/{id}`
|
||||
- 可选 admin:`{prefix}/`、`/login`、`/logout`、`/{table}`、`/new`、`/{id}/edit`、`/{id}/delete`(C0:`admin=False` 让出 `/admin`)
|
||||
- 作者 `route` 页 + `{path}/_part/{id}`;动态路径参数
|
||||
- WS;RSS;upload POST;download GET;gallery;sitemap;`/robots.txt`
|
||||
- 301/307 重定向;自定义 404/500;proxy;invoke
|
||||
- 静态与 icons;约定 `/favicon.ico`
|
||||
- 保留名:`/_form`、`/_part`、静态挂载冲突检测
|
||||
|
||||
### 5.10 `host_query` 依赖
|
||||
|
||||
| name | 用途 |
|
||||
|------|------|
|
||||
| `entry_dir` | 路径沙箱根 |
|
||||
| `call_lib_path` | invoke / 嵌套 lib 调用(含 `args`) |
|
||||
| (其它已允许项) | 与 ABI v2 allowlist 一致;不得扩展任意 HostFn |
|
||||
|
||||
---
|
||||
|
||||
## 6. 作者面(保持 · 不另起炉灶)
|
||||
|
||||
英文 `ext/web/web.mq.md` / 中文 `ext/web/网页.mq.md` 现有 `#` 类与 `##` 方法 **保持**:
|
||||
|
||||
| 类 | 职责 |
|
||||
|----|------|
|
||||
| `# page` / `# 页面` | 装配、meta、head、images、paginate、render |
|
||||
| `# db` / `# 数据库` + `# txn` | CRUD、事务、migrate/FTS(SQLite) |
|
||||
| `# form` / `# 表单` | 字段、规则、校验、渲染、提交 |
|
||||
| `# app` / `# 应用` | route、configure、listen、auth、gate、upload… |
|
||||
| `# auth` / `# 鉴权` | login/check/logout/hash |
|
||||
| `# cache` / `# 缓存` | memory/redis |
|
||||
| `# storage` / `# 存储` | file/s3 |
|
||||
| `# media` / `# 媒体` | validate/save |
|
||||
| `# ws` / `# 实时` | connect |
|
||||
| 模块函数 | `ensure_plugin`、`make_style`、`make_head`、`make_images`、`client_embed`、`text_patch`、`dom_patch`、`list_html` |
|
||||
|
||||
**重写默认策略**:先 **只换原生 `.so`**,L1 不动;仅当 §7 G 增强需要新方法时,再 **追加**(不破坏旧方法)。
|
||||
|
||||
---
|
||||
|
||||
## 7. G 增强(完备网页制备 + anlian;兼容之上增量)
|
||||
|
||||
> 以下为 **新增能力**,不替代 §5。作者面用新方法/新 configure 键;旧脚本不受影响。
|
||||
|
||||
| ID | 能力 | 动机 | 作者面草案 |
|
||||
|----|------|------|------------|
|
||||
| **G-WS1** | **命名房间** WS:`join`/`leave`/`publish`;组名 ASCII(如 `chat.room.{id}`) | anlian 公聊/私聊 | `app.route_ws` 增 `mode=room` + `room_key`;或 `ws.room_*` ABI |
|
||||
| **G-WS2** | 房间消息钩子:先 `invoke`/落库再广播 | 「先写 PG 再推送」 | configure 或 route 表 `on_message=lib.member` |
|
||||
| **G-SESS1** | Session 后端可选 `redis://` | 多进程/多实例 | `web_session_new` url 或 auth 配置 `session=redis://` |
|
||||
| **G-CACHE1** | Redis pub/sub 可选作 WS 扇出后端 | 多进程 WS | `configure ws_backend=redis` |
|
||||
| **G-API1** | Bearer API Key 校验原语(hash+pepper+scopes) | anlian `apikeys` | `web_api_key_check` + `# auth` 或独立小类;**业务 scopes 仍在 .mq.md** |
|
||||
| **G-MAIL0** | (可选后续)SMTP 发送原语 | 邮箱验证码 | 不阻塞首版对等;列入 anlian 二期 |
|
||||
|
||||
**明确仍属应用层(不进插件)**:反垃圾策略、草稿定时发布约定、好友关系、专题 `topic_bundles` 静态交互内容(静态挂载 + 前端 Marqdo/既有 JS 资产)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 暗恋见君验收矩阵(检测「能不能写完」)
|
||||
|
||||
外部依赖(允许):**PostgreSQL**、**Redis**;可选对象存储。
|
||||
|
||||
| 模块 | Marqdo 后端 | Marqdo 前端 | 插件依赖 | 验收 |
|
||||
|------|-------------|-------------|----------|------|
|
||||
| 站点壳 / 首页 | `# page` + db | 局部刷新可选 WASM | listen、static、cache | 首页可开 |
|
||||
| posts 帖子/评论/板块 | route + form + db | 发帖表单 WASM 可选 | CRUD、CSRF、upload | CRUD+列表详情 |
|
||||
| news | 同上 | 同上 | 同上 | 列表详情 |
|
||||
| accounts | auth + session +(二期 mail) | 登录表单 | argon2、session、gate | 注册登录 |
|
||||
| profiles | db + storage | 头像上传 | storage/upload | 资料页 |
|
||||
| search | db.search 或 PG 查询 + cache | — | db/cache | 关键词搜索 |
|
||||
| chat | route_ws + G-WS1/2 + db | WS 客户端脚本 | Redis + WS rooms | 公聊+私聊实时 |
|
||||
| apikeys | G-API1 + db | 管理页 | — | Bearer 调 API |
|
||||
| webmaster | sitemap/robots | — | 已有 ABI | `/sitemap.xml` |
|
||||
| topics | `app.static` → bundles | 既有静态交互 | static | 专题可访问 |
|
||||
|
||||
**「写完」定义**:上述模块在 Marqdo 仓库或 `anlian` 旁路目录有可运行 `.mq.md` 站点;gold/手工脚本能走通主路径;不依赖 Django/Channels/Daphne/gunicorn。
|
||||
|
||||
---
|
||||
|
||||
## 9. 仓库布局与构建
|
||||
|
||||
### 9.1 目录(目标)
|
||||
|
||||
```text
|
||||
plugins/web/ # Go module(替换原 Rust crate)
|
||||
go.mod
|
||||
go.sum
|
||||
README.md
|
||||
abi/
|
||||
marqdo_abi.h # 从 include/ 拷贝或 cgo 引用
|
||||
bridge.go # //export marqdo_plugin_* ;register;alloc/free
|
||||
internal/
|
||||
page/ compose/ render/ form/
|
||||
db/ # sqlite + postgres driver
|
||||
cache/ storage/ upload/
|
||||
session/ auth/ password/ ratelimit/
|
||||
httpx/ # listen、router、middleware、admin、proxy、invoke
|
||||
ws/ # hub、rooms、client connect
|
||||
assets/ rss/ sitemap/ markdown/
|
||||
table/ # GFM 表 JSON 形态辅助
|
||||
cmd/ # 可选:非 c-shared 的本地自测
|
||||
scripts/build-web-plugin.sh # go build -buildmode=c-shared -o …/libweb.so
|
||||
```
|
||||
|
||||
原 Rust 源码:`plugins/web-rust-archive/`(**已移出 Cargo workspace**;参考用,默认不构建)。
|
||||
|
||||
### 9.2 产物与解析
|
||||
|
||||
| 平台 | 文件名 |
|
||||
|------|--------|
|
||||
| Linux | `libweb.so` |
|
||||
| macOS | `libweb.dylib` |
|
||||
| Windows | `web.dll` |
|
||||
|
||||
解析顺序仍走 `installed_native_path` / `MARQDO_WEB_PLUGIN`;`find_native_plugin` 增加查找:
|
||||
|
||||
- `plugins/web/build/libweb.so`(Go 构建输出)
|
||||
- `target/{debug,release}/libweb.so`(兼容旧路径,可选 copy)
|
||||
|
||||
### 9.3 宿主 / CI 变更要点
|
||||
|
||||
| 组件 | 变更 |
|
||||
|------|------|
|
||||
| 根 `Cargo.toml` workspace | 移除 `plugins/web` / `web-rust-archive` Rust member |
|
||||
| `tests/gold.rs` | `ensure_web_plugin_built()` → `scripts/build-web-plugin.sh` |
|
||||
| `marqdo ext add web` | 构建回退:`scripts/build-web-plugin.sh`(Go);Release 仍下发预编译 native zip |
|
||||
| Release 脚本 | Go:`scripts/build-web-plugin.sh`;其它插件仍 `cargo build -p …` |
|
||||
| [ext-cli.md](ext-cli.md) / [ext-abi.md](ext-abi.md) | 注明 web 插件实现语言为 Go |
|
||||
|
||||
### 9.4 cgo / runtime 注意
|
||||
|
||||
- `marqdo_plugin_init` 内 `register_fn` 注册全部符号;保存 host `alloc`/`free`/`host_query`。
|
||||
- 长时间 `web_listen`:在独立 goroutine 跑 `http.Server`,ABI 调用阻塞至 shutdown 或按现语义阻塞(**对齐现 Rust:listen 阻塞当前插件调用**)。
|
||||
- 禁止在 FFI 回调里长时间持有阻碍 GC 的错误模式;JSON 尽快拷贝到 Go string。
|
||||
- Windows 导出需 `.def` 或 `//export` 完整三个符号。
|
||||
|
||||
---
|
||||
|
||||
## 10. 实现波次(按文档开发顺序)
|
||||
|
||||
| 波次 | 内容 | 退出条件 |
|
||||
|------|------|----------|
|
||||
| **W-G0** | 文档(本文)+ ADR + 目录骨架 + ABI bridge 能 `plugin.load` + `demo` 注册探测 | ✅ `tests/ext/web-go-abi-smoke.mq.md`;`web_go_ready` + `web_page_new`;`scripts/build-web-plugin.sh` → `libweb.so` |
|
||||
| **W-G1** | table 辅助 + `web_style` + page new/compose/render(无 listen) | ✅ `web-smoke` / `web-zh-smoke`(含 compose_form / app_new / app_route 袋) |
|
||||
| **W-G2** | SQLite db CRUD + where + txn + init | ✅ `web-db-w2-smoke` / `web-db-w6-smoke`(txn·migrate·FTS) |
|
||||
| **W-G3** | form + mount_form + CSRF 基础 | ✅ `web-form-smoke`(validate/submit/render;CSRF 字段已接,listen 侧硬化见 W-G4/G5) |
|
||||
| **W-G4** | `web_listen` + route + static + part + middleware + JSON API | ✅ offline:`web-route` / `web-static` / `web-middleware` / `web-part`;`web_listen` 已接线(live 随 W-G5+ hardening) |
|
||||
| **W-G5** | session/auth/password/rate limit/gate/admin | ✅ offline:`web-security` / `web-c0` / `web-c1`;login rate limit 包已就位(HTTP 接线随 listen hardening) |
|
||||
| **W-G6** | upload/download/gallery/ETag + assets W8 | ✅ `web-upload` / `web-assets` / `web-p3` |
|
||||
| **W-G7** | SEO RSS sitemap robots redirect error paginate markdown | ✅ `web-content` / `web-w7-*` |
|
||||
| **W-G8** | WS echo/broadcast + access_log | ✅ `web-ws-broadcast-*` |
|
||||
| **W-G9** | Postgres + Redis cache + file/S3 storage | ✅ `web-drivers-smoke` |
|
||||
| **W-G10** | proxy + invoke + nested plugin | ✅ `web-proxy-invoke` / hosting live |
|
||||
| **W-G11** | 定制 C2–C4 shell/layout/style/nav | ✅ `web-c2`–`c4` |
|
||||
| **W-G12** | G 增强 WS rooms + Redis session/pubsub + API key 原语 | ✅ 单测 + `web-g12-api-key-smoke` |
|
||||
| **W-G13** | 默认切换 Go `libweb`;归档 Rust;更新发版与 ext CLI | ✅ 离线+live gold(7 个 `*_live`)对 Go 全绿;`ext add`/`gold`/`release` 走 `scripts/build-web-plugin.sh`;Rust 移出 workspace;gold 强制 `MARQDO_WEB_PLUGIN` 避免 `~/.marqdo` 旧 so |
|
||||
| **W-G14** | anlian Marqdo 重写主路径(可分仓或 `examples/anlian-mq/`) | ✅ `examples/anlian-mq/`(本地 SQLite + 粉玻璃主题 + 主路由/登录/片段;外接 PG/Redis 仍为增强路径) |
|
||||
|
||||
每波次:**先补 Go 实现 → 跑对应 gold → 再进入下一波**。禁止跨波次留下「注册了但返回 stub 错误」的 ABI(除 W-G0 明确的未实现探测)。
|
||||
|
||||
---
|
||||
|
||||
## 11. 测试策略
|
||||
|
||||
| 类型 | 做法 |
|
||||
|------|------|
|
||||
| 单元 | Go `go test ./internal/...`(db where、form rules、middleware) |
|
||||
| 金样例 | 现有 `tests/ext/web-*.mq.md`;构建脚本产出 `libweb.so` 后跑 |
|
||||
| Live | 现有 `*-live-server.mq.md` + curl |
|
||||
| 回归门禁 | CI:安装 Go → `scripts/build-web-plugin.sh` → `cargo test` 相关 web 项 |
|
||||
| anlian | 独立 smoke:登录、发帖、WS 发言、API key |
|
||||
|
||||
---
|
||||
|
||||
## 12. 风险与缓解
|
||||
|
||||
| 风险 | 缓解 |
|
||||
|------|------|
|
||||
| cgo/共享库与宿主线程 | 文档化;listen 独立 goroutine;shutdown 明确 |
|
||||
| JSON ABI 开销 | 热路径减少往返;装配结果缓存;不在此用「换语言」幻想消除 |
|
||||
| 行为微差异(HTML/Markdown) | 用同一批 gold HTML 片段断言;差异列 changelog |
|
||||
| 交叉编译 | 优先 `modernc.org/sqlite`;Release 矩阵 Linux/Windows 先 |
|
||||
| 双实现并存混乱 | W-G13 前用 `MARQDO_WEB_PLUGIN` 显式指向;文档写清默认 |
|
||||
|
||||
---
|
||||
|
||||
## 13. 文档与索引更新清单
|
||||
|
||||
实现推进时同步:
|
||||
|
||||
- [x] 本文状态行随波次更新
|
||||
- [x] [ext-abi.md](ext-abi.md) Demo/Web 节:实现语言 Go
|
||||
- [x] [ext-cli.md](ext-cli.md):构建回退含 `go build` / `scripts/build-web-plugin.sh`
|
||||
- [x] [ext-web.md](ext-web.md):链到本文;C5 落实说明
|
||||
- [ ] [web-asgi-servers-and-marqdo.md](web-asgi-servers-and-marqdo.md):axum → Go `net/http`
|
||||
- [ ] [doc/README.md](../README.md) 索引行(若尚未链到本文)
|
||||
- [x] ADR:`doc/adr/0004-web-plugin-go.md`(Accepted)
|
||||
- [x] `plugins/web/README.md` 开发者构建说明
|
||||
|
||||
---
|
||||
|
||||
## 14. 决议摘要
|
||||
|
||||
1. **全量重写** `plugins/web` 为 Go,**不是**最小闭环。
|
||||
2. **既有网络拓展能力(§5)重写后必须仍可用**;作者面默认兼容。
|
||||
3. **PostgreSQL / Redis 外接** 为一等公民;Marqdo 承担应用前后端脚本。
|
||||
4. **暗恋见君** 为完备性验收,不是缩小插件范围的借口。
|
||||
5. **多语言 ABI 生态** 以本插件为样板(G7)。
|
||||
6. 开发严格按 **§10 波次** 推进;本文件为唯一施工图。
|
||||
@@ -45,7 +45,7 @@
|
||||
| C2 | 作者面**禁止** `json.parse` / `json.set` 袋胶水、手写 part JSON、手写 assemble 袋 |
|
||||
| C3 | 能力以 **`#` 类 + `##` 方法** 暴露;**英文库文件只用英文名,中文库文件只用中文名**(见 [stdlib-i18n.md](stdlib-i18n.md));同一 `.mq.md` 内禁止中英 API 混排 |
|
||||
| C4 | 首页在 **`index.mq.md`**:页面表在此;可复用片段进 `components/`;主体可就地写 |
|
||||
| C5 | **旧有网络扩展库全部废弃**:`plugins/web`、`ext/web/**`(含现网示例/gold 中依赖旧 API 者)评审通过后**删除或清空后重写**;禁止在旧代码上打补丁演进 |
|
||||
| C5 | **旧有网络扩展库全部废弃**:`plugins/web`、`ext/web/**`(含现网示例/gold 中依赖旧 API 者)评审通过后**删除或清空后重写**;禁止在旧代码上打补丁演进。**落实**:原生层 Go 全量重写见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md);作者面 ABI 名保持兼容 |
|
||||
| C6 | `# db` / `# 数据库` 必须提供完整**增删改查**;列表查询英文方法名为 **`select`**(中文 **`查询`**);后台 `/admin` 与表单提交走同一套写库 API |
|
||||
| C7 | 用户输入经 `# form` / `# 表单`:字段表 + 校验表;**服务端校验必须在写库前执行**(见 §5.5) |
|
||||
|
||||
@@ -541,7 +541,7 @@ submit → action=insert → db.insert;action=update → db.update
|
||||
|----|----|------|
|
||||
| Marqdo 核心 | 表→Value、类/方法、import | 不识别 web 路径语法 |
|
||||
| `ext/web/*.mq.md` | 作者 API、中英面、委托插件 | 不直接 `host_*` |
|
||||
| `plugins/web` | 路径解析辅助、装配结果、listen、SQL、渲染 | 不要求作者写袋 |
|
||||
| `plugins/web` | **Go** `libweb`(HTTP / SQL / HTML 壳;见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md)) | 不要求作者写袋 |
|
||||
|
||||
**实现要点(评审通过后再做):**
|
||||
|
||||
|
||||
@@ -0,0 +1,55 @@
|
||||
# 标准库 / 扩展库:代码即文档
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-09-14 |
|
||||
| 相关 | [code-as-docs-gaps.md](code-as-docs-gaps.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md) · [collection-access-link.md](collection-access-link.md) · [stdlib.md](stdlib.md) · [marqdo-dev skill](../../.cursor/skills/marqdo-dev/SKILL.md) · [roadmap](../roadmap/lib-ext-code-as-docs.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
`lib/*` 与 `ext/*` 的 `.mq.md` 应**可当说明书读、可当程序跑**。薄库不写长文;厚领域库(web / quantum / …)仍用叙述承载意图,但数据与调用面与用户程序同一套标记。
|
||||
|
||||
## 2. 薄库模板(默认)
|
||||
|
||||
每个导出函数 / 方法尽量按此骨架(中英分文件锁步):
|
||||
|
||||
1. **目的句**(一句人话,无标记即可)。
|
||||
2. **叙述形参**:正文里出现 `` `名` `` / `` `名`=默认 ``(推断签名);过渡期可保留 `` + `名` ``。
|
||||
3. **一例**:粗体或 `>` 调用;优先可读表面。
|
||||
4. **实现**:短;取元用 `[键](集合)`,**禁止新增**脚注取元 `` `m`[^k] ``(旧解析仍可用)。
|
||||
|
||||
调用示例(三种等价,试点期任选;新叙述优先括号标记或粗体):
|
||||
|
||||
```markdown
|
||||
**出 = [put] 入=`表` 键="a" 值=1**
|
||||
|
||||
**出 = put 入=`表` 键="a" 值=1**
|
||||
|
||||
> put 入=`表` 键="a" 值=1
|
||||
```
|
||||
|
||||
带布尔开关时可用前置修饰:`严格 [parse] text=`源`` → `严格=True`(形参名与修饰语字面一致;核心不剥「的」等词缀)。
|
||||
|
||||
## 3. 硬约束
|
||||
|
||||
| 要 | 不要 |
|
||||
|----|------|
|
||||
| GFM 表作数据;`table.put` / 具名助手 | `json.set` 链当字典构造器 |
|
||||
| 作者程序用 `[k](c)` 取元;`- [项](集合)` foreach | 新代码写 `` m[^k] `` |
|
||||
| 中英 API 对称(见 [stdlib-i18n.md](stdlib-i18n.md)) | 只改一侧 |
|
||||
| 一例跑通即文档(public/stdlib 或 examples) | 另开第二套「文档站」手写说明 |
|
||||
|
||||
**库函数体内的叙述坑:** 函数体里的链接形 `[k](c)`、以及单独的 `**强调**` 会被当成可执行代码。库内说明用「链接取元 / link-index」等字面描述;可执行示例放在 `public/stdlib` 或 `examples/`,不要写在 `##` 体内当叙述。
|
||||
|
||||
## 4. 波次
|
||||
|
||||
见 [roadmap/lib-ext-code-as-docs.md](../roadmap/lib-ext-code-as-docs.md):先稳定调用表面,再 M1 试点 table/text/json,其后批次 lib → ext。
|
||||
|
||||
## 5. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-09-14 | 初稿(随括号调用落地) |
|
||||
@@ -0,0 +1,618 @@
|
||||
# Marqdo 语法映射 v0.3(叙述统一 · 粗体即代码)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 现行运行时目标(实现中)** |
|
||||
| 日期 | 2026-09-13 |
|
||||
| 取代 | [markdown-mapping.md](markdown-mapping.md) **v0.2(已废止为运行时宪法)** |
|
||||
| ADR | [0005-prose-unified-markup.md](../adr/0005-prose-unified-markup.md) |
|
||||
| 路线 | [markup-v0.3.md](../roadmap/markup-v0.3.md) |
|
||||
| 相关 | [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) · [call-arguments.md](call-arguments.md) · [objects.md](objects.md) · [keywords.md](keywords.md) |
|
||||
|
||||
> **名词:** 本文「Markup」指 Marqdo **如何把 Markdown 标记映射成语法**(`**` 代码、`*` 返回、`` `名` `` 声明),不是另一个语言。产品仍是 Marqdo。
|
||||
> **v0.3 为唯一映射。** 不做 v0.2 双模式 / `--markup` 版本身份。摸索阶段允许破坏性变更;旧 `.mq.md`(`*语句*` / `**返回**`)须改写。金样例见 `tests/markup-v03/`。
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
让 **Markdown 叙述本身成为程序的一部分**:普通文字里用 `` `名` `` 出现变量(首次未赋值 = 声明);用 **`**…**` 粗体** 包裹可执行代码(含调用,不必再写 `>`);用 **`*…*` 斜体** 表示返回值。函数形参**不再手写 `+` 列表**,由函数体内的声明/赋值自行推断。
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机(为何推翻 v0.2 的部分定论)
|
||||
|
||||
v0.2 为了「标记即语法」的清晰边界,做了这些硬隔离:
|
||||
|
||||
| v0.2 | 代价 |
|
||||
|------|------|
|
||||
| 无标记行 = 纯注释;变量只能写在 `*…*` / 结构行里 | 叙述与代码割裂,「文档即代码」读起来像两套语言叠在一起 |
|
||||
| `*…*` = 语句,`**…**` = 返回 | 与常见 Markdown/AI 习惯相反:模型更爱用 `**` 强调「要执行的东西」,读者也更易看见粗体 |
|
||||
| 调用必须 `>` | 行间调用要另起结构行,叙述中夹调用不自然 |
|
||||
| 形参必须 `` + `名` `` | 仪式感强;函数头像「另一套签名语言」,与正文脱节 |
|
||||
|
||||
古早示例(当时不能跑,正是本文要合法化的目标面):
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
|
||||
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
|
||||
|
||||
# main
|
||||
|
||||
我要调用加一函数可以采用这样的办法:
|
||||
|
||||
> 加一函数 37
|
||||
|
||||
或者可以直接这么调用**加一函数 37**
|
||||
```
|
||||
|
||||
目标:上述文件在 v0.3 下应能解析、求值,且**读起来仍是一篇正常中文说明**。
|
||||
|
||||
---
|
||||
|
||||
## 2. 哲学(设计原则)
|
||||
|
||||
### P1 — 叙述统一(Prose-unified)
|
||||
|
||||
- Marqdo 注释采用 **Markdown 叙述**(段落、列表中的说明文字),不是第二种注释语法。
|
||||
- **变量可以出现在正常文字之间**:用 Markdown 行内代码 `` `n` `` 标识标识符。
|
||||
- **第一次出现且未赋值 = 声明变量**;之后的出现 = 引用。赋值发生在粗体代码段内(或兼容的结构赋值形)。
|
||||
- **未使用的变量无害**(不报错、不升参);真正的输入由「可执行面读取」升为形参(§8)。
|
||||
- 这样「说明文字」与「程序名字」共用同一套 Markdown 视觉习惯,整体更和谐。
|
||||
|
||||
### P2 — 粗体即代码(Bold-as-code)
|
||||
|
||||
- **`**…**` = 代码段**(可执行):赋值、表达式、函数/方法调用、可内联的短语句。
|
||||
- 选择粗体的原因:
|
||||
1. **AI 输出偏好**:模型天然爱用 `**` 强调「重要操作」;把粗体定为可执行,降低「模型写了强调却被当成返回」的错配。
|
||||
2. **行间显眼**:在长段落里,粗体比斜体更容易被扫到。
|
||||
- 粗体代码段内的调用 **允许不写 `>`**:`**加一函数 37**` 与 `> 加一函数 37` 语义等价(见 §6)。
|
||||
- **`>` 保留为可选调用面**(blockquote 风格、独立行、兼容 v0.2 迁移与 AI 已学会的形态)。
|
||||
|
||||
### P3 — 斜体即返回(Italic-as-return)
|
||||
|
||||
- **`*…*` = 返回值**(架构级),与粗体代码形成对立、易读的一对:
|
||||
- 做了什么 → 粗体
|
||||
- 结果是什么 → 斜体
|
||||
- **空返回 / 无值收束**(已决议,见 §7.2):推荐 `*None*` / `*无*`;整行 `**`;兼容 `****`。`---` / `***` 仅为叙述分隔(跳过),**不再**结束函数体。
|
||||
- **输出仍不是返回**:打印继续用内置 `print` / `打印`(副作用函数),不把粗体或斜体当成「打印到终端」的语法。
|
||||
|
||||
### P4 — 形参由体推断(Body-inferred params)
|
||||
|
||||
- **不再要求**作者手写 `` + `名` `` 形参表(v0.3 默认关闭;过渡期可兼容,见 §8)。
|
||||
- 函数体内:
|
||||
- **只声明、未赋默认** → **必选形参**(调用时必须提供)。
|
||||
- **声明同时赋值**(含默认值字面量)→ **可选形参**(带默认值)。
|
||||
- 推断顺序与绑定规则见 §8;与位置/具名实参规则对齐 [call-arguments.md](call-arguments.md) 的精神(可修订附录)。
|
||||
|
||||
### P5 — 标记仍承载控制流(不变)
|
||||
|
||||
- **不引入** `if` / `else` / `while` / `for` / `def` / `return` 关键字。
|
||||
- `#` = 对象/类型,`##`+ = 函数/方法([objects.md](objects.md) 不变)。
|
||||
- 分支仍用 `1.` `2.` …;循环仍用 `-`;结构行不必再包粗体(见 §5)。
|
||||
|
||||
### P6 — 其它「代码即文档」补强(本版一并采纳)
|
||||
|
||||
| 思路 | 说明 |
|
||||
|------|------|
|
||||
| **渐进披露** | 读者可只读叙述;运行时只执行标记与推断出的声明。同一文件服务人与机器。 |
|
||||
| **最小仪式** | 能从正文看出的签名,就不在函数头重复写一遍。 |
|
||||
| **双调用面** | 独立行 `>` 适合「步骤清单」;行间 `**f …**` 适合「嵌在句子里的动作」。 |
|
||||
| **标识符视觉统一** | 叙述、代码、形参一律优先 `` `名` ``;粗体/斜体内部允许裸名(与 v0.2 斜体/粗体内规则同类)。 |
|
||||
| **段落仍可整段注释** | 不含任何可执行标记、且无「声明性 `` `名` ``」义务的纯说明段,行为与注释相同(见 §4 消歧)。 |
|
||||
| **迁移可观测** | `--dump-lines` / `--dump-ast` 必须能区分「叙述中的声明」与「粗体代码」与「斜体返回」。 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 与 v0.2 对照(角色对调摘要)
|
||||
|
||||
| 概念 | v0.2 | v0.3 |
|
||||
|------|------|------|
|
||||
| 程序语句 / 代码段 | `*…*` | `**…**` |
|
||||
| 返回值 | `**…**` | `*…*` |
|
||||
| 独立调用 | 必须 `>` | `>` **或** `**callee …**` |
|
||||
| 形参 | 标题下 `` + `名` `` | **体推断**(`+` 过渡兼容) |
|
||||
| 叙述中的变量 | 一般为注释,不可声明 | `` `名` `` 可声明/引用 |
|
||||
| 无标记纯文字 | 成段注释 | 仍为叙述;**若含声明性反引号则参与绑定图**(见 §4) |
|
||||
|
||||
这是一次 **架构级标记对调**,不是局部糖。金样例、教程、Skill、扩展库需按路线图分波迁移。
|
||||
|
||||
---
|
||||
|
||||
## 4. 叙述、声明与注释
|
||||
|
||||
### 4.1 三层模型(修订)
|
||||
|
||||
| 层 | 形态 | 角色 |
|
||||
|----|------|------|
|
||||
| **叙述面** | 普通 Markdown 段落、列表说明 | 给人读;其中的 `` `名` `` 可进入**绑定图** |
|
||||
| **可执行面** | 结构标记(`#` `>` `+` `-` `1.` 表…)+ **`**代码**`** + **`*返回*`** | 求值 |
|
||||
| **外联面** | ` ```lang ` | FFI(不变) |
|
||||
|
||||
### 4.2 变量在叙述中的出现
|
||||
|
||||
语法:Markdown **行内代码** `` `标识符` ``。
|
||||
|
||||
| 出现形态 | 语义 |
|
||||
|----------|------|
|
||||
| 全文(当前函数/对象作用域)**首次**出现 `` `n` ``,且此前/同句无对 `n` 的赋值 | **声明变量**(进入绑定图;是否升为形参见 §8) |
|
||||
| 已声明之后再次 `` `n` `` | **引用**(不生成新绑定) |
|
||||
| 粗体内 `**n = …**` / `**n=n+1**` | **赋值**(若首次赋值且未见声明,则声明+赋值一并发生) |
|
||||
| 叙述中 `` `n`=1 ``(反引号名紧贴 `=`,无粗体) | **带初值的声明**(形参默认或局部初值;见 §8) |
|
||||
|
||||
推荐作者写法(与动机示例一致):
|
||||
|
||||
```markdown
|
||||
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
|
||||
```
|
||||
|
||||
- `` `n` `` → 声明变量;因随后在代码中**读取**未先由局部独力定义 → 升为必选形参(§8)
|
||||
- `**n=n+1**` → 代码段(赋值)
|
||||
- `*n*` → 返回
|
||||
|
||||
### 4.3 何为「纯注释」
|
||||
|
||||
满足下列**全部**条件的段落,不产生绑定、不求值:
|
||||
|
||||
1. 不含结构标记行;
|
||||
2. 不含 `**…**` / 作为返回的 `*…*`(见 §7);
|
||||
3. 不含任何 `` `标识符` ``。
|
||||
|
||||
仍建议:**叙述段与独立结构代码行之间空一行**,降低人读与差分时的视觉粘连(解析器在 v0.3 下不再依赖「空行分段注释升级」作为唯一边界,但空行仍是作者卫生习惯)。
|
||||
|
||||
### 4.4 提及性反引号:一律视作变量(已决议)
|
||||
|
||||
**不另设「仅提及、不声明」语法。** 叙述里凡出现合法标识符 code span `` `名` ``,一律按 **变量** 处理(首次 = 声明,其后 = 引用)。
|
||||
|
||||
| 情况 | 处理 |
|
||||
|------|------|
|
||||
| 谈到某名但可执行代码**从未读写**它 | 仍是绑定图中的变量;**对求值无影响**(死绑定) |
|
||||
| 与其它语言对照 | 类似 Python 写了未用局部、JS 未用 `let`——默认可忽略;实现可对「从未读写」发**可选 lint**,**不得**因此报错或拒绝运行 |
|
||||
| 是否变成函数形参 | **否**(仅声明、从未在可执行面被读取)——见 §8.2「升参条件」 |
|
||||
| 是否需要 `` 提及`n` `` 等前缀 | **不需要**;避免第二套反引号方言 |
|
||||
|
||||
例(合法、无副作用):
|
||||
|
||||
```markdown
|
||||
## 说明性函数
|
||||
|
||||
本文顺便提到`Markdown`与`GFM`,但真正的输入只有`题干`。
|
||||
**print text=题干**
|
||||
---
|
||||
```
|
||||
|
||||
- `` `Markdown` `` / `` `GFM` `` → 变量声明,未使用 → 不进形参表、不改行为
|
||||
- `` `题干` `` → 声明且在粗体中读取 → 必选形参
|
||||
|
||||
**否决**:为「提及」单独做转义/前缀(曾列于开放点);若将来作者强烈需要「叙述中的等宽字但不进绑定图」,另开增强案,不阻塞 v0.3 核心。
|
||||
|
||||
### 4.5 成段规则相对 v0.2 的变化
|
||||
|
||||
v0.2:「段首无标记 → 整段注释,续行永不升级」。
|
||||
v0.3:
|
||||
|
||||
- 叙述段落**可以**内含可执行粗体/斜体返回;解析器做**段内扫描**,抽出 `` `名` ``、`**…**`、`*…*`。
|
||||
- 独立结构行(行首 `#` `>` `-` `1.` `|` 等)仍整行分类为代码。
|
||||
- **否决维持**:「整行无标记 = 默认可执行代码」。无标记且无反引号声明的文字永不单独变成语句。
|
||||
|
||||
---
|
||||
|
||||
## 5. 映射总表(v0.3)
|
||||
|
||||
| 标记 | 语义 |
|
||||
|------|------|
|
||||
| `#` … `######` | `#` = 对象/类型;`##`+ = 函数/方法(同 [objects.md](objects.md)) |
|
||||
| 叙述中 `` `名` `` | 声明或引用(§4) |
|
||||
| `**…**` | **代码段**(赋值、表达式、调用) |
|
||||
| `*…*` | **返回值**(含显式空值,见 §7.2) |
|
||||
| `>` 行 | **调用**(可选面,与粗体内调用等价) |
|
||||
| `` + `名` `` | **过渡兼容**:显式形参;新代码不推荐 |
|
||||
| 体内 `1.` `2.` … | 分支 |
|
||||
| 体内 `-` | 循环 |
|
||||
| `N. *` | else 臂(此处 `*` 仍是「空条件」标记,**不是**返回值;见 §7.3) |
|
||||
| GFM 表格 | 集合(不变) |
|
||||
| 表达式 `[键](集合)` | **取元**(与 foreach 同形;见 [collection-access-link.md](collection-access-link.md)) |
|
||||
| `修饰… [函数名] 实参…` | **方括号标记调用**(前置修饰 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md)) |
|
||||
| `` 集合[^键] `` | **过渡**:旧脚注取元(仍可用) |
|
||||
| ` ```lang ` | 外联(不变) |
|
||||
| 单独一行 `---` / `***` | **叙述分隔**(跳过;模块顶与函数体内相同) |
|
||||
| 整行恰 `**` 或 `****` / `*None*` / `*无*` | **空返回**并结束本函数体(见 §7.2) |
|
||||
|
||||
### 结构行与粗体
|
||||
|
||||
行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包 `**…**`。
|
||||
粗体用于:**嵌在叙述中的代码**,以及「我想把这一小段标成可执行」的行间片段。
|
||||
|
||||
---
|
||||
|
||||
## 6. 调用
|
||||
|
||||
### 6.1 调用表面
|
||||
|
||||
```markdown
|
||||
> 加一函数 37
|
||||
|
||||
**加一函数 37**
|
||||
|
||||
礼貌 [问候] marqdo
|
||||
```
|
||||
|
||||
前两种解析为对 `加一函数` 的调用;第三种为**方括号标记调用**(`[` `]` 标出函数名,前置裸词展开为 `名=True`)。实参位置或具名绑定;详见 [call-arguments.md](call-arguments.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md)。
|
||||
|
||||
| 形式 | 典型用途 |
|
||||
|------|----------|
|
||||
| `> …` | 步骤列表、独立可执行行、与 v0.2/AI 习惯兼容 |
|
||||
| `**…**` | 嵌在句子中:「或者可以直接这么调用**加一函数 37**」 |
|
||||
| `**x = 加一 37**` | 粗体赋值右侧为调用时**可省略 `>`**(代码即文档首选;`> 加一 37` 仍合法) |
|
||||
| `修饰… [函数] 实参…` | 叙述里需要「形容词 + 动词」时消歧;与 `[键](集合)` 取元靠 `]` 后是否紧邻 `(` 区分 |
|
||||
|
||||
### 6.2 粗体内调用的判别
|
||||
|
||||
粗体内容在去掉外层 `**` 后,按下列优先级分类:
|
||||
|
||||
1. 含 `=` 且左侧为可赋值目标(标识符 / 脚注左值等)→ **赋值语句**(可含右侧调用)。
|
||||
2. 否则,若首词为已知函数/方法/内置/导入成员(Pass 名表可见)→ **调用**。
|
||||
3. 否则 → **表达式语句**(求值后丢弃,或在语句位置非法则诊断)。
|
||||
|
||||
示例:
|
||||
|
||||
| 粗体内容 | 分类 |
|
||||
|----------|------|
|
||||
| `n=n+1` | 赋值 |
|
||||
| `加一函数 37` | 调用 |
|
||||
| `加一函数 n=37` | 调用(具名) |
|
||||
| `n + 1` | 表达式(单独出现时;作返回应写 `*n + 1*`) |
|
||||
| `print text=hi` / `打印 内容=你好` | 调用(内置) |
|
||||
|
||||
### 6.3 方法调用
|
||||
|
||||
- 独立行:`` > `对象`.方法 … ``(兼容)或 `> 对象.方法 …`(若接收者规则允许)。
|
||||
- 粗体内:`**对象.方法 …**` / `**p = page.主体装配 组件=home**`。
|
||||
- 粗体/斜体内裸名 = 变量(延续 v0.2「段内统一命名空间」精神)。
|
||||
|
||||
### 6.4 实参
|
||||
|
||||
具名 + 位置混用规则继承 [call-arguments.md](call-arguments.md);v0.3 仅把「形参列表来源」从 `+` 行改为**推断签名**(§8)。独立 `>` 行上裸词仍为文本字面量;粗体内调用的裸词为变量(与 v0.2「段内调用」一致)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 返回
|
||||
|
||||
### 7.1 斜体返回
|
||||
|
||||
```markdown
|
||||
*n*
|
||||
*n + 1*
|
||||
*"ok"*
|
||||
```
|
||||
|
||||
斜体内部值语法与 v0.2 粗体返回内部相同(裸词 = 变量;文本须引号)。
|
||||
|
||||
### 7.2 空返回与收束(已决议)
|
||||
|
||||
Marqdo **不引入** `return` 关键字;「无值结束」用标记表达。对照常见语言:
|
||||
|
||||
| 语言 | 无值 / 空返回 | Marqdo v0.3 对应 |
|
||||
|------|----------------|------------------|
|
||||
| Python | `return` / `return None` | 显式 `*None*`·`*无*` |
|
||||
| Go | 无结果函数里的 `return` | `*None*` / 整行 `**` / `****` |
|
||||
| Rust | `()` 或函数末尾隐式 unit | 同上;或下一标题 / EOF 自然结束 |
|
||||
| JavaScript | `return;` → `undefined` | 同上 → 运行时 `None` |
|
||||
| Marqdo 历史 | `---` 收束;`****` | `---` 已改为叙述跳过;`****` 仍兼容 |
|
||||
|
||||
#### 形式层级(推荐自上而下)
|
||||
|
||||
| 优先级 | 形式 | 语义 | 说明 |
|
||||
|--------|------|------|------|
|
||||
| **1. 显式空值** | `*None*` 或 `*无*`(整段或行内返回位) | 返回 `None` **并结束本函数体解析** | 对齐 Python `return None`;副作用函数首选;外层续写依赖此收束 |
|
||||
| **2. 空斜体标记** | **整行** trim 后恰为两个星号:`**` | 同上 | 词法钉死:`^\s*\*\*\s*$` → **空斜体返回**,**不得**当成粗体开闭 |
|
||||
| **3. 兼容** | 整行 `****`(四个星号) | 同空返回 | 迁移期识别 |
|
||||
| **(非收束)** | 整行 `---` / `***` | **仅叙述分隔**,跳过 | 不再结束函数;见 [code-as-docs-gaps.md](code-as-docs-gaps.md) |
|
||||
|
||||
```markdown
|
||||
## 只打印
|
||||
**print text=hi**
|
||||
*None*
|
||||
|
||||
## 空斜体行
|
||||
**print text=hi**
|
||||
**
|
||||
|
||||
## 分割线不收束(下一标题才结束)
|
||||
**print text=hi**
|
||||
---
|
||||
```
|
||||
|
||||
#### 词法消歧(空斜体 vs 粗体)
|
||||
|
||||
1. **整行恰好 `**`(两个 `*`)** → 空返回(规则 2),不是未闭合粗体。
|
||||
2. **粗体代码**至少包住一个非空内容:`**x**`、`**n=1**`;不允许「空粗体代码段」作为语句。
|
||||
3. **四个星号整行 `****`** → 兼容空返回(规则 3),不解释为「空粗体代码」。
|
||||
4. 行内出现的 `**…**`(两侧还有叙述文字)按正常粗体代码扫描,不走「整行空返回」。
|
||||
|
||||
#### 与「有返回值」的关系
|
||||
|
||||
- 需要把值交回调用方 → 用非空斜体:`*n*`、`*n + 1*`(返回即结束本函数体解析)。
|
||||
- 只做副作用、不要值 → 优先 `*None*` / `*无*` / 整行 `**`。
|
||||
- 下一标题或 EOF 也可结束体;**不要**再靠 `---` 收束。
|
||||
|
||||
### 7.3 与 else 臂 `N. *` 的消歧
|
||||
|
||||
有序列表臂头 `2. *` 中的 `*` 表示 **else**,不是返回。判别:行匹配 `^\s*\d+\.\s+\*\s*$`(可带尾注)→ 分支 else;不进入返回扫描。
|
||||
|
||||
### 7.4 输出
|
||||
|
||||
```markdown
|
||||
**print text=Hello**
|
||||
> print text=Hello
|
||||
```
|
||||
|
||||
打印是调用,不是返回。禁止把 `*Hello*` / `**Hello**` 解释为「打印 Hello」(延续 v0.2 决议精神,仅对调标记)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 形参推断
|
||||
|
||||
### 8.1 目标签名
|
||||
|
||||
对每个 `## 函数`(及方法),在 Pass1 收集体之后得到:
|
||||
|
||||
```text
|
||||
params: Vec<{ name, default: Option<Expr>, span }>
|
||||
```
|
||||
|
||||
### 8.2 收集规则(函数作用域)
|
||||
|
||||
扫描该函数标题之下、下一同级/更高级标题之前的所有节点,维护**绑定图**与**形参表**(二者分离):
|
||||
|
||||
#### A. 绑定图(所有变量)
|
||||
|
||||
1. **声明事件**:叙述或代码中的首次 `` `名` ``,或粗体内首次对 `名` 的赋值左值。
|
||||
2. **默认/初值事件**:叙述 `` `名`=默认表达式 ``;或符合 §8.3 的「形参默认」赋值。
|
||||
3. **排除出绑定图**(不建变量):
|
||||
- 循环变量 `` - [项](集合) `` 中的 `项`(循环自有绑定);
|
||||
- `self` / `自`(方法自动注入)。
|
||||
|
||||
凡进入绑定图的名字都是**变量**——包括「只在叙述里出现、可执行代码从未读写」的名字(§4.4)。未使用 → **不报错**。
|
||||
|
||||
#### B. 升为形参的条件(升参)
|
||||
|
||||
名字已在绑定图中,且满足下列之一,才进入 `params`:
|
||||
|
||||
| 升参种类 | 条件 |
|
||||
|----------|------|
|
||||
| **必选形参** | 在可执行面(`**…**` / `*…*` / `>` / 结构语句)中存在对 `名` 的**读取**,且该读取无法单靠「不依赖外部输入的局部赋值」满足——典型:先声明、后 `n=n+1` / `*n*` / `**print text=n**` 等读到未先行赋成纯局部常量 |
|
||||
| **可选形参** | 有默认/初值事件(`` `名`=… `` 或 §8.3 默认赋值),供调用方覆盖 |
|
||||
|
||||
**不升参**:仅叙述声明、可执行面零读取(死绑定)→ 留在绑定图,**不进** `params`,调用签名不变。
|
||||
|
||||
**顺序**:按升参名字的**首次声明事件**在源码中的出现序。
|
||||
|
||||
**仍排除**:分支/块内纯局部(金样例钉启发式);显式 `+` 合并见 §8.4。
|
||||
|
||||
### 8.3 「形参默认」与「函数体赋值」的区分
|
||||
|
||||
```markdown
|
||||
## 问候
|
||||
对`谁`打招呼,默认`礼貌`=False。
|
||||
|
||||
**print text=谁**
|
||||
```
|
||||
|
||||
- `` `谁` `` → 必选
|
||||
- `` `礼貌`=False `` → 可选,默认 `False`
|
||||
- 体里的 `**print …**` 不是给 `谁` 赋默认值
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
输入`n`。**n=n+1**返回*n*。
|
||||
```
|
||||
|
||||
- `` `n` `` 先声明 → 必选
|
||||
- `**n=n+1**` 是**体语句**(对已声明形参赋值),**不是**默认值
|
||||
|
||||
判别启发式(实现契约):
|
||||
|
||||
- 若赋值右值**依赖同名左值**(如 `n=n+1`)→ 体语句。
|
||||
- 若赋值出现在「该名被当作输入读取」之前,且右值不依赖未绑定的同名 → 可作为默认值候选。
|
||||
- 叙述形 `` `名`=字面量 `` 优先视为默认值声明。
|
||||
|
||||
### 8.4 显式 `+` 形参(过渡)
|
||||
|
||||
- 若函数标题下仍有 `` + `名` `` 行:与推断结果**合并**;冲突时 **显式 `+` 胜出**并诊断警告。
|
||||
- 迁移完成后(路线图 M4)可改为:存在 `+` 则关闭推断,或直接废弃 `+`。
|
||||
|
||||
### 8.5 调用绑定
|
||||
|
||||
与现有一致:具名优先,位置按「尚未绑定的形参」从左到右填充。缺必选形参 → 语义错误。
|
||||
|
||||
---
|
||||
|
||||
## 9. 完整示例(规范金样意向)
|
||||
|
||||
### 9.1 加一(动机例)
|
||||
|
||||
```markdown
|
||||
## 加一函数
|
||||
|
||||
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
|
||||
|
||||
# main
|
||||
|
||||
我要调用加一函数可以采用这样的办法:
|
||||
|
||||
> 加一函数 37
|
||||
|
||||
或者可以直接这么调用**加一函数 37**
|
||||
```
|
||||
|
||||
期望:
|
||||
|
||||
- 签名:`加一函数(n)`
|
||||
- `# main` 两次调用均返回 `38`(第二次若未绑定到打印,至少 AST/求值结果为 38;可用 `**print text=…**` 观测)。
|
||||
|
||||
### 9.2 带默认值
|
||||
|
||||
```markdown
|
||||
## 问候
|
||||
|
||||
向`谁`问好;`礼貌`=False 时用短句。
|
||||
|
||||
1. 礼貌
|
||||
**print text=您好,**
|
||||
**print text=谁**
|
||||
2. *
|
||||
**print text=嗨,**
|
||||
**print text=谁**
|
||||
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**问候 谁=Marqdo 礼貌=True**
|
||||
> 问候 Marqdo
|
||||
```
|
||||
|
||||
### 9.3 对象方法(不变骨架)
|
||||
|
||||
```markdown
|
||||
# 计数器
|
||||
## 加
|
||||
将`self`的`值`增加`delta`(`delta`=1)。
|
||||
**值 = 值 + delta**
|
||||
*self*
|
||||
|
||||
# main
|
||||
*c = > 计数器*
|
||||
**c.加 3**
|
||||
```
|
||||
|
||||
(方法形参推断含 `delta`;`self` 自动。)
|
||||
|
||||
---
|
||||
|
||||
## 10. AST / 管线变更要点(设计约束)
|
||||
|
||||
详细里程碑见 [markup-v0.3.md](../roadmap/markup-v0.3.md)。此处只钉**语义 → 树**的约束,供实现对照:
|
||||
|
||||
### 10.1 行分类(lex / line-class)
|
||||
|
||||
新增或调整类别:
|
||||
|
||||
| 类别 | 说明 |
|
||||
|------|------|
|
||||
| `Prose` | 叙述行;需**内联扫描** |
|
||||
| `BoldCode` | 整行或片段 `**…**` |
|
||||
| `ItalicReturn` | 整行或片段 `*…*`(非 else 臂) |
|
||||
| `CallLine` | `>` 调用(保留) |
|
||||
| … | 原有 Heading / List / Table / Fence / Hr |
|
||||
|
||||
**内联扫描**产出 `InlineBit`:`Text` | `IdentDecl/Ref` | `BoldCode` | `ItalicReturn`。
|
||||
|
||||
### 10.2 AST 节点调整(建议)
|
||||
|
||||
```text
|
||||
Param { name, default?, inferred: bool, span } // inferred=true 表示来自体推断
|
||||
|
||||
Stmt::
|
||||
Assign { … } // 多由 BoldCode 解析
|
||||
Call { … } // CallLine 或 BoldCode 判别为调用
|
||||
Return { value } // 由 ItalicReturn 解析(原由 Bold)
|
||||
ExprStmt { … } // 可选:纯表达式粗体
|
||||
Prose { bits } // 可选:保留叙述结构供 view/catalog;求值阶段只消费 Decl
|
||||
|
||||
FnDef.params:
|
||||
由 InferParams(body + prose bits) 填充,再合并显式 +
|
||||
```
|
||||
|
||||
`Stmt::Return` 的**语法来源**从粗体改为斜体;dump 文本应写 `return←italic`。
|
||||
|
||||
### 10.3 Pass1 / Pass2
|
||||
|
||||
- Pass1:收集 `#`/`##` 结构;建绑定图;跑 **ParamInfer(升参)**;登记名表。
|
||||
- Pass2:粗体内调用名解析;叙述 Decl 不重复建参。
|
||||
- 诊断:**必选缺失**、`+` 与推断冲突、空返回词法歧义(非整行 `**` 的残缺粗体)。
|
||||
- Lint(可选、默认关或降级为 hint):绑定图中「从未读写」的死变量——**不得**当错误。
|
||||
|
||||
### 10.4 双后端
|
||||
|
||||
树遍历与字节码均消费同一 AST;字节码发射仅跟随 `Stmt`/`Expr` 变化,不感知 Markdown 标记。
|
||||
|
||||
---
|
||||
|
||||
## 11. 破坏性切换(无双模式)
|
||||
|
||||
**产品决定(2026-09-13):** 直接以 v0.3 为唯一运行时映射;**不**保留 `--markup v0.2` / 双 edition。旧语法金样例与库文件在迁移完成前可能失败——可接受。
|
||||
|
||||
| 阶段 | 行为 |
|
||||
|------|------|
|
||||
| 现在 | 解析器切到 v0.3;`tests/markup-v03/` 为门禁 |
|
||||
| 随后 | 批量改写 `tests/structure|keywords`、`lib/`、`ext/`、Skill、`public/` |
|
||||
| 文档 | `markdown-mapping.md` 改为指向本文;ADR 0005 → Accepted |
|
||||
|
||||
**机械改写:**
|
||||
|
||||
- 语句 `*a = 1*` → `**a = 1**`
|
||||
- 返回 `**x**` → `*x*`
|
||||
- 粗体内文本字面量须引号:`**print text="hi"**`(裸词 = 变量)
|
||||
- 调用可保留 `>` 或改为粗体
|
||||
- `` + `n` `` 可删,改为叙述 `` `n` `` + 升参
|
||||
|
||||
---
|
||||
|
||||
## 12. 开放问题 / 已决议
|
||||
|
||||
| # | 议题 | 状态 | 决议摘要 |
|
||||
|---|------|------|----------|
|
||||
| 1 | 空返回词法 | **已决议** | §7.2:推荐 `*None*`/`*无*`;整行 `**`;兼容 `****`;`---` 仅叙述跳过 |
|
||||
| 2 | 提及性反引号 | **已决议** | §4.4:一律视作变量;未使用不报错、不升参;不设提及前缀 |
|
||||
| 3 | 粗体内调用 vs 赋值 | **已落地** | §6.2:可赋值左值 → 赋值;否则表达式优先、再裸调用;`**n + 1**` = ExprStmt |
|
||||
| 4 | `` `n`+1 `` 误声明 | **已落地** | Decl 名须为标识符;`` `n+1` `` 不升 Decl |
|
||||
| 5 | 叙述强调斜体 vs 返回 | **已落地** | 整行 / `返回*…*` / 表达式形才当返回;`*only*` `*very important*` `*foo.bar*` 为叙述 |
|
||||
| 6 | 一行多 `**…**` | **已落地** | 允许,按出现序执行(`tests/markup-v03/multi-bold.mq.md`) |
|
||||
| 7 | view 展示 prose Decl | **已落地** | Structure / Functions 大纲:`inferred` 形参标注(`chip inferred`) |
|
||||
|
||||
---
|
||||
|
||||
## 13. 非目标
|
||||
|
||||
- 不把整篇无标记 Markdown 变成可执行程序。
|
||||
- 不引入 `def` / `return` 关键字(空返回用标记,见 §7.2)。
|
||||
- 不改变 `#` / `##` 对象体系与 ext 插件 ABI。
|
||||
- 不在本文阶段修改解释器代码(见路线图)。
|
||||
- 不为「提及」另发明一套反引号方言(§4.4)。
|
||||
|
||||
---
|
||||
|
||||
## 14. 验收标准(设计完成 ≠ 实现完成)
|
||||
|
||||
设计稿验收:
|
||||
|
||||
- [x] 哲学 P1–P6 成文
|
||||
- [x] 与 v0.2 对照表
|
||||
- [x] 形参推断规则可实现(含升参 vs 死绑定)
|
||||
- [x] 动机示例在语义上闭合
|
||||
- [x] AST/管线约束与路线图挂接
|
||||
- [x] ADR 记录决策意向
|
||||
- [x] **空返回**对照其它语言并钉死词法
|
||||
- [x] **提及/未使用变量**政策钉死
|
||||
|
||||
实现验收:
|
||||
|
||||
- [x] 金样例夹具 `tests/markup-v03/`(`gold.rs` `markup_v03_*`)
|
||||
- [x] 动机示例金样例通过(`inc-prose.mq.md`)
|
||||
- [x] `--dump-ast` 可见 inferred params 与死绑定;`--dump-lines` 标注 `[decl]` / `[bold]` / `[italic]`
|
||||
- [x] 空返回四种形式金样例通过
|
||||
- [x] 无 v0.2 双模式(默认即 v0.3)
|
||||
|
||||
---
|
||||
|
||||
## 15. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-09-13 | 初稿:叙述统一、粗体代码、斜体返回、形参体推断;Proposed |
|
||||
| 2026-09-13 | 决议空返回(§7.2)与提及性反引号(§4.4);形参改为「升参」与绑定图分离(§8.2) |
|
||||
| 2026-09-14 | §7.2:`---` 不再收束;返回语句结束函数体解析;空返回首选 `*None*` |
|
||||
| 2026-09-14 | 取元主语法改为 `[键](集合)`;脚注取元过渡保留 |
|
||||
@@ -2,9 +2,10 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、同级再 `1.` 为新分支、标识符反引号、`-` 专用于循环) |
|
||||
| 状态 | **历史文档(v0.2 · 已废止为运行时)** — 现行见 **[markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)** |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 取代 | v0.1 中「函数头 `-` 形参 / 裸名形参与遍历变量 / `+` 分支」 |
|
||||
| 被取代 | **[markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)**(粗体即代码 · 斜体即返回 · 无双模式兼容) |
|
||||
| 相关 | [objects.md](objects.md) · [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) · [module-namespace.md](module-namespace.md) |
|
||||
|
||||
Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。
|
||||
|
||||
@@ -23,9 +23,9 @@ marqdo dump FILE --stage lines|tokens|ast|sema|all
|
||||
|
||||
| 标志 | 阶段 | 输出内容 |
|
||||
|------|------|----------|
|
||||
| `--dump-lines` | 行分类 | 每行:`LINE kind=Comment\|Code\|Blank` + 原文预览 |
|
||||
| `--dump-lines` | 行分类 | 每行:`kind=Comment\|Code\|Blank` + 原文;v0.3 行内位 `[decl n]` / `[bold …]` / `[italic …]` |
|
||||
| `--dump-tokens` | 词法 | Token 流:`type lexeme line:col` |
|
||||
| `--dump-ast` | 语法 | S 表达式或缩进树(模块/函数/语句) |
|
||||
| `--dump-ast` | 语法 | 模块/函数/语句;形参带 `inferred`;叙述死绑定 `dead=[…]` |
|
||||
| `--dump-sema` | 语义 | 作用域、导入图、提升后的符号表 |
|
||||
| `--trace-eval` | 求值 | **JSON 行**(stderr):语句级事件,含 `path` / `span`(`line:col`) |
|
||||
| `--dump-bytecode` | 字节码 | 反汇编 `Program`(指令旁带 `@line:col`;见 [bytecode.md](bytecode.md)) |
|
||||
|
||||
@@ -2,18 +2,36 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已决议(并入 mapping v0.1 + keywords;2026-08-04 修订函数收束) |
|
||||
| 状态 | **v0.2 已决议**(现行实现);**v0.3 拟对调 `*` / `**` 角色**(见下) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 修订 | 2026-09-13:挂接 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) |
|
||||
|
||||
---
|
||||
|
||||
## 决议
|
||||
## 决议(v0.2 · 现行)
|
||||
|
||||
1. **`*…*` = 程序语句**。
|
||||
2. **`**…**` = 返回值**(架构级);空粗体 `****` / `** **` = 空返回(`None`)并结束函数体。
|
||||
3. **输出**用内置函数 **`print`**(英文),不是粗体,不是中文名。
|
||||
4. **`---` / `***`(函数体顶层)**:结束本函数体(无返回值函数收束);**不是**分支/循环装饰框。
|
||||
4. **`---` / `***`**:Markdown 叙述分隔(跳过);**不再**结束函数体。无值收束用 `*None*` / 整行 `**` / `****`(见 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) §7.2)。
|
||||
5. **成段注释**:空行分段;段内续行不因首字符升级为代码。
|
||||
6. **否决**:无标记行 = 默认代码。
|
||||
|
||||
详见 [keywords.md](keywords.md)、[markdown-mapping.md](markdown-mapping.md)、[code-vs-comment.md](code-vs-comment.md)。
|
||||
|
||||
---
|
||||
|
||||
## v0.3 意向(Proposed · 未实现)
|
||||
|
||||
产品方重新审视后,拟在 [ADR 0005](../adr/0005-prose-unified-markup.md) 下**对调**架构标记,并放宽叙述面:
|
||||
|
||||
| 概念 | v0.2 | v0.3 草案 |
|
||||
|------|------|-----------|
|
||||
| 代码段 / 语句 | `*…*` | `**…**` |
|
||||
| 返回值 | `**…**` | `*…*` |
|
||||
| 空返回 | `****` / 空粗体;或 `---` | **推荐 `*None*`/`*无*`**;整行 `**`;兼容 `****`;`---` 仅叙述 |
|
||||
| 输出 | 仍为 `print` / `打印` | 不变 |
|
||||
| 无标记 = 默认代码 | 否决 | **仍否决** |
|
||||
| 叙述中 `` `名` `` | 通常无绑定义 | 一律变量;未使用 OK;升参需可执行面读取 |
|
||||
|
||||
完整规则与迁移见 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)。**v0.3 已为运行时;本文件历史决议中「`---` 收束」已废止。**
|
||||
@@ -0,0 +1,29 @@
|
||||
# `lib/csv` — 逗号表(Mid M4)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M4)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-text-mid.md](stdlib-text-mid.md) · [stdlib-mid.md](stdlib-mid.md) |
|
||||
| 导入 | `lib/csv.mq.md` · `lib/逗号表.mq.md` |
|
||||
| Host | `host_csv_*`(RFC4180 最小集,无第三方 crate) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `parse` | `解析` | `text` | **list of maps**:首行为表头 |
|
||||
| `stringify` | `序列化` | `rows` | CSV 文本(表头 = 首行 map 的键顺序) |
|
||||
|
||||
## 2. 方言(v1)
|
||||
|
||||
- 分隔符 `,`;引号 `"`;`""` 转义。
|
||||
- 换行 `\n` / `\r\n`;忽略末尾空行。
|
||||
- 字段内可含逗号与换行(须加引号)。
|
||||
- **不**支持自定义分隔符 / 无表头模式(可后续加)。
|
||||
|
||||
## 3. 刻意不做
|
||||
|
||||
流式大文件、类型推断、Excel 方言。
|
||||
@@ -0,0 +1,40 @@
|
||||
# 设计:`lib/datetime` / `lib/日期时间`(Mid2 M7)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地** |
|
||||
| 日期 | 2026-09-09 |
|
||||
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §2.1 |
|
||||
| 宿主 | `src/host/datetime.rs` · `host_datetime_*` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 时刻形状
|
||||
|
||||
每次返回 **map**:
|
||||
|
||||
| 键 | 含义 |
|
||||
|----|------|
|
||||
| `unix` | 秒级 Unix 戳(int) |
|
||||
| `zone` | 固定偏移文本,如 `+08:00` / `+00:00` |
|
||||
| `iso` | RFC3339(秒精度) |
|
||||
|
||||
`to_unix` 也接受裸 int 或 ISO 文本。
|
||||
|
||||
## 2. API
|
||||
|
||||
| EN | ZH | 说明 |
|
||||
|----|-----|------|
|
||||
| `now` | `现在` | UTC 此刻(wasm 无时钟桥则失败) |
|
||||
| `from_unix` | `自戳` | `unix` + 可选 `zone` |
|
||||
| `to_unix` | `成戳` | |
|
||||
| `parse` | `解析` | 默认 RFC3339 / `YYYY-MM-DD[ HH:MM:SS]`;`pattern=` |
|
||||
| `format` | `格式化` | `rfc3339`/`date`/`time` 或 strftime |
|
||||
| `add` | `加` | `days`/`hours`/`minutes`/`seconds` |
|
||||
| `in_zone` | `时区` | 同瞬间换区 |
|
||||
|
||||
**区名**:`+HH:MM` / `UTC` / `Z`,以及少量固定偏移别名(如 `Asia/Shanghai`)。**不做**完整 tzdb / DST。
|
||||
|
||||
## 3. 与 `lib/time`
|
||||
|
||||
`lib/time` 保留极简 unix/format/parse/sleep。日历语义用本库。
|
||||
@@ -0,0 +1,32 @@
|
||||
# `lib/encoding` — 编解码(Mid M1)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M1)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [stdlib-re.md](stdlib-re.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 导入 | `lib/encoding.mq.md` · `lib/编码.mq.md` |
|
||||
| Host | `host_encoding_*`(无第三方 crate:标准 Base64 / hex) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `base64_encode` | `基64编码` | `text` | 文本(UTF-8 字节 → 标准 Base64,含 `=` 填充) |
|
||||
| `base64_decode` | `基64解码` | `text` | 文本(解码后须为合法 UTF-8) |
|
||||
| `hex_encode` | `十六进制编码` | `text` | 小写 hex |
|
||||
| `hex_decode` | `十六进制解码` | `text` | 文本(偶数字节;合法 UTF-8) |
|
||||
|
||||
## 2. 与 `net.url_encode` 的边界
|
||||
|
||||
| 能力 | 归属 |
|
||||
|------|------|
|
||||
| `application/x-www-form-urlencoded` 风格 | `net.url_encode` |
|
||||
| Base64 / hex | **本库** |
|
||||
| 百分号编解码通用版 | 可日后加 `encoding.percent_*`;本波不做 |
|
||||
|
||||
## 3. 刻意不做(v1)
|
||||
|
||||
URL-safe Base64 变体开关、忽略空白的宽松解码、二进制 `bytes` 类型(仍经 UTF-8 文本往返)。
|
||||
@@ -0,0 +1,24 @@
|
||||
# `lib/fs` 加厚 — 复制 / 移动 / 临时文件(Mid M2)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M2)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-path.md](stdlib-path.md) · [stdlib-mid.md](stdlib-mid.md) |
|
||||
| 边界 | **文本与普通文件**;不引入 `bytes` 类型(`read_bytes` 延后) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 新增 API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `copy_file` | `复制文件` | `src`, `dest` | `None`(覆盖已存在的目标文件) |
|
||||
| `move` | `移动` | `src`, `dest` | `None`(rename;跨设备失败则报错) |
|
||||
| `make_temp` | `建临时` | 可选 `prefix` | 相对 `cwd`/`fs_root` 的新空文件路径文本 |
|
||||
|
||||
均走现有 `resolve_path` 沙箱;写操作受 `fs_write` 策略约束。
|
||||
|
||||
## 2. 刻意不做
|
||||
|
||||
目录树 `copy_tree`、原子替换、`read_bytes`、权限 chmod。
|
||||
@@ -0,0 +1,25 @@
|
||||
# 设计:`lib/fs` Mid2 加厚(M9)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地** |
|
||||
| 日期 | 2026-09-09 |
|
||||
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §4 · [stdlib-fs-mid.md](stdlib-fs-mid.md)(M2) |
|
||||
| 宿主 | `src/host/fs.rs` · `host_make_dirs` / `host_remove_tree` / `host_stat` / `host_walk` |
|
||||
|
||||
---
|
||||
|
||||
## API
|
||||
|
||||
| EN | ZH | 行为 |
|
||||
|----|-----|------|
|
||||
| `make_dirs` | `建目录树` | 递归创建(与既有 `make_dir` 同为 `create_dir_all`;显式命名) |
|
||||
| `remove_tree` | `删目录树` | 仅删目录树;路径为文件则报错 |
|
||||
| `stat` | `状态` | `{size, mtime_unix, is_file, is_dir}` |
|
||||
| `walk` | `遍历` | **深度优先**;相对路径列表(正斜杠);含目录项;同级按名排序 |
|
||||
|
||||
既有 `remove` 对目录仍递归删除;`remove_tree` 拒绝文件,语义更窄。
|
||||
|
||||
## 刻意不做
|
||||
|
||||
ACL、watch、硬链接、`copy_tree`、惰性迭代器协议。
|
||||
@@ -0,0 +1,26 @@
|
||||
# `lib/hash` — 摘要与 HMAC(Mid M3)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M3)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [stdlib-secrets.md](stdlib-secrets.md) |
|
||||
| 导入 | `lib/hash.mq.md` · `lib/哈希.mq.md` |
|
||||
| Host | `host_hash_*`(`sha2` / `sha1` / `md-5` / `hmac`) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `sha256` | `哈希256` | `text` | 小写 hex |
|
||||
| `sha1` | `哈希1` | `text` | 小写 hex |
|
||||
| `md5` | `md5` | `text` | 小写 hex |
|
||||
| `hmac_sha256` | `密钥哈希256` | `key`, `text` | 小写 hex |
|
||||
|
||||
输入按 **UTF-8 字节**摘要。文档标明:用于完整性标识 / 缓存键,**不是**密码存储(无 Argon2/bcrypt)。
|
||||
|
||||
## 2. 刻意不做
|
||||
|
||||
密码哈希、流式大文件哈希 API、非 UTF-8 二进制类型。
|
||||
@@ -0,0 +1,19 @@
|
||||
# 设计:`lib/html` / `lib/超文本`(Mid2 M8)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地** |
|
||||
| 日期 | 2026-09-09 |
|
||||
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §3.2 |
|
||||
| 宿主 | `src/host/html_ops.rs` · `host_html_escape` / `host_html_unescape` |
|
||||
|
||||
---
|
||||
|
||||
## API
|
||||
|
||||
| EN | ZH | 行为 |
|
||||
|----|-----|------|
|
||||
| `escape` | `转义` | `& < > " '` → 实体(`'` → `'`) |
|
||||
| `unescape` | `还原` | 上述实体(含 `'` / `'`) |
|
||||
|
||||
**不做** DOM / 模板引擎。
|
||||
@@ -0,0 +1,36 @@
|
||||
# `lib/table` 集合加厚 + `lib/cli`(Mid M5)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M5)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 集合 | 加厚现有 `lib/table` / `lib/表`(不另开 `listx`) |
|
||||
| CLI | `lib/cli.mq.md` / `lib/命令行.mq.md` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 集合新增
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `sort` | `排序` | `list` | 升序列表(int/num/text 优先;其它按显示文本) |
|
||||
| `sort_by` | `按键排序` | `list`, `key` | 对 **map 列表**按键值排序 |
|
||||
| `unique` | `去重` | `list` | 保序去重 |
|
||||
| `chunk` | `分块` | `list`, `size` | 列表的列表 |
|
||||
| `zip` | `拉链` | `a`, `b` | `[[a0,b0], …]`(取较短长度) |
|
||||
| `flatten` | `展平` | `list` | 一层展平 |
|
||||
|
||||
`reverse` 已有。
|
||||
|
||||
## 2. CLI
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `parse` | `解析` | 可选 `args` | map:`--k v` / `--k=v` → 文本;裸 `--flag` → `True`;位置参 → 键 `_` 列表 |
|
||||
|
||||
`args` 缺省时用 `sys.args`(经宿主 `argv`)。
|
||||
|
||||
## 3. 刻意不做
|
||||
|
||||
稳定自定义比较器、惰性迭代器、完整 argparse 互斥组。
|
||||
@@ -0,0 +1,30 @@
|
||||
# `lib/log` + `lib/uuid`(Mid M6)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 日志 `lib/log` / `lib/日志`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `set_level` | `设级别` | `level`(`debug`/`info`/`warn`/`error`) | `None` |
|
||||
| `debug` / `info` / `warn` / `error` | `调试` / `信息` / `警告` / `错误` | `text` | 达级别则 `print` 一行 `LEVEL message`;否则无输出 |
|
||||
|
||||
默认级别:`info`(隐藏 `debug`)。中文级别别名:`调试`/`信息`/`警告`/`错误`。
|
||||
|
||||
实现:宿主记最小级别;`host_log_line` 返回待打印文本或 `None`;L1 再 `print`(接入现有 stdout / capture)。
|
||||
|
||||
## 2. UUID `lib/uuid` / `lib/标识`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `v4` | `版本4` | (无) | 标准 8-4-4-4-12 小写 hex(`getrandom`) |
|
||||
|
||||
## 3. 刻意不做
|
||||
|
||||
结构化 JSON 日志、远程 sink、UUID v1/v7、yaml。
|
||||
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| 状态 | **已实现(M1–M4)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) · 大学线性代数见规划 [ext-linalg.md](ext-linalg.md) |
|
||||
| 导入 | `lib/math.mq.md`(英)· `lib/数学.mq.md`(中) |
|
||||
| 范围 | **高中数学**(初等函数、导数、圆锥曲线、简单方程);非大学 CAS |
|
||||
|
||||
@@ -92,7 +92,7 @@ $$
|
||||
| 代入求值 | `subs` → `num` 或公式 |
|
||||
| 求解 | 一元一次 / 二次闭式;其它用数值求根并标明 |
|
||||
|
||||
**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、矩阵、复数完备、任意证明。
|
||||
**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、**大学线性代数**(符号矩阵表达式 / 分解 —— 见 [ext-linalg.md](ext-linalg.md))、复数完备、任意证明。数值小矩阵字面量可在 `$$` 中解析为 `formula::Matrix`,但符号 MatExpr 与分解不在 `lib/math`。
|
||||
|
||||
### 3.2 作图(P)
|
||||
|
||||
@@ -210,6 +210,7 @@ Interpreter.plots: Vec<Stringimport math:lib/math.mq.md · lib/数学.mq.md
|
||||
- `$$:name` 模块级具名绑定(已废除)。
|
||||
- 无名 `$$` 自动进运行时。
|
||||
- 大学级数 / 完备积分 / 定理证明。
|
||||
- **大学线性代数扩展**(见 [ext-linalg.md](ext-linalg.md);不在本库做符号 MatExpr)。
|
||||
- 通用隐函数作图引擎。
|
||||
- 3D、交互式图表库。
|
||||
|
||||
|
||||
@@ -0,0 +1,172 @@
|
||||
# 中层标准库(Mid Stdlib)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **M1–M6 已落地** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-abi.md](ext-abi.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) · **后续** [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) |
|
||||
| 目标 | 在接下来数个发版周期内,把「通用编程」能力沉到 **L0.5 宿主 + L1 `.mq.md`**,减少「凡是稍有能力就必须 ABI 插件」的路径依赖 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么现在做
|
||||
|
||||
现状分层(已落地):
|
||||
|
||||
```text
|
||||
L0 内置 print / len / split / …
|
||||
L0.5 宿主原语 src/host/*(供 L1 包装,作者原则上不直调)
|
||||
L1 官方库 lib/*.mq.md(嵌入二进制 / 可覆盖)
|
||||
ext 官方扩展 .mq.md + 可选 cdylib(web / agent / quantum / linalg)
|
||||
```
|
||||
|
||||
痛点:
|
||||
|
||||
1. **通用语言能力缺口**:`lib/text` 几乎只是 `trim/split/join`;无正则、无编解码、无哈希、无路径代数、无 CSV……日常脚本要么外联 Python,要么新开插件。
|
||||
2. **插件路径过重**:ABI 插件适合**领域热路径**(量子核、公式矩阵、HTTP 服务+SQLite),不适合「再来一个 base64」。每加一个插件都要:crate、Release 资产、`ext add`、CI、WASM 缺口。
|
||||
3. **扩展作者被逼进插件**:`ext/**` 禁止 `host_*`。若 L1 没有正则 / 哈希 / 路径,扩展只能 `plugin.load`,导致「库」与「原生模块」边界模糊。
|
||||
4. **对照成熟语言**:Go 的 `strings` / `regexp` / `encoding/*` / `crypto` / `path/filepath`、Python 的「难写对才进 stdlib」标准——都把**通用原语**留在语言自带层,把**领域产品**留给第三方。Marqdo 的「通用」应对齐前者;`ext/` 对齐后者。
|
||||
|
||||
中层标准库 = **在现有 L1 之上、在官方 ext 之下**,专门补「写通用程序必备、又不该做成插件」的那一档。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层命名(本波约定)
|
||||
|
||||
| 名称 | 位置 | 用户导入 | 实现形态 |
|
||||
|------|------|----------|----------|
|
||||
| **核心 L1** | 已有 `lib/{fs,sys,time,json,net,math,…}` | 是 | 薄包装 → 已有 `host_*` |
|
||||
| **中层 L1(Mid)** | 新增 / 加厚 `lib/{re,encoding,hash,path,…}` | 是(仍属 `lib/` / `std/`) | **优先**薄 `host_*` + L1;能纯 `.mq.md` 则纯库 |
|
||||
| **官方 ext** | `ext/{web,agent,quantum,linalg,ai}` | 显式 `ext/` | `.mq.md`;**仅**领域热路径允许 ABI 插件 |
|
||||
| **catalog / 用户库** | 发版外收录 | 各自约定 | 应能主要靠 Mid + 核心 L1 写成,**默认无插件** |
|
||||
|
||||
> **不**新开第三棵目录树。中层仍落在 `lib/`,用文档与路线图分期交付,避免 `lib/` vs `lib-mid/` 分裂。
|
||||
|
||||
---
|
||||
|
||||
## 3. 准入 / 不准入(宪法)
|
||||
|
||||
### 3.1 进入中层的条件(须同时满足多数)
|
||||
|
||||
| # | 条件 | 说明 |
|
||||
|---|------|------|
|
||||
| 1 | **跨领域高频** | 脚本、站点、智能体、教学示例都会用到 |
|
||||
| 2 | **难写对或不可移植** | 正则、Unicode、密码学、路径跨平台——纯 Marqdo 成本过高 |
|
||||
| 3 | **解锁「无插件写库」** | 有了它,更多 `ext/` / catalog 可用纯 `.mq.md` |
|
||||
| 4 | **宿主面积极小** | 一个或少数 `host_*` + 稳定 crate;不把巨型框架链进主二进制 |
|
||||
| 5 | **API 可长期冻住** | 宁可窄接口,也不提前做成第二个 Requests |
|
||||
|
||||
参考(外部):
|
||||
|
||||
- Python:[stdlib 准入](https://devguide.python.org/developer-workflow/stdlib/) 与 [Language Summit:stdlib 何用](https://blog.python.org/2023/05/the-python-language-summit-2023-what-is.html)——偏「启动器 / 新手脚本 / 难写对的协议」,而非「万物入 std」。
|
||||
- Go:日常几乎离不开的 `strings`、`regexp`、`encoding/*`、`crypto`、`path/filepath`、`slices`——对标我们的 Mid 候选,而非 `database/sql` 驱动全家桶。
|
||||
- 反面:PEP 594「死电池」——过窄协议、过时格式、与生态脱节的模块不要进 Mid。
|
||||
|
||||
### 3.2 明确不准入(继续走 ext + 可选插件)
|
||||
|
||||
| 领域 | 原因 |
|
||||
|------|------|
|
||||
| HTTP **服务端** / ASGI / 路由框架 | 产品面;已有 `ext/web` |
|
||||
| SQLite / ORM / 管理后台 | 同上 |
|
||||
| LLM / 智能体编排 / OKF | `ext/ai` · `ext/agent` |
|
||||
| 量子线路 / 密度矩阵核 | `ext/quantum` |
|
||||
| 大学线性代数 CAS / 分解可视化 | `ext/linalg`(公式文档面) |
|
||||
| 完整图像 / 音视频 / ML | 体积与依赖爆炸 |
|
||||
| 任意第三方云 SDK | 不属于语言 |
|
||||
|
||||
### 3.3 插件仍保留的边界
|
||||
|
||||
ABI 插件 **不废除**。规则收紧为:
|
||||
|
||||
```text
|
||||
若能力可用「少量 host_* + lib/*.mq.md」表达 → 必须走中层,禁止新开官方插件。
|
||||
若能力是领域数值核 / 长生命周期服务 / 可选重依赖 → 才允许官方插件。
|
||||
```
|
||||
|
||||
`lib/plugin` 继续服务:本地实验、第三方原生、官方领域包。
|
||||
|
||||
---
|
||||
|
||||
## 4. 实现分工(怎么长)
|
||||
|
||||
```text
|
||||
用户 / catalog / 官方 ext(纯 mq 优先)
|
||||
│ import re:lib/re.mq.md
|
||||
▼
|
||||
中层 L1(.mq.md,中英分文件,除 json 类共用外)
|
||||
│ **> host_re_find …**
|
||||
▼
|
||||
L0.5 宿主(Rust:regex / sha2 / …)
|
||||
│
|
||||
▼
|
||||
OS / 算法库(精选 crate,默认 features 最小化)
|
||||
```
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| `ext/**` 仍禁止 `host_*` | 中层补齐后,ext 经 `lib/re` 等调用 |
|
||||
| 每个新 `host_*` | 必须有 L1 包装 + 金样 + 中英对称(见 [stdlib-i18n.md](stdlib-i18n.md)) |
|
||||
| 能纯 mq 的 | 例如在 `table` 上的 `sort_by` 若性能可接受,可先纯库;热路径再下沉 host |
|
||||
| WASM | 新 host 须标注是否进浏览器构建;不能 WASM 的在文档标 `host-only` |
|
||||
| 依赖 | 新增 crate 写进 [dependencies.md](dependencies.md) 动机;禁止「顺手」拉大型框架 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 模块候选总表(按优先级波次)
|
||||
|
||||
完整排期与验收见 [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md)。摘要:
|
||||
|
||||
| 波次 | 模块(英 / 中) | 典型能力 | 主要形态 |
|
||||
|------|-----------------|----------|----------|
|
||||
| **M1** | `re` / `正则` · `encoding` / `编码` | match / find / replace;base64 / hex | **done** |
|
||||
| **M2** | `path` / `路径` · `fs` 加厚 | join / normalize;copy / move / temp | **done** |
|
||||
| **M3** | `hash` / `哈希` · `secrets` / `机密` | sha256 / hmac;token | **done** |
|
||||
| **M4** | `csv` / `逗号表` · `text` 加厚 | parse / stringify;contains / replace | **done** |
|
||||
| **M5** | `table` 加厚 · `cli` / `命令行` | sort / zip;flags | **done** |
|
||||
| **M6** | `log` / `日志` · `uuid` / `标识` | level 日志;v4 | **done** |
|
||||
| **可选(Mid1)** | `yaml` | 默认 **不做** | 见 Mid2:优先 TOML |
|
||||
|
||||
**Mid1 刻意延后、现已升格到 Mid2:** 日历/时区、URL 解析 —— 见 [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md)。
|
||||
|
||||
**仍不准入 Mid:** 连接池、异步 runtime、模板引擎、完整 `collections` 类型系统、HTTP 服务端 / SQLite(`ext/`)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 与现有库的关系
|
||||
|
||||
| 现有 | 中层策略 |
|
||||
|------|----------|
|
||||
| `lib/text` | **加厚**,不另起 `strings` 英文名(保持 Marqdo 习惯);中文 `文本` |
|
||||
| `lib/table` | Mid 集合算法优先挂这里或薄 `listx`;避免与 GFM 表语义打架 |
|
||||
| `lib/net` | HTTP 客户端保留;编解码类能力与 `encoding` 边界写清(url 组件归谁) |
|
||||
| `lib/math` | 保持**高中**;哈希 / 安全随机不进 math |
|
||||
| `lib/json` | 仍只 parse/stringify/quote;CSV/YAML 另库 |
|
||||
| `lib/plugin` | 不变;文档写明「通用能力请先查 Mid」 |
|
||||
| `ext/*` | 逐步**改写依赖**:能改用 `lib/re` 的路由/校验,去掉不必要的原生 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 文档与工程节奏
|
||||
|
||||
每个 Mid 波次固定流水线(与现有发版习惯对齐):
|
||||
|
||||
1. 本设计不变的前提下,在 roadmap 勾选该波次工作项。
|
||||
2. `doc/design/stdlib-<module>.md`(可短)→ `host_*` → `lib/` 中英 → `tests/lib/*` 金样 → `public/features` 短文。
|
||||
3. 更新 [stdlib-modules.md](stdlib-modules.md) 模块表。
|
||||
4. **不**为 Mid 单开 SemVer 故事;随正常产品发版收进 CHANGELOG「标准库」小节。
|
||||
5. 发版技能 / Release 资产:仅当新增 **必须** 随 CLI 分发的东西时改 release 脚本——Mid 默认已嵌入 stdlib,**无** native zip。
|
||||
|
||||
---
|
||||
|
||||
## 8. 成功标准(数个版本后)
|
||||
|
||||
1. 用 Mid + 核心 L1 **不加载任何插件**,能写:日志采集脚本、CSV 清洗、带正则的文本管线、带哈希校验的下载器、简单 CLI 工具。
|
||||
2. 新的官方 **非领域** 能力默认进 `lib/`,评审时问:「能否不做成插件?」
|
||||
3. `ext/web` / `ext/agent` 等仍可有插件,但依赖面写进文档:哪些能力已改走 Mid。
|
||||
4. 主二进制体积与依赖可解释;WASM 可用性有清单。
|
||||
|
||||
---
|
||||
|
||||
## 9. 一句话
|
||||
|
||||
**中层标准库把「通用原语」沉回语言自带层,让插件专属于真正的领域引擎——这样 Marqdo 才像一门通用语言,而不是「Markdown + 一堆 .so」。**
|
||||
@@ -0,0 +1,139 @@
|
||||
# 设计:中层标准库第二波(Mid2 · M7–M10)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · M7–M10 已落地(zip 跳过)** |
|
||||
| 日期 | 2026-09-09 |
|
||||
| 缺口盘点 | [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) |
|
||||
| 路线图 | [stdlib-mid2.md](../roadmap/stdlib-mid2.md) |
|
||||
| 宪法 | [stdlib-mid.md](stdlib-mid.md) §3(准入 / 不准入 **不变**) |
|
||||
| 目标 | 在 M1–M6 之上补「日历 · URL · 配置 · HTML 安全 · fs 再厚」,仍保持宿主面积极小 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**Mid2 = 第二档通用原语,不是第二套 stdlib。** 仍落在 `lib/` + 薄 `host_*`;禁止借机引入 YAML 全家桶、HTTP 服务端、数据库。
|
||||
|
||||
---
|
||||
|
||||
## 1. 分层与禁止
|
||||
|
||||
| 允许 | 禁止 |
|
||||
|------|------|
|
||||
| 新 `lib/*.mq.md` 中英对偶 | 新开 `lib-mid2/` 目录树 |
|
||||
| 少数 `host_datetime_*` / `host_url_*` / `host_toml_parse` | 为 Mid 新增 ABI 插件 |
|
||||
| 加厚既有 `fs` / `encoding` / `net` / `text` | 把 `ext/web` 能力下沉进 `lib/net` 服务端 |
|
||||
| TOML **只读** | 完整 YAML 1.2、任意对象反序列化 |
|
||||
| HTML **转义** | 模板引擎 / CSS 选择器引擎 |
|
||||
|
||||
---
|
||||
|
||||
## 2. M7 — `datetime` + `url`
|
||||
|
||||
### 2.1 `lib/datetime.mq.md` / `lib/日期时间.mq.md`
|
||||
|
||||
| 函数(英) | 中文建议 | 行为 |
|
||||
|------------|----------|------|
|
||||
| `now` | `现在` | 返回结构化时刻(见下)或 ISO 文本(二选一,实现时锁定) |
|
||||
| `from_unix` / `to_unix` | `自戳` / `成戳` | 秒级;可选 `ms` |
|
||||
| `parse` | `解析` | 支持 RFC3339 / 常见 `YYYY-MM-DD[ HH:MM:SS]` |
|
||||
| `format` | `格式化` | strftime 子集或命名样式 `rfc3339`/`date`/`time` |
|
||||
| `add` | `加` | `days`/`hours`/`minutes`/`seconds` 具名 |
|
||||
| `in_zone` | `时区` | IANA 名或 `+08:00`;失败 → 诊断 |
|
||||
|
||||
**结构化时刻(建议 map)**:`{unix, zone, iso}` 或宿主不透明柄 + `_type=datetime`。优先 **map + 稳定字段**,便于 GFM/table 协作。
|
||||
|
||||
**刻意不做**:农历、营业日、完整 tzdb 热更新 UI、闰秒政治。
|
||||
|
||||
### 2.2 `lib/url.mq.md` / `lib/地址.mq.md`(或并入 `net`)
|
||||
|
||||
| 函数 | 行为 |
|
||||
|------|------|
|
||||
| `parse` | → `{scheme, userinfo, host, port, path, query, fragment}` |
|
||||
| `query_parse` | `a=1&b=2` → map(多值用列表) |
|
||||
| `query_stringify` | map → query |
|
||||
| `join` | base + relative(可选,可二期) |
|
||||
|
||||
既有 `net.url_encode` **保留**;文档写清:编码单段用 `net`/`encoding`,解析整 URL 用 `url`。
|
||||
|
||||
**验收**:金样解析带 query 的 HTTPS URL;往返 query。
|
||||
|
||||
---
|
||||
|
||||
## 3. M8 — `toml` + `html` + `encoding` 加厚
|
||||
|
||||
### 3.1 `lib/toml.mq.md` / `lib/Toml.mq.md`(或 `配置表`)
|
||||
|
||||
| 函数 | 行为 |
|
||||
|------|------|
|
||||
| `parse` | TOML 文本 → Marqdo map/list(只读) |
|
||||
|
||||
**不做** `stringify`(首版);需要写出时继续用 JSON。动机对齐 PEP 680:配置引导,而非通用文档格式战争。
|
||||
|
||||
### 3.2 HTML 转义
|
||||
|
||||
二选一(实现时定一):
|
||||
|
||||
- A:`lib/html.mq.md` · `escape` / `unescape`
|
||||
- B:`text.html_escape` / `text.html_unescape`
|
||||
|
||||
推荐 **A**(安全语义独立可见)。
|
||||
|
||||
### 3.3 `encoding` 加厚
|
||||
|
||||
| 函数 | 行为 |
|
||||
|------|------|
|
||||
| `base32_encode` / `base32_decode` | RFC 4648 |
|
||||
| (可选)`percent_decode` | 与 `url` 协作 |
|
||||
|
||||
---
|
||||
|
||||
## 4. M9 — `fs` 加厚
|
||||
|
||||
| 函数 | 行为 |
|
||||
|------|------|
|
||||
| `make_dirs` | 递归创建 |
|
||||
| `remove_tree` | 递归删除(目录) |
|
||||
| `stat` | `{size, mtime_unix, is_file, is_dir}` |
|
||||
| `walk` | 返回路径列表(深度优先或广度;文档锁定) |
|
||||
|
||||
**不做**:权限 ACL、watch/inotify、硬链接全家桶。
|
||||
|
||||
---
|
||||
|
||||
## 5. M10 — 收口糖(可选)
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| `lib/stats` 或 `math.mean`/`median`/`stdev` | 极薄;非 pandas |
|
||||
| `log` 结构化字段 | 可选 `fields=` map;非完整 slog 生态 |
|
||||
| `zip` 读写 | **默认跳过**;有明确 Release 需求再开 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 宿主与 WASM
|
||||
|
||||
| Host | WASM |
|
||||
|------|------|
|
||||
| `datetime` / `url` / `toml` / `html` / `fs.stat` | 尽量可进;IANA tz 数据体积需评估(可 host-only + 文档标注) |
|
||||
| `fs.walk` / `remove_tree` | host-only 可接受 |
|
||||
|
||||
新 crate 写进 [dependencies.md](dependencies.md);禁止顺手拉大型框架。
|
||||
|
||||
---
|
||||
|
||||
## 7. 作者面风格
|
||||
|
||||
- 中英分文件;形参表声明全部可选并转发 `host_*`。
|
||||
- 数据优先 GFM / `table`;`json` 仍只 parse/stringify/quote。
|
||||
- 每波:设计短文 → host → lib → `tests/lib/*` → `public/features` 短页。
|
||||
|
||||
---
|
||||
|
||||
## 8. 完成定义(Mid2 整包)
|
||||
|
||||
1. 作者可用 `datetime` + `url` + `toml.parse` + `html.escape` 写配置驱动脚本,无需 foreign。
|
||||
2. `fs.stat` / `make_dirs` 金样绿。
|
||||
3. 研究文高优先级缺口标 closed;YAML/模板/sqlite 仍标明 won't。
|
||||
4. [stdlib-modules.md](stdlib-modules.md) 总表更新;`stdlib.md` 状态改为 Mid2 进行中/完成。
|
||||
@@ -2,10 +2,10 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin**/browser |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
|
||||
| 状态 | **核心已落地**;**Mid M1–M6 已落地**;**Mid2 规划中** · [stdlib-mid2.md](stdlib-mid2.md) / [roadmap/stdlib-mid2.md](../roadmap/stdlib-mid2.md) |
|
||||
| 日期 | 2026-09-08 |
|
||||
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精;**通用能力优先 Mid,插件留给领域核** |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-mid.md](stdlib-mid.md) · [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
|
||||
|
||||
---
|
||||
|
||||
@@ -15,10 +15,24 @@
|
||||
|
||||
| 模块族 | 英文库 | 中文库 | 状态 |
|
||||
|--------|--------|--------|------|
|
||||
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
|
||||
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有(`put`/`改` + list/map;见 [stdlib-table.md](stdlib-table.md)) |
|
||||
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 + **Mid M4** 加厚 |
|
||||
| **正则** | `lib/re.mq.md` | `lib/正则.mq.md` | **Mid M1** |
|
||||
| **编解码** | `lib/encoding.mq.md` | `lib/编码.mq.md` | **Mid M1** + Mid2 M8 base32 |
|
||||
| **路径** | `lib/path.mq.md` | `lib/路径.mq.md` | **Mid M2** |
|
||||
| **哈希** | `lib/hash.mq.md` | `lib/哈希.mq.md` | **Mid M3** |
|
||||
| **机密** | `lib/secrets.mq.md` | `lib/机密.mq.md` | **Mid M3** |
|
||||
| **逗号表** | `lib/csv.mq.md` | `lib/逗号表.mq.md` | **Mid M4** |
|
||||
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有 + Mid M4/M5:`sort`/`unique`/`zip`/… |
|
||||
| **命令行** | `lib/cli.mq.md` | `lib/命令行.mq.md` | **Mid M5** |
|
||||
| **日志** | `lib/log.mq.md` | `lib/日志.mq.md` | **Mid M6** + Mid2 M10 `fields=` |
|
||||
| **标识** | `lib/uuid.mq.md` | `lib/标识.mq.md` | **Mid M6** |
|
||||
| **日期时间** | `lib/datetime.mq.md` | `lib/日期时间.mq.md` | **Mid2 M7** |
|
||||
| **地址** | `lib/url.mq.md` | `lib/地址.mq.md` | **Mid2 M7** |
|
||||
| **配置表** | `lib/toml.mq.md` | `lib/配置表.mq.md` | **Mid2 M8** |
|
||||
| **超文本** | `lib/html.mq.md` | `lib/超文本.mq.md` | **Mid2 M8** |
|
||||
| **统计** | `lib/stats.mq.md` | `lib/统计.mq.md` | **Mid2 M10** |
|
||||
| 浏览器效应 | `lib/browser.mq.md` | `lib/浏览器.mq.md` | WASM 客户端效应助手(GFM + helpers;勿用 `json.set` 链) |
|
||||
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 |
|
||||
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 + Mid M2 + **Mid2 M9**:`make_dirs` / `remove_tree` / `stat` / `walk` |
|
||||
| 系统 | `lib/sys.mq.md` | `lib/系统.mq.md` | 已有(含 `load_dotenv`) |
|
||||
| 时间 | `lib/time.mq.md` | `lib/时间.mq.md` | 已有 |
|
||||
| JSON | `lib/json.mq.md` | **同文件** | **仅** parse / stringify / quote;集合请用 table / GFM |
|
||||
@@ -29,7 +43,11 @@
|
||||
| **自写回** | `lib/writeback.mq.md` | `lib/自写回.mq.md` | **已有**(Jupyter 式输出写回) |
|
||||
| **子任务** | `lib/subtask.mq.md` | `lib/子任务.mq.md` | **已有**(OS 子进程 + KillOnDrop) |
|
||||
|
||||
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` — 见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` · `ext/web` · `ext/quantum` · `ext/linalg` — 见各 `ext-*.md`。
|
||||
|
||||
**中层已落地:** M1–M6(含 log / uuid)— 见 [stdlib-mid.md](stdlib-mid.md) · [stdlib-log-uuid.md](stdlib-log-uuid.md)。
|
||||
|
||||
**Mid2:** **M7–M10 done**(datetime / url / toml / html / base32 / fs++ / stats / log.fields;zip 跳过)— [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-stats-log.md](stdlib-stats-log.md)。
|
||||
|
||||
设计细节:[stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md)。
|
||||
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
# `lib/path` — 路径代数(Mid M2)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M2)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 导入 | `lib/path.mq.md` · `lib/路径.mq.md` |
|
||||
| Host | `host_path_*`(`std::path`;无 I/O、不经 `fs_root`) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `join` | `拼接` | `a`, `b` | 文本路径 |
|
||||
| `split` | `拆分` | `path` | 组件文本列表(去空段) |
|
||||
| `file_name` | `文件名` | `path` | 最后一段;根路径可为空文本 |
|
||||
| `parent` | `父目录` | `path` | 父路径文本;无父则 `"."` |
|
||||
| `extension` | `扩展名` | `path` | 不含点;无扩展名为 `""` |
|
||||
| `normalize` | `规范化` | `path` | 清理 `.` / `..`(纯字符串,不访问磁盘) |
|
||||
| `is_absolute` | `是绝对` | `path` | 布尔 |
|
||||
|
||||
## 2. 语义
|
||||
|
||||
- 分隔符与绝对路径判定跟随 **宿主 OS**(Linux CI 为 `/`)。
|
||||
- **不做** I/O;逃逸检查仍由 `lib/fs` 在读写时执行。
|
||||
- `join`:若 `b` 为绝对路径,结果为 `b`(同 `Path::join`)。
|
||||
|
||||
## 3. 刻意不做(v1)
|
||||
|
||||
`glob`、符号链接解析、`relative_to`、Windows UNC 专项文档。
|
||||
@@ -0,0 +1,33 @@
|
||||
# `lib/re` — 正则(Mid M1)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M1)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 导入 | `lib/re.mq.md` · `lib/正则.mq.md` |
|
||||
| Host | `host_re_*`(`regex` crate,默认 Unicode) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `is_match` | `匹配` | `text`, `pattern` | 布尔 |
|
||||
| `find` | `查找` | `text`, `pattern` | 首个匹配文本,或 `None` |
|
||||
| `find_all` | `查找全部` | `text`, `pattern` | 文本列表 |
|
||||
| `replace` | `替换` | `text`, `pattern`, `with`, 可选 `count` | 文本(`count` 缺省 = 全部) |
|
||||
| `split` | `拆分` | `text`, `pattern` | 文本列表 |
|
||||
|
||||
非法 pattern → 诊断失败(含 crate 错误信息)。
|
||||
|
||||
## 2. 语义
|
||||
|
||||
- 引擎:Rust [`regex`](https://docs.rs/regex)(无回溯引用;与 RE2 同族限制)。
|
||||
- 按 **UTF-8 文本**匹配,不做字节模式。
|
||||
- `find` / `find_all` 返回整段匹配(不含捕获组拆分;捕获组 v1 不做)。
|
||||
|
||||
## 3. 刻意不做(v1)
|
||||
|
||||
命名捕获、替换回调、`Regex` 对象缓存 API、字节模式。
|
||||
@@ -0,0 +1,24 @@
|
||||
# `lib/secrets` — 安全随机令牌(Mid M3)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M3)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-hash.md](stdlib-hash.md) · [stdlib-mid.md](stdlib-mid.md) |
|
||||
| 导入 | `lib/secrets.mq.md` · `lib/机密.mq.md` |
|
||||
| Host | `host_secrets_*`(`getrandom`) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `token_hex` | `十六进制令牌` | 可选 `n`(字节数,默认 16) | 小写 hex,长度 `2*n` |
|
||||
| `token_urlsafe` | `网址安全令牌` | 可选 `n`(字节数,默认 16) | URL-safe Base64(无填充) |
|
||||
|
||||
**不要**用 `math.random` / `math.seed` 生成令牌。
|
||||
|
||||
## 2. 刻意不做
|
||||
|
||||
密钥派生、加密/解密、密码哈希。
|
||||
@@ -0,0 +1,30 @@
|
||||
# 设计:`lib/stats` / `lib/统计` 与 `log.fields`(Mid2 M10)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地** |
|
||||
| 日期 | 2026-09-09 |
|
||||
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §5 |
|
||||
| 宿主 | `src/host/stats.rs` · `host_stats_*`;`log::line` 可选 `fields` |
|
||||
|
||||
---
|
||||
|
||||
## 1. `lib/stats`
|
||||
|
||||
| EN | ZH | 行为 |
|
||||
|----|-----|------|
|
||||
| `mean` | `均值` | 算术平均 → Num |
|
||||
| `median` | `中位数` | 排序后中位;偶数取两中点平均 |
|
||||
| `stdev` | `标准差` | **样本**标准差(n≥2) |
|
||||
|
||||
**不做** dataframe、分位数全家桶、加权统计。
|
||||
|
||||
## 2. `log` `fields=`
|
||||
|
||||
各级别函数可选 `fields`(map)。宿主拼到行尾:`INFO msg key=val …`(map 插入序)。
|
||||
|
||||
**不做** 远程 sink、结构化 JSON 日志协议。
|
||||
|
||||
## 3. zip
|
||||
|
||||
按路线图 **默认跳过**。
|
||||
@@ -11,9 +11,9 @@
|
||||
|
||||
| 读 | 写 |
|
||||
|----|----|
|
||||
| 脚注 `` `xs`[^1] `` / `` `m`[^key] `` / 嵌套 `` `m`[^a][^1] `` | **`table.put` / `表.改`** |
|
||||
| 链接取元 `[key](xs)` / `[key](m)` / 嵌套 `[1]([a](m))`(脚注 `` `m`[^k] `` 仍兼容) | **`table.put` / `表.改`** |
|
||||
|
||||
`put` / `改` 的 `at=`(`于=`)与脚注同构:文本键、**1-based** 整数下标,或键/下标组成的路径列表。
|
||||
`put` / `改` 的 `at=`(`于=`)与取元同构:文本键、**1-based** 整数下标,或键/下标组成的路径列表。
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -22,7 +22,7 @@ import table:lib/table.mq.md
|
||||
|
||||
# main
|
||||
|
||||
*`h` = > table.put in=None at=Authorization value=Bearer-x*
|
||||
**`h` = [table.put] in=None at="Authorization" value="Bearer-x"**
|
||||
|
||||
`xs` =
|
||||
|
||||
@@ -31,7 +31,8 @@ import table:lib/table.mq.md
|
||||
| a |
|
||||
| b |
|
||||
|
||||
*`xs` = > table.put in=`xs` at=1 value=A*
|
||||
**`xs` = [table.put] in=`xs` at=1 value="A"**
|
||||
**打印 内容=[Authorization](h)**
|
||||
```
|
||||
|
||||
`in=None` 且 `at=` 为单个文本键 → 新建单键字典。值一律不可变更新(返回新集合)。
|
||||
|
||||
@@ -0,0 +1,30 @@
|
||||
# `lib/text` 加厚(Mid M4)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M4)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-csv.md](stdlib-csv.md) · [stdlib-mid.md](stdlib-mid.md) |
|
||||
| 导入 | `lib/text.mq.md` · `lib/文本.mq.md` |
|
||||
| Host | `host_text_*`(Unicode 大小写 / 子串;非正则替换) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 新增 API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `contains` | `包含` | `text`, `sub` | 布尔 |
|
||||
| `starts_with` | `开头是` | `text`, `prefix` | 布尔 |
|
||||
| `ends_with` | `结尾是` | `text`, `suffix` | 布尔 |
|
||||
| `replace` | `替换` | `text`, `old`, `new`, 可选 `count` | 文本(字面替换,非正则) |
|
||||
| `to_upper` | `大写` | `text` | 文本(Unicode) |
|
||||
| `to_lower` | `小写` | `text` | 文本 |
|
||||
| `repeat` | `重复` | `text`, `n` | 文本 |
|
||||
| `pad` | `填充` | `text`, `width`, 可选 `fill`=`" "`,可选 `align`=`left`/`right`/`center` | 文本 |
|
||||
|
||||
保留原有 `str_trim` / `str_split` / `str_join`(及中文去空白/拆分/拼接)。
|
||||
|
||||
## 2. 刻意不做
|
||||
|
||||
正则替换(用 `lib/re`)、完整 `format` 模板引擎。
|
||||
@@ -0,0 +1,24 @@
|
||||
# 设计:`lib/toml` / `lib/配置表`(Mid2 M8)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地** |
|
||||
| 日期 | 2026-09-09 |
|
||||
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §3.1 |
|
||||
| 宿主 | `src/host/toml_ops.rs` · `host_toml_parse`(手写子集,无 `toml` crate) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| EN | ZH | 行为 |
|
||||
|----|-----|------|
|
||||
| `parse` | `解析` | TOML 文本 → map/list |
|
||||
|
||||
**不做** `stringify`;写出继续用 JSON。
|
||||
|
||||
## 2. 子集
|
||||
|
||||
支持:`#` 注释、基本/字面字符串、int/float/bool、标量数组、`[table]` 与 dotted key。
|
||||
|
||||
**不支持:** `[[array of tables]]`、内联表、TOML datetime、多行字符串。
|
||||
@@ -0,0 +1,24 @@
|
||||
# 设计:`lib/url` / `lib/地址`(Mid2 M7)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地** |
|
||||
| 日期 | 2026-09-09 |
|
||||
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §2.2 |
|
||||
| 宿主 | `src/host/url_ops.rs` · `host_url_*`(手写子集,无 `url` crate) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 与 `net.url_encode`
|
||||
|
||||
| API | 用途 |
|
||||
|-----|------|
|
||||
| `net.url_encode` | **单段** form 编码(空格→`+`) |
|
||||
| `url.parse` | 整 URL → `{scheme,userinfo,host,port,path,query,fragment}` |
|
||||
| `url.query_parse` / `query_stringify` | 查询串 ↔ map(重复键→列表;空格→`%20`) |
|
||||
|
||||
## 2. 解析子集
|
||||
|
||||
`scheme://[userinfo@]host[:port]/path[?query][#fragment]`,含 IPv6 `[addr]`。缺 path 时规范为 `/`。
|
||||
|
||||
**不做**:相对 URL join、完整 WHATWG 边角、IDNA 规范化(host 原样保留)。
|
||||
+11
-6
@@ -2,12 +2,15 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **S0–S3 + L1 全模块落地** |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) |
|
||||
| 状态 | **S0–S3 + 核心 L1 + Mid M1–M6 + Mid2 M7–M10 已落地** |
|
||||
| 日期 | 2026-09-09 |
|
||||
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [lib-code-as-docs.md](lib-code-as-docs.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [**stdlib-mid.md**](stdlib-mid.md) · [**stdlib-mid2.md**](stdlib-mid2.md) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) |
|
||||
|
||||
> **库写法(代码即文档)**:[lib-code-as-docs.md](lib-code-as-docs.md) · [roadmap/lib-ext-code-as-docs.md](../roadmap/lib-ext-code-as-docs.md)。
|
||||
> **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。
|
||||
> **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
> **中层标准库 Mid(M1–M6)**:已落地——[stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md)。
|
||||
> **中层第二波 Mid2(M7–M10)**:已落地——[stdlib-mid2.md](stdlib-mid2.md) · [roadmap/stdlib-mid2.md](../roadmap/stdlib-mid2.md) · 缺口 [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md)。
|
||||
> **`ext/` 不是 stdlib**:官方可选扩展见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
---
|
||||
@@ -17,9 +20,11 @@
|
||||
| 层 | 内容 |
|
||||
|----|------|
|
||||
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at`(`type` 可含 `map`) |
|
||||
| **L1 官方库** | 仓库根目录 [`lib/`](../../lib/)(`.mq.md`);可用 `lib/…` 或别名 `std/…` 导入 |
|
||||
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1 |
|
||||
| **L2** | catalog / 用户站收录(随发版) |
|
||||
| **L1 核心** | 已有 [`lib/`](../../lib/):fs/sys/time/json/net/math/foreign/plugin/table/text/… |
|
||||
| **L1 中层(Mid)** | **已落地** re / encoding / path / hash / secrets / csv / text++ / table++ / cli / log / uuid — [stdlib-mid.md](stdlib-mid.md) |
|
||||
| **L1 Mid2** | **已落地** datetime / url / toml / html / fs++ / stats / log.fields — [stdlib-mid2.md](stdlib-mid2.md) |
|
||||
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1;插件仅领域热路径 |
|
||||
| **L2** | catalog / 用户站收录(随发版);应主要靠核心+中层、默认无插件 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,35 @@
|
||||
# View:Markup 表面保真
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-09-14 |
|
||||
| 相关 | [view.md](view.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md) · [collection-access-link.md](collection-access-link.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
`marqdo view` 的 Structure / 表达式展示应**贴近作者写出的 Markup**,而不是内部 AST 的旧拼法。读者从 view 抄回源文件时,应仍是合法、推荐的表面。
|
||||
|
||||
## 2. 表面对照
|
||||
|
||||
| AST / 概念 | View 优先显示 | 备注 |
|
||||
|------------|---------------|------|
|
||||
| `Expr::Index` | `[键](基)` | 嵌套 `[k2]([k1](base))` |
|
||||
| `InterpPart::Index` | 同上嵌套链接形 | 不再默认 `` `base`[^k] `` |
|
||||
| `CallExpr` + `bracket_marked` / `pre_modifiers` | `修饰 [callee] 实参…` 或 `[callee] 实参…` | 仅经典 `>` 解析时仍显示 `> callee …` |
|
||||
| 赋值 / 返回 | 粗体 / 斜体语义即可 | 不强制还原整句叙述 |
|
||||
| foreach | `- [项](集合)` | 不变 |
|
||||
|
||||
## 3. 非目标
|
||||
|
||||
- 不把 view 做成第二语法;解析真相仍在 mapping / call-arguments。
|
||||
- 不删除对脚注取元、旧 `>` 调用的兼容显示需求时,可用次要提示,但默认推荐面优先。
|
||||
|
||||
## 4. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-09-14 | 初稿;Index 链接形 + 括号调用修饰表面 |
|
||||
| 2026-09-14 | `bracket_marked`:无修饰的 `[callee]` 也保真显示 |
|
||||
+1
-1
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| 状态 | 已定(v0.0.2 方向) |
|
||||
| 日期 | 2026-08-04 |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
|
||||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [view-markup-surface.md](view-markup-surface.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -121,13 +121,16 @@ url = /favicon.ico
|
||||
| `媒体` | `media` | CSS media |
|
||||
| `作为` | `as` | preload `as` |
|
||||
| `跨域` | `crossorigin` | 空 / `anonymous` / `use-credentials` |
|
||||
| `推迟` | `defer` | 经典 `script` 为真时输出 `defer`(缺省同步,兼容旧站) |
|
||||
| `异步` | `async` | 为真时输出 `async` |
|
||||
| `版本` | `version` / `v` | 非空则自动追加 `?v=`;否则用页面/应用 `asset_version` |
|
||||
|
||||
**渲染规则**
|
||||
|
||||
| `rel` | 输出 |
|
||||
|-------|------|
|
||||
| `script` | `<script src="…"></script>`(`type` 非空则写出) |
|
||||
| `module` | `<script type="module" src="…"></script>` |
|
||||
| `script` | `<script … src="…"></script>`(可选 `defer`/`async`;`type` 非空则写出) |
|
||||
| `module` | `<script type="module" src="…"></script>`(浏览器默认 defer 语义) |
|
||||
| 其他 | `<link rel="…" href="…" …>`(按列附加 `type`/`sizes`/`media`/`as`/`crossorigin`) |
|
||||
|
||||
空 `地址` 的行跳过。
|
||||
|
||||
@@ -13,6 +13,8 @@
|
||||
|
||||
**`ext/web` + `plugins/web` 已完成 W0–W7 + P3 路线图**:中间件/JSON API、数据层(连接池/事务/分页/FTS/迁移/外键/审计时间戳)、安全硬化(argon2/CSRF/会话持久化/限速/RBAC)、内容站点标配(SEO/RSS/Markdown/分页 UI)、上传下载/相册/ETag、sitemap/robots/错误页/重定向、WebSocket 广播与访问日志。足以在 Marqdo 上实现博客/CMS/中小型 API 站点;**未内置**的仅剩标签页模板(D6,可用路由+`db.count` 自建)与应用层反垃圾。边界不变:**纯解析进 `lib/net`,HTTP 服务器与领域能力进 `plugins/web` + `ext/web` 作者面**。
|
||||
|
||||
**宿主集成下一刀**(同域 LLM SSE 中继、HTTP→用户 `##`、与 MCP Server 协作)不在本 W 表内,见 [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) · [ext-hosting-fill.md](ext-hosting-fill.md) · [ext-hosting.md](../roadmap/ext-hosting.md)。
|
||||
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,54 @@
|
||||
# 调研刷新:2026-09 智能体框架与 Marqdo「代码即文档」
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Wave B1 Active**(B0/B0.5 已完成;宪法优先) |
|
||||
| 日期 | 2026-09-04 |
|
||||
| 前置 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) |
|
||||
| 路线 | [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) |
|
||||
|
||||
## 0. 结论
|
||||
|
||||
业界框架(LangGraph / Microsoft Agent Framework / CrewAI / OpenAI Agents SDK)在编排、工具、检查点、MCP、评测上继续收敛;**权威真相仍默认在对象图 + transcript + 外置 Store**。
|
||||
|
||||
Marqdo 的差异化不是「再做一个 loop」,而是:
|
||||
|
||||
1. **代码即文档** — 编排 `.mq.md` = 提示词工作面
|
||||
2. **调用位置可见** — `agent_call_site`(路径 / 函数 / 行)是一等上下文
|
||||
3. **文档即知识库(OKF)** — 写回 → promote / solidify → 二次命中 / `llm_free`
|
||||
|
||||
Wave B 的目标函数:**证明并硬化上述三点**;产品化示例与评测必须服务差异化,禁止做成无源码上下文的 chatbot demo。
|
||||
|
||||
## 1. 业界快照(2026)
|
||||
|
||||
| 模式 | 代表 | 状态记忆 | 对 Marqdo |
|
||||
|------|------|----------|-----------|
|
||||
| 图 + checkpointer | LangGraph | typed state 持久化 | 续跑应对齐**文件化工作簿**,不造 Python 图 DSL |
|
||||
| Agent vs Workflow | Microsoft AF | 自主 + 确定性流 | 已有 step / plan,强化即可 |
|
||||
| 角色班组 | CrewAI | Task 管道 | 多 Agent 低优先;父 CALL + 多工作簿 |
|
||||
| Handoff + Guardrails | OpenAI Agents SDK | 显式交接 | 可借鉴语义;权威仍在 `.mq.md` |
|
||||
|
||||
## 2. 深远影响(开发硬约束)
|
||||
|
||||
| 约束 | 含义 |
|
||||
|------|------|
|
||||
| 提示不黑盒 | standing / 工具 / 任务写在文件;拼装可审查 |
|
||||
| 位置感知 | 每次推理注入 call_site;示例与评测可断言 |
|
||||
| 源码工作面 | `source_brief` + `READ:source\|skill`;禁止藏整份 Skill 进不可见提示 |
|
||||
| 写回即记忆 | ok/error 槽 + view;非默认向量库 |
|
||||
| OKF 飞轮 | promote / solidify / hit / llm_free |
|
||||
| 外置工具 | corpus / MCP 仅证据,`authority=workbook` |
|
||||
|
||||
## 3. Wave B 范围
|
||||
|
||||
| 波次 | 主题 |
|
||||
|------|------|
|
||||
| **B0** | 宪法可见示例 + 上下文管道可读性 + Skill/文档 |
|
||||
| **B0.5** | 本机 live(`.env` → cflmy)验证「模型用上了文档」 |
|
||||
| **B1** | 评测锁住 call_site / OKF / 写回 / 预算 |
|
||||
|
||||
暂缓:真 MCP、resume/HITL view、kb stats、并行、A2A。
|
||||
|
||||
## 4. 开发期 LLM
|
||||
|
||||
仓库根目录 `.env`(gitignore):`OPENAI_*` 或 `MARQDO_LLM_*`。模板见 `.env.example`。
|
||||
@@ -70,6 +70,7 @@
|
||||
| **高** | 官方端到端示例 + 文档新鲜度 | 无独立 `examples/agent-*`;Skill/参考里仍有「layout / roadmap」陈旧表述;外人难「照抄即跑通 plan→固化→二次命中」 | `examples/agent-pong`(或同类)+ README;Skill 专节与 A0–A4 对齐 |
|
||||
| **高** | Agent 评测 / 回归 harness | 有离线金样,缺成本·恢复·命中率·补丁质量的系统评测;业界强调 evaluation 先于上线 | `tests/` 或脚本:命中率、llm_free 占比、失败恢复、可选 live 预算 |
|
||||
| **高** | 真 MCP(HTTP/SSE)与凭证 | A4 仅 JSON fixture;缺 streamable HTTP、鉴权、resources/prompts | 金样打 mock MCP server;返回仍带 `authority=workbook` |
|
||||
| **高** | **MCP Server 宿主**(stdio / HTTP) | Agent 只能当客户端 fixture;IDE 无法把 `.mq.md` `##` 暴露为 MCP 工具 | 见 [ext-hosting-gaps.md](ext-hosting-gaps.md) GAP-03 · [ext-hosting-fill.md](../design/ext-hosting-fill.md) |
|
||||
| **中** | Plan 断点续跑 | 工作簿在盘上,缺显式 checkpoint / resume(对标 LangGraph checkpointer) | `plan resume=` 从第 N 轮 DECISION 继续;进程崩溃可恢复 |
|
||||
| **中** | 人机协同(HITL)加深 | 仅有 `confirm=True` 建簿即停;缺审批卡、拒绝重开、view 一键继续 | view 审批控件 + 金样 |
|
||||
| **中** | 飞轮可观测指标 | `hits` / `improve_every` / `llm_free` 有字段,缺汇总与 CLI/view 报表 | `agent_kb_stats` 或 view 面板:命中率、探索浪费 |
|
||||
|
||||
@@ -0,0 +1,156 @@
|
||||
# 调研:宿主集成缺口(浏览器中继 · HTTP→`##` · MCP Server · 同寿副端口 · 跨模块 DB/检索)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记 · 缺口盘点(H1–H4 stdio 已落地;H4b HTTP 可选)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 触发 | 下游应用(对话站 / 求道类 Agent)在真实集成中被迫旁路 Python 脚本 |
|
||||
| 基线版本 | **v0.3.6+**(宿主波次 H1–H4 见 [ext-hosting.md](../roadmap/ext-hosting.md)) |
|
||||
| 相关设计 | [ext-web.md](../design/ext-web.md) · [ext-web-net.md](../design/ext-web-net.md) · [web-net-capabilities.md](../design/web-net-capabilities.md) · [ext-agent.md](../design/ext-agent.md) · [ext-abi.md](../design/ext-abi.md) |
|
||||
| 邻近缺口 | [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md)(真 MCP **客户端**) |
|
||||
| 补齐设计 | [ext-hosting-fill.md](../design/ext-hosting-fill.md) |
|
||||
| 实现路线 | [ext-hosting.md](../roadmap/ext-hosting.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
`ext/web` 已能做**内容站 / CRUD / JSON-DB API / WS**;`ext/ai` 已能做**工作簿 Agent + 客户端 SSE 消费**。下游要把「浏览器同域流式 LLM」「请求触发任意 `##`」「MCP Server 被 IDE 拉起」合进**单一 Marqdo 进程**时,现有扩展**没有一等装配**——只能外挂缓冲代理 / CLI 子进程。缺口集中在 **扩展库作者面 + `plugins/web|agent` ABI**,不是语法层,也不是再开一套标准库。
|
||||
|
||||
**原则:** 旁路脚本只证明需求;关闭缺口必须把能力沉进 `ext/*` + `plugins/*`(可选极薄 `lib/` 编排),禁止把领域逻辑塞进 `src/host/`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 已有基线(不是缺口)
|
||||
|
||||
| 能力 | 现状 | 文档 / 金样 |
|
||||
|------|------|-------------|
|
||||
| CORS / 安全头 / gzip / body limit | `app.configure` | `tests/ext/web-middleware-smoke.mq.md` |
|
||||
| JSON **DB select** 路由 | `configure json=` | `plugins/web/src/middleware.rs` |
|
||||
| `/_form/*` SQL CRUD | `mount_form` | `plugins/web/src/form.rs` |
|
||||
| 客户端缓冲 SSE | `lib/net.http_post_sse` → `ext/llm.complete stream=` | `tests/lib/net-openai-sse.mq.md` |
|
||||
| 执行过程 SSE(非 LLM 中继) | `marqdo view` `/api/run` | [view.md](../design/view.md) §5 |
|
||||
| Agent 证据工具(fixture MCP) | `corpus_search` / `mcp_list_tools` / `mcp_call` | A4;[agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) |
|
||||
| 同模块 `# db` CRUD | `ext/web` `# db` | `examples/web-site/db/` |
|
||||
|
||||
---
|
||||
|
||||
## 2. 缺口总表
|
||||
|
||||
| ID | 缺口 | 需要 | Marqdo 现状 | 典型旁路 | 解除条件 |
|
||||
|----|------|------|-------------|----------|----------|
|
||||
| **GAP-01** | 浏览器 → 上游 LLM **同域流式中继** | 绕过对方 CORS;**SSE 原样转发** | **`app.proxy` / `configure proxy=`**(H1) | ~~`llm_proxy.py`~~ | ✅ 已关闭 |
|
||||
| **GAP-02** | HTTP 处理函数可调用用户 `##` | 请求内执行用户 `##`,返回 JSON | **`app.invoke` / `configure invoke=`**(H2) | ~~外挂 `marqdo run`~~ | ✅ 已关闭 |
|
||||
| **GAP-03** | **MCP Server** 宿主 | IDE 拉起暴露工具 | **`agent.mcp_server` + `serve` stdio**(H4);HTTP=H4b | ~~`qdagent_mcp.py`~~ | ✅ stdio;HTTP 可选 |
|
||||
| **GAP-04** | 同寿「第二监听端口」 | 与 `listen` 同寿中继 | 并入主端口(H1+H2) | ~~`mq.sh` 双进程~~ | ✅ won't |
|
||||
| **GAP-05** | 跨模块 `db`;纯 run 用 corpus | 跨文件 `select`;CLI 检索 | 传递归查找 + `corpus_search` ensure_plugin(H3) | ~~db/index 导出~~ | ✅ 已关闭 |
|
||||
|
||||
旁路脚本名来自下游集成仓库;**本仓库 `scripts/` 不含这些文件**——它们是需求证据,不是上游实现。
|
||||
|
||||
---
|
||||
|
||||
## 3. 分项说明
|
||||
|
||||
### 3.1 GAP-01 · 同域 SSE 中继
|
||||
|
||||
**问题**
|
||||
浏览器页面跑在 `ext/web` 源上时,直连 OpenAI 兼容上游会撞 CORS;`lib/net.http_post_sse` 只在 **CLI/宿主侧缓冲整段流**,不能把字节边收边推回浏览器。
|
||||
|
||||
**现状边界**
|
||||
|
||||
| 已有 | 缺什么 |
|
||||
|------|--------|
|
||||
| `app.configure cors=` | 解决的是**本站对外** CORS,不是替上游开 CORS |
|
||||
| `http_post_sse` → `{status, events}` | **客户端消费**,非服务器中继 |
|
||||
| `app.download` 对象流 | 存储下载,非上游 SSE |
|
||||
| view `/api/run` SSE | Marqdo **执行事件**,非 LLM token 流 |
|
||||
|
||||
**解除形态(产品)**
|
||||
作者声明:`path` + `upstream`(或 env)+ 可选 header 白名单;监听端对浏览器返回 `Content-Type: text/event-stream`,chunk 原样或按 OpenAI SSE 帧转发。
|
||||
|
||||
### 3.2 GAP-02 · 路由 → `##`
|
||||
|
||||
**问题**
|
||||
对话沉淀、表单后写 `data/runs/*.mq.md`、触发 `lib/run.沉淀` 等,需要**同进程**执行用户函数。今天只有:
|
||||
|
||||
1. 页面装配期 `call_lib_path`(compose,非每请求);
|
||||
2. `/_form` / `json=` 的 **DB 专用** handler。
|
||||
|
||||
**解除形态(产品)**
|
||||
声明式:`path` · `method` · `fn=lib.member` 或 `file=… ## name` · body→形参映射 · 返回值序列化为 JSON(错误码约定)。安全默认:仅允许入口模块已导入路径;禁止任意路径注入。
|
||||
|
||||
### 3.3 GAP-03 · MCP Server
|
||||
|
||||
**问题**
|
||||
A4 解决的是 Agent **调用** MCP 工具(且仍是 fixture)。下游要把 Marqdo 工作簿 **暴露为** MCP Server(stdio / Streamable HTTP),IDE 拉起后调 `qd_*`。
|
||||
|
||||
与 [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md)「真 MCP 客户端」正交:本缺口是 **Server 宿主**。
|
||||
|
||||
**解除形态(产品)**
|
||||
`ext/ai`(或 `ext/mcp`)提供:`server tools=` 表(name → `.mq.md`/`##`);`serve stdio=` / `serve http port=`;工具结果仍可带 `authority=workbook`。
|
||||
|
||||
### 3.4 GAP-04 · 同寿副端口
|
||||
|
||||
**问题**
|
||||
在 GAP-01/02 未并入主端口前,下游用第二端口跑代理。`app.listen` 同步阻塞,无「同进程再绑一个 TcpListener」的作者 API;只能 shell 并起另一运行时。
|
||||
|
||||
**解除形态(产品)**
|
||||
优先:GAP-01/02 挂在同一 `listen` → **本缺口关闭**。备选:`app.attach` / `listen also=` 同 tokio 运行时附加服务(仅当必须隔离路径树)。
|
||||
|
||||
### 3.5 GAP-05 · 跨模块 DB 句柄与 corpus 可发现性
|
||||
|
||||
**问题**
|
||||
|
||||
1. **类型分发:** 插件对象依赖 `_type` / 方法表;跨模块传回的 store 若丢类型或未注册方法,报 `unknown object type db`。同文件 `db/index.mq.md` 内 `## recent` 再导出 JSON 是现行绕过。
|
||||
2. **`agent_corpus_search`:** 注册在 `plugins/agent`;普通 `marqdo run` 未 `plugin.load` / 未构造 `# agent` 时不可用。导入 `ext/ai/agent.mq.md` 文本本身不保证原生插件已加载。
|
||||
|
||||
**解除形态(产品)**
|
||||
句柄:跨模块返回值保留 `_type=db` 且方法分发查全局/插件表(修运行时或约定「只返回 url,调用方再 `web.db`」二选一,见补齐设计)。corpus:`plugin.load` 自动路径,或 `ext/ai` 导出独立 `## corpus_search` 并在调用前 `ensure_plugin`。
|
||||
|
||||
---
|
||||
|
||||
## 4. 归属判定(标准库 vs 扩展)
|
||||
|
||||
沿用 [ext-web-net.md](../design/ext-web-net.md) / [web-net-capabilities.md](../design/web-net-capabilities.md) 边界:
|
||||
|
||||
| 能力 | 归属 | 理由 |
|
||||
|------|------|------|
|
||||
| SSE **中继**路由、HTTP→`##`、副端口 | **`plugins/web` + `ext/web`** | 服务器结构 / 网站领域;axum 已在依赖链 |
|
||||
| MCP **Server**、corpus 可发现 | **`plugins/agent` + `ext/ai`** | Agent/工具宿主;禁止塞 `src/host/` |
|
||||
| 缓冲 SSE 客户端、解析 | 已有 **`lib/net`** | 不新增中继到 stdlib |
|
||||
| 任意路径 shell 出去跑 `marqdo` | **刻意不做进核心** | 旁路脚本可留在下游;上游给一等 API 后废弃 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 优先级建议
|
||||
|
||||
| 优先级 | ID | 理由 |
|
||||
|--------|-----|------|
|
||||
| **高** | GAP-01 + GAP-02 | 去掉 Python 中继的主路径;浏览器站 + 沉淀闭环 |
|
||||
| **高** | GAP-03 | IDE 生态入口;与「真 MCP 客户端」可并行设计、分波交付 |
|
||||
| **中** | GAP-05 | 减少 `db/index` 与 bridge 胶水;影响面偏语言/插件加载 |
|
||||
| **低(可随 01/02 关闭)** | GAP-04 | 并入主端口后自然消失 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 明确「不是缺口」
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| 内容站 W0–W7+P3 | 已完结;本清单不重开上传/RSS/RBAC |
|
||||
| Mid M1–M6 | 通用原语已够;本清单不是再开 `lib/re` 一类 |
|
||||
| 隐藏 JSON TOOL 主循环 | 与 Agent 宪法冲突 |
|
||||
| Dense embedding 默认化 | 仍见 [okf-near-match.md](../roadmap/okf-near-match.md) |
|
||||
| 浏览器手写业务 JS 代理 | 与 WASM 路线「作者零 JS」冲突;中继应在服务端 `ext/web` |
|
||||
|
||||
---
|
||||
|
||||
## 7. 与其它文档
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| [ext-hosting-fill.md](../design/ext-hosting-fill.md) | **补齐设计(作者 API + ABI)** |
|
||||
| [ext-hosting.md](../roadmap/ext-hosting.md) | 实现波次 H0–H4 |
|
||||
| [ext-web.md](../roadmap/ext-web.md) | 站点主线完结;本缺口为后续宿主波次 |
|
||||
| [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) | 客户端真 MCP;与 GAP-03 Server 互补 |
|
||||
| [web-asgi-servers-and-marqdo.md](../design/web-asgi-servers-and-marqdo.md) | 反代模型;中继仍在 Marqdo `listen` 内 |
|
||||
@@ -0,0 +1,113 @@
|
||||
# 调研:线性代数 × 公式类 × 展示
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 调研纪要(为 [ext-linalg](../design/ext-linalg.md) 供输入) |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-math.md](../design/stdlib-math.md) · [ext-quantum-q7.md](../design/ext-quantum-q7.md) · SymPy MatrixExpr · Symbolics.jl · LAFigureSpecs |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题陈述
|
||||
|
||||
Marqdo 已有:
|
||||
|
||||
- `Value::Formula` + `` `f` = `` + `$$…$$`(高中标量符号)
|
||||
- `formula::Expr::Matrix`:**数值**稠密矩阵字面量(`[[…]]` / `\begin{pmatrix}`),供量子门核对与 view KaTeX
|
||||
- `ext/quantum` Q7:**量子语境**下的密度矩阵 / Kronecker / 谱 / SVD 风格图(ABI)
|
||||
|
||||
缺口:一门**经典线性代数**扩展——作者用**公式级矩阵表达式**写 \(A^\top A\)、\((X^\top X)^{-1}X^\top y\)、分块、Kronecker,在**不立刻展开成巨大稠密矩阵**的前提下做重写与化简,并在文档 / view 中**好看地呈现**分解与结构。
|
||||
|
||||
---
|
||||
|
||||
## 2. 业界对照
|
||||
|
||||
### 2.1 符号矩阵表达式(大规模优化的关键)
|
||||
|
||||
| 系统 | 模型 | 对 Marqdo 的启示 |
|
||||
|------|------|------------------|
|
||||
| **SymPy `MatrixExpr`** | `MatrixSymbol(name, n, m)` + `MatMul` / `MatAdd` / `Inverse` / `Transpose` / `Trace` / `Determinant` / `BlockMatrix` / `KroneckerProduct`;`as_explicit()` 才展开 | **默认保持抽象**;形状元数据传播;显式求值是可选动作 |
|
||||
| SymPy `block_collapse` | 分块表达式在块级化简,避免整块稠密展开 | 分块是教学与优化的第一公民 |
|
||||
| SymPy Kronecker | `KroneckerProduct` 惰性 + `combine_kronecker` 规则 | Kronecker **绝不能**默认 `expand`(维数爆炸) |
|
||||
| SymPy 矩阵求导 | 经 array expr 再收回 MatrixExpr;闭式导数 | v1 **不做**;记入远期 |
|
||||
| **Symbolics.jl** | 「数组的符号」vs「符号数组」:后者 O(1) 表示整阵,保留 `A*B` 不展开 | 与 MatrixExpr 同构;强调 **shape / eltype 元数据** |
|
||||
| NumPy / Eigen / nalgebra | 数值热路径,无公式树 | 对应 Marqdo **插件数值层**,不是文档作者主路径 |
|
||||
|
||||
**结论:** 「公式类线性代数」= **抽象表达式 DAG + 形状检查 + 重写规则**;稠密数值是 `eval` / `as_explicit` 的终点,不是默认形态。
|
||||
|
||||
### 2.2 教学与展示(效果最好的做法)
|
||||
|
||||
| 做法 | 来源 | 效果 | Marqdo 映射 |
|
||||
|------|------|------|-------------|
|
||||
| KaTeX / MathJax 渲染 `bmatrix` / `pmatrix` | SymPy `latex()` + Jupyter `init_printing` | 公式即排版;多式用 `display` 并列 | 既有 view `formula-card` + KaTeX |
|
||||
| 标签化等式 `A = UΣV^\top` | 教材 / Qiita display+Math | 步骤可读 | `show` / writeback 多卡片 |
|
||||
| **结构图**(SVD / QR / 消元轨) | [LAFigureSpecs](https://github.com/ea42gh/LAFigureSpecs) + matrixlayout;TeX `drawmatrix` | 比数字表更能讲「秩 / 零空间 / 对角结构」 | SVG `kind=svd|qr|ge|eig` |
|
||||
| 热力图 / Hinton | Qiskit / QuTiP / 既有 quantum | 稠密数值矩阵的幅度/符号 | `kind=heatmap|hinton`(经典实/复) |
|
||||
| 分块着色矩形 | CTAN `drawmatrix` | 零块 / 三角 / 带状一目了然 | `kind=structure`(形状示意图,可无元素值) |
|
||||
| 仅打印 ASCII | CLI 默认 | 金样可断言 | `str` / `print` → 规范 ASCII / LaTeX 源 |
|
||||
|
||||
**展示优先级(锁定建议):**
|
||||
|
||||
1. **符号式**:始终可 `latex` → view KaTeX(不依赖数值)
|
||||
2. **结构式 SVG**:分解 / 分块 / 秩示意(教学主图)
|
||||
3. **数值热力图**:仅在 `eval` 后、维数可控时
|
||||
4. CLI:短 ASCII;大矩阵默认摘要 `m×n …` + 可选 `preview=`
|
||||
|
||||
### 2.3 一门「够用」的线性代数库需要什么
|
||||
|
||||
按大学一学期 + 数据科学入门,能力桶:
|
||||
|
||||
| 桶 | 内容 | 符号层 | 数值层 |
|
||||
|----|------|--------|--------|
|
||||
| A 构造 | 符号阵、常数阵、单位/零/对角、从 `$$` / 表 / list | ✅ | ✅ |
|
||||
| B 代数 | 加减乘、转置、逆、伴随、幂、Kronecker、分块 | ✅ 重写 | ✅ |
|
||||
| C 分解 | LU / QR / 特征 / SVD / Cholesky(对称) | 结果对象 + 结构图 | ✅ |
|
||||
| D 系统 | `Ax=b`、最小二乘、伪逆 | 公式写法 + 数值解 | ✅ |
|
||||
| E 度量 | 行列式、迹、秩、范数、条件数 | 部分可符号 | ✅ |
|
||||
| F 展示 | latex / ASCII / SVG 结构 / heatmap | ✅ | ✅ |
|
||||
| G 微积分 | 矩阵导数、Jacobian 积木 | 远期 | — |
|
||||
|
||||
**不做(首版):** 稀疏专用格式、GPU、分布式、完整 CAS 证明、通用张量网络、与 `lib/math` 高中标量混成一个巨模块。
|
||||
|
||||
---
|
||||
|
||||
## 3. 与现有 Marqdo 的衔接点
|
||||
|
||||
| 已有 | 用法 | 扩展时注意 |
|
||||
|------|------|------------|
|
||||
| `$$` + Matrix 数值字面量 | 小门矩阵、手算核对 | 保留;符号阵用 `MatrixSymbol` 或 `matrix.symbol`,勿与数值 Matrix 混为一谈 |
|
||||
| `lib/math` formula | 标量 simplify/diff/plot | **不**把大学线性代数塞进 `lib/math`(与 Q7 结论一致) |
|
||||
| view KaTeX | formula-card | 符号 MatExpr 的 `latex` 字符串直接喂 KaTeX |
|
||||
| `ext/quantum` Q7 linop | 量子密度 / 纠缠 | **经典 API 不复用 quantum 命名空间**;共享算法可在插件内私有复用,作者面分离 |
|
||||
| `plugins/*` ABI | 重数值 / SVG | 稠密分解与大图走 `plugins/linalg` |
|
||||
| GFM 表 | 数据即代码 | 矩阵输入:表或 `$$`;分解步骤:`@` 记录表 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 「大规模优化」具体指什么
|
||||
|
||||
在公式类语境下,优化 ≠ BLAS 微内核,而是:
|
||||
|
||||
1. **惰性**:`A*B*C` 保持乘积树,直到 `eval` / `explicit`
|
||||
2. **形状短路**:不相容维数在符号阶段报错,不跑数值
|
||||
3. **代数恒等**:`(A^{-1})^{-1}→A`,`(AB)^\top→B^\top A^\top`,`I*A→A`,分块 `block_collapse`
|
||||
4. **禁止爆炸展开**:Kronecker / 高维符号积默认不 `expand`
|
||||
5. **数值批处理**:同形状多 RHS、分解一次多用(`factorize` 对象)
|
||||
6. **展示成本**:大矩阵不默认内嵌完整 KaTeX 数字阵;结构图 + 摘要
|
||||
|
||||
---
|
||||
|
||||
## 5. 推荐产品叙事(一句)
|
||||
|
||||
**线性代数文档用公式写变换,用规则做化简,用结构图讲分解,用可控数值做验算——公式是一等公民,稠密矩阵是可选终点。**
|
||||
|
||||
---
|
||||
|
||||
## 6. 参考链接
|
||||
|
||||
- SymPy Matrix Expressions: https://docs.sympy.org/latest/modules/matrices/expressions.html
|
||||
- SymPy Matrix derivatives (远期): https://docs.sympy.org/dev/explanation/modules/matrices/matrixderivatives.html
|
||||
- Symbolics.jl Symbolic Arrays: https://docs.sciml.ai/Symbolics/v6.54/manual/arrays/
|
||||
- LAFigureSpecs(教学结构图): https://github.com/ea42gh/LAFigureSpecs
|
||||
- CTAN drawmatrix: 矩阵形状示意
|
||||
- 既有:`doc/design/stdlib-math.md` · `doc/design/ext-quantum-q7.md`
|
||||
@@ -0,0 +1,154 @@
|
||||
# `ext/web` 定制限制:开发者不易定制的问题盘点
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研锁定(踩坑整理)** |
|
||||
| 日期 | 2026-09-04 |
|
||||
| 相关 | [ext-web.md](../design/ext-web.md) · [ext-web-net.md](../design/ext-web-net.md) · [web-net-capabilities.md](../design/web-net-capabilities.md) |
|
||||
| 解决索引 | [../design/ext-web-customization/](../design/ext-web-customization/) |
|
||||
|
||||
结合自研后台、样式迁移与响应式改造中的实际踩坑,整理当前 `plugins/web` + `ext/web` 对站点作者的**强占与难定制点**。本文只陈述问题与证据;逐项解法见解决索引。
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
内置 `/admin` 壳、固定鉴权路径、注入式 `SHELL_CSS` 与四区栅格,让「只写 `.mq.md`」的产品路径在**自研后台 / 品牌主题 / 移动端**上反复撞墙;作者被迫旁路前缀 + `!important` + 前端 JS 兜底。
|
||||
|
||||
---
|
||||
|
||||
## 1. 路由与路径被框架强占
|
||||
|
||||
**现象**
|
||||
|
||||
- `/admin` 及 `/admin/*` 整段保留,无法 `app.route` 注册自定义页(错误:`route path … is reserved`)。
|
||||
- `app.重定向` / `redirect` 目标若落在 reserved 前缀,同样被校验拒绝。
|
||||
- `后台=False`(`admin=False`)后,访问 `/admin/news` 等仍进内置壳,只显示 *Admin is disabled*,**不能**换成自研页。
|
||||
- 登录/登出硬绑 `/admin/login`、`/admin/logout`;登录成功硬编码 `Redirect::to("/admin")`,无法配置回跳到 `/desk`。
|
||||
|
||||
**代码证据**
|
||||
|
||||
| 位置 | 行为 |
|
||||
|------|------|
|
||||
| `plugins/web/src/lib.rs` → `normalize_route_path` | `/admin`、`/_form`、`/_part`、`/static` 一律 reserved |
|
||||
| `plugins/web/src/http.rs` | 始终挂 `/admin…` 路由;disabled 时仍 `admin_shell` + 文案 |
|
||||
| 同文件 `admin_login_post` | 成功跳转写死 `/admin` |
|
||||
|
||||
**结果**
|
||||
|
||||
自研后台只能用 `/desk` 等旁路前缀;入口与鉴权路径分裂,还要靠前端 JS(`fetch('/admin/login')` 再 `replace('/desk')`)做跳转兜底。
|
||||
|
||||
→ 解决:[01-routes-and-admin-prefix.md](../design/ext-web-customization/01-routes-and-admin-prefix.md)
|
||||
|
||||
---
|
||||
|
||||
## 2. 内置 `SHELL_CSS` 难以彻底覆盖
|
||||
|
||||
**现象**
|
||||
|
||||
- 每个页面都会注入框架壳样式,例如 `body.has-sidebar { grid-template-columns:14rem 1fr; … }`、默认卡片/表单/侧栏色。
|
||||
- 规则**无媒体查询**、选择器优先级不低;站点主题选择器不够强时,小屏双列、侧栏占位等「幽灵布局」反复出现。
|
||||
- 首页有额外 class(如 `has-rail`)时碰巧盖住,其他页没有同类 class 就暴露——表现为「只修了首页」。
|
||||
- 实务上经常要 `!important` + 更高选择器,与「干净主题层」冲突。
|
||||
|
||||
**代码证据**
|
||||
|
||||
| 位置 | 行为 |
|
||||
|------|------|
|
||||
| `plugins/web/src/render.rs` → `SHELL_CSS` | 常量内联进每个 HTML |
|
||||
| 同文件壳渲染 | `<style>{SHELL_CSS}{extra}</style>`,主题只能接在后面 |
|
||||
|
||||
→ 解决:[02-shell-css.md](../design/ext-web-customization/02-shell-css.md)
|
||||
|
||||
---
|
||||
|
||||
## 3. 鉴权 / 门禁模型偏固定
|
||||
|
||||
**现象**
|
||||
|
||||
- 未登录访问受保护路径:对 `/admin*` 会 **303 → 登录页**;对 `/desk` 等自定义路径往往是 **403 HTML**,行为不一致。
|
||||
- 门禁匹配偏宽:`path.starts_with` / `path_matches` 使 `/desk` 匹配 `/desk/login`,公开登录页易被误伤。
|
||||
- 默认鉴权挂上 `/admin*` → `admin`;`/admin-publish` 这类名字也会被当成 admin 域(`starts_with("/admin")`)。
|
||||
- 会话 cookie、CSRF、登录表单字段均固定在框架实现;难换登录 UI 或改成功落地页。
|
||||
|
||||
**代码证据**
|
||||
|
||||
| 位置 | 行为 |
|
||||
|------|------|
|
||||
| `http.rs` → `rbac_middleware` | visitor + `/admin*` → redirect;其它 gate → 403 |
|
||||
| `http.rs` → `path_matches` | 前缀匹配,无「精确路径 + 子路径排除」DSL |
|
||||
| `lib.rs` → `web_app_auth` | 默认塞入 `/admin*` gate |
|
||||
|
||||
→ 解决:[03-auth-gates.md](../design/ext-web-customization/03-auth-gates.md)
|
||||
|
||||
---
|
||||
|
||||
## 4. 样式作者体验受限
|
||||
|
||||
**现象**
|
||||
|
||||
- 样式表是 GFM 表格;含 `/` 的值必须加引号(如 `"1 / 5"`),否则单元格表达式把 `/` 当除法(曾出现 `grid-column` 变成 `0`)。
|
||||
- `@keyframes`、复杂选择器、多层媒体查询(`min-width` and `max-width`)表达能力有限,装配顺序要小心。
|
||||
- 主题 CSS 与 `SHELL_CSS` 同页串联,级联顺序不透明,调试成本高。
|
||||
- 响应式不能指望框架;壳层几乎不提供移动端抽屉/折叠。
|
||||
|
||||
→ 解决:[04-stylesheet-authoring.md](../design/ext-web-customization/04-stylesheet-authoring.md)
|
||||
|
||||
---
|
||||
|
||||
## 5. 页面壳与插槽约定僵硬
|
||||
|
||||
**现象**
|
||||
|
||||
- 壳结构固定为 `topnav` / `side` / `main` / `foot` 栅格命名区。
|
||||
- 侧栏一旦装配,`body` 即 `has-sidebar`,套上框架双列;杂志风单列、抽屉必须自己拆布局。
|
||||
- 组件表驱动导航,难做运行时条件导航(小屏合并顶栏+侧栏),通常再补 `theme.js`。
|
||||
|
||||
→ 解决:[05-page-shell-slots.md](../design/ext-web-customization/05-page-shell-slots.md)
|
||||
|
||||
---
|
||||
|
||||
## 6. 后台 CRUD 与表单能力边界
|
||||
|
||||
**现象**
|
||||
|
||||
- 内置 admin 是通用表管理,不是产品级 CMS;**关了又占着 `/admin` 路径**(与 §1 叠加)。
|
||||
- 表单以声明式字段表为主;Markdown 分栏、专栏元数据联动等只能外挂 JS。
|
||||
- 列表「链接前缀」等约定简单;编辑/新建状态机常靠前端拼(`?id=`、`?new=1`)。
|
||||
|
||||
→ 解决:[06-admin-crud-forms.md](../design/ext-web-customization/06-admin-crud-forms.md)
|
||||
|
||||
---
|
||||
|
||||
## 7. 静态资源与脚本生命周期
|
||||
|
||||
**现象**
|
||||
|
||||
- 头资源脚本常在 `<head>` **同步**加载;若脚本假设 DOM 已就绪会直接失败(登录页曾因此不跳转)。
|
||||
- 缓存靠 `?v=` 手动 bump;无构建管线时易出现「改了 JS 浏览器仍用旧文件」。
|
||||
|
||||
→ 解决:[07-assets-script-lifecycle.md](../design/ext-web-customization/07-assets-script-lifecycle.md)
|
||||
|
||||
---
|
||||
|
||||
## 8. 扩展与部署耦合
|
||||
|
||||
**现象**
|
||||
|
||||
- 能力依赖 web 插件 ABI / Marqdo 版本(如 0.3.2 起的样式引号约定);升级要同步 Docker / 本机二进制。
|
||||
- 定制若依赖改插件源码(放宽 `/admin` reserved、可配置 login redirect),就脱离「只写 `.mq.md`」的产品路径,维护成本陡增。
|
||||
|
||||
→ 解决:[08-ext-deploy-coupling.md](../design/ext-web-customization/08-ext-deploy-coupling.md)
|
||||
|
||||
---
|
||||
|
||||
## 9. 优先级建议(给实现排期)
|
||||
|
||||
| 优先级 | 项 | 理由 |
|
||||
|--------|-----|------|
|
||||
| P0 | §1 路由/前缀 + §3 鉴权一致 | 阻塞自研后台产品路径 |
|
||||
| P1 | §2 SHELL_CSS + §5 壳布局 | 阻塞品牌主题与响应式 |
|
||||
| P2 | §4 样式作者体验 + §7 脚本生命周期 | 降低日常踩坑,不改架构也能缓解 |
|
||||
| P3 | §6 CRUD 边界 + §8 部署耦合 | 文档/约定/可选增强为主 |
|
||||
|
||||
详细验收与实现切片见解决索引 README。
|
||||
@@ -0,0 +1,144 @@
|
||||
# 调研:Mid M1–M6 之后标准库还缺什么
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记 · 缺口盘点(M1–M6 闭环之后)** |
|
||||
| 日期 | 2026-09-08 |
|
||||
| 基线 | **v0.3.7+** · Mid M1–M6 **done** |
|
||||
| 已落地设计 | [stdlib-mid.md](../design/stdlib-mid.md) · [stdlib-modules.md](../design/stdlib-modules.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 补齐设计 | [stdlib-mid2.md](../design/stdlib-mid2.md) |
|
||||
| 实现路线 | [stdlib-mid2.md](../roadmap/stdlib-mid2.md) |
|
||||
| 外部对照 | Python stdlib([use-case 索引](https://www.socratopia.app/library/python-programming-ai-era-en/chapter-15) · [PEP 680 tomllib](https://peps.python.org/pep-0680/))· Go `strings`/`regexp`/`encoding/*`/`crypto`/`path`/`time`/`net/url` · Node 内置 vs userland |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**M1–M6 已把「写日常脚本 / 多数扩展库不再事事插件」的硬缺口补齐。** 相对 Python / Go 的「通用原语层」,Marqdo **不再缺** 正则、编解码、路径、哈希、CSV、集合糖、CLI、日志、UUID。
|
||||
|
||||
仍缺的是 **第二档通用能力**:日历与时区、URL/查询串、配置格式(优先 TOML)、HTML 安全转义、文件系统再厚一点(`mkdir -p` / 元数据 / 递归删除)、轻量统计。这些**值得开 Mid2(M7+)**,但**不应**再开一轮「事事插件」;也**不要**把 YAML 全家桶、HTTP 服务端、SQLite、图像/ML 塞进 `lib/`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 已有基线(不是缺口)
|
||||
|
||||
| 族 | Marqdo | 对标 |
|
||||
|----|--------|------|
|
||||
| 文本 / 正则 | `text`++ · `re` | Python `str`/`re` · Go `strings`/`regexp` |
|
||||
| 编解码 | `encoding`(base64/hex)· `net.url_encode` | Go `encoding/base64`/`hex` · Python `base64`/`binascii` |
|
||||
| 路径 / 文件 | `path` · `fs`(含 copy/move/temp) | Go `path/filepath` · Python `pathlib`(子集) |
|
||||
| 完整性 / 机密 | `hash` · `secrets` | Go `crypto` 子集 · Python `hashlib`/`secrets` |
|
||||
| 表数据 | `csv` · `table`++ · `json` | Go `encoding/csv`/`json` · Python `csv`/`json` |
|
||||
| CLI / 可观测 | `cli` · `log` · `uuid` | Python `argparse`/`logging`/`uuid`(窄) |
|
||||
| 时间(极简) | `time`:unix/ms · format · parse · sleep | **远薄于** Python `datetime`/`zoneinfo` · Go `time` |
|
||||
| 网络客户端 | `net`:HTTP/SSE/cookie/multipart/markdown | Go `net/http` **客户端**侧;服务端在 `ext/web` |
|
||||
| 数学 | `math`(含公式/作图) | Python `math` + 教学向扩展 |
|
||||
|
||||
准入宪法仍见 [stdlib-mid.md](../design/stdlib-mid.md) §3:跨领域、难写对、解锁无插件写库、宿主面积极小。
|
||||
|
||||
---
|
||||
|
||||
## 2. 对照总表(按「脚本作者是否还要 foreign / 自造轮子」)
|
||||
|
||||
| 能力 | Python / Go 常态 | Marqdo 现状 | 缺口级别 | Mid2 建议 |
|
||||
|------|------------------|-------------|----------|-----------|
|
||||
| 日历日期 / 时区 / timedelta | `datetime`+`zoneinfo` · `time` | 仅 unix 戳 + 简单 format/parse | **高** | **M7** `datetime` |
|
||||
| URL 解析 / 查询串 | `urllib.parse` · `net/url` | 仅 `url_encode` | **高** | **M7** `url`(或并入 `net`) |
|
||||
| 配置 TOML 只读 | `tomllib`(PEP 680) | 无 | **中高** | **M8** `toml`(只读优先) |
|
||||
| 配置 YAML | 第三方;**故意不进** CPython | 无 | **低 / 慎入** | 默认 **不做**;与 Python 同理(复杂度/安全) |
|
||||
| HTML / XML 转义 | `html` · `html/template` 转义 | 无(`markdown_parse` ≠ 转义) | **中** | **M8** `html` 或 `text.html_escape` |
|
||||
| `mkdir -p` / 递归删 / stat | `pathlib`/`shutil` | `make_dir`/`remove` 偏浅 | **中** | **M9** `fs` 加厚 |
|
||||
| 文件元数据(size/mtime) | `os.stat` · `Path.stat` | 无一等 API | **中** | **M9** |
|
||||
| base32 / percent 完整 | `base64.b32*` · `url` | 无 base32 | **低–中** | **M8** `encoding` 加厚 |
|
||||
| 轻量统计 | `statistics` | `math` 无 mean/median | **低–中** | **M10** `stats` 或 `math` 薄加 |
|
||||
| 计数 / 默认字典 / deque | `collections` | `table` 可凑 | **低** | 优先用 `table`;必要时 M10 `collections` 极薄 |
|
||||
| 组合迭代 | `itertools` | 无 | **低** | 多数可用 `table`;**延后** |
|
||||
| 模板引擎 | Jinja / Go `text/template` | 无 | **不准入 Mid** | 应用层 / 未来 ext |
|
||||
| SQLite 客户端 | `sqlite3` · `database/sql` | **`ext/web` `# db`** | **不准入** | 保持扩展 |
|
||||
| HTTP 服务端 | — | **`ext/web`** | **不准入** | 已关闭(宿主波次另文) |
|
||||
| 密码哈希 Argon2 | 第三方 / 框架 | `ext/web` 已有 | **不准入 Mid** | 安全产品面 |
|
||||
| 完整 TLS/证书 API | `ssl` · `crypto/tls` | 客户端 HTTPS 由 ureq | **不准入** | 宿主实现细节即可 |
|
||||
| 压缩 zip/tar | `zipfile` · `archive/zip` | 无 | **低** | 可选 M10;体积敏感 |
|
||||
| 环境 `.env` | 第三方;Go 常自写 | **`sys.load_dotenv` 已有** | 无 | — |
|
||||
|
||||
---
|
||||
|
||||
## 3. 分项说明(高优先级)
|
||||
|
||||
### 3.1 日历 / 时区(M7 候选之首)
|
||||
|
||||
**问题**
|
||||
脚本与站点大量需要「今天」「本地日界」「RFC3339」「时区换算」。现有 `time.parse`/`format` 够演示,不够「难写对」的日历语义(闰秒除外,但 DST / offset 已够劝退字符串拼接)。
|
||||
|
||||
**对照**
|
||||
Python 强调 **aware datetime + zoneinfo**;Go `time.Location` 是日常依赖。Mid 原文已把「完整 datetime 时区库」标为刻意延后——M1–M6 完成后应升格。
|
||||
|
||||
**建议窄 API(设计文锁定)**
|
||||
`now` / `parse` / `format` / `add`(天/时)/ `to_unix` / `from_unix` / 可选 `in_zone`(IANA 或固定 offset)。**不做**完整历法 UI、农历、业务假期库。
|
||||
|
||||
### 3.2 URL 与查询串
|
||||
|
||||
**问题**
|
||||
`url_encode` 只解决「编码一段」;解析 `https://a/b?x=1&y=2#frag`、合并 query、取 path 仍靠 `re` 自造。浏览器代理 / `invoke` / webhook 场景高频。
|
||||
|
||||
**建议**
|
||||
`url.parse` → `{scheme,host,path,query,fragment}`;`url.query_parse` / `query_stringify`;与 `url_encode` 边界写进 `net` vs 新 `lib/url`。
|
||||
|
||||
### 3.3 TOML vs YAML
|
||||
|
||||
**外部事实**
|
||||
Python 因 **打包引导**(`pyproject.toml`)接受只读 `tomllib`([PEP 680](https://peps.python.org/pep-0680/));YAML 多次被拒:规范复杂、实现难维护、安全面大。
|
||||
|
||||
**对 Marqdo**
|
||||
catalog / 工具配置若走向 TOML,只读 `toml.parse` 性价比高。YAML:**默认不准入 Mid**;若 public 强需求,单独 ADR,且优先「JSON 超集子集」而非完整 1.2。
|
||||
|
||||
### 3.4 HTML 转义
|
||||
|
||||
**问题**
|
||||
`ext/web` 与浏览器 WASM 拼 HTML 时,缺 `escape` 易 XSS。这是「难写对 / 安全相关」的经典 stdlib 项(Python `html.escape`)。
|
||||
|
||||
**建议**
|
||||
极薄:`html.escape` / `unescape`(或挂 `text`)。**不做** DOM / 模板语言。
|
||||
|
||||
### 3.5 文件系统再厚
|
||||
|
||||
**问题**
|
||||
`make_dir` 是否递归、`remove` 是否递归、无 `stat`(size/mtime)、无 `walk`——脚本仍会 `foreign` 或脆弱字符串。
|
||||
|
||||
**建议**
|
||||
`fs.make_dirs` · `fs.remove_tree` · `fs.stat` · 可选 `fs.walk`(返回路径列表,非惰性迭代器协议)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 明确「不是缺口」
|
||||
|
||||
| 项 | 说明 |
|
||||
|----|------|
|
||||
| Mid M1–M6 清单本身 | 已收口;不要用本表重开 base64/re |
|
||||
| HTTP 服务 / DB / Agent | `ext/*`;见 [ext-hosting](ext-hosting-gaps.md) |
|
||||
| Dense embedding / 向量库默认化 | OKF 路线不变 |
|
||||
| 完整 `collections` / `itertools` 类型系统 | 语言没有泛型迭代协议;用 `table` |
|
||||
| 「对齐 Python 模块个数」 | 反模式;对齐**用例与难写对** |
|
||||
|
||||
---
|
||||
|
||||
## 5. 优先级建议(转入 Mid2)
|
||||
|
||||
| 优先级 | 波次草案 | 内容 |
|
||||
|--------|----------|------|
|
||||
| **高** | **M7** | `datetime` + `url` — **done** |
|
||||
| **高** | **M8** | `toml` 只读 + `html.escape` + `encoding` base32 — **done** |
|
||||
| **中** | **M9** | `fs` 加厚(dirs/stat/walk) — **done** |
|
||||
| **低** | **M10** | `stats` 薄 · log 字段 · (zip 默认跳过) — **done**(zip 仍跳过) |
|
||||
| **won't** | — | 完整 YAML · 模板引擎 · sqlite 进 `lib/` |
|
||||
|
||||
---
|
||||
|
||||
## 6. 与其它文档
|
||||
|
||||
| 文档 | 关系 |
|
||||
|------|------|
|
||||
| [stdlib-mid2.md](../design/stdlib-mid2.md) | **补齐设计(作者 API + 边界)** |
|
||||
| [stdlib-mid2.md](../roadmap/stdlib-mid2.md) | 实现波次 M7–M10 |
|
||||
| [stdlib-mid.md](../design/stdlib-mid.md) | Mid1 宪法;本调研不改准入原则 |
|
||||
| [web-net-capabilities.md](../design/web-net-capabilities.md) | 网络服务端能力在 ext,不进 Mid2 |
|
||||
@@ -0,0 +1,66 @@
|
||||
# 路线图:代码即文档叙述面摩擦(G1–G4)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Done**(实现已合入工作树;金样绿) |
|
||||
| 日期 | 2026-09-14 |
|
||||
| 设计 | [code-as-docs-gaps.md](../design/code-as-docs-gaps.md) |
|
||||
| 样例 | `examples/code-as-docs/index.mq.md` |
|
||||
|
||||
---
|
||||
|
||||
## 里程碑
|
||||
|
||||
### M1 — 文档与金样夹具
|
||||
|
||||
- [x] 设计文档记录 G1–G4 与启发式
|
||||
- [x] 本路线图
|
||||
- [x] `tests/markup-v03/` 四缝金样 + `gold.rs` `markup_v03_*`
|
||||
|
||||
### M2 — G1 模块级 `---`
|
||||
|
||||
- [x] `parse_classified`:顶层 frame 行 skip;顶层 Comment 引言 skip
|
||||
- [x] 函数体内 `---` / `***` 改为叙述跳过(不再收束;空返回收束)
|
||||
- [x] 金样:`module-hr.mq.md`
|
||||
|
||||
### M3 — G3 浮点面量与运算
|
||||
|
||||
- [x] `Literal::Num(f64)`
|
||||
- [x] `parse_primary` 识别 `digits.digits`(及 `.5` / `3.` 形态)
|
||||
- [x] `eval_binary` + bytecode Int/Num 提升(Int/Int `/` 仍为整除)
|
||||
- [x] 金样:`float-discount.mq.md`
|
||||
|
||||
### M4 — G2 叙述强调启发式
|
||||
|
||||
- [x] `scan_prose_line`:非代码形粗体、非返回形行内斜体 → 丢弃
|
||||
- [x] 保持 `**n=n+1**`、`**加一 37**`、整行 `*n*`、「返回*n*」
|
||||
- [x] 更新 Skill:允许装饰性强调;可执行仍看形状
|
||||
- [x] 金样:`soft-emphasis.mq.md`
|
||||
|
||||
### M5 — G4 动态脚注键
|
||||
|
||||
- [x] AST:`IndexKey::{Lit,Var}`(`` [^`ident`] ``)
|
||||
- [x] 解析、求值、bytecode
|
||||
- [x] 金样:`dynamic-footnote.mq.md`
|
||||
- [x] 回写 `examples/code-as-docs`(浮点折扣 + 动态键)
|
||||
|
||||
### M6 — 出门
|
||||
|
||||
- [x] `examples/code-as-docs` 展示四缝修复后的写法
|
||||
- [x] `cargo test --test gold` 绿
|
||||
- [x] 设计验收覆盖(见金样)
|
||||
|
||||
---
|
||||
|
||||
## 顺序建议
|
||||
|
||||
G1(小)→ G3(中,Literal/运算)→ G2(启发式,依赖金样钉行为)→ G4(AST 面)→ 回写样例。
|
||||
|
||||
---
|
||||
|
||||
## 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-09-14 | 初稿 |
|
||||
| 2026-09-14 | 实现完成并勾选 |
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **A0–A4 完成**(调研驱动优化闭环;A4:corpus/MCP 证据工具,权威仍是 `.mq.md`) |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · **缺口盘点** [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) |
|
||||
| 状态 | **A0–A4 完成**;**Wave B Active**(宪法优先:代码即文档 / call_site / OKF) |
|
||||
| 日期 | 2026-09-04 |
|
||||
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) · **[agent-framework-2026-09.md](../research/agent-framework-2026-09.md)** |
|
||||
| 设计 | [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md) · [okf.md](../design/okf.md) |
|
||||
| 邻近 | [agent-streaming.md](agent-streaming.md) · [okf-near-match.md](okf-near-match.md) |
|
||||
|
||||
@@ -13,21 +13,32 @@
|
||||
## 1. 优化原则(来自调研)
|
||||
|
||||
1. **强化差异化,不向 LangChain 薄循环回退**(禁止隐藏 TOOL: 主路径、禁止整文件 LLM 重写工作簿)。
|
||||
2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视**。
|
||||
2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视、源码/调用位置注入**。
|
||||
3. 外部 RAG/MCP 只作**工具**,不升为权威真相源。
|
||||
|
||||
自评四问见调研 §9。A0–A4 之后的缺口与建议分期 **B0–B5** 见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md)。
|
||||
自评四问见调研 §9。A0–A4 之后的缺口见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md)。**2026-09 Wave B** 锁定见 [agent-framework-2026-09.md](../research/agent-framework-2026-09.md)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 建议分期(摘要)
|
||||
## 2. A0–A4(已完成)
|
||||
|
||||
| 波次 | 主题 | 验收线索 |
|
||||
|------|------|----------|
|
||||
| **A0** | 工作簿补丁 / 固化可靠性 | **done** — 整文件 FIND 护栏;`soft` 仅 miss;decompose `n` 检查;`workbook_solidify` 单测;金样 `agent-workbook-patch-a0`(双 CONTINUE + solidify) |
|
||||
| **A1** | OKF 复用飞轮(lookup / near / soft_match UX) | **done** — `list_tasks` 含 description/aliases/status/llm_free/hits;`plan` 命中路径暴露 `match`/`score`;soft_match 策展行含 meta;view plan 卡显示 match;金样 `agent-kb-plan-hit`(exact hit + near soft-hit) |
|
||||
| **A2** | 过程可见(stream + view 过程卡) | **done** — `plan_append_*` / `plan_finish_stream` 始终写入 `events`(SSE 仍仅 `stream=True`);OKF REUSE 记 `decision`;view `plan-card` 渲染过程时间线(跳过 delta);金样断言 `events-ok`;对齐 [agent-streaming.md](agent-streaming.md) |
|
||||
| **A3** | 上下文预算(源码/Skill 渐进披露) | **done** — `source_brief` / 加深 `skill_brief`;`build_step_context` 默认预算 + `READ:source|skill`;`step max_reads`;父 `READ:skill`;金样 `agent-context-budget-a3` |
|
||||
| **A4** | 可选:RAG/MCP 工具适配器 | **done** — `corpus_search`(本地语料关键词);`mcp_list_tools` / `mcp_call`(JSON fixture);`authority=workbook`;金样 `agent-tools-rag-a4` |
|
||||
| **A0** | 工作簿补丁 / 固化可靠性 | **done** — 金样 `agent-workbook-patch-a0` |
|
||||
| **A1** | OKF 复用飞轮 | **done** — 金样 `agent-kb-plan-hit` |
|
||||
| **A2** | 过程可见 | **done** — events + view plan 卡 |
|
||||
| **A3** | 上下文预算 | **done** — `source_brief` / `READ:`;金样 `agent-context-budget-a3` |
|
||||
| **A4** | RAG/MCP 证据工具 | **done** — 金样 `agent-tools-rag-a4` |
|
||||
|
||||
细节与行业对照以调研正文为准;本文件只跟踪 **A0–A4** 实现分期。后续产品化 / 评测 / live MCP 等见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) §5(草案 B0–B5)。
|
||||
---
|
||||
|
||||
## 3. Wave B(Active — 宪法优先)
|
||||
|
||||
| 波次 | 主题 | 状态 |
|
||||
|------|------|------|
|
||||
| **B0** | 官方示例演示 call_site/源码/OKF;Skill/文档;上下文管道可读 | **done** |
|
||||
| **B0.5** | 本机 live(`.env` → 开发模型)验证「模型用上了文档」 | **done**(`AGENT_LIVE` / `AGENT_HARNESS_LIVE`) |
|
||||
| **B1** | 评测 harness 锁差异化指标(constitution / dump / writeback 遮蔽) | **Active** |
|
||||
| **B2–B5** | 真 MCP / resume+HITL / stats / 并行 | 暂缓 |
|
||||
|
||||
示例:`examples/agent-pong/` · `examples/agent-okf-flywheel/`。
|
||||
@@ -0,0 +1,102 @@
|
||||
# 路线图:宿主集成补齐(H0–H4)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active · 规划** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 缺口 | [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) |
|
||||
| 设计 | [ext-hosting-fill.md](../design/ext-hosting-fill.md) |
|
||||
| 相关 | [ext-web.md](ext-web.md)(W/C 完结)· [ext-agent-optimize.md](ext-agent-optimize.md) · [agent-streaming.md](agent-streaming.md) |
|
||||
| 基线 | v0.3.6+ |
|
||||
|
||||
本文只跟踪**实现波次**。作者 API、ABI 边界、禁止项以设计文为准。
|
||||
|
||||
---
|
||||
|
||||
## 0. 目标回顾
|
||||
|
||||
让 `ext/web` + `ext/ai` 具备:同域 SSE 中继、HTTP→用户 `##`、MCP Server(至少 stdio)、跨模块 db/corpus 可发现——从而下游无需 Python 旁路进程。
|
||||
|
||||
---
|
||||
|
||||
## 1. 波次总表
|
||||
|
||||
| 波次 | 内容 | 关闭缺口 | 状态 |
|
||||
|------|------|----------|------|
|
||||
| **H0** | 文档契约:跨模块 `db` 传 `url`;`corpus_search` 调用前 `ensure_plugin` 说明;缺口索引进 `doc/README` | GAP-05 文档侧 | **done** |
|
||||
| **H1** | `app.proxy` / `configure proxy=`:上游 SSE/HTTP **流式**转发 | GAP-01 | **done** |
|
||||
| **H2** | `app.invoke` / `configure invoke=`:请求 → 白名单 `##` → JSON | GAP-02 | **done** |
|
||||
| **H3** | 跨模块插件对象 `_type` 分发修补 + `corpus_search` 自动 `ensure_plugin` | GAP-05 运行时 | **done** |
|
||||
| **H4** | `agent.mcp_server` + `serve transport=stdio`(HTTP 可选 H4b) | GAP-03 | **done**(stdio) |
|
||||
| **H4b** | MCP Streamable HTTP | GAP-03 余量 | **todo**(可选) |
|
||||
| **—** | 副端口 API | GAP-04 | **won't**:H1+H2 同端口关闭 |
|
||||
|
||||
建议顺序:**H1 → H2 → H3 → H4**(H2 的 invoke 内核可被 H4 工具复用,故 H2 不宜晚于 H4)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分波工作项
|
||||
|
||||
### H1 — 流式代理
|
||||
|
||||
1. `plugins/web`:`proxy.rs` + `web_app_proxy`;listen 挂流式 handler。
|
||||
2. `ext/web`:`## proxy` + `configure proxy=` 表。
|
||||
3. 金样 `web-proxy-sse-smoke`(mock 上游)。
|
||||
4. 教程/public 短节:「浏览器同域调 LLM」。
|
||||
|
||||
**完成定义:** `curl -N` 同域 path 收到多帧 SSE;密钥仅 env 注入。
|
||||
|
||||
### H2 — HTTP invoke
|
||||
|
||||
1. 共享或插件内 `invoke_fn`(解析 `库.成员`、映射 body)。
|
||||
2. `web_app_invoke` + 白名单。
|
||||
3. 金样:临时 `##` 写文件 + JSON 响应;拒绝未允许路径。
|
||||
4. 迁移说明:替换 `/store/*` + 外挂 `marqdo run`。
|
||||
|
||||
**完成定义:** 单进程 `listen` 下表单/fetch 可触发用户 `##`。
|
||||
|
||||
### H3 — db / corpus
|
||||
|
||||
1. 复现并修跨模块 `unknown object type db`(设计选项 A)。
|
||||
2. `ext/ai` `corpus_search` 路径 `ensure_plugin`。
|
||||
3. 金样 `web-db-cross-module-smoke` + corpus CLI run 金样。
|
||||
|
||||
### H4 — MCP Server
|
||||
|
||||
1. `plugins/agent` stdio JSON-RPC 最小子集:`initialize` / `tools/list` / `tools/call`。
|
||||
2. `ext/ai` `# mcp_server` · `## tool` · `## serve`。
|
||||
3. 工具调用复用 H2 `invoke_fn`。
|
||||
4. 金样夹具;文档对接 Cursor `mcp.json` 示例。
|
||||
|
||||
**H4b:** Streamable HTTP 与鉴权;不阻塞 H4 stdio 发版。
|
||||
|
||||
---
|
||||
|
||||
## 3. 刻意不做
|
||||
|
||||
| 项 | 原因 |
|
||||
|----|------|
|
||||
| 默认开启任意 `##` 远程执行 | 安全 |
|
||||
| 中继进 `lib/net` / `src/host` | 边界 |
|
||||
| 重开 W0–W7 内容站清单 | 已完结 |
|
||||
| 以副端口为推荐架构 | H1+H2 同端口即可 |
|
||||
| Dense embedding 默认 | OKF 路线不变 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 与发版
|
||||
|
||||
- 每波可随小版本发布;H1+H2 建议同一版本对外宣传「可去掉 llm_proxy」。
|
||||
- H4 可标 `ext/ai` 能力点,与「真 MCP 客户端」分列 Release notes。
|
||||
|
||||
---
|
||||
|
||||
## 5. 进度勾选(落地时改)
|
||||
|
||||
- [x] H0 缺口 + 补齐文档
|
||||
- [x] H1 proxy SSE
|
||||
- [x] H2 invoke
|
||||
- [x] H3 db/corpus
|
||||
- [x] H4 mcp_server stdio
|
||||
- [ ] H4b mcp http(可选)
|
||||
- [x] 研究文 GAP 状态改为 closed(H4b 除外)
|
||||
@@ -0,0 +1,126 @@
|
||||
# 官方扩展:`ext/linalg` 实现路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **L0–L6 + 公式文档面 F1–F3 已落地 · L7+ 远期** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| **锁定设计** | [design/ext-linalg.md](../design/ext-linalg.md) · [design/ext-linalg-formula-doc.md](../design/ext-linalg-formula-doc.md) |
|
||||
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
|
||||
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [view.md](../design/view.md) · [ext-quantum-q7.md](../design/ext-quantum-q7.md) |
|
||||
| 安装(规划) | `marqdo ext add linalg`(`linalg` / `线性代数`) |
|
||||
|
||||
本文只跟踪**实现阶段**。作者面、公式规则、展示以设计文为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标回顾(一句)
|
||||
|
||||
**可运行的线性代数公式文档**:矩阵公式可化简、可 KaTeX 展示;跑通即在规则集内正确;需要时再稠密求值与分解,并内嵌结构 SVG。
|
||||
|
||||
---
|
||||
|
||||
## 2. 落地阶段
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **L0** | CATALOG + `plugins/linalg` ping + L1 `ensure_plugin`;`ext add` 条目 | **done** |
|
||||
| **L1** | MatExpr:`symbol` / 稠密叶子 / `mul`·`add`·`T`·`inv`;`simplify` R1–R5;`latex`·`ascii`·`show` | **done** |
|
||||
| **L2** | `explicit` / 小阵 gemm·解系·`det`·`trace`;维数护栏;金样 `linalg-basic-smoke` | **done** |
|
||||
| **L3** | `block` + `collapse`;`kron` 惰性 + R7;金样 `linalg-block-kron` | **done** |
|
||||
| **L4** | `factorize` LU/QR/SVD/eig(+ 可选 chol);结构 SVG `svd|qr|ge|eig`;金样 `linalg-factor-smoke` | **done** |
|
||||
| **L5** | `heatmap`/`hinton`;examples(最小二乘 / SVD 示意);public + skill 摘要 | **done** |
|
||||
| **L6** | 复数 dtype;`lstsq`;`norm`/`cond`;主题令牌对齐 | **done** |
|
||||
| **F1** | 展示路径默认 simplify;公式文档金样 | **done** |
|
||||
| **F2** | 符号引入降噪;examples 讲义化 | **done** |
|
||||
| **F3** | 紧凑糖 + public「如何写公式文档」 | **done** |
|
||||
| **L7+** | 矩阵微积分 / 更大 BLAS 依赖(仅当用户明确要求) | **deferred** |
|
||||
|
||||
验收金样(规划路径):`tests/ext/linalg-*-smoke.mq.md`;示例:`examples/linalg-least-squares/`、`examples/linalg-svd/`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 每阶段出口检查
|
||||
|
||||
### L0
|
||||
|
||||
- [x] `ext/linalg` CATALOG 含 `linalg`
|
||||
- [x] 插件 `ping` → ok
|
||||
- [x] 文档:`marqdo ext add linalg`
|
||||
|
||||
### L1
|
||||
|
||||
- [x] `(AB)^\top` → `simplify` → `B^T*A^T`(无 dense)
|
||||
- [x] 形状错误含行列信息
|
||||
- [x] CLI `ascii` / `show` SVG 通道
|
||||
- [x] 中英 L1 各一 smoke
|
||||
|
||||
### L2
|
||||
|
||||
- [x] `from_formula` 吸收 `$$` 数值阵
|
||||
- [x] `solve` 与手算 2×2 一致
|
||||
- [x] 超维 `explicit` 硬错误(单元测护栏)
|
||||
|
||||
### L3
|
||||
|
||||
- [x] 分块乘 `collapse` 后块级正确
|
||||
- [x] Kronecker 默认不膨胀元素个数(惰性 `A⊗B`)
|
||||
|
||||
### L4
|
||||
|
||||
- [x] SVD/特征结果对象字段稳定
|
||||
- [x] SVG 含可断言标记(如 `data-linalg="eig"`)
|
||||
- [x] `factorize` + 二次 `solve` 复用(LU)
|
||||
|
||||
### L5
|
||||
|
||||
- [x] 至少 1 个 examples 可 `marqdo run`
|
||||
- [x] public/features 或 tutorial 短页
|
||||
- [x] skill / CHANGELOG Unreleased 条目
|
||||
|
||||
### L6
|
||||
|
||||
- [x] `lstsq` / `norm` / `cond` / `rank` 金样
|
||||
- [x] `dtype=complex` 基线(Frobenius;分解仍为实数)
|
||||
- [x] `draw theme=light|dark|bw` 与 quantum Q8 令牌对齐(`data-theme`)
|
||||
|
||||
### F1
|
||||
|
||||
- [x] `ascii` / `latex` / `show` 默认 simplify
|
||||
- [x] 金样:`.T` 后直接 `ascii` 得 `B^T*A^T`(无需显式 simplify)
|
||||
- [x] 设计文 [ext-linalg-formula-doc.md](../design/ext-linalg-formula-doc.md) 落地
|
||||
|
||||
### F2
|
||||
|
||||
- [x] 符号引入降噪(选定候选) — GFM `@` 表 + `la.declare`
|
||||
- [x] 至少 1 个 example 以代数面为主叙述 — `examples/linalg-transpose/`
|
||||
|
||||
### F3
|
||||
|
||||
- [x] `T_ascii` / `转置文本` 一步展示糖
|
||||
- [x] `explicit` 默认先 simplify(`raw=` 可关)
|
||||
- [x] public `07-linalg` / `07-线性代数`「如何写公式文档」
|
||||
|
||||
---
|
||||
|
||||
## 4. 依赖与并行
|
||||
|
||||
| 依赖 | 说明 |
|
||||
|------|------|
|
||||
| ABI v2 + ext CLI | 已有 |
|
||||
| view KaTeX / plot | 已有;L1 `show` 接现成通道 |
|
||||
| Release native zip | 随首次含 `plugins/linalg` 的发版接入 |
|
||||
| quantum 数值核 | **可选**私有复用;不阻塞 L1–L2 |
|
||||
|
||||
不阻塞项:浏览器 WASM 上的 linalg(默认 host/native;WASM 另议)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议开发顺序(下一手)
|
||||
|
||||
1. **L7+** 仅当用户明确要求更深符号(微积分等)。公式文档面 F1–F3 已收口。
|
||||
|
||||
---
|
||||
|
||||
## 6. 一句话
|
||||
|
||||
**代数面像讲义、计算面是步骤;跑通即在规则集内正确;每阶段都有可跑金样。**
|
||||
@@ -35,6 +35,18 @@
|
||||
| **W7** | Cache-Control / 404·500 / 重定向 / sitemap·robots / init 唯一·索引 / HTTPS 反代说明 | **done** |
|
||||
| **P3** | 审计时间戳 / 外键 / RBAC / 相册 / ETag | **done** |
|
||||
|
||||
### 定制波次(规划中)
|
||||
|
||||
自研后台 / 主题 / 响应式踩坑见 [ext-web-customization-limits.md](../research/ext-web-customization-limits.md);解法索引 [ext-web-customization/](../design/ext-web-customization/)。
|
||||
|
||||
| 波次 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **C0** | `admin` 关则不占路径;`admin_prefix` / 登录回跳可配 | **done** |
|
||||
| **C1** | gate 匹配与未登录策略一致;段边界默认 admin gate | **done** |
|
||||
| **C2** | `shell_css` + `layout` 松绑 | **done** |
|
||||
| **C3** | 样式 strict / 脚本 defer·version | **done** |
|
||||
| **C4** | 条件导航 when/media(layout 见 C2) | **done** |
|
||||
|
||||
验收金样:`tests/ext/web-smoke.mq.md`、`tests/ext/web-security-smoke.mq.md`、`tests/ext/web-drivers-smoke.mq.md`、`tests/ext/web-upload-smoke.mq.md`、`tests/ext/web-db-w6-smoke.mq.md`、`tests/ext/web-w7-finish-smoke.mq.md`、`tests/ext/web-p3-smoke.mq.md`、`ext_cli_add_web`。
|
||||
|
||||
---
|
||||
@@ -57,3 +69,4 @@
|
||||
| [design/ext-web.md](../design/ext-web.md) | **真理** |
|
||||
| [user-site.md](../design/user-site.md) | 静态站互补 |
|
||||
| [ext-quantum.md](ext-quantum.md) | 同属官方 ext + ABI + `ext add` |
|
||||
| [ext-hosting.md](ext-hosting.md) · [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) | **W/C 之后**:同域 SSE 中继、HTTP→`##`(不重开本表 W0–W7) |
|
||||
@@ -0,0 +1,59 @@
|
||||
# Roadmap:lib / ext 代码即文档
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Active** |
|
||||
| 日期 | 2026-09-14 |
|
||||
| 相关 | [lib-code-as-docs.md](../design/lib-code-as-docs.md) · [view-markup-surface.md](../design/view-markup-surface.md) · [bracket-call-modifiers.md](../design/bracket-call-modifiers.md) · [collection-access-link.md](../design/collection-access-link.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 总序(防返工)
|
||||
|
||||
1. **方括号标记调用**(设计 + AST + 金样)— **已落地**
|
||||
2. lib / view 设计文档 — **已写**
|
||||
3. View 表面(Index 链接形、括号调用)— **已落地**
|
||||
4. 分波改造 `lib/*` → `ext/*`
|
||||
|
||||
旧 `>` / 粗体调用、脚注取元解析均保留。
|
||||
|
||||
## 1. 里程碑
|
||||
|
||||
| 波 | 内容 | 状态 |
|
||||
|----|------|------|
|
||||
| **Call** | `pre_modifiers`;`tests/structure/bracket-call.mq.md`;mapping / call-arguments | **done** |
|
||||
| **M0 View** | `InterpPart::Index` → `[k](base)`;`call_display` 修饰表面 | **done** |
|
||||
| **M1** | 试点 `lib/table` · `lib/text` · `lib/json`(中英)+ public/stdlib | **done** |
|
||||
| **M2** | 其余 `lib/*` 叙述化;禁新脚注取元 | **done** |
|
||||
| **M3–M4** | `ext/web`、`ext/ai`:脚注→链接取元;叙述;示例可逐步换括号调用 | **done**(取元迁移) |
|
||||
| **M5** | quantum / linalg + full gold | **done** |
|
||||
| **M6** | examples + public/structure + tests/ext·lib 链接取元;cafe 括号调用例 | **done** |
|
||||
| **M7** | structure collection 金样改链接形;public/stdlib 括号调用例 | **done** |
|
||||
| **M8** | 教程第 9 章 + Skill examples → 链接取元 / v0.3 标记 | **done** |
|
||||
| **M9** | 教程其余章节(1–8、10–12、14)全面对齐 v0.3 + 链接取元 | **done** |
|
||||
| **M10** | public/stdlib 剩余演示统一括号调用;public import 返回面修到 v0.3 | **done** |
|
||||
| **M11** | View:`bracket_marked` 使无修饰 `[callee]` 也显示括号形 | **done** |
|
||||
|
||||
## 2. 验收(出门)
|
||||
|
||||
- 括号调用与 `[k](c)` 取元金样并存、不回归。
|
||||
- 试点库可读:目的句 + 叙述形参 + 一例 + 短实现。
|
||||
- `cargo test --test gold` 绿。
|
||||
- 脚注取元金样(`tests/structure/footnote*`)仍保留作兼容门禁。
|
||||
- 教程与 Skill 示例以链接取元 / `**` 代码 / `*` 返回为准。
|
||||
|
||||
## 3. 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-09-14 | 初稿;Call + M0 标 done |
|
||||
| 2026-09-14 | M1 试点 table/text/json + public/stdlib 标 done |
|
||||
| 2026-09-14 | M2 其余 lib 叙述化标 done |
|
||||
| 2026-09-14 | M3–M4 ext/web+ai 脚注→链接取元 |
|
||||
| 2026-09-14 | M5 quantum/linalg 叙述 + public/features 取元 |
|
||||
| 2026-09-14 | M6 examples/public/tests 批量链接取元 + cafe 括号调用 |
|
||||
| 2026-09-14 | M7 structure collection 金样 + stdlib 括号调用例 |
|
||||
| 2026-09-14 | M8 教程 + Skill examples 同步 |
|
||||
| 2026-09-14 | M9 教程全书对齐 v0.3 标记与链接取元 |
|
||||
| 2026-09-14 | M10 public/stdlib 括号调用扫尾 + import 返回面 |
|
||||
| 2026-09-14 | M11 View `bracket_marked` 无修饰括号调用表面 |
|
||||
@@ -0,0 +1,111 @@
|
||||
# 路线图:Marqdo Markdown 语法映射 v0.3(叙述统一)
|
||||
|
||||
「Markup」= Marqdo 把 Markdown 标记当成语法的那一层(不是另一个产品)。v0.3 = 现行映射:粗体代码、斜体返回。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Done(v1.0.0)** |
|
||||
| 日期 | 2026-09-13 |
|
||||
| 设计 | [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) |
|
||||
| ADR | [0005-prose-unified-markup.md](../adr/0005-prose-unified-markup.md) |
|
||||
| 依赖 | 现有管线 [interpreter.md](interpreter.md) · [pipeline-debug.md](../design/pipeline-debug.md) |
|
||||
|
||||
---
|
||||
|
||||
## 目标
|
||||
|
||||
把 v0.3 宪法落到词法 → AST → 语义 → 双后端,使动机示例(加一函数)成为金样例,并安全迁移存量代码。
|
||||
|
||||
---
|
||||
|
||||
## 里程碑
|
||||
|
||||
### M0 — 设计冻结与双模式骨架(文档 ✅ / 代码 ⏳)
|
||||
|
||||
- [x] 设计文档 + ADR Proposed + 本路线图
|
||||
- [x] **钉死**:空返回词法(设计 §7.2);提及/未使用变量(§4.4);升参 vs 绑定图(§8.2)
|
||||
- [x] **钉死**:一行多 `**…**` 按序执行(设计 §12 #6)
|
||||
- [x] **不做双模式** — 直接 v0.3 默认
|
||||
|
||||
**出门:** 设计评审通过;旗标可切换;无行为默认变化。
|
||||
|
||||
### M1 — 内联扫描与 AST
|
||||
|
||||
- [x] 金样例目录 `tests/markup-v03/`(夹具 + `gold.rs` `#[ignore]`;见目录 README)
|
||||
- [x] `Prose` 行内联扫描:`` `ident` `` / `**…**` / `*…*`
|
||||
- [x] `Stmt::Return` ← italic;`Stmt` ← bold Assign/Call
|
||||
- [x] `Param.inferred` + 升参
|
||||
- [x] `tests/markup-v03/` 金样通过(默认运行时)
|
||||
|
||||
**出门:** `cargo test markup_v03`(无 ignore)绿。
|
||||
|
||||
### M2 — 形参推断
|
||||
|
||||
- [x] `InferParams`:首次 `` `名` `` = 必选;`` `名`=默认 `` = 可选
|
||||
- [x] 体赋值 `n=n+1` 不误判为默认
|
||||
- [x] 与显式 `+` 合并规则 + 警告
|
||||
- [x] 方法 `self`/`自` 排除
|
||||
- [x] 金样例:默认实参、位置/具名调用、粗体内调用
|
||||
|
||||
**出门:** 推断签名与 `+` 兼容套件绿。
|
||||
|
||||
### M3 — 调用面与消歧
|
||||
|
||||
- [x] `**callee args**` ≡ `> callee args`
|
||||
- [x] else 臂 `N. *` 与返回斜体消歧
|
||||
- [x] 一行多 `**…**` 按序执行
|
||||
- [x] 金样例:`---` / `*None*` / 整行 `**` / 兼容 `****`;叙述死绑定不升参
|
||||
- [x] 诊断:必选缺失、未知 callee(已有 errors 金样);死变量不报错
|
||||
- [x] 残缺粗体:与 GAP-06/07「未闭合后恢复」冲突,保持 Comment 跳过恢复,不硬报错
|
||||
- [x] 粗体内表达式语句:`**n + 1**` 求值后丢弃(非误判为调用)
|
||||
- [x] 叙述斜体:仅整行 / `返回*…*` / 表达式形当返回(`*very important*` 不收束函数)
|
||||
|
||||
**出门:** `tests/markup-v03/*` 覆盖设计 §9 示例。
|
||||
|
||||
### M4 — 双后端与工具
|
||||
|
||||
- [x] 字节码发射跟随新 Stmt 源
|
||||
- [x] `view` / Structure:推断形参 `chip inferred` + Functions 大纲标注
|
||||
- [ ] (可选)`marqdo migrate markup-v03` 机械改写提示/工具
|
||||
|
||||
**出门:** tree 与 bytecode 后端对 `markup-v03` 金样一致。
|
||||
|
||||
### M5 — 默认切换与存量迁移
|
||||
|
||||
- [x] 默认 `MarkupEdition::V03`
|
||||
- [x] 迁移 `tests/**`、`lib/**`、`ext/**`、`public/**`、教程
|
||||
- [x] 更新 `.cursor/skills/marqdo/SKILL.md` 硬规则
|
||||
- [x] 修订 [markdown-mapping.md](../design/markdown-mapping.md) 为 v0.3 正式正文(或声明由 v0.3 文件接任)
|
||||
- [x] ADR 0005 → **Accepted**
|
||||
- [x] CHANGELOG / 发版说明(破坏性:标记对调)— **v1.0.0**
|
||||
|
||||
**出门:** 全量 gold 默认绿(live LLM 无钥跳过);无 v0.2 双模式。
|
||||
|
||||
---
|
||||
|
||||
## 非目标(本路线)
|
||||
|
||||
- 不改插件 ABI / Go libweb
|
||||
- 不引入 `def`/`return` 关键字
|
||||
- M0–M4 不强制改生产 `.mq.md`
|
||||
|
||||
---
|
||||
|
||||
## 风险
|
||||
|
||||
| 风险 | 缓解 |
|
||||
|------|------|
|
||||
| 标记对调导致海量假失败 | 双模式 + 分目录金样;默认晚切换 |
|
||||
| 形参推断误伤局部变量 | 金样例钉启发式;允许过渡期写 `+` |
|
||||
| 空返回 vs `**` 词法 | §7.2 已钉:整行 `**` = 空返回;推荐优先 `---` |
|
||||
| 叙述反引号误升参 | §8.2 升参需可执行面读取;死绑定不进 params |
|
||||
| Skill/AI 仍按 v0.2 生成 | M5 同步 Skill;过渡期文档标明版本 |
|
||||
|
||||
---
|
||||
|
||||
## 修订历史
|
||||
|
||||
| 日期 | 说明 |
|
||||
|------|------|
|
||||
| 2026-09-13 | 初稿与设计/ADR 同步 |
|
||||
| 2026-09-13 | 空返回与提及性反引号决议合入;M0 文档项勾选 |
|
||||
@@ -18,7 +18,7 @@
|
||||
| **诊断** | 语句级 `path:line:col: message`;字节码指令带 `spans`;errors 金样例双后端断言位置 | **P0 完成** |
|
||||
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
|
||||
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
|
||||
| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
|
||||
| **标准库** | 核心 L1 + Mid M1–M6 + Mid2 M7–M10 已完成([stdlib-modules.md](../design/stdlib-modules.md) · [stdlib-mid2.md](../design/stdlib-mid2.md)) | **P2 + Mid1 + Mid2 完成** |
|
||||
| **模块** | [module-namespace.md](../design/module-namespace.md):**M1+M2 已落地**(库名绑定、`库.成员` / `use`;无扁平合并) | — |
|
||||
|
||||
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
|
||||
|
||||
@@ -0,0 +1,200 @@
|
||||
# 路线图:中层标准库(数个版本)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **M1–M6 已落地**(收口) |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 设计 | [stdlib-mid.md](../design/stdlib-mid.md) |
|
||||
| 后续 | [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) |
|
||||
| 相关 | [stdlib-modules.md](../design/stdlib-modules.md) · [next-phase.md](next-phase.md) · [ext-cli.md](../design/ext-cli.md) |
|
||||
|
||||
> **不预标 SemVer。** 每一波随当时产品发版合入;下文用 **M1…M6** 波次名。每波须可单独演示、可回滚。
|
||||
|
||||
---
|
||||
|
||||
## 0. 总序
|
||||
|
||||
```text
|
||||
M1 文本与编解码地基 re + encoding ← 最先解锁「无插件写库」
|
||||
M2 路径与文件中层 path + fs 加厚
|
||||
M3 完整性与机密 hash + secrets
|
||||
M4 表格数据与文本加厚 csv + text++
|
||||
M5 集合与 CLI 糖 table/listx + cli
|
||||
M6 可观测与标识 log + uuid(+ 可选 yaml)
|
||||
```
|
||||
|
||||
原则:
|
||||
|
||||
1. **先原语、后糖**:正则 / 编解码 / 路径先于 CLI 糖与日志格式。
|
||||
2. **每波必须有金样 + public 短页**;无文档不算完成。
|
||||
3. **并行约束**:不阻塞 `ext/linalg` 等已定领域工作;但新官方能力评审优先问 Mid。
|
||||
4. **插件冻结规则**:自 M1 起,官方新增「通用」ABI 插件默认 **拒绝**,除非设计文档论证无法用 host+L1。
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状缺口(开工依据)
|
||||
|
||||
| 能力 | 现状 | 后果 |
|
||||
|------|------|------|
|
||||
| 正则 | 无 | 校验、替换、简单解析只能 foreign 或插件 |
|
||||
| base64 / hex | 无(仅有 `url_encode`) | 令牌、摘要、嵌二进制文本困难 |
|
||||
| 路径代数 | `fs` 只做 I/O | 拼接靠字符串,跨平台易错 |
|
||||
| 哈希 / HMAC | 无 | 校验、缓存键、签名只能外联 |
|
||||
| CSV | 无 | 数据脚本推向外联 Python |
|
||||
| `lib/text` | 3 个包装函数 | 「有 text 库」名不副实 |
|
||||
| 安全随机 | 仅 `math.random` | 易误用于 token |
|
||||
| 结构化日志 / flags | 无 | 每个脚本自造 |
|
||||
|
||||
对照:Go 日常高频包(`regexp`、`encoding/*`、`crypto`、`path/filepath`、`slices`)与 Python「难写对才进 stdlib」——正是 M1–M5 的选型来源;**不**把 HTTP 服务端、数据库驱动塞进 Mid(见设计文 §3.2)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 波次明细
|
||||
|
||||
### M1 — 正则与编解码(最高优先) — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/re.mq.md` / `lib/正则.mq.md` | `is_match` / `find` / `find_all` / `replace` / `split` |
|
||||
| `lib/encoding.mq.md` / `lib/编码.mq.md` | `base64_*` / `hex_*` |
|
||||
| Host | `host_re_*`(`regex`)、`host_encoding_*`(无第三方编解码 crate) |
|
||||
| 金样 | `tests/lib/re-smoke` · `正则-烟测` · `encoding-smoke` · `编码-烟测` |
|
||||
| 文档 | [stdlib-re.md](../design/stdlib-re.md) · [stdlib-encoding.md](../design/stdlib-encoding.md) · public `08-re-encoding` |
|
||||
| 验收 | 无插件:邮箱式校验 + base64/hex 往返 |
|
||||
|
||||
**刻意不做:** 回溯引用极致兼容、替换回调、完整 PCRE 方言文档化——先 RE2/ Rust `regex` 语义并写清。
|
||||
|
||||
---
|
||||
|
||||
### M2 — 路径与文件中层 — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/path.mq.md` / `lib/路径.mq.md` | `join` / `split` / `file_name` / `parent` / `extension` / `normalize` / `is_absolute` |
|
||||
| `lib/fs` 加厚 | `copy_file` / `move` / `make_temp`(文本边界;无 `read_bytes`) |
|
||||
| Host | `host_path_*`、`host_copy_file` / `host_move` / `host_make_temp` |
|
||||
| 金样 | `path-smoke` · `路径-烟测` · `fs-copy-move` · `文件-复制` |
|
||||
| 文档 | [stdlib-path.md](../design/stdlib-path.md) · [stdlib-fs-mid.md](../design/stdlib-fs-mid.md) · public `09-path-fs` |
|
||||
| 验收 | 规范化 + 沙箱内复制/移动 |
|
||||
|
||||
**刻意不做:** 完整 `shutil`、监视 `inotify`、权限 ACL 全家桶。
|
||||
|
||||
---
|
||||
|
||||
### M3 — 哈希与机密 — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/hash.mq.md` / `lib/哈希.mq.md` | `sha256` / `sha1` / `md5` / `hmac_sha256` |
|
||||
| `lib/secrets.mq.md` / `lib/机密.mq.md` | `token_hex` / `token_urlsafe` |
|
||||
| Host | `host_hash_*`、`host_secrets_*`(`sha2`/`sha1`/`md-5`/`hmac`/`getrandom`) |
|
||||
| 金样 | `hash-smoke` · `哈希-烟测` · `secrets-smoke` · `机密-烟测` |
|
||||
| 文档 | [stdlib-hash.md](../design/stdlib-hash.md) · [stdlib-secrets.md](../design/stdlib-secrets.md) · public `10-hash-secrets` |
|
||||
| 验收 | 已知向量 + 令牌长度 |
|
||||
|
||||
**刻意不做:** 密码哈希(Argon2/bcrypt)、完整 TLS、证书管理——仍属服务端/安全产品。
|
||||
|
||||
---
|
||||
|
||||
### M4 — CSV 与文本加厚 — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/csv.mq.md` / `lib/逗号表.mq.md` | `parse` / `stringify`(首行表头 → list of maps) |
|
||||
| `lib/text` / `文本` 加厚 | `contains` / `starts_with` / `ends_with` / `replace` / `to_upper`/`to_lower` / `repeat` / `pad` |
|
||||
| Host | `host_csv_*`、`host_text_*` |
|
||||
| 金样 | `csv-smoke` · `逗号表-烟测` · `text-mid-smoke` · `文本-加厚-烟测` |
|
||||
| 文档 | [stdlib-csv.md](../design/stdlib-csv.md) · [stdlib-text-mid.md](../design/stdlib-text-mid.md) · public `11-csv-text` |
|
||||
| 验收 | CSV 往返 + 文本清洗小例 |
|
||||
|
||||
**可选同波:** 极简 `format`(`{name}` 替换),若与引用语法冲突则延后。
|
||||
|
||||
---
|
||||
|
||||
### M5 — 集合算法与 CLI — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/table` / `表` 加厚 | `sort` / `sort_by` / `unique` / `chunk` / `zip` / `flatten`(`reverse` 已有) |
|
||||
| `lib/cli.mq.md` / `lib/命令行.mq.md` | `parse`(`--k v` / `--k=v` / `--flag`;位置参 `_`) |
|
||||
| Host | `host_list_sort*` / `unique` / `chunk` / `zip` / `flatten`、`host_cli_parse` |
|
||||
| 金样 | `table-list-mid` · `cli-sort-smoke` · `表-命令行-烟测` |
|
||||
| 文档 | [stdlib-list-cli.md](../design/stdlib-list-cli.md) · public `12-list-cli` |
|
||||
| 验收 | CSV 按键排序 + 参数解析 |
|
||||
|
||||
**刻意不做:** 泛型迭代器协议、惰性流、完整 argparse 互斥组。
|
||||
|
||||
---
|
||||
|
||||
### M6 — 日志、UUID、收口 — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/log.mq.md` / `lib/日志.mq.md` | `debug`/`info`/`warn`/`error`;level 过滤;一行文本 |
|
||||
| `lib/uuid.mq.md` / `lib/标识.mq.md` | `v4` |
|
||||
| Host | `host_log_set_level` / `host_log_line`、`host_uuid_v4` |
|
||||
| 金样 | `log-uuid-smoke` · `日志-标识-烟测` |
|
||||
| 文档 | [stdlib-log-uuid.md](../design/stdlib-log-uuid.md) · public `13-log-uuid` |
|
||||
| 文档收口 | `stdlib-modules.md` 总表;设计文状态 → **M1–M6 已落地** |
|
||||
| 可选未做 | `yaml` 只读子集(默认不做) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 跨波次工程清单
|
||||
|
||||
每波共用:
|
||||
|
||||
- [ ] 中英 L1 对称([stdlib-i18n.md](../design/stdlib-i18n.md))
|
||||
- [ ] `host_*` 形参在 L1 **全量转发**([stdlib-modules.md](../design/stdlib-modules.md) §2.1)
|
||||
- [ ] 双后端金样(tree + bytecode,若该 host 已接线)
|
||||
- [ ] WASM:标注 `host-only` 或实现 stub
|
||||
- [ ] CHANGELOG「标准库」条目
|
||||
- [ ] skill `examples.md` 增加 Mid 惯用写法(GFM 优先)
|
||||
|
||||
宿主膨胀守卫:
|
||||
|
||||
- 新增 crate 须在 PR/设计中写清:**为何不能纯 mq**、**features 如何裁剪**、**许可证**。
|
||||
- 禁止借 Mid 把 `ext/web` 的服务端栈链进主二进制。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与官方扩展的互动(减插件)
|
||||
|
||||
| 扩展 | Mid 落地后可做的减负 |
|
||||
|------|----------------------|
|
||||
| `ext/web` | 路由/校验用 `re`;ETag/缓存键用 `hash`;静态路径用 `path` |
|
||||
| `ext/agent` | 工具参数校验、密钥材料用 `secrets`/`hash`(领域核仍插件) |
|
||||
| `ext/ai/llm` | 头/体编解码走 `encoding` |
|
||||
| `ext/linalg` / `quantum` | **不**迁入 Mid;继续插件;仅共用 `path`/`hash` 等通用面 |
|
||||
|
||||
跟踪方式:某波完成后,开短 issue/清单「ext X 可删除的原生辅助」,不强迫同波大改。
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议人力切分(示意)
|
||||
|
||||
| 波次 | 大致体量 | 可演示产物 |
|
||||
|------|----------|------------|
|
||||
| M1 | 中 | 「正则替换 + base64 往返」用户页 |
|
||||
| M2 | 中 | 「安全拼接路径写文件」 |
|
||||
| M3 | 小–中 | 「下载内容 sha256 校验」 |
|
||||
| M4 | 中 | 「CSV → 表 → 打印」 |
|
||||
| M5 | 小–中 | 「零插件数据 CLI」 |
|
||||
| M6 | 小 | 「带 log level 的脚本」 |
|
||||
|
||||
若只能开一条线:**M1 → M3 → M2 → M4 → M5 → M6**(完整性校验常比路径代数更刚需时,M3 可紧贴 M1)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 完成定义(整条 Mid 叙事)
|
||||
|
||||
当 M1–M6 完成时,对外可宣称:
|
||||
|
||||
> Marqdo 自带中层标准库:正则、编解码、路径、哈希、CSV、加厚文本与集合/CLI 糖,以及日志与 UUID;**写通用脚本与多数扩展库不再需要原生插件。**
|
||||
> 插件保留给 web 运行时、智能体、量子与线性代数等**领域引擎**。
|
||||
|
||||
---
|
||||
|
||||
## 7. 一句话
|
||||
|
||||
**按 M1→M6 把通用原语沉进 `lib/`,用数个发版周期换掉「事事插件」——领域 `ext/` 继续尖,语言本体变宽。**
|
||||
@@ -0,0 +1,91 @@
|
||||
# 路线图:中层标准库第二波(M7–M10)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Completed · M7–M10 已落地(zip 跳过)** |
|
||||
| 日期 | 2026-09-09 |
|
||||
| 设计 | [stdlib-mid2.md](../design/stdlib-mid2.md) |
|
||||
| 缺口 | [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) |
|
||||
| 前序 | [stdlib-mid.md](stdlib-mid.md)(**M1–M6 done**) |
|
||||
| 基线 | v0.3.7+ |
|
||||
|
||||
> **不预标 SemVer。** 波次名 **M7…M10**;每波可单独演示、可回滚。
|
||||
|
||||
---
|
||||
|
||||
## 0. 总序
|
||||
|
||||
```text
|
||||
M7 时间与地址 datetime + url
|
||||
M8 配置与安全字面 toml(只读) + html.escape + encoding/base32
|
||||
M9 文件再厚 fs make_dirs / remove_tree / stat / walk
|
||||
M10 收口糖(可选) stats 薄 · log 字段 · (zip 默认跳过)
|
||||
```
|
||||
|
||||
原则:
|
||||
|
||||
1. 继承 Mid1 宪法:通用、难写对、小宿主、可冻 API。
|
||||
2. **TOML 优先于 YAML**(对齐 PEP 680 教训)。
|
||||
3. 不阻塞宿主 / ext 产品线;但新「通用」ABI 插件默认拒绝。
|
||||
|
||||
---
|
||||
|
||||
## 1. 波次明细
|
||||
|
||||
### M7 — datetime + url — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/datetime` · `日期时间` | now/parse/format/add/unix/zone 子集 |
|
||||
| `lib/url` · `地址` | parse · query_parse/stringify(手写;无 `url` crate) |
|
||||
| Host | `host_datetime_*` · `host_url_*` |
|
||||
| 金样 | `tests/lib/datetime-smoke` · `url-smoke`(中英) |
|
||||
| public | `14-datetime-url` · `14-日期时间地址` |
|
||||
| 设计 | [stdlib-datetime.md](../design/stdlib-datetime.md) · [stdlib-url.md](../design/stdlib-url.md) |
|
||||
|
||||
### M8 — toml + html + encoding — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/toml` · `配置表` | 只读子集 `parse` |
|
||||
| `lib/html` · `超文本` | `escape` / `unescape` |
|
||||
| `encoding` base32 | RFC 4648 |
|
||||
| 金样 | `toml-html-encoding-smoke`(中英) |
|
||||
| public | `15-toml-html-encoding` · `15-配置表超文本编码` |
|
||||
| 设计 | [stdlib-toml.md](../design/stdlib-toml.md) · [stdlib-html.md](../design/stdlib-html.md) |
|
||||
|
||||
### M9 — fs 加厚 — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `make_dirs` / `remove_tree` / `stat` / `walk` | 见 [stdlib-fs-mid2.md](../design/stdlib-fs-mid2.md) |
|
||||
| 金样 | `fs-mid2-smoke`(中英) |
|
||||
| public | `16-fs-mid2` · `16-文件mid2` |
|
||||
|
||||
### M10 — 可选收口 — **done**(zip 跳过)
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/stats` · `统计` | mean / median / sample stdev |
|
||||
| `log` `fields=` | 行尾 `key=val` |
|
||||
| zip | **跳过** |
|
||||
| 金样 | `stats-log-smoke`(中英) |
|
||||
| public | `17-stats-log` · `17-统计日志` |
|
||||
| 设计 | [stdlib-stats-log.md](../design/stdlib-stats-log.md) |
|
||||
|
||||
---
|
||||
|
||||
## 2. 进度勾选
|
||||
|
||||
- [x] M7 datetime + url
|
||||
- [x] M8 toml + html + base32
|
||||
- [x] M9 fs 加厚
|
||||
- [x] M10 可选(zip 跳过)
|
||||
- [x] 研究文高优先级缺口 → closed(M7–M9;M10 为收口糖)
|
||||
- [x] `stdlib-modules.md` / `stdlib.md` 状态同步
|
||||
|
||||
---
|
||||
|
||||
## 3. 成功标准
|
||||
|
||||
对外可宣称:在 Mid1(文本/路径/哈希/CSV/CLI/日志)之上,**日历、URL、TOML 配置、HTML 转义、实用 fs** 无需外联即可完成常见脚本与 catalog 工具——领域能力仍在 `ext/`。
|
||||
@@ -167,9 +167,12 @@
|
||||
|
||||
---
|
||||
|
||||
## 4. 脚注取元(提案)
|
||||
## 4. 脚注取元(历史 · 过渡保留)
|
||||
|
||||
### 4.1 为何用脚注外形
|
||||
> **主语法已切换为链接形** `[键](集合)`,见 [collection-access-link.md](../design/collection-access-link.md)。
|
||||
> 本节 `` 集合[^键] `` 仍由运行时接受;**新代码请写链接形**。
|
||||
|
||||
### 4.1 为何曾用脚注外形
|
||||
|
||||
- Markdown 已有 `[^…]` 引用形态,读者不陌生。
|
||||
- 避免 `篮子[0]` 与链接 / 图片语法纠缠。
|
||||
|
||||
@@ -13,7 +13,7 @@
|
||||
| 传统语言 | Marqdo |
|
||||
|----------|--------|
|
||||
| 代码在 `.py`,文档在 `.md` | 代码与文档同在 `.mq.md` |
|
||||
| `def` / `if` / `for` / `return` 是关键字 | 用 Markdown 标记 `##` / `1.` / `-` / `**…**` 表达 |
|
||||
| `def` / `if` / `for` / `return` 是关键字 | 用 Markdown 标记 `##` / `1.` / `-` / `**代码**` / `*返回*` 表达 |
|
||||
| 注释用 `#` 或 `//` | **无标记的叙述就是注释** |
|
||||
| 大括号 `{}` 或缩进界定代码块 | 标题层级 `#` / `##` 界定作用域 |
|
||||
|
||||
|
||||
+15
-15
@@ -6,8 +6,8 @@
|
||||
|
||||
1. **Frontmatter**(可选):文件开头的成对 `---` 之间的元信息,如标题、导入。
|
||||
2. **对象 / 函数定义**:以 `#` / `##` 开头的标题。
|
||||
3. **叙述注释**:无标记的普通文字段落。
|
||||
4. **可执行语句**:以标记开头的行。
|
||||
3. **叙述注释**:无标记的普通文字段落(可含 `` `名` `` 声明/引用)。
|
||||
4. **可执行语句**:粗体代码、独立调用行、标题下的结构行等。
|
||||
|
||||
```markdown
|
||||
---
|
||||
@@ -34,7 +34,7 @@ Marqdo 的注释规则很特别:**无标记的叙述就是注释**,靠空行
|
||||
# main
|
||||
|
||||
这段注释里有一行看起来像代码,但它不会执行:
|
||||
*not_executed = 1*
|
||||
**not_executed = 1**
|
||||
> print text=这也是注释
|
||||
|
||||
空行之后,代码开始运行:
|
||||
@@ -44,22 +44,22 @@ Marqdo 的注释规则很特别:**无标记的叙述就是注释**,靠空行
|
||||
|
||||
> **注意**:叙述与可执行代码之间**必须空一行**。忘记空行会让本意是注释的文字被当作代码,或让代码被吞进注释段。
|
||||
|
||||
## 2.3 标记一览表
|
||||
|
||||
以下标记表示「这是代码」:
|
||||
## 2.3 标记一览表(markup v0.3)
|
||||
|
||||
| 标记 | 含义 |
|
||||
|------|------|
|
||||
| `#` | 对象 / 类型(`# main` = 入口) |
|
||||
| `##` … `######` | 函数 / 方法(嵌套按标题深度) |
|
||||
| `` + `名` `` | 函数标题下的形参 |
|
||||
| `` + `名` `` | 函数标题下的形参(亦可由正文 `` `名` `` 推断) |
|
||||
| `1.` `2.` … | 条件分支 |
|
||||
| `-` | 循环(遍历或 while) |
|
||||
| `> 函数 参数` | 调用 |
|
||||
| `*…*` | 程序语句(赋值 / 表达式) |
|
||||
| `**…**` | 返回值 |
|
||||
| `> 函数 参数` | 调用(可选;粗体内可不写 `>`) |
|
||||
| `修饰 [函数] 实参` | 方括号标记调用(前导词 → `名=True`) |
|
||||
| `**…**` | **代码**(赋值 / 调用) |
|
||||
| `*…*` | **返回值** |
|
||||
| `|` 开头的 GFM 表格 | 集合(列表 / 字典) |
|
||||
| `---` / `***`(函数体内) | 结束函数体 |
|
||||
| `[键](集合)` | 链接取元 |
|
||||
| 单独一行 `---` / `***` | Markdown 分隔线(跳过,**不**结束函数体) |
|
||||
|
||||
## 2.4 标识符与反引号
|
||||
|
||||
@@ -75,7 +75,7 @@ Marqdo 中,**变量、参数名用反引号 `` ` `` 包裹**,这与 Markdown
|
||||
- `+ `谁`` —— 声明形参 `谁`
|
||||
- `> print text=Hello, `谁`!` —— 在字符串中引用变量 `谁`
|
||||
|
||||
> **注意**:反引号规则有例外。在 `*…*`(斜体语句)和 `**…**`(粗体返回)内部,**裸标识符就是变量**,反引号可以省略(详见 [第 3 章](./03-变量与赋值.md))。
|
||||
> **注意**:在 `**…**`(粗体代码)和 `*…*`(斜体返回)内部,**裸标识符就是变量**,反引号可以省略(详见 [第 3 章](./03-变量与赋值.md))。
|
||||
|
||||
## 2.5 字面量
|
||||
|
||||
@@ -98,7 +98,7 @@ Marqdo 的字面量:
|
||||
|
||||
```markdown
|
||||
> print text=Hello World! # 裸 token,按字面量
|
||||
*msg = "Hello, `name`!\n"* # 字符串,可插值、可转义
|
||||
**msg = "Hello, `name`!\n"** # 字符串,可插值、可转义
|
||||
```
|
||||
|
||||
## 2.6 关键字(不可作变量名)
|
||||
@@ -132,12 +132,12 @@ Marqdo 的字面量:
|
||||
|
||||
> print text=你好,`谁`!
|
||||
|
||||
---
|
||||
*None*
|
||||
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
*n + 1*
|
||||
```
|
||||
|
||||
运行输出:
|
||||
|
||||
+23
-23
@@ -2,34 +2,34 @@
|
||||
|
||||
## 3.1 什么是变量
|
||||
|
||||
变量是给数据起的一个名字。Marqdo 中,变量在**斜体语句 `*…*`** 中通过 `=` 绑定:
|
||||
变量是给数据起的一个名字。Marqdo 中,变量在**粗体代码 `**…**`** 中通过 `=` 绑定:
|
||||
|
||||
```markdown
|
||||
*x = 1*
|
||||
*name = "Marqdo"*
|
||||
*ok = True*
|
||||
**x = 1**
|
||||
**name = "Marqdo"**
|
||||
**ok = True**
|
||||
```
|
||||
|
||||
> **重要**:在 `*…*` / `**…**` 内部,**裸标识符就是变量**——不需要反引号。这是 Marqdo 的关键约定。
|
||||
> **重要**:在 `**…**` / `*…*` 内部,**裸标识符就是变量**——不需要反引号。这是 Marqdo 的关键约定。
|
||||
|
||||
## 3.2 绑定的三种写法
|
||||
|
||||
### 写法一:斜体语句 `*…*`(推荐)
|
||||
### 写法一:粗体代码 `**…**`(推荐)
|
||||
|
||||
```markdown
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
**x = 1**
|
||||
**y = x + 2**
|
||||
```
|
||||
|
||||
这是最常用的绑定方式。裸标识符就是变量。
|
||||
|
||||
### 写法二:行首反引号绑定(无 `*…*`)
|
||||
### 写法二:行首反引号绑定(无粗体)
|
||||
|
||||
```markdown
|
||||
`x` = 1
|
||||
```
|
||||
|
||||
不带 `*…*` 的绑定,变量名**需要反引号**。常用于绑定集合(表格)或公式:
|
||||
不带 `**…**` 的绑定,变量名**需要反引号**。常用于绑定集合(表格)或公式:
|
||||
|
||||
```markdown
|
||||
`篮子` =
|
||||
@@ -42,29 +42,29 @@
|
||||
### 写法三:绑定调用结果
|
||||
|
||||
```markdown
|
||||
*len_s = > len value="hello"*
|
||||
**len_s = > len value="hello"**
|
||||
```
|
||||
|
||||
`*…*` 内用 `= >` 表示「把调用结果赋给变量」。
|
||||
粗体内用 `= >` 表示「把调用结果赋给变量」;也可写成无 `>` 的调用形:`**len_s = len value="hello"**`。
|
||||
|
||||
## 3.3 引用变量
|
||||
|
||||
在 `*…*` 内部,直接写变量名即可:
|
||||
在 `**…**` / `*…*` 内部,直接写变量名即可:
|
||||
|
||||
```markdown
|
||||
*a = 5*
|
||||
*b = a * 2*
|
||||
**a = 5**
|
||||
**b = a * 2**
|
||||
> print text=`b` # 独立 > 调用中,变量要反引号
|
||||
```
|
||||
|
||||
> **关键区别**:在**独立 `>` 调用**(如 `> print …`)里,裸词是**文本**,所以引用变量要加反引号:`> print text=`b``。而在 `*…*` / `**…**` 内,裸词是**变量**:`*b = a * 2*`。
|
||||
> **关键区别**:在**独立 `>` 调用**(如 `> print …`)里,裸词是**文本**,所以引用变量要加反引号:`> print text=`b``。而在 `**…**` / `*…*` 内,裸词是**变量**:`**b = a * 2**`。
|
||||
|
||||
## 3.4 字符串与插值
|
||||
|
||||
### 双引号字符串
|
||||
|
||||
```markdown
|
||||
*msg = "Hello, World!"*
|
||||
**msg = "Hello, World!"**
|
||||
```
|
||||
|
||||
### 转义字符
|
||||
@@ -87,8 +87,8 @@
|
||||
字符串内用 `` `变量` `` 插值:
|
||||
|
||||
```markdown
|
||||
*name = "Marqdo"*
|
||||
*msg = "Hello, `name`!"*
|
||||
**name = "Marqdo"**
|
||||
**msg = "Hello, `name`!"**
|
||||
> print text=`msg` # 输出:Hello, Marqdo!
|
||||
```
|
||||
|
||||
@@ -97,14 +97,14 @@
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*name = "Alice"*
|
||||
*age = 30*
|
||||
*next_age = age + 1*
|
||||
**name = "Alice"**
|
||||
**age = 30**
|
||||
**next_age = age + 1**
|
||||
|
||||
> print text=名字:`name`
|
||||
> print text=明年:`next_age` 岁
|
||||
|
||||
*msg = "你好,`name`!你明年 `next_age` 岁。"*
|
||||
**msg = "你好,`name`!你明年 `next_age` 岁。"**
|
||||
> print text=`msg`
|
||||
```
|
||||
|
||||
|
||||
+12
-10
@@ -2,7 +2,7 @@
|
||||
|
||||
## 4.1 输出:`print` / `打印`
|
||||
|
||||
`print`(中文 `打印`)是内置函数,用于向标准输出写一行文本。**输出不是 `**粗体**`**——粗体是返回值,不是打印。
|
||||
`print`(中文 `打印`)是内置函数,用于向标准输出写一行文本。**输出不是粗体、也不是斜体**——粗体是代码,斜体是返回;打印是普通函数调用。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
@@ -20,19 +20,21 @@
|
||||
|------|------|------|
|
||||
| `> print text=…` | `> 打印 内容=…` | `text` ≡ `内容` |
|
||||
|
||||
粗体内也可写:`**打印 内容="你好"**`(文本字面量须加引号)。
|
||||
|
||||
### 输出变量
|
||||
|
||||
独立 `>` 调用中,变量用反引号:
|
||||
|
||||
```markdown
|
||||
*x = 42*
|
||||
**x = 42**
|
||||
> print text=`x` # 输出:42
|
||||
```
|
||||
|
||||
### 输出拼接
|
||||
|
||||
```markdown
|
||||
*name = "Marqdo"*
|
||||
**name = "Marqdo"**
|
||||
> print text=欢迎使用 `name`!
|
||||
```
|
||||
|
||||
@@ -55,7 +57,7 @@
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*name = > input prompt="请输入名字:"*
|
||||
**name = > input prompt="请输入名字:"**
|
||||
> print text=你好,`name`!
|
||||
```
|
||||
|
||||
@@ -68,10 +70,10 @@
|
||||
|
||||
这是一个人机问答程序。
|
||||
|
||||
*name = > input prompt="你叫什么名字?\n"*
|
||||
**name = > input prompt="你叫什么名字?\n"**
|
||||
> print text=你好,`name`!
|
||||
|
||||
*age = > int value=`age_input`*
|
||||
**age = > int value=`age_input`**
|
||||
```
|
||||
|
||||
> **注意**:上面的示例为了展示 `int` 用法,`age_input` 尚未定义。实际中你需要先从 `input` 得到字符串,再用 `int` 转换。完整可运行版本:
|
||||
@@ -79,12 +81,12 @@
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*name = > input prompt="你叫什么名字?\n"*
|
||||
**name = > input prompt="你叫什么名字?\n"**
|
||||
> print text=你好,`name`!
|
||||
|
||||
*age_str = > input prompt="你几岁?\n"*
|
||||
*age = > int value=`age_str`*
|
||||
*next_age = age + 1*
|
||||
**age_str = > input prompt="你几岁?\n"**
|
||||
**age = > int value=`age_str`**
|
||||
**next_age = age + 1**
|
||||
> print text=`name`,你明年 `next_age` 岁。
|
||||
```
|
||||
|
||||
|
||||
+19
-19
@@ -2,16 +2,16 @@
|
||||
|
||||
## 5.1 算术运算符
|
||||
|
||||
在 `*…*` 表达式内部:
|
||||
在 `**…**` 表达式内部:
|
||||
|
||||
```markdown
|
||||
*a = 10*
|
||||
*b = 3*
|
||||
**a = 10**
|
||||
**b = 3**
|
||||
|
||||
*sum = a + b* # 13
|
||||
*diff = a - b* # 7
|
||||
*prod = a * b* # 30
|
||||
*quo = a / b* # 3.33…(浮点除法)
|
||||
**sum = a + b** # 13
|
||||
**diff = a - b** # 7
|
||||
**prod = a * b** # 30
|
||||
**quo = a / b** # 3.33…(浮点除法)
|
||||
```
|
||||
|
||||
| 运算符 | 含义 |
|
||||
@@ -28,13 +28,13 @@
|
||||
`+` 也可以拼接字符串:
|
||||
|
||||
```markdown
|
||||
*first = "Hello, "*
|
||||
*second = "World!"*
|
||||
*msg = first + second*
|
||||
**first = "Hello, "**
|
||||
**second = "World!"**
|
||||
**msg = first + second**
|
||||
> print text=`msg` # Hello, World!
|
||||
```
|
||||
|
||||
> 在 `*…*` 内变量是裸名;若拼接的是字符串字面量,要加引号。
|
||||
> 在 `**…**` 内变量是裸名;若拼接的是字符串字面量,要加引号。
|
||||
|
||||
## 5.3 比较运算符
|
||||
|
||||
@@ -47,7 +47,7 @@
|
||||
| `<=` | 小于等于 |
|
||||
|
||||
```markdown
|
||||
*n = 5*
|
||||
**n = 5**
|
||||
|
||||
1. `n` > 3
|
||||
> print text=大于 3
|
||||
@@ -64,8 +64,8 @@
|
||||
| `not` | `非` | 逻辑非 |
|
||||
|
||||
```markdown
|
||||
*age = 20*
|
||||
*has_id = True*
|
||||
**age = 20**
|
||||
**has_id = True**
|
||||
|
||||
1. `age` >= 18 and `has_id`
|
||||
> print text=可以进入
|
||||
@@ -78,7 +78,7 @@
|
||||
布尔值字面量:`True` / `False`(中文 `真` / `假`)。
|
||||
|
||||
```markdown
|
||||
*is_admin = False*
|
||||
**is_admin = False**
|
||||
|
||||
1. `is_admin` == True
|
||||
> print text=管理员
|
||||
@@ -89,7 +89,7 @@
|
||||
也可以直接用布尔变量作条件:
|
||||
|
||||
```markdown
|
||||
*flag = True*
|
||||
**flag = True**
|
||||
|
||||
1. `flag`
|
||||
> print text=为真
|
||||
@@ -102,9 +102,9 @@
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*score = 85*
|
||||
*passed = score >= 60*
|
||||
*bonus = passed and score >= 80*
|
||||
**score = 85**
|
||||
**passed = score >= 60**
|
||||
**bonus = passed and score >= 80**
|
||||
|
||||
> print text=及格:`passed`
|
||||
> print text=优秀:`bonus`
|
||||
|
||||
+33
-21
@@ -8,18 +8,18 @@
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
*n + 1*
|
||||
```
|
||||
|
||||
- `## 加一` —— 函数名
|
||||
- `+ `n`` —— 参数
|
||||
- `**n + 1**` —— 返回值(**粗体 = 返回**)
|
||||
- `*n + 1*` —— 返回值(**斜体 = 返回**)
|
||||
|
||||
函数可以挂在 `# main` 之下作为嵌套函数,也可以作为顶层自由函数。
|
||||
|
||||
## 6.2 调用函数
|
||||
|
||||
使用 `>` 调用(具名参数或位置参数):
|
||||
使用 `>` 或粗体内调用(具名参数或位置参数):
|
||||
|
||||
```markdown
|
||||
# main
|
||||
@@ -32,7 +32,7 @@
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
*None*
|
||||
```
|
||||
|
||||
### 具名 vs 位置
|
||||
@@ -46,6 +46,17 @@
|
||||
|
||||
> 具名实参的值可以含空格,直到下一个 `名=` 边界;位置实参是单个词法单元(不含空格)。
|
||||
|
||||
### 方括号标记调用
|
||||
|
||||
可用 `[函数名]` 标出被调函数;`[` 前的裸词会变成布尔修饰(`名=True`):
|
||||
|
||||
```markdown
|
||||
> 问候 谁=小明 礼貌=True
|
||||
礼貌 [问候] 小明
|
||||
```
|
||||
|
||||
`]` 后**紧邻** `(` 是链接取元,不是调用(见[第 9 章](./09-集合.md))。
|
||||
|
||||
## 6.3 参数与默认值
|
||||
|
||||
可选参数用 `=默认值`:
|
||||
@@ -66,17 +77,18 @@
|
||||
```markdown
|
||||
> 问候 谁=小明
|
||||
> 问候 谁=小明 礼貌=True
|
||||
礼貌 [问候] 小明
|
||||
```
|
||||
|
||||
## 6.4 返回值:`**…**`
|
||||
## 6.4 返回值:`*…*`
|
||||
|
||||
用 `**…**` 返回表达式结果:
|
||||
用 `*…*` 返回表达式结果:
|
||||
|
||||
```markdown
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
*n + 1*
|
||||
```
|
||||
|
||||
调用并绑定结果:
|
||||
@@ -84,19 +96,19 @@
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*b = > 加一 n=1*
|
||||
**b = > 加一 n=1**
|
||||
> print text=`b` # 2
|
||||
```
|
||||
|
||||
### 返回 None:`****`
|
||||
### 返回 None
|
||||
|
||||
`****`(或空粗体 `**` + 空白 + `**`)返回 `None` 并结束函数体:
|
||||
推荐 `*None*` / `*无*`;也可整行空粗体 `**` 或 `****`:
|
||||
|
||||
```markdown
|
||||
## 静默
|
||||
+ `x`
|
||||
|
||||
****
|
||||
*None*
|
||||
```
|
||||
|
||||
### 字符串返回
|
||||
@@ -105,12 +117,12 @@
|
||||
## 问候语
|
||||
+ `谁`
|
||||
|
||||
**"你好," + 谁 + "!"**
|
||||
*"你好," + 谁 + "!"*
|
||||
```
|
||||
|
||||
## 6.5 结束函数体:`---` / `***`
|
||||
## 6.5 结束函数体
|
||||
|
||||
对于**没有返回值、只有副作用**的函数,用单独一行 `---` 或 `***` 结束函数体,避免后续兄弟语句被吞掉:
|
||||
副作用函数用斜体返回收束,避免后续兄弟语句被吞进本函数:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
@@ -122,20 +134,20 @@
|
||||
|
||||
> print text=Hello, `谁`!
|
||||
|
||||
---
|
||||
*None*
|
||||
|
||||
## 下一个函数
|
||||
...
|
||||
```
|
||||
|
||||
> `---` 仅在**函数体顶层单独一行**时表示「结束本函数」;文件开头的成对 `---` 是 frontmatter,不会混淆。
|
||||
> 单独一行的 `---` / `***` 只是 Markdown 分隔线(跳过),**不再**表示结束函数体。文件开头的成对 `---` 仍是 frontmatter。
|
||||
|
||||
## 6.6 完整示例
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 问候 谁=Alice 礼貌=True
|
||||
礼貌 [问候] Alice
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
@@ -146,12 +158,12 @@
|
||||
2. *
|
||||
> print text=嗨,`谁`!
|
||||
|
||||
---
|
||||
*None*
|
||||
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
*n + 1*
|
||||
```
|
||||
|
||||
输出:
|
||||
@@ -172,13 +184,13 @@
|
||||
## 处理
|
||||
+ `名字`
|
||||
|
||||
*上 = > 大写 文本=`名字`*
|
||||
**上 = > 大写 文本=`名字`**
|
||||
> print text=`上`
|
||||
|
||||
### 大写
|
||||
+ `文本`
|
||||
|
||||
**> str `文本`**
|
||||
*> str `文本`*
|
||||
```
|
||||
|
||||
> 深度约定:`##` 是 `#` 的子级,`###` 是 `##` 的子级……按标题深度嵌套。
|
||||
|
||||
@@ -7,7 +7,7 @@ Marqdo 用**有序列表** `1.` `2.` `3.` … 表达条件分支:
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*n = 5*
|
||||
**n = 5**
|
||||
|
||||
1. `n` > 0
|
||||
> print text=正数
|
||||
@@ -32,7 +32,7 @@ Marqdo 用**有序列表** `1.` `2.` `3.` … 表达条件分支:
|
||||
在 `1.` 之后的任意臂上,**整行恰为 `*`** 表示 else:
|
||||
|
||||
```markdown
|
||||
*age = 15*
|
||||
**age = 15**
|
||||
|
||||
1. `age` >= 18
|
||||
> print text=成年
|
||||
@@ -43,7 +43,7 @@ Marqdo 用**有序列表** `1.` `2.` `3.` … 表达条件分支:
|
||||
## 7.3 布尔分支
|
||||
|
||||
```markdown
|
||||
*is_admin = False*
|
||||
**is_admin = False**
|
||||
|
||||
1. `is_admin`
|
||||
> print text=管理员
|
||||
@@ -54,7 +54,7 @@ Marqdo 用**有序列表** `1.` `2.` `3.` … 表达条件分支:
|
||||
## 7.4 多条件分支
|
||||
|
||||
```markdown
|
||||
*score = 85*
|
||||
**score = 85**
|
||||
|
||||
1. `score` >= 90
|
||||
> print text=优秀
|
||||
@@ -69,8 +69,8 @@ Marqdo 用**有序列表** `1.` `2.` `3.` … 表达条件分支:
|
||||
## 7.5 逻辑组合条件
|
||||
|
||||
```markdown
|
||||
*age = 25*
|
||||
*has_id = True*
|
||||
**age = 25**
|
||||
**has_id = True**
|
||||
|
||||
1. `age` >= 18 and `has_id`
|
||||
> print text=可以进入
|
||||
@@ -85,8 +85,8 @@ Marqdo 用**有序列表** `1.` `2.` `3.` … 表达条件分支:
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*a = True*
|
||||
*b = False*
|
||||
**a = True**
|
||||
**b = False**
|
||||
|
||||
1. `a`
|
||||
> print text=A 为真
|
||||
@@ -113,7 +113,7 @@ B 为假
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*score = 72*
|
||||
**score = 72**
|
||||
|
||||
1. `score` >= 90
|
||||
> print text=评级:A
|
||||
|
||||
@@ -61,7 +61,7 @@ Marqdo 用 `-`(无序列表)表达循环。遍历列表用 `- [项](集合)`
|
||||
黄瓜
|
||||
```
|
||||
|
||||
> 遍历字典遍历的是键;要取值,用脚注取元(见[第 9 章](./09-集合.md))。
|
||||
> 遍历字典遍历的是键;要取值,用链接取元 `[键](集合)`(见[第 9 章](./09-集合.md))。
|
||||
|
||||
## 8.3 while 循环:`- 条件`
|
||||
|
||||
@@ -70,11 +70,11 @@ Marqdo 用 `-`(无序列表)表达循环。遍历列表用 `- [项](集合)`
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*n = 3*
|
||||
**n = 3**
|
||||
|
||||
- `n` > 0
|
||||
> print text=`n`
|
||||
*n = n - 1*
|
||||
**n = n - 1**
|
||||
```
|
||||
|
||||
输出:
|
||||
@@ -85,7 +85,7 @@ Marqdo 用 `-`(无序列表)表达循环。遍历列表用 `- [项](集合)`
|
||||
1
|
||||
```
|
||||
|
||||
> 循环体内用 `*…*` 语句更新变量。
|
||||
> 循环体内用 `**…**` 语句更新变量。
|
||||
|
||||
## 8.4 嵌套循环
|
||||
|
||||
@@ -160,10 +160,10 @@ B2
|
||||
| 4 |
|
||||
| 5 |
|
||||
|
||||
*sum = 0*
|
||||
**sum = 0**
|
||||
|
||||
- [n](数字)
|
||||
*sum = sum + n*
|
||||
**sum = sum + n**
|
||||
|
||||
> print text=总和:`sum`
|
||||
```
|
||||
|
||||
+27
-26
@@ -14,7 +14,7 @@ Marqdo 用 **GFM 表格**直接构造数据集合。表格的**几何形状**决
|
||||
| 值 | 值 |
|
||||
```
|
||||
|
||||
表格绑定变量名**需要反引号**(不在 `*…*` 内)。
|
||||
表格绑定变量名**需要反引号**(不在粗体代码 `**…**` 内时)。
|
||||
|
||||
## 9.2 单列竖表 → 列表(List)
|
||||
|
||||
@@ -101,63 +101,64 @@ Marqdo 用 **GFM 表格**直接构造数据集合。表格的**几何形状**决
|
||||
| ≥2 列 + 0 行 | `Map`(键存在,值空列表) |
|
||||
| 首列 `@`/`行`/`row` | `List` of `Map`(行向记录) |
|
||||
|
||||
## 9.7 脚注取元:`[^…]`
|
||||
## 9.7 链接取元:`[键](集合)`
|
||||
|
||||
用 Markdown 脚注外形从集合取元素(**表达式级**,可链式)。
|
||||
主语法与 foreach 同形:**方括号 = 取出的名字,圆括号 = 从哪取**(见 [collection-access-link.md](../design/collection-access-link.md))。
|
||||
|
||||
### 从列表按下标取
|
||||
|
||||
**下标是 1-based**(与人类读表一致):
|
||||
|
||||
```markdown
|
||||
*第一 = 篮子[^1]*
|
||||
> print text=`第一` # 苹果
|
||||
**第一 = [1](篮子)**
|
||||
**打印 内容=`第一`**
|
||||
```
|
||||
|
||||
### 从字典按键取
|
||||
|
||||
```markdown
|
||||
*种 = 分类[^苹果]*
|
||||
> print text=`种` # 水果
|
||||
**种 = [苹果](分类)**
|
||||
**打印 内容=`种`**
|
||||
```
|
||||
|
||||
### 动态键
|
||||
|
||||
```markdown
|
||||
**名 = "拿铁"**
|
||||
**价 = [`名`](菜单)**
|
||||
```
|
||||
|
||||
### 嵌套取元
|
||||
|
||||
```markdown
|
||||
*第一种苹果 = 货架[^苹果][^1]* # 先键,再下标 → 红富士
|
||||
```
|
||||
|
||||
### 基名的反引号
|
||||
|
||||
`` 名[^键] `` 与 `` `名`[^键] `` 等价(紧跟 `[^` 时可省略反引号):
|
||||
|
||||
```markdown
|
||||
*种 = `分类`[^苹果]*
|
||||
**第一种苹果 = [1]([苹果](货架))**
|
||||
```
|
||||
|
||||
### 插值中的取元
|
||||
|
||||
在**调用实参值 / 引号字符串**里,`` `变量` `` 后**紧跟**(无空白)`[^…]` 时也按取元解析,而不必先绑定再输出:
|
||||
在**调用实参值 / 引号字符串**里也可以写链接取元(或过渡期的脚注形):
|
||||
|
||||
```markdown
|
||||
> print text=苹果单价:`水果价格`[^苹果] # 输出:苹果单价:5
|
||||
> print text=第一种:`货架`[^苹果][^1] # 链式取元 → 红富士
|
||||
> print text="价 `水果价格`[^香蕉] 元" # 引号字符串内也可取元 → 价 3 元
|
||||
> print text=苹果单价:[苹果](`水果价格`)
|
||||
> print text=第一种:[1]([苹果](`货架`))
|
||||
```
|
||||
|
||||
> 规则:`` `变量` [^…] ``(**有空白**)时 `[^…]` 仍是普通文本;只有 `` `变量`[^…] ``(无空白)才算取元。
|
||||
### 过渡:脚注取元 `` 集合[^键] ``
|
||||
|
||||
旧写法 `` 分类[^苹果] `` / `` `分类`[^苹果] `` **仍可解析**;新代码与教程示例请用链接形。脚注兼容金样见 `tests/structure/footnote*`。
|
||||
|
||||
> 规则:
|
||||
> - **List**:标签须为纯数字(1-based);`[^0]` 或越界 → 报错。
|
||||
> - **Map**:标签为键文本(含纯数字键,如 `[^00]`);缺键 → 报错。
|
||||
> - **List**:键须为纯数字(1-based);`[0](…)` 或越界 → 报错。
|
||||
> - **Map**:键为键文本;缺键 → 报错。
|
||||
> - 文末的 `[^1]: …` 定义块仍是注释,与取元无关。
|
||||
> - `]` 后**紧邻** `(` 才是取元;否则 `[名字]` 可能是[方括号标记调用](../design/bracket-call-modifiers.md)。
|
||||
|
||||
## 9.8 表格单元格是表达式
|
||||
|
||||
数据单元格支持表达式(与调用实参值语法相同):裸词、数字、`` `var` ``、算术、引号串。URL / `gpt-4o-mini` 等按路径/连字符折叠为文本。
|
||||
|
||||
```markdown
|
||||
*k = "secret"*
|
||||
**k = "secret"**
|
||||
|
||||
`cfg` =
|
||||
|
||||
@@ -177,7 +178,7 @@ Marqdo 用 **GFM 表格**直接构造数据集合。表格的**几何形状**决
|
||||
|------|------|
|
||||
| 5 | 3 |
|
||||
|
||||
> print text=苹果单价:`水果价格`[^苹果]
|
||||
**打印 内容="苹果单价:" + [苹果](水果价格)**
|
||||
|
||||
`购物单` =
|
||||
|
||||
@@ -187,7 +188,7 @@ Marqdo 用 **GFM 表格**直接构造数据集合。表格的**几何形状**决
|
||||
| 2 | 香蕉 | 3 |
|
||||
|
||||
- [行](购物单)
|
||||
> print text=`行`[^品名] × `行`[^数量]
|
||||
**打印 内容=[品名](行) + " × " + [数量](行)**
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
+45
-45
@@ -10,13 +10,13 @@ Marqdo 用 `#` 标题定义**对象 / 类型**,用 `##` 定义其下的**方
|
||||
# 大模型
|
||||
+ `模型名`
|
||||
|
||||
*配置 = > json.parse text={"model":"gpt-4o-mini"}*
|
||||
**配置**
|
||||
**配置 = > json.parse text={"model":"gpt-4o-mini"}**
|
||||
*配置*
|
||||
```
|
||||
|
||||
- `# 大模型` —— 类型名
|
||||
- `+ `模型名`` —— 构造参数
|
||||
- 构造体执行后 `**…**` 返回一个 map,运行时写入 `_type` 字段,形成实例句柄
|
||||
- 构造体执行后 `*…*` 返回一个 map,运行时写入 `_type` 字段,形成实例句柄
|
||||
|
||||
## 10.2 构造实例
|
||||
|
||||
@@ -25,27 +25,27 @@ Marqdo 用 `#` 标题定义**对象 / 类型**,用 `##` 定义其下的**方
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*模型 = > 大模型 模型名="gpt-4o-mini"*
|
||||
**模型 = > 大模型 模型名="gpt-4o-mini"**
|
||||
```
|
||||
|
||||
## 10.3 定义方法
|
||||
|
||||
对象下的 `##` 标题是方法:
|
||||
对象下的 `##` 标题是方法。读字段优先用链接取元;写字段可用 `json.set` / `table.put`(跨边界序列化时再用 `json.*`):
|
||||
|
||||
```markdown
|
||||
# 计数器
|
||||
+ `初始值`
|
||||
|
||||
*状态 = > json.parse text={"n":0}*
|
||||
*状态 = > json.set map=`状态` key="n" value=`初始值`*
|
||||
**状态**
|
||||
**状态 = > json.parse text={"n":0}**
|
||||
**状态 = > json.set map=`状态` key="n" value=`初始值`**
|
||||
*状态*
|
||||
|
||||
## 加一
|
||||
|
||||
*n = > json.get value=`self` key="n"*
|
||||
*n2 = n + 1*
|
||||
*t = > json.set map=`self` key="n" value=`n2`*
|
||||
**t**
|
||||
**n = [n](self)**
|
||||
**n2 = n + 1**
|
||||
**t = > json.set map=`self` key="n" value=`n2`**
|
||||
*t*
|
||||
```
|
||||
|
||||
方法体内自动绑定:
|
||||
@@ -60,18 +60,18 @@ Marqdo 用 `#` 标题定义**对象 / 类型**,用 `##` 定义其下的**方
|
||||
### 独立 `>` 调用(接收者加反引号)
|
||||
|
||||
```markdown
|
||||
*计数器 = > 计数器 初始值=3*
|
||||
*新值 = > `计数器`.加一*
|
||||
**计数器 = > 计数器 初始值=3**
|
||||
**新值 = > `计数器`.加一**
|
||||
```
|
||||
|
||||
### `*…*` 段内调用(接收者裸名)
|
||||
### 粗体代码段内调用(接收者裸名)
|
||||
|
||||
```markdown
|
||||
*计数器 = > 计数器 初始值=3*
|
||||
*新值 = > 计数器.加一*
|
||||
**计数器 = > 计数器 初始值=3**
|
||||
**新值 = > 计数器.加一**
|
||||
```
|
||||
|
||||
> **重要**:在 `*…*` / `**…**` 段内,裸词是变量,所以**方法接收者不加反引号**:`*新值 = > 计数器.加一*`。而在独立 `>` 调用中,裸词是文本,接收者需要反引号:`> `计数器`.加一`。
|
||||
> **重要**:在 `**…**` / `*…*` 段内,裸词是变量,所以**方法接收者不加反引号**:`**新值 = > 计数器.加一**`。而在独立 `>` 调用中,裸词是文本,接收者需要反引号:`` > `计数器`.加一 ``。
|
||||
|
||||
## 10.5 完整对象示例
|
||||
|
||||
@@ -84,27 +84,27 @@ import json:lib/json.mq.md
|
||||
|
||||
# main
|
||||
|
||||
*c = > 计数器 初始值=5*
|
||||
*ty = > json.get value=`c` key="_type"*
|
||||
**c = > 计数器 初始值=5**
|
||||
**ty = [_type](c)**
|
||||
> print text=类型:`ty`
|
||||
|
||||
*c2 = > c.加一*
|
||||
*n = > json.get value=`c2` key="n"*
|
||||
**c2 = > c.加一**
|
||||
**n = [n](c2)**
|
||||
> print text=加一后:`n`
|
||||
|
||||
# 计数器
|
||||
+ `初始值`
|
||||
|
||||
*状态 = > json.parse text={"n":0}*
|
||||
*状态 = > json.set map=`状态` key="n" value=`初始值`*
|
||||
**状态**
|
||||
**状态 = > json.parse text={"n":0}**
|
||||
**状态 = > json.set map=`状态` key="n" value=`初始值`**
|
||||
*状态*
|
||||
|
||||
## 加一
|
||||
|
||||
*n = > json.get value=`self` key="n"*
|
||||
*n2 = n + 1*
|
||||
*t = > json.set map=`self` key="n" value=`n2`*
|
||||
**t**
|
||||
**n = [n](self)**
|
||||
**n2 = n + 1**
|
||||
**t = > json.set map=`self` key="n" value=`n2`**
|
||||
*t*
|
||||
```
|
||||
|
||||
输出:
|
||||
@@ -122,16 +122,16 @@ import json:lib/json.mq.md
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*msg = "Hello, `who`!"*
|
||||
**msg**
|
||||
**msg = "Hello, `who`!"**
|
||||
*msg*
|
||||
|
||||
# Loud = > Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*msg = "HELLO, `who`!"*
|
||||
**msg**
|
||||
**msg = "HELLO, `who`!"**
|
||||
*msg*
|
||||
```
|
||||
|
||||
规则:
|
||||
@@ -152,9 +152,9 @@ import json:lib/json.mq.md
|
||||
# Child = > Parent
|
||||
+ `name`
|
||||
|
||||
*self = > Parent name=`name`*
|
||||
*self = > json.set map=`self` key="role" value="child"*
|
||||
**self**
|
||||
**self = > Parent name=`name`**
|
||||
**self = > json.set map=`self` key="role" value="child"**
|
||||
*self*
|
||||
```
|
||||
|
||||
## 10.7 完整继承示例
|
||||
@@ -162,25 +162,25 @@ import json:lib/json.mq.md
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*c = > Child name="Ada"*
|
||||
*ty = > json.get value=`c` key="_type"*
|
||||
*role = > json.get value=`c` key="role"*
|
||||
**c = > Child name="Ada"**
|
||||
**ty = [_type](c)**
|
||||
**role = [role](c)**
|
||||
> print text=`ty`
|
||||
> print text=`role`
|
||||
|
||||
# Parent
|
||||
+ `name`
|
||||
|
||||
*out = > json.parse text={"role":"parent"}*
|
||||
*out = > json.set map=`out` key="name" value=`name`*
|
||||
**out**
|
||||
**out = > json.parse text={"role":"parent"}**
|
||||
**out = > json.set map=`out` key="name" value=`name`**
|
||||
*out*
|
||||
|
||||
# Child = > Parent
|
||||
+ `name`
|
||||
|
||||
*self = > Parent name=`name`*
|
||||
*self = > json.set map=`self` key="role" value="child"*
|
||||
**self**
|
||||
**self = > Parent name=`name`**
|
||||
**self = > json.set map=`self` key="role" value="child"**
|
||||
*self*
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
Loaded 100 of 763 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user