Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
5272acaea0 | ||
|
|
cba51238b6 | ||
|
|
5fffb800f9 | ||
|
|
1a729eb9ec | ||
|
|
00c763300e | ||
|
|
224b3d4a66 | ||
|
|
81d26a265a | ||
|
|
5b599125d1 | ||
|
|
18d89d6cf2 | ||
|
|
199b5c532f | ||
|
|
db5f0e830b | ||
|
|
7a449c40b1 | ||
|
|
97fda7aa10 | ||
|
|
a49592a3ba | ||
|
|
ed9ac03c0c | ||
|
|
cb46ad7abe | ||
|
|
586975090b | ||
|
|
544805266b | ||
|
|
f3051fb536 | ||
|
|
86b183e2d7 | ||
|
|
8e23a5395a | ||
|
|
cab609ee91 | ||
|
|
b752cd49b7 | ||
|
|
2c91b5cc7b | ||
|
|
453321c8c2 | ||
|
|
981d754133 | ||
|
|
410f36f719 | ||
|
|
bd06aedb90 | ||
|
|
42ddeb14e7 | ||
|
|
6bd127a313 | ||
|
|
4b7643d833 | ||
|
|
3f96592c99 | ||
|
|
98018fc63b | ||
|
|
aeac4d6d20 | ||
|
|
9e9a80df31 | ||
|
|
5f07b1c3b1 | ||
|
|
bfea2204eb | ||
|
|
fb30cd3db3 | ||
|
|
584cb9ac9d | ||
|
|
428ee141e1 | ||
|
|
ec9718466d | ||
|
|
c5bb08022a | ||
|
|
b710745e88 | ||
|
|
5cf84fe9b7 | ||
|
|
27991a7822 | ||
|
|
d1e2f0ced0 | ||
|
|
e848306187 | ||
|
|
2ee9d7e66d | ||
|
|
e31585842d | ||
|
|
f068b4ab75 | ||
|
|
26e29409a9 | ||
|
|
4923129d10 | ||
|
|
8ab55e2193 | ||
|
|
9bc7ef3b5a | ||
|
|
9431ad835c | ||
|
|
2984d7d4f8 | ||
|
|
6324036e41 | ||
|
|
3287799959 | ||
|
|
f95e5d3339 | ||
|
|
52b4bae423 | ||
|
|
037592087c |
No files matched your search
@@ -150,3 +150,18 @@ When editing a file full of `json.set`:
|
||||
- Tables: `doc/design/stdlib-table.md` · `doc/design/table-cell-expressions.md`
|
||||
- Browser effects: `doc/roadmap/browser-wasm-e.md` · `doc/roadmap/browser-wasm-f.md`
|
||||
- Release: [marqdo-release](../marqdo-release/SKILL.md)
|
||||
|
||||
## 渐进式契约 + MLSP(Phase 2/3 落地后的开发戒律)
|
||||
|
||||
- **契约实现**:`src/contract.rs`(类型词汇 / 三形状契约表解析 / 合并 / 四边界校验诊断);
|
||||
`src/parse/mod.rs::extract_function_contract`(位置 + 形状双重判定,**在升参推断之前**执行;
|
||||
绑定表与普通文档表绝不吃 ⇒ 无契约文件零回归)。契约表从 body 移除——元数据永不执行。
|
||||
- **静态互查**:`src/check.rs`(`marqdo check [--json]`)——契约行 vs 升参推断形参双向漂移、
|
||||
未知类型名、错位契约;Error ⇒ 非零退出。
|
||||
- **AI 工具面**:`src/mlsp.rs`(`marqdo mlsp`,行分隔 JSON)——`locate` / `syntax` / `validate` /
|
||||
`repair_targets` / `schema`。语法唯一事实来源 = `parse::CORE_CONSTRUCTS`(CI 守卫与
|
||||
`doc/design/core-surface.md` 同步);MLSP 只加检索别名,**不定义语法**。
|
||||
- **准入戒律**:新特性先过 `doc/design/layers.md` 三层归属(Language 层改动须 ADR + core-surface);
|
||||
新契约形状/类型词汇 = 文档层扩展,进 `src/contract.rs`,不进词法/语法。
|
||||
- **错误出口唯一**:`src/load.rs::label_error` 已示范——装载层/任何新代码都**不许**把
|
||||
`Diagnostic` 拍平成字符串;错误链里必须能 `Diagnostic::find` 找回结构化诊断(AI/MLSP 面)。
|
||||
@@ -1,16 +1,14 @@
|
||||
---
|
||||
name: marqdo-release
|
||||
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 (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.
|
||||
Run a Marqdo product release: detect latest version and ask the user for the
|
||||
next tag (or confirm mode), update CHANGELOG/README/skills/public docs, bump
|
||||
Cargo and/or ext/VERSION, sync VS Code extension when needed, publish GitHub
|
||||
Release assets, upload extension packs to Cloudflare R2 (ext.marqdo.com) and
|
||||
GitHub, ship Ubuntu CLI via PPA (scripts/ppa-ship.sh), and print manual
|
||||
commands when sudo/GPG/network steps need the user. Use when the user asks to
|
||||
release, cut a version, publish vX.Y.Z, ext-only pack, PPA, 发版, 发布新版本,
|
||||
or tag marqdo.
|
||||
---
|
||||
|
||||
# Marqdo release
|
||||
@@ -19,166 +17,193 @@ Canonical release playbook for **cflmy/marqdo**. Read this skill **before** tagg
|
||||
|
||||
## Hard rules
|
||||
|
||||
1. **Never invent the next version.** Detect current versions → **stop and ask the user** for the next SemVer (`X.Y.Z`). Do not proceed until they confirm.
|
||||
1. **Never invent the next version.** Detect current versions → **stop and ask the user** for the next SemVer (`X.Y.Z`) and **release mode** if unclear. Do not proceed until they confirm (unless they already stated both in the same message).
|
||||
2. **Never force-push** `main` / tags. **Never** `--no-verify` unless the user explicitly orders it.
|
||||
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 **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.
|
||||
5. **Tag format:** CLI/full → `vX.Y.Z` matching root `Cargo.toml`. Ext-only → `ext-vX.Y.Z` matching `ext/VERSION` (Cargo may stay unchanged).
|
||||
6. Prefer **tag push → GitHub Actions** (`.github/workflows/release.yml`) for Windows/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`. Retry; do not silently skip uploads. If needed: **HK jump** (`scripts/push-via-hk-jump.py`).
|
||||
8. **Do not ship a full GitHub Release without the Linux extension/native zip** when the mode includes ext packs. Missing Linux packages = incomplete for that mode.
|
||||
9. **Extension packs always publish to both** Cloudflare R2 (`https://ext.marqdo.com` via `scripts/upload-ext-r2.py`) **and** GitHub (Release assets / `ext-v*` tag). Credentials only in `~/.marqdo/r2.env` / CI — **never** commit. See [ext-cdn.md](../../../doc/design/ext-cdn.md).
|
||||
10. **CLI Ubuntu package = PPA** (`ppa:cflmy/marqdo`) via `./scripts/ppa-ship.sh` / `ppa-build-source.sh`. GitHub zips remain for Windows and non-apt Linux.
|
||||
11. **When a step needs the user** (sudo password, GPG passphrase, Launchpad UI, interactive `dput`): **stop, state what failed, and give the exact commands** to run in their terminal. Do not pretend the step succeeded.
|
||||
|
||||
## Defaults (after version is confirmed)
|
||||
## Release modes
|
||||
|
||||
Unless the user overrides, apply these automatically — **do not re-ask**:
|
||||
Ask (or take from user message) which mode:
|
||||
|
||||
| Mode | Bumps | Git tag | GitHub assets | R2 CDN | Ubuntu PPA |
|
||||
|------|-------|---------|---------------|--------|------------|
|
||||
| **full** (default) | `Cargo.toml` + `ext/VERSION` (same SemVer) | `vX.Y.Z` | CLI + ext + native + VSIX + … | yes | yes |
|
||||
| **cli** | `Cargo.toml` only | `vX.Y.Z` | CLI (+ optional attach prior ext) | no (unless user asks) | yes |
|
||||
| **ext** | `ext/VERSION` only | `ext-vX.Y.Z` (or attach to latest CLI release) | ext.zip + native-*.zip | **required** | no |
|
||||
|
||||
Defaults after version+mode confirmed — **do not re-ask**:
|
||||
|
||||
| Setting | Default |
|
||||
|---------|---------|
|
||||
| Sync / bump `vscode-extension` to same `VER` | **yes** |
|
||||
| Push `main`, create annotated tag, push tag immediately (trigger CI) | **yes** |
|
||||
| Release notes language | **中英双语** (Chinese first, then English section, or paired ZH/EN under each heading) |
|
||||
| Skip VSIX | **no** |
|
||||
| Docs-only release | **no** (full asset pipeline via CI) |
|
||||
| Sync / bump `vscode-extension` to same `VER` | **yes** for full/cli; **no** for ext-only |
|
||||
| Push `main`, create annotated tag, push tag (trigger CI) | **yes** for full/cli |
|
||||
| Ext packs → R2 **and** GitHub | **yes** whenever ext ships |
|
||||
| Ubuntu PPA upload after CLI tag | **yes** for full/cli |
|
||||
| Release notes language | **中英双语** |
|
||||
| Deploy gh-pages after release | **no** (only if user asks) |
|
||||
|
||||
Phase 0 asks **only** for the next version (and optional overrides). Example ask:
|
||||
Phase 0 ask example:
|
||||
|
||||
> 当前最新是 **vA.B.C**。请指定下一个版本号(如 `0.3.2`)。其余按默认:同步扩展、立刻打 tag 发布、中英双语说明。
|
||||
> 当前最新 CLI **vA.B.C**,扩展包 **E.F.G**。请指定下一个版本号与模式(`full` / `cli` / `ext`,如 `1.0.3 full`)。
|
||||
|
||||
## Phase 0 — Detect versions (mandatory stop)
|
||||
|
||||
Run in repo root (parallel OK):
|
||||
|
||||
```bash
|
||||
python3 .cursor/skills/marqdo-release/scripts/detect_version.py
|
||||
# or: rg / git tag / gh release list — see reference.md
|
||||
```
|
||||
|
||||
Report briefly, then **ask only for the next SemVer** (defaults above). Wait for confirmation. Normalize to `VER=X.Y.Z` and `TAG=vX.Y.Z`.
|
||||
Report briefly, then **ask for SemVer + mode** (unless already given). Normalize `VER` / `TAG`.
|
||||
|
||||
## Phase 1 — Preflight
|
||||
|
||||
Copy and track:
|
||||
|
||||
```
|
||||
Release progress:
|
||||
- [ ] Phase 0: version confirmed by user (TAG=…)
|
||||
- [ ] Phase 0: version + mode confirmed
|
||||
- [ ] Phase 1: preflight green
|
||||
- [ ] Phase 2: docs + version bumps committed
|
||||
- [ ] Phase 3: extension branch (if needed)
|
||||
- [ ] Phase 3: extension branch (full/cli)
|
||||
- [ ] Phase 4: main pushed; tag created & pushed
|
||||
- [ ] Phase 5: CI / assets / release notes verified
|
||||
- [ ] Phase 6: post-release checks
|
||||
- [ ] Phase 5: CI / GitHub assets / notes
|
||||
- [ ] Phase 6: R2 upload (if ext ships)
|
||||
- [ ] Phase 7: Ubuntu PPA (full/cli)
|
||||
- [ ] Phase 8: post-release checks
|
||||
```
|
||||
|
||||
Checks:
|
||||
|
||||
1. `git status` clean or only release WIP you control.
|
||||
2. `git checkout main && git pull --ff-only origin main`.
|
||||
3. Quick gate: `cargo test --test gold structure_hello` (and any release-critical tests the user named). Full gold suite if time allows.
|
||||
4. `CHANGELOG.md` has meaningful **Unreleased** notes; if empty, draft from `git log vLAST..HEAD --oneline` and confirm with user.
|
||||
5. Confirm no secrets in the commit (`*.env`, credentials).
|
||||
Checks: clean tree; `main` ff-only; smoke tests; CHANGELOG Unreleased; no secrets.
|
||||
|
||||
## Phase 2 — Docs & version bumps (main)
|
||||
|
||||
Bump **in lockstep**:
|
||||
|
||||
| File | Change |
|
||||
|------|--------|
|
||||
| `Cargo.toml` | `version = "VER"` |
|
||||
| `crates/marqdo-wasm/Cargo.toml` | same `VER` |
|
||||
| `CHANGELOG.md` | Move `## Unreleased` → `## vVER — YYYY-MM-DD`; leave fresh empty `## Unreleased` |
|
||||
| `README.md` | 「现状 / 如何使用最新」version strings, checkout tag, release URL |
|
||||
| `.cursor/skills/marqdo/SKILL.md` | Version-sensitive bullets if any (WASM/web status); keep rules accurate |
|
||||
| `public/**` | User-facing tutorials if features shipped (welcome, features/*, extensions). Prefer small factual updates over rewrites |
|
||||
| `doc/roadmap/*.md` | Mark shipped waves done if this release closes them |
|
||||
| `.github/workflows/release.yml` | Update **Highlights** body template to this release (CI still uses hardcoded blurb—keep in sync) |
|
||||
|
||||
Public HTML: regenerate before packaging / pages deploy:
|
||||
| File | full | cli | ext |
|
||||
|------|------|-----|-----|
|
||||
| `Cargo.toml` + `crates/marqdo-wasm/Cargo.toml` | bump | bump | — |
|
||||
| `ext/VERSION` | bump | — | bump |
|
||||
| `CHANGELOG.md` | `## vVER`(含**核心表面 Δ**,见 `doc/design/layers.md`) | same | `## Ext pack vVER` |
|
||||
| `README.md` / `public/**` install + download table | update | update | update ext notes |
|
||||
| `.cursor/skills/marqdo/SKILL.md` | if surface changed | same | rare |
|
||||
| `.github/workflows/release.yml` Highlights stub | yes | yes | — |
|
||||
|
||||
```bash
|
||||
./scripts/build-public.sh
|
||||
# outputs under public/ (gitignored HTML); used by release zip / gh-pages
|
||||
./scripts/build-public.sh # when public/ sources changed
|
||||
```
|
||||
|
||||
Commit on `main` (HEREDOC message), e.g.:
|
||||
|
||||
```text
|
||||
release: vVER — <one-line highlight>
|
||||
|
||||
EOF
|
||||
```
|
||||
|
||||
Push `main` (this repo’s `origin` is usually the reverse proxy):
|
||||
Commit + push `main` (proxy origin). On push failure → reference § Proxy; if still blocked, **print** for the user:
|
||||
|
||||
```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
|
||||
# or: python3 scripts/push-via-hk-jump.py
|
||||
```
|
||||
|
||||
If that times out: [reference § HK SSH jump](reference.md).
|
||||
## Phase 3 — VS Code / Cursor extension (full/cli only)
|
||||
|
||||
## Phase 3 — VS Code / Cursor extension
|
||||
Default: bump `vscode-extension` package.json to `VER`, compile, push branch `vscode-extension`, return to `main`.
|
||||
|
||||
**Default: always** bump extension to `VER` on branch `vscode-extension` (skip only if user said so).
|
||||
|
||||
1. `git fetch origin vscode-extension`
|
||||
2. Work on `vscode-extension` branch (not main):
|
||||
- Bump `vscode-extension/package.json` `version` to `VER`.
|
||||
- Update `engines` / CLI version hints in extension README if present.
|
||||
- `npm ci && npm run compile`
|
||||
3. Commit & `git push origin vscode-extension`.
|
||||
4. Return to `main`. **Do not** add `vscode-extension/` to main.
|
||||
|
||||
## Phase 4 — Tag & trigger CI
|
||||
## Phase 4 — Tag & trigger CI (full/cli)
|
||||
|
||||
```bash
|
||||
git tag -a "TAG" -m "TAG"
|
||||
git push origin "TAG"
|
||||
git tag -a "vVER" -m "vVER"
|
||||
git push origin "vVER"
|
||||
```
|
||||
|
||||
This runs `.github/workflows/release.yml`:
|
||||
Ext-only:
|
||||
|
||||
- **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`)
|
||||
```bash
|
||||
git tag -a "ext-vVER" -m "ext-vVER"
|
||||
git push origin "ext-vVER"
|
||||
```
|
||||
|
||||
If tag push fails: [reference.md § Proxy](reference.md) (`proxy.cflmy.top` first), retry once; then HK jump.
|
||||
(or build zips locally / via workflow and `gh release upload`).
|
||||
|
||||
## Phase 5 — Release notes & assets
|
||||
If tag push needs the user:
|
||||
|
||||
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. 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.
|
||||
```bash
|
||||
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git vVER
|
||||
```
|
||||
|
||||
Local Windows fallback: `scripts/release-full.ps1 -Tag TAG -Upload` (see script header).
|
||||
## Phase 5 — GitHub Release notes & assets
|
||||
|
||||
## Phase 6 — Post-release
|
||||
1. Wait for Actions (full/cli): both `windows` and `linux` green when ext natives required.
|
||||
2. Rewrite release body 中英双语 — [reference.md § Notes](reference.md).
|
||||
3. Confirm Linux `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` when mode ships ext.
|
||||
|
||||
1. `gh release view TAG` — confirm assets + notes.
|
||||
2. `git status` clean; `main` synced.
|
||||
3. Tell user: release URL `https://github.com/cflmy/marqdo/releases/tag/TAG`.
|
||||
4. Optional: `./scripts/deploy-public.ps1` / pages workflow if user wants user-site refresh.
|
||||
5. Open fresh `## Unreleased` already done in Phase 2.
|
||||
## Phase 6 — Extension CDN (R2) — required when ext ships
|
||||
|
||||
```bash
|
||||
# credentials: ~/.marqdo/r2.env (never commit)
|
||||
python3 scripts/upload-ext-r2.py --version VER --from-dir dist/
|
||||
curl -fsS https://ext.marqdo.com/latest/VERSION
|
||||
```
|
||||
|
||||
Also ensure the **same** zips are on GitHub (`vVER` or `ext-vVER`). If R2 credentials missing, **tell the user**:
|
||||
|
||||
```bash
|
||||
# put keys in ~/.marqdo/r2.env then:
|
||||
python3 scripts/upload-ext-r2.py --version VER --from-dir dist/
|
||||
```
|
||||
|
||||
## Phase 7 — Ubuntu PPA (full/cli)
|
||||
|
||||
Linux CLI for apt users. After `Cargo.toml` is at `VER` and `debian/changelog` has a matching `VER-1ppaN` stanza:
|
||||
|
||||
```bash
|
||||
./scripts/ppa-ship.sh noble
|
||||
```
|
||||
|
||||
Packaging notes / noble Cargo.lock v4: [ubuntu-ppa.md](../../../doc/design/ubuntu-ppa.md).
|
||||
|
||||
**If the agent cannot sudo / sign / dput**, print exactly:
|
||||
|
||||
```bash
|
||||
cd ~/work/marqdo
|
||||
./scripts/ppa-ship.sh noble
|
||||
# or build then upload:
|
||||
./scripts/ppa-build-source.sh noble
|
||||
dput ppa:cflmy/marqdo ../build-area/marqdo_*~noble_source.changes
|
||||
```
|
||||
|
||||
Watch: https://launchpad.net/~cflmy/+archive/ubuntu/marqdo/+builds
|
||||
On Launchpad failure: read the build log, fix `debian/` or bundle script, bump `1ppaN`, re-upload. Tell the user the new `dput` command.
|
||||
|
||||
## Phase 8 — Post-release
|
||||
|
||||
1. `gh release view TAG` — assets + notes.
|
||||
2. CDN `https://ext.marqdo.com/vVER/` (if ext shipped).
|
||||
3. PPA build green (if cli shipped).
|
||||
4. Tell user URLs: GitHub release, CDN, PPA install one-liner.
|
||||
5. Optional gh-pages only if asked.
|
||||
|
||||
## Extension-only release (mode=ext)
|
||||
|
||||
1. User confirms **ext** SemVer (may differ from CLI).
|
||||
2. Bump `ext/VERSION`; CHANGELOG → `## Ext pack vVER`.
|
||||
3. Build/package `marqdo-VER-ext.zip` + `marqdo-VER-native-*.zip` (CI or local).
|
||||
4. Upload to **R2 and GitHub** (required both).
|
||||
5. Do **not** retag CLI / do **not** PPA unless user also asked for cli.
|
||||
|
||||
## Failure matrix (short)
|
||||
|
||||
| Failure | Action |
|
||||
|---------|--------|
|
||||
| `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` |
|
||||
| Linux native/CLI zip missing | Incomplete release — fix `linux` job or `gh release upload`; do not skip |
|
||||
| `gh` / git TLS or Clash `7890` refused | Unset bad proxy; see [reference § Proxy](reference.md) |
|
||||
| GitHub blocked | proxy.cflmy.top, then HK jump; **print commands** if agent cannot push |
|
||||
| Tag exists | Stop; ask user |
|
||||
| CI red | Fix on main; retag only if user allows |
|
||||
| R2 upload fails | Print `upload-ext-r2.py` command; do not skip silently |
|
||||
| PPA / sudo / GPG | Print `./scripts/ppa-ship.sh noble` (or `dput …`); do not skip silently |
|
||||
| Launchpad `Cargo.lock` v4 / old cargo | Ensure bundled `third_party/rust` via current `ppa-build-source.sh`; bump `1ppaN` |
|
||||
| Linux native zip missing (full/ext) | Incomplete — fix linux job or upload |
|
||||
|
||||
## Do not
|
||||
|
||||
- Ship without user-confirmed version.
|
||||
- Hardcode release highlights only in Actions YAML and forget CHANGELOG.
|
||||
- Commit `target/`, `dist/`, `*.wasm`, or `public/**/*.html` unless project policy changes.
|
||||
- Ship without user-confirmed version (and mode when ambiguous).
|
||||
- Ship ext packs to only one of R2 / GitHub.
|
||||
- Call a full/cli release done without attempting PPA **or** giving the user the PPA commands.
|
||||
- Commit `target/`, `dist/`, `*.wasm`, `third_party/rust/`, or `public/**/*.html` unless policy changes.
|
||||
- Merge extension tree into `main`.
|
||||
@@ -236,7 +236,25 @@ 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).
|
||||
`gh` / Release API can use the same path reverse-proxy:
|
||||
|
||||
| Path prefix | Upstream |
|
||||
|-------------|----------|
|
||||
| `/github.com/` | `https://github.com/` |
|
||||
| `/api.github.com/` | `https://api.github.com/` |
|
||||
| `/uploads.github.com/` | `https://uploads.github.com/` (Release asset POST; OpenResty on HK) |
|
||||
|
||||
```bash
|
||||
# Upload a Release asset through proxy.cflmy.top (Content-Type: application/octet-stream)
|
||||
curl -X POST \
|
||||
-H "Authorization: Bearer $GH_TOKEN" \
|
||||
-H "Accept: application/vnd.github+json" \
|
||||
-H "Content-Type: application/octet-stream" \
|
||||
--data-binary @dist/FILE.zip \
|
||||
"https://proxy.cflmy.top/uploads.github.com/repos/cflmy/marqdo/releases/RELEASE_ID/assets?name=FILE.zip"
|
||||
```
|
||||
|
||||
Do **not** rewrite `Host: uploads.github.com` against `proxy.cflmy.top` without the `/uploads.github.com/` path prefix — that returns 404.
|
||||
|
||||
### Diagnose
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ Canonical design (repo): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-
|
||||
|
||||
**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/*`.
|
||||
|
||||
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number.
|
||||
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets, **ext → R2+GitHub**, **CLI → Ubuntu PPA**): use [marqdo-release](../marqdo-release/SKILL.md) — detect versions, **ask for SemVer + mode (`full` / `cli` / `ext`)**, then follow that playbook. Ext-only releases are allowed. If sudo/GPG/PPA steps need the user, print the exact commands.
|
||||
|
||||
## Hard rules (do not violate)
|
||||
|
||||
@@ -36,6 +36,62 @@ Canonical design (repo): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-
|
||||
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).
|
||||
|
||||
## 记不住语法细节?查 MLSP(AI 必读)
|
||||
|
||||
**不必背 Marqdo 语法细节**——语法可查、程序可验、修复有界。写码前后走**查询式**工作流:
|
||||
|
||||
```bash
|
||||
printf '%s\n' '{"id":1,"method":"syntax","params":{"query":"返回"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":2,"method":"locate","params":{"path":"a.mq.md","symbol":"加一"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":3,"method":"validate","params":{"path":"a.mq.md"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":4,"method":"schema","params":{"path":"a.mq.md","unit":"加一"}}' | marqdo mlsp
|
||||
printf '%s\n' '{"id":5,"method":"repair_targets","params":{"code":"contract.arg_mismatch","doc_anchor":"a.mq.md#L9-L15"}}' | marqdo mlsp
|
||||
```
|
||||
|
||||
| method | 何时用 |
|
||||
|--------|--------|
|
||||
| `syntax` | 不确定某个语法怎么写(关键字/别名 → 构造卡片:「返回」「表」「调用」「循环」…) |
|
||||
| `locate` | 找符号定义位置 + 契约;或反查构造卡片 |
|
||||
| `validate` | 提交前校验(结构化诊断数组;`ok:false` 就修) |
|
||||
| `schema` | 查单元契约(形参/返回/字段) |
|
||||
| `repair_targets` | 拿错误的**有界**修复靶点:只改锚点范围内行,越界必弃权(abstain) |
|
||||
|
||||
行分隔 JSON:每行请求 `{"id","method","params"}` → 每行响应 `{"id","ok","result"|"error"}`。
|
||||
语法唯一事实来源 = `doc/design/core-surface.md`(CI 守卫同步);卡片带 `manual` 指回文档行。
|
||||
所有错误诊断都是结构化 JSON:`code` / `severity` / `span` / `suggestion` / `doc_anchor` / `doc_quote` / `contract_ref`。
|
||||
|
||||
### 渐进式契约(可选标注;schema 就长在文档表里)
|
||||
|
||||
契约是**未绑定文档表**(绑定表是数据,永远不是契约)。三种形状、严格位置:
|
||||
|
||||
| 形状(须含 `类型` 列) | 允许位置 | 附着 |
|
||||
|--------------------------|----------|------|
|
||||
| `参数`/`类型`/`说明` 表 + `返回`/`类型`/`说明` 表 | 函数体首个可执行行之前 | 函数 |
|
||||
| `字段`/`类型`/`可空`/`说明` 表 | 紧邻 `` `名` = `` 绑定之前 | 集合(变量) |
|
||||
| `字段`/`类型`/`可空`/`说明` 表 | 对象(`#`)体首成员之前 | 对象类型 |
|
||||
|
||||
````text
|
||||
## 加一
|
||||
|
||||
对于输入变量`n`,期望是数字。
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| n | number | 输入值 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| | number | 加一结果 |
|
||||
|
||||
*n+1*
|
||||
````
|
||||
|
||||
- 类型词汇:`text` / `number` / `bool` / `list` / `map` / `any` / `#` 对象名(拼错 ⇒ `contract.unknown_type` + 最近建议)。
|
||||
- 契约表**永不执行**、不污染升参推断;无契约文件行为逐字节不变(动态默认,零摩擦)。
|
||||
- 运行时只在四个边界校验:调用实参 / 字段访问 `[键](集合)` / 表绑定 / 返回。
|
||||
- `marqdo check [FILE] [--json]` 静态互查:契约行 vs 升参推断形参**双向**漂移(错行=Error;新升参未覆盖=Warning)、未知类型、错位契约;有 Error 非零退出。
|
||||
- 契约诊断带 `doc_anchor` + `doc_quote`(表原文)——修复只照锚点局部改。
|
||||
|
||||
## Markup → meaning (v0.3)
|
||||
|
||||
| Marker | Meaning |
|
||||
@@ -199,7 +255,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/).
|
||||
|
||||
@@ -244,11 +300,14 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
|
||||
|
||||
## AI authoring workflow
|
||||
|
||||
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
2. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
|
||||
3. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
|
||||
4. On `path:line:col: message`, fix that span; re-run until exit 0.
|
||||
5. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
|
||||
1. **查再写**:不确定语法就 `marqdo mlsp`(`syntax` / `locate`)——不必背语法细节。
|
||||
2. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
3. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
|
||||
4. 可选:给函数/集合写**渐进式契约**(上节三种表格形状;写全或不写,别写一半)。
|
||||
5. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
|
||||
6. On errors:结构化诊断(含 `doc_anchor` / `suggestion`)→ `repair_targets` 取有界靶点,**只改锚点范围内**的行。
|
||||
7. 提交前:`marqdo check path/to/file.mq.md`(或 `mlsp validate`)清到零 Error。
|
||||
8. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
|
||||
|
||||
## Anti-patterns (common model mistakes)
|
||||
|
||||
@@ -287,3 +346,5 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
|
||||
- [ ] Browser client: `lib/browser` + tables when returning effects
|
||||
- [ ] Quantum draw: quote `kind=` / `theme=`; rebuild plugin → `ext add quantum` before view
|
||||
- [ ] `marqdo run` succeeds (or errors addressed)
|
||||
- [ ] 语法拿不准的地方已查 MLSP(`syntax`/`locate`),而不是凭记忆发明
|
||||
- [ ] 契约(如有)与升参一致:`marqdo check` 零 Error
|
||||
@@ -0,0 +1,9 @@
|
||||
# Ext CDN / R2 (Cloudflare) — copy to ~/.marqdo/r2.env and chmod 600
|
||||
# Never commit real keys. Public downloads: https://ext.marqdo.com
|
||||
|
||||
R2_ACCOUNT_ID=
|
||||
R2_BUCKET=marqdo
|
||||
R2_ENDPOINT=https://<accountid>.r2.cloudflarestorage.com
|
||||
R2_ACCESS_KEY_ID=
|
||||
R2_SECRET_ACCESS_KEY=
|
||||
R2_PUBLIC_BASE=https://ext.marqdo.com
|
||||
@@ -0,0 +1,15 @@
|
||||
## 层归属(必填,见 doc/design/layers.md)
|
||||
|
||||
- [ ] Language(`src/lex` `src/parse` `src/ast` `src/interp` `src/diagnostics` / 契约)
|
||||
- [ ] Runtime(`lib/` `plugins/` `crates/` catalog / view / debug / builtin)
|
||||
- [ ] Document(`*.mq.md` `skills/` `ext/` `public/` `examples/`)
|
||||
|
||||
## 核心表面(见 doc/design/core-surface.md)
|
||||
|
||||
- [ ] 不涉及核心标记
|
||||
- [ ] 涉及核心标记:ADR 编号 ______;core-surface.md 与 `CORE_CONSTRUCTS` 已同步(CI 守卫)
|
||||
|
||||
## 验收
|
||||
|
||||
- [ ] 相关验收(机器可验证)全绿
|
||||
- [ ] 全量回归绿(`cargo test` / `go test ./...` 视触及面)
|
||||
@@ -124,9 +124,12 @@ jobs:
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### 亮点 / Highlights
|
||||
- **v1.0.1**:修复 Go `libweb` 动态路由 `{param}` 查询代入、详情 Markdown、CSS 数字误报、`/static/` ServeMux 冲突
|
||||
- **v1.0.1**: fix Go `libweb` dynamic-route `{param}` query resolve, article Markdown, CSS numeric false positives, `/static/` ServeMux conflict
|
||||
- **v1.0.0**:Markdown 语法映射 v0.3 为唯一运行时(`**` 代码 / `*` 返回 / 叙述 `` `名` ``)
|
||||
- **v1.1.0**:AI 原生闭环三件套——核心表面守卫(问题一)· 渐进式契约 + `marqdo check`(问题二)· **MLSP for AI**(`marqdo mlsp`:locate/syntax/validate/repair_targets/repair_apply/schema,AI 按需查语法而非背诵)(问题三)· `run --json` 结构化诊断
|
||||
- **v1.1.0**: AI-native loop — core-surface guard, progressive contracts + `marqdo check`, **MLSP for AI** (`marqdo mlsp`: query syntax on demand instead of memorizing), `run --json` structured diagnostics
|
||||
- **v1.0.7**:WS/网络边界加固(同源握手、require_auth/需要登录、消息上限、HTTP 8 MiB 截断);`url_encode` `%20`
|
||||
- **v1.0.3**:Ubuntu PPA + 扩展 CDN(ext.marqdo.com);CLI/扩展可分发;noble 捆绑 Rust 工具链
|
||||
- **v1.0.3**: Ubuntu PPA + extension CDN; independent CLI/ext packs; bundled Rust for noble
|
||||
- **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)
|
||||
|
||||
|
||||
+9
-1
@@ -24,7 +24,8 @@
|
||||
.marqdo/
|
||||
**/.marqdo/
|
||||
.marqdo-ext/
|
||||
.env
|
||||
/vendor/
|
||||
/.cargo/config.toml
|
||||
|
||||
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
|
||||
/public/index.html
|
||||
@@ -77,5 +78,12 @@ plugins/*/tmp/
|
||||
# Go web plugin c-shared build output (./scripts/build-web-plugin.sh)
|
||||
/plugins/web/build/
|
||||
|
||||
# PPA build: bundled Rust toolchain (packed into .orig by ppa-build-source.sh only)
|
||||
/third_party/rust/
|
||||
/third_party/
|
||||
|
||||
# ephemeral sqlite / test artifacts
|
||||
tests/ext/:memory:
|
||||
|
||||
# local secrets
|
||||
.env
|
||||
+189
@@ -1,5 +1,75 @@
|
||||
# Changelog
|
||||
|
||||
## v1.1.0 — 2026-09-23
|
||||
|
||||
### Highlights
|
||||
|
||||
**AI 原生闭环三件套落地**:核心表面守卫(问题一)· 渐进式契约(问题二)· MLSP for AI(问题三)。
|
||||
`marqdo check` 静态契约防漂移、`marqdo mlsp` 让 AI **按需查询**语法而非背诵、`run --json` 统一结构化诊断(错误即数据,供 AI 直接消费)。
|
||||
本版 CLI 与扩展包 **同步为 1.1.0**。
|
||||
|
||||
- **核心要小(问题一)**:`doc/design/core-surface.md` 列出 19 个核心构造 + `CORE_CONSTRUCTS` 守卫测试——任一侧(清单/文档/金样)单边改动 CI 必红;三层架构(Core / Runtime / Document)入 `doc/design/layers.md`。
|
||||
- **语义校验(问题二)**:渐进式契约表(`参数`/`返回`/`字段`/集合)嵌入文档叙述;四边界校验(调用实参 / 返回值 / 表绑定 / 键访问);`marqdo check` 静态防漂移(类型 typo / 参数名漂移 / 重复契约必报)。
|
||||
- **AI 可靠反馈 + 不必学语法(问题三)**:`marqdo mlsp`(MLSP,行分隔 JSON over stdio)提供 `locate` / `syntax` / `validate` / `repair_targets` / `repair_apply` / `schema`;`syntax` 卡片机械携带戒律原文 / 样例 / 文档锚点,AI 无需预学语法。修复护栏:有界行编辑、越界必拒(abstain)。
|
||||
- **验证(P4)**:锚点消融 anchor 一轮修复率 **100%**(双模型,plain 85%/90%);契约消融拦截 100% / 误报 0%;防漂移必报 9/9;核心守卫演练 3/3 必红。详见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)。
|
||||
|
||||
```bash
|
||||
# Ubuntu PPA / 源码
|
||||
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
|
||||
git checkout v1.1.0 && cargo build --release
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造(`heading` / `bold-code` / `italic-return` / `param-list` / `call-quote` / `branch-list` / `loop-list` / `table-bind` / `footnote-index` / `link-index` / …)与 v1.0.7 完全一致,未新增标记。本版为 **Runtime 层(契约校验 / MLSP / 诊断 JSON)** 与 **Document 层(core-surface / layers)** 变更,不触碰语言核心。
|
||||
|
||||
### Added
|
||||
- **MLSP(`marqdo mlsp`)**:面向 AI 的语言服务协议(行分隔 JSON over stdio)——`locate` / `syntax` / `validate` / `repair_targets` / `repair_apply` / `schema`;`syntax` 卡片含 `semantics` / `rule` / `sample` / `doc_quote`(自持,机器可读戒律原文)。
|
||||
- **`marqdo check`**:静态契约漂移检查(未知类型词 / 参数名漂移 / 返回越约 / 重复契约表 / 错位契约表)。
|
||||
- **渐进式契约(Progressive contracts)**:文档叙述内嵌契约表(`参数`/`返回`/`字段` + 集合 `字段`),四边界校验(调用实参 / 返回值 / 表绑定 / 键访问);被绑定的 `字段|类型` 表是**数据**、永不误判为契约。
|
||||
- **`marqdo run --json`**:统一结构化诊断(`code` / `severity` / `suggestion` / `doc_anchor` / `doc_quote` / `contract_ref`),错误即数据。
|
||||
- **修复护栏**:`mlsp repair_apply` 有界行编辑——只允许落在 `doc_anchor` 指定范围内的编辑,越界整体拒绝(all-or-nothing / abstain)。
|
||||
- **守卫与文档**:`doc/design/core-surface.md`(19 构造)、`doc/design/layers.md`(三层架构)、`tests/core_surface.rs`(守卫生效验证)。
|
||||
|
||||
### Fixed
|
||||
- **错误链不再扁平化**:`src/load.rs` 以 `label_error` 保留结构化 `Diagnostic`("Error Exit Only" 原则),修复契约类错误被降级为字符串的回归。
|
||||
- **契约 parse 边界**:`interp.rs` 键访问优先给出 `index_diag`(索引/键诊断先于取值),空字段 vs 缺字段语义消歧。
|
||||
|
||||
### Changed
|
||||
- **`.cursor/skills/marqdo`**:由「背诵式压缩操作手册」改为**查询式工作流**——写码前 `mlsp syntax` / `locate`,提交前 `mlsp validate` + `marqdo check`,修复照 `doc_anchor` 局部改。
|
||||
- **契约表一经出现即为完整声明**(新推断的升参未覆盖 ⇒ `contract.param_drift` 警告,不静默)。
|
||||
- 取元**主推** `[键](集合)`(`link-index`);`` `集合`[^键] ``(`footnote-index`)保留兼容。
|
||||
|
||||
### 已知未决(诚实标注)
|
||||
- **P4 实验 (b) 盲测未达标**:「查询式 vs 全文档背诵」四判据未全立(`deepseek-flash`:docs 4/6 vs query 0/3;端点 infra 削样本)。查询机制本身已验证无缺陷,瓶颈在**模型自查纪律**(不知道自己不知道 ⇒ 不查询)——协议改进(写码前强制自检 / 陌生构造强制查询)列入下一阶段。见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md) §3。
|
||||
|
||||
## Unreleased
|
||||
|
||||
## v1.0.7 — 2026-09-22
|
||||
|
||||
### Highlights
|
||||
|
||||
**WS / 网络边界加固**:WebSocket 握手同源校验、broadcast/room 默认需登录(`require_auth`/`需要登录` 可显式关闭)、消息 1 MiB × 256 条上限、空 room 回收;HTTP 响应 8 MiB 在读流时截断;`url_encode` 空格 `%20`。本版 CLI 与扩展包 **同步为 1.0.7**。
|
||||
|
||||
- **安全默认**:浏览器 WS 握手仅同源;有状态 fan-out 端点未登录 401 / 公开直播流显式 `require_auth=False`
|
||||
- **资源上限**:WS 单条 1 MiB、单连接 256 条;HTTP/SSE 8 MiB 读流截断——对端无法借大响应耗尽内存
|
||||
- **测试**:P3 金样对齐 quiet-admin 门禁语义;wasm smoke 以 ESM 加载官方 bridge
|
||||
|
||||
```bash
|
||||
# Ubuntu PPA / 源码
|
||||
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
|
||||
git checkout v1.0.7 && cargo build --release
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
### Fixed
|
||||
- **WS 安全默认**:握手改为同源校验(不再放行任意 Origin);`route_ws` 新增 `require_auth`/`需要登录`,broadcast/room 默认要求登录会话,公开直播流需显式设假,未认证握手 401。
|
||||
- **WS 资源上限**:单条消息 1 MiB、单连接最多收集 256 条回复;传输错误/超时返回 `{ok:false, error}`,不再伪装空成功;空 room 自动回收(防 URL 派生 room 名耗尽内存)。
|
||||
- **HTTP 响应上限**:8 MiB 上限在读流时截断(含错误路径与 SSE 错误路径),上游无法借超大响应耗尽内存。
|
||||
|
||||
### Changed
|
||||
- `net.url_encode`:空格编码为 `%20`(原 `+`),URL 段语义下与字面 `+` 消歧义。
|
||||
- `web`/`网页` 文档同步:`route_ws` 的 `require_auth`/`需要登录` 与 `ws.connect` 的收集上限语义。
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
@@ -8,6 +78,125 @@
|
||||
|
||||
### Changed
|
||||
|
||||
## Ext pack v1.0.6 — 2026-09-18
|
||||
|
||||
### Highlights
|
||||
|
||||
**ext/web OIDC、表单删除与安静管理台(CLI 仍为 v1.0.3)**:OIDC 登录/登出回首页、表单 `删除` 动作、默认关闭内置 admin/RBAC desk、独立 Redis 会话 URL、Postgres CRUD。安装:
|
||||
|
||||
```bash
|
||||
marqdo ext add web # CDN latest → 1.0.6
|
||||
```
|
||||
|
||||
### Added
|
||||
- **OIDC**:`auth.oidc` / 网页鉴权 OIDC;登录入口与 `next` 回跳。
|
||||
- **表单删除**:`form` 动作 `删除`/`delete`(通用 CRUD,无站点特判)。
|
||||
- **列表/路由**:请求上下文、列表装配延续;注销默认回 `/` 避免 IdP 再登录环。
|
||||
|
||||
### Fixed
|
||||
- 内置 admin / RBAC desk 默认安静,直至显式 `admin` / `enable_rbac`。
|
||||
- 静态资源缓存与 WASM 启动延迟;会话 CSRF 与 Postgres 方言。
|
||||
|
||||
### Changed
|
||||
- 扩展包 SemVer **1.0.6**(`ext/VERSION`);与 CLI **v1.0.3** 可独立安装。
|
||||
|
||||
## Ext pack v1.0.5 — 2026-09-18
|
||||
|
||||
### Highlights
|
||||
|
||||
**ext/web 请求上下文与表单来源(CLI 仍为 v1.0.3)**:字段 `来源`/`source`(session / route / now)、server-only 盖戳、页面 `列表装配`/`compose_list`;禁止按业务表特判。安装:
|
||||
|
||||
```bash
|
||||
marqdo ext add web # CDN latest → 1.0.5
|
||||
```
|
||||
|
||||
### Added
|
||||
- **Request context**:表单提交携带 `_mq_params` / `_mq_return`;`ApplySources` 从 session/route/now 写入。
|
||||
- **字段来源列**:`client`(默认)/ `session.username` / `route.NAME` / `now`;非 client 不渲染且覆盖客户端伪造。
|
||||
- **列表装配**:`compose_list` / `列表装配`(副绑定 + 条件/排序/插槽),详情页可同页渲染子列表。
|
||||
- 设计文:[ext-web-request-context.md](doc/design/ext-web-request-context.md);金样 `ext_web_form_source_live`。
|
||||
|
||||
### Changed
|
||||
- 扩展包 SemVer **1.0.5**(`ext/VERSION`);与 CLI **v1.0.3** 可独立安装。
|
||||
- 移除评论表名特判(`enrichCommentSubmit`)。
|
||||
|
||||
## Ext pack v1.0.4 — 2026-09-17
|
||||
|
||||
### Highlights
|
||||
|
||||
**ext/web 能力面扩展(CLI 仍为 v1.0.3)**:可配置 RBAC、租户作用域、WS `on_message`/presence、原生 SPA 内存路由、协同记事本 MVP。安装:
|
||||
|
||||
```bash
|
||||
marqdo ext add web # CDN latest → 1.0.4
|
||||
```
|
||||
|
||||
### Added
|
||||
- **RBAC**:五表(`web_permissions` / `web_roles` / `web_role_permissions` / `web_users` / `web_user_roles`);`app.enable_rbac`、`app.gate permissions=`、`rbac.can`、注册页、`/_rbac/*` 管理 API/desk。
|
||||
- **Tenant**:`app.tenant`(path/header/subdomain)+ `tenant_scope` 自动过滤/盖戳。
|
||||
- **WebSocket G-WS2**:`route_ws` 支持 `on_message` 钩子、动态 room、`presence` 通道。
|
||||
- **Native SPA**:内存 `store_set` / `spa_goto` 与全页 WASM SPA 样站。
|
||||
- **Collab MVP**:LWW 文档协议(`DOC\t`)双端协同记事本样站。
|
||||
|
||||
### Changed
|
||||
- 扩展包 SemVer **1.0.4**(`ext/VERSION`);与 CLI **v1.0.3** 可独立安装。
|
||||
|
||||
## v1.0.3 — 2026-09-17
|
||||
|
||||
### Highlights
|
||||
|
||||
**分发渠道齐备**:Ubuntu PPA 装 CLI;扩展包走 CDN(`ext.marqdo.com`)与 GitHub;CLI 与扩展可分开发版。本版 CLI 与扩展包 **同步为 1.0.3**。
|
||||
|
||||
**语法**:未绑定的 GFM 表格是可丢弃的集合值,不再报 `unrecognized statement`(文档页可直接写安装表)。
|
||||
|
||||
```bash
|
||||
# Ubuntu
|
||||
sudo add-apt-repository ppa:cflmy/marqdo
|
||||
sudo apt update && sudo apt install marqdo
|
||||
marqdo ext add web
|
||||
|
||||
# 或源码 / Releases
|
||||
git checkout v1.0.3 && cargo build --release
|
||||
```
|
||||
|
||||
### Added
|
||||
- Ubuntu PPA packaging: `debian/` + `scripts/ppa-ship.sh` (一键装工具/打包/dput) + `ppa-build-source.sh` + [ubuntu-ppa.md](doc/design/ubuntu-ppa.md).
|
||||
- **Extension CDN** (`https://ext.marqdo.com` / Cloudflare R2):`ext add` 下载顺序改为 CDN → GitHub → proxy;独立包版本见 `ext/VERSION` 与 CDN `latest/VERSION`;上传脚本 `scripts/upload-ext-r2.py`(凭据 `~/.marqdo/r2.env`)。设计见 [ext-cdn.md](doc/design/ext-cdn.md)。
|
||||
- `ext add` 下载:GitHub 失败后自动回退 `https://proxy.cflmy.top/github.com/…`;可用 `MARQDO_EXT_DOWNLOAD_BASE` 指定首选镜像;加长读写超时。
|
||||
- 用户文档(README / `public/00-欢迎` / `features/05-扩展`)标明安装渠道:Ubuntu PPA、GitHub Releases、源码;扩展走 CDN。
|
||||
|
||||
### Fixed
|
||||
- `ext/` 导入默认搜索 `~/.marqdo/ext`(与 `marqdo ext add` 安装根一致),无需再手动 `export MARQDO_EXT`。
|
||||
- PPA/noble:捆绑 `third_party/rust`(现代 cargo)以构建 Cargo.lock v4;修复首次 Launchpad 构建失败(distro cargo 1.75)。
|
||||
- 未绑定的 GFM 表格不再报 `unrecognized statement`:作为集合值求值后丢弃(文档中可写表)。
|
||||
|
||||
### Changed
|
||||
- 允许 **CLI 与扩展包分开发版**:扩展包 SemVer 可与 `Cargo.toml` 不同(`MARQDO_EXT_VERSION` / `ext/VERSION` / CDN latest)。
|
||||
- 发版 skill:支持 `full` / `cli` / `ext`;扩展必传 R2+GitHub;CLI 走 PPA;需用户操作时打印确切命令。
|
||||
|
||||
## 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
|
||||
|
||||
Generated
+2
-2
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "1.0.1"
|
||||
version = "1.1.0"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
@@ -603,7 +603,7 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.0.1"
|
||||
version = "1.1.0"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
|
||||
+3
-2
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "1.0.1"
|
||||
version = "1.1.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -50,8 +50,9 @@ include_dir = "0.7"
|
||||
libc = { version = "0.2", optional = true }
|
||||
|
||||
[target.'cfg(target_arch = "wasm32")'.dependencies]
|
||||
# No `wasmbind`: keeps cdylib free of wasm-bindgen imports (raw mq_* ABI).
|
||||
# Custom entropy — no `js`/wasm-bindgen imports (raw mq_* ABI + marqdo-bridge.js).
|
||||
chrono = { version = "0.4", default-features = false, features = ["alloc", "std"] }
|
||||
getrandom = { version = "=0.2.17", default-features = false, features = ["custom"] }
|
||||
|
||||
[workspace]
|
||||
members = [
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
# Marqdo
|
||||
|
||||
**代码即文档。文档即代码。文档即知识库。**
|
||||
**代码即文档。文档即知识库。知识即可执行。**
|
||||
|
||||
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
|
||||
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。它不是「又一个 Markdown 编程语言」,而是**文档原生的编程运行时(Document-native runtime)**——一门关于**可执行知识(Executable Knowledge)**的语言。
|
||||
|
||||
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
|
||||
|
||||
@@ -10,6 +10,47 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
|
||||
---
|
||||
|
||||
## 核心优势:可执行知识(Executable Knowledge)
|
||||
|
||||
> **Knowledge That Can Run —— 知识即可执行。**
|
||||
> Marqdo 不是「用 Markdown 写程序」这么简单:它让一个 `.mq.md` 文档**同时**是文稿、知识与程序——同一份结构,同时服务于人、解释器、工具与 AI。
|
||||
|
||||
```text
|
||||
.mq.md(同一份文件)
|
||||
┌─────────┼─────────┐
|
||||
文稿 知识 程序
|
||||
└─────────┼─────────┘
|
||||
▼
|
||||
Marqdo 运行时
|
||||
▼
|
||||
可执行知识(Executable Knowledge)
|
||||
```
|
||||
|
||||
| 真正的核心优势 | 说明 |
|
||||
|------|------|
|
||||
| **知识-代码一致性**<br>Knowledge-Code Coherence | 说明、数据、示例与实现**同一份源文件**:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的**知识不一致**——知识陈述本身可以被测试。 |
|
||||
| **默认安全,AI 友好** | 无标记文字默认是叙述(注释),只有显式标记才进入执行。AI 自由发挥**不会污染**文档与代码的边界——这比「自然语言编程」安全得多,是 AI 原生语言的重要前提。 |
|
||||
| **multi-view artifact**<br>`.mq.md` 双后缀即开放接口 | `.mq` 告诉解释器「可执行」,`.md` 告诉整个 Markdown 生态「仍是文档」。GitHub 直接读、VS Code 直接改、搜索引擎直接索引、LLM 直接理解、Marqdo 直接运行。**Marqdo 不占有知识,只是给 Markdown 增加执行语义。** |
|
||||
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元 `[键](集合)` 也是 Markdown 链接形。这是 literate programming 的下一步。 |
|
||||
| **语义干净** | **返回是架构,打印只是函数**:`*…*` 改变控制流,`print` 只是副作用函数;分支与循环长在 Markdown 结构上(`1.` `2.` 递增 = 分支,`-` = 循环),不是所有列表都被粗暴当成 if。 |
|
||||
| **AI 的可靠上下文与长期记忆** | 一个 `.mq.md` 同时是 documentation + schema + code + examples + knowledge + executable behavior;AI 不必再拼装 README + OpenAPI + JSON Schema + prompt。整个工程天然就是 AI 的**世界模型**——比 RAG 更接近 Executable RAG。 |
|
||||
| **完整工程,不是玩具** | Rust 正经解释器(词法 / 语法 / 语义 / 树遍历 + 字节码后端)、stdlib、模块与对象、debugger、viewer、catalog、WASM、原生插件 ABI、VS Code 扩展、agent / LLM / MCP。 |
|
||||
|
||||
---
|
||||
|
||||
## 愿景与期许
|
||||
|
||||
不把「AI 能写 Marqdo」当终点,而是 **「AI 能可靠地生成可验证的 Marqdo」**:
|
||||
|
||||
1. **AI 可验证语言**:`LLM → Marqdo AST → 语义检查 → 结构化诊断 → LLM 修复 → 合格程序`。让类型与语义检查成为 AI 编程闭环里的强约束,堵住「语义看似合理、类型实则不对」的生成。
|
||||
2. **Marqdo Schema / Language Server for AI**:机器可读的语言 Schema(`get_syntax` / `validate` / `repair` …),AI 不必读千行文档猜语法,而是 discover → construct → validate → execute → inspect。
|
||||
3. **程序即 AI 长期记忆**:`.mq.md` 工程 = 可执行知识库 = AI 的世界模型(Executable Knowledge Representation)。
|
||||
4. **可执行知识图**:`.mq.md` 之间的 Markdown 链接天然长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
|
||||
5. **知识可测试**:文档中的示例表自动执行;知识与执行结果不一致会被机器报告——Knowledge-Code Coherence 从理念变为日常。
|
||||
6. **可靠性基准**:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成真实任务,测量生成长度、语法 / 语义错误率、修复轮次、token 消耗与人类阅读 / 修改成本——用实验数据证明「文档型语法降低 LLM 生成熵」。
|
||||
|
||||
---
|
||||
|
||||
## 为什么重要
|
||||
|
||||
| 痛点 | Marqdo 的答案 |
|
||||
@@ -38,7 +79,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
| 叙述 `` `名` `` / `` `名`=默认 `` | 形参由体推断(`` + `名` `` 仍可用) |
|
||||
| `1.` … | 体内 `1.` `2.` … = 分支(`N. *` = else) |
|
||||
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) ``) |
|
||||
| 表格 | 集合;取元优先 `[键](集合)` |
|
||||
| 表格 | 集合(几何即类型,见下);取元优先 `[键](集合)` |
|
||||
| 单独一行 `---` / `***` | **叙述分隔**(跳过;不是函数收束) |
|
||||
|
||||
```markdown
|
||||
@@ -58,6 +99,8 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
对于输入变量`n`,执行**n=n+1**接着返回*n*。
|
||||
```
|
||||
|
||||
**表格几何即类型**:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。详见 [tables-maps-footnotes.md](doc/roadmap/tables-maps-footnotes.md)。
|
||||
|
||||
完整约定:[markdown-mapping-v0.3.md](doc/design/markdown-mapping-v0.3.md)。
|
||||
|
||||
---
|
||||
@@ -68,7 +111,8 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
|
||||
2. **返回是架构;打印只是函数。**
|
||||
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
|
||||
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
|
||||
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
|
||||
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
|
||||
6. **语言核心保持小**:Language(标记映射 / AST / 语义 / 类型)、Runtime(stdlib / 插件 ABI / WASM / agent)、Document(知识 + 代码 + UI + AI)三层分明——生态功能不淹没语言身份。
|
||||
|
||||
---
|
||||
|
||||
@@ -98,8 +142,9 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v1.0.1)
|
||||
## 现状(v1.1.0)
|
||||
|
||||
- **AI 原生闭环(v1.1.0 新增)**:核心表面守卫(19 构造,单边改动 CI 必红)· **渐进式契约**(文档内嵌 `参数`/`返回`/`字段` 表 + 四边界校验 + `marqdo check` 防漂移)· **MLSP for AI**(`marqdo mlsp`:`locate`/`syntax`/`validate`/`repair_targets`/`repair_apply`/`schema`,AI 按需查语法而非背诵)· **结构化诊断**(`run --json`,错误即数据);验证见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)
|
||||
- 映射与解释器:**v0.3 语法宪法**(`**` 代码 / `*` 返回 / 叙述声明);Phase I 树遍历 + 字节码后端;金样例在 `tests/` 与 `tests/markup-v03/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
|
||||
@@ -108,7 +153,7 @@ marqdo catalog public -o .marqdo
|
||||
- **`marqdo version --check`**:与 GitHub 最新 release 对比
|
||||
- 标准库:**内置于二进制**(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**;**定制 C0–C4**;**宿主 H1–H2**(`proxy`/`invoke`,见 [ext-hosting.md](doc/roadmap/ext-hosting.md));原生层默认 **Go `libweb`**([ADR 0004](doc/adr/0004-web-plugin-go.md),`scripts/build-web-plugin.sh`);示例 [marqdo-blog](examples/marqdo-blog/) · [anlian-mq](examples/anlian-mq/);生产路径见 [web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)
|
||||
- **`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/)
|
||||
- **`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)
|
||||
@@ -120,12 +165,22 @@ marqdo catalog public -o .marqdo
|
||||
- **浏览器 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(v1.0.1)
|
||||
### 如何使用最新 Marqdo(v1.1.0)
|
||||
|
||||
**安装解释器(任选其一)**
|
||||
|
||||
| 方式 | 适用 | 命令 / 链接 |
|
||||
|------|------|-------------|
|
||||
| **Ubuntu PPA** | Ubuntu 24.04+(`noble` 等) | `sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo` |
|
||||
| **GitHub Releases** | Windows / Linux 预编译 zip | https://github.com/cflmy/marqdo/releases |
|
||||
| **源码** | 需本机 Rust | 见下方 `git clone` + `cargo build --release` |
|
||||
|
||||
**安装官方扩展**(与 CLI 可分开发版):`marqdo ext add …` 默认下载顺序为 **CDN** [`https://ext.marqdo.com`](https://ext.marqdo.com) → GitHub Releases → [`proxy.cflmy.top`](https://proxy.cflmy.top) 镜像。
|
||||
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v1.0.1 # 或留在 main
|
||||
git checkout v1.1.0 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
@@ -138,7 +193,12 @@ marqdo view public --no-open
|
||||
marqdo debug public --no-open
|
||||
marqdo catalog public -o .marqdo
|
||||
|
||||
# 3) 安装官方扩展(Release 用户:无需本机 Rust/Go)
|
||||
# 2b) AI 原生闭环(v1.1.0):契约检查 / 结构化诊断 / MLSP 查询
|
||||
marqdo check tests/contracts/ok_contract.mq.md # 静态契约防漂移
|
||||
marqdo run tests/structure/hello.mq.md --json # 结构化诊断(错误即数据)
|
||||
printf '{"id":1,"method":"syntax","params":{"query":"返回"}}\n' | marqdo mlsp
|
||||
|
||||
# 3) 安装官方扩展(Release / CDN 用户:无需本机 Rust/Go)
|
||||
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native(Go libweb)
|
||||
marqdo ext add agent # 或:智能体
|
||||
marqdo ext add quantum # 或:量子
|
||||
@@ -149,6 +209,7 @@ marqdo ext add llm # 或:大模型(纯 .mq.md)
|
||||
# 离线:解压 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
|
||||
@@ -158,7 +219,7 @@ marqdo wasm build
|
||||
# → dist/wasm/ … 见 examples/browser-hello/
|
||||
|
||||
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v1.0.1
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v1.1.0
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
@@ -170,7 +231,7 @@ cargo run -- view output public -o public
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
**发布包(GitHub Releases)**:单独二进制 **已内置**官方 `lib/`(`import …:lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发。**扩展库**用 `marqdo ext add …` 安装(见 [CHANGELOG](CHANGELOG.md) 与 [ext-cli.md](doc/design/ext-cli.md));原生 `.so`/`.dll` 需本地编译或从带 `native/` 的安装目录解析。
|
||||
**发布包**:GitHub Releases 的单独二进制 **已内置**官方 `lib/`。Ubuntu 用户优先 **PPA** 装 CLI。**扩展库**用 `marqdo ext add …`(CDN → GitHub);设计见 [ext-cdn.md](doc/design/ext-cdn.md) · [ubuntu-ppa.md](doc/design/ubuntu-ppa.md) · [ext-cli.md](doc/design/ext-cli.md)。
|
||||
|
||||
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md) · 变更 [CHANGELOG.md](CHANGELOG.md)
|
||||
---
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "1.0.1"
|
||||
version = "1.1.0"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
|
||||
@@ -197,6 +197,20 @@ export function eventArgsFromDom(ev, valueFromSel) {
|
||||
args.fields = fields;
|
||||
}
|
||||
}
|
||||
if (ev && (ev.type === "scroll" || ev.type === "resize")) {
|
||||
try {
|
||||
const doc = typeof document !== "undefined" ? document.documentElement : null;
|
||||
const body = typeof document !== "undefined" ? document.body : null;
|
||||
const scrollTop = (doc && (doc.scrollTop || 0)) || (body && body.scrollTop) || 0;
|
||||
const height = doc ? (doc.scrollHeight - doc.clientHeight) || 1 : 1;
|
||||
const ratio = Math.max(0, Math.min(1, scrollTop / height));
|
||||
args.scroll_top = scrollTop;
|
||||
args.scroll_max = height;
|
||||
args.scroll_ratio = ratio;
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
}
|
||||
}
|
||||
return args;
|
||||
}
|
||||
|
||||
@@ -721,75 +735,88 @@ function runObserveEffect(exports, spec, onError) {
|
||||
const kind = String(spec.kind || spec.type || "intersect").toLowerCase();
|
||||
const sel = String(spec.sel || "");
|
||||
const thenFn = spec.then;
|
||||
const id = String(spec.id || `obs${++observeSeq}`);
|
||||
const el = qsOne(sel);
|
||||
if (!el || !thenFn) return;
|
||||
const baseId = String(spec.id || `obs${++observeSeq}`);
|
||||
const nodes = qsAll(sel);
|
||||
if (!nodes.length || (!thenFn && !spec.add_class)) return;
|
||||
|
||||
const prev = observeHandles.get(id);
|
||||
if (prev) {
|
||||
try {
|
||||
prev.disconnect();
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
}
|
||||
}
|
||||
|
||||
const fire = (payload) => {
|
||||
try {
|
||||
const result = call(exports, thenFn, payload);
|
||||
if (!result.ok) {
|
||||
if (onError) onError(result.error);
|
||||
return;
|
||||
nodes.forEach((el, idx) => {
|
||||
const id = nodes.length === 1 ? baseId : `${baseId}_${idx}`;
|
||||
const prev = observeHandles.get(id);
|
||||
if (prev) {
|
||||
try {
|
||||
prev.disconnect();
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
}
|
||||
applyEffects(exports, result.value, { onError });
|
||||
} catch (e) {
|
||||
if (onError) onError(String(e));
|
||||
}
|
||||
};
|
||||
|
||||
if (kind === "resize" && typeof ResizeObserver !== "undefined") {
|
||||
const ro = new ResizeObserver((entries) => {
|
||||
const en = entries[0];
|
||||
const cr = en?.contentRect;
|
||||
fire({
|
||||
ok: true,
|
||||
kind: "resize",
|
||||
id,
|
||||
width: cr ? cr.width : 0,
|
||||
height: cr ? cr.height : 0,
|
||||
});
|
||||
});
|
||||
ro.observe(el);
|
||||
observeHandles.set(id, ro);
|
||||
return;
|
||||
}
|
||||
const fire = (payload) => {
|
||||
try {
|
||||
const result = call(exports, thenFn, payload);
|
||||
if (!result.ok) {
|
||||
if (onError) onError(result.error);
|
||||
return;
|
||||
}
|
||||
applyEffects(exports, result.value, { onError });
|
||||
} catch (e) {
|
||||
if (onError) onError(String(e));
|
||||
}
|
||||
};
|
||||
|
||||
if (typeof IntersectionObserver !== "undefined") {
|
||||
const io = new IntersectionObserver(
|
||||
(entries) => {
|
||||
if (kind === "resize" && typeof ResizeObserver !== "undefined") {
|
||||
const ro = new ResizeObserver((entries) => {
|
||||
const en = entries[0];
|
||||
if (!en) return;
|
||||
const cr = en?.contentRect;
|
||||
fire({
|
||||
ok: true,
|
||||
kind: "intersect",
|
||||
kind: "resize",
|
||||
id,
|
||||
intersecting: !!en.isIntersecting,
|
||||
ratio: en.intersectionRatio,
|
||||
width: cr ? cr.width : 0,
|
||||
height: cr ? cr.height : 0,
|
||||
});
|
||||
if (spec.once && en.isIntersecting) {
|
||||
try {
|
||||
io.disconnect();
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
});
|
||||
ro.observe(el);
|
||||
observeHandles.set(id, ro);
|
||||
return;
|
||||
}
|
||||
|
||||
if (typeof IntersectionObserver !== "undefined") {
|
||||
const opts = { threshold: spec.threshold != null ? Number(spec.threshold) : 0.1 };
|
||||
if (spec.rootMargin != null) opts.rootMargin = String(spec.rootMargin);
|
||||
const io = new IntersectionObserver(
|
||||
(entries) => {
|
||||
const en = entries[0];
|
||||
if (!en) return;
|
||||
if (en.isIntersecting && spec.add_class) {
|
||||
for (const c of String(spec.add_class).split(/\s+/).filter(Boolean)) {
|
||||
el.classList.add(c);
|
||||
}
|
||||
}
|
||||
observeHandles.delete(id);
|
||||
}
|
||||
},
|
||||
{ threshold: spec.threshold != null ? Number(spec.threshold) : 0.1 },
|
||||
);
|
||||
io.observe(el);
|
||||
observeHandles.set(id, io);
|
||||
}
|
||||
if (thenFn) {
|
||||
fire({
|
||||
ok: true,
|
||||
kind: "intersect",
|
||||
id,
|
||||
intersecting: !!en.isIntersecting,
|
||||
ratio: en.intersectionRatio,
|
||||
target_id: el.id || "",
|
||||
});
|
||||
}
|
||||
if (spec.once && en.isIntersecting) {
|
||||
try {
|
||||
io.disconnect();
|
||||
} catch (_) {
|
||||
/* ignore */
|
||||
}
|
||||
observeHandles.delete(id);
|
||||
}
|
||||
},
|
||||
opts,
|
||||
);
|
||||
io.observe(el);
|
||||
observeHandles.set(id, io);
|
||||
}
|
||||
});
|
||||
}
|
||||
|
||||
function buildFetchInit(spec) {
|
||||
@@ -921,8 +948,23 @@ function runIntervalEffect(exports, spec, onError) {
|
||||
intervalHandles.set(id, handle);
|
||||
}
|
||||
|
||||
const memoryKV = new Map();
|
||||
|
||||
function storageStore(scope) {
|
||||
if (scope === "cookie") return null;
|
||||
if (scope === "memory" || scope === "mem" || scope === "内存") {
|
||||
return {
|
||||
getItem(key) {
|
||||
return memoryKV.has(key) ? memoryKV.get(key) : null;
|
||||
},
|
||||
setItem(key, value) {
|
||||
memoryKV.set(key, String(value));
|
||||
},
|
||||
removeItem(key) {
|
||||
memoryKV.delete(key);
|
||||
},
|
||||
};
|
||||
}
|
||||
if (typeof localStorage === "undefined") return null;
|
||||
return scope === "session" ? sessionStorage : localStorage;
|
||||
}
|
||||
@@ -1371,12 +1413,24 @@ export async function autoMount(doc) {
|
||||
|
||||
const g = typeof globalThis !== "undefined" ? globalThis : undefined;
|
||||
if (g && g.document) {
|
||||
// Defer WASM boot until after first paint / load so LCP images are not
|
||||
// contending with a ~1.6MB wasm download on the critical path.
|
||||
const start = () => {
|
||||
autoMount(g.document).catch((e) => console.error("marqdo autoMount:", e));
|
||||
const run = () => {
|
||||
autoMount(g.document).catch((e) => console.error("marqdo autoMount:", e));
|
||||
};
|
||||
const schedule = () => {
|
||||
if (typeof g.requestIdleCallback === "function") {
|
||||
g.requestIdleCallback(() => run(), { timeout: 1500 });
|
||||
} else {
|
||||
g.setTimeout(run, 0);
|
||||
}
|
||||
};
|
||||
if (g.document.readyState === "complete") {
|
||||
schedule();
|
||||
} else {
|
||||
g.addEventListener("load", schedule, { once: true });
|
||||
}
|
||||
};
|
||||
if (g.document.readyState === "loading") {
|
||||
g.document.addEventListener("DOMContentLoaded", start);
|
||||
} else {
|
||||
queueMicrotask(start);
|
||||
}
|
||||
start();
|
||||
}
|
||||
@@ -0,0 +1,5 @@
|
||||
{
|
||||
"name": "marqdo-bridge",
|
||||
"private": true,
|
||||
"type": "module"
|
||||
}
|
||||
@@ -185,7 +185,38 @@ fn pack_json(v: &serde_json::Value) -> *mut u8 {
|
||||
ptr::copy_nonoverlapping(len.to_le_bytes().as_ptr(), out, 4);
|
||||
ptr::copy_nonoverlapping(bytes.as_ptr(), out.add(4), bytes.len());
|
||||
}
|
||||
out
|
||||
out
|
||||
}
|
||||
|
||||
/// getrandom `custom` backend for wasm32 — no wasm-bindgen / JS glue imports.
|
||||
/// Preferable to the `js` feature which pulls `__wbindgen_*` and breaks raw mq_* ABI.
|
||||
#[cfg(target_arch = "wasm32")]
|
||||
#[no_mangle]
|
||||
unsafe extern "Rust" fn __getrandom_custom(dest: *mut u8, len: usize) -> u32 {
|
||||
// xorshift64* seeded once; fine for uuid/non-crypto browser host helpers.
|
||||
use std::cell::Cell;
|
||||
thread_local! {
|
||||
static STATE: Cell<u64> = const { Cell::new(0x4d51_5241_4e44_4f21) };
|
||||
}
|
||||
if dest.is_null() || len == 0 {
|
||||
return 0;
|
||||
}
|
||||
let mut s = STATE.with(|c| {
|
||||
let mut v = c.get();
|
||||
if v == 0 {
|
||||
v = 0x4d51_5241_4e44_4f21;
|
||||
}
|
||||
v
|
||||
});
|
||||
let buf = unsafe { std::slice::from_raw_parts_mut(dest, len) };
|
||||
for b in buf.iter_mut() {
|
||||
s ^= s << 13;
|
||||
s ^= s >> 7;
|
||||
s ^= s << 17;
|
||||
*b = (s >> 8) as u8;
|
||||
}
|
||||
STATE.with(|c| c.set(s));
|
||||
0
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
|
||||
Vendored
+22
@@ -0,0 +1,22 @@
|
||||
Marqdo for Ubuntu (PPA)
|
||||
=======================
|
||||
|
||||
This package installs the marqdo CLI (/usr/bin/marqdo).
|
||||
|
||||
Official language extensions are not bundled. After install:
|
||||
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
|
||||
Extension packs download from https://ext.marqdo.com (then GitHub / proxy).
|
||||
|
||||
Install this package from:
|
||||
|
||||
sudo add-apt-repository ppa:cflmy/marqdo
|
||||
sudo apt update
|
||||
sudo apt install marqdo
|
||||
|
||||
Also available: GitHub Releases (Windows/Linux zips) and building from source.
|
||||
|
||||
Documentation: https://github.com/cflmy/marqdo
|
||||
PPA notes: doc/design/ubuntu-ppa.md in the upstream repository.
|
||||
Vendored
+46
@@ -0,0 +1,46 @@
|
||||
marqdo (1.1.0-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.1.0: core surface guard + progressive contracts + MLSP for AI.
|
||||
New `marqdo check` (static contract drift) and `marqdo mlsp` (language
|
||||
server for AI: locate/syntax/validate/repair_targets/schema/repair_apply);
|
||||
`run --json` unified structured diagnostics; contract tables
|
||||
(参数/返回/字段/集合) with four validation boundaries; anchored repair
|
||||
guardrails (bounded line edits, out-of-scope refused).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Wed, 23 Sep 2026 13:30:00 +0800
|
||||
|
||||
marqdo (1.0.7-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.0.7: WS/net boundary hardening (same-origin handshake,
|
||||
require_auth/需要登录, message caps, empty-room GC); HTTP 8 MiB cap
|
||||
enforced while reading; url_encode space -> %20.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Tue, 22 Sep 2026 15:40:00 +0800
|
||||
|
||||
marqdo (1.0.3-1ppa2) noble; urgency=medium
|
||||
|
||||
* Fix Launchpad build: dh_clean -Xvendor/ so cargo vendor checksums keep
|
||||
Cargo.toml.orig (debian-only; reuse published 1.0.3.orig.tar.xz).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 21:28:00 +0800
|
||||
|
||||
marqdo (1.0.3-1ppa1) noble; urgency=medium
|
||||
|
||||
* Marqdo 1.0.3: PPA + ext CDN; unbound GFM tables; bundled Rust for noble.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 10:35:00 +0800
|
||||
|
||||
marqdo (1.0.2-1ppa2) noble; urgency=medium
|
||||
|
||||
* Bundle Rust toolchain in orig (third_party/rust) so noble can build
|
||||
Cargo.lock v4 offline; drop distro cargo/rustc Build-Depends.
|
||||
* Architecture: amd64 (bundled toolchain is x86_64).
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 10:20:00 +0800
|
||||
|
||||
marqdo (1.0.2-1ppa1) noble; urgency=medium
|
||||
|
||||
* Initial Ubuntu PPA packaging for Marqdo 1.0.2.
|
||||
* CLI only; extensions via "marqdo ext add" / ext.marqdo.com.
|
||||
|
||||
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 09:55:00 +0800
|
||||
Vendored
+29
@@ -0,0 +1,29 @@
|
||||
Source: marqdo
|
||||
Section: devel
|
||||
Priority: optional
|
||||
Maintainer: cflmy <pingan@cflmy.cn>
|
||||
Build-Depends:
|
||||
debhelper-compat (= 13),
|
||||
build-essential,
|
||||
pkg-config,
|
||||
libssl-dev,
|
||||
ca-certificates
|
||||
Standards-Version: 4.7.0
|
||||
Homepage: https://github.com/cflmy/marqdo
|
||||
Vcs-Git: https://github.com/cflmy/marqdo.git
|
||||
Vcs-Browser: https://github.com/cflmy/marqdo
|
||||
Rules-Requires-Root: no
|
||||
|
||||
Package: marqdo
|
||||
Architecture: amd64
|
||||
Depends: ${shlibs:Depends}, ${misc:Depends}, ca-certificates
|
||||
Description: Markdown markers as an interpreted programming language
|
||||
Marqdo treats Markdown markers as executable syntax (code / return /
|
||||
control flow). This package installs the marqdo CLI.
|
||||
.
|
||||
Official extensions (web, quantum, …) are installed separately via
|
||||
"marqdo ext add" and download from https://ext.marqdo.com .
|
||||
.
|
||||
Launchpad builds use a bundled Rust toolchain under third_party/rust
|
||||
(Ubuntu noble cargo is too old for Cargo.lock v4). Rebuilds on newer
|
||||
series may use distro rustc if cargo ≥ 1.78.
|
||||
Vendored
+24
@@ -0,0 +1,24 @@
|
||||
Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
|
||||
Upstream-Name: marqdo
|
||||
Upstream-Contact: cflmy <pingan@cflmy.cn>
|
||||
Source: https://github.com/cflmy/marqdo
|
||||
|
||||
Files: *
|
||||
Copyright: 2024-2026 cflmy
|
||||
License: Apache-2.0
|
||||
|
||||
License: Apache-2.0
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
.
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
.
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
.
|
||||
On Debian systems, the complete text of the Apache License version 2
|
||||
can be found in "/usr/share/common-licenses/Apache-2.0".
|
||||
+58
@@ -0,0 +1,58 @@
|
||||
#!/usr/bin/make -f
|
||||
|
||||
export DH_VERBOSE = 1
|
||||
# Offline builds on Launchpad: vendored crates + optional bundled Rust toolchain.
|
||||
export CARGO_HOME = $(CURDIR)/debian/cargo_home
|
||||
export CARGO_NET_OFFLINE = true
|
||||
|
||||
# Noble (and older) distro cargo cannot read Cargo.lock v4 / modern crates.
|
||||
# Prefer third_party/rust from the orig tarball when present (see ppa-build-source.sh).
|
||||
BUNDLED_RUST = $(CURDIR)/third_party/rust
|
||||
ifneq ($(wildcard $(BUNDLED_RUST)/bin/cargo),)
|
||||
export PATH := $(BUNDLED_RUST)/bin:$(PATH)
|
||||
endif
|
||||
|
||||
%:
|
||||
dh $@
|
||||
|
||||
override_dh_auto_configure:
|
||||
mkdir -p debian/cargo_home
|
||||
@if [ -x "$(BUNDLED_RUST)/bin/cargo" ]; then \
|
||||
echo "Using bundled Rust: $$($(BUNDLED_RUST)/bin/rustc --version)"; \
|
||||
else \
|
||||
echo "Using system Rust: $$(rustc --version 2>/dev/null || echo missing)"; \
|
||||
fi
|
||||
@if [ -f "$(CURDIR)/.cargo/config.toml" ] || [ -d "$(CURDIR)/vendor" ]; then \
|
||||
echo "Using vendored Cargo dependencies"; \
|
||||
else \
|
||||
echo "WARNING: no vendor/ — online cargo fetch required (not for Launchpad)"; \
|
||||
fi
|
||||
|
||||
override_dh_auto_build:
|
||||
mkdir -p debian/cargo_home
|
||||
@command -v cargo >/dev/null || { echo "error: cargo not found (bundle third_party/rust or install rustc/cargo)" >&2; exit 1; }
|
||||
if [ -d "$(CURDIR)/vendor" ]; then \
|
||||
CARGO_NET_OFFLINE=true cargo build --release --locked --offline \
|
||||
-p marqdo; \
|
||||
else \
|
||||
cargo build --release --locked -p marqdo; \
|
||||
fi
|
||||
|
||||
override_dh_auto_test:
|
||||
@echo "Skipping full test suite on package build (run cargo test in CI)."
|
||||
|
||||
override_dh_auto_install:
|
||||
install -d $(CURDIR)/debian/marqdo/usr/bin
|
||||
install -m 0755 $(CURDIR)/target/release/marqdo \
|
||||
$(CURDIR)/debian/marqdo/usr/bin/marqdo
|
||||
|
||||
# dh_clean deletes *.orig by default; cargo vendor checksums require
|
||||
# vendor/**/Cargo.toml.orig. Exclude the vendored tree from that purge.
|
||||
override_dh_clean:
|
||||
dh_clean -Xvendor/
|
||||
|
||||
override_dh_auto_clean:
|
||||
dh_auto_clean
|
||||
rm -rf debian/cargo_home
|
||||
# keep vendor/ and third_party/rust (part of source package)
|
||||
-cargo clean
|
||||
Vendored
+1
@@ -0,0 +1 @@
|
||||
3.0 (quilt)
|
||||
Vendored
+2
@@ -0,0 +1,2 @@
|
||||
# Ignore temporary files while editing patches
|
||||
extend-diff-ignore = "^vendor/"
|
||||
@@ -53,6 +53,8 @@
|
||||
| [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(文档驱动:单步 / 多步工作簿 + 自写回;废弃 thin TOOL 循环)** |
|
||||
| [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-cdn.md](design/ext-cdn.md) | **扩展 CDN(R2 / ext.marqdo.com)与分开发版** |
|
||||
| [design/ubuntu-ppa.md](design/ubuntu-ppa.md) | **Ubuntu PPA 打包与上传** |
|
||||
| [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** |
|
||||
|
||||
@@ -0,0 +1,47 @@
|
||||
# 核心表面清单(core-surface)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 核心语法封闭集合(CI 守卫锁定)** |
|
||||
| 日期 | 2026-09-22 |
|
||||
| 守卫 | `tests/core_surface.rs` ⇄ `src/parse/mod.rs` `CORE_CONSTRUCTS`(改动任一侧不同步 → CI 红) |
|
||||
| 相关 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)(语义宪法)· [layers.md](layers.md)(准入戒律)· [three-problems.md](../roadmap/three-problems.md) 问题一 · [three-problems-plan.md](../roadmap/three-problems-plan.md) T1.1/T1.3 |
|
||||
|
||||
> **戒律总纲**:核心标记是**封闭集合**(约 19 个构造)。新增任何一行必须走 ADR(见 [layers.md](layers.md) 准入戒律)并回答「为什么现有标记不够」;生态需求的默认答案是**进 ext**。本表 id 列与守卫测试强一致:改表不同步 `CORE_CONSTRUCTS`(或反之)、样例文件缺失,一律 CI 红。
|
||||
|
||||
## 1. 行构造
|
||||
|
||||
| id | 外形 | 语义 | 戒律 | 样例 |
|
||||
|----|------|------|------|------|
|
||||
| `narrative` | 无标记文字 | 叙述(注释) | 段落内延续到空行;**默认安全**——永远不存在「叙述被执行」的路径 | `tests/markup-v03/soft-emphasis.mq.md` |
|
||||
| `blank` | 空行 | 段落边界 | 叙述分段的唯一手段;不得被赋予其它语义 | `tests/markup-v03/inc-prose.mq.md` |
|
||||
| `heading-unit` | `#` / `##` | 对象 / 函数单元 | 标题即单元边界,按深度嵌套;正文禁止用 `##` 做版式(会变成函数) | `tests/markup-v03/decl-ident-only.mq.md` |
|
||||
| `call-line` | `>` | 调用行 | 输出等副作用 = **普通函数**,不是架构标记 | `tests/markup-v03/dual-call.mq.md` |
|
||||
| `branch-list` | 体内 `1.` 递增 | 分支 | 自 `1.` 起序号递增构成一个判断;重出 `1.` 开新判断;`N. *` = else;**不是所有有序列表都是 if** | `tests/markup-v03/greet-default.mq.md` |
|
||||
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [项](集合)` | `tests/structure/loop.mq.md` |
|
||||
| `param` | `` + `名` `` | 形参(兼容形) | 首选叙述 `` `名` `` 升参(宪法 §8);`+` 形仅兼容保留 | `tests/markup-v03/greet-default.mq.md` |
|
||||
| `table` | GFM 表 | 集合 | 几何即类型([tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md));**绑定 = 数据,未绑定 = 文档表** | `tests/structure/collection.mq.md` |
|
||||
| `fence` | ` ```lang ` | 外联 | 语言块原样外联,不进 Marqdo 语义 | `tests/lib/foreign-python.mq.md` |
|
||||
| `hr` | 单行 `---` 或 `***` | 叙述分隔 | **不收束函数**(返回才收束) | `tests/markup-v03/module-hr.mq.md` |
|
||||
| `writeback` | `<!-- marqdo-out … -->` | 持久化输出 | 只读回放,不执行 | `tests/lib/writeback-get.mq.md` |
|
||||
|
||||
## 2. 内联标记
|
||||
|
||||
| id | 外形 | 语义 | 戒律 | 样例 |
|
||||
|----|------|------|------|------|
|
||||
| `ident` | `` `名` `` | 声明 / 引用 | 首次未赋值 = 声明;叙述与程序共用同一视觉习惯 | `tests/markup-v03/decl-ident-only.mq.md` |
|
||||
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 只有粗体进入执行;判别序:赋值 → 调用 → 表达式 | `tests/markup-v03/multi-bold.mq.md` |
|
||||
| `italic-return` | `*…*` | 返回 | 改变控制流(**返回是架构**);返回即结束函数体 | `tests/markup-v03/inc-prose.mq.md` |
|
||||
| `empty-return` | `*None*` / `****` | 空返回 | 返回 `None` 并结束函数体 | `tests/markup-v03/empty-return-none.mq.md` |
|
||||
| `link-index` | `[键](集合)` | 取元 / foreach | **主取元语法**;与 bracket-call 靠 `]` 后是否紧邻 `(` 消歧 | `tests/lib/table-collections.mq.md` |
|
||||
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;与 link-index 消歧同上 | `tests/structure/bracket-call.mq.md` |
|
||||
| `footnote-index` | `集合[^键]` | 过渡取元 | **仅兼容**;新代码一律写 link-index | `tests/structure/footnote-index.mq.md` |
|
||||
| `soft-emphasis` | `*仅*` / `**说明**` | 忽略 | 非代码形强调**不执行**——默认安全的关键消歧规则 | `tests/markup-v03/soft-emphasis.mq.md` |
|
||||
|
||||
## 3. 词法大类(LineKind,`src/lex/mod.rs`)
|
||||
|
||||
行级入口只有四个大类:`Blank` / `Comment`(叙述段落,含软强调与行内 `` `名` ``)/ `Writeback` / `Code`(`# * > + - | ~ $` 或数字开头)。本清单第 1 节的行构造是在 `Code`(及 `Comment`/`Writeback`)内部的**语义细分**;第 2 节内联标记由 `src/parse/prose.rs` 行内扫描产出。两层合起来 = 核心表面全集。
|
||||
|
||||
## 4. 范围外(进 Language 层,但不在本守卫)
|
||||
|
||||
frontmatter YAML(元信息)与 `import` 行(模块装载)属于 Language 层的其它语言面,随 [layers.md](layers.md) 准入流程登记,暂不进本清单守卫;如需一并守卫,走 ADR 扩表。
|
||||
@@ -0,0 +1,66 @@
|
||||
# Extension CDN (Cloudflare R2 → https://ext.marqdo.com)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted** — download prefer CDN; upload via `scripts/upload-ext-r2.py` |
|
||||
| Date | 2026-09-17 |
|
||||
| Related | [ext-cli.md](ext-cli.md) · [marqdo-release](../../.cursor/skills/marqdo-release/SKILL.md) |
|
||||
|
||||
## Why
|
||||
|
||||
CLI (语法解释器) and official **extension packs** (`ext/` L1 + native plugins) update on different cadences. Users behind unstable GitHub links should get packs from a stable object store first.
|
||||
|
||||
## Public URL layout
|
||||
|
||||
Bucket: `marqdo` · Custom domain: **https://ext.marqdo.com**
|
||||
|
||||
| Key | Meaning |
|
||||
|-----|---------|
|
||||
| `v{VER}/marqdo-{VER}-ext.zip` | L1 sources |
|
||||
| `v{VER}/marqdo-{VER}-native-{triple}.zip` | Prebuilt plugins |
|
||||
| `v{VER}/VERSION` | Pack SemVer echo |
|
||||
| `latest/VERSION` | Recommended pack SemVer (plain text) |
|
||||
| `latest/marqdo-…zip` | Same assets mirrored for convenience |
|
||||
|
||||
`{VER}` is the **extension pack** version (`ext/VERSION`), which **may differ** from CLI `Cargo.toml` version.
|
||||
|
||||
## Client download order (`marqdo ext add`)
|
||||
|
||||
1. `MARQDO_EXT_DOWNLOAD_BASE` (optional override)
|
||||
2. **CDN** `https://ext.marqdo.com/v{VER}/…` (override host with `MARQDO_EXT_CDN`)
|
||||
3. GitHub Releases
|
||||
4. `https://proxy.cflmy.top/github.com/…`
|
||||
|
||||
Pack SemVer resolution (`release_version()`):
|
||||
|
||||
1. `MARQDO_EXT_VERSION`
|
||||
2. CDN `GET …/latest/VERSION` (short timeout)
|
||||
3. Embedded `ext/VERSION` at build time
|
||||
4. CLI `CARGO_PKG_VERSION`
|
||||
|
||||
## Separate ext release (no CLI bump)
|
||||
|
||||
1. Bump `ext/VERSION` (e.g. `1.0.3`) — leave root `Cargo.toml` alone if CLI unchanged.
|
||||
2. Build native zips (CI Linux/Windows jobs or local `scripts/build-web-plugin.sh` + cargo plugins).
|
||||
3. Package `marqdo-{VER}-ext.zip` and `marqdo-{VER}-native-*.zip`.
|
||||
4. Upload **both**:
|
||||
- R2: `python3 scripts/upload-ext-r2.py --version VER --from-dir dist/`
|
||||
- GitHub: attach to a GitHub Release (tag `ext-vVER` **or** reuse latest CLI release assets)
|
||||
5. Confirm `https://ext.marqdo.com/latest/VERSION` and a sample zip URL return 200.
|
||||
|
||||
## Full product release (CLI + ext)
|
||||
|
||||
Keep `ext/VERSION` equal to (or compatible with) CLI SemVer unless documenting a deliberate skew. CI still publishes GitHub assets; **after** CI green, run `upload-ext-r2.py` so CDN is populated (or add a CI step with R2 secrets).
|
||||
|
||||
## Credentials
|
||||
|
||||
| Where | What |
|
||||
|-------|------|
|
||||
| Local | `~/.marqdo/r2.env` (`chmod 600`) — see `.env.r2.example` |
|
||||
| CI (optional) | GitHub Actions secrets: `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_ENDPOINT`, `R2_BUCKET` |
|
||||
|
||||
**Never** commit Account API tokens or S3 secret keys. If a token was pasted into chat, **rotate** it in the Cloudflare dashboard.
|
||||
|
||||
## Object ACL
|
||||
|
||||
Custom domain public reads require the bucket/objects to be publicly readable (R2 public bucket / r2.dev / custom domain). Uploads use S3 API credentials; downloads by `ext add` are anonymous HTTPS GETs.
|
||||
@@ -51,10 +51,16 @@ L1 sources:
|
||||
|
||||
| Variable | Meaning |
|
||||
|----------|---------|
|
||||
| `MARQDO_EXT_VERSION` | Override SemVer used for Release asset names (default: CLI `CARGO_PKG_VERSION`) |
|
||||
| `MARQDO_EXT_VERSION` | Override **extension pack** SemVer (default: CDN `latest/VERSION` → embedded `ext/VERSION` → CLI version) |
|
||||
| `MARQDO_EXT_CDN` | Public CDN base (default `https://ext.marqdo.com`) |
|
||||
| `MARQDO_EXT_NO_DOWNLOAD=1` | Never hit the network (CI / air-gap); local/cargo only |
|
||||
| `MARQDO_EXT_DOWNLOAD_BASE` | Optional extra base tried **before** CDN |
|
||||
| `MARQDO_WEB_PLUGIN` / `MARQDO_AGENT_PLUGIN` / `MARQDO_QUANTUM_PLUGIN` | Explicit native path |
|
||||
|
||||
Download order for each Release asset: `MARQDO_EXT_DOWNLOAD_BASE` → **CDN `ext.marqdo.com`** → `github.com` → **`proxy.cflmy.top`**. Connect timeout 20s; read timeout 10min.
|
||||
|
||||
See [ext-cdn.md](ext-cdn.md) for R2 layout, separate ext releases, and `scripts/upload-ext-r2.py`.
|
||||
|
||||
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)
|
||||
|
||||
@@ -0,0 +1,19 @@
|
||||
# Collaborative document MVP
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · MVP (LWW)** |
|
||||
| 日期 | 2026-09-17 |
|
||||
|
||||
## Approach
|
||||
|
||||
Not a full CRDT. Peers sync plain text over `route_ws mode=room` with:
|
||||
|
||||
- Client → server: `DOC\\t<body>`
|
||||
- Server fan-out (existing G-WS1/2)
|
||||
- Apply remote if body ≠ local; `applying` flag suppresses echo
|
||||
- Presence JSON on `room.presence` (`presence=True`)
|
||||
|
||||
## Demo
|
||||
|
||||
`examples/web-collab-doc/` — open two browsers on the same room.
|
||||
@@ -0,0 +1,81 @@
|
||||
# `ext/web` 可配置 RBAC(角色 ⊥ 权限)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 验收 | qdqc:门禁 `desk:access` + 评论权限;`tests/ext/web-rbac-*-smoke.mq.md` |
|
||||
| 状态 | **Accepted · 已落地核心**(gate permissions;`/_rbac/*` 管理台 **opt-in** `管理台=真`) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
权限是原子能力(`resource:action`);角色是权限包;用户通过 `user_roles` 获得角色。门禁与业务都问 `can(user, permission)`。管理员可在后台新建角色、勾选权限、赋给用户——**禁止**只靠写死的 `role=admin|user` 字符串作为唯一模型(兼容期仍可读旧 `roles=` gate)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 表结构(SQLite / Postgres 同构)
|
||||
|
||||
| 表 | 列 |
|
||||
|----|-----|
|
||||
| `web_permissions` | `code` PK, `resource`, `action`, `description` |
|
||||
| `web_roles` | `id` PK, `name` UNIQUE, `is_system` INT, `tenant_id` TEXT NULL |
|
||||
| `web_role_permissions` | `role_id`, `permission_code` PK(role_id, permission_code) |
|
||||
| `web_user_roles` | `user_id`, `role_id`, `tenant_id` TEXT NULL, PK(user_id, role_id, tenant_id) |
|
||||
| `web_users` | `id` PK, `username` UNIQUE, `password_hash`, `created_at` |
|
||||
|
||||
命名带 `web_` 前缀,避免与业务表冲突。站点也可映射自定义表名(后期);首版固定。
|
||||
|
||||
---
|
||||
|
||||
## 2. 权限码约定
|
||||
|
||||
形如 `comments:create`、`desk:access`、`roles:manage`。内置种子见 `DefaultCatalog`。`*` 或角色名 `superadmin` / 兼容 `admin`:登录时展开为目录全集。
|
||||
|
||||
---
|
||||
|
||||
## 3. 作者 API
|
||||
|
||||
```markdown
|
||||
**`应用` = > `应用`.权限 确保结构=真 目录=`权限目录`**
|
||||
**`应用` = > `应用`.门禁 路径="/desk" 权限="desk:access" 匹配="prefix" 拒绝="redirect"**
|
||||
**`应用` = > `应用`.鉴权 用户表=`管理员` 注册=真 注册路径="/register" …**
|
||||
```
|
||||
|
||||
| 方法 | ABI | 说明 |
|
||||
|------|-----|------|
|
||||
| `app.rbac` / `启用权限` | `web_app_rbac` | ensure schema;可选 `目录`;`管理台=真` 才挂 `/_rbac/*` |
|
||||
| `app.gate` | `web_app_gate` | 新增 `permissions`/`权限`(CSV);与 `roles` 可并存:有 permissions 时按权限判定 |
|
||||
| `rbac.can` | `web_rbac_can` | `{ok, allowed}` |
|
||||
| `rbac.assign_role` | `web_rbac_assign_role` | 用户←角色 |
|
||||
| `rbac.set_role_permissions` | `web_rbac_set_role_permissions` | 角色←权限列表 |
|
||||
|
||||
防提权:`set_role_permissions` / `assign_role` 在 HTTP 管理面检查操作者 `roles:manage` 且不能授予自身没有的 permission。
|
||||
|
||||
---
|
||||
|
||||
## 4. 运行时
|
||||
|
||||
1. `listen`:若 `auth.rbac=true` 或调用过 `app.rbac`,对 `db` URL `EnsureSchema` + 种子。
|
||||
2. 仅当 `auth.rbac_desk=true`(`启用权限 管理台=真`)时挂载 `/_rbac/*` API 与 desk。
|
||||
3. 登录成功:解析角色 → DB `user_roles` ∪ GFM 角色展开 → session `permissions`(CSV)+ 兼容 `role`。
|
||||
4. `withRBAC`:gate 含 `permissions` 则 `PermissionAllowed`;否则旧 `RoleAllowed`。
|
||||
5. 注册:`POST /register` 写入 `web_users`,默认赋 `member` 角色。
|
||||
|
||||
---
|
||||
|
||||
## 5. qdqc 映射
|
||||
|
||||
| 产品 | 权限码 |
|
||||
|------|--------|
|
||||
| 发评论 | `comments:create` |
|
||||
| 删任意评论 | `comments:delete` |
|
||||
| 进 desk | `desk:access` |
|
||||
| 管角色 | `roles:manage` |
|
||||
|
||||
首个 GFM `admin` 用户登录后视为 `superadmin`(全权限);DB 迁移后绑定 `superadmin` 角色。
|
||||
|
||||
---
|
||||
|
||||
## 6. 非目标(本切片)
|
||||
|
||||
对象级 ACL 全图、ABAC;租户列先可空,多租户波次再启用。
|
||||
@@ -0,0 +1,91 @@
|
||||
# ext/web:请求上下文与表单字段来源
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted** |
|
||||
| 日期 | 2026-09-18 |
|
||||
| 相关 | [ext-web.md](ext-web.md) §5.5 · 对照 Django `request.user` / URL kwargs |
|
||||
| 动机 | 禁止扩展库按业务表名(如 `comments`)特判填字段;身份与路由键属于请求上下文 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 原则
|
||||
|
||||
1. **扩展库提供机制,站点表达领域** — 不得出现 `if table == "comments"`。
|
||||
2. **身份只从 session 来,且服务端盖戳** — 客户端提交的 `author` 等不可信。
|
||||
3. **资源键从路由参数来** — 页面已在 `/post/{slug}` 时,表单继承该页 `params`,不解析 Referer 猜 slug。
|
||||
4. **非 `client` 来源的字段默认不渲染** — 服务端在校验前写入;若 POST 带同名键,一律覆盖丢弃。
|
||||
|
||||
---
|
||||
|
||||
## 1. 请求上下文(Request)
|
||||
|
||||
每次处理 HTTP 请求时,框架逻辑上持有:
|
||||
|
||||
| 键 | 含义 |
|
||||
|----|------|
|
||||
| `user` / `username` | 登录名;访客为空 |
|
||||
| `params` | 动态路由捕获(如 `{slug}`) |
|
||||
| `path` | 请求路径 |
|
||||
| `method` | GET / POST / … |
|
||||
| `query` | URL 查询(可选) |
|
||||
|
||||
与 Django 对应:`request.user`、`request.resolver_match.kwargs`、`request.path`。
|
||||
|
||||
页面渲染时已有 `page.params`(`injectParams`)。表单提交时通过隐藏字段 `_mq_params`(JSON)与 `_mq_return`(回跳路径)把**渲染该表单时的页上下文**带回 POST,避免依赖 Referer。
|
||||
|
||||
---
|
||||
|
||||
## 2. 字段表「来源」列
|
||||
|
||||
字段表增加可选列 `来源` / `source`(缺省 = `client`):
|
||||
|
||||
```markdown
|
||||
| 字段 | 标签 | 类型 | 必填 | 默认 | 来源 |
|
||||
|------|------|------|------|------|------|
|
||||
| body | 写下你的想法 | textarea | true | | client |
|
||||
| author | | | true | | session.username |
|
||||
| post_slug | | | true | | route.slug |
|
||||
| created_at | | | false | | now |
|
||||
```
|
||||
|
||||
| 来源值 | 含义 | 渲染 |
|
||||
|--------|------|------|
|
||||
| `client` / 空 | 用户填写 | 正常控件 |
|
||||
| `session.username` / `session.user` / `user` | 当前登录用户名 | 不渲染 |
|
||||
| `route.NAME` / `param.NAME` / `params.NAME` | `params[NAME]` | 不渲染 |
|
||||
| `now` / `utc.now` / `server.now` | UTC `YYYY-MM-DD HH:MM:SS` | 不渲染 |
|
||||
|
||||
`类型=hidden` 仍可显式使用;与 `来源≠client` 叠加时仍不依赖客户端值(服务端覆盖)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 提交管线
|
||||
|
||||
```
|
||||
ParseForm → 去掉来源≠client 的 POST 键
|
||||
→ 按字段来源从 Request 写入
|
||||
→ validate → insert/update
|
||||
→ 回跳:优先 _mq_return(同站路径),否则 form.redirect
|
||||
```
|
||||
|
||||
伪造 `author` / `post_slug` 无效。
|
||||
|
||||
---
|
||||
|
||||
## 4. 页面列表装配(副绑定)
|
||||
|
||||
详情页可附加与主主体**不同查询条件**的列表绑定(如评论):
|
||||
|
||||
```markdown
|
||||
**post = > post.列表装配 主体=`评论卡片` 条件=`评论条件` 排序="-created_at"**
|
||||
```
|
||||
|
||||
条件值同样支持 `{slug}`。渲染在主文章/卡片区之后,无需为子资源单独写 JSON API + 前端过滤。
|
||||
|
||||
---
|
||||
|
||||
## 5. 非目标
|
||||
|
||||
- 不在扩展库内实现「评论」领域类型。
|
||||
- 不把 Referer 解析当作正式 params 来源(仅兼容期可作 `_mq_params` 缺失时的弱回退,金样不依赖)。
|
||||
@@ -0,0 +1,24 @@
|
||||
# Native SPA(Marqdo WASM 全页客户端)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · MVP** |
|
||||
| 日期 | 2026-09-17 |
|
||||
| 相关 | [browser-marqdo-wasm.md](browser-marqdo-wasm.md) · route D/E |
|
||||
|
||||
## 约定
|
||||
|
||||
| 表 | 列 | 用途 |
|
||||
|----|-----|------|
|
||||
| 客户端路由 | `路径` / `面板` / `标题` | 文档化视图;运行时用 `path` + `set_attr(hidden)` 切换 |
|
||||
| 客户端状态 | `browser.store_set` / `store_get` `scope=memory` | 页内状态(列表 JSON、当前 id) |
|
||||
|
||||
作者零业务 JS:`web.client_embed` + `static/client.mq.md` + `lib/browser`。
|
||||
|
||||
## Bridge
|
||||
|
||||
`storage` effect 支持 `scope=memory`(进程内 `Map`),与 `local` / `session` / `cookie` 并列。
|
||||
|
||||
## Demo
|
||||
|
||||
`examples/web-spa-app/` — 列表 → 详情 → 编辑,全客户端路由。
|
||||
@@ -0,0 +1,23 @@
|
||||
# ext/web multi-tenant (path / subdomain / header)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · MVP** |
|
||||
| 日期 | 2026-09-17 |
|
||||
| 相关 | [ext-web-rbac.md](ext-web-rbac.md) · full-ambition plan |
|
||||
|
||||
## Author API
|
||||
|
||||
```markdown
|
||||
**应用 = > `应用`.tenant mode="path" param="t" column="tenant_id" default_scope=False**
|
||||
```
|
||||
|
||||
JSON route table may set `tenant_scope` / `租户作用域` = true so `GET /api/items?t=acme` only returns rows with `tenant_id=acme`.
|
||||
|
||||
## Runtime
|
||||
|
||||
1. `withTenant` resolves id into request context.
|
||||
2. Scoped JSON selects `AND tenant_id=?`; missing tenant → 400.
|
||||
3. `default_scope=True` also stamps form POST bodies.
|
||||
|
||||
Demo: `examples/web-tenant-saas/`.
|
||||
@@ -3,8 +3,8 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · W0–W7 + P3 + W8(站点图标/Head/图片装配)完结**(SQLite/Postgres 作者面:页面装配 / db CRUD+`where` / form / 嵌入主区 / `app.route` / 路由 `/_part` / admin UI / RBAC / 上传相册 / SEO·RSS·sitemap / **favicon·头资源·图片装配**;Postgres 等见 §9) |
|
||||
| 日期 | 2026-08-11(W8:2026-08-29) |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [stdlib-i18n.md](stdlib-i18n.md) · [web-assets-and-images.md](web-assets-and-images.md) |
|
||||
| 日期 | 2026-08-11(W8:2026-08-29;请求上下文:2026-09-18) |
|
||||
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [stdlib-i18n.md](stdlib-i18n.md) · [web-assets-and-images.md](web-assets-and-images.md) · **[ext-web-request-context.md](ext-web-request-context.md)** |
|
||||
| 安装(目标) | `marqdo ext add web`(中英:`web` / `网页`) |
|
||||
| 本文目的 | 锁定**作者面**与**类 API**;指导实现 |
|
||||
|
||||
@@ -247,6 +247,7 @@ import db:db/index.mq.md
|
||||
|------|------|
|
||||
| compose_components / 组件装配 | 解析组件·样式路径 → 填 nav/sidebar/footer → CSS → 登记 part |
|
||||
| compose_main / 主体装配 | 解析库字段与样式路径 → 填 main → 登记 part(如 id=`index`) |
|
||||
| compose_list / 列表装配 | 副绑定(独立 query/order);可选 target 注入引言元素;见 [ext-web-request-context.md](ext-web-request-context.md) |
|
||||
|
||||
**槽位推断:** 由组件导出名决定(`nav`→顶栏,`side`→侧栏,`foot`→底栏;其余→main)。
|
||||
|
||||
@@ -423,6 +424,7 @@ import db:db/index.mq.md
|
||||
| `类型` | 控件/值类型:`text` `textarea` `number` `email` `url` `checkbox` `select` … |
|
||||
| `必填` | 是否必填 |
|
||||
| `默认` | 可选默认值 |
|
||||
| `来源` / `source` | 可选;见 [ext-web-request-context.md](ext-web-request-context.md):`client`(默认)/ `session.username` / `route.NAME` / `now`;非 client 不渲染且服务端盖戳 |
|
||||
|
||||
#### 5.5.2 校验表(作者面)
|
||||
|
||||
@@ -580,7 +582,9 @@ submit → action=insert → db.insert;action=update → db.update
|
||||
## 9. 非本波次(可记入路线图)
|
||||
|
||||
- Postgres / Redis / S3 驱动细节(SQLite 已落地);
|
||||
- 复杂权限与多租户;
|
||||
- ~~复杂权限与多租户~~ → **可配置 RBAC** 见 [ext-web-rbac.md](ext-web-rbac.md);**多租户** 见 [ext-web-tenant.md](ext-web-tenant.md)(path/subdomain/header + `tenant_scope`);
|
||||
- ~~重客户端 SPA~~ → **Native SPA** 见 [ext-web-spa.md](ext-web-spa.md)(WASM + 路由表 + `store_set` memory);
|
||||
- ~~实时协同编辑~~ → **Collab MVP** 见 [ext-web-collab.md](ext-web-collab.md)(WS room LWW 文本 + presence);
|
||||
- 子页路由糖的更多约定(`# 应用.route` 已够用)。
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# 三层归属与准入戒律(layers)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 准入制度(问题一落地)** |
|
||||
| 日期 | 2026-09-22 |
|
||||
| 相关 | [core-surface.md](core-surface.md)(核心表面守卫)· [three-problems.md](../roadmap/three-problems.md) 问题一 · [three-problems-plan.md](../roadmap/three-problems-plan.md) T1.2 |
|
||||
|
||||
> **目的**:语言核心保持小——**Language / Runtime / Document 三层分明,生态功能不淹没语言身份**。本制度是机制不是宣言:违反即 CI 红 / PR 不评审。
|
||||
|
||||
## 1. 三层归属表
|
||||
|
||||
| 层 | 内容 | 仓库位置 |
|
||||
|----|------|----------|
|
||||
| **Language** | 标记映射、词法/行分类、AST、语义、升参、契约检查器、诊断 | `src/lex/` `src/parse/` `src/ast.rs` `src/interp.rs` `src/diagnostics.rs`(及 `contract`/`check`)· 宪法 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [core-surface.md](core-surface.md) |
|
||||
| **Runtime** | stdlib、插件 ABI、WASM、debugger、view、catalog / schema / mcp CLI、字节码后端 | `lib/` `plugins/` `crates/` `src/catalog.rs` `src/view/` `src/debug/` `src/builtin.rs` `src/bytecode/` |
|
||||
| **Document** | 知识单元、AI skills、示例、官方扩展、用户站 | `*.mq.md` `skills/` `ext/` `public/` `examples/` `doc/` |
|
||||
|
||||
## 2. 准入戒律
|
||||
|
||||
1. **先填层归属**:任何新特性提案(issue / PR / 设计文档)必须先声明进哪层;未填 = 不评审。
|
||||
2. **Language 层变更 = ADR**:新增核心标记必须有 `doc/adr/` 编号 + 「为什么现有标记不够」+ [core-surface.md](core-surface.md) 增行 + 样例 + `CORE_CONSTRUCTS` 同步(缺任一 → CI 守卫红)。
|
||||
3. **核心计数只许持平或下降**:每个 release 的核心标记计数不得增长;确需增长即触发 Language 层复盘(ADR 里写明不可替代理由)。
|
||||
4. **默认进 ext**:能用扩展、stdlib、插件解决的,一律不进核心。
|
||||
5. **CHANGELOG 单列「核心表面 Δ」**:每个 release 写明增删(无 Δ 写「无」);发版 checklist(`.cursor/skills/marqdo-release/SKILL.md`)含此步。
|
||||
|
||||
## 3. PR 模板
|
||||
|
||||
`.github/PULL_REQUEST_TEMPLATE.md` 含「层归属」必填项与「核心表面」勾选——与本制度一一对应。
|
||||
@@ -211,7 +211,7 @@ v0.3:
|
||||
| 体内 `1.` `2.` … | 分支 |
|
||||
| 体内 `-` | 循环 |
|
||||
| `N. *` | else 臂(此处 `*` 仍是「空条件」标记,**不是**返回值;见 §7.3) |
|
||||
| GFM 表格 | 集合(不变) |
|
||||
| GFM 表格 | 集合;`` `名` = `` 后绑定,或**未绑定**时求值后丢弃(文档中可写表) |
|
||||
| 表达式 `[键](集合)` | **取元**(与 foreach 同形;见 [collection-access-link.md](collection-access-link.md)) |
|
||||
| `修饰… [函数名] 实参…` | **方括号标记调用**(前置修饰 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md)) |
|
||||
| `` 集合[^键] `` | **过渡**:旧脚注取元(仍可用) |
|
||||
|
||||
@@ -0,0 +1,85 @@
|
||||
# Ubuntu PPA packaging (Marqdo)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Active** — `ppa:cflmy/marqdo`; noble builds need bundled Rust (Cargo.lock v4) |
|
||||
| Maintainer | cflmy \<pingan@cflmy.cn\> |
|
||||
| GPG | `505943294D04C803` (fingerprint `52A1…C803`) |
|
||||
| PPA | `ppa:cflmy/marqdo` |
|
||||
|
||||
## Goal
|
||||
|
||||
Users install with:
|
||||
|
||||
```bash
|
||||
sudo add-apt-repository ppa:cflmy/marqdo
|
||||
sudo apt update
|
||||
sudo apt install marqdo
|
||||
```
|
||||
|
||||
CLI and extension packs stay independent: the `.deb` ships the **interpreter**; `marqdo ext add …` still pulls from **https://ext.marqdo.com** (then GitHub / proxy).
|
||||
|
||||
## Why bundled Rust?
|
||||
|
||||
Ubuntu **noble** ships cargo/rustc **1.75**, which cannot parse **Cargo.lock version 4** (`lock file version 4 requires -Znext-lockfile-bump`). Launchpad builders also have **no network**, so `ppa-build-source.sh` vendors crates **and** installs a modern toolchain into `third_party/rust` inside the `.orig.tar.xz`. `debian/rules` prefers that toolchain over distro cargo.
|
||||
|
||||
## One-time Launchpad setup
|
||||
|
||||
1. Create PPA: https://launchpad.net/~cflmy/+activate-ppa → name e.g. `marqdo`
|
||||
2. OpenPGP key already on Launchpad (done)
|
||||
3. Sign Ubuntu Code of Conduct if Launchpad asks
|
||||
4. Enable the Ubuntu **series** you upload for (e.g. noble) under PPA → Change details
|
||||
5. On the build machine:
|
||||
|
||||
```bash
|
||||
sudo apt install build-essential debhelper devscripts dput lintian \
|
||||
dpkg-dev quilt cargo rustc pkg-config curl xz-utils
|
||||
```
|
||||
|
||||
## Package layout
|
||||
|
||||
| File | Role |
|
||||
|------|------|
|
||||
| `debian/control` | Metadata (amd64; no distro cargo BD) |
|
||||
| `debian/changelog` | Upload revisions (`1ppaN`) |
|
||||
| `debian/rules` | `dh` + bundled/system cargo build |
|
||||
| `scripts/ppa-build-source.sh` | Vendor + bundle Rust + `debuild -S` |
|
||||
| `scripts/ppa-ship.sh` | apt deps + build + `dput` |
|
||||
|
||||
## Versioning
|
||||
|
||||
- Upstream SemVer: `Cargo.toml` / git tag `vX.Y.Z`
|
||||
- Debian revision: `X.Y.Z-1ppaN~SERIES` (SERIES = `noble`, …) — bump `1ppaN` on packaging-only reuploads
|
||||
- **Ext pack** SemVer (`ext/VERSION`) is **not** the deb version
|
||||
|
||||
## One-shot (recommended)
|
||||
|
||||
```bash
|
||||
cd ~/work/marqdo
|
||||
./scripts/ppa-ship.sh noble # tools → debuild -S → dput
|
||||
./scripts/ppa-ship.sh noble -n # build only
|
||||
```
|
||||
|
||||
If automation cannot enter sudo/GPG, tell the user these commands (do not invent alternatives):
|
||||
|
||||
```bash
|
||||
./scripts/ppa-build-source.sh noble
|
||||
dput ppa:cflmy/marqdo ../build-area/marqdo_*~noble_source.changes
|
||||
```
|
||||
|
||||
Watch: https://launchpad.net/~cflmy/+archive/ubuntu/marqdo/+builds
|
||||
|
||||
## Failure notes
|
||||
|
||||
| Symptom | Fix |
|
||||
|---------|-----|
|
||||
| `lock file version 4 requires -Znext-lockfile-bump` | Rebuild with current `ppa-build-source.sh` (bundles Rust); bump `1ppaN` |
|
||||
| `failed to calculate checksum of: …/vendor/…/Cargo.toml.orig` | `dh_clean` purged `*.orig`; fixed via `dh_clean -Xvendor/` (+ strip `.orig` only when **creating a new** orig); bump `1ppaN` with **`-sd`** |
|
||||
| `orig.tar.xz already exists … different contents` | Never rewrite an uploaded upstream `.orig`; reuse PPA file (`ppa-build-source.sh` downloads it) and `debuild -S -sd` |
|
||||
| Same version rejected by Launchpad | Bump `debian/changelog` (`1ppa2`, …) |
|
||||
| Wrong series | Enable series on PPA; rebuild with that series name |
|
||||
|
||||
## Out of scope (v1 deb)
|
||||
|
||||
- Shipping `ext/native/*.so` inside the deb (use CDN `ext add`)
|
||||
- WASM / VSIX / non-amd64
|
||||
+1373
File diff suppressed because it is too large.
Load diff
+933
@@ -0,0 +1,933 @@
|
||||
这是marqdo的智能体框架,我一直都不满意,我认为marqdo的智能体框架应该更好才对,因为marqdo本身就是一门极好的AI原生语言,针对这个智能体框架,我的构想是,每次执行,智能体都会沉淀mq.md文档,超过三次的调用就会自动总结优化出一份类似与记忆的mq.md文档,把每一步都拆解的非常好,类似与人类的某些学习过程,当完全学习到了一些内容,实际上后续就可以不再每次都聚精会神,而是用一种较低能耗运行,就像是我们沉淀下来的mq.md代码,其中可以使用非常少的大模型思考,或者使用类似Jev的决策模型,或者干脆只使用分支控制,之后调用即可,你觉得呢?
|
||||
|
||||
对,而且我现在觉得你这个构想**很可能比目前的 Agent 框架本身更接近 Marqdo 真正应该成为的东西**。
|
||||
|
||||
我仔细看了你上传的 `ext/ai/agent`。其实你已经无意中铺好了不少基础:现在的 `plan` 已经有 `reuse`、`near_match`、`soft_match`、`promote`、`improve_every=3` 和 `kb_dir=.marqdo/agent-kb`;命中已有 skill 后甚至可以走 `llm_free` 路径。 而且现有逻辑已经会把成功的 workbook promote 到 agent KB。
|
||||
|
||||
**所以我觉得你现在缺的不是“memory”,而是一个更深的概念:Learning → Compilation。**
|
||||
|
||||
---
|
||||
|
||||
# 1. 我会把你想做的东西定义成:Agent 的“认知编译”
|
||||
|
||||
你描述的人类学习过程非常准确:
|
||||
|
||||
```text
|
||||
第一次:
|
||||
仔细思考
|
||||
↓
|
||||
尝试
|
||||
↓
|
||||
犯错
|
||||
↓
|
||||
修正
|
||||
|
||||
第二次:
|
||||
仍然需要思考
|
||||
↓
|
||||
但已经有经验
|
||||
|
||||
第三次:
|
||||
开始形成套路
|
||||
|
||||
多次之后:
|
||||
“我知道怎么做了”
|
||||
↓
|
||||
不再重新思考
|
||||
↓
|
||||
直接执行
|
||||
```
|
||||
|
||||
传统 Agent:
|
||||
|
||||
```text
|
||||
User
|
||||
↓
|
||||
LLM
|
||||
↓
|
||||
Tool
|
||||
↓
|
||||
LLM
|
||||
↓
|
||||
Tool
|
||||
↓
|
||||
LLM
|
||||
```
|
||||
|
||||
每次任务都重新付出推理成本。
|
||||
|
||||
你想让 Marqdo 变成:
|
||||
|
||||
```text
|
||||
新任务
|
||||
│
|
||||
▼
|
||||
是否已经学会?
|
||||
/ \
|
||||
是 否
|
||||
│ │
|
||||
▼ ▼
|
||||
已编译 mq.md LLM 推理
|
||||
│ │
|
||||
▼ ▼
|
||||
低成本执行 执行 + 观察
|
||||
│
|
||||
▼
|
||||
沉淀 mq.md
|
||||
│
|
||||
▼
|
||||
验证 / 优化
|
||||
│
|
||||
▼
|
||||
编译成 Skill
|
||||
```
|
||||
|
||||
我认为这个想法**非常漂亮**。
|
||||
|
||||
---
|
||||
|
||||
# 2. 而且这和 Marqdo 的语言设计天然吻合
|
||||
|
||||
这可能是你整个项目最重要的一次“闭环”。
|
||||
|
||||
你前面定义:
|
||||
|
||||
> `.mq.md` = Markdown + 可执行程序 + 知识。
|
||||
|
||||
现在 Agent 又产生:
|
||||
|
||||
> `.mq.md` = Agent 学会的经验。
|
||||
|
||||
于是:
|
||||
|
||||
```text
|
||||
Agent
|
||||
│
|
||||
│ 学习
|
||||
▼
|
||||
.mq.md
|
||||
│
|
||||
┌───────┼────────┐
|
||||
↓ ↓ ↓
|
||||
知识 策略 程序
|
||||
│ │ │
|
||||
└───────┼────────┘
|
||||
▼
|
||||
Agent Skill
|
||||
│
|
||||
▼
|
||||
低成本执行
|
||||
```
|
||||
|
||||
这就非常有意思了。
|
||||
|
||||
**Agent 的 memory 不再是一段向量 embedding,也不只是聊天历史。**
|
||||
|
||||
它是:
|
||||
|
||||
> **可阅读、可修改、可验证、可执行的知识程序。**
|
||||
|
||||
这才是真正的 **Marqdo-native Agent**。
|
||||
|
||||
---
|
||||
|
||||
# 3. 你现在的 Agent 已经有这个雏形,但还没有真正“学习”
|
||||
|
||||
从你现在的代码看,已经存在:
|
||||
|
||||
```text
|
||||
reuse
|
||||
near_match
|
||||
soft_match
|
||||
promote
|
||||
improve_every = 3
|
||||
llm_free
|
||||
```
|
||||
|
||||
这些机制实际上已经在做:
|
||||
|
||||
> **经验复用。**
|
||||
|
||||
例如当前逻辑会查找已有 KB,如果命中 `llm_free` skill,就可以直接运行 resource,而不是再让父 Agent 做一轮 LLM 推理。
|
||||
|
||||
这是很好的基础。
|
||||
|
||||
但我认为:
|
||||
|
||||
> **Reuse ≠ Learning。**
|
||||
|
||||
现在更像:
|
||||
|
||||
```text
|
||||
成功任务
|
||||
↓
|
||||
保存
|
||||
↓
|
||||
以后查找
|
||||
↓
|
||||
复用
|
||||
```
|
||||
|
||||
而你现在构想的是:
|
||||
|
||||
```text
|
||||
成功任务
|
||||
↓
|
||||
观察多次执行
|
||||
↓
|
||||
抽象共同结构
|
||||
↓
|
||||
去掉偶然信息
|
||||
↓
|
||||
形成一般策略
|
||||
↓
|
||||
验证
|
||||
↓
|
||||
编译
|
||||
↓
|
||||
以后低成本执行
|
||||
```
|
||||
|
||||
这两者差距非常大。
|
||||
|
||||
---
|
||||
|
||||
# 4. 我甚至建议你不要叫它 Memory
|
||||
|
||||
我会给它一个更有 Marqdo 味道的名字:
|
||||
|
||||
## **Skill Compilation**
|
||||
|
||||
或者:
|
||||
|
||||
## **Experience Compilation**
|
||||
|
||||
甚至:
|
||||
|
||||
## **Cognitive Compilation**
|
||||
|
||||
整个过程:
|
||||
|
||||
```text
|
||||
Experience
|
||||
↓
|
||||
Episodic Trace
|
||||
↓
|
||||
Pattern Extraction
|
||||
↓
|
||||
Generalization
|
||||
↓
|
||||
Marqdo Skill
|
||||
↓
|
||||
Validation
|
||||
↓
|
||||
Compiled Skill
|
||||
```
|
||||
|
||||
然后 Agent 不再只是:
|
||||
|
||||
> “记住我以前做过什么。”
|
||||
|
||||
而是:
|
||||
|
||||
> **“把以前的思考编译成以后不需要思考的程序。”**
|
||||
|
||||
我觉得这是一个非常强的概念。
|
||||
|
||||
---
|
||||
|
||||
# 5. 例如真的可以这样工作
|
||||
|
||||
第一次:
|
||||
|
||||
用户:
|
||||
|
||||
> 把这个 CSV 中年龄大于 18 的用户筛出来,并按照年龄排序。
|
||||
|
||||
Agent:
|
||||
|
||||
```text
|
||||
LLM reasoning
|
||||
↓
|
||||
读取 CSV
|
||||
↓
|
||||
分析结构
|
||||
↓
|
||||
过滤
|
||||
↓
|
||||
排序
|
||||
↓
|
||||
输出
|
||||
```
|
||||
|
||||
产生:
|
||||
|
||||
```text
|
||||
.marqdo/agent-runs/xxx.mq.md
|
||||
```
|
||||
|
||||
第二次用户:
|
||||
|
||||
> 把另一个 CSV 中年龄大于 18 的用户筛出来,并按照年龄排序。
|
||||
|
||||
Agent 发现:
|
||||
|
||||
```text
|
||||
intent similarity = 0.94
|
||||
```
|
||||
|
||||
于是:
|
||||
|
||||
```text
|
||||
REUSE
|
||||
```
|
||||
|
||||
直接调用之前的程序。
|
||||
|
||||
---
|
||||
|
||||
第三、第四、第五次:
|
||||
|
||||
Agent 发现:
|
||||
|
||||
```text
|
||||
same structure
|
||||
different file
|
||||
different column names
|
||||
```
|
||||
|
||||
这时候不应该继续保存五个:
|
||||
|
||||
```text
|
||||
task1.mq.md
|
||||
task2.mq.md
|
||||
task3.mq.md
|
||||
task4.mq.md
|
||||
task5.mq.md
|
||||
```
|
||||
|
||||
而应该让 LLM 总结:
|
||||
|
||||
```markdown
|
||||
# Filter and Sort CSV Users
|
||||
|
||||
## Preconditions
|
||||
|
||||
- Input contains user records.
|
||||
- An age field exists.
|
||||
|
||||
## Procedure
|
||||
|
||||
1. Read the input table.
|
||||
2. Keep rows where `age > 18`.
|
||||
3. Sort by `age` ascending.
|
||||
|
||||
## Variables
|
||||
|
||||
- `input`
|
||||
- `age_field`
|
||||
- `output`
|
||||
|
||||
## Exceptions
|
||||
|
||||
- Missing age field
|
||||
- Invalid age
|
||||
|
||||
## Examples
|
||||
|
||||
| Input | Output |
|
||||
|---|---|
|
||||
| ... | ... |
|
||||
```
|
||||
|
||||
然后:
|
||||
|
||||
```text
|
||||
skill_status = compiled
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
# 6. 更关键的是:这个 mq.md 可以逐渐“去 LLM 化”
|
||||
|
||||
这是你刚才说的:
|
||||
|
||||
> “其中可以使用非常少的大模型思考,或者使用类似 Jev 的决策模型,或者干脆只使用分支控制。”
|
||||
|
||||
**我非常赞同。**
|
||||
|
||||
我甚至认为这应该成为 Marqdo Agent 的核心架构。
|
||||
|
||||
可以设计成一个:
|
||||
|
||||
# Cognitive Cost Ladder
|
||||
|
||||
```text
|
||||
Level 0
|
||||
Deterministic Marqdo
|
||||
│
|
||||
▼
|
||||
Level 1
|
||||
Rule / Branch
|
||||
│
|
||||
▼
|
||||
Level 2
|
||||
Small decision model
|
||||
│
|
||||
▼
|
||||
Level 3
|
||||
Small LLM
|
||||
│
|
||||
▼
|
||||
Level 4
|
||||
Full LLM reasoning
|
||||
│
|
||||
▼
|
||||
Level 5
|
||||
Multi-agent exploration
|
||||
```
|
||||
|
||||
新问题:
|
||||
|
||||
```text
|
||||
Full LLM
|
||||
↓
|
||||
learn
|
||||
↓
|
||||
Marqdo Skill
|
||||
↓
|
||||
validation
|
||||
↓
|
||||
Level 2/1
|
||||
```
|
||||
|
||||
于是 Agent 会越来越“便宜”。
|
||||
|
||||
---
|
||||
|
||||
# 7. 这甚至给你提供了一个极漂亮的学习曲线
|
||||
|
||||
假设一个任务第一次需要:
|
||||
|
||||
```text
|
||||
8 次 LLM calls
|
||||
```
|
||||
|
||||
第二次:
|
||||
|
||||
```text
|
||||
5 次
|
||||
```
|
||||
|
||||
第三次:
|
||||
|
||||
```text
|
||||
3 次
|
||||
```
|
||||
|
||||
学习完成:
|
||||
|
||||
```text
|
||||
0 次
|
||||
```
|
||||
|
||||
或者:
|
||||
|
||||
```text
|
||||
1 次 small model
|
||||
```
|
||||
|
||||
这时候你就有一个非常漂亮的指标:
|
||||
|
||||
## Reasoning Amortization
|
||||
|
||||
定义:
|
||||
|
||||
$$
|
||||
C_n =
|
||||
\frac{
|
||||
\text{LLM inference cost over first } n \text{ executions}
|
||||
}{n}
|
||||
$$
|
||||
|
||||
随着执行次数增加:
|
||||
|
||||
```text
|
||||
Cost
|
||||
│\
|
||||
│ \
|
||||
│ \
|
||||
│ \
|
||||
│ \____
|
||||
│ ─────────
|
||||
└───────────────────
|
||||
executions
|
||||
```
|
||||
|
||||
**这甚至解决了你之前担心的 Marqdo 性能难以证明的问题。**
|
||||
|
||||
你之前不知道怎么证明:
|
||||
|
||||
> Marqdo 比 Python 更适合 AI。
|
||||
|
||||
但现在你可以研究:
|
||||
|
||||
> **Marqdo Agent 能否把高成本 LLM reasoning 逐渐编译成低成本 executable knowledge?**
|
||||
|
||||
这个是一个非常明确、可测量、而且很有研究价值的问题。
|
||||
|
||||
---
|
||||
|
||||
# 8. 但是这里有一个非常重要的危险
|
||||
|
||||
你说:
|
||||
|
||||
> “超过三次调用就自动总结。”
|
||||
|
||||
我建议:
|
||||
|
||||
**不要真的这么简单。**
|
||||
|
||||
三次可以作为:
|
||||
|
||||
> **触发学习候选**
|
||||
|
||||
但不能作为:
|
||||
|
||||
> **自动认为已经学会。**
|
||||
|
||||
否则会发生:
|
||||
|
||||
```text
|
||||
第一次:特殊情况
|
||||
第二次:特殊情况
|
||||
第三次:特殊情况
|
||||
```
|
||||
|
||||
LLM 总结:
|
||||
|
||||
```text
|
||||
General rule:
|
||||
...
|
||||
```
|
||||
|
||||
然后把偶然性错误“编译”进 Skill。
|
||||
|
||||
这会非常危险。
|
||||
|
||||
---
|
||||
|
||||
# 9. 我建议建立“经验 → 技能”的四阶段
|
||||
|
||||
## Stage 1 — Episode
|
||||
|
||||
每次任务产生:
|
||||
|
||||
```text
|
||||
task
|
||||
context
|
||||
actions
|
||||
tool calls
|
||||
observations
|
||||
errors
|
||||
result
|
||||
cost
|
||||
```
|
||||
|
||||
例如:
|
||||
|
||||
```text
|
||||
episode-001.mq.md
|
||||
episode-002.mq.md
|
||||
episode-003.mq.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Stage 2 — Candidate Skill
|
||||
|
||||
达到阈值之后:
|
||||
|
||||
```text
|
||||
3+ similar episodes
|
||||
```
|
||||
|
||||
让 LLM 总结:
|
||||
|
||||
```text
|
||||
candidate.mq.md
|
||||
```
|
||||
|
||||
但它还是:
|
||||
|
||||
> **candidate**
|
||||
|
||||
而不是正式 skill。
|
||||
|
||||
---
|
||||
|
||||
## Stage 3 — Verification
|
||||
|
||||
用历史任务重新运行:
|
||||
|
||||
```text
|
||||
episode 1
|
||||
episode 2
|
||||
episode 3
|
||||
```
|
||||
|
||||
测试:
|
||||
|
||||
```text
|
||||
candidate skill
|
||||
```
|
||||
|
||||
如果:
|
||||
|
||||
```text
|
||||
3 / 3 success
|
||||
```
|
||||
|
||||
再加新的 held-out task:
|
||||
|
||||
```text
|
||||
episode 4
|
||||
```
|
||||
|
||||
如果:
|
||||
|
||||
```text
|
||||
4 / 4
|
||||
```
|
||||
|
||||
才提高 confidence。
|
||||
|
||||
---
|
||||
|
||||
## Stage 4 — Compilation
|
||||
|
||||
最后:
|
||||
|
||||
```text
|
||||
candidate
|
||||
↓
|
||||
verified
|
||||
↓
|
||||
compiled
|
||||
```
|
||||
|
||||
此时才允许:
|
||||
|
||||
```text
|
||||
llm_free = true
|
||||
```
|
||||
|
||||
你目前的系统已经有 `llm_free` 命中后直接运行 resource 的机制。
|
||||
|
||||
我认为未来这个 flag **不应该是人工/静态指定的属性,而应该成为学习系统的产物。**
|
||||
|
||||
---
|
||||
|
||||
# 10. 甚至可以让 mq.md 自己记录“学习程度”
|
||||
|
||||
比如:
|
||||
|
||||
```yaml
|
||||
---
|
||||
type: skill
|
||||
status: compiled
|
||||
confidence: 0.97
|
||||
evidence: 17
|
||||
success_rate: 0.941
|
||||
llm_free: true
|
||||
created_from: 6c8...
|
||||
last_validated: 2026-09-23
|
||||
avg_reasoning_cost: 0.2
|
||||
---
|
||||
```
|
||||
|
||||
然后正文:
|
||||
|
||||
```markdown
|
||||
# CSV 成人用户筛选
|
||||
|
||||
## Intent
|
||||
|
||||
筛选年龄大于 18 岁的用户。
|
||||
|
||||
## Procedure
|
||||
|
||||
- 读取 CSV
|
||||
- 判断 age
|
||||
- 过滤
|
||||
- 排序
|
||||
|
||||
## Fallback
|
||||
|
||||
如果无法确定 age 字段:
|
||||
|
||||
> ask_llm
|
||||
|
||||
## Verification
|
||||
|
||||
| Case | Result |
|
||||
|---|---|
|
||||
| case-001 | ✓ |
|
||||
| case-002 | ✓ |
|
||||
| case-003 | ✓ |
|
||||
| case-004 | ✓ |
|
||||
```
|
||||
|
||||
注意这个设计里非常重要的一点:
|
||||
|
||||
> **Skill 本身可以包含一个 fallback 到 LLM 的路径。**
|
||||
|
||||
所以不是:
|
||||
|
||||
```text
|
||||
学会 / 不会
|
||||
```
|
||||
|
||||
而是:
|
||||
|
||||
```text
|
||||
确定部分 → deterministic
|
||||
不确定部分 → small model
|
||||
真正未知 → full LLM
|
||||
```
|
||||
|
||||
这就非常接近人类的实际认知过程。
|
||||
|
||||
---
|
||||
|
||||
# 11. 我甚至会把 Agent 的运行模型改成这样
|
||||
|
||||
```text
|
||||
User Task
|
||||
│
|
||||
▼
|
||||
┌─────────────────┐
|
||||
│ Skill Resolver │
|
||||
└────────┬────────┘
|
||||
│
|
||||
┌────────────┼────────────┐
|
||||
▼ ▼ ▼
|
||||
Exact Near Unknown
|
||||
Hit Hit
|
||||
│ │ │
|
||||
▼ ▼ ▼
|
||||
mq.md execute small model Full LLM
|
||||
│ │ │
|
||||
└────────────┼────────────┘
|
||||
▼
|
||||
Result
|
||||
│
|
||||
▼
|
||||
Episode
|
||||
│
|
||||
▼
|
||||
Experience Store
|
||||
│
|
||||
┌────────┴────────┐
|
||||
│ │
|
||||
repeated? novel?
|
||||
│
|
||||
▼
|
||||
Skill synthesis
|
||||
│
|
||||
▼
|
||||
Verification
|
||||
│
|
||||
▼
|
||||
Compilation
|
||||
│
|
||||
▼
|
||||
mq.md Skill
|
||||
```
|
||||
|
||||
**这就已经不是普通 Agent framework 了。**
|
||||
|
||||
它是一个:
|
||||
|
||||
> **Self-compiling Agent**
|
||||
|
||||
---
|
||||
|
||||
# 12. 而 Marqdo 在这里有一个其他 Agent framework 很难天然拥有的优势
|
||||
|
||||
因为“学习结果”不是:
|
||||
|
||||
```json
|
||||
{
|
||||
"memory": "..."
|
||||
}
|
||||
```
|
||||
|
||||
也不是:
|
||||
|
||||
```text
|
||||
embedding vector
|
||||
```
|
||||
|
||||
而是:
|
||||
|
||||
```text
|
||||
learned_skill.mq.md
|
||||
```
|
||||
|
||||
这意味着用户可以:
|
||||
|
||||
```text
|
||||
打开
|
||||
阅读
|
||||
修改
|
||||
运行
|
||||
测试
|
||||
分享
|
||||
Git commit
|
||||
diff
|
||||
fork
|
||||
```
|
||||
|
||||
甚至:
|
||||
|
||||
```text
|
||||
Agent A
|
||||
↓
|
||||
learned_skill.mq.md
|
||||
↓
|
||||
Agent B
|
||||
```
|
||||
|
||||
**Agent 的经验第一次成为一种真正可移植的软件 artifact。**
|
||||
|
||||
我认为这是你整个 Marqdo 项目里非常值得深入挖掘的东西。
|
||||
|
||||
---
|
||||
|
||||
# 13. 而且它和你前面说的“Executable Knowledge”完全闭环
|
||||
|
||||
你之前提出:
|
||||
|
||||
```text
|
||||
Executable Document
|
||||
↓
|
||||
Executable Knowledge Base
|
||||
```
|
||||
|
||||
现在再往前一步:
|
||||
|
||||
```text
|
||||
Executable Knowledge
|
||||
↓
|
||||
Agent Experience
|
||||
↓
|
||||
Agent Learning
|
||||
↓
|
||||
Compiled Knowledge
|
||||
↓
|
||||
Executable Skill
|
||||
```
|
||||
|
||||
于是整个 Marqdo 可以形成:
|
||||
|
||||
```text
|
||||
┌───────────────┐
|
||||
│ Human │
|
||||
└───────┬───────┘
|
||||
│
|
||||
▼
|
||||
Natural Task
|
||||
│
|
||||
▼
|
||||
AI Reasoning
|
||||
│
|
||||
▼
|
||||
Executable Work
|
||||
│
|
||||
▼
|
||||
.mq.md
|
||||
│
|
||||
┌───────┴───────┐
|
||||
▼ ▼
|
||||
Knowledge Skill
|
||||
│ │
|
||||
└───────┬───────┘
|
||||
▼
|
||||
Future Agent
|
||||
│
|
||||
▼
|
||||
Less Reasoning
|
||||
│
|
||||
▼
|
||||
More Execution
|
||||
```
|
||||
|
||||
这就是我现在最喜欢 Marqdo 的地方:
|
||||
|
||||
> **Agent 不只是使用知识库;Agent 会把自己的经验沉淀成知识库,然后知识库反过来改变 Agent 的计算方式。**
|
||||
|
||||
这是一个真正的闭环。
|
||||
|
||||
---
|
||||
|
||||
## 最后,我会建议你对现有 Agent 做一个非常明确的架构升级
|
||||
|
||||
你现在已经有:
|
||||
|
||||
```text
|
||||
reuse
|
||||
near_match
|
||||
soft_match
|
||||
promote
|
||||
improve_every=3
|
||||
llm_free
|
||||
```
|
||||
|
||||
所以**完全没必要推倒重来**。
|
||||
|
||||
我会把它演化成:
|
||||
|
||||
```text
|
||||
Current Agent
|
||||
│
|
||||
┌────────┴────────┐
|
||||
│ │
|
||||
Execution Experience
|
||||
│ │
|
||||
│ ▼
|
||||
│ Episode Store
|
||||
│ │
|
||||
│ ≥ N similar
|
||||
│ │
|
||||
│ ▼
|
||||
│ Skill Synthesis
|
||||
│ │
|
||||
│ ▼
|
||||
│ Skill Validation
|
||||
│ │
|
||||
│ ▼
|
||||
│ Skill Compilation
|
||||
│ │
|
||||
└─────────────┬───┘
|
||||
▼
|
||||
.mq.md Skill
|
||||
│
|
||||
┌────────┼────────┐
|
||||
▼ ▼ ▼
|
||||
Branch Small LLM Full LLM
|
||||
```
|
||||
|
||||
而且你当前已经有一个非常好的“终点”:**当 child 返回 value 时,可以 deterministic 地 solidify,而不是再次让父 LLM 发明 patch。** 当前代码已经明确这么处理。
|
||||
|
||||
所以我会把你的下一版 Agent 的核心 slogan 直接定成:
|
||||
|
||||
> **Think → Execute → Learn → Compile → Reuse**
|
||||
|
||||
或者更 Marqdo 一点:
|
||||
|
||||
> **Every successful thought can become executable knowledge.**
|
||||
|
||||
这比“Marqdo 有一个 Agent framework”强得多。
|
||||
|
||||
而且这件事**非常适合做你前面说的论文实验**:你甚至可以测一个 Agent 在重复任务上的 **LLM calls / tokens / latency / success rate 随经验次数变化的曲线**,直接验证“推理成本被 mq.md 技能逐渐摊销”的假设。这样 Marqdo 的 Agent、Executable Knowledge 和你之前苦恼的“性能怎么证明”三个问题,反而被同一个实验串起来了。
|
||||
@@ -0,0 +1,34 @@
|
||||
# 盲测实验(§5.2(b) 查询式 vs 全文档背诵)—— 2026-09-23
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 模型 | `deepseek-flash` @ `https://llm.cflmy.cn/v1` |
|
||||
| 样本 | 6 任务(业务 3 + QuixBugs 改写 3),oracle = stdout 精确匹配 |
|
||||
| 协议 | 系统提示词 = 硬规则 12 条 + 契约表三形状(两臂同文);**唯一变量 = 语法来源**:`query` 臂 MLSP 查询通道(≤3 次)vs `docs` 臂完整 markup 参考(背诵) |
|
||||
| 修复 | validate 诊断 + stderr 回喂,≤2 次修复;temperature=0,max_tokens=8000 |
|
||||
|
||||
## 汇总(判据:Q 通过率不劣于 D;首轮语法错误率 Q≤D;token Q≤70%%D;轮次不升)
|
||||
|
||||
| 臂 | 通过(一轮) | 通过(最终≤3) | 首轮语法错误 | 首轮契约诊断 | 平均修复轮(过例) | token 合计(prompt+completion) | 弃权/基础设施 |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| query | 0/3 | 0/3 | 2/3 | 1/3 | 0.00 | 69771(42478+27293) | 3 |
|
||||
| docs | 3/6 | 4/6 | 2/6 | 0/6 | 0.50 | 57276(33346+23930) | 0 |
|
||||
|
||||
## 逐例
|
||||
|
||||
| 例 | 臂 | 结果 | 修复轮 | 首轮语法错 | 首轮契约诊断 | token(p+c) | 查询 | 备注 |
|
||||
|---|---|---|---|---|---|---|---|---|
|
||||
| claims_reserve_settle | query | load-fail | 0 | 是 | 否 | 11987+8177 | 3 | {"error":{"code":"mlsp.parse_error","message":"<memory>: trailing input in expression: \"(claim - deductible, 0)\""},"id":1,"ok":false} \| stderr=error: /tmp/marqdo_blind_1694593_query_claims_reserve_settle.mq.md: trailing input in expression: "(claim - deductible, 0)" |
|
||||
| contract_milestone_pay | query | infra | 0 | 否 | 否 | 3970+4718 | 3 | 非 JSON / 空体: |
|
||||
| vendor_po_gate | query | load-fail | 0 | 是 | 否 | 9552+3686 | 3 | 回复中无程序 \| 开头: QUERY: 条件分支 写法 |
|
||||
| qb_gcd | query | run-fail | 0 | 否 | 是 | 9700+8488 | 3 | \| stderr=error: /tmp/marqdo_blind_1694593_query_qb_gcd.mq.md:26:1: unknown function `gcd(48` |
|
||||
| qb_max_sublist_sum | query | infra | 0 | 否 | 否 | 1253+134 | 3 | 非 JSON / 空体: |
|
||||
| qb_get_factors | query | infra | 0 | 否 | 否 | 6016+2090 | 3 | 非 JSON / 空体: |
|
||||
| claims_reserve_settle | docs | pass | 0 | 否 | 否 | 2699+2987 | 0 | queries=0 |
|
||||
| contract_milestone_pay | docs | pass | 0 | 否 | 否 | 2800+3202 | 0 | queries=0 |
|
||||
| vendor_po_gate | docs | pass | 0 | 否 | 否 | 2690+1264 | 0 | queries=0 |
|
||||
| qb_gcd | docs | pass | 2 | 否 | 否 | 8147+6970 | 0 | queries=0 |
|
||||
| qb_max_sublist_sum | docs | run-fail | 0 | 是 | 否 | 8518+3609 | 0 | \| stderr=error: /tmp/marqdo_blind_1694593_docs_qb_max_sublist_sum.mq.md:3:1: unknown function `[-2,` |
|
||||
| qb_get_factors | docs | run-fail | 0 | 是 | 否 | 8492+5898 | 0 | \| stderr=error: /tmp/marqdo_blind_1694593_docs_qb_get_factors.mq.md:20:1: missing argument for parameter `value` |
|
||||
|
||||
报告由 `tests/blind_experiment.rs` 生成;材料冻结于 `tests/blind/`(任务书 + docs-bundle),判据见 `doc/roadmap/perf-validation.md` §2。
|
||||
@@ -0,0 +1,34 @@
|
||||
# 盲测实验(§5.2(b) 查询式 vs 全文档背诵)—— 2026-09-23
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 模型 | `mimo-v2.6-pro` @ `https://llm.cflmy.cn/v1` |
|
||||
| 样本 | 6 任务(业务 3 + QuixBugs 改写 3),oracle = stdout 精确匹配 |
|
||||
| 协议 | 系统提示词 = 硬规则 12 条 + 契约表三形状(两臂同文);**唯一变量 = 语法来源**:`query` 臂 MLSP 查询通道(≤3 次)vs `docs` 臂完整 markup 参考(背诵) |
|
||||
| 修复 | validate 诊断 + stderr 回喂,≤2 次修复;temperature=0,max_tokens=8000 |
|
||||
|
||||
## 汇总(判据:Q 通过率不劣于 D;首轮语法错误率 Q≤D;token Q≤70%%D;轮次不升)
|
||||
|
||||
| 臂 | 通过(一轮) | 通过(最终≤3) | 首轮语法错误 | 首轮契约诊断 | 平均修复轮(过例) | token 合计(prompt+completion) | 弃权/基础设施 |
|
||||
|---|---|---|---|---|---|---|---|
|
||||
| query | 0/1 | 0/1 | 1/1 | 0/1 | 0.00 | 12428(10255+2173) | 5 |
|
||||
| docs | 0/0 | 0/0 | 0/0 | 0/0 | 0.00 | 0(0+0) | 6 |
|
||||
|
||||
## 逐例
|
||||
|
||||
| 例 | 臂 | 结果 | 修复轮 | 首轮语法错 | 首轮契约诊断 | token(p+c) | 查询 | 备注 |
|
||||
|---|---|---|---|---|---|---|---|---|
|
||||
| claims_reserve_settle | query | infra | 0 | 否 | 否 | 1424+324 | 3 | 非 JSON / 空体: |
|
||||
| contract_milestone_pay | query | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
|
||||
| vendor_po_gate | query | infra | 0 | 否 | 否 | 1417+213 | 3 | 非 JSON / 空体: |
|
||||
| qb_gcd | query | load-fail | 0 | 是 | 否 | 5011+1265 | 0 | {"error":{"code":"mlsp.parse_error","message":"<memory>: unexpected expression input: \"**y**\""},"id":1,"ok":false} \| stderr=error: /tmp/marqdo_blind_1710203_query_qb_gcd.mq.md: unexpected expression input: "**y**" |
|
||||
| qb_max_sublist_sum | query | infra | 0 | 否 | 否 | 1216+172 | 3 | 非 JSON / 空体: |
|
||||
| qb_get_factors | query | infra | 0 | 否 | 否 | 1187+199 | 3 | 非 JSON / 空体: |
|
||||
| claims_reserve_settle | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
|
||||
| contract_milestone_pay | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
|
||||
| vendor_po_gate | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
|
||||
| qb_gcd | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
|
||||
| qb_max_sublist_sum | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
|
||||
| qb_get_factors | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: {"error":{"message":"upstream connection failed","type":"server_error","param":n… |
|
||||
|
||||
报告由 `tests/blind_experiment.rs` 生成;材料冻结于 `tests/blind/`(任务书 + docs-bundle),判据见 `doc/roadmap/perf-validation.md` §2。
|
||||
@@ -0,0 +1,118 @@
|
||||
# P4 验证汇总报告 — 2026-09-23
|
||||
|
||||
> 执行 [perf-validation.md](perf-validation.md)(自设计性能验证协议)的结果汇总。
|
||||
> 覆盖 three-problems.md 三大问题的**验证矩阵**(§5.2 a–e)。逐例明细见各实验原始报告(文末索引)。
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 协议 | [perf-validation.md](perf-validation.md)(实验 (a)–(e)) |
|
||||
| 判据源 | [three-problems.md](three-problems.md) §3.7 / 各问题 §2.4 |
|
||||
| 构建 | marqdo v1.0.7(本仓库工作树;金 20 + 全量回归通过后采样) |
|
||||
| 端点 | `llm.cflmy.cn/v1`(OpenAI 兼容;temperature=0) |
|
||||
| 模型 | 修复实验:`cflmy`、`mimo-v2.6-flash`;盲测:`deepseek-flash`、`mimo-v2.6-pro`(按用户指定) |
|
||||
| 回归 | 全量干净回归(无 API key 基线)**零失败** |
|
||||
|
||||
## 1. 五实验结果与判据对照
|
||||
|
||||
| 实验 | 判据 | 结果 | 判定 |
|
||||
|---|---|---|---|
|
||||
| **(a) 锚点消融**(T3.3,双模型×20例×双臂,三轮) | anchor 臂一轮修复率 ≥ 80%;护栏 0 次越界应用 | cflmy anchor **20/20=100%**(plain 17/20=85%);mimo-v2.6-flash anchor **20/20=100%**(plain 18/20=90%;容错加固中的第二轮 anchor 18/20=90% 亦 ≥80%);越界拒/越界应用 0/0 | ✅ 过 |
|
||||
| **(b) 盲测**(查询式 vs 全文档背诵,6任务×2臂) | 四判据:最终通过率 Q 不劣于 D(允许 −0 例);首轮语法错误率 Q ≤ D;平均修复轮次 Q ≤ D;token ≤ 70% of D(首轮契约诊断率为观测项) | deepseek-flash:docs 4/6 vs query 0/3(3 例端点 infra 剔除);首轮语法错 2/3 vs 2/6;token 69,771 vs 57,276。mimo-v2.6-pro:两跑均端点 infra(12/12、11/12),**不可评估** | ❌ 四判据未全立 ⇒ 按 §3.7 继续改协议 |
|
||||
| **(c) 契约消融**(四边界×三情形) | 带契约错值拦截 = 100%;带契约对值误报 = 0%;无契约路径零回归 | 拦截 4/4=**100%**;误报 0/4=**0%**;无契约 4/4 动态语义保持(含 `missing map key` 基线) | ✅ 过 |
|
||||
| **(d) 防漂移演练**(9 漂移 + 2 负对照) | 故意写错必报 = 100%;对照组误报 = 0% | 必报 9/9=**100%**(`unknown_type`×2、`param_drift`×2、`return_mismatch`、`arg_mismatch`、`unknown_key`、`contract.duplicate`、`contract.unknown_table`);负对照误报 0/2 | ✅ 过 |
|
||||
| **(e) 核心守卫演练**(3 种变异注入) | 单边改动必红;还原必绿 | 3/3 必红(`CORE_CONSTRUCTS` 私增、`core-surface.md` 私增、金样删除);还原全绿 | ✅ 过 |
|
||||
|
||||
**可复制结论(a/c/d/e 全过)**:锚点臂一轮修复率双模型 100%(判据 ≥80%,增量 +15pp/+10pp——易锚定样本近天花板,区分性留难样本扩展);契约系统"只在声明处拦截、零误报、不碰动态路径"成立;契约/实现互查防漂移 100% 必报;核心面单边膨胀被 CI 守卫机械阻断。
|
||||
|
||||
## 2. 实验 (c)(d)(e) 明细
|
||||
|
||||
### (c) 契约消融(tests/contract_ablation.rs,确定性)
|
||||
|
||||
四边界(调用实参 / 返回值 / 表绑定 / 键访问)各测三情形:
|
||||
|
||||
| 情形 | 口径 | 结果 |
|
||||
|---|---|---|
|
||||
| ① 带契约 + 错值 | 必须拦截(`contract.arg_mismatch` / `contract.return_mismatch` / `contract.field_mismatch` / `contract.unknown_key`) | 4/4 |
|
||||
| ② 带契约 + 对值 | 不得报契约错(同路径同形状) | 0/4 误报 |
|
||||
| ③ 无契约 + 错值 | 保持动态语义(不得出现 `contract.*`;走经典动态错误如 `missing map key`) | 4/4 |
|
||||
|
||||
取元一律用主推的 `[]()` 形(`[键](`集合`)`)验证;`集合[^键]` 过渡形保留兼容金样覆盖。
|
||||
|
||||
### (d) 防漂移演练(tests/drift_drill.rs,确定性)
|
||||
|
||||
9 个"故意写错"全部必报:类型词拼错、参数名漂移、升参未覆盖、返回越约、实参越约、未知键、重复契约表、错列表头契约表、运行时值越约。负对照 2 例(被绑定的数据表、纯动态程序)零误报。同时验证"契约表一经出现即为完整声明"(新升参未覆盖 ⇒ `contract.param_drift` warning)被按设计触发。
|
||||
|
||||
### (e) 核心守卫演练(人工变异,tests/core_surface.rs 必红验证)
|
||||
|
||||
| 变异 | 注入点 | 结果 |
|
||||
|---|---|---|
|
||||
| 私增 `ghost-construct` | `src/parse/mod.rs` `CORE_CONSTRUCTS` | 🔴 必红 |
|
||||
| 私增 `ghost-construct` 行 | `doc/design/core-surface.md` | 🔴 必红 |
|
||||
| 删除金样文件 | `tests/markup-v03/soft-emphasis.mq.md` | 🔴 必红 |
|
||||
|
||||
三次还原后 🟢 全绿。CI 守卫强制"清单与文档双改 + 全部金样存在"。
|
||||
|
||||
## 3. 实验 (b) 盲测:详况与诚实结论
|
||||
|
||||
### 协议
|
||||
|
||||
两臂系统提示词同文 = 硬规则 12 条 + 契约表三形状;**唯一变量 = 语法知识获取**:
|
||||
|
||||
- `query` 臂:MLSP 查询通道(`QUERY: <关键字>` ⇒ `mlsp syntax` 卡片,含戒律原文/样例/文档锚点;≤3 次)
|
||||
- `docs` 臂:完整 markup 参考背诵(`tests/blind/docs-bundle.md`,背诵式全语法表 + 中文内建面)
|
||||
|
||||
任务 6 例(`tests/blind/tasks/`):业务 3(保险理赔准备金 / 工程进度款 / 采购付款门槛,均出自律所实测任务集)+ QuixBugs 改写 3(gcd / 最大子段和 / 质因数分解);oracle = stdout 精确匹配(任务书自带期望输出,把推理难度控制掉,失败归因于**语言能力**)。修复回路 ≤2 次(validate 结构化诊断 + stderr 回喂)。
|
||||
|
||||
### deepseek-flash(完成)
|
||||
|
||||
| 臂 | 通过(一轮) | 通过(最终) | 首轮语法错 | 平均修复轮(过例) | token(p+c) | infra 剔除 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| query | 0/3 | 0/3 | 2/3 | – | 69,771(42,478+27,293) | 3/6 |
|
||||
| docs | 3/6 | **4/6** | 2/6 | 0.50 | 57,276(33,346+23,930) | 0/6 |
|
||||
|
||||
- **docs 臂**:业务题 3/3 全部一轮通过(各 ~3k token);`qb_gcd` 修复 2 轮过;`qb_max_sublist_sum`、`qb_get_factors` 暴露真语法滑倒(列表字面量被当调用 `unknown function [-2,`;参数名漂移 `missing argument for parameter value`)。
|
||||
- **query 臂**:查询通道**被积极使用**(5/6 例用满 3 次,多词查询如 `条件分支 写法` 也能正确命中卡片——已单独验证查询匹配无缺陷);但 3 例被端点空体吃掉,其余 3 例败于真语法错(Python 式元组 `(a, b)` ⇒ `trailing input in expression`;Python 式调用 `gcd(48, 18)` ⇒ `unknown function gcd(48`)与 1 例查询后未交程序。
|
||||
|
||||
### mimo-v2.6-pro(两跑均不可评估)
|
||||
|
||||
首跑 **12/12** 全部"非 JSON / 空体"(与 deepseek 并行时段)。三向探针(小提示词×12000/4000、大提示词×12000)证实**网关随机空体**、与 `max_tokens`/提示词体量无稳定关系。加重试(8→12 次、退避 10→15 秒)并**单独**重跑后仍为 **11/12** 端点 infra(含两臂首聊即 `tok=(0,0)` 的空体);唯一执行到的 `qb_gcd` 例暴露真语法错(`**y**` 作语句 ⇒ `unexpected expression input`)。**结论:`mimo-v2.6-pro` 经本网关不可评估**,(b) 判据以 `deepseek-flash` 数据为准。原始报告:[blind-experiment-2026-09-23-mimo-v2.6-pro.md](blind-experiment-2026-09-23-mimo-v2.6-pro.md)。
|
||||
|
||||
### 判据对照(截至 deepseek-flash)
|
||||
|
||||
| 判据(协议 §2.4 原文口径) | 目标 | 实测(deepseek-flash,非 infra 口径) | 判定 |
|
||||
|---|---|---|---|
|
||||
| 最终通过率(≤3 轮)Q 不劣于 D(允许 −0 例) | ≥ D | 0/3 vs 4/6 | ❌ |
|
||||
| 首轮语法错误率 Q ≤ D | ≤ | 2/3 vs 2/6 | ❌ |
|
||||
| 平均修复轮次 Q ≤ D | ≤ | query 臂无通过例,不可比 | ⚠️ |
|
||||
| token 用量 Q ≤ 70% of D | ≤ 40,093 | 69,771(D 的 121.8%) | ❌ |
|
||||
| (观测项)首轮契约诊断率 Q ≤ D | – | 1/3 vs 0/6 | ➖ 观测 |
|
||||
|
||||
**诚实结论:在 deepseek-flash 上,"查询式"没有跑赢"全背诵"**——三项可判量化判据未达,按协议 §3.7 判定:**四判据未全成立 ⇒「AI 不必学语法」本轮未获实证,继续改协议**(不是证伪——infra 吞掉 query 臂一半样本,非 infra n=3)。要点:
|
||||
|
||||
1. **统计力被端点削弱**:query 臂 6 例中 3 例被空体吃掉(协议无从执行),非 infra 样本 n=3;mimo-v2.6-pro 整组不可用。判据是"有方向的强声明",当前证据**不足以支持也未证伪**其普适性,只能定格为"deepseek-flash × 本任务集 × 本协议版本"下的一次未达标观测。
|
||||
2. **失败模式是真发现**:查询臂的败例是**跨语言习惯泄漏**(元组表达式、Python 调用形)——查询卡片能回答"条件分支怎么写",但模型不查询"这里能不能用元组"。说明"AI 不必学语法"的瓶颈不在**查询机制**,而在**模型的自查纪律**(不知道自己不知道)。
|
||||
3. **token 判据方向存疑**:查询式省的是**系统提示词常驻**(背诵包),花的是**多轮往返**。6 例短程序任务里往返开销 > 常驻节省;该判据更适用于**长会话多文件**场景(一次背诵包 × N 轮 vs 每轮均摊查询),本轮任务形态低估了查询式的收益面。
|
||||
4. **docs 臂的 4/6 说明任务集有区分度**(不是全过/全不过的退化测量)。
|
||||
|
||||
## 4. 测量端基础设施记录(方法学附注)
|
||||
|
||||
- **LLM 端点不稳定**是本轮最大的干扰源:随机空体、reasoning 模型 `finish=length` 截断(思考吃满额度、正文为空)。对策:空体重试 5→12 次 + 退避 5→15 秒、截断自适应(`max_tokens` 加倍重试,封顶 32k)、infra 例从判据比率中剔除并单列。
|
||||
- **harness 缺陷两处**(已修,未污染最终数据):查询额度用满后的续篇被当最终回复(⇒ 假"无程序");程序提取失败不进修复回路(⇒ 少给模型一次标准修复机会)。修复后的协议对两臂完全一致。
|
||||
- **模型口径变化留痕**:原定 `cflmy`/`mimo-v2.6-flash` 组合按用户指示弃用,改 `mimo-v2.6-pro`/`deepseek-flash`;修复实验 (a) 的双模型数据仍是原组合(金 20 协议已完成,不重跑)。
|
||||
|
||||
## 5. 材料与复现
|
||||
|
||||
```bash
|
||||
# (a) 锚点消融(需要 API key)
|
||||
cargo test --test repair_experiment -- --ignored --nocapture # anchor/plain 双臂×20例
|
||||
# (b) 盲测(每模型一次;建议单独跑避免并发)
|
||||
OPENAI_MODEL=deepseek-flash MARQDO_EXP_DATE=2026-09-23 cargo test --test blind_experiment -- --ignored --nocapture
|
||||
# (c)(d) 确定性
|
||||
cargo test --test contract_ablation --test drift_drill
|
||||
# (e) 核心守卫(变异注入→必红→还原必绿,按 perf-validation.md §5 手法)
|
||||
cargo test --test core_surface
|
||||
```
|
||||
|
||||
- 任务书 / 背诵包(冻结,勿改):`tests/blind/`
|
||||
- 原始报告:[blind-experiment-2026-09-23-deepseek-flash.md](blind-experiment-2026-09-23-deepseek-flash.md) · [blind-experiment-2026-09-23-mimo-v2.6-pro.md](blind-experiment-2026-09-23-mimo-v2.6-pro.md)(首跑全 infra)· [repair-experiment-2026-09-22.md](repair-experiment-2026-09-22.md) · [repair-experiment-2026-09-22-mimo-v2.6-flash.md](repair-experiment-2026-09-22-mimo-v2.6-flash.md)
|
||||
- 判据协议:[perf-validation.md](perf-validation.md)(版本化于本仓库,实验前冻结)
|
||||
@@ -0,0 +1,125 @@
|
||||
# P4 性能验证设计(实验协议与判据)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · P4 执行依据** |
|
||||
| 日期 | 2026-09-23 |
|
||||
| 授权 | 用户授权**自行设计**本性能验证设计(P4 不再等待外部文档导入;`doc/next/002.md` 与性能验证无关) |
|
||||
| 上位判据 | [three-problems.md](three-problems.md) §5.1 判据矩阵 + §5.2 实验 (a)–(e);「判据矩阵全绿 + 实验数字可复现之前,三大问题一律视为未解决」 |
|
||||
| 工程任务 | [three-problems-plan.md](three-problems-plan.md) Phase 1–3(已完成);本文只负责**验证它们** |
|
||||
|
||||
> **本文定位**:把 three-problems.md §5.2 的五个实验操作化——每个实验给出**材料、协议、指标、判据**,全部机器可执行、数字可复现。实验产物 = 报告 [perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)。**只认行为与数字,不认宣言。**
|
||||
|
||||
## 0. 总览
|
||||
|
||||
| 实验 | 验证对象 | 判据(全过 = 该问题的实证成立) | 执行方式 | 状态 |
|
||||
|------|----------|-------------------------------|----------|------|
|
||||
| (a) 锚点修复消融 | 问题三 · 可靠反馈 | 一轮修复率 ≥ 80%(anchor 臂),护栏 0 越界 | 模型在环 `tests/repair_experiment.rs` | ✅ 已完成(三轮双模型) |
|
||||
| (b) 盲测 | 问题三 · 不必学语法 | 查询组错误率 ≤ 全文档组;token 显著更少;修复轮次不升 | 模型在环 `tests/blind_experiment.rs` | 见报告 |
|
||||
| (c) 契约消融 | 问题二 · 语义校验 | 拦截率 = 100%;误报率 = 0%;无契约路径零回归 | 确定性 `tests/contract_ablation.rs` | 见报告 |
|
||||
| (d) 防漂移演练 | 问题二 · 契约可信 | 故意写错契约必报率 = 100% | 确定性 `tests/drift_drill.rs` | 见报告 |
|
||||
| (e) 核心守卫演练 | 问题一 · 核心要小 | 三种变异注入各必红 → 还原必绿 | 变异脚本(见 §4) | 见报告 |
|
||||
|
||||
判定口径([three-problems.md](three-problems.md) §5.1):**任何一项判据不成立,对应问题即「未解决」**——不许用文档宣言充数。
|
||||
|
||||
---
|
||||
|
||||
## 1. 实验 (a):锚点修复消融(问题三 · 可靠反馈)
|
||||
|
||||
**假设**:诊断带 `doc_anchor`/`doc_quote`/`suggestion`(锚点诊断)比裸诊断显著提高一轮修复率。
|
||||
|
||||
- **对照**:`anchor` 臂(全量诊断字段)vs `plain` 臂(剥掉 doc_anchor/doc_quote/suggestion)。
|
||||
- **材料**:golden 20 例(10 骨架 × 2 变体:arg/ret/field/key/typo/drift/dup),易锚定错误。
|
||||
- **协议**:`validate` → `repair_targets` → 模型行编辑 → `repair_apply`(越界必拒/abstain)→ 复验;≤2 轮。
|
||||
- **指标**:一轮修复率、最终修复率、平均尝试、越界拒、弃权。
|
||||
- **判据**:anchor 臂一轮修复率 ≥ 80%;护栏 0 次越界应用(越界必拒由 `tests/repair_loop.rs` 硬断言兜底)。
|
||||
- **执行**:`OPENAI_MODEL=… cargo test --test repair_experiment -- --ignored --nocapture`。
|
||||
- **结果**:三轮双模型全过(cflmy anchor 100% / mimo 90%→100%,plain 85%–100%,护栏 0 越界)——
|
||||
详见 [repair-experiment-2026-09-22.md](repair-experiment-2026-09-22.md) 与
|
||||
[repair-experiment-2026-09-22-mimo-v2.6-flash.md](repair-experiment-2026-09-22-mimo-v2.6-flash.md)。**✅ PASS**。
|
||||
- **诚实注记**:样本为易锚定错误(两臂近天花板),锚点增量的区分性证据留待难样本扩展;不影响本判据达标。
|
||||
|
||||
## 2. 实验 (b):盲测——查询式 vs 全文档背诵(问题三 · 超级核心)
|
||||
|
||||
**假设**:「零语法文档 + MLSP 查询」组(Q)成绩**不劣于**「全文档背诵」组(D),且 prompt token 显著更少、修复轮次不升([three-problems.md](three-problems.md) §3.7 最终判据)。
|
||||
|
||||
### 2.1 对照(唯一变量 = 语法知识的获取方式)
|
||||
|
||||
| 臂 | 系统提示词内容 | 语法知识来源 |
|
||||
|----|----------------|--------------|
|
||||
| **Q 查询组** | 硬规则(12 条)+ 契约表三形状 + MLSP 查询通道说明 | 按需 `QUERY: <关键字>`(≤3 次,harness 代答 `mlsp syntax` 卡片) |
|
||||
| **D 全文档组** | 硬规则(12 条)+ 契约表三形状 + **完整 markup 参考**(`tests/blind/docs-bundle.md`:v0.3 全语法表 + 中文内建面) | 上下文预载(背诵) |
|
||||
|
||||
两臂共同点:硬规则与契约表形状**同文**(受控变量,不测契约知识差异);修复回路相同(`mlsp validate` 诊断回喂,≤2 轮);模型 / 温度 / 任务 / 提示词模板相同。
|
||||
|
||||
### 2.2 材料:任务集(6 例,业务 3 + 算法 3)
|
||||
|
||||
| id | 类型 | 任务 | 功能 oracle(stdout 精确匹配) |
|
||||
|----|------|------|-------------------------------|
|
||||
| `claims_reserve_settle` | 业务 | 保险准备金(免赔/共保/分项限额/追偿/地板) | `28000` |
|
||||
| `contract_milestone_pay` | 业务 | 工程里程碑应付款(保留金/逾期罚/变更/税/地板) | `37354` |
|
||||
| `vendor_po_gate` | 业务 | 采购 PO 准付闸(折扣/加急/预算帽/合规费/地板) | `814` |
|
||||
| `qb_gcd` | 算法 | 最大公约数;打印 gcd(48,18) gcd(1071,462) gcd(0,5) gcd(17,5) 各一行 | `6` `21` `5` `1` |
|
||||
| `qb_max_sublist_sum` | 算法 | 最大子段和;三组输入各打印一行 | `6` `6` `-1` |
|
||||
| `qb_get_factors` | 算法 | 质因数分解,因数以 `*` 连接;12 / 13 / 60 各一行 | `2*2*3` `13` `2*2*3*5` |
|
||||
|
||||
业务任务书复用 MarqdoThesis `formal/exp3-bizreq/data/tasks/`(权威规则文本原样进入提示词);算法任务书为 QuixBugs 改写(从「修 bug」改「实现 + 固定输出」,消除参考源码变量)。
|
||||
|
||||
### 2.3 协议(每例)
|
||||
|
||||
1. 提示词 = 任务书 + 「输出完整 `.mq.md` 源码于单个 ```markdown 围栏」;
|
||||
2. **查询阶段**(仅 Q 臂):模型可输出 `QUERY: <关键字>` 行,harness 以 `mlsp syntax` 卡片作答并继续;累计 ≤3 次;
|
||||
3. **执行阶段**:`marqdo run` → stdout == oracle 即通过;失败则回喂 `mlsp validate` 结构化诊断 + stderr,允许 ≤2 次修复;
|
||||
4. 记录每轮 token(API `usage.prompt_tokens + completion_tokens` 累计)。
|
||||
|
||||
### 2.4 指标与判据
|
||||
|
||||
| 指标 | 口径 | 判据 |
|
||||
|------|------|------|
|
||||
| 功能通过率(一轮 / 最终≤3 轮) | stdout 与 oracle 精确匹配 | Q 最终通过率**不劣于** D(允许 −0 例) |
|
||||
| 首轮语法错误率 | 首轮 `validate`/run 出现 parse 类失败的例数占比 | Q ≤ D |
|
||||
| 首轮契约诊断率 | 首轮出现 `contract.*` 诊断的例数占比 | Q ≤ D(观测项) |
|
||||
| 平均修复轮次 | 通过前的修复次数(含首轮生成记 0) | Q ≤ D |
|
||||
| token 用量 | 逐例累计 prompt+completion | Q **显著更少**(≤ 70% of D) |
|
||||
|
||||
**判定**:四条判据全成立 ⇒ 「AI 不必学语法」实证成立;否则按 §3.7「继续改协议」,不得以改进文档充数。
|
||||
- **执行**:`OPENAI_MODEL=… cargo test --test blind_experiment -- --ignored --nocapture`(每模型一轮)。
|
||||
|
||||
## 3. 实验 (c):契约消融(问题二 · 语义校验)
|
||||
|
||||
**假设**:契约只在**有契约处**拦截错误值(P1:无契约 = 全动态),且不误报。
|
||||
|
||||
- **材料**:`tests/contract_ablation.rs` 内联四边界用例(调用实参 / 返回 / 表绑定 / 字段访问)×三形态:
|
||||
① 带契约 + 错值 → **必拦**(`contract.*` 诊断);② 带契约 + 对值 → **零误报**(正常产出);③ 同程序**删契约表** + 错值 → **零契约诊断**(动态语义原样)。
|
||||
- **指标与判据**:
|
||||
- 拦截率 = ①被拦 / ①总数 = **100%**;
|
||||
- 误报率 = ②误报 / ②总数 = **0%**;
|
||||
- 无契约零回归 = ③零 `contract.*` 诊断且输出 = 动态语义基线;且全量 `cargo test` 绿(441+ 既有测试是无契约路径的主回归面)。
|
||||
- **执行**:`cargo test --test contract_ablation`。
|
||||
|
||||
## 4. 实验 (d):防漂移演练(问题二 · 契约可信)
|
||||
|
||||
**假设**:契约写错**必**被机器抓(不静默信任契约)——three-problems.md §2.8「故意写错契约的金样必红」。
|
||||
|
||||
- **材料**:`tests/drift_drill.rs`——故意写错契约的 N 例(类型 typo `nubmer`、未知对象类型、契约参数名 ≠ 升参名 ×2、返回契约明显不符、重复契约表、错位契约表)+ **负对照**(被绑定的 `字段|类型` 数据表 = web_db_migration 式,必须**不**被当契约吃掉)。
|
||||
- **指标与判据**:
|
||||
- 必报率 = 漂移例被诊断(`check` 报错/警告或运行时 `contract.*`)/ 漂移例总数 = **100%**;
|
||||
- 负对照误报 = **0**。
|
||||
- **执行**:`cargo test --test drift_drill`。
|
||||
|
||||
## 5. 实验 (e):核心守卫演练(问题一 · 核心要小)
|
||||
|
||||
**假设**:核心表面任何**单侧**变更(代码/文档/金样不同步)→ CI 必红——three-problems.md §1.5「新增标记不更新清单时 CI 必须红」。
|
||||
|
||||
- **材料**:`tests/core_surface.rs` 守卫 + 三种变异注入(脚本化,`git checkout` 还原):
|
||||
1. `src/parse/mod.rs` `CORE_CONSTRUCTS` 增一行、不改文档 → **必红**;
|
||||
2. `doc/design/core-surface.md` 表增一行、不改代码 → **必红**;
|
||||
3. 金样文件改名(路径失效)→ **必红**。
|
||||
- **指标与判据**:3/3 变异注入后守卫测试红;还原后全绿。**必红率 = 100%**。
|
||||
- **执行**:报告内嵌演练记录(命令 + 测试输出摘录)。
|
||||
|
||||
## 6. 报告与复现
|
||||
|
||||
- 报告:[perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)((a) 引用既有两份实验报告;(b)–(e) 本次产出)。
|
||||
- 复现命令全部写入报告各节;模型在环实验记录模型名与端点,判据数字允许 ±1 例波动(模型非确定性),**判据线本身不放宽**。
|
||||
- 汇总结论回填 [three-problems-plan.md](three-problems-plan.md) 落地记录;§5.1 判据矩阵逐行标注 ✅/❌。
|
||||
@@ -0,0 +1,64 @@
|
||||
# 修复实验(§5.2(a) 锚点消融)—— 2026-09-22
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 模型 | `mimo-v2.6-flash` @ `https://llm.cflmy.cn/v1` |
|
||||
| 样本 | golden 20 例(易锚定错误) |
|
||||
| 协议 | `validate` → `repair_targets` → 模型行编辑 → `repair_apply`(越界必拒/abstain)→ 复验;≤2 轮 |
|
||||
| 对照 | `anchor` = 诊断带 `doc_anchor`/`doc_quote`/`suggestion`;`plain` = 全部剥掉 |
|
||||
|
||||
## 汇总(设计目标:一轮修复率 ≥ 80%)
|
||||
|
||||
| 臂 | 一轮修复率 | 最终修复率(≤2轮) | 平均尝试 | 越界拒(护栏) | 弃权 |
|
||||
|---|---|---|---|---|---|
|
||||
| anchor | 20/20(100%) | 20/20(100%) | 1.00 | 0 | 0 |
|
||||
| plain | 18/20(90%) | 19/20(95%) | 1.05 | 0 | 1 |
|
||||
|
||||
## 逐例
|
||||
|
||||
| 例 | 臂 | 结果 | 轮次 | 越界拒 | 备注 |
|
||||
|---|---|---|---|---|---|
|
||||
| arg-num-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-num-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| arg-num-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-num-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| field-nullable-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-nullable-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| field-nullable-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-nullable-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| field-type-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-type-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| field-type-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-type-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| key-fix-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| key-fix-a | plain | 未修复 | 1 | 0 | 模型弃权/输出不可解析: [{"op":"replace","line":13","text":"*`用户`[^name]*"}] |
|
||||
| key-fix-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| key-fix-b | plain | 二轮修复 | 2 | 0 | 修复后仍有诊断: {"code":"marqdo.error","contract_ref":null,"doc_anchor":null,"doc_quote":null,"message":"missing map key `phone`","severity":"error","span":{"col":1,"file":"/tmp/marqdo_repair_1666049_plain_key-fix-b.mq.md","line":14},"suggestion":null} |
|
||||
| ret-type-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| ret-type-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| ret-type-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| ret-type-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-b | plain | 一轮修复 | 1 | 0 | |
|
||||
|
||||
## 护栏核对
|
||||
|
||||
- 每次越界编辑都以 `mlsp.repair_out_of_scope` + `abstain` 被拒,且 `repair_apply` 全有或全无(源零字节不改)——由 `tests/repair_loop.rs` 的确定性断言覆盖;本实验计数仅作记录。
|
||||
@@ -0,0 +1,64 @@
|
||||
# 修复实验(§5.2(a) 锚点消融)—— 2026-09-22
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 模型 | `cflmy` @ `https://llm.cflmy.cn/v1` |
|
||||
| 样本 | golden 20 例(易锚定错误) |
|
||||
| 协议 | `validate` → `repair_targets` → 模型行编辑 → `repair_apply`(越界必拒/abstain)→ 复验;≤2 轮 |
|
||||
| 对照 | `anchor` = 诊断带 `doc_anchor`/`doc_quote`/`suggestion`;`plain` = 全部剥掉 |
|
||||
|
||||
## 汇总(设计目标:一轮修复率 ≥ 80%)
|
||||
|
||||
| 臂 | 一轮修复率 | 最终修复率(≤2轮) | 平均尝试 | 越界拒(护栏) | 弃权 |
|
||||
|---|---|---|---|---|---|
|
||||
| anchor | 20/20(100%) | 20/20(100%) | 1.00 | 0 | 0 |
|
||||
| plain | 17/20(85%) | 17/20(85%) | 0.85 | 0 | 0 |
|
||||
|
||||
## 逐例
|
||||
|
||||
| 例 | 臂 | 结果 | 轮次 | 越界拒 | 备注 |
|
||||
|---|---|---|---|---|---|
|
||||
| arg-num-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-num-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| arg-num-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-num-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| arg-text-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-cover-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| drift-rename-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| dup-delete-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| field-nullable-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-nullable-a | plain | 未修复 | 0 | 0 | LLM 调用失败(重试后): 非 JSON / 空体: |
|
||||
| field-nullable-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-nullable-b | plain | 未修复 | 0 | 0 | LLM 调用失败(重试后): 非 JSON / 空体: |
|
||||
| field-type-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-type-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| field-type-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| field-type-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| key-fix-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| key-fix-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| key-fix-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| key-fix-b | plain | 未修复 | 0 | 0 | LLM 调用失败(重试后): 非 JSON / 空体: |
|
||||
| ret-type-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| ret-type-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| ret-type-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| ret-type-b | plain | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-a | anchor | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-a | plain | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-b | anchor | 一轮修复 | 1 | 0 | |
|
||||
| type-typo-b | plain | 一轮修复 | 1 | 0 | |
|
||||
|
||||
## 护栏核对
|
||||
|
||||
- 每次越界编辑都以 `mlsp.repair_out_of_scope` + `abstain` 被拒,且 `repair_apply` 全有或全无(源零字节不改)——由 `tests/repair_loop.rs` 的确定性断言覆盖;本实验计数仅作记录。
|
||||
@@ -0,0 +1,225 @@
|
||||
# 三大问题落地计划(core 收口 · 渐进式契约 · MLSP)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **本期开发依据 · 执行中** |
|
||||
| 日期 | 2026-09-22 |
|
||||
| 设计 | [three-problems.md](three-problems.md)(解决方向与验证设计;判据矩阵 §5.1) |
|
||||
| 范围 | **工程任务 = Phase 1–3**;验证实验(three-problems.md §5.2)协议见 [perf-validation.md](perf-validation.md)(2026-09-23 用户授权自行设计并执行) |
|
||||
| 约定 | 每任务带机器可验证验收;**任务完成 = 验收全绿 + 全量回归绿**;只改宣言不改行为 = 未完成 |
|
||||
|
||||
## 0. 本期范围与依赖
|
||||
|
||||
| 阶段 | 定位 | 本期 |
|
||||
|------|------|------|
|
||||
| **Phase 1** 核心收口 + 诊断地基 | 一切的地基 | ✅ 启动 |
|
||||
| **Phase 2** 渐进式契约层 | 校验层(schema 源头 = 表格/段落) | ✅ 本期主目标 |
|
||||
| **Phase 3** MLSP(AI 语言服务) | **下一步的超级核心**(AI 不必学语法 + 可靠反馈闭环) | ⏭ 下期启动,本期只留接口 |
|
||||
| **Phase 4** 验证实验 | 性能验证(非开发任务) | ❌ 不认领 |
|
||||
|
||||
依赖链(**跳步会倒逼「另造一套错误 / 另写一套 schema」的遮盖式捷径**):
|
||||
|
||||
```text
|
||||
T1.4 Diagnostic ──是──> T2.x 契约诊断的唯一出口
|
||||
T2.x 契约 ───────是──> T3.1 schema 注册表的主数据源
|
||||
T1.1 core-surface ─是─> T3.1 语言面 + T1.3 守卫
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 1 · 核心收口 + 诊断地基(本期启动)
|
||||
|
||||
### T1.1 核心表面清单
|
||||
|
||||
- **产出**:`doc/design/core-surface.md`
|
||||
- **实现要点**:
|
||||
- 两张表:**行构造**(heading-unit `#`/`##`、call-line `>`、branch-list `1.`、loop-list `-`、param `+ 名`、table、fence、hr、writeback、narrative、blank)与**内联标记**(ident `` `名` ``、bold-code `**…**`、italic-return `*…*`、empty-return、link-index `[键](集合)`、bracket-call `[函数]`、footnote-index `[^键]` 过渡);
|
||||
- 每行含:**id**(英文 kebab,守卫用)、Markdown 外形、语义、**戒律**(边界 + 为什么不能是普通 Markdown)、**金样**(`tests/markup-v03/…` 路径);
|
||||
- 与 [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) §5 / §10 对齐;词法大类(`src/lex/mod.rs` `LineKind`)另列一节说明与构造表的关系。
|
||||
- **验收**:每行金样文件真实存在(T1.3 断言);id 全集 = T1.3 `CORE_CONSTRUCTS` 全集。
|
||||
|
||||
### T1.2 三层归属与准入戒律
|
||||
|
||||
- **产出**:`doc/design/layers.md` + `.github/PULL_REQUEST_TEMPLATE.md`(无则新建)
|
||||
- **实现要点**:
|
||||
- 归属表(含仓库路径):Language = `src/lex` `src/parse` `src/ast` `src/interp` `src/diagnostics` + 契约检查器;Runtime = `lib/` `plugins/` `crates/` `src/catalog.rs` `src/view` `src/debug` + 未来的 check/schema/mcp;Document = `*.mq.md` `skills/` `ext/` `public/` `examples/`;
|
||||
- 准入戒律:新特性先填层归属;进 Language 必答「为什么现有标记不够」;默认进 ext;核心标记计数每 release 只许持平或下降;
|
||||
- 发布 checklist:CHANGELOG 增「核心表面 Δ」栏(写入 `skills/marqdo-release/SKILL.md` 一步)。
|
||||
- **验收**:PR 模板含「层归属」必填项;layers.md 与 core-surface.md 互相引用闭合。
|
||||
|
||||
### T1.3 核心表面守卫(CI)
|
||||
|
||||
- **产出**:`tests/core_surface.rs` + `src/parse/mod.rs` 增 `pub const CORE_CONSTRUCTS: &[(&str, &str)]`(id、外形;**紧邻分类代码维护**)
|
||||
- **实现要点**:`include_str!` 解析 core-surface.md 表格 id 列 ↔ `CORE_CONSTRUCTS` **双向集合相等**;每行「金样」路径 `Path::exists()` 断言。
|
||||
- **验收(反遮盖核心)**:
|
||||
- 新增 `CORE_CONSTRUCTS` 条目不改文档 → **红**;
|
||||
- 文档加行不改代码 → **红**;
|
||||
- 删除/改名金样文件 → **红**。
|
||||
|
||||
### T1.4 诊断对象扩展(Phase 2/3 的唯一出口)
|
||||
|
||||
- **产出**:`src/diagnostics.rs` 扩展 + `src/main.rs` `run --json`
|
||||
- **实现要点**:
|
||||
- `Diagnostic` 增 `code`(如 `parse.*` / `contract.*` / `runtime.*`)、`severity`、`suggestion`、`doc_anchor`、`doc_quote`、`contract_ref`(Phase 2 起填值);`::new/at` 签名不变(全仓调用零改动),新增 builder 方法;
|
||||
- `serde::Serialize` + `to_json()`;**Display 保持 `path:line:col: message`**(人类输出零回归);
|
||||
- `run --json`:顶层错误路径把 Diagnostic 序列化输出(stderr JSON 行)。
|
||||
- **验收**:现有错误金样文本输出**零变化**;新金样断言 JSON `code`/`span` 非空;`cargo test` 全绿。
|
||||
|
||||
---
|
||||
|
||||
## Phase 2 · 渐进式契约层(本期主目标)
|
||||
|
||||
### T2.1 契约 AST + 提取器
|
||||
|
||||
- **产出**:`src/contract.rs`(`Contract` / `ParamContract` / `FieldContract` + 类型词汇 `text/number/bool/list/map/any/对象名`);`src/parse/`(提取);`src/ast.rs`(挂载,带 span)
|
||||
- **实现要点**:按 [three-problems.md](three-problems.md) §2.3/§2.4——**未绑定文档表** + 列头关键字(`参数/返回/字段/类型/说明`)+ 允许位置(函数体首个可执行行前 / 绑定前 / 对象体首成员前);**被绑定的表永不视为契约表**。
|
||||
- **验收**:三附着面金样 + 「绑定表不吃」反例金样(web_db_migration 式 `字段|类型|可空` 绑定数据表必须原样是数据);未知类型名(`nubmer`)必产诊断。
|
||||
|
||||
### T2.2 四边界运行时校验
|
||||
|
||||
- **产出**:`src/interp.rs` 接入四边界——调用实参 / 字段访问(`[键](集合)`、`.field`)/ 表绑定 / `*…*` 返回
|
||||
- **实现要点**:只在**该边界有契约**时校验(无契约 = 全动态,P1);诊断一律走 T1.4 出口(`code=contract.*`)。
|
||||
- **验收**:有契约 + 错值 → 必产诊断;**无契约路径全量回归零变化**;three-problems.md §5.2(c) 消融材料可产。
|
||||
|
||||
### T2.3 `marqdo check` + `--json`
|
||||
|
||||
- **产出**:`src/check.rs` + `src/main.rs` `Commands::Check`
|
||||
- **实现要点**:静态**按需**校验(只查有契约处);不做全局推导。
|
||||
- **验收**:契约样例工程 `check` 退出码非 0 且 JSON 合协议;干净工程 0 退出零输出。
|
||||
|
||||
### T2.4 锚点诊断
|
||||
|
||||
- **产出**:契约诊断填 `doc_anchor`(契约表行段 `file#Lx-Ly`)+ `doc_quote`(表行原文)
|
||||
- **验收**:金样断言锚点非空且行号回读命中契约表;three-problems.md §5.2(a) 材料就绪。
|
||||
|
||||
### T2.5 契约 vs 实现互查(防漂移)
|
||||
|
||||
- **产出**:check + 运行时提示——契约参数名 ≠ 升参名 / 未知类型 / 返回契约明显不符 → 诊断
|
||||
- **验收**:故意写错契约的金样**必红**(three-problems.md §5.2(d) 材料就绪)。
|
||||
|
||||
### T2.6 运行时内省 `get_schema`(可延后,P3)
|
||||
|
||||
- **产出**:`src/builtin.rs` 内省 builtin(契约是数据,P3)
|
||||
- **验收**:demo 运行中取回自身函数契约并打印。
|
||||
|
||||
---
|
||||
|
||||
## Phase 3 · MLSP(下一步的超级核心;本期只留接口)
|
||||
|
||||
### T3.1 `marqdo schema`(schema 注册表,三来源零手写)
|
||||
|
||||
- **产出**:`src/schema.rs` + `Commands::Schema`——语言面(core-surface 机械转 JSON)+ 函数/类型面(**契约** + stdlib/ext 签名)+ 项目面(`catalog.yaml`)
|
||||
- **验收**:两次生成 byte-identical;stdlib 主函数覆盖率 ≥ 90%。
|
||||
|
||||
### T3.2 `marqdo mcp`(AI 工具面)
|
||||
|
||||
- **产出**:MCP server(参考 `plugins/agent/src/mcp_server.rs`)——`syntax_list` / `syntax_get` / `fn_schema` / `type_schema` / `validate` / `repair` / `run`
|
||||
- **验收**:MCP 客户端冒烟:`fn_schema` → `validate` → `repair` 全链路。
|
||||
|
||||
### T3.3 查询式 AI Skill
|
||||
|
||||
- **产出**:`skills/marqdo/` 改写——十条硬规则 + 查询工作流(construct → validate → 修 → run);细节一律走 `syntax_get` / `fn_schema`
|
||||
- **验收**:skill 体积减半以上;金样全绿。
|
||||
|
||||
### T3.4 修复回路
|
||||
|
||||
- **产出**:repair 规则库 + 语句级 patch(AST span 对齐;预算 N=3;防循环)
|
||||
- **验收**:注入 bug 金样一轮修复率可测(three-problems.md §5.2(a) 执行就绪)。
|
||||
|
||||
---
|
||||
|
||||
## Phase 4 · 验证实验(**协议 = [perf-validation.md](perf-validation.md)**)
|
||||
|
||||
- 2026-09-23 用户授权**自行设计**性能验证设计并执行验证;`doc/next/002.md` 与性能验证无关(此前「待导入」表述已纠正)。
|
||||
- five 实验 (a)–(e) 的**材料由 Phase 1–3 的验收金样直接供给**;协议 / 指标 / 判据见 [perf-validation.md](perf-validation.md) §1–§5;
|
||||
实验产物 = [perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)。
|
||||
|
||||
---
|
||||
|
||||
## 完成定义
|
||||
|
||||
| 阶段 | 完成定义 |
|
||||
|------|----------|
|
||||
| Phase 1 | T1.1–T1.4 验收全绿 |
|
||||
| Phase 2 | T2.1–T2.5 验收全绿(T2.6 可延后) |
|
||||
| Phase 3 | T3.1–T3.4 验收全绿 |
|
||||
| 三大问题「已解决」 | [three-problems.md](three-problems.md) §5.1 判据矩阵全绿 + 实验数字可复现(Phase 4) |
|
||||
|
||||
## 落地记录
|
||||
|
||||
### Phase 2 · 渐进式契约层(2026-09-22 完成 T2.1–T2.5;T2.6 按计划延后至 Phase 3)
|
||||
|
||||
- **T2.1** `src/contract.rs`(类型词汇/三形状契约表解析/合并/四边界校验诊断)+
|
||||
`src/parse/mod.rs::extract_function_contract`(位置 + 形状双重判定,**在升参推断之前**执行——
|
||||
契约表的单元不会被误升参;契约表从 body 移除,元数据永不执行)。
|
||||
反例守住:**绑定**的 `字段|类型` 数据表(web_db_migration 风格)绝不视为契约。
|
||||
- **T2.2** 四边界全接:调用实参(普通/库路径/方法三条调用路径)、返回、表绑定、字段访问
|
||||
(键存在性**先于**取值,契约诊断优先于 `missing map key`)。列语义按「几何即类型」:标量或全匹配列向量。
|
||||
- **T2.3/T2.5** `marqdo check [FILE] [--json]`:契约行 vs 升参推断形参双向互查
|
||||
(错行 ⇒ Error;新升参未覆盖 ⇒ Warning)、未知类型名(附最近建议)、错位契约;Error ⇒ 非零退出。
|
||||
- **T2.4** 全部契约诊断带 `doc_anchor`(`file.mq.md#L7-L13`)+ `doc_quote`(契约表原文)+
|
||||
`contract_ref`(`declared` = 契约声明摘要);`run --json` / `check --json` 同源输出。
|
||||
- **附带修复(错误出口唯一)**:`src/load.rs` 原来把 parse 错误 `anyhow!("{label}: {e}")` 拍平成字符串,
|
||||
结构化诊断在 import 装载链路丢失;改为 `label_error` 保留 Diagnostic(补文件标签),任何装载层都不许拍平错误。
|
||||
- 验收:`tests/contracts.rs` 12 例(提取 4 + 四边界 4 + check 3 + 正向对照 1)全绿;
|
||||
全量回归零失败(含 262 gold)。
|
||||
- **T2.6(契约导出 `get_schema`)**:按计划延后至 Phase 3 与 MLSP `schema` 一并实现。
|
||||
|
||||
### Phase 3 · MLSP(2026-09-22 完成 T3.1–T3.4 全部工程项 + T2.6)
|
||||
|
||||
- **T3.1** `marqdo mlsp` 子命令:行分隔 JSON over stdio,请求 `{"id","method","params"}` →
|
||||
响应 `{"id","ok","result"|"error"}`(永不 panic,错误也是结构化 JSON)。
|
||||
- **T3.2** 五个 handler 全部实现(`src/mlsp.rs`):
|
||||
`locate`(构造卡片 / 符号定位 + 契约)、`syntax`(关键字/别名 → 卡片;语法唯一事实来源 =
|
||||
`parse::CORE_CONSTRUCTS`,MLSP 只加检索别名不定义语法)、`validate`(parse + 契约 check → 结构化诊断数组)、
|
||||
`repair_targets`(有界修复靶点:`strategy=anchored-local`、`on_violation=abstain`——越界必拒护栏先行)、
|
||||
`schema`(**T2.6 完成**:单元名 → 形参/返回/字段契约 + 升参清单 + 锚点)。
|
||||
- 验收:`tests/mlsp.rs` 7 例全绿(语法问答/未知查询/符号定位/漂移校验/schema 导出/有界修复/结构化错误);
|
||||
stdio 冒烟通过;全量回归零失败。
|
||||
- **T3.4(修复回路)**(2026-09-22 完成工程项)——`src/repair.rs` **机械护栏**(有界行编辑
|
||||
replace/delete/insert:触碰行必须落在靶点范围内,越界 ⇒ 整体拒绝 + 越界清单 + abstain,源零字节不改;
|
||||
表尾追加允许 end+1)+ `mlsp repair_apply` 出口(护栏的 MLSP 面)+ **golden 20 例**
|
||||
(10 骨架 × 2 变体:arg/ret/field/key/typo/drift/dup;金修复经完整修复循环复现——诊断 → 靶点 →
|
||||
行编辑自动推导 → 范围自检(「易锚定」的机器验证)→ 应用 → 复验)+ 护栏负例(越界必拒/部分越界全拒)。
|
||||
**模型实验完成(2026-09-22 · `tests/repair_experiment.rs` · 双模型三轮 @ llm.cflmy.cn)**:
|
||||
§5.2(a) 锚点消融——`anchor` 臂(诊断带 `doc_anchor`/`doc_quote`/`suggestion`)**一轮修复率最高 20/20 = 100%**(目标 ≥80% ✅);
|
||||
`plain` 臂(去锚)85%–100%。三轮汇总:
|
||||
|
||||
| 轮 | 模型 | anchor 一轮 | anchor 最终 | plain 一轮 | plain 最终 | 护栏越界 |
|
||||
|---|---|---|---|---|---|---|
|
||||
| 1 | `cflmy`(Qwen3.8-Flash-Next) | **20/20(100%)** | 100% | 17/20(85%) | 17/20 | 0 |
|
||||
| 2 | `mimo-v2.6-flash`(容错加固中) | 18/20(90%) | 19/20(95%) | 19/20(95%) | 19/20 | 0 |
|
||||
| 3 | `mimo-v2.6-flash`(容错补齐后) | **20/20(100%)** | 100% | 18/20(90%) | 19/20(95%) | 0 |
|
||||
|
||||
**"≥80% 一轮修复率"三轮双臂全部达标(最低 85%)**;护栏 0 越界(越界必拒/abstain 由确定性测试
|
||||
`tests/repair_loop.rs` 硬断言覆盖)。实验同时是 `validate`→`repair_targets`→`repair_apply` 功能面的真实消费者。
|
||||
**"不稳定"定性为三类测量端问题,均已加固**(与 Marqdo 语义无关):① 网关空体抖动 → curl `--retry` + 5s 退避;
|
||||
② 推理模型 token 预算被 `reasoning_content` 吃光 → `max_tokens` 2000→8000;③ 模型输出格式畸形 → 解析容错
|
||||
(数组/单对象/NDJSON 多对象流/字符串化元素/字符串型行号/围栏/数字后多余引号的确定性修补)。
|
||||
锚点增量观察:易锚定样本两臂都高(天花板效应),cflmy 上 anchor +20pp 明显、mimo 上持平——
|
||||
**锚点价值的区分性验证留 Phase 4**(难样本/信息受限消融)。
|
||||
报告:[repair-experiment-2026-09-22.md](repair-experiment-2026-09-22.md)(cflmy)、
|
||||
[repair-experiment-2026-09-22-mimo-v2.6-flash.md](repair-experiment-2026-09-22-mimo-v2.6-flash.md)(mimo 终测)。
|
||||
- **T3.3(AI Skill 换骨:背语法 → 查 MLSP)**(2026-09-22 完成)——`marqdo` / `marqdo-dev` 两件套改为
|
||||
查询式工作流:写码前 `mlsp syntax/locate`、提交前 `mlsp validate` + `marqdo check`;
|
||||
渐进式契约三种表格形状入语法面;错误修复照 `doc_anchor` 局部改(越界必弃权)。
|
||||
|
||||
## Phase 4 · 验证执行记录(2026-09-23,协议 [perf-validation.md](perf-validation.md))
|
||||
|
||||
- **(a) 锚点修复消融** ✅ PASS——判据「anchor 一轮 ≥80% + 护栏 0 越界」:cflmy anchor 20/20=100%(plain 85%)、
|
||||
mimo-v2.6-flash anchor 20/20=100%(plain 90%),越界拒/越界应用 0/0。易锚定样本近天花板,
|
||||
增量区分性留难样本扩展(协议 §1 诚实注记)。
|
||||
- **(b) 盲测(查询式 vs 全文档背诵)** ❌ 四判据未全立 ⇒ 按 three-problems.md §3.7 **继续改协议**——
|
||||
deepseek-flash:docs 4/6 vs query 0/3(端点 infra 剔除 3/6);首轮语法错 2/3 vs 2/6;token 69,771 vs 57,276。
|
||||
mimo-v2.6-pro 两跑均端点 infra(12/12、11/12,**不可评估**;结果回填 [perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md) §3)。
|
||||
**真发现**:查询机制本身无缺陷(多词查询亦正确命中卡片),败例是**跨语言习惯泄漏**(元组表达式/Python 调用形)
|
||||
——模型"不知道自己不知道"而不去查。协议改进主攻方向:**自查触发机制**(validate 前置自检、
|
||||
陌生构造强制查询),而非继续改进卡片。
|
||||
- **(c) 契约消融** ✅ PASS——拦截率 4/4=100%、误报率 0/4=0%、无契约零回归 4/4(四边界:调用实参/返回/表绑定/键访问)。
|
||||
- **(d) 防漂移演练** ✅ PASS——必报率 9/9=100%(9 类故意写错全数诊断)、负对照误报 0/2。
|
||||
- **(e) 核心守卫演练** ✅ PASS——3/3 变异注入必红(清单私增/文档私增/金样删除)、还原必绿。
|
||||
- **判据矩阵回填**:three-problems.md §5.1 逐行标注——问题 1 ✅、问题 2 ✅、**问题 3 ❌(未解决)**。
|
||||
- **测量端记录**:LLM 网关随机空体为最大干扰(重试 5→12 次、退避 5→15 秒、截断自适应 max_tokens);
|
||||
harness 修复两处协议性 bug(查询额度用满误判、提取失败不进修复回路)后采样;
|
||||
模型口径按用户指示由 `cflmy`/`mimo-v2.6-flash` 改 `mimo-v2.6-pro`/`deepseek-flash`(实验 (a) 数据为原组合,不重跑)。
|
||||
- **全量干净回归**(无 API key 基线)零失败。
|
||||
@@ -0,0 +1,393 @@
|
||||
# Marqdo 三大问题:解决方向与验证设计
|
||||
|
||||
——证明「被解决」,而不是「被遮盖」
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **设计 · 已导出本期开发任务:[three-problems-plan.md](three-problems-plan.md);验证实验不属于开发任务** |
|
||||
| 日期 | 2026-09-22 |
|
||||
| 来源 | [001.md](../next/001.md) 评审讨论提炼的三大问题;用户决议:**问题二走「渐进式契约 / 标注类型」**(拒绝照搬静态类型,也拒绝放弃语义校验);**问题三(AI 可靠反馈 + AI 不必学语法)是下一步的超级核心** |
|
||||
| 相关 | [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md)(语法宪法)· [tables-maps-footnotes.md](tables-maps-footnotes.md)(表格几何)· [catalog-cli.md](../design/catalog-cli.md) · [ai-skill.md](../design/ai-skill.md) · [objects.md](../design/objects.md) · [interpreter.md](interpreter.md) |
|
||||
|
||||
> **本文定位:三大问题的解决方向与验证设计。** 给三大问题定义「什么算被解决」(机器可验证判据,见 §5.1)与验证实验(修复率 / 盲测 / 消融 / 防漂移演练,见 §5.2),把「真正解决」与「遮盖过去」区分开。文中的解决步骤(各节 S 表)是**设计方向**;本期开发任务、排期与验收以 [three-problems-plan.md](three-problems-plan.md) 为准。**验证实验(§5.2)协议见 [perf-validation.md](perf-validation.md)**(2026-09-23 用户授权自行设计并执行)。
|
||||
>
|
||||
> **一句话:语言核心收口是地基;渐进式契约是校验层,schema 直接长在表格与说明段落里;AI 语言服务消费这两者形成可靠闭环。** 三个问题必须一起解——契约是 AI 接口的数据源,核心收口是契约语法不膨胀的前提。
|
||||
|
||||
**贯穿戒律(防止「遮盖式解决」):每个阶段的验收必须是机器可验证的行为变化。只产出宣言文档、不改变工具行为的,一律视为未完成。**
|
||||
|
||||
---
|
||||
|
||||
## 0. 问题清单与依赖
|
||||
|
||||
| # | 问题 | 定位 | 一句话方案 |
|
||||
|---|------|------|-----------|
|
||||
| 1 | 语言核心正在被生态功能淹没,identity 不清 | **地基** | 三层归属表 + 准入戒律 + 核心表面守卫(CI 断言) |
|
||||
| 2 | 「静态类型列为非目标」被误读为「不需要语义校验」;但照搬 Java/TS 静态类型会毁掉低摩擦 | **校验层** | **渐进式契约**:schema 写在表格 / 说明段落里;按需契约校验;诊断带文档锚点 |
|
||||
| 3 | AI 反馈不可靠(只有给人看的文本);AI 还在背千行语法文档 | **超级核心** | **Marqdo Language Server for AI(MLSP)**:结构化诊断协议 + 可查询 schema + 修复回路 |
|
||||
|
||||
依赖链:
|
||||
|
||||
```text
|
||||
问题 1(核心收口:契约语法不许越界进核心)
|
||||
└─→ 问题 2(契约层:schema 源头 = 表格 / 说明段落)
|
||||
└─→ 问题 3(schema 注册表 = 契约 + 核心表面 + catalog)
|
||||
└─→ 实证(修复实验 + 消融基准 → README 愿景 6)
|
||||
```
|
||||
|
||||
共享地基先行项:**统一诊断协议(Diagnostic)**——问题 2 的契约校验与问题 3 的 AI 反馈都以它为出口,因此它排在最前(见 §3.3 与 §4)。
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题一:语言核心必须小
|
||||
|
||||
### 1.1 诊断
|
||||
|
||||
Marqdo 现在同时是:Markdown 语言 + literate programming + 知识库 + catalog + web + WASM + 浏览器 + LLM + agent + MCP + 量子 + 线代 + 插件 ABI。工程上这很酷;语言设计上的危险是:
|
||||
|
||||
> **核心语言的 identity 被生态功能淹没;新功能随手进核心 → 语法面暗中膨胀。**
|
||||
|
||||
真正缺的不是「收敛宣言」,而是**三样机制**:
|
||||
|
||||
1. 一份穷举的**核心表面清单**——现在「什么算核心」没有唯一明文;
|
||||
2. 一张**三层归属表**——新提案无处登记,默认哪儿都塞;
|
||||
3. 一条**越界即可见的守卫**——核心语法暗增长没有任何机器报警。
|
||||
|
||||
### 1.2 目标 / 非目标
|
||||
|
||||
**目标**:Language / Runtime / Document 三层分离;核心标记维持**约 15 个**的封闭集合,生态增长不再增加语言面。
|
||||
|
||||
**非目标**:删掉 web/quantum/agent 等功能(它们不是错,层次混放才是错);重写解释器;给核心加模块可见性等系统编程特性。
|
||||
|
||||
### 1.3 三层归属表(S1 产出物,此处先锁定语义)
|
||||
|
||||
| 层 | 内容 | 仓库位置 |
|
||||
|----|------|----------|
|
||||
| **Language** | 标记映射、词法/行分类、AST、语义、升参、**契约检查器**、诊断 | `src/`(解释器核心)· `doc/design/markdown-mapping-v0.3.md` |
|
||||
| **Runtime** | stdlib、插件 ABI、WASM、debugger、view、catalog / schema CLI、MCP | `lib/` · `plugins/` · `crates/` · `src/bin` |
|
||||
| **Document** | 知识单元、skills、示例、public 站、agent 工作流、官方扩展 | `*.mq.md` · `skills/` · `ext/` · `public/` · `examples/` |
|
||||
|
||||
核心表面清单(S1 的枚举基线,来自宪法 §5,逐项进 `core-surface.md`):
|
||||
|
||||
叙述(含 `` `名` `` 声明/引用)· `**…**` 代码 · `*…*` 返回 · 空返回形(`*None*` 等)· `>` 调用 · `#` / `##` 标题单元 · 体内 `1.` 分支 · `-` 循环 · GFM 表格 = 集合 · `[键](集合)` 取元 · `修饰… [函数名]` 方括号调用 · 脚注取元(过渡)· ` ```lang ` 外联 · `---` 叙述分隔 · `` + `名` `` 形参(兼容形)。
|
||||
|
||||
### 1.4 解决方向(设计 · 任务化见 plan)
|
||||
|
||||
| 步 | 动作 | 产出 | 验收(机器可验证) |
|
||||
|----|------|------|--------------------|
|
||||
| S1 | 写 `doc/design/core-surface.md`:穷举核心标记,每个标记一行「戒律」(语义、边界、**为什么不能是普通 Markdown**) | 核心表面唯一清单 | 清单项 ↔ `tests/markup-v03/` 金样逐项有例;缺项即测试红 |
|
||||
| S2 | 写 `doc/design/layers.md`:§1.3 归属表 + **准入戒律**——任何新特性提案必须先填「进哪层」;进 Language 层必须答「为什么现有标记不够」,默认答案是「进 ext」 | 归属与准入制度 | 仓库 PR 模板加「层归属」必填项 |
|
||||
| S3 | 核心表面守卫:Rust 测试断言「词法分类枚举 ↔ core-surface.md 表格」一致(脚本解析 markdown 表格比对枚举名) | `tests/core_surface.rs` | 故意加一个新标记不更新清单 → CI 红 |
|
||||
| S4 | 核心变更强制走 ADR:新增核心标记必须有 `doc/adr/` 编号 + 反例说明;每个 release 的 CHANGELOG 单列「核心表面 Δ」 | ADR 戒律 | 发版 checklist 含「核心表面 Δ」栏 |
|
||||
| S5 | 文档收口:README/doc 目录按三层重排;`doc/design/` 只收 Language 层决策,Runtime 进 `doc/roadmap/`,生态面进各自 ext 文档 | 重排后的文档树 | README 目录树与三层表一一对应 |
|
||||
|
||||
**观测指标**(不是 KPI,是体检):核心标记计数每个 release 只许持平或下降;连续 3 个版本增长即触发 Language 层复盘。
|
||||
|
||||
### 1.5 遮盖 vs 解决
|
||||
|
||||
| 遮盖式做法(禁止) | 本方案的做法 | 判据 |
|
||||
|--------------------|--------------|------|
|
||||
| 写一篇「语言核心很重要」的宣言 | 清单 + 归属表 + **CI 守卫** | 新增标记不更新清单时 CI 必须红 |
|
||||
| 「以后尽量不加语法」的口头约定 | ADR 强制 + CHANGELOG 核心表面 Δ | 没有 ADR 编号的核心变更不允许合并 |
|
||||
| 把 ext 功能砍掉显得小 | 不砍功能,只**归层** | web/quantum/agent 全部保留且测试通过 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 问题二:渐进式契约 / 标注类型
|
||||
|
||||
### 2.1 分歧点澄清(本方案的立场)
|
||||
|
||||
GPT 一侧强调「AI 可验证语言需要强语义校验」,容易被听成「上静态类型」。**这两件事不一样**:
|
||||
|
||||
> 「放弃全程序静态编译类型」**≠** 「放弃语义检查、字段解析、契约校验」。
|
||||
|
||||
照搬 Java/TS 式静态类型会破坏「自然叙述优先、低摩擦」的体验——Marqdo 会变得笨重,丢掉对业务人员 / agent 即兴脚本的友好性。**目标不是变成静态语言,而是一套附着在文档单元上的可查询契约系统,作为 AI 闭环里的校验层。**
|
||||
|
||||
渐进式契约的四条特征:
|
||||
|
||||
1. **动态默认**——不强制任何标注,保持动态,适合快速原型与 agent 即兴脚本;
|
||||
2. **契约即文档**——schema 可选地写在**表格、文档段落**里,不引入第二套标注语言;
|
||||
3. **按需校验**——不做全局类型推导;在调用边界 / 字段访问时校验「当前值 vs 契约」;
|
||||
4. **诊断即文档链接**——错误不只报类型错,还定位到文档里对应的说明段落,给 AI 的诊断自带文档上下文。
|
||||
|
||||
**独有优势(TS/Python 做不到)**:契约的 schema 源头就是表格与函数说明段落本身——不是额外写一套 JSON Schema。知识、契约、数据、代码在同一份 `.mq.md` 里,**契约即知识**。这是 Knowledge-Code Coherence 的第一个可落地实证:契约说 `int` 实际来了 `text` 时,被机器抓住的不是「文档过期」,而是**知识不一致**。
|
||||
|
||||
### 2.2 设计原则
|
||||
|
||||
| # | 原则 | 含义 |
|
||||
|---|------|------|
|
||||
| P1 | 无契约 = 全动态 | 没写契约的单元行为**一字不变**(零回归是硬验收) |
|
||||
| P2 | 不新增核心标记 | 契约语法全部骑在现有 Markdown 外形上(问题一戒律直接约束本节) |
|
||||
| P3 | 契约是数据 | 契约表本身就是 Marqdo 集合,运行时可内省(`get_schema` 一类的 lib 函数免费获得) |
|
||||
| P4 | 双向防漂移 | 不只「值 vs 契约」,还查「契约 vs 实现」(§2.7-S5) |
|
||||
| P5 | 诊断带锚点 | 凡契约诊断必含:契约表所在文件 + 行段 + 原文引用 |
|
||||
|
||||
### 2.3 契约的三个附着面
|
||||
|
||||
**A. 函数契约** —— `##` 函数体内、首个可执行行之前的**未绑定文档表**:
|
||||
|
||||
```markdown
|
||||
## 加一
|
||||
|
||||
加一函数:把输入加一。
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| `n` | number | 输入值 |
|
||||
|
||||
| 返回 | 类型 | 说明 |
|
||||
|------|------|------|
|
||||
| — | number | n+1 |
|
||||
|
||||
对于输入变量`n`,执行**n=n+1**接着返回*n*。
|
||||
```
|
||||
|
||||
参数仍由 v0.3 升参推断(宪法 §8),契约**不改变**形参机制,只在存在时校验——零摩擦兼容存量代码。
|
||||
|
||||
**B. 集合 / 表格契约** —— 紧邻 `` `名` = `` 绑定之前的未绑定文档表:
|
||||
|
||||
```markdown
|
||||
| 字段 | 类型 | 可空 |
|
||||
|------|------|------|
|
||||
| id | number | 否 |
|
||||
| name | text | 否 |
|
||||
|
||||
`用户` =
|
||||
|
||||
| 行 | id | name |
|
||||
|----|----|------|
|
||||
| 1 | 1 | 甲 |
|
||||
```
|
||||
|
||||
**C. 对象契约** —— `# 对象` 体内首个成员之前的 `| 字段 | 类型 |` 表;同时被 catalog 提取为条目 schema(见 §3.5 项目面)。
|
||||
|
||||
**先例**:schema 长在表格里今天已经发生——`web_db_migration` 的 `| 字段 | 类型 | 可空 |` 列就是以数据形式传递的 DDL schema。契约系统把这个模式升格为**通用约定**。
|
||||
|
||||
### 2.4 形态选型(为什么是「契约表」)
|
||||
|
||||
| 候选 | 形态 | 判决 |
|
||||
|------|------|------|
|
||||
| **P-A 契约表**(选定) | 列头关键字(`参数`/`返回`/`字段`/`类型`/`说明`)的未绑定文档表 | ✅ 与「GFM 表格即数据」哲学一致;catalog 可提取;人读无负担 |
|
||||
| P-B 叙述内标注 | `` `n`: int `` 写在散文里 | ❌ **否决**:改动行内 `` `名` `` 词法 = 核心标记变更,违反问题一戒律与 P2 |
|
||||
| P-C frontmatter | YAML 声明契约 | ⚠️ 仅作文件级汇总的可选补充(serde_yaml 已在解析元信息);函数粒度不够,不作主形态 |
|
||||
|
||||
**消歧规则(防「契约表」误吃数据表)**:
|
||||
|
||||
1. **被绑定的表永不视为契约表**——`名` = 后的表是数据(宪法 §5:未绑定才「求值后丢弃」,即文档表)。`web_db_migration` 的列头恰好叫 `字段|类型|可空` 但它是绑定数据,不受影响;
|
||||
2. 契约表必须是**未绑定文档表** + 列头命中关键字集,且出现在允许位置(§2.3 A/B/C);
|
||||
3. 同一位置出现多张契约表:参数表与返回表各认各的列头;其余重复 → 诊断(防两份契约打架)。
|
||||
|
||||
### 2.5 类型词汇(刻意做小)
|
||||
|
||||
`text` · `number` · `bool` · `list` · `map` · `any` · 对象名(与 `# 对象` / `_type` 对齐)。
|
||||
|
||||
- 词汇表**只有这一行**;扩展类型词汇 = Language 层变更,走 ADR(问题一 S4)。
|
||||
- 类型名拼错(如 `nubmer`)→ **必须报诊断**(§2.7 验收),否则契约本身成为新的漂移源。
|
||||
|
||||
### 2.6 校验时机(按需四边界,不做全局推导)
|
||||
|
||||
| 边界 | 校验什么 | 时机 |
|
||||
|------|----------|------|
|
||||
| 调用实参 | 实参值 vs 参数契约(类型 + 可选 required) | 运行时调用瞬间;`check` 静态可查处一并查 |
|
||||
| 字段访问 | `[键](集合)` / `obj.field` vs 字段契约(键存在性 + 类型) | 访问瞬间 |
|
||||
| 表绑定 | `` `名` = `` 表的几何/单元格 vs 集合契约 | 绑定瞬间 |
|
||||
| 返回 | `*…*` 值 vs 返回契约 | 返回瞬间 |
|
||||
|
||||
无契约 → 该边界直接跳过(P1)。校验器**不是**编译器:不做跨函数全局推导、不要求全程序一致。
|
||||
|
||||
### 2.7 解决方向(设计 · 任务化见 plan)
|
||||
|
||||
| 步 | 动作 | 产出 | 验收(机器可验证) |
|
||||
|----|------|------|--------------------|
|
||||
| S1 | 契约提取器:按 §2.3/§2.4 规则解析未绑定文档表 → `Contract` 对象,挂入 AST 单元(`Param` 已有 `span`,契约同级带 `span`) | AST + 提取器 | 金样:三附着面各一份提取断言(含「绑定表不吃」反例) |
|
||||
| S2 | 运行时边界校验:§2.6 四边界接入 `Contract` | 运行时校验 | 有契约 + 错值 → **必**产出 §3.3 诊断;无契约金样**全绿零回归** |
|
||||
| S3 | `marqdo check`:静态按需校验(只查有契约处),`--json` 输出诊断 | CLI | 契约样例工程 `check` 退出码非 0 且诊断 JSON 合协议 |
|
||||
| S4 | 诊断锚点:契约错误必带 `doc_anchor` + `doc_quote`(契约表原文行) | 诊断增强 | 金样断言诊断 JSON 里锚点字段非空、行号可回读原文 |
|
||||
| S5 | **契约 vs 实现互查**(P4):契约参数名 ≠ 升参推断名、契约类型名未知、契约返回 vs 语句结构明显不符 → 诊断 | 防漂移检查 | 故意写错契约的金样**必须**红(而不是静默信任契约) |
|
||||
| S6 | 运行时内省:`lib` 提供 `get_schema 单元=…`(P3:契约是数据) | lib 函数 | demo:运行中取回自身函数契约表并打印 |
|
||||
|
||||
### 2.8 遮盖 vs 解决
|
||||
|
||||
| 遮盖式做法(禁止) | 本方案的做法 | 判据 |
|
||||
|--------------------|--------------|------|
|
||||
| 把「静态类型」继续列为非目标就收工 | 明确「≠ 放弃语义校验」,落**边界校验器** | 运行时行为变化可测(§2.7-S2) |
|
||||
| 照搬 Java/TS 全程序静态类型 | 渐进式:无标注零摩擦,按需四边界 | 无契约金样零回归 |
|
||||
| 另写一套 JSON Schema 文件 | schema = 表格 / 说明段落本身 | 仓库里**不允许**出现手写的第二份 schema;契约只能从 `.mq.md` 提取 |
|
||||
| 契约写了就永远正确 | 契约 vs 升参互查 + 未知类型名必报 | 故意写错契约的金样必红 |
|
||||
| 错误只报 `type mismatch` 文本 | 诊断带文档锚点 + 原文引用 | 金样断言锚点字段 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 问题三(超级核心):AI 可靠反馈 + AI 不必学语法细节
|
||||
|
||||
### 3.1 两个子问题
|
||||
|
||||
**A. 可靠反馈**:今天解释器诊断是给人看的文本(`path:line:col` + message,见 ai-skill「按诊断迭代」)。AI 拿到它要「猜」哪里错、对应文档哪句话、怎么改。GPT 设想的闭环——
|
||||
|
||||
```text
|
||||
LLM → Marqdo → 语义校验 → 结构化 Error → LLM 修复 → 合格程序
|
||||
```
|
||||
|
||||
——的第一块砖就是**结构化诊断**,而且诊断必须自带文档上下文(问题二 §2.1-4 的锚点在这里被 AI 消费)。
|
||||
|
||||
**B. 不必学语法**:今天 `skills/marqdo` 是「面向模型的压缩操作手册」= **背诵式**。正确形态是**查询式**:
|
||||
|
||||
```text
|
||||
AI ── discover ─→ construct ─→ validate ─→ execute ─→ inspect
|
||||
```
|
||||
|
||||
AI 不阅读一千行文档然后猜,而是按需调 `get_syntax("branch")`、`fn_schema("print")`、`validate(program)`。**这才是 Marqdo 与普通 DSL 拉开距离的地方。**
|
||||
|
||||
### 3.2 总形态:Marqdo Language Server for AI(MLSP)
|
||||
|
||||
一套机器可读的语言服务协议。工具面(首版最小集):
|
||||
|
||||
| 工具 | 入参 | 返回 | 数据源 |
|
||||
|------|------|------|--------|
|
||||
| `syntax_list` / `syntax_get` | — / 构造名 | 核心构造表 / 单构造戒律 | core-surface(问题一 S1,机械转 JSON) |
|
||||
| `fn_schema` | 函数名 | 参数/返回契约 + 说明 + 锚点 | 契约(问题二)+ stdlib/ext 签名 |
|
||||
| `type_schema` | 对象名 | 字段契约 + 方法表 | `# 对象` 契约 + catalog |
|
||||
| `validate` | 程序文本/文件 | `Diagnostic[]` | 契约校验器 + 语义检查 |
|
||||
| `repair` | 程序 + 诊断 | 建议 patch(限定行级) | 诊断规则库 |
|
||||
| `run` | 入口 | 结果或结构化错误 | 运行时 |
|
||||
|
||||
交付通道(按序):**`marqdo mcp`**(MCP server,复用 agent ext 的 MCP 经验)→ CLI `--json`(任何宿主可用)→ `skills/marqdo` 改造成「教 AI 查询」(§3.6)。
|
||||
|
||||
### 3.3 先决:统一诊断协议(可靠反馈的地基)
|
||||
|
||||
所有层(解释器、check、契约、插件错误)统一产出:
|
||||
|
||||
```json
|
||||
{
|
||||
"code": "contract.arg_mismatch",
|
||||
"severity": "error",
|
||||
"message": "参数 `n` 期望 number,实际 text",
|
||||
"span": { "file": "demo.mq.md", "line": 12, "col": 3, "heading": ["加一"] },
|
||||
"doc_anchor": "demo.mq.md#L4-L7",
|
||||
"doc_quote": "| `n` | number | 输入值 |",
|
||||
"contract_ref": { "unit": "加一", "kind": "param", "name": "n", "declared": "number" },
|
||||
"suggestion": "把实参改为数字;若契约有误,改契约表的类型列"
|
||||
}
|
||||
```
|
||||
|
||||
规则:
|
||||
|
||||
1. 凡可定位必带 `span`(AST 已有 span,宪法 §10.2);
|
||||
2. 凡契约错误必带 `doc_anchor` + `doc_quote`——**错误直接定位到文档里对应的说明段落**;
|
||||
3. 凡可修复建议必带 `suggestion`(给修复回路的原料);
|
||||
4. 人类文本输出保持现状,`--json` 并行提供——人机同读同写,诊断也一样。
|
||||
|
||||
### 3.4 修复回路(repair loop)
|
||||
|
||||
```text
|
||||
validate(p) → diagnose → patch(p, diag) → validate(p') → … (预算 N=3 轮)
|
||||
```
|
||||
|
||||
- **限定行级 patch**,不允许整文件重写(防止 AI「修复」时破坏叙述);
|
||||
- 尝试预算与重复诊断去重,防循环;
|
||||
- 实验指标:**一轮修复率**(带锚点 vs 不带锚点两组对比)——这是「可靠反馈」的直接证据。
|
||||
|
||||
### 3.5 Schema 注册表(三来源,零手写第二份)
|
||||
|
||||
| 面 | 来源 | 说明 |
|
||||
|----|------|------|
|
||||
| 语言面 | `core-surface.md` 机械转 JSON | 构造戒律原文进 `description` |
|
||||
| 函数 / 类型面 | **契约**(问题二产物)+ stdlib/ext 签名 | schema 源头 = 表格与说明段落(§2.1 独有优势) |
|
||||
| 项目面 | `catalog.yaml`(catalog 自动生成) | 知识单元、链接关系(知识图的边) |
|
||||
|
||||
格式 `marqdo-schema.json`(示意):
|
||||
|
||||
```json
|
||||
{
|
||||
"language": "marqdo",
|
||||
"version": "0.3",
|
||||
"constructs": [{ "name": "branch", "syntax": "1. … 2. … N. *", "rule": "自 1. 递增;重出 1. 开新判断" }],
|
||||
"functions": [{ "name": "加一", "params": [{ "name": "n", "type": "number", "desc": "输入值", "anchor": "#L4" }], "returns": { "type": "number" } }]
|
||||
}
|
||||
```
|
||||
|
||||
命令:`marqdo schema [PATH]`(catalog 的兄弟命令,同样**只生成不手改**)。
|
||||
|
||||
### 3.6 AI Skill:从「背诵」改「查询」
|
||||
|
||||
`skills/marqdo` 改造原则:
|
||||
|
||||
- `SKILL.md` 只留**十条不可违反的硬规则**(叙述默认安全、`**` 代码 `*` 返回、表格几何、命名/双语约定等)+ MLSP 工具用法;
|
||||
- 语法细节、API 明细**一律走 `syntax_get` / `fn_schema`**,不再进上下文;
|
||||
- 工作流改为:construct(凭硬规则写)→ `validate` → 按诊断修 → `run`。
|
||||
|
||||
### 3.7 解决方向(设计 · 任务化见 plan)
|
||||
|
||||
| 步 | 动作 | 验收(机器可验证) |
|
||||
|----|------|--------------------|
|
||||
| S1 | Diagnostic 结构落地(Rust)+ 解释器诊断改造 + `run --json` / `check --json` | 现有错误金样转 JSON 后 `code`/`span` 全非空 |
|
||||
| S2 | 契约诊断接入(消费 §2.7-S4 的锚点) | §2.8 判据全部成立 |
|
||||
| S3 | `marqdo schema` 生成器(三来源汇聚) | 生成物 diff 稳定(两次生成 byte-identical);stdlib 主函数覆盖率 ≥ 90% |
|
||||
| S4 | `marqdo mcp`:暴露 §3.2 工具面 | 用 MCP 客户端冒烟:`fn_schema` → `validate` → `repair` 全链路 |
|
||||
| S5 | `skills/marqdo` 改造为查询式(保留硬规则十条) | skill 体积减半以上;既有 `marqdo run` 金样仍全绿 |
|
||||
| S6 | 修复回路 + 实验执行(实验设计见 §5.2) | 实验报告(进 MarqdoThesis,对接 README 愿景 6) |
|
||||
|
||||
**「解决而不是遮盖」的最终判据(问题三)**:盲测组(零语法文档 + 工具)的成绩**不劣于**全文档背诵组,且 token 显著更少、修复轮次不升——达不到就继续改协议,**不许**用「再写一篇更好的文档」充数。
|
||||
|
||||
### 3.8 遮盖 vs 解决
|
||||
|
||||
| 遮盖式做法(禁止) | 本方案的做法 | 判据 |
|
||||
|--------------------|--------------|------|
|
||||
| 再写一份更全的 AI 语法文档 | 查询协议 + schema 注册表 | 盲测实验成立 |
|
||||
| 让 AI「多读 reference.md」 | `syntax_get` / `fn_schema` 按需取 | skill 体积减半且成绩不降 |
|
||||
| 报错文本润色一下 | 统一 Diagnostic JSON + 文档锚点 | 诊断金样断言锚点字段 |
|
||||
| 主观感觉「AI 好用了」 | 一轮修复率 / 盲测 / token 三组数字 | 实验报告可复现(MarqdoThesis) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 路线顺序(依赖序 · 排期见 [three-problems-plan.md](three-problems-plan.md))
|
||||
|
||||
> 本表是**依赖顺序**,不是排期表——任务化与本期范围见 [three-problems-plan.md](three-problems-plan.md)。
|
||||
|
||||
| 顺序 | 内容 | 产出 | 依赖 |
|
||||
|------|------|------|------|
|
||||
| **M0 核心收口** | 问题一 S1–S5 | core-surface.md · layers.md · CI 守卫 | — |
|
||||
| **M1 诊断地基** | 问题三 S1(Diagnostic + `--json`) | 统一诊断协议 | M0 |
|
||||
| **M2 契约层** | 问题二 S1–S6 | 提取器 · 四边界校验 · `check` · 锚点 · 防漂移 | M1 |
|
||||
| **M3 AI 语言服务** | 问题三 S2–S5 | schema 生成 · `marqdo mcp` · 查询式 skill · 修复回路 | M2 |
|
||||
| **M4 实证** | 问题三 S6 | 修复实验 + 盲测 + 消融(对接 README 愿景 6) | M3 |
|
||||
|
||||
顺序理由:Diagnostic 先于契约(契约诊断是它的第一个消费者);契约先于 MLSP(契约是 schema 注册表的主数据源)——**任何一个跳步都会倒逼「另写一套 schema / 另造一套错误」的遮盖式捷径**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验证矩阵与实验设计(本文核心)
|
||||
|
||||
### 5.1 判据矩阵:什么算「已解决」
|
||||
|
||||
| 问题 | 解决的定义(机器可验证) | 遮盖式收场(一句话就能写完的,禁止) | 验证手段 | 判定(2026-09-23) |
|
||||
|------|--------------------------|--------------------------------------|----------|--------------------|
|
||||
| 1 核心要小 | 新标记不更新 core-surface → **CI 红** | 「我们重视语言核心」 | CI 守卫演练:故意加标记不更新清单,必须红 | ✅ (e) 3/3 必红→还原必绿 |
|
||||
| 2 语义校验 | 四边界校验器上线;契约写错**必**被机器抓;无契约路径零回归 | 「静态类型是非目标」/照搬 TS 类型/另写 JSON Schema | 契约金样 + 防漂移金样 + 全量回归 | ✅ (c) 拦截 100%/误报 0%/零回归;(d) 必报 9/9 |
|
||||
| 3 AI 反馈 / 语法 | 盲测组错误率 ≤ 全文档组且 token 显著更少;一轮修复率可复现 | 「再写更好的文档」 | §5.2 实验 (a)(b)(d) | ❌ (a) 过(双模型 100%);**(b) 四判据未全立** ⇒ 按 §3.7 继续改协议 |
|
||||
|
||||
> 2026-09-23 实测数字与判据对照:[perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)。
|
||||
> 按本矩阵口径:**问题 1、2 实证成立;问题 3 未解决**(查询式盲测未跑赢全背诵——详见报告 §3 的四条要点,
|
||||
> 其中「模型不查自己不知道的语法」是协议改进的主攻方向)。
|
||||
|
||||
### 5.2 实验设计(性能 / 可靠性验证)
|
||||
|
||||
| 实验 | 对照组 | 指标 | 材料 |
|
||||
|------|--------|------|------|
|
||||
| (a) 锚点修复 | 诊断带 `doc_anchor` vs 不带 | 一轮修复率、平均修复轮次 | 注入已知 bug 的金样集 |
|
||||
| (b) 盲测(零语法文档) | 只给 MLSP 工具 vs 给全文档背诵(现 `skills/marqdo`) | 语法错误率、契约违规率、token 消耗 | 任务集(QuixBugs 类 + 业务逻辑类) |
|
||||
| (c) 契约消融 | 契约开 / 关 | 契约拦截率、误报率、无契约路径零回归 | 同上 |
|
||||
| (d) 防漂移演练 | 契约故意写错(类型 typo / 参数名与升参不符) | 必报率 = 100% | 契约金样 |
|
||||
| (e) 核心守卫演练 | 故意加新标记不更新清单 | CI 红 = 必须 | — |
|
||||
|
||||
实验基建:复用 MarqdoThesis `formal/exp1–3` 的 runner / oracle / 容错重试;报告即 README 愿景 6 的「可靠性基准」材料。**判据矩阵全绿 + 实验数字可复现之前,三大问题一律视为未解决**——这是「不遮盖」的最终保险。
|
||||
|
||||
---
|
||||
|
||||
## 6. 未决问题(进 M0/M2 的 ADR 逐条锁定)
|
||||
|
||||
1. 契约表消歧的边界案例:紧邻绑定的未绑定表(注释表)紧贴数据表时的归属规则要不要「隔空行才算分离」?(M2-S1 金样定夺)
|
||||
2. 参数表与返回表合并成单表(首列 `参数`/`返回` 混排)是否更可读?(M2-S1 对比样例后定)
|
||||
3. 对象字段契约:与 [objects.md](../design/objects.md) 「不把表当对象定义语言」的非目标如何划界——契约是**可选校验元数据**,不定义对象布局(对象仍是运行时 map);需 ADR 明文,避免与 [tables-maps-footnotes.md](tables-maps-footnotes.md) 非目标条目互相打架。
|
||||
4. 类型词汇是否收 `对象名` 之外的复合形(如 `list<number>`)?——默认**不收**,需要时走 ADR(P2 + 问题一 S4)。
|
||||
5. `marqdo check` 独立子命令 vs `run --check` 并存?(M2-S3 定,倾向独立 + `run` 默认轻查)
|
||||
6. `repair` 的 patch 边界:行级 patch 的具体格式(unified diff vs 语句级替换)?(M3-S4 定,倾向语句级——与 AST span 对齐)
|
||||
@@ -0,0 +1,12 @@
|
||||
# web-collab-doc
|
||||
|
||||
Two-browser collaborative notepad over WebSocket room (last-write-wins text).
|
||||
|
||||
```bash
|
||||
marqdo wasm build -o examples/web-collab-doc/static
|
||||
cd examples/web-collab-doc
|
||||
marqdo run index.mq.md
|
||||
# open http://127.0.0.1:18094 twice
|
||||
```
|
||||
|
||||
Design: [ext-web-collab.md](../../doc/design/ext-web-collab.md).
|
||||
@@ -0,0 +1,24 @@
|
||||
---
|
||||
title: web-collab-doc
|
||||
description: Two-browser collaborative plain-text editor over WS room (LWW snapshot sync)
|
||||
import web:ext/web/web.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Collaborative notepad: open the page in two browsers; edits fan out via
|
||||
`/live/{room}` WebSocket (mode=room + presence). Build WASM first:
|
||||
|
||||
```
|
||||
marqdo wasm build -o examples/web-collab-doc/static
|
||||
```
|
||||
|
||||
**`embed` = > web.client_embed bridge="/static/marqdo-bridge.js" wasm="/static/marqdo_wasm.wasm" source="/static/client.mq.md" boot=True**
|
||||
|
||||
**`intro` = "<p class='lede'>Room <code>demo</code> · open twice to co-edit.</p><p id='presence'>presence: —</p><textarea id='doc' rows='16' cols='72' placeholder='Type together…'></textarea><pre id='log'></pre>" + embed**
|
||||
|
||||
**page = > web.page title="Collab doc" intro=intro layout="bare"**
|
||||
**app = > web.app page=page host="127.0.0.1" port=18094**
|
||||
**app = > app.static dir="static" mount="/static"**
|
||||
**app = > `app`.route_ws path="/live/{id}" mode="room" room_key="doc.{id}" presence=True**
|
||||
> `app`.listen
|
||||
@@ -0,0 +1,85 @@
|
||||
---
|
||||
title: collab client
|
||||
description: LWW text sync over WS room + presence (DOC\\t protocol)
|
||||
import browser:lib/browser.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import text:lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**`ws_id` = "doc"**
|
||||
**`applying` = False**
|
||||
**`doc` = ""**
|
||||
|
||||
`wire` =
|
||||
|
||||
| @ | 选择器 | 事件 | 调用 | 值选择器 |
|
||||
|---|--------|------|------|----------|
|
||||
| 1 | "#doc" | input | on_edit | "#doc" |
|
||||
|
||||
`open` =
|
||||
|
||||
| op | id | url | then_open | then_message | then_error | then_close |
|
||||
|----|----|-----|-----------|--------------|------------|------------|
|
||||
| open | `ws_id` | "ws://127.0.0.1:18094/live/demo" | on_open | on_msg | on_err | on_close |
|
||||
|
||||
**`w` = > table.put in=None at="wire" value=wire**
|
||||
**`ws` = > browser.ws spec=open**
|
||||
**`boot` = > browser.merge a=w b=ws**
|
||||
**`ready` = > browser.set_text sel="#log" text="connecting…"**
|
||||
*> browser.merge a=boot b=ready*
|
||||
|
||||
## on_open
|
||||
+ `ok`=True
|
||||
|
||||
*> browser.set_text sel="#log" text="ws open · room demo"*
|
||||
|
||||
## on_err
|
||||
+ `error`=""
|
||||
|
||||
**`msg` = "ws error: " + error**
|
||||
*> browser.set_text sel="#log" text=msg*
|
||||
|
||||
## on_close
|
||||
*> browser.set_text sel="#log" text="ws closed"*
|
||||
|
||||
## on_edit
|
||||
+ `value`=""
|
||||
|
||||
1. `applying`
|
||||
**`applying` = False**
|
||||
****
|
||||
2. *
|
||||
**`doc` = value**
|
||||
**`payload` = "DOC\t" + value**
|
||||
`send` =
|
||||
|
||||
| op | id | data |
|
||||
|----|----|------|
|
||||
| send | `ws_id` | `payload` |
|
||||
|
||||
*> browser.ws spec=send*
|
||||
|
||||
## on_msg
|
||||
+ `data`=""
|
||||
|
||||
1. `data` != ""
|
||||
**`is_pres` = > text.starts_with text=data prefix="{"**
|
||||
1. `is_pres`
|
||||
**`msg` = "presence: " + data**
|
||||
*> browser.set_text sel="#presence" text=msg*
|
||||
2. *
|
||||
**`is_doc` = > text.starts_with text=data prefix="DOC\t"**
|
||||
1. `is_doc`
|
||||
**`remote` = > text.replace text=data old="DOC\t" new="" count=1**
|
||||
1. `remote` != `doc`
|
||||
**`doc` = remote**
|
||||
**`applying` = True**
|
||||
*> browser.set_value sel="#doc" value=remote*
|
||||
2. *
|
||||
****
|
||||
2. *
|
||||
****
|
||||
2. *
|
||||
****
|
||||
@@ -1,10 +1,9 @@
|
||||
# examples/web-site-zh
|
||||
|
||||
中文作者面示例:只导入 `ext/web/网页.mq.md`(不用英文 `web.mq.md`)。
|
||||
与 [`examples/web-site`](../web-site/) 对等(`ext/web/网页.mq.md`)。
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_web
|
||||
cargo run -- examples/web-site-zh/index.mq.md
|
||||
marqdo run examples/web-site-zh/index.mq.md
|
||||
```
|
||||
|
||||
打开 http://127.0.0.1:18082/ — `/about`、`/new`、`/admin`、`/static/site.css`。
|
||||
http://127.0.0.1:18082/ — 演示脚本见英文样站 [DEMO.md](../web-site/DEMO.md)。
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: components/desk
|
||||
description: 管理台壳 — 顶栏品牌为「后台」,无前台侧栏。
|
||||
---
|
||||
|
||||
## nav
|
||||
|
||||
`nav` =
|
||||
|
||||
| 属性 | 值 | 样式 | 媒体 | 当 |
|
||||
|------|-----|------|------|-----|
|
||||
| 后台 | /admin | | | |
|
||||
| 站点 | / | | | |
|
||||
| 写文章 | /new | | | |
|
||||
| 退出 | /admin/logout | | | auth |
|
||||
|
||||
*`nav`*
|
||||
|
||||
## foot
|
||||
|
||||
`foot` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| 站点 | / | |
|
||||
| 后台 | /admin | |
|
||||
| 退出 | /admin/logout | |
|
||||
|
||||
*`foot`*
|
||||
@@ -4,6 +4,8 @@
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| Marqdo | https://github.com | |
|
||||
| Marqdo | https://www.marqdo.com/ | |
|
||||
| Source | https://github.com/cflmy/marqdo | |
|
||||
|
||||
*`foot`*
|
||||
|
||||
@@ -1,12 +1,16 @@
|
||||
## nav
|
||||
|
||||
顶栏:**登录**(访客)/ **后台** + **退出**(已登录)。
|
||||
|
||||
`nav` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| 首页 | / | |
|
||||
| 关于 | /about | |
|
||||
| 写文章 | /new | |
|
||||
| 后台 | /admin | |
|
||||
| 属性 | 值 | 样式 | 媒体 | 当 |
|
||||
|------|-----|------|------|-----|
|
||||
| Marqdo | / | | | |
|
||||
| 关于 | /about | | | |
|
||||
| 写文章 | /new | | | |
|
||||
| 登录 | /login | | | guest |
|
||||
| 后台 | /admin | | | auth |
|
||||
| 退出 | /admin/logout | | | auth |
|
||||
|
||||
*`nav`*
|
||||
@@ -2,9 +2,12 @@
|
||||
|
||||
`side` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| 笔记 | / | |
|
||||
| 文档 | https://github.com | |
|
||||
| 属性 | 值 | 样式 | 媒体 | 当 |
|
||||
|------|-----|------|------|-----|
|
||||
| 1. 首页 | / | | | |
|
||||
| 2. 写文章 | /new | | | |
|
||||
| 3. 登录 | /login | | | guest |
|
||||
| 3. 后台 | /admin | | | auth |
|
||||
| 关于 | /about | | | |
|
||||
|
||||
*`side`*
|
||||
@@ -6,17 +6,27 @@
|
||||
|------|------|------|
|
||||
| id | integer | false |
|
||||
| title | text | false |
|
||||
| slug | text | false |
|
||||
| summary | text | true |
|
||||
| body | text | true |
|
||||
|
||||
*`fields`*
|
||||
|
||||
## seed
|
||||
|
||||
卡片显示 summary;/post/{slug} 显示完整 body(Markdown)。
|
||||
|
||||
`rows` =
|
||||
|
||||
| id | title | body |
|
||||
|----|-------|------|
|
||||
| 1 | 你好 Marqdo | 第一篇来自 GFM 表格。 |
|
||||
| 2 | 代码即文档 | 页面表就是程序。 |
|
||||
| id | title | slug | summary | body |
|
||||
|----|-------|------|---------|------|
|
||||
| 1 | 你好 Marqdo | hello-marqdo | 一份可执行 Markdown 既是站点说明,也是上线制品——路由、表单与样式都用表声明。 | "Marqdo 把 .mq.md 当作可执行文档。编辑器里读到的叙述,就是服务器跑起来的同一份制品:GFM 表变成 schema、表单、导航与 CSS。本 Demo 走完这条契约——打开「写文章」、触发规则表校验,再发布一行,首页与后台同时出现,全程无需作者业务 JavaScript。" |
|
||||
| 2 | 表即全栈 | tables-full-stack | Schema、表单、路由、后台与主题令牌共用一套表方言,而不是 JS/CSS 分家。 | "常见技术栈把关切拆进多种语言:数据用 SQL/ORM,输入用表单库,URL 用路由,外观用手写样式。Marqdo 把这些表面收成作者本来就会写的 GFM 表。字段表、规则表、绑定表、样式表不是比喻,而是运行时。结果是一份既能当散文扫读、又能当程序执行的站点。" |
|
||||
| 3 | 零作者 JS 与 CSS | zero-author-js-css | 业务留在 Markdown;外观是样式表加宿主壳——无作者业务 JS、无作者 .css。 | "作者业务 JavaScript 从构造上为零:校验来自服务端规则表,列表/详情由绑定表交给宿主渲染。主题令牌写在属性/值表里,经样式装配变成 CSS,作者也不必维护 .css 文件。本 Demo 关闭壳样式,只让声明过的样式上色——方便会议观众当场核对主张。" |
|
||||
| 4 | 一表打通卡片与详情 | card-to-detail | 列表把 href 绑到 slug;/post/{slug} 加详情=真即可打开全文。 | "点击首页任意卡片。列表绑定用 articles.slug 作为 href,链接前缀补上 /post/。详情页复用同一张表,查询条件 slug = {slug},再页面.详情,首行就渲染成完整文章(标题 + Markdown 正文),而不是卡片网格。这与求道量子等更大的 Marqdo 站同一套路。" |
|
||||
| 5 | 样式表不是样式文件 | style-tables | 具名样式表(kicker、intro_title、card_title)通过绑定表第三列挂上。 | "引言、卡片与壳层都用属性/值/样式绑定。样式列指向 styles/shell.mq.md 里的具名属性表。引言装配或主体装配时,这些表变成页面上的 CSS 类。改 Demo 外观不必打开 .css——改可读的 Markdown 表,文案与样式仍挨在一起。" |
|
||||
| 6 | 表单来自字段表与规则表 | forms-from-tables | 「写文章」空标题会因规则表失败;合法提交写入与后台共享的一行。 | "写文章与后台挂载同一表单对象:字段表声明标签与类型,规则表声明 required、max 与提示文案。空标题提交时错误来自服务端,不是客户端脚本。填好标题与 slug 再提交,卡片网格与后台列表都会出现——一张 schema、两个表面、零作者 JS。" |
|
||||
| 7 | 种子数据就是文档 | seed-is-docs | 这些段落写在 GFM 种子表里——Demo 正文也是程序的一部分。 | "种子行与 schema 同在 db/articles.mq.md。首次启动若表为空,宿主会插入它们。于是 Demo 叙述与代码同版本:卡片用稍长摘要,详情用更长正文,slug 保证深链稳定。审稿人打开种子表,就能看到会场站点将展示的内容。" |
|
||||
| 8 | 为什么要做这个 Demo | why-demo-matters | WWW Demo 需要审稿人几分钟内能跑、能点、能对照源码的制品。 | "Demo 轨道要的是可运行系统,不是只靠幻灯片。本样站刻意很小:一张 SQLite 表、几条路由、一套文学风壳层——却覆盖论文主张(表即全栈),并配三步操作脚本。克隆仓库,运行样站,点开卡片,弄坏一次表单,再把 index.mq.md 与浏览器对照。这个闭环就是投稿本身。" |
|
||||
|
||||
*`rows`*
|
||||
@@ -1,37 +1,113 @@
|
||||
---
|
||||
title: 中文站点示例
|
||||
description: Home + /about + /new(表单嵌入)+ 后台;只用 ext/web/网页.mq.md。
|
||||
description: >-
|
||||
与 examples/web-site 对等的 WWW Demo 样站:表驱动全站;作者业务 JS=0;作者 .css=0。
|
||||
导入 网页:ext/web/网页.mq.md
|
||||
import shell:styles/shell.mq.md
|
||||
import nav:components/nav.mq.md
|
||||
import side:components/side.mq.md
|
||||
import foot:components/foot.mq.md
|
||||
import desk:components/desk.mq.md
|
||||
import articles:db/articles.mq.md
|
||||
import db:db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
本文件既是站点说明,也是可运行应用。
|
||||
|
||||
`home` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav.`nav` | shell.`topnav` |
|
||||
| side.`side` | shell.`side_panel` |
|
||||
| foot.`foot` | |
|
||||
| foot.`foot` | shell.`footer` |
|
||||
|
||||
后台壳:去掉前台侧栏,顶栏品牌改为「后台」。
|
||||
|
||||
`desk_shell` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| desk.`nav` | shell.`topnav` |
|
||||
| desk.`foot` | shell.`footer` |
|
||||
|
||||
`index` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| title | articles.`articles`.title | shell.`card_title` |
|
||||
| body | articles.`articles`.body | shell.`card_body` |
|
||||
| body | articles.`articles`.summary | shell.`card_body` |
|
||||
| href | articles.`articles`.slug | |
|
||||
|
||||
`detail` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| title | articles.`articles`.title | shell.`card_title` |
|
||||
| body | articles.`articles`.body | |
|
||||
|
||||
`by_slug` =
|
||||
|
||||
| 字段 | 操作 | 值 |
|
||||
|------|------|-----|
|
||||
| slug | = | {slug} |
|
||||
|
||||
`首页引言` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| 眉题 | WWW Demo · 表即全栈 | shell.`kicker` |
|
||||
| 标题 | Marqdo | shell.`intro_title` |
|
||||
| 导语 | "一份可执行 Markdown 声明路由、表单、后台与样式——作者零业务 JavaScript、零手写 .css。点击卡片打开全文,再按下列三步动手试。" | shell.`lede` |
|
||||
| 标签 | 0 作者 JS | shell.`claim` |
|
||||
| 标签 | 0 作者 .css | shell.`claim` |
|
||||
| 标签 | GFM 表 | shell.`claim` |
|
||||
| 步骤 | "点击任意卡片 — /post/{slug} 用同一张 articles 表打开详情。" | shell.`step` |
|
||||
| 步骤 | "打开 [写文章](/new),空标题提交(规则表校验)。" | shell.`step` |
|
||||
| 步骤 | "点顶栏 **登录**(admin / demo),再进 **后台** — 门禁管理台:创建表单 + 列表。" | shell.`step` |
|
||||
|
||||
`关于引言` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| 眉题 | 关于 | shell.`kicker` |
|
||||
| 标题 | 关于 | shell.`intro_title` |
|
||||
| 导语 | "文档与站点同一 .mq.md 制品。版式与主题是 styles/shell.mq.md 里的 GFM 样式表——无需手写 CSS 或业务 JavaScript。" | shell.`lede` |
|
||||
|
||||
`写文章引言` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| 眉题 | 表单 · 试校验 | shell.`kicker` |
|
||||
| 标题 | 写文章 | shell.`intro_title` |
|
||||
| 导语 | 空标题提交应失败(规则表,非客户端 JS);填写标题、slug 与摘要后与后台、卡片网格共享一行。 | shell.`lede` |
|
||||
|
||||
`后台引言` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| 眉题 | 管理台 · 已进入后台 | shell.`kicker` |
|
||||
| 标题 | 后台 | shell.`intro_title` |
|
||||
| 导语 | "这就是管理台(需登录):与前台共用 articles schema,装配成列表 + 创建表单——不是另写一套 SPA。顶栏「站点」回前台,「退出」结束会话。" | shell.`lede` |
|
||||
| 标签 | 登录门禁 | shell.`claim` |
|
||||
| 标签 | 表声明 | shell.`claim` |
|
||||
| 标签 | "创建 + 列表" | shell.`claim` |
|
||||
|
||||
`文章引言` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| 眉题 | 文章 · 表绑定详情 | shell.`kicker` |
|
||||
|
||||
`article_fields` =
|
||||
|
||||
| 字段 | 标签 | 类型 | 必填 | 默认 |
|
||||
|------|------|------|------|------|
|
||||
| title | 标题 | text | true | |
|
||||
| slug | slug | text | true | |
|
||||
| summary | 摘要 | textarea | false | |
|
||||
| body | 正文 | textarea | false | |
|
||||
|
||||
`article_rules` =
|
||||
@@ -40,26 +116,88 @@ import db:db/index.mq.md
|
||||
|------|------|------|
|
||||
| title | required | 标题不能为空 |
|
||||
| title | max:120 | 标题太长 |
|
||||
| slug | required | slug 不能为空 |
|
||||
| slug | max:80 | slug 太长 |
|
||||
| summary | max:500 | 摘要太长 |
|
||||
| body | max:8000 | 正文太长 |
|
||||
|
||||
`home_meta` =
|
||||
|
||||
| key | value |
|
||||
|-----|-------|
|
||||
| description | 表即全栈 — Marqdo 网页示例;作者零业务 JavaScript。 |
|
||||
| og:type | website |
|
||||
| og:title | Marqdo 中文站 |
|
||||
|
||||
`fonts` =
|
||||
|
||||
| 关系 | 地址 | 跨域 |
|
||||
|------|------|------|
|
||||
| preconnect | https://fonts.googleapis.com | |
|
||||
| preconnect | https://fonts.gstatic.com | anonymous |
|
||||
| stylesheet | https://fonts.googleapis.com/css2?family=Great+Vibes&family=Noto+Sans+SC:wght@300;400;500;700&family=Noto+Serif+SC:wght@400;600&display=swap | |
|
||||
|
||||
**store = > db.open**
|
||||
**page = > 网页.页面 标题="Marqdo 中文站" 引言="<h1>中文站</h1><p>表格 + 类方法。</p>"**
|
||||
**site_css = > shell.css**
|
||||
|
||||
**page = > 网页.页面 标题="Marqdo 中文站" 壳样式="off"**
|
||||
**page = > page.引言装配 引言=`首页引言`**
|
||||
**page = > page.元数据 元数据=home_meta**
|
||||
**page = > page.头装配 表=fonts**
|
||||
**page = > page.样式 样式=site_css**
|
||||
**page = > page.组件装配 组件=home**
|
||||
**page = > page.主体装配 主体=index**
|
||||
**page = > page.链接前缀 前缀="/post/"**
|
||||
|
||||
**about = > 网页.页面 标题="关于" 引言="<h1>关于</h1><p>导入网页.mq.md 即用中文 API。</p>"**
|
||||
**about = > 网页.页面 标题="关于 · Marqdo 中文站" 壳样式="off"**
|
||||
**about = > about.引言装配 引言=`关于引言`**
|
||||
**about = > about.头装配 表=fonts**
|
||||
**about = > about.样式 样式=site_css**
|
||||
**about = > about.组件装配 组件=home**
|
||||
|
||||
**article_form = > 网页.表单 表="articles" 动作="插入"**
|
||||
**article_form = > article_form.字段 字段=article_fields**
|
||||
**article_form = > article_form.规则 规则=article_rules**
|
||||
|
||||
**new = > 网页.页面 标题="写文章" 引言="<h1>写文章</h1><p>表单嵌在主区。</p>"**
|
||||
**new = > 网页.页面 标题="写文章 · Marqdo 中文站" 壳样式="off"**
|
||||
**new = > new.引言装配 引言=`写文章引言`**
|
||||
**new = > new.头装配 表=fonts**
|
||||
**new = > new.样式 样式=site_css**
|
||||
**new = > new.组件装配 组件=home**
|
||||
**new = > new.表单装配 id="article" 表单=article_form**
|
||||
|
||||
**app = > 网页.应用 页面=page 数据库=store 后台=True 主机="127.0.0.1" 端口=18082**
|
||||
**desk = > 网页.页面 标题="后台 · Marqdo 中文站" 壳样式="off"**
|
||||
**desk = > desk.壳HTML 体类="is-desk"**
|
||||
**desk = > desk.引言装配 引言=`后台引言`**
|
||||
**desk = > desk.头装配 表=fonts**
|
||||
**desk = > desk.样式 样式=site_css**
|
||||
**desk = > desk.组件装配 组件=desk_shell**
|
||||
**desk = > desk.表单装配 id="article" 表单=article_form**
|
||||
**desk = > desk.主体装配 主体=index**
|
||||
**desk = > desk.链接前缀 前缀="/post/"**
|
||||
|
||||
**post = > 网页.页面 标题="文章 · Marqdo 中文站" 壳样式="off"**
|
||||
**post = > post.引言装配 引言=`文章引言`**
|
||||
**post = > post.头装配 表=fonts**
|
||||
**post = > post.样式 样式=site_css**
|
||||
**post = > post.组件装配 组件=home**
|
||||
**post = > post.主体装配 主体=detail**
|
||||
**post = > post.查询条件 条件=by_slug**
|
||||
**post = > post.详情 详情=True**
|
||||
|
||||
演示账号(用户表声明;宿主会话鉴权,无作者 JS)。
|
||||
|
||||
`管理员` =
|
||||
|
||||
| 用户名 | 密码 | 角色 |
|
||||
|--------|------|------|
|
||||
| admin | demo | admin |
|
||||
|
||||
**app = > 网页.应用 页面=page 数据库=store 后台=False 主机="127.0.0.1" 端口=18082 壳样式="off" 登录回跳="/admin" 登出回跳="/"**
|
||||
**app = > app.路由 路径="/about" 页面=about**
|
||||
**app = > app.路由 路径="/new" 页面=new**
|
||||
**app = > app.静态 目录="public" 挂载="/static"**
|
||||
**app = > app.路由 路径="/admin" 页面=desk**
|
||||
**app = > app.路由 路径="/post/{slug}" 页面=post**
|
||||
**app = > app.鉴权 用户表=`管理员` 会话时长=3600 登录路径="/login" 登录回跳="/admin" 登出回跳="/"**
|
||||
**app = > app.门禁 路径="/admin" 角色="admin" 匹配="prefix" 拒绝="redirect" 排除="/login"**
|
||||
> `app`.监听
|
||||
@@ -1,5 +0,0 @@
|
||||
/* 可选站点样式 — /static/site.css */
|
||||
body.site-hint::before {
|
||||
content: "static ok";
|
||||
display: none;
|
||||
}
|
||||
@@ -1,11 +1,233 @@
|
||||
---
|
||||
title: styles/shell
|
||||
description: >-
|
||||
Literary dark theme for examples/web-site — ink / wine / gold after the
|
||||
anlian.cyou Zhang Ailing topic. GFM tables only; no author .css.
|
||||
import web:ext/web/web.mq.md
|
||||
import text:lib/text.mq.md
|
||||
---
|
||||
|
||||
Authors style the site with **GFM tables** only. App pages use `shell_css=off`
|
||||
so host defaults do not fight this theme. Palette mirrors
|
||||
[海上花开](https://www.anlian.cyou/topics/author-zhangailing/): night ink,
|
||||
wine, cold gold, serif display.
|
||||
|
||||
## vars
|
||||
|
||||
`vars` =
|
||||
|
||||
| 选择器 | 属性 | 值 |
|
||||
|--------|------|-----|
|
||||
| :root | --ink | #0a0809 |
|
||||
| :root | --ink-lift | #141012 |
|
||||
| :root | --wine | #6b1e3a |
|
||||
| :root | --wine-soft | rgba(107,30,58,0.35) |
|
||||
| :root | --gold | #d4af37 |
|
||||
| :root | --gold-dim | rgba(212,175,55,0.45) |
|
||||
| :root | --gold-soft | rgba(212,175,55,0.12) |
|
||||
| :root | --paper | rgba(255,248,240,0.92) |
|
||||
| :root | --paper-dim | rgba(255,248,240,0.72) |
|
||||
| :root | --paper-faint | rgba(255,248,240,0.48) |
|
||||
| :root | --glass | rgba(20,12,18,0.72) |
|
||||
| :root | --glass-strong | rgba(20,12,18,0.88) |
|
||||
| :root | --border | rgba(212,175,55,0.22) |
|
||||
| :root | --border-soft | rgba(212,175,55,0.12) |
|
||||
| :root | --danger | #e8a0a8 |
|
||||
| :root | --radius | 4px |
|
||||
| :root | --radius-sm | 2px |
|
||||
| :root | --space-2 | 8px |
|
||||
| :root | --space-3 | 12px |
|
||||
| :root | --space-4 | 16px |
|
||||
| :root | --space-5 | 20px |
|
||||
| :root | --space-6 | 24px |
|
||||
| :root | --space-8 | 32px |
|
||||
| :root | --text | 16px |
|
||||
| :root | --leading | "1.75" |
|
||||
| :root | --shadow | "0 24px 80px rgba(0,0,0,.55), inset 0 1px 0 rgba(255,255,255,.06)" |
|
||||
| :root | --shadow-card | "0 12px 40px rgba(107,30,58,.35)" |
|
||||
| :root | --ring | "0 0 0 2px rgba(212,175,55,.35)" |
|
||||
| :root | --serif | "'Noto Serif SC', 'Source Serif 4', Georgia, serif" |
|
||||
| :root | --sans | "'Noto Sans SC', 'IBM Plex Sans', system-ui, sans-serif" |
|
||||
| :root | --display | "'Great Vibes', 'Allura', cursive" |
|
||||
| :root | --mono | "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" |
|
||||
| ::selection | background | rgba(212,175,55,0.35) |
|
||||
| ::selection | color | var(--paper) |
|
||||
|
||||
*`vars`*
|
||||
|
||||
## motion
|
||||
|
||||
`motion` =
|
||||
|
||||
| 选择器 | 属性 | 值 |
|
||||
|--------|------|-----|
|
||||
| @keyframes rise 0% | opacity | "0" |
|
||||
| @keyframes rise 0% | transform | translateY(14px) |
|
||||
| @keyframes rise 100% | opacity | "1" |
|
||||
| @keyframes rise 100% | transform | translateY(0) |
|
||||
| @keyframes float 0% | transform | translateY(0) |
|
||||
| @keyframes float 0% | opacity | "0.7" |
|
||||
| @keyframes float 50% | transform | translateY(6px) |
|
||||
| @keyframes float 50% | opacity | "1" |
|
||||
| @keyframes float 100% | transform | translateY(0) |
|
||||
| @keyframes float 100% | opacity | "0.7" |
|
||||
| @keyframes goldPulse 0% | text-shadow | "0 0 24px rgba(212,175,55,.2)" |
|
||||
| @keyframes goldPulse 50% | text-shadow | "0 0 48px rgba(212,175,55,.45)" |
|
||||
| @keyframes goldPulse 100% | text-shadow | "0 0 24px rgba(212,175,55,.2)" |
|
||||
| @keyframes particleDrift 0% | transform | translate3d(0,0,0) |
|
||||
| @keyframes particleDrift 50% | transform | translate3d(-2.5vw, 1.5vh, 0) |
|
||||
| @keyframes particleDrift 100% | transform | translate3d(0,0,0) |
|
||||
| @keyframes particleDrift2 0% | transform | translate3d(0,0,0) |
|
||||
| @keyframes particleDrift2 50% | transform | translate3d(2vw, -2vh, 0) |
|
||||
| @keyframes particleDrift2 100% | transform | translate3d(0,0,0) |
|
||||
| @keyframes nebulaPulse 0% | opacity | "0.55" |
|
||||
| @keyframes nebulaPulse 50% | opacity | "0.9" |
|
||||
| @keyframes nebulaPulse 100% | opacity | "0.55" |
|
||||
|
||||
*`motion`*
|
||||
|
||||
## layout
|
||||
|
||||
`layout` =
|
||||
|
||||
| 选择器 | 属性 | 值 |
|
||||
|--------|------|-----|
|
||||
| * | box-sizing | border-box |
|
||||
| html | scroll-behavior | smooth |
|
||||
| html | -webkit-text-size-adjust | 100% |
|
||||
| body | margin | "0" |
|
||||
| body | min-height | 100vh |
|
||||
| body | font-family | var(--sans) |
|
||||
| body | font-weight | "400" |
|
||||
| body | font-size | var(--text) |
|
||||
| body | line-height | var(--leading) |
|
||||
| body | color | var(--paper) |
|
||||
| body | background | var(--ink) |
|
||||
| body | background-image | "radial-gradient(ellipse 90% 55% at 50% -15%, rgba(107,30,58,.5), transparent 58%), radial-gradient(ellipse 55% 45% at 92% 75%, rgba(212,175,55,.14), transparent 55%), radial-gradient(ellipse 40% 35% at 8% 70%, rgba(107,30,58,.22), transparent 60%), linear-gradient(180deg, #0a0809 0%, #120c10 45%, #0a0809 100%)" |
|
||||
| body | background-attachment | fixed |
|
||||
| body | display | grid |
|
||||
| body | grid-template-rows | "auto 1fr auto" |
|
||||
| body | -webkit-font-smoothing | antialiased |
|
||||
| body | position | relative |
|
||||
| body | overflow-x | hidden |
|
||||
| body::before | content | '""' |
|
||||
| body::before | position | fixed |
|
||||
| body::before | inset | "0" |
|
||||
| body::before | z-index | "1" |
|
||||
| body::before | pointer-events | none |
|
||||
| body::before | opacity | "0.1" |
|
||||
| body::before | background-image | "url(\"data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E\")" |
|
||||
| html::before | content | '""' |
|
||||
| html::before | position | fixed |
|
||||
| html::before | inset | "0" |
|
||||
| html::before | z-index | "0" |
|
||||
| html::before | pointer-events | none |
|
||||
| html::before | background-image | "radial-gradient(ellipse 50% 40% at 15% 30%, rgba(107,30,58,.35), transparent 70%), radial-gradient(ellipse 45% 35% at 85% 60%, rgba(212,175,55,.12), transparent 65%), radial-gradient(ellipse 40% 30% at 50% 90%, rgba(107,30,58,.25), transparent 70%)" |
|
||||
| html::before | animation | "nebulaPulse 12s ease-in-out infinite" |
|
||||
| body::after | content | '""' |
|
||||
| body::after | position | fixed |
|
||||
| body::after | top | "0" |
|
||||
| body::after | left | "0" |
|
||||
| body::after | width | "2px" |
|
||||
| body::after | height | "2px" |
|
||||
| body::after | z-index | "2" |
|
||||
| body::after | pointer-events | none |
|
||||
| body::after | border-radius | 50% |
|
||||
| body::after | background | transparent |
|
||||
| body::after | box-shadow | "82vw 15vh 0px 0px rgba(212,175,55,0.55),29vw 18vh 0px 1px rgba(212,175,55,0.25),95vw 70vh 1px 0px rgba(212,175,55,0.55),4vw 12vh 0px 1px rgba(212,175,55,0.35),78vw 4vh 0px 1px rgba(245,230,200,0.5),84vw 90vh 1px 0px rgba(245,230,200,0.5),58vw 76vh 0px 0px rgba(255,248,240,0.4),90vw 55vh 0px 0px rgba(255,248,240,0.4),28vw 98vh 0px 0px rgba(255,248,240,0.4),49vw 13vh 0px 1px rgba(255,248,240,0.4),34vw 6vh 1px 1px rgba(212,175,55,0.25),16vw 49vh 0px 1px rgba(212,175,55,0.55),80vw 47vh 0px 1px rgba(245,230,200,0.5),9vw 6vh 0px 0px rgba(212,175,55,0.25),11vw 30vh 1px 0px rgba(212,175,55,0.55),59vw 82vh 0px 0px rgba(255,248,240,0.4),46vw 27vh 0px 1px rgba(212,175,55,0.25),88vw 83vh 0px 1px rgba(212,175,55,0.55),94vw 32vh 1px 0px rgba(212,175,55,0.35),35vw 82vh 0px 1px rgba(212,175,55,0.25),42vw 99vh 0px 0px rgba(212,175,55,0.55),41vw 52vh 0px 0px rgba(255,248,240,0.4),73vw 92vh 0px 1px rgba(255,248,240,0.4),64vw 51vh 1px 0px rgba(212,175,55,0.25),34vw 18vh 0px 1px rgba(212,175,55,0.35),75vw 55vh 1px 0px rgba(245,230,200,0.5),29vw 18vh 1px 0px rgba(245,230,200,0.5),97vw 7vh 0px 1px rgba(212,175,55,0.55),21vw 88vh 0px 0px rgba(107,30,58,0.45),49vw 77vh 0px 1px rgba(107,30,58,0.45),2vw 88vh 0px 1px rgba(212,175,55,0.25),69vw 97vh 0px 0px rgba(255,248,240,0.4),38vw 56vh 1px 0px rgba(212,175,55,0.35),93vw 93vh 0px 1px rgba(255,248,240,0.4),14vw 81vh 0px 0px rgba(255,248,240,0.4),48vw 98vh 0px 1px rgba(212,175,55,0.35),42vw 63vh 0px 0px rgba(212,175,55,0.55),40vw 31vh 0px 1px rgba(212,175,55,0.55),11vw 11vh 1px 0px rgba(212,175,55,0.25),98vw 69vh 0px 1px rgba(212,175,55,0.35),61vw 71vh 0px 1px rgba(212,175,55,0.35),78vw 55vh 0px 1px rgba(212,175,55,0.35),40vw 52vh 0px 0px rgba(212,175,55,0.25),67vw 58vh 0px 0px rgba(212,175,55,0.55),9vw 44vh 0px 1px rgba(212,175,55,0.55),29vw 1vh 0px 0px rgba(212,175,55,0.55),9vw 5vh 0px 1px rgba(255,248,240,0.4),31vw 36vh 1px 0px rgba(212,175,55,0.25),70vw 17vh 1px 0px rgba(212,175,55,0.25),61vw 53vh 0px 0px rgba(212,175,55,0.35),85vw 56vh 1px 0px rgba(255,248,240,0.4),60vw 94vh 0px 0px rgba(212,175,55,0.55),52vw 94vh 0px 0px rgba(255,248,240,0.4),25vw 25vh 1px 0px rgba(245,230,200,0.5),55vw 24vh 1px 0px rgba(255,248,240,0.4),10vw 57vh 0px 0px rgba(245,230,200,0.5),84vw 70vh 0px 0px rgba(212,175,55,0.55),22vw 53vh 1px 0px rgba(107,30,58,0.45),52vw 8vh 1px 0px rgba(212,175,55,0.35),50vw 34vh 0px 0px rgba(107,30,58,0.45),90vw 94vh 1px 0px rgba(245,230,200,0.5),25vw 38vh 0px 1px rgba(212,175,55,0.35),95vw 70vh 0px 0px rgba(212,175,55,0.55),7vw 75vh 0px 0px rgba(107,30,58,0.45),66vw 11vh 0px 1px rgba(212,175,55,0.35),9vw 87vh 1px 0px rgba(212,175,55,0.35),73vw 32vh 0px 1px rgba(245,230,200,0.5),11vw 54vh 0px 0px rgba(212,175,55,0.25),27vw 86vh 0px 0px rgba(212,175,55,0.25),34vw 51vh 0px 0px rgba(212,175,55,0.35),41vw 97vh 0px 0px rgba(212,175,55,0.55),80vw 73vh 0px 1px rgba(212,175,55,0.55)" |
|
||||
| body::after | animation | "particleDrift 48s ease-in-out infinite" |
|
||||
| html::after | content | '""' |
|
||||
| html::after | position | fixed |
|
||||
| html::after | top | "0" |
|
||||
| html::after | left | "0" |
|
||||
| html::after | width | "1px" |
|
||||
| html::after | height | "1px" |
|
||||
| html::after | z-index | "2" |
|
||||
| html::after | pointer-events | none |
|
||||
| html::after | border-radius | 50% |
|
||||
| html::after | background | transparent |
|
||||
| html::after | box-shadow | "28vw 65vh 0 0 rgba(255,248,240,0.25),17vw 45vh 0 0 rgba(212,175,55,0.3),32vw 48vh 0 0 rgba(255,248,240,0.25),21vw 57vh 0 0 rgba(107,30,58,0.3),91vw 39vh 0 0 rgba(107,30,58,0.3),84vw 68vh 0 0 rgba(212,175,55,0.3),86vw 71vh 0 0 rgba(255,248,240,0.25),85vw 14vh 0 0 rgba(212,175,55,0.3),34vw 15vh 0 0 rgba(212,175,55,0.3),96vw 71vh 0 0 rgba(212,175,55,0.3),35vw 37vh 0 0 rgba(107,30,58,0.3),27vw 92vh 0 0 rgba(255,248,240,0.25),27vw 88vh 0 0 rgba(107,30,58,0.3),34vw 65vh 0 0 rgba(255,248,240,0.25),33vw 7vh 0 0 rgba(212,175,55,0.3),82vw 55vh 0 0 rgba(255,248,240,0.25),6vw 1vh 0 0 rgba(255,248,240,0.25),99vw 17vh 0 0 rgba(107,30,58,0.3),34vw 21vh 0 0 rgba(107,30,58,0.3),57vw 71vh 0 0 rgba(107,30,58,0.3),55vw 72vh 0 0 rgba(212,175,55,0.3),15vw 10vh 0 0 rgba(107,30,58,0.3),20vw 70vh 0 0 rgba(212,175,55,0.3),48vw 75vh 0 0 rgba(107,30,58,0.3),19vw 56vh 0 0 rgba(212,175,55,0.3),6vw 40vh 0 0 rgba(255,248,240,0.25),6vw 46vh 0 0 rgba(212,175,55,0.3),88vw 32vh 0 0 rgba(107,30,58,0.3),14vw 46vh 0 0 rgba(107,30,58,0.3),53vw 80vh 0 0 rgba(107,30,58,0.3),20vw 31vh 0 0 rgba(212,175,55,0.3),23vw 53vh 0 0 rgba(212,175,55,0.3),23vw 95vh 0 0 rgba(255,248,240,0.25),53vw 86vh 0 0 rgba(107,30,58,0.3),32vw 35vh 0 0 rgba(212,175,55,0.3),90vw 14vh 0 0 rgba(255,248,240,0.25),5vw 61vh 0 0 rgba(212,175,55,0.3),26vw 59vh 0 0 rgba(255,248,240,0.25),40vw 30vh 0 0 rgba(212,175,55,0.3),4vw 85vh 0 0 rgba(212,175,55,0.3),52vw 43vh 0 0 rgba(255,248,240,0.25),9vw 99vh 0 0 rgba(255,248,240,0.25),45vw 83vh 0 0 rgba(107,30,58,0.3),52vw 87vh 0 0 rgba(107,30,58,0.3),43vw 4vh 0 0 rgba(212,175,55,0.3),34vw 23vh 0 0 rgba(107,30,58,0.3),34vw 5vh 0 0 rgba(212,175,55,0.3),77vw 56vh 0 0 rgba(255,248,240,0.25)" |
|
||||
| html::after | animation | "particleDrift2 64s ease-in-out infinite" |
|
||||
| body.has-sidebar | grid-template-columns | "14rem minmax(0, 1fr)" |
|
||||
| body.has-sidebar | grid-template-areas | '"top top" "side main" "foot foot"' |
|
||||
| body.no-sidebar | grid-template-areas | '"top" "main" "foot"' |
|
||||
| body.layout-stacked | grid-template-areas | '"top" "main" "foot"' |
|
||||
| body.is-desk | grid-template-areas | '"top" "main" "foot"' |
|
||||
| header.topnav | grid-area | top |
|
||||
| aside.side | grid-area | side |
|
||||
| main.main | grid-area | main |
|
||||
| footer.foot | grid-area | foot |
|
||||
| header.topnav | position | relative |
|
||||
| header.topnav | z-index | "20" |
|
||||
| aside.side | position | relative |
|
||||
| aside.side | z-index | "10" |
|
||||
| main.main | position | relative |
|
||||
| main.main | z-index | "10" |
|
||||
| footer.foot | position | relative |
|
||||
| footer.foot | z-index | "10" |
|
||||
| main.main | width | "100%" |
|
||||
| main.main | max-width | "min(78rem, 100%)" |
|
||||
| main.main | padding | "var(--space-8) var(--space-6) 4rem" |
|
||||
| main.main | animation | "rise .8s cubic-bezier(.22,1,.36,1) both" |
|
||||
| a | color | var(--gold) |
|
||||
| a | text-decoration | none |
|
||||
| a | transition | color 0.25s ease |
|
||||
| a:hover | color | #f5e6c8 |
|
||||
| code | font-family | var(--mono) |
|
||||
| code | font-size | "0.82em" |
|
||||
| code | font-weight | "400" |
|
||||
| code | background | rgba(0,0,0,0.35) |
|
||||
| code | border | 1px solid var(--border-soft) |
|
||||
| code | padding | "0.12em 0.45em" |
|
||||
| code | border-radius | var(--radius-sm) |
|
||||
| code | color | var(--gold) |
|
||||
|
||||
*`layout`*
|
||||
|
||||
## responsive
|
||||
|
||||
`responsive` =
|
||||
|
||||
| 媒体 | 选择器 | 属性 | 值 |
|
||||
|------|--------|------|-----|
|
||||
| (max-width: 860px) | body.has-sidebar | grid-template-columns | 1fr |
|
||||
| (max-width: 860px) | body.has-sidebar | grid-template-areas | '"top" "main" "side" "foot"' |
|
||||
| (max-width: 860px) | aside.side | border-right | "0" |
|
||||
| (max-width: 860px) | aside.side | border-top | 1px solid var(--border-soft) |
|
||||
| (max-width: 860px) | main.main | padding | "var(--space-6) var(--space-4) var(--space-8)" |
|
||||
| (max-width: 860px) | .content.cards | grid-template-columns | 1fr |
|
||||
| (max-width: 860px) | .site-form form | grid-template-columns | 1fr |
|
||||
| (max-width: 860px) | .site-form label:nth-child(1) | grid-column | "1 / -1" |
|
||||
| (max-width: 860px) | .site-form label:nth-child(2) | grid-column | "1 / -1" |
|
||||
| (max-width: 860px) | header.topnav | padding | "0.85rem var(--space-4)" |
|
||||
| (max-width: 860px) | .intro_title | font-size | "2.4rem" |
|
||||
| (prefers-reduced-motion: reduce) | main.main | animation | none |
|
||||
| (prefers-reduced-motion: reduce) | .kicker | animation | none |
|
||||
| (prefers-reduced-motion: reduce) | article.card | transition | none |
|
||||
| (prefers-reduced-motion: reduce) | body::after | animation | none |
|
||||
| (prefers-reduced-motion: reduce) | html::after | animation | none |
|
||||
| (prefers-reduced-motion: reduce) | html::before | animation | none |
|
||||
|
||||
*`responsive`*
|
||||
|
||||
## topnav
|
||||
|
||||
`topnav` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| background | #ffffff |
|
||||
| border-bottom | 1px solid #e7e5e4 |
|
||||
| position | sticky |
|
||||
| top | "0" |
|
||||
| z-index | "40" |
|
||||
| display | flex |
|
||||
| align-items | center |
|
||||
| justify-content | flex-start |
|
||||
| gap | var(--space-4) |
|
||||
| padding | "1rem var(--space-6)" |
|
||||
| background | "linear-gradient(180deg, rgba(10,8,9,.92) 0%, rgba(10,8,9,.55) 70%, transparent 100%)" |
|
||||
| backdrop-filter | blur(10px) |
|
||||
| -webkit-backdrop-filter | blur(10px) |
|
||||
| border-bottom | 1px solid var(--border-soft) |
|
||||
|
||||
*`topnav`*
|
||||
|
||||
@@ -15,18 +237,40 @@
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| background | #f5f5f4 |
|
||||
| background | "rgba(10,8,9,.55)" |
|
||||
| padding | "var(--space-6) var(--space-4)" |
|
||||
| border-right | 1px solid var(--border-soft) |
|
||||
|
||||
*`side_panel`*
|
||||
|
||||
## footer
|
||||
|
||||
`footer` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| color | var(--paper-faint) |
|
||||
| font-size | "0.8rem" |
|
||||
| letter-spacing | "0.08em" |
|
||||
| padding | "var(--space-5) var(--space-6)" |
|
||||
| border-top | 1px solid var(--border-soft) |
|
||||
| background | "rgba(10,8,9,.75)" |
|
||||
|
||||
*`footer`*
|
||||
|
||||
## card_title
|
||||
|
||||
`card_title` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| font-size | 1.15rem |
|
||||
| margin | 0 0 0.35rem |
|
||||
| font-family | var(--serif) |
|
||||
| font-size | "1.15rem" |
|
||||
| font-weight | "600" |
|
||||
| margin | "0 0 var(--space-2)" |
|
||||
| color | var(--gold) |
|
||||
| letter-spacing | "0.02em" |
|
||||
| line-height | "1.35" |
|
||||
|
||||
*`card_title`*
|
||||
|
||||
@@ -36,7 +280,396 @@
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| color | #57534e |
|
||||
| margin | 0 |
|
||||
| color | var(--paper-dim) |
|
||||
| margin | "0" |
|
||||
| line-height | "1.65" |
|
||||
| font-size | "0.9rem" |
|
||||
| font-weight | "400" |
|
||||
| display | "-webkit-box" |
|
||||
| -webkit-box-orient | vertical |
|
||||
| -webkit-line-clamp | "3" |
|
||||
| overflow | hidden |
|
||||
|
||||
*`card_body`*
|
||||
|
||||
## chrome
|
||||
|
||||
Panel + claim/steps group layout (field look comes from named bind styles).
|
||||
|
||||
`chrome` =
|
||||
|
||||
| 选择器 | 属性 | 值 |
|
||||
|--------|------|-----|
|
||||
| .main-intro | background | var(--glass) |
|
||||
| .main-intro | border | 1px solid var(--border) |
|
||||
| .main-intro | border-radius | var(--radius) |
|
||||
| .main-intro | padding | "2.25rem 1.75rem 1.85rem" |
|
||||
| .main-intro | box-shadow | var(--shadow) |
|
||||
| .main-intro | backdrop-filter | blur(16px) |
|
||||
| .main-intro | -webkit-backdrop-filter | blur(16px) |
|
||||
| .main-intro | margin-bottom | var(--space-8) |
|
||||
| .main-intro > .claim | display | flex |
|
||||
| .main-intro > .claim | flex-wrap | wrap |
|
||||
| .main-intro > .claim | gap | var(--space-2) |
|
||||
| .main-intro > .claim | margin | "0 0 var(--space-6)" |
|
||||
| .main-intro > .steps | margin | "0" |
|
||||
| .main-intro > .steps | padding | "var(--space-5) var(--space-5) var(--space-5) 1.5rem" |
|
||||
| .main-intro > .steps | color | var(--paper-dim) |
|
||||
| .main-intro > .steps | background | "rgba(0,0,0,.35)" |
|
||||
| .main-intro > .steps | border | 1px solid var(--border-soft) |
|
||||
| .main-intro > .steps | border-left | 2px solid var(--gold-dim) |
|
||||
| .main-intro > .steps | border-radius | var(--radius) |
|
||||
| .main-intro > .steps | font-size | "0.95rem" |
|
||||
| .main-intro > .steps | letter-spacing | "0.02em" |
|
||||
| .main-intro > .steps a | color | var(--gold) |
|
||||
| .main-intro > .steps a | font-weight | "500" |
|
||||
| .main-intro > .steps a:hover | color | #f5e6c8 |
|
||||
| .article | background | var(--glass) |
|
||||
| .article | border | 1px solid var(--border) |
|
||||
| .article | border-radius | var(--radius) |
|
||||
| .article | padding | "2rem 1.75rem" |
|
||||
| .article | box-shadow | var(--shadow) |
|
||||
| .article | backdrop-filter | blur(16px) |
|
||||
| .article | -webkit-backdrop-filter | blur(16px) |
|
||||
| .article-title | font-family | var(--serif) |
|
||||
| .article-title | font-size | "clamp(1.75rem, 4vw, 2.35rem)" |
|
||||
| .article-title | font-weight | "600" |
|
||||
| .article-title | color | var(--gold) |
|
||||
| .article-title | letter-spacing | "0.04em" |
|
||||
| .article-title | margin | "0 0 var(--space-5)" |
|
||||
| .article-title | line-height | "1.25" |
|
||||
| .article-body | color | var(--paper-dim) |
|
||||
| .article-body | font-family | var(--sans) |
|
||||
| .article-body | font-size | "1.02rem" |
|
||||
| .article-body | line-height | "1.85" |
|
||||
| .article-body.md p | margin | "0 0 1.1rem" |
|
||||
| .article-body.md a | color | var(--gold) |
|
||||
| article.card | cursor | pointer |
|
||||
| a.card-link | color | inherit |
|
||||
| a.card-link | text-decoration | none |
|
||||
| a.card-link:hover | color | inherit |
|
||||
|
||||
*`chrome`*
|
||||
|
||||
## kicker
|
||||
|
||||
`kicker` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| letter-spacing | "0.32em" |
|
||||
| text-transform | uppercase |
|
||||
| font-size | "0.72rem" |
|
||||
| color | var(--gold-dim) |
|
||||
| margin | "0 0 var(--space-4)" |
|
||||
| font-weight | "400" |
|
||||
| font-family | var(--sans) |
|
||||
| animation | "float 2.8s ease-in-out infinite" |
|
||||
|
||||
*`kicker`*
|
||||
|
||||
## intro_title
|
||||
|
||||
`intro_title` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| font-family | var(--display) |
|
||||
| font-size | "clamp(3rem, 10vw, 4.8rem)" |
|
||||
| font-weight | "400" |
|
||||
| line-height | "1.15" |
|
||||
| letter-spacing | "0.04em" |
|
||||
| margin | "0 0 var(--space-4)" |
|
||||
| color | transparent |
|
||||
| background | "linear-gradient(135deg, #f5e6c8 0%, var(--gold) 42%, var(--wine) 100%)" |
|
||||
| -webkit-background-clip | text |
|
||||
| background-clip | text |
|
||||
| animation | "goldPulse 4.5s ease-in-out infinite" |
|
||||
|
||||
*`intro_title`*
|
||||
|
||||
## lede
|
||||
|
||||
`lede` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| color | var(--paper-dim) |
|
||||
| max-width | "34rem" |
|
||||
| line-height | "1.85" |
|
||||
| margin | "0 0 var(--space-5)" |
|
||||
| font-size | "1.05rem" |
|
||||
| letter-spacing | "0.02em" |
|
||||
| font-weight | "400" |
|
||||
| font-family | var(--sans) |
|
||||
|
||||
*`lede`*
|
||||
|
||||
## claim
|
||||
|
||||
`claim` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| display | inline-flex |
|
||||
| align-items | center |
|
||||
| padding | "0.2rem 0.65rem" |
|
||||
| border-radius | var(--radius-sm) |
|
||||
| background | var(--wine-soft) |
|
||||
| color | #f0c9d4 |
|
||||
| font-size | "0.68rem" |
|
||||
| font-weight | "500" |
|
||||
| letter-spacing | "0.14em" |
|
||||
| border | 1px solid rgba(107,30,58,0.5) |
|
||||
|
||||
*`claim`*
|
||||
|
||||
## step
|
||||
|
||||
`step` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| margin | "0.55rem 0" |
|
||||
|
||||
*`step`*
|
||||
|
||||
## widgets
|
||||
|
||||
`widgets` =
|
||||
|
||||
| 选择器 | 属性 | 值 |
|
||||
|--------|------|-----|
|
||||
| ul.nav | display | flex |
|
||||
| ul.nav | flex-wrap | wrap |
|
||||
| ul.nav | align-items | center |
|
||||
| ul.nav | gap | "0.35rem 1rem" |
|
||||
| ul.nav | list-style | none |
|
||||
| ul.nav | margin | "0" |
|
||||
| ul.nav | padding | "0" |
|
||||
| ul.nav a | display | inline-flex |
|
||||
| ul.nav a | align-items | center |
|
||||
| ul.nav a | text-decoration | none |
|
||||
| ul.nav a | color | var(--paper-dim) |
|
||||
| ul.nav a | padding | "0.35rem 0" |
|
||||
| ul.nav a | border-radius | "0" |
|
||||
| ul.nav a | font-weight | "400" |
|
||||
| ul.nav a | font-size | "0.8rem" |
|
||||
| ul.nav a | letter-spacing | "0.14em" |
|
||||
| ul.nav a | transition | color 0.25s ease |
|
||||
| ul.nav a:hover | background | transparent |
|
||||
| ul.nav a:hover | color | var(--gold) |
|
||||
| ul.nav a:hover | text-decoration | none |
|
||||
| ul.nav a[href="/admin"] | color | var(--gold) |
|
||||
| ul.nav a[href="/admin"] | letter-spacing | "0.18em" |
|
||||
| ul.nav a[href="/admin"] | border-bottom | 1px solid var(--gold-dim) |
|
||||
| ul.side-nav a[href="/admin"] | color | var(--gold) |
|
||||
| body.is-desk header.topnav | border-bottom | 1px solid rgba(107,30,58,0.55) |
|
||||
| body.is-desk header.topnav | box-shadow | "0 12px 40px rgba(107,30,58,.18)" |
|
||||
| body.is-desk .main-intro | border-left | 3px solid var(--wine) |
|
||||
| body.is-desk .site-form | border-color | rgba(107,30,58,0.45) |
|
||||
| body.is-desk .site-form | box-shadow | "0 0 0 1px rgba(212,175,55,.12), 0 18px 48px rgba(0,0,0,.35)" |
|
||||
| body.is-desk .content.cards | margin-top | var(--space-6) |
|
||||
| ul.nav li:first-child a | font-family | var(--display) |
|
||||
| ul.nav li:first-child a | font-weight | "400" |
|
||||
| ul.nav li:first-child a | color | var(--gold) |
|
||||
| ul.nav li:first-child a | font-size | "1.85rem" |
|
||||
| ul.nav li:first-child a | letter-spacing | "0.06em" |
|
||||
| ul.nav li:first-child a | padding | "0.1rem 0.2rem 0.1rem 0" |
|
||||
| ul.nav li:first-child a:hover | background | transparent |
|
||||
| ul.nav li:first-child a:hover | color | #f5e6c8 |
|
||||
| .side-label | display | block |
|
||||
| .side-label | font-size | "0" |
|
||||
| .side-label | margin | "0 0 var(--space-4)" |
|
||||
| .side-label::before | content | '"Path"' |
|
||||
| .side-label::before | display | block |
|
||||
| .side-label::before | font-size | "0.68rem" |
|
||||
| .side-label::before | letter-spacing | "0.28em" |
|
||||
| .side-label::before | text-transform | uppercase |
|
||||
| .side-label::before | color | var(--gold-dim) |
|
||||
| .side-label::before | font-weight | "400" |
|
||||
| ul.side-nav | list-style | none |
|
||||
| ul.side-nav | margin | "0" |
|
||||
| ul.side-nav | padding | "0" |
|
||||
| ul.side-nav | display | grid |
|
||||
| ul.side-nav | gap | "2px" |
|
||||
| ul.side-nav | border-left | 1px solid var(--border) |
|
||||
| ul.side-nav | padding-left | "0.85rem" |
|
||||
| ul.side-nav | margin-left | "0.25rem" |
|
||||
| ul.side-nav a | display | block |
|
||||
| ul.side-nav a | text-decoration | none |
|
||||
| ul.side-nav a | color | var(--paper-dim) |
|
||||
| ul.side-nav a | padding | "0.45rem 0.35rem" |
|
||||
| ul.side-nav a | border-radius | "0" |
|
||||
| ul.side-nav a | font-weight | "400" |
|
||||
| ul.side-nav a | font-size | "0.88rem" |
|
||||
| ul.side-nav a | letter-spacing | "0.06em" |
|
||||
| ul.side-nav a | border | "0" |
|
||||
| ul.side-nav a | position | relative |
|
||||
| ul.side-nav a:hover | background | transparent |
|
||||
| ul.side-nav a:hover | border-color | transparent |
|
||||
| ul.side-nav a:hover | color | var(--gold) |
|
||||
| ul.side-nav a:hover | text-decoration | none |
|
||||
| ul.side-nav a:hover | box-shadow | none |
|
||||
| ul.foot-nav | display | flex |
|
||||
| ul.foot-nav | gap | var(--space-4) |
|
||||
| ul.foot-nav | list-style | none |
|
||||
| ul.foot-nav | margin | "0" |
|
||||
| ul.foot-nav | padding | "0" |
|
||||
| ul.foot-nav a | color | var(--paper-faint) |
|
||||
| ul.foot-nav a | font-weight | "400" |
|
||||
| ul.foot-nav a | letter-spacing | "0.1em" |
|
||||
| ul.foot-nav a | font-size | "0.78rem" |
|
||||
| ul.foot-nav a:hover | color | var(--gold) |
|
||||
| .content.cards | display | grid |
|
||||
| .content.cards | gap | var(--space-4) |
|
||||
| .content.cards | margin-top | "0" |
|
||||
| .content.cards | grid-template-columns | "repeat(auto-fill, minmax(16rem, 1fr))" |
|
||||
| article.card | background | "rgba(0,0,0,.35)" |
|
||||
| article.card | border | 1px solid var(--border-soft) |
|
||||
| article.card | border-radius | var(--radius-sm) |
|
||||
| article.card | padding | "1.35rem 1.15rem" |
|
||||
| article.card | box-shadow | none |
|
||||
| article.card | transition | "border-color .35s ease, box-shadow .35s ease, transform .35s ease" |
|
||||
| article.card:hover | transform | "translateY(-3px)" |
|
||||
| article.card:hover | box-shadow | var(--shadow-card) |
|
||||
| article.card:hover | border-color | var(--gold-dim) |
|
||||
| .site-form | background | var(--glass) |
|
||||
| .site-form | border | 1px solid var(--border) |
|
||||
| .site-form | border-radius | var(--radius) |
|
||||
| .site-form | padding | "var(--space-6) var(--space-6) var(--space-7, 1.75rem)" |
|
||||
| .site-form | margin | "0 0 var(--space-6)" |
|
||||
| .site-form | max-width | "100%" |
|
||||
| .site-form | width | "100%" |
|
||||
| .site-form | box-shadow | var(--shadow) |
|
||||
| .site-form | backdrop-filter | blur(16px) |
|
||||
| .site-form | -webkit-backdrop-filter | blur(16px) |
|
||||
| .site-form .meta | display | none |
|
||||
| .site-form form | display | grid |
|
||||
| .site-form form | grid-template-columns | "minmax(0, 1fr) minmax(0, 1fr)" |
|
||||
| .site-form form | column-gap | var(--space-5) |
|
||||
| .site-form form | row-gap | var(--space-5) |
|
||||
| .site-form form | gap | var(--space-5) |
|
||||
| .site-form form | margin | "0" |
|
||||
| .site-form form | width | "100%" |
|
||||
| .site-form form | max-width | "100%" |
|
||||
| .site-form label | display | grid |
|
||||
| .site-form label | gap | var(--space-2) |
|
||||
| .site-form label | margin | "0" |
|
||||
| .site-form label | min-width | "0" |
|
||||
| .site-form label | font-weight | "400" |
|
||||
| .site-form label | color | var(--gold) |
|
||||
| .site-form label | font-size | "0.78rem" |
|
||||
| .site-form label | letter-spacing | "0.16em" |
|
||||
| .site-form label | text-transform | uppercase |
|
||||
| .site-form label:nth-child(1) | grid-column | "1" |
|
||||
| .site-form label:nth-child(2) | grid-column | "2" |
|
||||
| .site-form label:nth-child(n+3) | grid-column | "1 / -1" |
|
||||
| .site-form .actions | grid-column | "1 / -1" |
|
||||
| .site-form input | -webkit-appearance | none |
|
||||
| .site-form textarea | -webkit-appearance | none |
|
||||
| .site-form input | appearance | none |
|
||||
| .site-form textarea | appearance | none |
|
||||
| .site-form input | box-sizing | border-box |
|
||||
| .site-form textarea | box-sizing | border-box |
|
||||
| .site-form input | display | block |
|
||||
| .site-form textarea | display | block |
|
||||
| .site-form input | width | "100%" |
|
||||
| .site-form textarea | width | "100%" |
|
||||
| .site-form input | height | "2.75rem" |
|
||||
| .site-form textarea | min-height | "10rem" |
|
||||
| .site-form label:nth-child(4) textarea | min-height | "14rem" |
|
||||
| .site-form textarea | resize | vertical |
|
||||
| .site-form input | padding | "0 0.9rem" |
|
||||
| .site-form textarea | padding | "0.75rem 0.9rem" |
|
||||
| .site-form input | border | 1px solid var(--border) |
|
||||
| .site-form textarea | border | 1px solid var(--border) |
|
||||
| .site-form input | border-radius | var(--radius-sm) |
|
||||
| .site-form textarea | border-radius | var(--radius-sm) |
|
||||
| .site-form input | background | "rgba(0,0,0,.4)" |
|
||||
| .site-form textarea | background | "rgba(0,0,0,.4)" |
|
||||
| .site-form input | color | var(--paper) |
|
||||
| .site-form textarea | color | var(--paper) |
|
||||
| .site-form input | font | inherit |
|
||||
| .site-form textarea | font | inherit |
|
||||
| .site-form input | font-size | "0.95rem" |
|
||||
| .site-form textarea | font-size | "0.95rem" |
|
||||
| .site-form input | line-height | "1.4" |
|
||||
| .site-form textarea | line-height | "1.65" |
|
||||
| .site-form input | transition | "border-color .2s ease, box-shadow .2s ease" |
|
||||
| .site-form textarea | transition | "border-color .2s ease, box-shadow .2s ease" |
|
||||
| .site-form input:hover | border-color | var(--gold-dim) |
|
||||
| .site-form textarea:hover | border-color | var(--gold-dim) |
|
||||
| .site-form input:focus | outline | none |
|
||||
| .site-form textarea:focus | outline | none |
|
||||
| .site-form input:focus | border-color | var(--gold) |
|
||||
| .site-form textarea:focus | border-color | var(--gold) |
|
||||
| .site-form input:focus | box-shadow | var(--ring) |
|
||||
| .site-form textarea:focus | box-shadow | var(--ring) |
|
||||
| .site-form input[readonly] | background | "rgba(0,0,0,.25)" |
|
||||
| .site-form input[readonly] | color | var(--paper-faint) |
|
||||
| .site-form .err | color | var(--danger) |
|
||||
| .site-form .err | font-size | "0.8rem" |
|
||||
| .site-form .err | font-weight | "500" |
|
||||
| .site-form .err | letter-spacing | "0.04em" |
|
||||
| .site-form .actions | display | flex |
|
||||
| .site-form .actions | align-items | center |
|
||||
| .site-form .actions | gap | var(--space-4) |
|
||||
| .site-form .actions | margin-top | var(--space-2) |
|
||||
| .site-form .actions | flex-wrap | wrap |
|
||||
| .site-form button | -webkit-appearance | none |
|
||||
| .site-form button | appearance | none |
|
||||
| .site-form button | height | "2.75rem" |
|
||||
| .site-form button | padding | "0 1.35rem" |
|
||||
| .site-form button | background | "linear-gradient(135deg, #f5e6c8, var(--gold))" |
|
||||
| .site-form button | color | var(--ink) |
|
||||
| .site-form button | border | "0" |
|
||||
| .site-form button | border-radius | 999px |
|
||||
| .site-form button | font-weight | "600" |
|
||||
| .site-form button | font-size | "0.85rem" |
|
||||
| .site-form button | letter-spacing | "0.12em" |
|
||||
| .site-form button | cursor | pointer |
|
||||
| .site-form button | box-shadow | "0 8px 28px rgba(212,175,55,.28)" |
|
||||
| .site-form button | transition | "transform .2s ease, box-shadow .2s ease, filter .2s ease" |
|
||||
| .site-form button:hover | filter | brightness(1.06) |
|
||||
| .site-form button:hover | transform | "translateY(-1px)" |
|
||||
| .site-form button:hover | box-shadow | "0 12px 36px rgba(212,175,55,.4)" |
|
||||
| .site-form .actions a | color | var(--paper-faint) |
|
||||
| .site-form .actions a | font-weight | "400" |
|
||||
| .site-form .actions a | text-decoration | none |
|
||||
| .site-form .actions a | font-size | "0.85rem" |
|
||||
| .site-form .actions a | letter-spacing | "0.08em" |
|
||||
| .site-form .actions a:hover | color | var(--gold) |
|
||||
| .flash.err | color | var(--danger) |
|
||||
| .flash.err | font-weight | "500" |
|
||||
|
||||
*`widgets`*
|
||||
|
||||
## css
|
||||
|
||||
**v = > vars**
|
||||
**m = > motion**
|
||||
**l = > layout**
|
||||
**r = > responsive**
|
||||
**c = > chrome**
|
||||
**w = > widgets**
|
||||
**css_v = > web.make_style name="vars" table=v**
|
||||
**css_m = > web.make_style name="motion" table=m**
|
||||
**css_l = > web.make_style name="layout" table=l**
|
||||
**css_r = > web.make_style name="responsive" table=r**
|
||||
**css_c = > web.make_style name="chrome" table=c**
|
||||
**css_w = > web.make_style name="widgets" table=w**
|
||||
|
||||
`parts` =
|
||||
|
||||
| css |
|
||||
|-----|
|
||||
| `css_v` |
|
||||
| `css_m` |
|
||||
| `css_l` |
|
||||
| `css_r` |
|
||||
| `css_c` |
|
||||
| `css_w` |
|
||||
|
||||
**out = > text.str_join xs=`parts` sep=""**
|
||||
*out*
|
||||
@@ -0,0 +1,40 @@
|
||||
# Demo walkthrough (`examples/web-site`)
|
||||
|
||||
Aligned with The Web Conference **Demo** expectations: implemented system,
|
||||
**hands-on** interaction, clear venue script, reproducible from the repo.
|
||||
|
||||
## Run
|
||||
|
||||
```bash
|
||||
./scripts/build-web-plugin.sh
|
||||
marqdo run examples/web-site/index.mq.md
|
||||
```
|
||||
|
||||
Open http://127.0.0.1:18081/
|
||||
|
||||
## Venue script (≈3 minutes)
|
||||
|
||||
| Step | Action | What reviewers should notice |
|
||||
|------|--------|------------------------------|
|
||||
| 1 | Home | Claim badges + steps; **8 seed cards** with summaries |
|
||||
| 2 | Click a card | `/post/{slug}` detail from the same table (`detail=True`) |
|
||||
| 3 | Open `index.mq.md` beside the browser | Narrative = program; field/rule/route/intro tables |
|
||||
| 4 | `/new` empty title → submit | Server validation from **rule table** (no author JS) |
|
||||
| 5 | `/new` valid title+slug → submit | Row appears on Home and Admin |
|
||||
| 6 | Top-nav **Login** (`admin` / `demo`) → **Admin** | Session gate; desk shell + create form |
|
||||
| 7 | Terminal check | `find examples/web-site \( -name '*.js' -o -name '*.css' \)` → **0** |
|
||||
|
||||
## Authoring contract
|
||||
|
||||
| Surface | Source |
|
||||
|---------|--------|
|
||||
| Routes / forms / admin | GFM tables in `index.mq.md` |
|
||||
| Styles | `styles/shell.mq.md` → `web.make_style` (ink / wine / gold; `shell_css=off`) |
|
||||
| Intro | `| front | back | style |` → `page.compose_intro` (same bind as main) |
|
||||
| Fonts | `page.head` table → Google Fonts (Noto Serif SC + Ma Shan Zheng) |
|
||||
| Author `.js` / `.css` | **None** |
|
||||
|
||||
## Video
|
||||
|
||||
Same beats as above; English captions preferred. See thesis
|
||||
`www-2027-demo/VIDEO.md` for length / upload tips.
|
||||
@@ -1,10 +1,27 @@
|
||||
# examples/web-site
|
||||
|
||||
Canonical English sample for `ext/web` (design §4).
|
||||
Canonical **English** sample for `ext/web` — WWW Demo walkthrough site.
|
||||
|
||||
**Hands-on script:** [DEMO.md](./DEMO.md)
|
||||
|
||||
## Authoring rules (checkable)
|
||||
|
||||
| Surface | How it is authored |
|
||||
|---------|-------------------|
|
||||
| Routes / forms / admin | GFM tables + class methods |
|
||||
| Look-and-feel | Host shell CSS + **style tables** |
|
||||
| Author business JavaScript | **none** |
|
||||
| Author hand-written `.css` | **none** |
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_web
|
||||
cargo run -- examples/web-site/index.mq.md
|
||||
marqdo run examples/web-site/index.mq.md
|
||||
```
|
||||
|
||||
Then open http://127.0.0.1:18081/ — `/about`, `/new` (form in page slot), `/admin`, `/static/site.css`.
|
||||
http://127.0.0.1:18081/ — `/about`, `/new` (validation), `/admin` (list + create).
|
||||
|
||||
```bash
|
||||
find examples/web-site \( -name '*.js' -o -name '*.css' \) | wc -l # 0
|
||||
```
|
||||
|
||||
Chinese twin: [`examples/web-site-zh/`](../web-site-zh/).
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: components/desk
|
||||
description: Admin desk chrome — brand reads Admin; no public side rail.
|
||||
---
|
||||
|
||||
## nav
|
||||
|
||||
`nav` =
|
||||
|
||||
| front | back | style | media | when |
|
||||
|-------|------|-------|-------|------|
|
||||
| Admin | /admin | | | |
|
||||
| Site | / | | | |
|
||||
| New | /new | | | |
|
||||
| Logout | /admin/logout | | | auth |
|
||||
|
||||
*`nav`*
|
||||
|
||||
## foot
|
||||
|
||||
`foot` =
|
||||
|
||||
| front | back | style |
|
||||
|-------|------|-------|
|
||||
| Site | / | |
|
||||
| Admin | /admin | |
|
||||
| Logout | /admin/logout | |
|
||||
|
||||
*`foot`*
|
||||
@@ -2,8 +2,10 @@
|
||||
|
||||
`foot` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| Marqdo | https://github.com | |
|
||||
| front | back | style |
|
||||
|-------|------|-------|
|
||||
| Marqdo | https://www.marqdo.com/ | |
|
||||
| Source | https://github.com/cflmy/marqdo | |
|
||||
|
||||
*`foot`*
|
||||
|
||||
@@ -1,14 +1,16 @@
|
||||
## nav
|
||||
|
||||
Static top links for the shell.
|
||||
Brand first, then demo routes. Guest sees **Login**; signed-in sees **Admin** + **Logout**.
|
||||
|
||||
`nav` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| Home | / | |
|
||||
| About | /about | |
|
||||
| New | /new | |
|
||||
| Admin | /admin | |
|
||||
| front | back | style | media | when |
|
||||
|-------|------|-------|-------|------|
|
||||
| Marqdo | / | | | |
|
||||
| About | /about | | | |
|
||||
| New | /new | | | |
|
||||
| Login | /login | | | guest |
|
||||
| Admin | /admin | | | auth |
|
||||
| Logout | /admin/logout | | | auth |
|
||||
|
||||
*`nav`*
|
||||
@@ -1,10 +1,15 @@
|
||||
## side
|
||||
|
||||
Hands-on demo checklist (links only — no JS).
|
||||
|
||||
`side` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| Notes | / | |
|
||||
| Docs | https://github.com | |
|
||||
| front | back | style | media | when |
|
||||
|-------|------|-------|-------|------|
|
||||
| 1. Home | / | | | |
|
||||
| 2. New form | /new | | | |
|
||||
| 3. Login | /login | | | guest |
|
||||
| 3. Admin | /admin | | | auth |
|
||||
| About | /about | | | |
|
||||
|
||||
*`side`*
|
||||
@@ -2,21 +2,31 @@
|
||||
|
||||
`fields` =
|
||||
|
||||
| 字段 | 类型 | 可空 |
|
||||
|------|------|------|
|
||||
| name | type | nullable |
|
||||
|------|------|----------|
|
||||
| id | integer | false |
|
||||
| title | text | false |
|
||||
| slug | text | false |
|
||||
| summary | text | true |
|
||||
| body | text | true |
|
||||
|
||||
*`fields`*
|
||||
|
||||
## seed
|
||||
|
||||
Longer demo rows — cards show summary; /post/{slug} shows full body (Markdown).
|
||||
|
||||
`rows` =
|
||||
|
||||
| id | title | body |
|
||||
|----|-------|------|
|
||||
| 1 | Hello Marqdo | First article from a GFM table. |
|
||||
| 2 | Code as docs | The page table is the program. |
|
||||
| id | title | slug | summary | body |
|
||||
|----|-------|------|---------|------|
|
||||
| 1 | Hello Marqdo | hello-marqdo | A runnable Markdown file is both the site docs and the deployed app — tables declare routes, forms, and styles. | "Marqdo treats an .mq.md file as an executable document. The narrative you read in the editor is the same artifact the server runs: GFM tables become schema, forms, navigation, and CSS. This demo shows that contract end-to-end — open New, trigger a rule-table validation error, then publish a row that appears on Home and Admin without any author JavaScript." |
|
||||
| 2 | Tables as the full stack | tables-full-stack | Schema, forms, routes, admin pages, and theme tokens share one tabular dialect instead of a JS/CSS split. | "Most stacks split concerns across languages: SQL or an ORM for data, a form library for input, a router for URLs, and a stylesheet for look. Marqdo collapses those surfaces into GFM tables with the same geometry authors already use for documentation. Field tables, rule tables, bind tables, and style tables are not metaphors — they are the runtime. The result is a site you can skim as prose and execute as a program." |
|
||||
| 3 | Zero author JS and CSS | zero-author-js-css | Business logic stays in Markdown; appearance is style tables plus the host shell — no hand-written business JS or author .css. | "Author business JavaScript is zero by construction: validation runs from rule tables on the server, and list/detail pages are bind tables rendered by the host. Author .css files are also unnecessary when theme tokens live in property/value tables assembled by make_style. The demo turns shell_css=off so only those declared styles paint the page — proving the claim for a conference audience." |
|
||||
| 4 | Card to detail in one bind | card-to-detail | List cards bind href to slug; a /post/{slug} route plus detail=True opens the full article. | "Click any card on the home page. The list bind exposes href from articles.slug, and link_prefix prefixes /post/. The detail page reuses the same table with a query slug = {slug} and page.detail so the first row renders as a full article — title and Markdown body — instead of a card grid. That is the same pattern used by larger Marqdo sites such as 求道量子." |
|
||||
| 5 | Style tables not stylesheets | style-tables | Named style tables (kicker, intro_title, card_title) bind through the third column of every layout table. | "Intro, cards, and chrome all use the bind shape front/back/style. The style column points at a named property table in styles/shell.mq.md. When compose_intro or compose_main runs, those tables become CSS classes on the page. Authors never open a .css file to tweak the demo look — they edit readable Markdown tables that stay next to the copy they style." |
|
||||
| 6 | Forms from field and rule tables | forms-from-tables | Empty title on New fails from the rule table; a valid submit inserts a row shared with Admin. | "The New and Admin pages mount the same form object: a field table declares labels and types, a rule table declares required and max constraints with messages. Submit with an empty title and the error is server-side, not a client script. Fill a title and slug, submit again, and the row shows up in the card grid and under Admin — one schema, two surfaces, zero author JS." |
|
||||
| 7 | Seed data is documentation | seed-is-docs | These paragraphs were written as a GFM seed table — the demo content is part of the program. | "Seed rows live beside the schema in db/articles.mq.md. On first boot the host inserts them when the articles table is empty. That means the demo narrative is versioned with the code: longer summaries for cards, fuller bodies for detail pages, and slugs that make deep links stable. Reviewers can open the seed table and see exactly what the venue site will show." |
|
||||
| 8 | Why this Demo matters | why-demo-matters | WWW Demo needs a hands-on artifact reviewers can run, click, and compare to source in minutes. | "A Demo track asks for an implemented system, not a slide-only pitch. This sample is intentionally small: one SQLite table, a handful of routes, and a literary shell — yet it covers the paper claim (tables as the full stack) with a three-step script. Clone the repo, run the web-site sample, click a card, break a form, then open index.mq.md beside the browser. That loop is the publication." |
|
||||
|
||||
*`rows`*
|
||||
+170
-22
@@ -1,73 +1,221 @@
|
||||
---
|
||||
title: web-site
|
||||
description: Home + /about + /new (form in page slot) + admin.
|
||||
description: >-
|
||||
WWW Demo sample — GFM tables for shell, schema, forms, styles, and admin.
|
||||
Author business JavaScript: none. Author hand-written .css: none.
|
||||
import web:ext/web/web.mq.md
|
||||
import shell:styles/shell.mq.md
|
||||
import nav:components/nav.mq.md
|
||||
import side:components/side.mq.md
|
||||
import foot:components/foot.mq.md
|
||||
import desk:components/desk.mq.md
|
||||
import articles:db/articles.mq.md
|
||||
import db:db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
This Markdown file is both the **site documentation** and the **running app**.
|
||||
Routes, forms, validation, admin pages, and look-and-feel are **GFM tables** —
|
||||
no hand-written business JavaScript and no author .css file.
|
||||
|
||||
`home` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| src | style |
|
||||
|-----|-------|
|
||||
| nav.`nav` | shell.`topnav` |
|
||||
| side.`side` | shell.`side_panel` |
|
||||
| foot.`foot` | |
|
||||
| foot.`foot` | shell.`footer` |
|
||||
|
||||
Main content is not a reusable component, so it is authored here.
|
||||
Public shell (nav + side + foot). Desk shell drops the public side rail.
|
||||
|
||||
`desk_shell` =
|
||||
|
||||
| src | style |
|
||||
|-----|-------|
|
||||
| desk.`nav` | shell.`topnav` |
|
||||
| desk.`foot` | shell.`footer` |
|
||||
|
||||
List cards: summary + slug link (click through to detail).
|
||||
|
||||
`index` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| front | back | style |
|
||||
|-------|------|-------|
|
||||
| title | articles.`articles`.title | shell.`card_title` |
|
||||
| body | articles.`articles`.body | shell.`card_body` |
|
||||
| body | articles.`articles`.summary | shell.`card_body` |
|
||||
| href | articles.`articles`.slug | |
|
||||
|
||||
Article create form (design §5.5): field table + rules table.
|
||||
Detail bind for /post/{slug} (full Markdown body).
|
||||
|
||||
`detail` =
|
||||
|
||||
| front | back | style |
|
||||
|-------|------|-------|
|
||||
| title | articles.`articles`.title | shell.`card_title` |
|
||||
| body | articles.`articles`.body | |
|
||||
|
||||
`by_slug` =
|
||||
|
||||
| field | op | value |
|
||||
|-------|-----|-------|
|
||||
| slug | = | {slug} |
|
||||
|
||||
Home intro — same bind shape as main (front / back / style).
|
||||
|
||||
`home_intro` =
|
||||
|
||||
| front | back | style |
|
||||
|-------|------|-------|
|
||||
| kicker | WWW demo · tables as the full stack | shell.`kicker` |
|
||||
| title | Marqdo | shell.`intro_title` |
|
||||
| lede | "One executable Markdown artifact declares routes, forms, admin pages, and styles — no hand-written business JavaScript, no author .css. Click a card for the full article, then try the three steps below." | shell.`lede` |
|
||||
| claim | 0 author JS | shell.`claim` |
|
||||
| claim | 0 author .css | shell.`claim` |
|
||||
| claim | GFM tables | shell.`claim` |
|
||||
| step | "Click any card — /post/{slug} opens the detail page from the same articles table." | shell.`step` |
|
||||
| step | "Open [New](/new) and submit with an empty title (validation from a rule table)." | shell.`step` |
|
||||
| step | "Open top-nav **Login** (admin / demo), then **Admin** — gated desk with create form + list." | shell.`step` |
|
||||
|
||||
`about_intro` =
|
||||
|
||||
| front | back | style |
|
||||
|-------|------|-------|
|
||||
| kicker | about | shell.`kicker` |
|
||||
| title | About | shell.`intro_title` |
|
||||
| lede | "Documentation and the deployed site stay one .mq.md artifact. Layout and theme are GFM style tables in styles/shell.mq.md — structure without hand-written CSS or business JavaScript." | shell.`lede` |
|
||||
| claim | docs = program | shell.`claim` |
|
||||
| claim | server-side rules | shell.`claim` |
|
||||
| claim | hands-on | shell.`claim` |
|
||||
|
||||
`new_intro` =
|
||||
|
||||
| front | back | style |
|
||||
|-------|------|-------|
|
||||
| kicker | form · try validation | shell.`kicker` |
|
||||
| title | New article | shell.`intro_title` |
|
||||
| lede | "Leave Title empty and submit — the error comes from the rule table, not client JavaScript. Then fill title, slug, and summary to create a row shared with Admin and the card grid." | shell.`lede` |
|
||||
|
||||
`admin_intro` =
|
||||
|
||||
| front | back | style |
|
||||
|-------|------|-------|
|
||||
| kicker | desk · you are in admin | shell.`kicker` |
|
||||
| title | Admin | shell.`intro_title` |
|
||||
| lede | "This is the management desk (login required): same articles schema as the public site, assembled as list + create form — not a separate SPA. Use Site in the topnav to return, or Logout to end the session." | shell.`lede` |
|
||||
| claim | login-gated | shell.`claim` |
|
||||
| claim | table-declared | shell.`claim` |
|
||||
| claim | "create + list" | shell.`claim` |
|
||||
|
||||
`post_intro` =
|
||||
|
||||
| front | back | style |
|
||||
|-------|------|-------|
|
||||
| kicker | article · table-bound detail | shell.`kicker` |
|
||||
|
||||
Article create form: field table + rules table (server-side validation).
|
||||
|
||||
`article_fields` =
|
||||
|
||||
| 字段 | 标签 | 类型 | 必填 | 默认 |
|
||||
|------|------|------|------|------|
|
||||
| name | label | type | required | default |
|
||||
|------|-------|------|----------|---------|
|
||||
| title | Title | text | true | |
|
||||
| slug | Slug | text | true | |
|
||||
| summary | Summary | textarea | false | |
|
||||
| body | Body | textarea | false | |
|
||||
|
||||
`article_rules` =
|
||||
|
||||
| 字段 | 规则 | 消息 |
|
||||
|------|------|------|
|
||||
| field | rule | message |
|
||||
|-------|------|---------|
|
||||
| title | required | Title is required |
|
||||
| title | max:120 | Title is too long |
|
||||
| slug | required | Slug is required |
|
||||
| slug | max:80 | Slug is too long |
|
||||
| summary | max:500 | Summary is too long |
|
||||
| body | max:8000 | Body is too long |
|
||||
|
||||
SEO / Open Graph for the home page (still a table).
|
||||
|
||||
`home_meta` =
|
||||
|
||||
| key | value |
|
||||
|-----|-------|
|
||||
| description | Tables as the full stack — Marqdo Web demo with zero author business JavaScript. |
|
||||
| og:type | website |
|
||||
| og:title | Marqdo Web Site |
|
||||
|
||||
Neat CJK sans for body; Great Vibes for English display.
|
||||
|
||||
`fonts` =
|
||||
|
||||
| rel | href | crossorigin |
|
||||
|-----|------|-------------|
|
||||
| preconnect | https://fonts.googleapis.com | |
|
||||
| preconnect | https://fonts.gstatic.com | anonymous |
|
||||
| stylesheet | https://fonts.googleapis.com/css2?family=Great+Vibes&family=Noto+Sans+SC:wght@300;400;500;700&family=Noto+Serif+SC:wght@400;600&display=swap | |
|
||||
|
||||
**store = > db.open**
|
||||
**page = > web.page title="Marqdo Web Site" intro="<h1>Web Site</h1><p>Tables + class methods.</p>"**
|
||||
**site_css = > shell.css**
|
||||
|
||||
**page = > web.page title="Marqdo Web Site" shell_css="off"**
|
||||
**page = > page.compose_intro intro=home_intro**
|
||||
**page = > page.meta meta=home_meta**
|
||||
**page = > page.head table=fonts**
|
||||
**page = > page.css css=site_css**
|
||||
**page = > page.compose_components components=home**
|
||||
**page = > page.compose_main main=index**
|
||||
**page = > page.link_prefix prefix="/post/"**
|
||||
|
||||
About page: same shell, different intro (no main bind).
|
||||
|
||||
**about = > web.page title="About" intro="<h1>About</h1><p>Marqdo web = tables + class methods.</p>"**
|
||||
**about = > web.page title="About · Marqdo Web" shell_css="off"**
|
||||
**about = > about.compose_intro intro=about_intro**
|
||||
**about = > about.head table=fonts**
|
||||
**about = > about.css css=site_css**
|
||||
**about = > about.compose_components components=home**
|
||||
|
||||
**article_form = > web.form table="articles" action="insert"**
|
||||
**article_form = > article_form.fields fields=article_fields**
|
||||
**article_form = > article_form.rules rules=article_rules**
|
||||
|
||||
New article: form embedded in the page main slot (design §5.5.4).
|
||||
|
||||
**new = > web.page title="New article" intro="<h1>New article</h1><p>Form lives in the main slot.</p>"**
|
||||
**new = > web.page title="New article · Marqdo Web" shell_css="off"**
|
||||
**new = > new.compose_intro intro=new_intro**
|
||||
**new = > new.head table=fonts**
|
||||
**new = > new.css css=site_css**
|
||||
**new = > new.compose_components components=home**
|
||||
**new = > new.compose_form id="article" form=article_form**
|
||||
|
||||
**app = > web.app page=page db=store admin=True host="127.0.0.1" port=18081**
|
||||
**desk = > web.page title="Admin · Marqdo Web" shell_css="off"**
|
||||
**desk = > desk.chrome body_class="is-desk"**
|
||||
**desk = > desk.compose_intro intro=admin_intro**
|
||||
**desk = > desk.head table=fonts**
|
||||
**desk = > desk.css css=site_css**
|
||||
**desk = > desk.compose_components components=desk_shell**
|
||||
**desk = > desk.compose_form id="article" form=article_form**
|
||||
**desk = > desk.compose_main main=index**
|
||||
**desk = > desk.link_prefix prefix="/post/"**
|
||||
|
||||
**post = > web.page title="Article · Marqdo Web" shell_css="off"**
|
||||
**post = > post.compose_intro intro=post_intro**
|
||||
**post = > post.head table=fonts**
|
||||
**post = > post.css css=site_css**
|
||||
**post = > post.compose_components components=home**
|
||||
**post = > post.compose_main main=detail**
|
||||
**post = > post.query query=by_slug**
|
||||
**post = > post.detail detail=True**
|
||||
|
||||
Demo credentials (table-declared users — host session auth, no author JS).
|
||||
|
||||
`admins` =
|
||||
|
||||
| username | password | role |
|
||||
|----------|----------|------|
|
||||
| admin | demo | admin |
|
||||
|
||||
**app = > web.app page=page db=store admin=False host="127.0.0.1" port=18081 shell_css="off" login_redirect="/admin" logout_redirect="/"**
|
||||
**app = > app.route path="/about" page=about**
|
||||
**app = > app.route path="/new" page=new**
|
||||
**app = > app.static dir="public" mount="/static"**
|
||||
**app = > app.route path="/admin" page=desk**
|
||||
**app = > app.route path="/post/{slug}" page=post**
|
||||
**app = > app.auth users=admins session_ttl=3600 login_path="/login" login_redirect="/admin" logout_redirect="/"**
|
||||
**app = > app.gate path="/admin" roles="admin" match="prefix" on_deny="redirect" exclude="/login"**
|
||||
> `app`.listen
|
||||
@@ -1,5 +0,0 @@
|
||||
/* Optional site stylesheet — served at /static/site.css */
|
||||
body.site-hint::before {
|
||||
content: "static ok";
|
||||
display: none;
|
||||
}
|
||||
@@ -1,11 +1,233 @@
|
||||
---
|
||||
title: styles/shell
|
||||
description: >-
|
||||
Literary dark theme for examples/web-site — ink / wine / gold after the
|
||||
anlian.cyou Zhang Ailing topic. GFM tables only; no author .css.
|
||||
import web:ext/web/web.mq.md
|
||||
import text:lib/text.mq.md
|
||||
---
|
||||
|
||||
Authors style the site with **GFM tables** only. App pages use `shell_css=off`
|
||||
so host defaults do not fight this theme. Palette mirrors
|
||||
[海上花开](https://www.anlian.cyou/topics/author-zhangailing/): night ink,
|
||||
wine, cold gold, serif display.
|
||||
|
||||
## vars
|
||||
|
||||
`vars` =
|
||||
|
||||
| selector | property | value |
|
||||
|----------|----------|-------|
|
||||
| :root | --ink | #0a0809 |
|
||||
| :root | --ink-lift | #141012 |
|
||||
| :root | --wine | #6b1e3a |
|
||||
| :root | --wine-soft | rgba(107,30,58,0.35) |
|
||||
| :root | --gold | #d4af37 |
|
||||
| :root | --gold-dim | rgba(212,175,55,0.45) |
|
||||
| :root | --gold-soft | rgba(212,175,55,0.12) |
|
||||
| :root | --paper | rgba(255,248,240,0.92) |
|
||||
| :root | --paper-dim | rgba(255,248,240,0.72) |
|
||||
| :root | --paper-faint | rgba(255,248,240,0.48) |
|
||||
| :root | --glass | rgba(20,12,18,0.72) |
|
||||
| :root | --glass-strong | rgba(20,12,18,0.88) |
|
||||
| :root | --border | rgba(212,175,55,0.22) |
|
||||
| :root | --border-soft | rgba(212,175,55,0.12) |
|
||||
| :root | --danger | #e8a0a8 |
|
||||
| :root | --radius | 4px |
|
||||
| :root | --radius-sm | 2px |
|
||||
| :root | --space-2 | 8px |
|
||||
| :root | --space-3 | 12px |
|
||||
| :root | --space-4 | 16px |
|
||||
| :root | --space-5 | 20px |
|
||||
| :root | --space-6 | 24px |
|
||||
| :root | --space-8 | 32px |
|
||||
| :root | --text | 16px |
|
||||
| :root | --leading | "1.75" |
|
||||
| :root | --shadow | "0 24px 80px rgba(0,0,0,.55), inset 0 1px 0 rgba(255,255,255,.06)" |
|
||||
| :root | --shadow-card | "0 12px 40px rgba(107,30,58,.35)" |
|
||||
| :root | --ring | "0 0 0 2px rgba(212,175,55,.35)" |
|
||||
| :root | --serif | "'Noto Serif SC', 'Source Serif 4', Georgia, serif" |
|
||||
| :root | --sans | "'Noto Sans SC', 'IBM Plex Sans', system-ui, sans-serif" |
|
||||
| :root | --display | "'Great Vibes', 'Allura', cursive" |
|
||||
| :root | --mono | "ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" |
|
||||
| ::selection | background | rgba(212,175,55,0.35) |
|
||||
| ::selection | color | var(--paper) |
|
||||
|
||||
*`vars`*
|
||||
|
||||
## motion
|
||||
|
||||
`motion` =
|
||||
|
||||
| selector | property | value |
|
||||
|----------|----------|-------|
|
||||
| @keyframes rise 0% | opacity | "0" |
|
||||
| @keyframes rise 0% | transform | translateY(14px) |
|
||||
| @keyframes rise 100% | opacity | "1" |
|
||||
| @keyframes rise 100% | transform | translateY(0) |
|
||||
| @keyframes float 0% | transform | translateY(0) |
|
||||
| @keyframes float 0% | opacity | "0.7" |
|
||||
| @keyframes float 50% | transform | translateY(6px) |
|
||||
| @keyframes float 50% | opacity | "1" |
|
||||
| @keyframes float 100% | transform | translateY(0) |
|
||||
| @keyframes float 100% | opacity | "0.7" |
|
||||
| @keyframes goldPulse 0% | text-shadow | "0 0 24px rgba(212,175,55,.2)" |
|
||||
| @keyframes goldPulse 50% | text-shadow | "0 0 48px rgba(212,175,55,.45)" |
|
||||
| @keyframes goldPulse 100% | text-shadow | "0 0 24px rgba(212,175,55,.2)" |
|
||||
| @keyframes particleDrift 0% | transform | translate3d(0,0,0) |
|
||||
| @keyframes particleDrift 50% | transform | translate3d(-2.5vw, 1.5vh, 0) |
|
||||
| @keyframes particleDrift 100% | transform | translate3d(0,0,0) |
|
||||
| @keyframes particleDrift2 0% | transform | translate3d(0,0,0) |
|
||||
| @keyframes particleDrift2 50% | transform | translate3d(2vw, -2vh, 0) |
|
||||
| @keyframes particleDrift2 100% | transform | translate3d(0,0,0) |
|
||||
| @keyframes nebulaPulse 0% | opacity | "0.55" |
|
||||
| @keyframes nebulaPulse 50% | opacity | "0.9" |
|
||||
| @keyframes nebulaPulse 100% | opacity | "0.55" |
|
||||
|
||||
*`motion`*
|
||||
|
||||
## layout
|
||||
|
||||
`layout` =
|
||||
|
||||
| selector | property | value |
|
||||
|----------|----------|-------|
|
||||
| * | box-sizing | border-box |
|
||||
| html | scroll-behavior | smooth |
|
||||
| html | -webkit-text-size-adjust | 100% |
|
||||
| body | margin | "0" |
|
||||
| body | min-height | 100vh |
|
||||
| body | font-family | var(--sans) |
|
||||
| body | font-weight | "400" |
|
||||
| body | font-size | var(--text) |
|
||||
| body | line-height | var(--leading) |
|
||||
| body | color | var(--paper) |
|
||||
| body | background | var(--ink) |
|
||||
| body | background-image | "radial-gradient(ellipse 90% 55% at 50% -15%, rgba(107,30,58,.5), transparent 58%), radial-gradient(ellipse 55% 45% at 92% 75%, rgba(212,175,55,.14), transparent 55%), radial-gradient(ellipse 40% 35% at 8% 70%, rgba(107,30,58,.22), transparent 60%), linear-gradient(180deg, #0a0809 0%, #120c10 45%, #0a0809 100%)" |
|
||||
| body | background-attachment | fixed |
|
||||
| body | display | grid |
|
||||
| body | grid-template-rows | "auto 1fr auto" |
|
||||
| body | -webkit-font-smoothing | antialiased |
|
||||
| body | position | relative |
|
||||
| body | overflow-x | hidden |
|
||||
| body::before | content | '""' |
|
||||
| body::before | position | fixed |
|
||||
| body::before | inset | "0" |
|
||||
| body::before | z-index | "1" |
|
||||
| body::before | pointer-events | none |
|
||||
| body::before | opacity | "0.1" |
|
||||
| body::before | background-image | "url(\"data:image/svg+xml,%3Csvg viewBox='0 0 256 256' xmlns='http://www.w3.org/2000/svg'%3E%3Cfilter id='n'%3E%3CfeTurbulence type='fractalNoise' baseFrequency='0.9' numOctaves='4' stitchTiles='stitch'/%3E%3C/filter%3E%3Crect width='100%25' height='100%25' filter='url(%23n)'/%3E%3C/svg%3E\")" |
|
||||
| html::before | content | '""' |
|
||||
| html::before | position | fixed |
|
||||
| html::before | inset | "0" |
|
||||
| html::before | z-index | "0" |
|
||||
| html::before | pointer-events | none |
|
||||
| html::before | background-image | "radial-gradient(ellipse 50% 40% at 15% 30%, rgba(107,30,58,.35), transparent 70%), radial-gradient(ellipse 45% 35% at 85% 60%, rgba(212,175,55,.12), transparent 65%), radial-gradient(ellipse 40% 30% at 50% 90%, rgba(107,30,58,.25), transparent 70%)" |
|
||||
| html::before | animation | "nebulaPulse 12s ease-in-out infinite" |
|
||||
| body::after | content | '""' |
|
||||
| body::after | position | fixed |
|
||||
| body::after | top | "0" |
|
||||
| body::after | left | "0" |
|
||||
| body::after | width | "2px" |
|
||||
| body::after | height | "2px" |
|
||||
| body::after | z-index | "2" |
|
||||
| body::after | pointer-events | none |
|
||||
| body::after | border-radius | 50% |
|
||||
| body::after | background | transparent |
|
||||
| body::after | box-shadow | "82vw 15vh 0px 0px rgba(212,175,55,0.55),29vw 18vh 0px 1px rgba(212,175,55,0.25),95vw 70vh 1px 0px rgba(212,175,55,0.55),4vw 12vh 0px 1px rgba(212,175,55,0.35),78vw 4vh 0px 1px rgba(245,230,200,0.5),84vw 90vh 1px 0px rgba(245,230,200,0.5),58vw 76vh 0px 0px rgba(255,248,240,0.4),90vw 55vh 0px 0px rgba(255,248,240,0.4),28vw 98vh 0px 0px rgba(255,248,240,0.4),49vw 13vh 0px 1px rgba(255,248,240,0.4),34vw 6vh 1px 1px rgba(212,175,55,0.25),16vw 49vh 0px 1px rgba(212,175,55,0.55),80vw 47vh 0px 1px rgba(245,230,200,0.5),9vw 6vh 0px 0px rgba(212,175,55,0.25),11vw 30vh 1px 0px rgba(212,175,55,0.55),59vw 82vh 0px 0px rgba(255,248,240,0.4),46vw 27vh 0px 1px rgba(212,175,55,0.25),88vw 83vh 0px 1px rgba(212,175,55,0.55),94vw 32vh 1px 0px rgba(212,175,55,0.35),35vw 82vh 0px 1px rgba(212,175,55,0.25),42vw 99vh 0px 0px rgba(212,175,55,0.55),41vw 52vh 0px 0px rgba(255,248,240,0.4),73vw 92vh 0px 1px rgba(255,248,240,0.4),64vw 51vh 1px 0px rgba(212,175,55,0.25),34vw 18vh 0px 1px rgba(212,175,55,0.35),75vw 55vh 1px 0px rgba(245,230,200,0.5),29vw 18vh 1px 0px rgba(245,230,200,0.5),97vw 7vh 0px 1px rgba(212,175,55,0.55),21vw 88vh 0px 0px rgba(107,30,58,0.45),49vw 77vh 0px 1px rgba(107,30,58,0.45),2vw 88vh 0px 1px rgba(212,175,55,0.25),69vw 97vh 0px 0px rgba(255,248,240,0.4),38vw 56vh 1px 0px rgba(212,175,55,0.35),93vw 93vh 0px 1px rgba(255,248,240,0.4),14vw 81vh 0px 0px rgba(255,248,240,0.4),48vw 98vh 0px 1px rgba(212,175,55,0.35),42vw 63vh 0px 0px rgba(212,175,55,0.55),40vw 31vh 0px 1px rgba(212,175,55,0.55),11vw 11vh 1px 0px rgba(212,175,55,0.25),98vw 69vh 0px 1px rgba(212,175,55,0.35),61vw 71vh 0px 1px rgba(212,175,55,0.35),78vw 55vh 0px 1px rgba(212,175,55,0.35),40vw 52vh 0px 0px rgba(212,175,55,0.25),67vw 58vh 0px 0px rgba(212,175,55,0.55),9vw 44vh 0px 1px rgba(212,175,55,0.55),29vw 1vh 0px 0px rgba(212,175,55,0.55),9vw 5vh 0px 1px rgba(255,248,240,0.4),31vw 36vh 1px 0px rgba(212,175,55,0.25),70vw 17vh 1px 0px rgba(212,175,55,0.25),61vw 53vh 0px 0px rgba(212,175,55,0.35),85vw 56vh 1px 0px rgba(255,248,240,0.4),60vw 94vh 0px 0px rgba(212,175,55,0.55),52vw 94vh 0px 0px rgba(255,248,240,0.4),25vw 25vh 1px 0px rgba(245,230,200,0.5),55vw 24vh 1px 0px rgba(255,248,240,0.4),10vw 57vh 0px 0px rgba(245,230,200,0.5),84vw 70vh 0px 0px rgba(212,175,55,0.55),22vw 53vh 1px 0px rgba(107,30,58,0.45),52vw 8vh 1px 0px rgba(212,175,55,0.35),50vw 34vh 0px 0px rgba(107,30,58,0.45),90vw 94vh 1px 0px rgba(245,230,200,0.5),25vw 38vh 0px 1px rgba(212,175,55,0.35),95vw 70vh 0px 0px rgba(212,175,55,0.55),7vw 75vh 0px 0px rgba(107,30,58,0.45),66vw 11vh 0px 1px rgba(212,175,55,0.35),9vw 87vh 1px 0px rgba(212,175,55,0.35),73vw 32vh 0px 1px rgba(245,230,200,0.5),11vw 54vh 0px 0px rgba(212,175,55,0.25),27vw 86vh 0px 0px rgba(212,175,55,0.25),34vw 51vh 0px 0px rgba(212,175,55,0.35),41vw 97vh 0px 0px rgba(212,175,55,0.55),80vw 73vh 0px 1px rgba(212,175,55,0.55)" |
|
||||
| body::after | animation | "particleDrift 48s ease-in-out infinite" |
|
||||
| html::after | content | '""' |
|
||||
| html::after | position | fixed |
|
||||
| html::after | top | "0" |
|
||||
| html::after | left | "0" |
|
||||
| html::after | width | "1px" |
|
||||
| html::after | height | "1px" |
|
||||
| html::after | z-index | "2" |
|
||||
| html::after | pointer-events | none |
|
||||
| html::after | border-radius | 50% |
|
||||
| html::after | background | transparent |
|
||||
| html::after | box-shadow | "28vw 65vh 0 0 rgba(255,248,240,0.25),17vw 45vh 0 0 rgba(212,175,55,0.3),32vw 48vh 0 0 rgba(255,248,240,0.25),21vw 57vh 0 0 rgba(107,30,58,0.3),91vw 39vh 0 0 rgba(107,30,58,0.3),84vw 68vh 0 0 rgba(212,175,55,0.3),86vw 71vh 0 0 rgba(255,248,240,0.25),85vw 14vh 0 0 rgba(212,175,55,0.3),34vw 15vh 0 0 rgba(212,175,55,0.3),96vw 71vh 0 0 rgba(212,175,55,0.3),35vw 37vh 0 0 rgba(107,30,58,0.3),27vw 92vh 0 0 rgba(255,248,240,0.25),27vw 88vh 0 0 rgba(107,30,58,0.3),34vw 65vh 0 0 rgba(255,248,240,0.25),33vw 7vh 0 0 rgba(212,175,55,0.3),82vw 55vh 0 0 rgba(255,248,240,0.25),6vw 1vh 0 0 rgba(255,248,240,0.25),99vw 17vh 0 0 rgba(107,30,58,0.3),34vw 21vh 0 0 rgba(107,30,58,0.3),57vw 71vh 0 0 rgba(107,30,58,0.3),55vw 72vh 0 0 rgba(212,175,55,0.3),15vw 10vh 0 0 rgba(107,30,58,0.3),20vw 70vh 0 0 rgba(212,175,55,0.3),48vw 75vh 0 0 rgba(107,30,58,0.3),19vw 56vh 0 0 rgba(212,175,55,0.3),6vw 40vh 0 0 rgba(255,248,240,0.25),6vw 46vh 0 0 rgba(212,175,55,0.3),88vw 32vh 0 0 rgba(107,30,58,0.3),14vw 46vh 0 0 rgba(107,30,58,0.3),53vw 80vh 0 0 rgba(107,30,58,0.3),20vw 31vh 0 0 rgba(212,175,55,0.3),23vw 53vh 0 0 rgba(212,175,55,0.3),23vw 95vh 0 0 rgba(255,248,240,0.25),53vw 86vh 0 0 rgba(107,30,58,0.3),32vw 35vh 0 0 rgba(212,175,55,0.3),90vw 14vh 0 0 rgba(255,248,240,0.25),5vw 61vh 0 0 rgba(212,175,55,0.3),26vw 59vh 0 0 rgba(255,248,240,0.25),40vw 30vh 0 0 rgba(212,175,55,0.3),4vw 85vh 0 0 rgba(212,175,55,0.3),52vw 43vh 0 0 rgba(255,248,240,0.25),9vw 99vh 0 0 rgba(255,248,240,0.25),45vw 83vh 0 0 rgba(107,30,58,0.3),52vw 87vh 0 0 rgba(107,30,58,0.3),43vw 4vh 0 0 rgba(212,175,55,0.3),34vw 23vh 0 0 rgba(107,30,58,0.3),34vw 5vh 0 0 rgba(212,175,55,0.3),77vw 56vh 0 0 rgba(255,248,240,0.25)" |
|
||||
| html::after | animation | "particleDrift2 64s ease-in-out infinite" |
|
||||
| body.has-sidebar | grid-template-columns | "14rem minmax(0, 1fr)" |
|
||||
| body.has-sidebar | grid-template-areas | '"top top" "side main" "foot foot"' |
|
||||
| body.no-sidebar | grid-template-areas | '"top" "main" "foot"' |
|
||||
| body.layout-stacked | grid-template-areas | '"top" "main" "foot"' |
|
||||
| body.is-desk | grid-template-areas | '"top" "main" "foot"' |
|
||||
| header.topnav | grid-area | top |
|
||||
| aside.side | grid-area | side |
|
||||
| main.main | grid-area | main |
|
||||
| footer.foot | grid-area | foot |
|
||||
| header.topnav | position | relative |
|
||||
| header.topnav | z-index | "20" |
|
||||
| aside.side | position | relative |
|
||||
| aside.side | z-index | "10" |
|
||||
| main.main | position | relative |
|
||||
| main.main | z-index | "10" |
|
||||
| footer.foot | position | relative |
|
||||
| footer.foot | z-index | "10" |
|
||||
| main.main | width | "100%" |
|
||||
| main.main | max-width | "min(78rem, 100%)" |
|
||||
| main.main | padding | "var(--space-8) var(--space-6) 4rem" |
|
||||
| main.main | animation | "rise .8s cubic-bezier(.22,1,.36,1) both" |
|
||||
| a | color | var(--gold) |
|
||||
| a | text-decoration | none |
|
||||
| a | transition | color 0.25s ease |
|
||||
| a:hover | color | #f5e6c8 |
|
||||
| code | font-family | var(--mono) |
|
||||
| code | font-size | "0.82em" |
|
||||
| code | font-weight | "400" |
|
||||
| code | background | rgba(0,0,0,0.35) |
|
||||
| code | border | 1px solid var(--border-soft) |
|
||||
| code | padding | "0.12em 0.45em" |
|
||||
| code | border-radius | var(--radius-sm) |
|
||||
| code | color | var(--gold) |
|
||||
|
||||
*`layout`*
|
||||
|
||||
## responsive
|
||||
|
||||
`responsive` =
|
||||
|
||||
| media | selector | property | value |
|
||||
|-------|----------|----------|-------|
|
||||
| (max-width: 860px) | body.has-sidebar | grid-template-columns | 1fr |
|
||||
| (max-width: 860px) | body.has-sidebar | grid-template-areas | '"top" "main" "side" "foot"' |
|
||||
| (max-width: 860px) | aside.side | border-right | "0" |
|
||||
| (max-width: 860px) | aside.side | border-top | 1px solid var(--border-soft) |
|
||||
| (max-width: 860px) | main.main | padding | "var(--space-6) var(--space-4) var(--space-8)" |
|
||||
| (max-width: 860px) | .content.cards | grid-template-columns | 1fr |
|
||||
| (max-width: 860px) | .site-form form | grid-template-columns | 1fr |
|
||||
| (max-width: 860px) | .site-form label:nth-child(1) | grid-column | "1 / -1" |
|
||||
| (max-width: 860px) | .site-form label:nth-child(2) | grid-column | "1 / -1" |
|
||||
| (max-width: 860px) | header.topnav | padding | "0.85rem var(--space-4)" |
|
||||
| (max-width: 860px) | .intro_title | font-size | "2.4rem" |
|
||||
| (prefers-reduced-motion: reduce) | main.main | animation | none |
|
||||
| (prefers-reduced-motion: reduce) | .kicker | animation | none |
|
||||
| (prefers-reduced-motion: reduce) | article.card | transition | none |
|
||||
| (prefers-reduced-motion: reduce) | body::after | animation | none |
|
||||
| (prefers-reduced-motion: reduce) | html::after | animation | none |
|
||||
| (prefers-reduced-motion: reduce) | html::before | animation | none |
|
||||
|
||||
*`responsive`*
|
||||
|
||||
## topnav
|
||||
|
||||
`topnav` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| background | #ffffff |
|
||||
| border-bottom | 1px solid #e7e5e4 |
|
||||
| property | value |
|
||||
|----------|-------|
|
||||
| position | sticky |
|
||||
| top | "0" |
|
||||
| z-index | "40" |
|
||||
| display | flex |
|
||||
| align-items | center |
|
||||
| justify-content | flex-start |
|
||||
| gap | var(--space-4) |
|
||||
| padding | "1rem var(--space-6)" |
|
||||
| background | "linear-gradient(180deg, rgba(10,8,9,.92) 0%, rgba(10,8,9,.55) 70%, transparent 100%)" |
|
||||
| backdrop-filter | blur(10px) |
|
||||
| -webkit-backdrop-filter | blur(10px) |
|
||||
| border-bottom | 1px solid var(--border-soft) |
|
||||
|
||||
*`topnav`*
|
||||
|
||||
@@ -13,20 +235,42 @@
|
||||
|
||||
`side_panel` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| background | #f5f5f4 |
|
||||
| property | value |
|
||||
|----------|-------|
|
||||
| background | "rgba(10,8,9,.55)" |
|
||||
| padding | "var(--space-6) var(--space-4)" |
|
||||
| border-right | 1px solid var(--border-soft) |
|
||||
|
||||
*`side_panel`*
|
||||
|
||||
## footer
|
||||
|
||||
`footer` =
|
||||
|
||||
| property | value |
|
||||
|----------|-------|
|
||||
| color | var(--paper-faint) |
|
||||
| font-size | "0.8rem" |
|
||||
| letter-spacing | "0.08em" |
|
||||
| padding | "var(--space-5) var(--space-6)" |
|
||||
| border-top | 1px solid var(--border-soft) |
|
||||
| background | "rgba(10,8,9,.75)" |
|
||||
|
||||
*`footer`*
|
||||
|
||||
## card_title
|
||||
|
||||
`card_title` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| font-size | 1.15rem |
|
||||
| margin | 0 0 0.35rem |
|
||||
| property | value |
|
||||
|----------|-------|
|
||||
| font-family | var(--serif) |
|
||||
| font-size | "1.15rem" |
|
||||
| font-weight | "600" |
|
||||
| margin | "0 0 var(--space-2)" |
|
||||
| color | var(--gold) |
|
||||
| letter-spacing | "0.02em" |
|
||||
| line-height | "1.35" |
|
||||
|
||||
*`card_title`*
|
||||
|
||||
@@ -34,9 +278,398 @@
|
||||
|
||||
`card_body` =
|
||||
|
||||
| 属性 | 值 |
|
||||
|------|-----|
|
||||
| color | #57534e |
|
||||
| margin | 0 |
|
||||
| property | value |
|
||||
|----------|-------|
|
||||
| color | var(--paper-dim) |
|
||||
| margin | "0" |
|
||||
| line-height | "1.65" |
|
||||
| font-size | "0.9rem" |
|
||||
| font-weight | "400" |
|
||||
| display | "-webkit-box" |
|
||||
| -webkit-box-orient | vertical |
|
||||
| -webkit-line-clamp | "3" |
|
||||
| overflow | hidden |
|
||||
|
||||
*`card_body`*
|
||||
|
||||
## chrome
|
||||
|
||||
Panel + claim/steps group layout (field look comes from named bind styles).
|
||||
|
||||
`chrome` =
|
||||
|
||||
| selector | property | value |
|
||||
|----------|----------|-------|
|
||||
| .main-intro | background | var(--glass) |
|
||||
| .main-intro | border | 1px solid var(--border) |
|
||||
| .main-intro | border-radius | var(--radius) |
|
||||
| .main-intro | padding | "2.25rem 1.75rem 1.85rem" |
|
||||
| .main-intro | box-shadow | var(--shadow) |
|
||||
| .main-intro | backdrop-filter | blur(16px) |
|
||||
| .main-intro | -webkit-backdrop-filter | blur(16px) |
|
||||
| .main-intro | margin-bottom | var(--space-8) |
|
||||
| .main-intro > .claim | display | flex |
|
||||
| .main-intro > .claim | flex-wrap | wrap |
|
||||
| .main-intro > .claim | gap | var(--space-2) |
|
||||
| .main-intro > .claim | margin | "0 0 var(--space-6)" |
|
||||
| .main-intro > .steps | margin | "0" |
|
||||
| .main-intro > .steps | padding | "var(--space-5) var(--space-5) var(--space-5) 1.5rem" |
|
||||
| .main-intro > .steps | color | var(--paper-dim) |
|
||||
| .main-intro > .steps | background | "rgba(0,0,0,.35)" |
|
||||
| .main-intro > .steps | border | 1px solid var(--border-soft) |
|
||||
| .main-intro > .steps | border-left | 2px solid var(--gold-dim) |
|
||||
| .main-intro > .steps | border-radius | var(--radius) |
|
||||
| .main-intro > .steps | font-size | "0.95rem" |
|
||||
| .main-intro > .steps | letter-spacing | "0.02em" |
|
||||
| .main-intro > .steps a | color | var(--gold) |
|
||||
| .main-intro > .steps a | font-weight | "500" |
|
||||
| .main-intro > .steps a:hover | color | #f5e6c8 |
|
||||
| .article | background | var(--glass) |
|
||||
| .article | border | 1px solid var(--border) |
|
||||
| .article | border-radius | var(--radius) |
|
||||
| .article | padding | "2rem 1.75rem" |
|
||||
| .article | box-shadow | var(--shadow) |
|
||||
| .article | backdrop-filter | blur(16px) |
|
||||
| .article | -webkit-backdrop-filter | blur(16px) |
|
||||
| .article-title | font-family | var(--serif) |
|
||||
| .article-title | font-size | "clamp(1.75rem, 4vw, 2.35rem)" |
|
||||
| .article-title | font-weight | "600" |
|
||||
| .article-title | color | var(--gold) |
|
||||
| .article-title | letter-spacing | "0.04em" |
|
||||
| .article-title | margin | "0 0 var(--space-5)" |
|
||||
| .article-title | line-height | "1.25" |
|
||||
| .article-body | color | var(--paper-dim) |
|
||||
| .article-body | font-family | var(--sans) |
|
||||
| .article-body | font-size | "1.02rem" |
|
||||
| .article-body | line-height | "1.85" |
|
||||
| .article-body.md p | margin | "0 0 1.1rem" |
|
||||
| .article-body.md a | color | var(--gold) |
|
||||
| article.card | cursor | pointer |
|
||||
| a.card-link | color | inherit |
|
||||
| a.card-link | text-decoration | none |
|
||||
| a.card-link:hover | color | inherit |
|
||||
|
||||
*`chrome`*
|
||||
|
||||
## kicker
|
||||
|
||||
`kicker` =
|
||||
|
||||
| property | value |
|
||||
|----------|-------|
|
||||
| letter-spacing | "0.32em" |
|
||||
| text-transform | uppercase |
|
||||
| font-size | "0.72rem" |
|
||||
| color | var(--gold-dim) |
|
||||
| margin | "0 0 var(--space-4)" |
|
||||
| font-weight | "400" |
|
||||
| font-family | var(--sans) |
|
||||
| animation | "float 2.8s ease-in-out infinite" |
|
||||
|
||||
*`kicker`*
|
||||
|
||||
## intro_title
|
||||
|
||||
`intro_title` =
|
||||
|
||||
| property | value |
|
||||
|----------|-------|
|
||||
| font-family | var(--display) |
|
||||
| font-size | "clamp(3rem, 10vw, 4.8rem)" |
|
||||
| font-weight | "400" |
|
||||
| line-height | "1.15" |
|
||||
| letter-spacing | "0.04em" |
|
||||
| margin | "0 0 var(--space-4)" |
|
||||
| color | transparent |
|
||||
| background | "linear-gradient(135deg, #f5e6c8 0%, var(--gold) 42%, var(--wine) 100%)" |
|
||||
| -webkit-background-clip | text |
|
||||
| background-clip | text |
|
||||
| animation | "goldPulse 4.5s ease-in-out infinite" |
|
||||
|
||||
*`intro_title`*
|
||||
|
||||
## lede
|
||||
|
||||
`lede` =
|
||||
|
||||
| property | value |
|
||||
|----------|-------|
|
||||
| color | var(--paper-dim) |
|
||||
| max-width | "34rem" |
|
||||
| line-height | "1.85" |
|
||||
| margin | "0 0 var(--space-5)" |
|
||||
| font-size | "1.05rem" |
|
||||
| letter-spacing | "0.02em" |
|
||||
| font-weight | "400" |
|
||||
| font-family | var(--sans) |
|
||||
|
||||
*`lede`*
|
||||
|
||||
## claim
|
||||
|
||||
`claim` =
|
||||
|
||||
| property | value |
|
||||
|----------|-------|
|
||||
| display | inline-flex |
|
||||
| align-items | center |
|
||||
| padding | "0.2rem 0.65rem" |
|
||||
| border-radius | var(--radius-sm) |
|
||||
| background | var(--wine-soft) |
|
||||
| color | #f0c9d4 |
|
||||
| font-size | "0.68rem" |
|
||||
| font-weight | "500" |
|
||||
| letter-spacing | "0.14em" |
|
||||
| border | 1px solid rgba(107,30,58,0.5) |
|
||||
|
||||
*`claim`*
|
||||
|
||||
## step
|
||||
|
||||
`step` =
|
||||
|
||||
| property | value |
|
||||
|----------|-------|
|
||||
| margin | "0.55rem 0" |
|
||||
|
||||
*`step`*
|
||||
|
||||
## widgets
|
||||
|
||||
`widgets` =
|
||||
|
||||
| selector | property | value |
|
||||
|----------|----------|-------|
|
||||
| ul.nav | display | flex |
|
||||
| ul.nav | flex-wrap | wrap |
|
||||
| ul.nav | align-items | center |
|
||||
| ul.nav | gap | "0.35rem 1rem" |
|
||||
| ul.nav | list-style | none |
|
||||
| ul.nav | margin | "0" |
|
||||
| ul.nav | padding | "0" |
|
||||
| ul.nav a | display | inline-flex |
|
||||
| ul.nav a | align-items | center |
|
||||
| ul.nav a | text-decoration | none |
|
||||
| ul.nav a | color | var(--paper-dim) |
|
||||
| ul.nav a | padding | "0.35rem 0" |
|
||||
| ul.nav a | border-radius | "0" |
|
||||
| ul.nav a | font-weight | "400" |
|
||||
| ul.nav a | font-size | "0.8rem" |
|
||||
| ul.nav a | letter-spacing | "0.14em" |
|
||||
| ul.nav a | transition | color 0.25s ease |
|
||||
| ul.nav a:hover | background | transparent |
|
||||
| ul.nav a:hover | color | var(--gold) |
|
||||
| ul.nav a:hover | text-decoration | none |
|
||||
| ul.nav a[href="/admin"] | color | var(--gold) |
|
||||
| ul.nav a[href="/admin"] | letter-spacing | "0.18em" |
|
||||
| ul.nav a[href="/admin"] | border-bottom | 1px solid var(--gold-dim) |
|
||||
| ul.side-nav a[href="/admin"] | color | var(--gold) |
|
||||
| body.is-desk header.topnav | border-bottom | 1px solid rgba(107,30,58,0.55) |
|
||||
| body.is-desk header.topnav | box-shadow | "0 12px 40px rgba(107,30,58,.18)" |
|
||||
| body.is-desk .main-intro | border-left | 3px solid var(--wine) |
|
||||
| body.is-desk .site-form | border-color | rgba(107,30,58,0.45) |
|
||||
| body.is-desk .site-form | box-shadow | "0 0 0 1px rgba(212,175,55,.12), 0 18px 48px rgba(0,0,0,.35)" |
|
||||
| body.is-desk .content.cards | margin-top | var(--space-6) |
|
||||
| ul.nav li:first-child a | font-family | var(--display) |
|
||||
| ul.nav li:first-child a | font-weight | "400" |
|
||||
| ul.nav li:first-child a | color | var(--gold) |
|
||||
| ul.nav li:first-child a | font-size | "1.85rem" |
|
||||
| ul.nav li:first-child a | letter-spacing | "0.06em" |
|
||||
| ul.nav li:first-child a | padding | "0.1rem 0.2rem 0.1rem 0" |
|
||||
| ul.nav li:first-child a:hover | background | transparent |
|
||||
| ul.nav li:first-child a:hover | color | #f5e6c8 |
|
||||
| .side-label | display | block |
|
||||
| .side-label | font-size | "0" |
|
||||
| .side-label | margin | "0 0 var(--space-4)" |
|
||||
| .side-label::before | content | '"Path"' |
|
||||
| .side-label::before | display | block |
|
||||
| .side-label::before | font-size | "0.68rem" |
|
||||
| .side-label::before | letter-spacing | "0.28em" |
|
||||
| .side-label::before | text-transform | uppercase |
|
||||
| .side-label::before | color | var(--gold-dim) |
|
||||
| .side-label::before | font-weight | "400" |
|
||||
| ul.side-nav | list-style | none |
|
||||
| ul.side-nav | margin | "0" |
|
||||
| ul.side-nav | padding | "0" |
|
||||
| ul.side-nav | display | grid |
|
||||
| ul.side-nav | gap | "2px" |
|
||||
| ul.side-nav | border-left | 1px solid var(--border) |
|
||||
| ul.side-nav | padding-left | "0.85rem" |
|
||||
| ul.side-nav | margin-left | "0.25rem" |
|
||||
| ul.side-nav a | display | block |
|
||||
| ul.side-nav a | text-decoration | none |
|
||||
| ul.side-nav a | color | var(--paper-dim) |
|
||||
| ul.side-nav a | padding | "0.45rem 0.35rem" |
|
||||
| ul.side-nav a | border-radius | "0" |
|
||||
| ul.side-nav a | font-weight | "400" |
|
||||
| ul.side-nav a | font-size | "0.88rem" |
|
||||
| ul.side-nav a | letter-spacing | "0.06em" |
|
||||
| ul.side-nav a | border | "0" |
|
||||
| ul.side-nav a | position | relative |
|
||||
| ul.side-nav a:hover | background | transparent |
|
||||
| ul.side-nav a:hover | border-color | transparent |
|
||||
| ul.side-nav a:hover | color | var(--gold) |
|
||||
| ul.side-nav a:hover | text-decoration | none |
|
||||
| ul.side-nav a:hover | box-shadow | none |
|
||||
| ul.foot-nav | display | flex |
|
||||
| ul.foot-nav | gap | var(--space-4) |
|
||||
| ul.foot-nav | list-style | none |
|
||||
| ul.foot-nav | margin | "0" |
|
||||
| ul.foot-nav | padding | "0" |
|
||||
| ul.foot-nav a | color | var(--paper-faint) |
|
||||
| ul.foot-nav a | font-weight | "400" |
|
||||
| ul.foot-nav a | letter-spacing | "0.1em" |
|
||||
| ul.foot-nav a | font-size | "0.78rem" |
|
||||
| ul.foot-nav a:hover | color | var(--gold) |
|
||||
| .content.cards | display | grid |
|
||||
| .content.cards | gap | var(--space-4) |
|
||||
| .content.cards | margin-top | "0" |
|
||||
| .content.cards | grid-template-columns | "repeat(auto-fill, minmax(16rem, 1fr))" |
|
||||
| article.card | background | "rgba(0,0,0,.35)" |
|
||||
| article.card | border | 1px solid var(--border-soft) |
|
||||
| article.card | border-radius | var(--radius-sm) |
|
||||
| article.card | padding | "1.35rem 1.15rem" |
|
||||
| article.card | box-shadow | none |
|
||||
| article.card | transition | "border-color .35s ease, box-shadow .35s ease, transform .35s ease" |
|
||||
| article.card:hover | transform | "translateY(-3px)" |
|
||||
| article.card:hover | box-shadow | var(--shadow-card) |
|
||||
| article.card:hover | border-color | var(--gold-dim) |
|
||||
| .site-form | background | var(--glass) |
|
||||
| .site-form | border | 1px solid var(--border) |
|
||||
| .site-form | border-radius | var(--radius) |
|
||||
| .site-form | padding | "var(--space-6) var(--space-6) var(--space-7, 1.75rem)" |
|
||||
| .site-form | margin | "0 0 var(--space-6)" |
|
||||
| .site-form | max-width | "100%" |
|
||||
| .site-form | width | "100%" |
|
||||
| .site-form | box-shadow | var(--shadow) |
|
||||
| .site-form | backdrop-filter | blur(16px) |
|
||||
| .site-form | -webkit-backdrop-filter | blur(16px) |
|
||||
| .site-form .meta | display | none |
|
||||
| .site-form form | display | grid |
|
||||
| .site-form form | grid-template-columns | "minmax(0, 1fr) minmax(0, 1fr)" |
|
||||
| .site-form form | column-gap | var(--space-5) |
|
||||
| .site-form form | row-gap | var(--space-5) |
|
||||
| .site-form form | gap | var(--space-5) |
|
||||
| .site-form form | margin | "0" |
|
||||
| .site-form form | width | "100%" |
|
||||
| .site-form form | max-width | "100%" |
|
||||
| .site-form label | display | grid |
|
||||
| .site-form label | gap | var(--space-2) |
|
||||
| .site-form label | margin | "0" |
|
||||
| .site-form label | min-width | "0" |
|
||||
| .site-form label | font-weight | "400" |
|
||||
| .site-form label | color | var(--gold) |
|
||||
| .site-form label | font-size | "0.78rem" |
|
||||
| .site-form label | letter-spacing | "0.16em" |
|
||||
| .site-form label | text-transform | uppercase |
|
||||
| .site-form label:nth-child(1) | grid-column | "1" |
|
||||
| .site-form label:nth-child(2) | grid-column | "2" |
|
||||
| .site-form label:nth-child(n+3) | grid-column | "1 / -1" |
|
||||
| .site-form .actions | grid-column | "1 / -1" |
|
||||
| .site-form input | -webkit-appearance | none |
|
||||
| .site-form textarea | -webkit-appearance | none |
|
||||
| .site-form input | appearance | none |
|
||||
| .site-form textarea | appearance | none |
|
||||
| .site-form input | box-sizing | border-box |
|
||||
| .site-form textarea | box-sizing | border-box |
|
||||
| .site-form input | display | block |
|
||||
| .site-form textarea | display | block |
|
||||
| .site-form input | width | "100%" |
|
||||
| .site-form textarea | width | "100%" |
|
||||
| .site-form input | height | "2.75rem" |
|
||||
| .site-form textarea | min-height | "10rem" |
|
||||
| .site-form label:nth-child(4) textarea | min-height | "14rem" |
|
||||
| .site-form textarea | resize | vertical |
|
||||
| .site-form input | padding | "0 0.9rem" |
|
||||
| .site-form textarea | padding | "0.75rem 0.9rem" |
|
||||
| .site-form input | border | 1px solid var(--border) |
|
||||
| .site-form textarea | border | 1px solid var(--border) |
|
||||
| .site-form input | border-radius | var(--radius-sm) |
|
||||
| .site-form textarea | border-radius | var(--radius-sm) |
|
||||
| .site-form input | background | "rgba(0,0,0,.4)" |
|
||||
| .site-form textarea | background | "rgba(0,0,0,.4)" |
|
||||
| .site-form input | color | var(--paper) |
|
||||
| .site-form textarea | color | var(--paper) |
|
||||
| .site-form input | font | inherit |
|
||||
| .site-form textarea | font | inherit |
|
||||
| .site-form input | font-size | "0.95rem" |
|
||||
| .site-form textarea | font-size | "0.95rem" |
|
||||
| .site-form input | line-height | "1.4" |
|
||||
| .site-form textarea | line-height | "1.65" |
|
||||
| .site-form input | transition | "border-color .2s ease, box-shadow .2s ease" |
|
||||
| .site-form textarea | transition | "border-color .2s ease, box-shadow .2s ease" |
|
||||
| .site-form input:hover | border-color | var(--gold-dim) |
|
||||
| .site-form textarea:hover | border-color | var(--gold-dim) |
|
||||
| .site-form input:focus | outline | none |
|
||||
| .site-form textarea:focus | outline | none |
|
||||
| .site-form input:focus | border-color | var(--gold) |
|
||||
| .site-form textarea:focus | border-color | var(--gold) |
|
||||
| .site-form input:focus | box-shadow | var(--ring) |
|
||||
| .site-form textarea:focus | box-shadow | var(--ring) |
|
||||
| .site-form input[readonly] | background | "rgba(0,0,0,.25)" |
|
||||
| .site-form input[readonly] | color | var(--paper-faint) |
|
||||
| .site-form .err | color | var(--danger) |
|
||||
| .site-form .err | font-size | "0.8rem" |
|
||||
| .site-form .err | font-weight | "500" |
|
||||
| .site-form .err | letter-spacing | "0.04em" |
|
||||
| .site-form .actions | display | flex |
|
||||
| .site-form .actions | align-items | center |
|
||||
| .site-form .actions | gap | var(--space-4) |
|
||||
| .site-form .actions | margin-top | var(--space-2) |
|
||||
| .site-form .actions | flex-wrap | wrap |
|
||||
| .site-form button | -webkit-appearance | none |
|
||||
| .site-form button | appearance | none |
|
||||
| .site-form button | height | "2.75rem" |
|
||||
| .site-form button | padding | "0 1.35rem" |
|
||||
| .site-form button | background | "linear-gradient(135deg, #f5e6c8, var(--gold))" |
|
||||
| .site-form button | color | var(--ink) |
|
||||
| .site-form button | border | "0" |
|
||||
| .site-form button | border-radius | 999px |
|
||||
| .site-form button | font-weight | "600" |
|
||||
| .site-form button | font-size | "0.85rem" |
|
||||
| .site-form button | letter-spacing | "0.12em" |
|
||||
| .site-form button | cursor | pointer |
|
||||
| .site-form button | box-shadow | "0 8px 28px rgba(212,175,55,.28)" |
|
||||
| .site-form button | transition | "transform .2s ease, box-shadow .2s ease, filter .2s ease" |
|
||||
| .site-form button:hover | filter | brightness(1.06) |
|
||||
| .site-form button:hover | transform | "translateY(-1px)" |
|
||||
| .site-form button:hover | box-shadow | "0 12px 36px rgba(212,175,55,.4)" |
|
||||
| .site-form .actions a | color | var(--paper-faint) |
|
||||
| .site-form .actions a | font-weight | "400" |
|
||||
| .site-form .actions a | text-decoration | none |
|
||||
| .site-form .actions a | font-size | "0.85rem" |
|
||||
| .site-form .actions a | letter-spacing | "0.08em" |
|
||||
| .site-form .actions a:hover | color | var(--gold) |
|
||||
| .flash.err | color | var(--danger) |
|
||||
| .flash.err | font-weight | "500" |
|
||||
|
||||
*`widgets`*
|
||||
|
||||
## css
|
||||
|
||||
**v = > vars**
|
||||
**m = > motion**
|
||||
**l = > layout**
|
||||
**r = > responsive**
|
||||
**c = > chrome**
|
||||
**w = > widgets**
|
||||
**css_v = > web.make_style name="vars" table=v**
|
||||
**css_m = > web.make_style name="motion" table=m**
|
||||
**css_l = > web.make_style name="layout" table=l**
|
||||
**css_r = > web.make_style name="responsive" table=r**
|
||||
**css_c = > web.make_style name="chrome" table=c**
|
||||
**css_w = > web.make_style name="widgets" table=w**
|
||||
|
||||
`parts` =
|
||||
|
||||
| css |
|
||||
|-----|
|
||||
| `css_v` |
|
||||
| `css_m` |
|
||||
| `css_l` |
|
||||
| `css_r` |
|
||||
| `css_c` |
|
||||
| `css_w` |
|
||||
|
||||
**out = > text.str_join xs=`parts` sep=""**
|
||||
*out*
|
||||
@@ -0,0 +1,14 @@
|
||||
# web-spa-app
|
||||
|
||||
Marqdo **native SPA**: list → detail → edit with client routes + `scope=memory` store. Zero author JS.
|
||||
|
||||
## Run
|
||||
|
||||
```bash
|
||||
marqdo wasm build -o examples/web-spa-app/static
|
||||
cd examples/web-spa-app
|
||||
marqdo run index.mq.md
|
||||
# http://127.0.0.1:18093
|
||||
```
|
||||
|
||||
Design: [ext-web-spa.md](../../doc/design/ext-web-spa.md).
|
||||
@@ -0,0 +1,23 @@
|
||||
---
|
||||
title: web-spa-app
|
||||
description: Native Marqdo SPA — list/detail/edit via WASM client routes + memory store
|
||||
import web:ext/web/web.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Full-page client app (zero author JS). Build assets first:
|
||||
|
||||
```
|
||||
marqdo wasm build -o examples/web-spa-app/static
|
||||
```
|
||||
|
||||
**`embed` = > web.client_embed bridge="/static/marqdo-bridge.js" wasm="/static/marqdo_wasm.wasm" source="/static/client.mq.md" boot=True**
|
||||
|
||||
**`intro` = "<nav class='spa-nav'><button type='button' id='nav-list'>Items</button> <button type='button' id='nav-new'>New</button></nav><p id='title' class='spa-title'>Items</p><section id='view-list'><ul id='items'></ul><p class='hint'>Click an item for detail.</p></section><section id='view-detail' hidden><p id='detail-body'></p><p><button type='button' id='btn-edit'>Edit</button> <button type='button' id='btn-back'>Back</button></p></section><section id='view-edit' hidden><label>Title <input id='edit-title' /></label><p><button type='button' id='btn-save'>Save</button> <button type='button' id='btn-cancel'>Cancel</button></p></section><pre id='log'></pre>" + embed**
|
||||
|
||||
**page = > web.page title="Marqdo SPA" intro=intro layout="bare"**
|
||||
**app = > web.app page=page host="127.0.0.1" port=18093**
|
||||
**app = > app.static dir="static" mount="/static"**
|
||||
**app = > app.redirect from="/item" to="/" permanent=False**
|
||||
> `app`.listen
|
||||
@@ -0,0 +1,174 @@
|
||||
---
|
||||
title: spa client
|
||||
description: routes table + memory store; list / detail / edit
|
||||
import browser:lib/browser.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import text:lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Routes (documentation + titles). Runtime switches panels by `path`.
|
||||
|
||||
`routes` =
|
||||
|
||||
| @ | 路径 | 面板 | 标题 |
|
||||
|---|------|------|------|
|
||||
| 1 | / | #view-list | Items |
|
||||
| 2 | /item | #view-detail | Detail |
|
||||
| 3 | /edit | #view-edit | Edit |
|
||||
|
||||
**`path` = "/"**
|
||||
**`cur_id` = ""**
|
||||
**`items` = "Alpha\nBeta"**
|
||||
|
||||
`wire` =
|
||||
|
||||
| @ | 选择器 | 事件 | 调用 | 委托 | 值选择器 |
|
||||
|---|--------|------|------|------|----------|
|
||||
| 1 | "#nav-list" | click | go_list | | |
|
||||
| 2 | "#nav-new" | click | go_new | | |
|
||||
| 3 | "#items" | click | open_item | "li[data-id]" | |
|
||||
| 4 | "#btn-edit" | click | go_edit | | |
|
||||
| 5 | "#btn-back" | click | go_list | | |
|
||||
| 6 | "#btn-save" | click | save_item | | "#edit-title" |
|
||||
| 7 | "#btn-cancel" | click | go_list | | |
|
||||
| 8 | "window" | popstate | on_pop | | |
|
||||
|
||||
`seed` =
|
||||
|
||||
| op | key | value | scope |
|
||||
|----|-----|-------|-------|
|
||||
| set | spa-items | `items` | memory |
|
||||
|
||||
**`w` = > table.put in=None at="wire" value=wire**
|
||||
**`s` = > browser.storage spec=seed**
|
||||
**`boot` = > browser.merge a=w b=s**
|
||||
**`ready` = > browser.set_text sel="#log" text="spa ready — click Items"**
|
||||
*> browser.merge a=boot b=ready*
|
||||
|
||||
## on_pop
|
||||
+ `path`=""
|
||||
|
||||
1. `path` != ""
|
||||
**`path` = path**
|
||||
2. *
|
||||
****
|
||||
*> spa_render*
|
||||
|
||||
## go_list
|
||||
**`path` = "/"**
|
||||
**`cur_id` = ""**
|
||||
*> spa_render*
|
||||
|
||||
## go_new
|
||||
**`path` = "/edit"**
|
||||
**`cur_id` = ""**
|
||||
*> spa_render*
|
||||
|
||||
## go_edit
|
||||
**`path` = "/edit"**
|
||||
*> spa_render*
|
||||
|
||||
## open_item
|
||||
+ `data_id`=""
|
||||
|
||||
1. `data_id` != ""
|
||||
**`cur_id` = data_id**
|
||||
**`path` = "/item"**
|
||||
*> spa_render*
|
||||
2. *
|
||||
****
|
||||
|
||||
## save_item
|
||||
+ `value`=""
|
||||
|
||||
1. `value` != ""
|
||||
1. `cur_id` != ""
|
||||
**`parts` = > text.str_split s=items sep="\n"**
|
||||
**`next` = ""**
|
||||
- [item](parts)
|
||||
1. `item` != ""
|
||||
1. `item` == `cur_id`
|
||||
1. `next` == ""
|
||||
**`next` = value**
|
||||
2. *
|
||||
**`next` = next + "\n" + value**
|
||||
2. *
|
||||
1. `next` == ""
|
||||
**`next` = item**
|
||||
2. *
|
||||
**`next` = next + "\n" + item**
|
||||
**`items` = next**
|
||||
**`cur_id` = value**
|
||||
2. *
|
||||
1. `items` == ""
|
||||
**`items` = value**
|
||||
2. *
|
||||
**`items` = items + "\n" + value**
|
||||
**`cur_id` = value**
|
||||
**`path` = "/item"**
|
||||
*> spa_render*
|
||||
2. *
|
||||
*> browser.set_text sel="#log" text="title required"*
|
||||
|
||||
## spa_render
|
||||
*> spa_paint*
|
||||
|
||||
## spa_paint
|
||||
**`hide` = > table.put in=None at="hidden" value=""**
|
||||
**`show` = > table.put in=None at="hidden" value=False**
|
||||
1. `path` == "/item"
|
||||
`attrs` =
|
||||
|
||||
| #view-detail | #view-list | #view-edit |
|
||||
|--------------|------------|------------|
|
||||
| `show` | `hide` | `hide` |
|
||||
**`title` = "Detail"**
|
||||
**`body` = cur_id**
|
||||
2. *
|
||||
1. `path` == "/edit"
|
||||
`attrs` =
|
||||
|
||||
| #view-edit | #view-list | #view-detail |
|
||||
|------------|------------|--------------|
|
||||
| `show` | `hide` | `hide` |
|
||||
**`title` = "Edit"**
|
||||
**`body` = cur_id**
|
||||
2. *
|
||||
`attrs` =
|
||||
|
||||
| #view-list | #view-detail | #view-edit |
|
||||
|------------|--------------|------------|
|
||||
| `show` | `hide` | `hide` |
|
||||
**`title` = "Items"**
|
||||
**`body` = ""**
|
||||
**`parts` = > text.str_split s=items sep="\n"**
|
||||
**`html` = ""**
|
||||
- [item](parts)
|
||||
1. `item` != ""
|
||||
**`html` = html + "<li data-id=\"" + item + "\">" + item + "</li>"**
|
||||
`persist` =
|
||||
|
||||
| op | key | value | scope |
|
||||
|----|-----|-------|-------|
|
||||
| set | spa-items | `items` | memory |
|
||||
|
||||
**`t` = > browser.set_text sel="#title" text=title**
|
||||
**`a` = > browser.wrap key="set_attr" value=attrs**
|
||||
**`ret` = > browser.merge a=t b=a**
|
||||
**`list` = > browser.set_html sel="#items" html=html**
|
||||
**`ret` = > browser.merge a=ret b=list**
|
||||
**`d` = > browser.set_text sel="#detail-body" text=body**
|
||||
**`ret` = > browser.merge a=ret b=d**
|
||||
1. `path` == "/edit"
|
||||
**`v` = > browser.set_value sel="#edit-title" value=cur_id**
|
||||
**`ret` = > browser.merge a=ret b=v**
|
||||
2. *
|
||||
****
|
||||
**`nav` = > browser.spa_goto url=path**
|
||||
**`ret` = > browser.merge a=ret b=nav**
|
||||
**`log` = > browser.set_text sel="#log" text=path**
|
||||
**`ret` = > browser.merge a=ret b=log**
|
||||
**`sav` = > browser.storage spec=persist**
|
||||
*> browser.merge a=ret b=sav*
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: web-tenant-saas demo
|
||||
description: Dual-tenant isolation via ?t= query + tenant_scope JSON API.
|
||||
import web:ext/web/web.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`items_schema` =
|
||||
|
||||
| name | type | nullable |
|
||||
|------|------|----------|
|
||||
| id | integer | false |
|
||||
| title | text | false |
|
||||
| tenant_id | text | false |
|
||||
|
||||
`api` =
|
||||
|
||||
| path | method | table | order | limit | tenant_scope |
|
||||
|------|--------|-------|-------|-------|--------------|
|
||||
| api/items | GET | items | id | 50 | true |
|
||||
|
||||
**db = > web.db url="sqlite:data/tenant-saas.db"**
|
||||
> `db`.init name=items fields=`items_schema`
|
||||
> `db`.exec sql="DELETE FROM items"
|
||||
> `db`.exec sql="INSERT INTO items(title, tenant_id) VALUES('Acme note','acme')"
|
||||
> `db`.exec sql="INSERT INTO items(title, tenant_id) VALUES('Beta note','beta')"
|
||||
|
||||
**page = > web.page title="Tenant SaaS" intro="<p>Try <a href='/api/items?t=acme'>/api/items?t=acme</a> vs <a href='/api/items?t=beta'>/api/items?t=beta</a>.</p>"**
|
||||
**app = > web.app page=`page` db=`db` host="127.0.0.1" port=18092 admin=False**
|
||||
**app = > `app`.tenant mode="path" param="t" default_scope=False**
|
||||
**app = > `app`.configure json=`api`**
|
||||
> `app`.listen
|
||||
@@ -0,0 +1,12 @@
|
||||
---
|
||||
title: web-ws-room demo
|
||||
description: Dynamic room WS with presence (G-WS1/2 bag). Open / and connect via bridge or wscat.
|
||||
import web:ext/web/web.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
**page = > web.page title="WS room" intro="<p class='lede'>Chat room <code>lobby</code> via <code>/chat/lobby</code>. Presence joins <code>chat.room.lobby.presence</code>.</p><pre id='log'></pre>"**
|
||||
**app = > web.app page=`page` host="127.0.0.1" port=18091 admin=False**
|
||||
**app = > `app`.route_ws path="/chat/{id}" mode="room" room_key="chat.room.{id}" presence=True**
|
||||
> `app`.listen
|
||||
@@ -0,0 +1 @@
|
||||
1.1.0
|
||||
+184
-8
@@ -38,6 +38,18 @@ them into CSS — 样式即数据、装配即函数.
|
||||
> ensure_plugin
|
||||
*> web_style name=`name` table=`table` strict=`strict`*
|
||||
|
||||
## make_intro
|
||||
+ `table`
|
||||
|
||||
Assemble an intro bind table (`|属性|值|样式|` / `|front|back|style|`) into an
|
||||
HTML fragment for `.main-intro`. Same slot vocabulary as `compose_intro`
|
||||
(`kicker`/`title`/`lede`/`claim`/`step`, plus ZH aliases). The `样式` column is
|
||||
treated as a class name only here — prefer `page.compose_intro` when styles
|
||||
should resolve from `shell.*` tables into `styles_css`.
|
||||
|
||||
> ensure_plugin
|
||||
*> web_intro table=`table`*
|
||||
|
||||
## make_images
|
||||
+ `table`
|
||||
|
||||
@@ -230,6 +242,32 @@ Assemble main from a bind table (`|属性|值|样式|` or `|front|back|css|`).
|
||||
|
||||
*> web_compose_main page=`self` main=`main`*
|
||||
|
||||
## compose_list
|
||||
+ `main`
|
||||
+ `query`=None
|
||||
+ `order`=""
|
||||
+ `target`=""
|
||||
|
||||
Secondary list bind (e.g. comments on a detail page). Same bind shape as compose_main.
|
||||
Optional query supports route param placeholders; optional target injects into an intro element id.
|
||||
|
||||
*> web_compose_list page=`self` main=`main` query=`query` order=`order` target=`target`*
|
||||
|
||||
## compose_intro
|
||||
+ `intro`
|
||||
|
||||
Assemble page intro from the same bind shape as `compose_main`
|
||||
(`|属性|值|样式|` / `|front|back|style|`). `值` is literal copy (light
|
||||
`[label](url)` / `**bold**`); `样式` resolves `shell.*` named
|
||||
tables into `styles_css` like `card_title`. Consecutive `claim` / `step` rows
|
||||
group into `.claim` / `.steps`. Slot aliases: `kicker`/`眉题`, `title`/`标题`,
|
||||
`lede`/`导语`, `claim`/`标签`, `step`/`步骤`, plus `mount`/`插槽` and
|
||||
`html`/`原文`. Replaces string `intro=` HTML. In `.mq.md` table cells, avoid
|
||||
inline `` `code` `` — backtick refs are Marqdo variables; quote long prose
|
||||
and use plain filenames or `[label](url)` links instead.
|
||||
|
||||
*> web_compose_intro page=`self` intro=`intro`*
|
||||
|
||||
## query
|
||||
+ `query`
|
||||
|
||||
@@ -318,6 +356,50 @@ Embed a form into the page main slot. Optional `target` / `form_slot` (CSS id, e
|
||||
|
||||
*> web_compose_form page=`self` form=`form` id=`id` target=`target`*
|
||||
|
||||
## compose_form_load
|
||||
+ `table`
|
||||
+ `id_param`="id"
|
||||
|
||||
Prefill the composed form from DB using route/query `id` (desk edit pages).
|
||||
|
||||
*> web_compose_form_load page=`self` table=`table` id_param=`id_param`*
|
||||
|
||||
## compose_auth_form
|
||||
+ `action`
|
||||
+ `submit`=""
|
||||
+ `form_id`=""
|
||||
+ `err_id`=""
|
||||
+ `target`=None
|
||||
+ `next`=""
|
||||
+ `kind`=""
|
||||
|
||||
Progressive-enhancement login/register form: server injects `_csrf` / `next`,
|
||||
re-renders the same branded page on failure. No author JS.
|
||||
|
||||
*> web_compose_auth_form page=`self` action=`action` submit=`submit` form_id=`form_id` err_id=`err_id` target=`target` next=`next` kind=`kind`*
|
||||
|
||||
## compose_nav_brand
|
||||
+ `title`=""
|
||||
+ `href`="/"
|
||||
+ `logo`=""
|
||||
+ `logo_light`=""
|
||||
+ `theme_key`="mq-theme"
|
||||
|
||||
SSR topnav brand (logo + title), theme toggle, and drawer button. Interactive
|
||||
behavior stays in `client.mq.md` via `compose_client` / `client_embed`.
|
||||
|
||||
*> web_compose_nav_brand page=`self` title=`title` href=`href` logo=`logo` logo_light=`logo_light` theme_key=`theme_key`*
|
||||
|
||||
## compose_client
|
||||
+ `source`
|
||||
+ `bridge`="/static/marqdo-bridge.js"
|
||||
+ `wasm`="/static/marqdo_wasm.wasm"
|
||||
|
||||
Stamp `page.client` so render injects official bridge auto-mount (`data-mq-wasm` /
|
||||
`data-mq-source-url`). Build with `marqdo wasm build -o static` first.
|
||||
|
||||
*> web_compose_client page=`self` source=`source` bridge=`bridge` wasm=`wasm`*
|
||||
|
||||
## render
|
||||
+ `db`=None
|
||||
|
||||
@@ -583,6 +665,15 @@ Field table + rules table; submit writes through `# db`.
|
||||
|
||||
*> web_form_rules form=`self` rules=`rules`*
|
||||
|
||||
## labels
|
||||
+ `submit`="Submit"
|
||||
+ `cancel`="cancel"
|
||||
+ `cancel_href`=""
|
||||
|
||||
Localized submit / cancel copy for rendered forms.
|
||||
|
||||
*> web_form_labels form=`self` submit=`submit` cancel=`cancel` cancel_href=`cancel_href`*
|
||||
|
||||
## validate
|
||||
+ `rules`=None
|
||||
+ `data`
|
||||
@@ -616,7 +707,7 @@ Field table + rules table; submit writes through `# db`.
|
||||
+ `layout`=None
|
||||
+ `asset_version`=None
|
||||
|
||||
Construct an app. `admin=True` mounts the built-in CRUD UI under `admin_prefix` (default `/admin`). When `admin=False`, that prefix is not reserved — you may `route` your own pages there. Optional `login_redirect` / `logout_redirect` override post-auth landing. Optional `shell_css` / `layout` / `asset_version` become defaults for pages that do not set their own (see `page.shell_css` / `page.layout` / `page.asset_version`).
|
||||
Construct an app. `admin=True` mounts the built-in **table browser** (not a CMS) under `admin_prefix` (default `/admin`). When `admin=False`, that prefix is not reserved and is not auto-gated — declare your own `route` + `gate` desk. Optional `login_redirect` / `logout_redirect` override post-auth landing. Optional `shell_css` / `layout` / `asset_version` become defaults for pages that do not set their own (see `page.shell_css` / `page.layout` / `page.asset_version`).
|
||||
|
||||
> ensure_plugin
|
||||
*> web_app_new page=`page` db=`db` admin=`admin` host=`host` port=`port` admin_prefix=`admin_prefix` login_redirect=`login_redirect` logout_redirect=`logout_redirect` shell_css=`shell_css` layout=`layout` asset_version=`asset_version`*
|
||||
@@ -706,10 +797,14 @@ Serve `/`, routed pages, `/_part/{id}` (home) and `{path}/_part/{id}` (routes),
|
||||
+ `path`
|
||||
+ `echo`=True
|
||||
+ `mode`=None
|
||||
+ `room_key`=None
|
||||
+ `on_message`=None
|
||||
+ `presence`=False
|
||||
+ `require_auth`=None
|
||||
|
||||
Register a WebSocket endpoint at `path` (e.g. `/live`). `mode` is `echo` (default), `broadcast` (fan-out text to all sockets on this path), or `drain`. Legacy `echo=False` maps to `drain`. Connect from a client with `web.ws.connect`.
|
||||
Register a WebSocket endpoint at `path` (e.g. `/live` or `/chat/{id}`). `mode` is `echo` (default), `broadcast` (fan-out text to all sockets on this path), `room` (named room via `room_key`, supports `{id}` from the path), or `drain`. Legacy `echo=False` maps to `drain`. `on_message` is an optional `lib.member` hook (G-WS2): called before fan-out with `message`/`room`/`user`; return `{skip:true}` to drop or `{message:…}` to rewrite. `presence=True` also joins `room.presence` and emits join/leave JSON. Stateful `broadcast` and `room` endpoints require a logged-in session by default; set `require_auth=False` only for intentionally public live feeds. Browser handshakes are same-origin. Connect from a client with `web.ws.connect`.
|
||||
|
||||
*> web_app_route_ws app=`self` path=`path` echo=`echo` mode=`mode`*
|
||||
*> web_app_route_ws app=`self` path=`path` echo=`echo` mode=`mode` room_key=`room_key` on_message=`on_message` presence=`presence` require_auth=`require_auth`*
|
||||
|
||||
## auth
|
||||
+ `users`
|
||||
@@ -718,21 +813,59 @@ Register a WebSocket endpoint at `path` (e.g. `/live`). `mode` is `echo` (defaul
|
||||
+ `login_redirect`=None
|
||||
+ `logout_redirect`=None
|
||||
+ `login_path`=None
|
||||
+ `register`=False
|
||||
+ `register_path`=/register
|
||||
+ `default_role`="member"
|
||||
+ `session_url`=None
|
||||
|
||||
Keep the app's `admin=True`, and gate `{admin_prefix}` (segment-boundary prefix) behind a login page (default `/admin`). Unauthenticated requests redirect to `login_path` (default `{admin_prefix}/login`, auto-excluded). Does not match `/admin-publish`-style siblings.
|
||||
Keep the app's `admin=True`, and gate `{admin_prefix}` (segment-boundary prefix) behind a login page (default `/admin`). Unauthenticated requests redirect to `login_path` (default `{admin_prefix}/login`, auto-excluded). Does not match `/admin-publish`-style siblings. With `register=True` and `enable_rbac`, exposes `register_path` (writes `web_users` + default role). Optional `session_url` (`redis://…` / `rediss://…`) stores sessions in Redis separately from the Postgres/SQLite app DB; omit to keep `_marqdo_sessions` (or in-memory). With OIDC, do not set `logout_redirect` to a login path (it would bounce to the IdP); conflicting values fall back to `/`.
|
||||
|
||||
*> web_app_auth app=`self` users=`users` session_ttl=`session_ttl` admin_prefix=`admin_prefix` login_redirect=`login_redirect` logout_redirect=`logout_redirect` login_path=`login_path`*
|
||||
*> web_app_auth app=`self` users=`users` session_ttl=`session_ttl` admin_prefix=`admin_prefix` login_redirect=`login_redirect` logout_redirect=`logout_redirect` login_path=`login_path` register=`register` register_path=`register_path` default_role=`default_role` session_url=`session_url`*
|
||||
|
||||
## oidc
|
||||
+ `issuer`=None
|
||||
+ `client_id`
|
||||
+ `client_secret`
|
||||
+ `redirect_uri`
|
||||
+ `scopes`="openid profile email"
|
||||
+ `callback_path`=None
|
||||
+ `authorize_url`=None
|
||||
+ `token_url`=None
|
||||
+ `userinfo_url`=None
|
||||
|
||||
Enable OAuth 2.0 authorization-code / OIDC login (e.g. CFLMY IdP). When set, `login_path` / `register_path` / desk login redirect to the IdP; the `redirect_uri` callback exchanges the code and opens a local session. userinfo `is_admin` / `admin_role` map to local role `admin`; otherwise `default_role`. Secrets stay server-side; PKCE S256 is always sent.
|
||||
|
||||
*> web_app_oidc app=`self` issuer=`issuer` client_id=`client_id` client_secret=`client_secret` redirect_uri=`redirect_uri` scopes=`scopes` callback_path=`callback_path` authorize_url=`authorize_url` token_url=`token_url` userinfo_url=`userinfo_url`*
|
||||
|
||||
## gate
|
||||
+ `path`
|
||||
+ `roles`=admin
|
||||
+ `permissions`=""
|
||||
+ `match`=prefix
|
||||
+ `on_deny`=forbid
|
||||
+ `exclude`=None
|
||||
|
||||
Require one of `roles` (CSV) for `path`. `match=prefix` uses segment boundaries; `exact` is equality. Trailing `*` on `path` means prefix. `on_deny=redirect` sends visitors to `login_path` (with `?next=`); `forbid` returns 403. `exclude` is CSV or list of open paths.
|
||||
Require access for `path`. Prefer `permissions` (CSV of `resource:action` codes such as `desk:access`); when non-empty, authorization uses the session permission set. Otherwise require one of `roles` (legacy). `match=prefix` uses segment boundaries; `exact` is equality. Trailing `*` on `path` means prefix. `on_deny=redirect` sends visitors to `login_path` (with `?next=`); `forbid` returns 403. `exclude` is CSV or list of open paths.
|
||||
|
||||
*> web_app_gate app=`self` path=`path` roles=`roles` match=`match` on_deny=`on_deny` exclude=`exclude`*
|
||||
*> web_app_gate app=`self` path=`path` roles=`roles` permissions=`permissions` match=`match` on_deny=`on_deny` exclude=`exclude`*
|
||||
|
||||
## enable_rbac
|
||||
+ `catalog`=None
|
||||
+ `desk`=False
|
||||
|
||||
Enable database-backed RBAC (role ⊥ permission). On listen, ensures `web_permissions` / `web_roles` / `web_role_permissions` / `web_users` / `web_user_roles` and seeds system roles `superadmin` and `member`. See `doc/design/ext-web-rbac.md`. By default **no** `/_rbac/*` routes; set `desk=True` to mount the API and `GET /_rbac/desk` (needs `roles:manage`). Permission gates work either way.
|
||||
|
||||
*> web_app_rbac app=`self` catalog=`catalog` desk=`desk`*
|
||||
|
||||
## tenant
|
||||
+ `mode`
|
||||
+ `param`=None
|
||||
+ `column`=tenant_id
|
||||
+ `default_scope`=False
|
||||
|
||||
Enable multi-tenant resolution: `mode` is `path` (query/`/t/{id}/…`), `subdomain`, or `header`. `param` is the path/query key or header name. When `default_scope=True`, JSON routes and form inserts auto-filter/stamp `column` (default `tenant_id`). Per-route override: JSON table column `tenant_scope` / `租户作用域`.
|
||||
|
||||
*> web_app_tenant app=`self` mode=`mode` param=`param` column=`column` default_scope=`default_scope`*
|
||||
|
||||
## gallery
|
||||
+ `path`=/gallery
|
||||
@@ -816,6 +949,49 @@ Mount `GET path` to stream an object. Path must capture `key` (use `{*key}` for
|
||||
|
||||
*> web_app_download app=`self` path=`path` storage=`storage` disposition=`disposition`*
|
||||
|
||||
# rbac
|
||||
|
||||
Offline helpers for role ⊥ permission. Prefer `app.enable_rbac` + gates for HTTP; use these for scripts/tests.
|
||||
|
||||
## can
|
||||
+ `permissions`
|
||||
+ `needed`
|
||||
|
||||
Return `{ok, allowed}` — whether held permission CSV includes any of `needed` (CSV). Held `*` allows all.
|
||||
|
||||
> ensure_plugin
|
||||
*> web_rbac_can permissions=`permissions` needed=`needed`*
|
||||
|
||||
## assign_role
|
||||
+ `url`
|
||||
+ `username`
|
||||
+ `role`
|
||||
|
||||
Bind `username` (in `web_users`) to role name.
|
||||
|
||||
> ensure_plugin
|
||||
*> web_rbac_assign_role url=`url` username=`username` role=`role`*
|
||||
|
||||
## create_role
|
||||
+ `url`
|
||||
+ `name`
|
||||
|
||||
Create a non-system role; returns `{ok, id, name}`.
|
||||
|
||||
> ensure_plugin
|
||||
*> web_rbac_create_role url=`url` name=`name`*
|
||||
|
||||
## set_role_permissions
|
||||
+ `url`
|
||||
+ `role`
|
||||
+ `permissions`
|
||||
+ `grantable`=""
|
||||
|
||||
Replace permissions on a non-system role (CSV). `grantable` restricts grants (anti-escalation); empty = full catalog.
|
||||
|
||||
> ensure_plugin
|
||||
*> web_rbac_set_role_permissions url=`url` role=`role` permissions=`permissions` grantable=`grantable`*
|
||||
|
||||
# auth
|
||||
+ `users`
|
||||
+ `session_ttl`=3600
|
||||
@@ -985,7 +1161,7 @@ WebSocket client helper.
|
||||
+ `message`=""
|
||||
+ `headers`=None
|
||||
|
||||
Single request–response: connect to `url`, send `message`, collect all server text replies, close. Returns `{ok, messages}`.
|
||||
Single request–response: connect to `url`, send `message`, collect up to 256 server text replies (each up to 1 MiB), close. Transport errors and timeouts return `{ok:false, error}` instead of looking like an empty successful reply.
|
||||
|
||||
**timeout = [timeout_sec](self)**
|
||||
*> web_ws_connect url=`url` message=`message` headers=`headers` timeout_sec=`timeout`*
|
||||
+183
-9
@@ -35,6 +35,16 @@ import table:lib/table.mq.md
|
||||
> 确保插件
|
||||
*> web_style name=`名` table=`表` strict=`严格`*
|
||||
|
||||
## 引言装配
|
||||
+ `表`
|
||||
|
||||
把引言绑定表(`|属性|值|样式|` / `|front|back|style|`)装配成 `.main-intro` HTML 片段。
|
||||
槽位与 `页面.引言装配` 相同。此处 `样式` 只当 class 名;要从 `shell.*` 解析进
|
||||
`styles_css` 请用 `页面.引言装配`。
|
||||
|
||||
> 确保插件
|
||||
*> web_intro table=`表`*
|
||||
|
||||
## 图片装配
|
||||
+ `表`
|
||||
|
||||
@@ -217,6 +227,31 @@ import table:lib/table.mq.md
|
||||
|
||||
*> web_compose_main page=`self` main=`主体`*
|
||||
|
||||
## 列表装配
|
||||
+ `主体`
|
||||
+ `条件`=None
|
||||
+ `排序`=""
|
||||
+ `插槽`=""
|
||||
|
||||
详情页副绑定(如评论列表)。绑定表形同 `主体装配`;`条件` 支持 `{参数}`;
|
||||
可选 `插槽`(元素 id)把列表注入引言 HTML(同表单插槽)。
|
||||
`插槽=rail` / `轨` / `新闻轨` 时渲染为右侧 `aside.side-rail`(量子新闻轨),并为 body 加上 `has-rail`。
|
||||
|
||||
*> web_compose_list page=`self` main=`主体` query=`条件` order=`排序` target=`插槽`*
|
||||
|
||||
## 引言装配
|
||||
+ `引言`
|
||||
|
||||
与 `主体装配` 同一绑定表形(`|属性|值|样式|`)。`值` 为文案(支持轻量
|
||||
`[文](url)` / `**粗**`);`样式` 解析 `shell.*` 具名表写入
|
||||
`styles_css`(同 `card_title`)。连续 `claim`/`标签`、`step`/`步骤` 会分组。
|
||||
槽位别名:`kicker`/`眉题`、`title`/`标题`、`lede`/`导语`、`claim`/`标签`、
|
||||
`step`/`步骤`,以及 `mount`/`插槽`、`html`/`原文`。用于替代字符串 `引言=` HTML。
|
||||
在 `.mq.md` 表单元格里请勿写行内 `` `code` ``(反引号是 Marqdo 变量语法);
|
||||
长文加引号,文件名用纯文本或 `[文](url)`。
|
||||
|
||||
*> web_compose_intro page=`self` intro=`引言`*
|
||||
|
||||
## 查询条件
|
||||
+ `条件`
|
||||
|
||||
@@ -300,6 +335,51 @@ SEO / OpenGraph 元数据表(`|键|值|`)。如 `title`、`description`、`c
|
||||
|
||||
*> web_compose_form page=`self` form=`表单` id=`id` target=`表单插槽`*
|
||||
|
||||
## 表单载入
|
||||
+ `表`
|
||||
+ `id参数`="id"
|
||||
|
||||
编辑页:按路由/查询参数中的 id 从数据库预填已装配表单,无需作者 JS 拉行。
|
||||
|
||||
*> web_compose_form_load page=`self` table=`表` id_param=`id参数`*
|
||||
|
||||
## 鉴权表单
|
||||
+ `动作`
|
||||
+ `提交`=""
|
||||
+ `表单id`=""
|
||||
+ `错误id`=""
|
||||
+ `表单插槽`=None
|
||||
+ `回跳`=""
|
||||
+ `种类`=""
|
||||
|
||||
装配原生登录/注册表单(隐藏 `_csrf` / `next`,失败时服务端回渲同一页 flash)。
|
||||
`动作` 为 POST 路径(如 `/login`、`/desk/login`、`/register`)。可选 `表单插槽`
|
||||
把表单注入引言 HTML;`回跳` 为默认 `next`(写作台登录用 `/desk`)。
|
||||
无需站点业务 JS。
|
||||
|
||||
*> web_compose_auth_form page=`self` action=`动作` submit=`提交` form_id=`表单id` err_id=`错误id` target=`表单插槽` next=`回跳` kind=`种类`*
|
||||
|
||||
## 导航品牌
|
||||
+ `标题`=""
|
||||
+ `链接`="/"
|
||||
+ `标志`=""
|
||||
+ `浅色标志`=""
|
||||
+ `主题键`="mq-theme"
|
||||
|
||||
SSR 顶栏刊名 Logo、主题切换钮与目录抽屉钮。交互写在 `client.mq.md`,配合 `客户端`。
|
||||
|
||||
*> web_compose_nav_brand page=`self` title=`标题` href=`链接` logo=`标志` logo_light=`浅色标志` theme_key=`主题键`*
|
||||
|
||||
## 客户端
|
||||
+ `源`
|
||||
+ `桥`="/static/marqdo-bridge.js"
|
||||
+ `wasm`="/static/marqdo_wasm.wasm"
|
||||
|
||||
写入 `page.client`,渲染时注入官方 bridge 自启(`data-mq-wasm` / `data-mq-source-url`)。
|
||||
先 `marqdo wasm build -o public`(或站点 static 目录)。
|
||||
|
||||
*> web_compose_client page=`self` source=`源` bridge=`桥` wasm=`wasm`*
|
||||
|
||||
## 渲染
|
||||
+ `数据库`=None
|
||||
|
||||
@@ -543,7 +623,7 @@ SEO / OpenGraph 元数据表(`|键|值|`)。如 `title`、`description`、`c
|
||||
+ `动作`=插入
|
||||
+ `id`=None
|
||||
|
||||
字段表 + 校验表;提交经 `# 数据库` 写入。
|
||||
字段表 + 校验表;提交经 `# 数据库` 写入。`动作` 为 `插入` / `更新` / `删除`(英:`insert` / `update` / `delete`)。删除按 `id` 删行,字段表可只读展示上下文。站点后台用「列表 + 表单页」声明即可,不必改插件。
|
||||
|
||||
> 确保插件
|
||||
*> web_form_new table=`表` action=`动作` id=`id`*
|
||||
@@ -558,6 +638,15 @@ SEO / OpenGraph 元数据表(`|键|值|`)。如 `title`、`description`、`c
|
||||
|
||||
*> web_form_rules form=`self` rules=`规则`*
|
||||
|
||||
## 文案
|
||||
+ `提交`="提交"
|
||||
+ `取消`="取消"
|
||||
+ `取消链接`=""
|
||||
|
||||
表单提交钮 / 取消链接文案(默认英文 Submit/cancel 由渲染层回退)。
|
||||
|
||||
*> web_form_labels form=`self` submit=`提交` cancel=`取消` cancel_href=`取消链接`*
|
||||
|
||||
## 校验
|
||||
+ `规则`=None
|
||||
+ `数据`
|
||||
@@ -591,7 +680,7 @@ SEO / OpenGraph 元数据表(`|键|值|`)。如 `title`、`description`、`c
|
||||
+ `布局`=None
|
||||
+ `资源版本`=None
|
||||
|
||||
构造应用。`后台=真` 时在 `后台前缀`(默认 `/admin`)挂载内置 CRUD。`后台=假` 时该前缀不再保留,可自行 `路由` 到 `/admin…`。可选 `登录回跳` / `登出回跳`。可选 `壳样式` / `布局` / `资源版本` 作为未自设页面的默认(见 `页面.壳样式` / `页面.布局` / `页面.资源版本`)。
|
||||
构造应用。`后台=真` 时在 `后台前缀`(默认 `/admin`)挂载**内置表浏览器**(不是 CMS)。`后台=假` 时该前缀不保留、不自动门禁,可自行 `路由` + `门禁` 做写作台。可选 `登录回跳` / `登出回跳`。可选 `壳样式` / `布局` / `资源版本` 作为未自设页面的默认(见 `页面.壳样式` / `页面.布局` / `页面.资源版本`)。
|
||||
|
||||
> 确保插件
|
||||
*> web_app_new page=`页面` db=`数据库` admin=`后台` host=`主机` port=`端口` admin_prefix=`后台前缀` login_redirect=`登录回跳` logout_redirect=`登出回跳` shell_css=`壳样式` layout=`布局` asset_version=`资源版本`*
|
||||
@@ -676,10 +765,14 @@ SEO / OpenGraph 元数据表(`|键|值|`)。如 `title`、`description`、`c
|
||||
+ `路径`
|
||||
+ `回显`=真
|
||||
+ `模式`=None
|
||||
+ `房间`=None
|
||||
+ `消息钩子`=None
|
||||
+ `在场`=假
|
||||
+ `需要登录`=None
|
||||
|
||||
在 `路径`(如 `/live`)注册 WebSocket 端点。`模式` 为 `echo`(默认)、`broadcast`(同路径全体广播)或 `drain`。旧参数 `回显=假` 等价于 `drain`。客户端用 `网页.实时` 的 `连接` 接入。
|
||||
在 `路径`(如 `/live` 或 `/chat/{id}`)注册 WebSocket。`模式` 为 `echo`(默认)、`broadcast`、`room`(需 `房间` 键,可含 `{id}`)或 `drain`。旧参数 `回显=假` 等价于 `drain`。`消息钩子` 为可选 `库.成员`(G-WS2):广播前调用,入参含 `message`/`room`/`user`;返回 `{skip:真}` 丢弃或 `{message:…}` 改写。`在场=真` 时另进 `房间.presence` 并推送 join/leave。有状态的 `broadcast` 与 `room` 端点默认需登录会话;仅对有意公开的直播流设 `需要登录=假`。浏览器握手同源。客户端用 `网页.实时` 的 `连接` 接入。
|
||||
|
||||
*> web_app_route_ws app=`self` path=`路径` echo=`回显` mode=`模式`*
|
||||
*> web_app_route_ws app=`self` path=`路径` echo=`回显` mode=`模式` room_key=`房间` on_message=`消息钩子` presence=`在场` require_auth=`需要登录`*
|
||||
|
||||
## 鉴权
|
||||
+ `用户表`
|
||||
@@ -688,21 +781,59 @@ SEO / OpenGraph 元数据表(`|键|值|`)。如 `title`、`description`、`c
|
||||
+ `登录回跳`=None
|
||||
+ `登出回跳`=None
|
||||
+ `登录路径`=None
|
||||
+ `注册`=假
|
||||
+ `注册路径`=/register
|
||||
+ `默认角色`="member"
|
||||
+ `会话地址`=None
|
||||
|
||||
在保持 `后台=真` 的同时,为 `{后台前缀}` 加段边界前缀门禁(默认 `/admin`)。未登录 重定向 到 `登录路径`(默认 `{前缀}/login`,自动排除)。不会匹配 `/admin-publish` 这类旁系路径。
|
||||
在保持 `后台=真` 的同时,为 `{后台前缀}` 加段边界前缀门禁(默认 `/admin`)。未登录 重定向 到 `登录路径`(默认 `{前缀}/login`,自动排除)。不会匹配 `/admin-publish` 这类旁系路径。`注册=真` 且已 `启用权限` 时开放 `注册路径`(写入 `web_users` 并赋默认角色)。`会话地址` 可选:`redis://…` / `rediss://…` 将会话存 Redis(与 Postgres/SQLite 业务库分离);缺省仍落在业务库的 `_marqdo_sessions` 或内存。启用统一身份时,`登出回跳` 勿设为登录页(会立刻再跳 IdP);默认/冲突时落首页 `/`。
|
||||
|
||||
*> web_app_auth app=`self` users=`用户表` session_ttl=`会话时长` admin_prefix=`后台前缀` login_redirect=`登录回跳` logout_redirect=`登出回跳` login_path=`登录路径`*
|
||||
*> web_app_auth app=`self` users=`用户表` session_ttl=`会话时长` admin_prefix=`后台前缀` login_redirect=`登录回跳` logout_redirect=`登出回跳` login_path=`登录路径` register=`注册` register_path=`注册路径` default_role=`默认角色` session_url=`会话地址`*
|
||||
|
||||
## 统一身份
|
||||
+ `发行方`=None
|
||||
+ `客户端编号`
|
||||
+ `客户端密钥`
|
||||
+ `回调`
|
||||
+ `范围`="openid profile email"
|
||||
+ `回调路径`=None
|
||||
+ `授权地址`=None
|
||||
+ `令牌地址`=None
|
||||
+ `用户信息地址`=None
|
||||
|
||||
接入 OIDC / OAuth 2.0 授权码(如 [CFLMY 统一身份](https://id.cflmy.cn/api-docs))。listen 后:`登录路径` / `注册路径` / 后台登录页 302 到 IdP;回调 `回调`(默认 `/oidc/callback`)换票并建本地会话。userinfo 的 `is_admin` / `admin_role` 映射为本地角色 `admin`(写作台权限),否则为 `默认角色`。`client_secret` 仅服务端;推荐配 PKCE(框架已启用 S256)。
|
||||
|
||||
*> web_app_oidc app=`self` issuer=`发行方` client_id=`客户端编号` client_secret=`客户端密钥` redirect_uri=`回调` scopes=`范围` callback_path=`回调路径` authorize_url=`授权地址` token_url=`令牌地址` userinfo_url=`用户信息地址`*
|
||||
|
||||
## 门禁
|
||||
+ `路径`
|
||||
+ `角色`=admin
|
||||
+ `权限`=""
|
||||
+ `匹配`=prefix
|
||||
+ `拒绝`=forbid
|
||||
+ `排除`=None
|
||||
|
||||
要求会话角色落在 `角色`(CSV)之一。`匹配=prefix` 为段边界前缀;`exact` 为精确路径。路径末尾 `*` 亦表示前缀。`拒绝=redirect` 时访客跳转登录页(带 `?next=`);`forbid` 返回 403。`排除` 为 CSV/列表(如登录页)。
|
||||
为 `路径` 要求访问权。优先使用 `权限`(CSV,如 `desk:access`);非空时按会话权限集判定。否则要求会话角色落在 `角色`(CSV)之一。`匹配=prefix` 为段边界前缀;`exact` 为精确路径。路径末尾 `*` 亦表示前缀。`拒绝=redirect` 时访客跳转登录页(带 `?next=`);`forbid` 返回 403。`排除` 为 CSV/列表(如登录页)。
|
||||
|
||||
*> web_app_gate app=`self` path=`路径` roles=`角色` match=`匹配` on_deny=`拒绝` exclude=`排除`*
|
||||
*> web_app_gate app=`self` path=`路径` roles=`角色` permissions=`权限` match=`匹配` on_deny=`拒绝` exclude=`排除`*
|
||||
|
||||
## 启用权限
|
||||
+ `目录`=None
|
||||
+ `管理台`=假
|
||||
|
||||
启用库表 RBAC(角色 ⊥ 权限)。listen 时确保五表并种子 `superadmin` / `member`。见 `doc/design/ext-web-rbac.md`。默认**不**挂 `/_rbac/*`;`管理台=真` 时才开放 API 与 `GET /_rbac/desk`(需 `roles:manage`)。门禁 `权限=` 在两种模式下均可用。
|
||||
|
||||
*> web_app_rbac app=`self` catalog=`目录` desk=`管理台`*
|
||||
|
||||
## 租户
|
||||
+ `模式`
|
||||
+ `参数`=None
|
||||
+ `列`=tenant_id
|
||||
+ `默认作用域`=假
|
||||
|
||||
启用多租户解析:`模式` 为 `path`(查询参数或 `/t/{id}/…`)、`subdomain` 或 `header`。`参数` 为路径/查询键或请求头名。`默认作用域=真` 时 JSON 路由与表单插入自动按 `列`(默认 `tenant_id`)过滤/盖戳。单路由可用表列 `租户作用域` 覆盖。
|
||||
|
||||
*> web_app_tenant app=`self` mode=`模式` param=`参数` column=`列` default_scope=`默认作用域`*
|
||||
|
||||
## 相册
|
||||
+ `路径`=/gallery
|
||||
@@ -786,6 +917,49 @@ SEO / OpenGraph 元数据表(`|键|值|`)。如 `title`、`description`、`c
|
||||
|
||||
*> web_app_download app=`self` path=`路径` storage=`存储` disposition=`处置`*
|
||||
|
||||
# 权限
|
||||
|
||||
角色 ⊥ 权限的离线助手。HTTP 侧优先 `应用.启用权限` + 门禁;脚本/测试可用本类。
|
||||
|
||||
## 可否
|
||||
+ `权限`
|
||||
+ `需要`
|
||||
|
||||
返回 `{ok, allowed}`:持有权限 CSV 是否包含 `需要`(CSV)中任一码。持有 `*` 则全允许。
|
||||
|
||||
> 确保插件
|
||||
*> web_rbac_can permissions=`权限` needed=`需要`*
|
||||
|
||||
## 赋角色
|
||||
+ `数据库`
|
||||
+ `用户名`
|
||||
+ `角色`
|
||||
|
||||
将 `用户名`(须已在 `web_users`)绑定到角色名。
|
||||
|
||||
> 确保插件
|
||||
*> web_rbac_assign_role url=`数据库` username=`用户名` role=`角色`*
|
||||
|
||||
## 建角色
|
||||
+ `数据库`
|
||||
+ `名称`
|
||||
|
||||
新建非系统角色;返回 `{ok, id, name}`。
|
||||
|
||||
> 确保插件
|
||||
*> web_rbac_create_role url=`数据库` name=`名称`*
|
||||
|
||||
## 设角色权限
|
||||
+ `数据库`
|
||||
+ `角色`
|
||||
+ `权限`
|
||||
+ `可授`=""
|
||||
|
||||
覆盖非系统角色的权限(CSV)。`可授` 限制可授予码(防提权);空则允许整份目录。
|
||||
|
||||
> 确保插件
|
||||
*> web_rbac_set_role_permissions url=`数据库` role=`角色` permissions=`权限` grantable=`可授`*
|
||||
|
||||
# 鉴权
|
||||
+ `用户表`
|
||||
+ `会话时长`=3600
|
||||
@@ -955,7 +1129,7 @@ WebSocket 客户端工具。
|
||||
+ `消息`=""
|
||||
+ `headers`=None
|
||||
|
||||
单次请求-响应:连接 `地址`,发送 `消息`,收集服务器全部文本回复后关闭。返回 `{ok, messages}`。
|
||||
单次请求-响应:连接 `地址`,发送 `消息`,最多收集 256 条服务器文本回复(每条 ≤1 MiB)后关闭。传输错误与超时返回 `{ok:false, error}`,不再像空的成功回复。
|
||||
|
||||
**timeout = [timeout_sec](self)**
|
||||
*> web_ws_connect url=`地址` message=`消息` headers=`headers` timeout_sec=`timeout`*
|
||||
@@ -44,6 +44,42 @@ Build set_class effect map.
|
||||
**`m` = > table.put in=None at=sel value=class**
|
||||
*> table.put in=None at="set_class" value=m*
|
||||
|
||||
## add_class
|
||||
+ `sel`
|
||||
+ `class`
|
||||
|
||||
Build add_class effect map (classList.add; space-separated names OK).
|
||||
|
||||
**`m` = > table.put in=None at=sel value=class**
|
||||
*> table.put in=None at="add_class" value=m*
|
||||
|
||||
## remove_class
|
||||
+ `sel`
|
||||
+ `class`
|
||||
|
||||
Build remove_class effect map.
|
||||
|
||||
**`m` = > table.put in=None at=sel value=class**
|
||||
*> table.put in=None at="remove_class" value=m*
|
||||
|
||||
## toggle_class
|
||||
+ `sel`
|
||||
+ `class`
|
||||
|
||||
Build toggle_class effect map.
|
||||
|
||||
**`m` = > table.put in=None at=sel value=class**
|
||||
*> table.put in=None at="toggle_class" value=m*
|
||||
|
||||
## set_style
|
||||
+ `sel`
|
||||
+ `style`
|
||||
|
||||
Build set_style effect map; style is a map of CSS properties or a cssText string.
|
||||
|
||||
**`m` = > table.put in=None at=sel value=style**
|
||||
*> table.put in=None at="set_style" value=m*
|
||||
|
||||
## set_attr
|
||||
+ `sel`
|
||||
+ `attrs`
|
||||
@@ -154,6 +190,54 @@ focus.
|
||||
|
||||
*> table.put in=None at="navigate" value=spec*
|
||||
|
||||
## store_set
|
||||
+ `key`
|
||||
+ `value`
|
||||
+ `scope`="memory"
|
||||
+ `then`=""
|
||||
|
||||
In-memory (or local/session) key write for SPA client state. Prefer `scope=memory` for tab-local app state.
|
||||
Optional `then` is called after the write with `{ok, op, key, scope}`.
|
||||
|
||||
`spec` =
|
||||
|
||||
| op | key | value | scope |
|
||||
|----|-----|-------|-------|
|
||||
| set | `key` | `value` | `scope` |
|
||||
|
||||
1. `then` != ""
|
||||
**`spec` = > table.put in=spec at="then" value=then**
|
||||
*> table.put in=None at="storage" value=spec*
|
||||
|
||||
## store_get
|
||||
+ `key`
|
||||
+ `then`
|
||||
+ `scope`="memory"
|
||||
|
||||
Read a key then call `then` with `{ok, value, found, key, scope}`.
|
||||
|
||||
`spec` =
|
||||
|
||||
| op | key | then | scope |
|
||||
|----|-----|------|-------|
|
||||
| get | `key` | `then` | `scope` |
|
||||
|
||||
*> table.put in=None at="storage" value=spec*
|
||||
|
||||
## spa_goto
|
||||
+ `url`
|
||||
+ `replace`=False
|
||||
|
||||
SPA navigation: `history.pushState` / `replaceState` via bridge `navigate` effect.
|
||||
|
||||
`spec` =
|
||||
|
||||
| url | replace |
|
||||
|-----|---------|
|
||||
| `url` | `replace` |
|
||||
|
||||
*> table.put in=None at="navigate" value=spec*
|
||||
|
||||
## storage
|
||||
+ `spec`
|
||||
|
||||
|
||||
+2
-2
@@ -9,7 +9,7 @@ English HTTP(S) wrappers. Optional headers / content_type via host aliases.
|
||||
+ `url`
|
||||
+ `headers`=None
|
||||
|
||||
HTTPS supported. Optional named arg `headers=` (map).
|
||||
HTTPS supported. Optional named arg `headers=` (map). Responses are capped at 8 MiB before decoding, so an upstream cannot exhaust the interpreter's memory.
|
||||
|
||||
*> host_http_get url=`url` headers=`headers`*
|
||||
|
||||
@@ -56,7 +56,7 @@ Optional `body=` / `content_type=` / `headers=`.
|
||||
## url_encode
|
||||
+ `text`
|
||||
|
||||
Percent-encode a URL segment.
|
||||
Percent-encode a URL segment. Spaces become `%20` (not form/query `+`), so literal `+` remains unambiguous in paths.
|
||||
|
||||
*> host_url_encode text=`text`*
|
||||
|
||||
|
||||
@@ -43,6 +43,42 @@ import table:lib/table.mq.md
|
||||
**`m` = > table.put in=None at=选择器 value=类**
|
||||
*> table.put in=None at="set_class" value=m*
|
||||
|
||||
## 加类
|
||||
+ `选择器`
|
||||
+ `类`
|
||||
|
||||
构造 add_class 效应(classList.add;可用空格分隔多个类名)。
|
||||
|
||||
**`m` = > table.put in=None at=选择器 value=类**
|
||||
*> table.put in=None at="add_class" value=m*
|
||||
|
||||
## 去类
|
||||
+ `选择器`
|
||||
+ `类`
|
||||
|
||||
构造 remove_class 效应。
|
||||
|
||||
**`m` = > table.put in=None at=选择器 value=类**
|
||||
*> table.put in=None at="remove_class" value=m*
|
||||
|
||||
## 切类
|
||||
+ `选择器`
|
||||
+ `类`
|
||||
|
||||
构造 toggle_class 效应。
|
||||
|
||||
**`m` = > table.put in=None at=选择器 value=类**
|
||||
*> table.put in=None at="toggle_class" value=m*
|
||||
|
||||
## 设样式
|
||||
+ `选择器`
|
||||
+ `样式`
|
||||
|
||||
构造 set_style 效应;样式为属性表或 cssText 字符串。
|
||||
|
||||
**`m` = > table.put in=None at=选择器 value=样式**
|
||||
*> table.put in=None at="set_style" value=m*
|
||||
|
||||
## 设属性
|
||||
+ `选择器`
|
||||
+ `属性`
|
||||
@@ -153,6 +189,54 @@ import table:lib/table.mq.md
|
||||
|
||||
*> table.put in=None at="navigate" value=spec*
|
||||
|
||||
## 存设
|
||||
+ `键`
|
||||
+ `值`
|
||||
+ `作用域`="memory"
|
||||
+ `然后`=""
|
||||
|
||||
SPA 客户端状态写入。优先 `作用域=memory`(页内内存)。
|
||||
可选 `然后`:写入后回调,参数含 `{ok, op, key, scope}`。
|
||||
|
||||
`spec` =
|
||||
|
||||
| op | key | value | scope |
|
||||
|----|-----|-------|-------|
|
||||
| set | `键` | `值` | `作用域` |
|
||||
|
||||
1. `然后` != ""
|
||||
**`spec` = > table.put in=spec at="then" value=然后**
|
||||
*> table.put in=None at="storage" value=spec*
|
||||
|
||||
## 存取
|
||||
+ `键`
|
||||
+ `然后`
|
||||
+ `作用域`="memory"
|
||||
|
||||
读取键并回调 `然后`,参数含 `{ok, value, found, key, scope}`。
|
||||
|
||||
`spec` =
|
||||
|
||||
| op | key | then | scope |
|
||||
|----|-----|------|-------|
|
||||
| get | `键` | `然后` | `作用域` |
|
||||
|
||||
*> table.put in=None at="storage" value=spec*
|
||||
|
||||
## 页跳
|
||||
+ `url`
|
||||
+ `替换`=False
|
||||
|
||||
SPA 导航(bridge `navigate`)。
|
||||
|
||||
`spec` =
|
||||
|
||||
| url | replace |
|
||||
|-----|---------|
|
||||
| `url` | `替换` |
|
||||
|
||||
*> table.put in=None at="navigate" value=spec*
|
||||
|
||||
## 存储
|
||||
+ `规格`
|
||||
|
||||
|
||||
@@ -17,6 +17,7 @@ import (
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/httpx"
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/middleware"
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/password"
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/rbac"
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/session"
|
||||
)
|
||||
|
||||
@@ -173,6 +174,27 @@ func web_form_rules(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
return replyJSON(outJSON, errMsg, form.SetRules(formBag, args["rules"]), nil)
|
||||
}
|
||||
|
||||
//export web_form_labels
|
||||
func web_form_labels(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
args, err := parseArgs(argsJSON)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
submit, _ := argStr(args, "submit")
|
||||
if submit == "" {
|
||||
submit, _ = argStr(args, "提交")
|
||||
}
|
||||
cancel, _ := argStr(args, "cancel")
|
||||
if cancel == "" {
|
||||
cancel, _ = argStr(args, "取消")
|
||||
}
|
||||
cancelHref, _ := argStr(args, "cancel_href")
|
||||
if cancelHref == "" {
|
||||
cancelHref, _ = argStr(args, "取消链接")
|
||||
}
|
||||
return replyJSON(outJSON, errMsg, form.SetLabels(asPageMap(args["form"]), submit, cancel, cancelHref), nil)
|
||||
}
|
||||
|
||||
//export web_form_validate
|
||||
func web_form_validate(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
args, err := parseArgs(argsJSON)
|
||||
@@ -480,6 +502,16 @@ func web_app_auth(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
return replyJSON(outJSON, errMsg, out, err)
|
||||
}
|
||||
|
||||
//export web_app_oidc
|
||||
func web_app_oidc(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
args, err := parseArgs(argsJSON)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
out, err := app.OIDC(asPageMap(args["app"]), args)
|
||||
return replyJSON(outJSON, errMsg, out, err)
|
||||
}
|
||||
|
||||
//export web_app_gate
|
||||
func web_app_gate(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
args, err := parseArgs(argsJSON)
|
||||
@@ -493,3 +525,154 @@ func web_app_gate(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
out, err := app.Gate(asPageMap(args["app"]), path, args)
|
||||
return replyJSON(outJSON, errMsg, out, err)
|
||||
}
|
||||
|
||||
//export web_app_rbac
|
||||
func web_app_rbac(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
args, err := parseArgs(argsJSON)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
out, err := app.Rbac(asPageMap(args["app"]), args)
|
||||
return replyJSON(outJSON, errMsg, out, err)
|
||||
}
|
||||
|
||||
//export web_app_tenant
|
||||
func web_app_tenant(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
args, err := parseArgs(argsJSON)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
out, err := app.Tenant(asPageMap(args["app"]), args)
|
||||
return replyJSON(outJSON, errMsg, out, err)
|
||||
}
|
||||
|
||||
//export web_rbac_can
|
||||
func web_rbac_can(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
args, err := parseArgs(argsJSON)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
heldRaw, _ := argStrReq(args, "permissions", "权限", "held")
|
||||
neededRaw, _ := argStrReq(args, "needed", "需要")
|
||||
if neededRaw == "" {
|
||||
neededRaw, _ = argStrReq(args, "permission", "权限码")
|
||||
}
|
||||
ok := rbac.HasAny(rbac.ParseCSV(heldRaw), rbac.ParseCSV(neededRaw))
|
||||
return replyJSON(outJSON, errMsg, map[string]any{"ok": true, "allowed": ok}, nil)
|
||||
}
|
||||
|
||||
//export web_rbac_ensure
|
||||
func web_rbac_ensure(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
args, err := parseArgs(argsJSON)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
url, err := dbURLOf(args)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
if err := rbac.EnsureSchema(url); err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
return replyJSON(outJSON, errMsg, map[string]any{"ok": true}, nil)
|
||||
}
|
||||
|
||||
//export web_rbac_assign_role
|
||||
func web_rbac_assign_role(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
args, err := parseArgs(argsJSON)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
url, err := dbURLOf(args)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
user, err := argStrReq(args, "username", "用户名", "user")
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
role, err := argStrReq(args, "role", "角色")
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
err = rbac.AssignRole(url, user, role)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
return replyJSON(outJSON, errMsg, map[string]any{"ok": true}, nil)
|
||||
}
|
||||
|
||||
//export web_rbac_create_role
|
||||
func web_rbac_create_role(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
args, err := parseArgs(argsJSON)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
url, err := dbURLOf(args)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
name, err := argStrReq(args, "name", "名称")
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
id, err := rbac.CreateRole(url, name)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
return replyJSON(outJSON, errMsg, map[string]any{"ok": true, "id": id, "name": name}, nil)
|
||||
}
|
||||
|
||||
//export web_rbac_set_role_permissions
|
||||
func web_rbac_set_role_permissions(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
args, err := parseArgs(argsJSON)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
url, err := dbURLOf(args)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
roleName, _ := argStrReq(args, "role", "角色")
|
||||
permsRaw, _ := argStrReq(args, "permissions", "权限")
|
||||
grantRaw, _ := argStrReq(args, "grantable", "可授")
|
||||
err = rbac.SetRolePermissionsByName(url, roleName, rbac.ParseCSV(permsRaw), rbac.ParseCSV(grantRaw))
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
return replyJSON(outJSON, errMsg, map[string]any{"ok": true}, nil)
|
||||
}
|
||||
|
||||
//export web_rbac_list_roles
|
||||
func web_rbac_list_roles(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
args, err := parseArgs(argsJSON)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
url, err := dbURLOf(args)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
roles, err := rbac.ListRoles(url)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
return replyJSON(outJSON, errMsg, map[string]any{"ok": true, "roles": roles}, nil)
|
||||
}
|
||||
|
||||
//export web_rbac_list_permissions
|
||||
func web_rbac_list_permissions(argsJSON *C.char, outJSON **C.char, errMsg **C.char) C.int {
|
||||
args, err := parseArgs(argsJSON)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
url, err := dbURLOf(args)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
perms, err := rbac.ListPermissions(url)
|
||||
if err != nil {
|
||||
return replyJSON(outJSON, errMsg, nil, err)
|
||||
}
|
||||
return replyJSON(outJSON, errMsg, map[string]any{"ok": true, "permissions": perms}, nil)
|
||||
}
|
||||
@@ -15,13 +15,19 @@ require (
|
||||
github.com/cespare/xxhash/v2 v2.3.0 // indirect
|
||||
github.com/dustin/go-humanize v1.0.1 // indirect
|
||||
github.com/google/uuid v1.6.0 // indirect
|
||||
github.com/jackc/pgpassfile v1.0.0 // indirect
|
||||
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
|
||||
github.com/jackc/pgx/v5 v5.7.4 // indirect
|
||||
github.com/jackc/puddle/v2 v2.2.2 // indirect
|
||||
github.com/mattn/go-isatty v0.0.24 // indirect
|
||||
github.com/ncruces/go-strftime v1.0.0 // indirect
|
||||
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
|
||||
github.com/yuin/goldmark v1.7.8 // indirect
|
||||
github.com/yuin/gopher-lua v1.1.1 // indirect
|
||||
go.uber.org/atomic v1.11.0 // indirect
|
||||
golang.org/x/sync v0.22.0 // indirect
|
||||
golang.org/x/sys v0.47.0 // indirect
|
||||
golang.org/x/text v0.28.0 // indirect
|
||||
modernc.org/libc v1.75.6 // indirect
|
||||
modernc.org/mathutil v1.7.1 // indirect
|
||||
modernc.org/memory v1.12.1 // indirect
|
||||
|
||||
@@ -8,6 +8,7 @@ github.com/bsm/gomega v1.27.10 h1:yeMWxP2pV2fG3FgAODIY8EiRE3dy0aeFYt4l7wh6yKA=
|
||||
github.com/bsm/gomega v1.27.10/go.mod h1:JyEr/xRbxbtgWNi8tIEVPUYZ5Dzef52k01W3YH0H+O0=
|
||||
github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
|
||||
github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
|
||||
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/davecgh/go-spew v1.1.1 h1:vj9j/u1bqnvCEfJOwUhtlOARqs3+rkHYY13jYWTU97c=
|
||||
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW2NihsgmVo/mv3lAwl/skON4iLHjSsI+c5H38=
|
||||
github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
|
||||
@@ -20,6 +21,14 @@ github.com/gorilla/websocket v1.5.3 h1:saDtZ6Pbx/0u+bgYQ3q96pZgCzfhKXGPqt7kZ72aN
|
||||
github.com/gorilla/websocket v1.5.3/go.mod h1:YR8l580nyteQvAITg2hZ9XVh4b55+EU/adAjf1fMHhE=
|
||||
github.com/hashicorp/golang-lru/v2 v2.0.7 h1:a+bsQ5rvGLjzHuww6tVxozPZFVghXaHOwFs4luLUK2k=
|
||||
github.com/hashicorp/golang-lru/v2 v2.0.7/go.mod h1:QeFd9opnmA6QUJc5vARoKUSoFhyfM2/ZepoAG6RGpeM=
|
||||
github.com/jackc/pgpassfile v1.0.0 h1:/6Hmqy13Ss2zCq62VdNG8tM1wchn8zjSGOBJ6icpsIM=
|
||||
github.com/jackc/pgpassfile v1.0.0/go.mod h1:CEx0iS5ambNFdcRtxPj5JhEz+xB6uRky5eyVu/W2HEg=
|
||||
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 h1:iCEnooe7UlwOQYpKFhBabPMi4aNAfoODPEFNiAnClxo=
|
||||
github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761/go.mod h1:5TJZWKEWniPve33vlWYSoGYefn3gLQRzjfDlhSJ9ZKM=
|
||||
github.com/jackc/pgx/v5 v5.7.4 h1:9wKznZrhWa2QiHL+NjTSPP6yjl3451BX3imWDnokYlg=
|
||||
github.com/jackc/pgx/v5 v5.7.4/go.mod h1:ncY89UGWxg82EykZUwSpUKEfccBGGYq1xjrOpsbsfGQ=
|
||||
github.com/jackc/puddle/v2 v2.2.2 h1:PR8nw+E/1w0GLuRFSmiioY6UooMp6KJv0/61nB7icHo=
|
||||
github.com/jackc/puddle/v2 v2.2.2/go.mod h1:vriiEXHvEE654aYKXXjOvZM39qJ0q+azkZFrfEOc3H4=
|
||||
github.com/klauspost/cpuid/v2 v2.2.10 h1:tBs3QSyvjDyFTq3uoc/9xFpCuOsJQFNPiAhYdw2skhE=
|
||||
github.com/klauspost/cpuid/v2 v2.2.10/go.mod h1:hqwkgyIinND0mEev00jJYCxPNVRVXFQeu1XKlok6oO0=
|
||||
github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsReI=
|
||||
@@ -32,8 +41,11 @@ github.com/redis/go-redis/v9 v9.22.0 h1:laDvpYXTJtZLloinw1fA5Kqd6HAEH2XKxOkG/PDq
|
||||
github.com/redis/go-redis/v9 v9.22.0/go.mod h1:y2g0Wj8rQvuK0ELM+oxSudcLtC09JScs98I/X9gRWY4=
|
||||
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
|
||||
github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
|
||||
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
|
||||
github.com/stretchr/testify v1.3.0 h1:TivCn/peBQ7UY8ooIcPgZFpTNSz0Q2U6UrFlUfqbe0Q=
|
||||
github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
|
||||
github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
|
||||
github.com/stretchr/testify v1.8.1 h1:w7B6lhMri9wdJUVmEZPGGhZzrYTPvgJArz7wNPgYKsk=
|
||||
github.com/yuin/goldmark v1.7.8 h1:iERMLn0/QJeHFhxSt3p6PeN9mGnvIKSpG9YYorDMnic=
|
||||
github.com/yuin/goldmark v1.7.8/go.mod h1:uzxRWxtg69N339t3louHJ7+O03ezfj6PlliRlaOzY1E=
|
||||
github.com/yuin/gopher-lua v1.1.1 h1:kYKnWBjvbNP4XLT3+bPEwAXJx262OhaHDWDVOPjL46M=
|
||||
@@ -50,8 +62,12 @@ golang.org/x/sync v0.22.0 h1:SZjpbeLmrCk4xhRSZFNZW5gFUeCeFgjekvI/+gfScek=
|
||||
golang.org/x/sync v0.22.0/go.mod h1:9xrNwdLfx4jkKbNva9FpL6vEN7evnE43NNNJQ2LF3+0=
|
||||
golang.org/x/sys v0.47.0 h1:o7XGOvZQCADBQQ4Y7VNq2dRWQR7JmOUW8Kxx4ZsNgWs=
|
||||
golang.org/x/sys v0.47.0/go.mod h1:4GL1E5IUh+htKOUEOaiffhrAeqysfVGipDYzABqnCmw=
|
||||
golang.org/x/text v0.28.0 h1:rhazDwis8INMIwQ4tpjLDzUhx6RlXqZNPEM0huQojng=
|
||||
golang.org/x/text v0.28.0/go.mod h1:U8nCwOR8jO/marOQ0QbDiOngZVEBB7MAiitBuMjXiNU=
|
||||
golang.org/x/tools v0.48.0 h1:3+hClM1aLL5mjMKm5ovokw9epgRXPuu2tILgismM6RE=
|
||||
golang.org/x/tools v0.48.0/go.mod h1:08xX0orndb/F7jJxGDicx061tyd5pcMto75YMAXr6lk=
|
||||
gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=
|
||||
gopkg.in/yaml.v3 v3.0.0-20200313102051-9f266ea9e77c/go.mod h1:K4uyk7z7BCEPqu6E+C64Yfv1cQ7kz7rIZviUmN+EgEM=
|
||||
modernc.org/cc/v4 v4.29.2 h1:h6+9ciCnPKutf4I03CvheAvDLX7+IHlqR6Iy6J+cgd8=
|
||||
modernc.org/cc/v4 v4.29.2/go.mod h1:OnovgIhbbMXMu1aISnJ0wvVD1KnW+cAUJkIrAWh+kVI=
|
||||
modernc.org/ccgo/v4 v4.35.0 h1:F+TUsmw09QxLzmi3aeYYGxjAXarmZaKgj3mKQHNaA8w=
|
||||
|
||||
@@ -6,7 +6,9 @@ import (
|
||||
"strings"
|
||||
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/assets"
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/oidc"
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/session"
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/tenant"
|
||||
)
|
||||
|
||||
// New builds an app bag matching Rust web_app_new defaults used by zh-smoke.
|
||||
@@ -194,12 +196,33 @@ func Auth(appBag map[string]any, users any, opts map[string]any) (map[string]any
|
||||
loginPath = prefix + "/login"
|
||||
}
|
||||
out["login_path"] = loginPath
|
||||
out["auth"] = map[string]any{
|
||||
"users": users,
|
||||
"session_ttl": float64(sessionTTL),
|
||||
authBag, _ := out["auth"].(map[string]any)
|
||||
if authBag == nil {
|
||||
authBag = map[string]any{}
|
||||
} else {
|
||||
authBag = clone(authBag)
|
||||
}
|
||||
authBag["users"] = users
|
||||
authBag["session_ttl"] = float64(sessionTTL)
|
||||
if v, ok := first(opts, "register", "注册"); ok {
|
||||
authBag["register"] = boolish(v)
|
||||
}
|
||||
if v := firstStr(opts, "register_path", "注册路径"); v != "" {
|
||||
authBag["register_path"] = v
|
||||
out["register_path"] = v
|
||||
}
|
||||
if v := firstStr(opts, "default_role", "默认角色"); v != "" {
|
||||
authBag["default_role"] = v
|
||||
}
|
||||
if v := firstStr(opts, "session_url", "会话地址", "redis_url", "Redis"); v != "" {
|
||||
out["session_url"] = v
|
||||
authBag["session_url"] = v
|
||||
}
|
||||
out["auth"] = authBag
|
||||
gates := gatesOf(out)
|
||||
if !hasAdminGate(gates, prefix) {
|
||||
// Auto-gate the built-in admin prefix only when admin=true. Custom desks
|
||||
// (admin=false) declare their own gates and must not inherit /admin noise.
|
||||
if boolish(out["admin"]) && !hasAdminGate(gates, prefix) {
|
||||
gates = append(gates, map[string]any{
|
||||
"path": prefix,
|
||||
"roles": []any{"admin"},
|
||||
@@ -207,15 +230,62 @@ func Auth(appBag map[string]any, users any, opts map[string]any) (map[string]any
|
||||
"on_deny": "redirect",
|
||||
"exclude": []any{loginPath},
|
||||
})
|
||||
out["gates"] = gates
|
||||
} else {
|
||||
out["gates"] = gates
|
||||
}
|
||||
out["gates"] = gates
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// OIDC configures OAuth2/OIDC authorization-code login (CFLMY IdP or compatible).
|
||||
// When enabled, GET/POST on login_path and register_path redirect to the IdP;
|
||||
// callback at redirect_uri path establishes the local session. IdP is_admin /
|
||||
// admin_role map to local role "admin".
|
||||
func OIDC(appBag map[string]any, opts map[string]any) (map[string]any, error) {
|
||||
if opts == nil {
|
||||
opts = map[string]any{}
|
||||
}
|
||||
cfg := oidc.ParseConfig(opts)
|
||||
if !cfg.Enabled() {
|
||||
return nil, fmt.Errorf("oidc: need client_id, client_secret, redirect_uri, and issuer (or authorize_url)")
|
||||
}
|
||||
out := clone(appBag)
|
||||
bag := map[string]any{
|
||||
"issuer": cfg.Issuer,
|
||||
"client_id": cfg.ClientID,
|
||||
"client_secret": cfg.ClientSecret,
|
||||
"redirect_uri": cfg.RedirectURI,
|
||||
"scopes": cfg.ScopesCSV(),
|
||||
"callback_path": cfg.Callback(),
|
||||
}
|
||||
if cfg.AuthorizeURL != "" {
|
||||
bag["authorize_url"] = cfg.AuthorizeURL
|
||||
}
|
||||
if cfg.TokenURL != "" {
|
||||
bag["token_url"] = cfg.TokenURL
|
||||
}
|
||||
if cfg.UserInfoURL != "" {
|
||||
bag["userinfo_url"] = cfg.UserInfoURL
|
||||
}
|
||||
out["oidc"] = bag
|
||||
authBag, _ := out["auth"].(map[string]any)
|
||||
if authBag == nil {
|
||||
authBag = map[string]any{}
|
||||
} else {
|
||||
authBag = clone(authBag)
|
||||
}
|
||||
authBag["oidc"] = true
|
||||
out["auth"] = authBag
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// Tenant configures multi-tenant resolution on the app bag (path|subdomain|header).
|
||||
func Tenant(appBag map[string]any, opts map[string]any) (map[string]any, error) {
|
||||
return tenant.Configure(appBag, opts)
|
||||
}
|
||||
|
||||
// Gate appends an RBAC gate (Rust web_app_gate).
|
||||
// opts: roles/角色, match/匹配, on_deny/拒绝, exclude/排除.
|
||||
// opts: roles/角色, permissions/权限, match/匹配, on_deny/拒绝, exclude/排除.
|
||||
// When permissions is non-empty, the HTTP middleware authorizes by permission codes;
|
||||
// otherwise it falls back to roles (legacy).
|
||||
func Gate(appBag map[string]any, path string, opts map[string]any) (map[string]any, error) {
|
||||
if opts == nil {
|
||||
opts = map[string]any{}
|
||||
@@ -225,7 +295,8 @@ func Gate(appBag map[string]any, path string, opts map[string]any) (map[string]a
|
||||
return nil, fmt.Errorf("missing `path`")
|
||||
}
|
||||
rolesRaw := firstStr(opts, "roles", "角色")
|
||||
if rolesRaw == "" {
|
||||
permsRaw := firstStr(opts, "permissions", "权限")
|
||||
if rolesRaw == "" && permsRaw == "" {
|
||||
rolesRaw = "admin"
|
||||
}
|
||||
roles := session.ParseRolesCSV(rolesRaw)
|
||||
@@ -233,6 +304,11 @@ func Gate(appBag map[string]any, path string, opts map[string]any) (map[string]a
|
||||
for i, r := range roles {
|
||||
roleAny[i] = r
|
||||
}
|
||||
perms := session.ParseRolesCSV(permsRaw)
|
||||
permAny := make([]any, len(perms))
|
||||
for i, p := range perms {
|
||||
permAny[i] = p
|
||||
}
|
||||
matchMode := firstStr(opts, "match", "匹配")
|
||||
if matchMode == "" {
|
||||
matchMode = "prefix"
|
||||
@@ -247,6 +323,9 @@ func Gate(appBag map[string]any, path string, opts map[string]any) (map[string]a
|
||||
"match": matchMode,
|
||||
"on_deny": onDeny,
|
||||
}
|
||||
if len(permAny) > 0 {
|
||||
entry["permissions"] = permAny
|
||||
}
|
||||
if v, ok := first(opts, "exclude", "排除"); ok && v != nil {
|
||||
entry["exclude"] = v
|
||||
}
|
||||
@@ -257,6 +336,31 @@ func Gate(appBag map[string]any, path string, opts map[string]any) (map[string]a
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// Rbac enables DB-backed RBAC on the app (ensure schema at listen).
|
||||
// opts: catalog/目录 (optional seed table); desk/管理台 (bool, default false) —
|
||||
// when true, listen mounts /_rbac/* API + desk UI; permission gates work either way.
|
||||
func Rbac(appBag map[string]any, opts map[string]any) (map[string]any, error) {
|
||||
out := clone(appBag)
|
||||
authBag, _ := out["auth"].(map[string]any)
|
||||
if authBag == nil {
|
||||
authBag = map[string]any{}
|
||||
} else {
|
||||
authBag = clone(authBag)
|
||||
}
|
||||
authBag["rbac"] = true
|
||||
authBag["rbac_desk"] = false
|
||||
if opts != nil {
|
||||
if v, ok := first(opts, "catalog", "目录"); ok && v != nil {
|
||||
authBag["permission_catalog"] = v
|
||||
}
|
||||
if v, ok := first(opts, "desk", "管理台"); ok {
|
||||
authBag["rbac_desk"] = boolish(v)
|
||||
}
|
||||
}
|
||||
out["auth"] = authBag
|
||||
return out, nil
|
||||
}
|
||||
|
||||
// NormalizeAdminPrefix cleans and validates admin_prefix.
|
||||
func NormalizeAdminPrefix(raw string) (string, error) {
|
||||
path, err := cleanMountPath(raw)
|
||||
|
||||
@@ -114,6 +114,50 @@ func TestAuthDefaultGate(t *testing.T) {
|
||||
}
|
||||
}
|
||||
|
||||
func TestAuthNoAutoGateWhenAdminOff(t *testing.T) {
|
||||
a := app.New(map[string]any{"admin": false})
|
||||
out, err := app.Auth(a, []any{}, map[string]any{"login_path": "/login"})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if gates, ok := out["gates"].([]any); ok && len(gates) != 0 {
|
||||
t.Fatalf("expected no auto gate when admin=false, got %v", gates)
|
||||
}
|
||||
}
|
||||
|
||||
func TestRbacDeskOptIn(t *testing.T) {
|
||||
a := app.New(map[string]any{"admin": false})
|
||||
out, err := app.Rbac(a, nil)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
authBag := out["auth"].(map[string]any)
|
||||
if !boolishTest(authBag["rbac"]) || boolishTest(authBag["rbac_desk"]) {
|
||||
t.Fatalf("default rbac_desk should be false: %v", authBag)
|
||||
}
|
||||
out2, err := app.Rbac(a, map[string]any{"管理台": true})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
if !boolishTest(out2["auth"].(map[string]any)["rbac_desk"]) {
|
||||
t.Fatal("expected rbac_desk true")
|
||||
}
|
||||
}
|
||||
|
||||
func boolishTest(v any) bool {
|
||||
switch x := v.(type) {
|
||||
case bool:
|
||||
return x
|
||||
case string:
|
||||
s := strings.ToLower(strings.TrimSpace(x))
|
||||
return s == "1" || s == "true" || s == "yes" || s == "真"
|
||||
case float64:
|
||||
return x != 0
|
||||
default:
|
||||
return false
|
||||
}
|
||||
}
|
||||
|
||||
func TestAuthCustomPrefix(t *testing.T) {
|
||||
a := app.New(map[string]any{"admin": true})
|
||||
out, err := app.Auth(a, []any{}, map[string]any{
|
||||
|
||||
@@ -86,7 +86,7 @@ func cellStr(v any) string {
|
||||
}
|
||||
|
||||
// Login validates credentials and creates a session.
|
||||
// Success: {"ok":true,"session_id":…,"username":…,"role":…}
|
||||
// Success: {"ok":true,"session_id":…,"username":…,"role":…,"permissions":…}
|
||||
// Failure: {"ok":false}
|
||||
func Login(username, pass string, users any, sessionTTL uint64) map[string]any {
|
||||
u, role, ok := CheckCredentials(users, username, pass)
|
||||
@@ -104,6 +104,14 @@ func Login(username, pass string, users any, sessionTTL uint64) map[string]any {
|
||||
}
|
||||
}
|
||||
|
||||
// AttachPermissions writes permission codes onto an existing login session.
|
||||
func AttachPermissions(sessionID string, codes []string) {
|
||||
if sessionID == "" {
|
||||
return
|
||||
}
|
||||
session.SetPermissions(sessionID, codes)
|
||||
}
|
||||
|
||||
// Check returns session auth state (web_auth_check).
|
||||
func Check(sessionID string) map[string]any {
|
||||
v, ok := session.GetValue(sessionID, "username")
|
||||
@@ -120,7 +128,12 @@ func Check(sessionID string) map[string]any {
|
||||
role = s
|
||||
}
|
||||
}
|
||||
return map[string]any{"ok": true, "username": u, "role": role}
|
||||
perms := session.PermissionsFromSession(sessionID)
|
||||
out := map[string]any{"ok": true, "username": u, "role": role}
|
||||
if len(perms) > 0 {
|
||||
out["permissions"] = perms
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// Logout destroys the session (web_auth_logout).
|
||||
|
||||
@@ -152,14 +152,10 @@ func ComposeComponents(page any, layout any, callLib CallLib) (any, error) {
|
||||
return obj, nil
|
||||
}
|
||||
|
||||
// ComposeMain merges a main bind table into a page bag.
|
||||
func ComposeMain(page any, mainTable any, callLib CallLib) (any, error) {
|
||||
obj := asObject(page)
|
||||
func resolveBinds(mainTable any, callLib CallLib) (binds []any, css string, err error) {
|
||||
raw := table.AsBind(mainTable)
|
||||
arr, _ := raw.([]any)
|
||||
binds := make([]any, 0, len(arr))
|
||||
css := strField(obj, "styles_css")
|
||||
|
||||
binds = make([]any, 0, len(arr))
|
||||
for _, b := range arr {
|
||||
bm, ok := b.(map[string]any)
|
||||
if !ok {
|
||||
@@ -191,7 +187,7 @@ func ComposeMain(page any, mainTable any, callLib CallLib) (any, error) {
|
||||
case table.SitePathLibMember:
|
||||
st, err := callLib(sp.Lib + "." + sp.Member)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
return nil, "", err
|
||||
}
|
||||
css += table.AsCSSNamed(sp.Member, st)
|
||||
cssName = sp.Member
|
||||
@@ -207,6 +203,17 @@ func ComposeMain(page any, mainTable any, callLib CallLib) (any, error) {
|
||||
"css": cssName,
|
||||
})
|
||||
}
|
||||
return binds, css, nil
|
||||
}
|
||||
|
||||
// ComposeMain merges a main bind table into a page bag.
|
||||
func ComposeMain(page any, mainTable any, callLib CallLib) (any, error) {
|
||||
obj := asObject(page)
|
||||
binds, cssExtra, err := resolveBinds(mainTable, callLib)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
css := strField(obj, "styles_css") + cssExtra
|
||||
|
||||
if t, ok := table.BindTableName(binds); ok {
|
||||
obj["table"] = t
|
||||
@@ -234,6 +241,41 @@ func ComposeMain(page any, mainTable any, callLib CallLib) (any, error) {
|
||||
return obj, nil
|
||||
}
|
||||
|
||||
// ComposeList appends a secondary bind (detail + child list), with optional
|
||||
// query/order/target (inject into intro element id, same as form_target).
|
||||
func ComposeList(page any, mainTable any, query any, order, target string, callLib CallLib) (any, error) {
|
||||
obj := asObject(page)
|
||||
binds, cssExtra, err := resolveBinds(mainTable, callLib)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if cssExtra != "" {
|
||||
prev := strField(obj, "styles_css")
|
||||
if prev != "" {
|
||||
obj["styles_css"] = prev + cssExtra
|
||||
} else {
|
||||
obj["styles_css"] = cssExtra
|
||||
}
|
||||
}
|
||||
entry := map[string]any{"main": binds}
|
||||
if query != nil {
|
||||
entry["query"] = query
|
||||
}
|
||||
if strings.TrimSpace(order) != "" {
|
||||
entry["order"] = strings.TrimSpace(order)
|
||||
}
|
||||
if t := strings.TrimSpace(target); t != "" {
|
||||
entry["target"] = t
|
||||
}
|
||||
lists := []any{}
|
||||
if existing, ok := obj["lists"].([]any); ok {
|
||||
lists = append(lists, existing...)
|
||||
}
|
||||
lists = append(lists, entry)
|
||||
obj["lists"] = lists
|
||||
return obj, nil
|
||||
}
|
||||
|
||||
// ComposeForm embeds a form into the page main slot.
|
||||
func ComposeForm(page any, form any, formID string, formTarget *string) (any, error) {
|
||||
id := strings.TrimSpace(formID)
|
||||
|
||||
@@ -0,0 +1,45 @@
|
||||
package compose
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// ComposeAuthForm stamps page.auth_form for progressive-enhancement login/register.
|
||||
// action is the form POST path (e.g. /login, /desk/login, /register).
|
||||
func ComposeAuthForm(page any, action, submit, formID, errID, target, nextDefault, kind string) (any, error) {
|
||||
action = strings.TrimSpace(action)
|
||||
if action == "" {
|
||||
return nil, fmt.Errorf("compose_auth_form requires non-empty action")
|
||||
}
|
||||
obj := asObject(page)
|
||||
kind = strings.TrimSpace(strings.ToLower(kind))
|
||||
if kind == "" {
|
||||
if strings.Contains(strings.ToLower(action), "register") {
|
||||
kind = "register"
|
||||
} else {
|
||||
kind = "login"
|
||||
}
|
||||
}
|
||||
spec := map[string]any{
|
||||
"action": action,
|
||||
"kind": kind,
|
||||
}
|
||||
if s := strings.TrimSpace(submit); s != "" {
|
||||
spec["submit"] = s
|
||||
}
|
||||
if s := strings.TrimSpace(formID); s != "" {
|
||||
spec["form_id"] = s
|
||||
}
|
||||
if s := strings.TrimSpace(errID); s != "" {
|
||||
spec["err_id"] = s
|
||||
}
|
||||
if s := strings.TrimSpace(target); s != "" {
|
||||
spec["target"] = s
|
||||
}
|
||||
if s := strings.TrimSpace(nextDefault); s != "" {
|
||||
spec["next"] = s
|
||||
}
|
||||
obj["auth_form"] = spec
|
||||
return obj, nil
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
package compose
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// ComposeFormLoad stamps page.form_load so render prefills the composed form
|
||||
// from DB by route/query id (desk edit pages without author JS).
|
||||
func ComposeFormLoad(page any, table, idParam string) (any, error) {
|
||||
obj := asObject(page)
|
||||
table = strings.TrimSpace(table)
|
||||
if table == "" {
|
||||
return nil, fmt.Errorf("compose_form_load requires non-empty table")
|
||||
}
|
||||
spec := map[string]any{"table": table}
|
||||
if s := strings.TrimSpace(idParam); s != "" {
|
||||
spec["id_param"] = s
|
||||
} else {
|
||||
spec["id_param"] = "id"
|
||||
}
|
||||
obj["form_load"] = spec
|
||||
return obj, nil
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
package compose
|
||||
|
||||
import "testing"
|
||||
|
||||
func TestComposeFormLoad(t *testing.T) {
|
||||
page := map[string]any{"title": "Edit"}
|
||||
out, err := ComposeFormLoad(page, "posts", "")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
obj, ok := out.(map[string]any)
|
||||
if !ok {
|
||||
t.Fatalf("want map, got %T", out)
|
||||
}
|
||||
load, ok := obj["form_load"].(map[string]any)
|
||||
if !ok {
|
||||
t.Fatalf("missing form_load: %#v", obj)
|
||||
}
|
||||
if load["table"] != "posts" {
|
||||
t.Fatalf("table=%v", load["table"])
|
||||
}
|
||||
if load["id_param"] != "id" {
|
||||
t.Fatalf("id_param=%v", load["id_param"])
|
||||
}
|
||||
}
|
||||
|
||||
func TestComposeFormLoadRequiresTable(t *testing.T) {
|
||||
_, err := ComposeFormLoad(map[string]any{}, " ", "id")
|
||||
if err == nil {
|
||||
t.Fatal("expected error for empty table")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,437 @@
|
||||
package compose
|
||||
|
||||
import (
|
||||
"fmt"
|
||||
"html"
|
||||
"strings"
|
||||
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/table"
|
||||
)
|
||||
|
||||
// ComposeIntro binds an intro table (|属性|值|样式| / |front|back|style|) onto the
|
||||
// page — same shape as ComposeMain. Literals go in 值/back; 样式 resolves like
|
||||
// card_title into styles_css + element class names. Sets page.intro HTML.
|
||||
//
|
||||
// Unlike AsBind, the 值/back column is not NormalizeRef'd so inline `code`
|
||||
// markers survive for richText.
|
||||
func ComposeIntro(page any, introTable any, callLib CallLib) (any, error) {
|
||||
obj := asObject(page)
|
||||
arr := asIntroRows(introTable)
|
||||
css := strField(obj, "styles_css")
|
||||
seenStyle := map[string]bool{}
|
||||
binds := make([]map[string]any, 0, len(arr))
|
||||
|
||||
for _, bm := range arr {
|
||||
front := table.NormalizeRef(strField(bm, "front"))
|
||||
backRaw := strings.TrimSpace(strField(bm, "back"))
|
||||
cssRaw := table.NormalizeRef(strField(bm, "css"))
|
||||
|
||||
back := backRaw
|
||||
switch sp := table.ParseSitePath(backRaw); sp.Kind {
|
||||
case table.SitePathLibMember:
|
||||
// Intro copy is almost always prose; only resolve clear lib.member refs
|
||||
// that look like style/module paths (no spaces).
|
||||
if !strings.ContainsAny(backRaw, " \t\n") {
|
||||
v, err := callLib(sp.Lib + "." + sp.Member)
|
||||
if err != nil {
|
||||
back = sp.Lib + "." + sp.Member
|
||||
} else if s, ok := v.(string); ok {
|
||||
back = s
|
||||
} else {
|
||||
back = fmt.Sprint(v)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
cssName := ""
|
||||
if cssRaw != "" {
|
||||
switch sp := table.ParseSitePath(cssRaw); sp.Kind {
|
||||
case table.SitePathLibMember:
|
||||
cssName = sp.Member
|
||||
if !seenStyle[cssName] {
|
||||
st, err := callLib(sp.Lib + "." + sp.Member)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
css += table.AsCSSNamed(sp.Member, st)
|
||||
seenStyle[cssName] = true
|
||||
}
|
||||
case table.SitePathPlain:
|
||||
cssName = sp.Plain
|
||||
case table.SitePathDbField:
|
||||
cssName = table.NormalizeRef(cssRaw)
|
||||
}
|
||||
}
|
||||
|
||||
if front == "" && back == "" {
|
||||
continue
|
||||
}
|
||||
binds = append(binds, map[string]any{
|
||||
"front": front,
|
||||
"back": back,
|
||||
"css": cssName,
|
||||
})
|
||||
}
|
||||
|
||||
obj["intro"] = RenderIntroHTML(binds)
|
||||
obj["intro_bind"] = binds
|
||||
if css != "" {
|
||||
obj["styles_css"] = css
|
||||
}
|
||||
return obj, nil
|
||||
}
|
||||
|
||||
// MakeIntroHTML builds intro HTML from a bind table without resolving lib styles
|
||||
// (css column used as class name as-is). Preserves backticks in 值/back.
|
||||
func MakeIntroHTML(introTable any) string {
|
||||
arr := asIntroRows(introTable)
|
||||
binds := make([]map[string]any, 0, len(arr))
|
||||
for _, bm := range arr {
|
||||
front := table.NormalizeRef(strField(bm, "front"))
|
||||
back := strings.TrimSpace(strField(bm, "back"))
|
||||
cssName := table.NormalizeRef(strField(bm, "css"))
|
||||
if front == "" && back == "" {
|
||||
continue
|
||||
}
|
||||
binds = append(binds, map[string]any{
|
||||
"front": front,
|
||||
"back": back,
|
||||
"css": cssName,
|
||||
})
|
||||
}
|
||||
return RenderIntroHTML(binds)
|
||||
}
|
||||
|
||||
func asIntroRows(v any) []map[string]any {
|
||||
switch t := v.(type) {
|
||||
case []any:
|
||||
out := make([]map[string]any, 0, len(t))
|
||||
for _, row := range t {
|
||||
m, ok := row.(map[string]any)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
front, back, css := "", "", ""
|
||||
if x, ok := pickIntro(m, []string{"属性", "前端变量", "front", "field"}); ok {
|
||||
front = cellIntro(x)
|
||||
}
|
||||
if x, ok := pickIntro(m, []string{"值", "后端数据库", "back", "db", "text", "文"}); ok {
|
||||
back = cellIntro(x)
|
||||
}
|
||||
if x, ok := pickIntro(m, []string{"样式", "绑定css样式", "css", "class", "style"}); ok {
|
||||
css = cellIntro(x)
|
||||
}
|
||||
if front != "" || back != "" {
|
||||
out = append(out, map[string]any{"front": front, "back": back, "css": css})
|
||||
}
|
||||
}
|
||||
return out
|
||||
case map[string]any:
|
||||
// Column-oriented map of lists (GFM multi-row table).
|
||||
fronts, backs, csses := []string{}, []string{}, []string{}
|
||||
if x, ok := pickIntro(t, []string{"属性", "前端变量", "front", "field"}); ok {
|
||||
fronts = asIntroStrList(x)
|
||||
}
|
||||
if x, ok := pickIntro(t, []string{"值", "后端数据库", "back", "db", "text", "文"}); ok {
|
||||
backs = asIntroStrList(x)
|
||||
}
|
||||
if x, ok := pickIntro(t, []string{"样式", "绑定css样式", "css", "class", "style"}); ok {
|
||||
csses = asIntroStrList(x)
|
||||
}
|
||||
n := len(fronts)
|
||||
if len(backs) > n {
|
||||
n = len(backs)
|
||||
}
|
||||
out := make([]map[string]any, 0, n)
|
||||
for i := 0; i < n; i++ {
|
||||
front, back, css := "", "", ""
|
||||
if i < len(fronts) {
|
||||
front = fronts[i]
|
||||
}
|
||||
if i < len(backs) {
|
||||
back = backs[i]
|
||||
}
|
||||
if i < len(csses) {
|
||||
css = csses[i]
|
||||
}
|
||||
if front != "" || back != "" {
|
||||
out = append(out, map[string]any{"front": front, "back": back, "css": css})
|
||||
}
|
||||
}
|
||||
return out
|
||||
default:
|
||||
return nil
|
||||
}
|
||||
}
|
||||
|
||||
func asIntroStrList(v any) []string {
|
||||
switch t := v.(type) {
|
||||
case []any:
|
||||
out := make([]string, 0, len(t))
|
||||
for _, x := range t {
|
||||
out = append(out, cellIntro(x))
|
||||
}
|
||||
return out
|
||||
case []string:
|
||||
return t
|
||||
default:
|
||||
s := cellIntro(v)
|
||||
if s == "" {
|
||||
return nil
|
||||
}
|
||||
return []string{s}
|
||||
}
|
||||
}
|
||||
|
||||
func pickIntro(m map[string]any, keys []string) (any, bool) {
|
||||
for _, k := range keys {
|
||||
if v, ok := m[k]; ok {
|
||||
return v, true
|
||||
}
|
||||
}
|
||||
return nil, false
|
||||
}
|
||||
|
||||
func cellIntro(v any) string {
|
||||
switch t := v.(type) {
|
||||
case nil:
|
||||
return ""
|
||||
case string:
|
||||
return t
|
||||
case bool:
|
||||
if t {
|
||||
return "true"
|
||||
}
|
||||
return "false"
|
||||
case float64:
|
||||
if t == float64(int64(t)) {
|
||||
return fmt.Sprintf("%d", int64(t))
|
||||
}
|
||||
return fmt.Sprintf("%v", t)
|
||||
default:
|
||||
return fmt.Sprint(t)
|
||||
}
|
||||
}
|
||||
|
||||
// RenderIntroHTML turns normalized intro binds into .main-intro inner HTML.
|
||||
func RenderIntroHTML(binds []map[string]any) string {
|
||||
if len(binds) == 0 {
|
||||
return ""
|
||||
}
|
||||
var out strings.Builder
|
||||
i := 0
|
||||
for i < len(binds) {
|
||||
front := strings.TrimSpace(strField(binds[i], "front"))
|
||||
kind := introKind(front)
|
||||
switch kind {
|
||||
case "claim":
|
||||
j := i
|
||||
for j < len(binds) && introKind(strField(binds[j], "front")) == "claim" {
|
||||
j++
|
||||
}
|
||||
out.WriteString(`<p class="claim">`)
|
||||
for _, row := range binds[i:j] {
|
||||
cls := classAttr(strField(row, "css"))
|
||||
out.WriteString(fmt.Sprintf("<span%s>%s</span>", cls, richText(strField(row, "back"))))
|
||||
}
|
||||
out.WriteString(`</p>`)
|
||||
i = j
|
||||
case "step":
|
||||
j := i
|
||||
for j < len(binds) && introKind(strField(binds[j], "front")) == "step" {
|
||||
j++
|
||||
}
|
||||
out.WriteString(`<ol class="steps">`)
|
||||
for _, row := range binds[i:j] {
|
||||
cls := classAttr(strField(row, "css"))
|
||||
out.WriteString(fmt.Sprintf("<li%s>%s</li>", cls, richText(strField(row, "back"))))
|
||||
}
|
||||
out.WriteString(`</ol>`)
|
||||
i = j
|
||||
case "mount":
|
||||
id := strField(binds[i], "back")
|
||||
if id == "" {
|
||||
id = front
|
||||
}
|
||||
id = strings.TrimPrefix(id, "#")
|
||||
out.WriteString(fmt.Sprintf(`<div id="%s"></div>`, html.EscapeString(id)))
|
||||
i++
|
||||
case "html":
|
||||
out.WriteString(strField(binds[i], "back"))
|
||||
i++
|
||||
default:
|
||||
tag, baseClass := introTagClass(kind, front)
|
||||
cssName := strField(binds[i], "css")
|
||||
cls := mergeClass(baseClass, cssName)
|
||||
out.WriteString(fmt.Sprintf("<%s%s>%s</%s>", tag, classAttr(cls), richText(strField(binds[i], "back")), tag))
|
||||
i++
|
||||
}
|
||||
}
|
||||
return out.String()
|
||||
}
|
||||
|
||||
func introKind(front string) string {
|
||||
s := strings.ToLower(strings.TrimSpace(front))
|
||||
switch s {
|
||||
case "kicker", "eyebrow", "眉题":
|
||||
return "kicker"
|
||||
case "title", "h1", "标题":
|
||||
return "title"
|
||||
case "lede", "lead", "导语":
|
||||
return "lede"
|
||||
case "claim", "badge", "标签":
|
||||
return "claim"
|
||||
case "step", "步骤":
|
||||
return "step"
|
||||
case "h2", "小标题":
|
||||
return "h2"
|
||||
case "p", "段落":
|
||||
return "p"
|
||||
case "mount", "插槽", "slot":
|
||||
return "mount"
|
||||
case "html", "原文", "raw":
|
||||
return "html"
|
||||
default:
|
||||
return s
|
||||
}
|
||||
}
|
||||
|
||||
func introTagClass(kind, front string) (tag, baseClass string) {
|
||||
switch kind {
|
||||
case "kicker":
|
||||
return "p", "kicker"
|
||||
case "title":
|
||||
return "h1", ""
|
||||
case "lede":
|
||||
return "p", "lede"
|
||||
case "h2":
|
||||
return "h2", ""
|
||||
case "p":
|
||||
return "p", ""
|
||||
default:
|
||||
if front != "" {
|
||||
return "p", front
|
||||
}
|
||||
return "p", ""
|
||||
}
|
||||
}
|
||||
|
||||
func mergeClass(base, style string) string {
|
||||
base = strings.TrimSpace(base)
|
||||
style = strings.TrimSpace(style)
|
||||
switch {
|
||||
case base == "":
|
||||
return style
|
||||
case style == "" || style == base:
|
||||
return base
|
||||
default:
|
||||
return base + " " + style
|
||||
}
|
||||
}
|
||||
|
||||
func classAttr(class string) string {
|
||||
class = strings.TrimSpace(class)
|
||||
if class == "" {
|
||||
return ""
|
||||
}
|
||||
return ` class="` + html.EscapeString(class) + `"`
|
||||
}
|
||||
|
||||
// richText escapes text then applies a tiny Markdown subset: [label](url), `code`, **bold**.
|
||||
func richText(s string) string {
|
||||
if s == "" {
|
||||
return ""
|
||||
}
|
||||
type span struct {
|
||||
kind string // text|a|code|strong
|
||||
a string
|
||||
b string
|
||||
}
|
||||
var spans []span
|
||||
rest := s
|
||||
for len(rest) > 0 {
|
||||
// find earliest special
|
||||
iLink := strings.Index(rest, "[")
|
||||
iCode := strings.Index(rest, "`")
|
||||
iBold := strings.Index(rest, "**")
|
||||
next := -1
|
||||
which := ""
|
||||
if iLink >= 0 && (next < 0 || iLink < next) {
|
||||
next, which = iLink, "a"
|
||||
}
|
||||
if iCode >= 0 && (next < 0 || iCode < next) {
|
||||
next, which = iCode, "code"
|
||||
}
|
||||
if iBold >= 0 && (next < 0 || iBold < next) {
|
||||
next, which = iBold, "strong"
|
||||
}
|
||||
if next < 0 {
|
||||
spans = append(spans, span{kind: "text", a: rest})
|
||||
break
|
||||
}
|
||||
if next > 0 {
|
||||
spans = append(spans, span{kind: "text", a: rest[:next]})
|
||||
}
|
||||
rest = rest[next:]
|
||||
switch which {
|
||||
case "a":
|
||||
// [label](url)
|
||||
endLabel := strings.Index(rest, "](")
|
||||
if endLabel < 0 {
|
||||
spans = append(spans, span{kind: "text", a: rest[:1]})
|
||||
rest = rest[1:]
|
||||
continue
|
||||
}
|
||||
endURL := strings.Index(rest[endLabel+2:], ")")
|
||||
if endURL < 0 {
|
||||
spans = append(spans, span{kind: "text", a: rest[:1]})
|
||||
rest = rest[1:]
|
||||
continue
|
||||
}
|
||||
label := rest[1:endLabel]
|
||||
url := rest[endLabel+2 : endLabel+2+endURL]
|
||||
spans = append(spans, span{kind: "a", a: label, b: url})
|
||||
rest = rest[endLabel+2+endURL+1:]
|
||||
case "code":
|
||||
end := strings.Index(rest[1:], "`")
|
||||
if end < 0 {
|
||||
spans = append(spans, span{kind: "text", a: rest[:1]})
|
||||
rest = rest[1:]
|
||||
continue
|
||||
}
|
||||
spans = append(spans, span{kind: "code", a: rest[1 : 1+end]})
|
||||
rest = rest[1+end+1:]
|
||||
case "strong":
|
||||
end := strings.Index(rest[2:], "**")
|
||||
if end < 0 {
|
||||
spans = append(spans, span{kind: "text", a: rest[:2]})
|
||||
rest = rest[2:]
|
||||
continue
|
||||
}
|
||||
spans = append(spans, span{kind: "strong", a: rest[2 : 2+end]})
|
||||
rest = rest[2+end+2:]
|
||||
}
|
||||
}
|
||||
var out strings.Builder
|
||||
for _, sp := range spans {
|
||||
switch sp.kind {
|
||||
case "a":
|
||||
out.WriteString(`<a href="`)
|
||||
out.WriteString(html.EscapeString(sp.b))
|
||||
out.WriteString(`">`)
|
||||
out.WriteString(html.EscapeString(sp.a))
|
||||
out.WriteString(`</a>`)
|
||||
case "code":
|
||||
out.WriteString(`<code>`)
|
||||
out.WriteString(html.EscapeString(sp.a))
|
||||
out.WriteString(`</code>`)
|
||||
case "strong":
|
||||
out.WriteString(`<strong>`)
|
||||
out.WriteString(html.EscapeString(sp.a))
|
||||
out.WriteString(`</strong>`)
|
||||
default:
|
||||
out.WriteString(html.EscapeString(sp.a))
|
||||
}
|
||||
}
|
||||
return out.String()
|
||||
}
|
||||
@@ -0,0 +1,30 @@
|
||||
package compose
|
||||
|
||||
import "testing"
|
||||
|
||||
func TestComposeListAppends(t *testing.T) {
|
||||
page := map[string]any{"title": "p"}
|
||||
main := []any{
|
||||
map[string]any{"front": "title", "back": "comments.author", "css": ""},
|
||||
map[string]any{"front": "body", "back": "comments.body", "css": ""},
|
||||
}
|
||||
q := []any{map[string]any{"field": "post_slug", "op": "=", "value": "{slug}"}}
|
||||
out, err := ComposeList(page, main, q, "-created_at", "#comment-list", func(string) (any, error) {
|
||||
return nil, nil
|
||||
})
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
m := out.(map[string]any)
|
||||
lists, ok := m["lists"].([]any)
|
||||
if !ok || len(lists) != 1 {
|
||||
t.Fatalf("lists=%v", m["lists"])
|
||||
}
|
||||
entry := lists[0].(map[string]any)
|
||||
if entry["order"] != "-created_at" || entry["target"] != "#comment-list" {
|
||||
t.Fatalf("entry=%v", entry)
|
||||
}
|
||||
if entry["query"] == nil {
|
||||
t.Fatal("missing query")
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,55 @@
|
||||
package compose
|
||||
|
||||
import (
|
||||
"strings"
|
||||
)
|
||||
|
||||
// ComposeNavBrand stamps page.nav_brand for SSR topnav lockup (logo + title),
|
||||
// theme toggle, and drawer button chrome. Client WASM only wires behavior.
|
||||
func ComposeNavBrand(page any, title, href, logo, logoLight, themeKey string) (any, error) {
|
||||
obj := asObject(page)
|
||||
spec := map[string]any{}
|
||||
if s := strings.TrimSpace(title); s != "" {
|
||||
spec["title"] = s
|
||||
}
|
||||
if s := strings.TrimSpace(href); s != "" {
|
||||
spec["href"] = s
|
||||
} else {
|
||||
spec["href"] = "/"
|
||||
}
|
||||
if s := strings.TrimSpace(logo); s != "" {
|
||||
spec["logo"] = s
|
||||
}
|
||||
if s := strings.TrimSpace(logoLight); s != "" {
|
||||
spec["logo_light"] = s
|
||||
}
|
||||
if s := strings.TrimSpace(themeKey); s != "" {
|
||||
spec["theme_key"] = s
|
||||
} else {
|
||||
spec["theme_key"] = "mq-theme"
|
||||
}
|
||||
obj["nav_brand"] = spec
|
||||
return obj, nil
|
||||
}
|
||||
|
||||
// ComposeClient stamps page.client so render injects official bridge auto-mount
|
||||
// (data-mq-wasm / data-mq-source-url). Authors ship client.mq.md, not business JS.
|
||||
func ComposeClient(page any, bridge, wasm, source string) (any, error) {
|
||||
obj := asObject(page)
|
||||
spec := map[string]any{}
|
||||
if s := strings.TrimSpace(bridge); s != "" {
|
||||
spec["bridge"] = s
|
||||
} else {
|
||||
spec["bridge"] = "/static/marqdo-bridge.js"
|
||||
}
|
||||
if s := strings.TrimSpace(wasm); s != "" {
|
||||
spec["wasm"] = s
|
||||
} else {
|
||||
spec["wasm"] = "/static/marqdo_wasm.wasm"
|
||||
}
|
||||
if s := strings.TrimSpace(source); s != "" {
|
||||
spec["source"] = s
|
||||
}
|
||||
obj["client"] = spec
|
||||
return obj, nil
|
||||
}
|
||||
@@ -0,0 +1,32 @@
|
||||
package compose_test
|
||||
|
||||
import (
|
||||
"testing"
|
||||
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/compose"
|
||||
)
|
||||
|
||||
func TestComposeNavBrandAndClient(t *testing.T) {
|
||||
page := map[string]any{"title": "t"}
|
||||
out, err := compose.ComposeNavBrand(page, "求道量子", "/", "/static/logo.png", "/static/logo-light.png", "mq-theme")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
m := out.(map[string]any)
|
||||
b, ok := m["nav_brand"].(map[string]any)
|
||||
if !ok || b["title"] != "求道量子" || b["logo"] != "/static/logo.png" {
|
||||
t.Fatalf("nav_brand: %#v", m["nav_brand"])
|
||||
}
|
||||
out, err = compose.ComposeClient(m, "", "", "/static/client.mq.md")
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
m = out.(map[string]any)
|
||||
c, ok := m["client"].(map[string]any)
|
||||
if !ok || c["source"] != "/static/client.mq.md" {
|
||||
t.Fatalf("client: %#v", m["client"])
|
||||
}
|
||||
if c["bridge"] != "/static/marqdo-bridge.js" {
|
||||
t.Fatalf("bridge default: %#v", c)
|
||||
}
|
||||
}
|
||||
@@ -1,11 +1,80 @@
|
||||
package compose_test
|
||||
|
||||
import (
|
||||
"strings"
|
||||
"testing"
|
||||
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/compose"
|
||||
)
|
||||
|
||||
func TestComposeIntroBindAndRichText(t *testing.T) {
|
||||
page := map[string]any{"title": "Home"}
|
||||
intro := []any{
|
||||
map[string]any{"属性": "kicker", "值": "WWW Demo", "样式": "shell.kicker"},
|
||||
map[string]any{"属性": "title", "值": "Marqdo", "样式": "shell.intro_title"},
|
||||
map[string]any{"属性": "lede", "值": "Zero author `JS`.", "样式": "shell.lede"},
|
||||
map[string]any{"属性": "claim", "值": "0 JS", "样式": "shell.claim"},
|
||||
map[string]any{"属性": "claim", "值": "GFM", "样式": "shell.claim"},
|
||||
map[string]any{"属性": "step", "值": "Open [New](/new) now.", "样式": "shell.step"},
|
||||
map[string]any{"属性": "step", "值": "Compare source.", "样式": "shell.step"},
|
||||
}
|
||||
callLib := func(path string) (any, error) {
|
||||
switch path {
|
||||
case "shell.kicker", "shell.intro_title", "shell.lede", "shell.claim", "shell.step":
|
||||
return map[string]any{
|
||||
"property": []any{"color"},
|
||||
"value": []any{"red"},
|
||||
}, nil
|
||||
default:
|
||||
t.Fatalf("unexpected callLib %q", path)
|
||||
return nil, nil
|
||||
}
|
||||
}
|
||||
out, err := compose.ComposeIntro(page, intro, callLib)
|
||||
if err != nil {
|
||||
t.Fatal(err)
|
||||
}
|
||||
obj := out.(map[string]any)
|
||||
html, _ := obj["intro"].(string)
|
||||
for _, want := range []string{
|
||||
`class="kicker"`,
|
||||
`<h1 class="intro_title">Marqdo</h1>`,
|
||||
`<code>JS</code>`,
|
||||
`<p class="claim">`,
|
||||
`<span class="claim">0 JS</span>`,
|
||||
`<ol class="steps">`,
|
||||
`<a href="/new">New</a>`,
|
||||
} {
|
||||
if !strings.Contains(html, want) {
|
||||
t.Fatalf("missing %q in html=%q", want, html)
|
||||
}
|
||||
}
|
||||
css, _ := obj["styles_css"].(string)
|
||||
if !strings.Contains(css, ".kicker") || !strings.Contains(css, ".intro_title") {
|
||||
t.Fatalf("styles_css incomplete: %q", css)
|
||||
}
|
||||
}
|
||||
|
||||
func TestMakeIntroHTMLZHAliases(t *testing.T) {
|
||||
tbl := []any{
|
||||
map[string]any{"属性": "眉题", "值": "演示", "样式": "kicker"},
|
||||
map[string]any{"属性": "标题", "值": "站名", "样式": "intro_title"},
|
||||
map[string]any{"属性": "标签", "值": "A", "样式": "claim"},
|
||||
map[string]any{"属性": "步骤", "值": "第一步", "样式": "step"},
|
||||
}
|
||||
html := compose.MakeIntroHTML(tbl)
|
||||
for _, want := range []string{
|
||||
`class="kicker"`,
|
||||
`<h1 class="intro_title">站名</h1>`,
|
||||
`<p class="claim">`,
|
||||
`<ol class="steps">`,
|
||||
} {
|
||||
if !strings.Contains(html, want) {
|
||||
t.Fatalf("missing %q in %q", want, html)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestComposeComponentsFakeCallLib(t *testing.T) {
|
||||
page := map[string]any{
|
||||
"title": "Home",
|
||||
|
||||
+101
-11
@@ -12,6 +12,7 @@ import (
|
||||
"time"
|
||||
|
||||
"github.com/marqdo/marqdo/plugins/web/internal/table"
|
||||
_ "github.com/jackc/pgx/v5/stdlib"
|
||||
_ "modernc.org/sqlite"
|
||||
)
|
||||
|
||||
@@ -54,13 +55,27 @@ func pathOf(url string) string {
|
||||
}
|
||||
|
||||
func open(url string) (*sql.DB, error) {
|
||||
path := pathOf(url)
|
||||
poolMu.Lock()
|
||||
defer poolMu.Unlock()
|
||||
key := ResolveURL(url)
|
||||
if db, ok := pool[key]; ok {
|
||||
return db, nil
|
||||
}
|
||||
if IsPostgres(url) {
|
||||
db, err := sql.Open("pgx", key)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
db.SetMaxOpenConns(16)
|
||||
db.SetMaxIdleConns(4)
|
||||
if err := db.Ping(); err != nil {
|
||||
_ = db.Close()
|
||||
return nil, fmt.Errorf("postgres ping: %w", err)
|
||||
}
|
||||
pool[key] = db
|
||||
return db, nil
|
||||
}
|
||||
path := pathOf(url)
|
||||
if parent := filepath.Dir(path); parent != "" && parent != "." {
|
||||
if err := os.MkdirAll(parent, 0o755); err != nil {
|
||||
return nil, err
|
||||
@@ -78,6 +93,12 @@ func open(url string) (*sql.DB, error) {
|
||||
return db, nil
|
||||
}
|
||||
|
||||
// OpenSQL returns a pooled *sql.DB (sqlite or postgres). Prefer OpenSQLDB when
|
||||
// issuing `?` placeholders against Postgres (RBAC).
|
||||
func OpenSQL(url string) (*sql.DB, error) {
|
||||
return open(url)
|
||||
}
|
||||
|
||||
// ResetPool closes pooled connections and open transactions (tests).
|
||||
func ResetPool() {
|
||||
resetTxns()
|
||||
@@ -117,6 +138,17 @@ func sqlType(t string) string {
|
||||
}
|
||||
}
|
||||
|
||||
func sqlTypeFor(url, t string) string {
|
||||
ty := sqlType(t)
|
||||
if IsPostgres(url) && ty == "REAL" {
|
||||
return "DOUBLE PRECISION"
|
||||
}
|
||||
if IsPostgres(url) && ty == "BLOB" {
|
||||
return "BYTEA"
|
||||
}
|
||||
return ty
|
||||
}
|
||||
|
||||
func cellStr(v any) string {
|
||||
switch t := v.(type) {
|
||||
case nil:
|
||||
@@ -236,11 +268,15 @@ func Init(url, name string, fields any) (map[string]any, error) {
|
||||
nullable := boolField(m, []string{"nullable", "可空"}, true)
|
||||
unique := boolField(m, []string{"unique", "唯一"}, false)
|
||||
index := boolField(m, []string{"index", "索引"}, false)
|
||||
col := fmt.Sprintf(`"%s" %s`, colName, sqlType(ty))
|
||||
col := fmt.Sprintf(`"%s" %s`, colName, sqlTypeFor(url, ty))
|
||||
if colName == "id" && !hasPK {
|
||||
col += " PRIMARY KEY"
|
||||
if sqlType(ty) == "INTEGER" {
|
||||
col += " AUTOINCREMENT"
|
||||
if IsPostgres(url) && sqlType(ty) == "INTEGER" {
|
||||
col = fmt.Sprintf(`"%s" INTEGER GENERATED BY DEFAULT AS IDENTITY PRIMARY KEY`, colName)
|
||||
} else {
|
||||
col += " PRIMARY KEY"
|
||||
if sqlType(ty) == "INTEGER" {
|
||||
col += " AUTOINCREMENT"
|
||||
}
|
||||
}
|
||||
hasPK = true
|
||||
} else if !nullable {
|
||||
@@ -292,7 +328,26 @@ func Init(url, name string, fields any) (map[string]any, error) {
|
||||
}, nil
|
||||
}
|
||||
|
||||
func columnNames(c dbConn, tableName string) ([]string, error) {
|
||||
func columnNames(c dbConn, tableName string, dbURL string) ([]string, error) {
|
||||
if IsPostgres(dbURL) {
|
||||
rows, err := c.Query(`
|
||||
SELECT column_name FROM information_schema.columns
|
||||
WHERE table_schema = current_schema() AND table_name = ?
|
||||
ORDER BY ordinal_position`, tableName)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer rows.Close()
|
||||
var out []string
|
||||
for rows.Next() {
|
||||
var name string
|
||||
if err := rows.Scan(&name); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
out = append(out, name)
|
||||
}
|
||||
return out, rows.Err()
|
||||
}
|
||||
rows, err := c.Query(fmt.Sprintf(`PRAGMA table_info("%s")`, tableName))
|
||||
if err != nil {
|
||||
return nil, err
|
||||
@@ -374,7 +429,7 @@ func Insert(url, tableName string, rows any, txnID ...string) (map[string]any, e
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
colsPresent, err := columnNames(c, tn)
|
||||
colsPresent, err := columnNames(c, tn, url)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
@@ -869,7 +924,7 @@ func Update(url, tableName, id string, row any, txnID ...string) (map[string]any
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
colsPresent, err := columnNames(c, tn)
|
||||
colsPresent, err := columnNames(c, tn, url)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
@@ -990,17 +1045,52 @@ type ColumnInfo struct {
|
||||
PK bool
|
||||
}
|
||||
|
||||
// TableInfo returns column metadata for a SQLite table.
|
||||
// TableInfo returns column metadata for a table (SQLite or Postgres).
|
||||
func TableInfo(url, tableName string) ([]ColumnInfo, error) {
|
||||
tn, err := ident(tableName)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
db, err := open(url)
|
||||
c, err := connFor(url, "")
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
rows, err := db.Query(fmt.Sprintf(`PRAGMA table_info("%s")`, tn))
|
||||
if IsPostgres(url) {
|
||||
rows, err := c.Query(`
|
||||
SELECT c.column_name, c.data_type, c.is_nullable,
|
||||
CASE WHEN tc.constraint_type = 'PRIMARY KEY' THEN 1 ELSE 0 END AS is_pk
|
||||
FROM information_schema.columns c
|
||||
LEFT JOIN information_schema.key_column_usage kcu
|
||||
ON c.table_schema = kcu.table_schema AND c.table_name = kcu.table_name AND c.column_name = kcu.column_name
|
||||
LEFT JOIN information_schema.table_constraints tc
|
||||
ON kcu.constraint_name = tc.constraint_name AND kcu.table_schema = tc.table_schema
|
||||
AND tc.constraint_type = 'PRIMARY KEY'
|
||||
WHERE c.table_schema = current_schema() AND c.table_name = ?
|
||||
ORDER BY c.ordinal_position`, tn)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
defer rows.Close()
|
||||
var out []ColumnInfo
|
||||
for rows.Next() {
|
||||
var name, dtype, nullable string
|
||||
var pk int
|
||||
if err := rows.Scan(&name, &dtype, &nullable, &pk); err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if dtype == "" {
|
||||
dtype = "TEXT"
|
||||
}
|
||||
out = append(out, ColumnInfo{
|
||||
Name: name,
|
||||
SQLType: dtype,
|
||||
NotNull: strings.EqualFold(nullable, "NO"),
|
||||
PK: pk != 0,
|
||||
})
|
||||
}
|
||||
return out, rows.Err()
|
||||
}
|
||||
rows, err := c.Query(fmt.Sprintf(`PRAGMA table_info("%s")`, tn))
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
|
||||
@@ -0,0 +1,144 @@
|
||||
package db
|
||||
|
||||
import (
|
||||
"database/sql"
|
||||
"strings"
|
||||
)
|
||||
|
||||
// IsPostgres reports whether url selects the Postgres backend.
|
||||
func IsPostgres(url string) bool {
|
||||
lower := strings.ToLower(strings.TrimSpace(url))
|
||||
return strings.HasPrefix(lower, "postgres://") || strings.HasPrefix(lower, "postgresql://")
|
||||
}
|
||||
|
||||
// RewritePlaceholdersPG turns `?` into `$1,$2,…` for Postgres.
|
||||
func RewritePlaceholdersPG(sqlStmt string) string {
|
||||
var b strings.Builder
|
||||
b.Grow(len(sqlStmt) + 8)
|
||||
n := 0
|
||||
for _, c := range sqlStmt {
|
||||
if c == '?' {
|
||||
n++
|
||||
b.WriteByte('$')
|
||||
b.WriteString(itoa(n))
|
||||
} else {
|
||||
b.WriteRune(c)
|
||||
}
|
||||
}
|
||||
return b.String()
|
||||
}
|
||||
|
||||
func itoa(n int) string {
|
||||
// small positive ints only
|
||||
if n < 10 {
|
||||
return string(rune('0' + n))
|
||||
}
|
||||
var buf [12]byte
|
||||
i := len(buf)
|
||||
for n > 0 {
|
||||
i--
|
||||
buf[i] = byte('0' + n%10)
|
||||
n /= 10
|
||||
}
|
||||
return string(buf[i:])
|
||||
}
|
||||
|
||||
// rewritingDB rewrites `?` placeholders when talking to Postgres.
|
||||
type rewritingDB struct {
|
||||
db *sql.DB
|
||||
pg bool
|
||||
}
|
||||
|
||||
func (d *rewritingDB) Exec(query string, args ...any) (sql.Result, error) {
|
||||
if d.pg {
|
||||
query = RewritePlaceholdersPG(query)
|
||||
}
|
||||
return d.db.Exec(query, args...)
|
||||
}
|
||||
|
||||
func (d *rewritingDB) Query(query string, args ...any) (*sql.Rows, error) {
|
||||
if d.pg {
|
||||
query = RewritePlaceholdersPG(query)
|
||||
}
|
||||
return d.db.Query(query, args...)
|
||||
}
|
||||
|
||||
func (d *rewritingDB) QueryRow(query string, args ...any) *sql.Row {
|
||||
if d.pg {
|
||||
query = RewritePlaceholdersPG(query)
|
||||
}
|
||||
return d.db.QueryRow(query, args...)
|
||||
}
|
||||
|
||||
func (d *rewritingDB) Begin() (*sql.Tx, error) {
|
||||
return d.db.Begin()
|
||||
}
|
||||
|
||||
func (d *rewritingDB) Underlying() *sql.DB { return d.db }
|
||||
|
||||
type rewritingTx struct {
|
||||
tx *sql.Tx
|
||||
pg bool
|
||||
}
|
||||
|
||||
func (t *rewritingTx) Exec(query string, args ...any) (sql.Result, error) {
|
||||
if t.pg {
|
||||
query = RewritePlaceholdersPG(query)
|
||||
}
|
||||
return t.tx.Exec(query, args...)
|
||||
}
|
||||
|
||||
func (t *rewritingTx) Query(query string, args ...any) (*sql.Rows, error) {
|
||||
if t.pg {
|
||||
query = RewritePlaceholdersPG(query)
|
||||
}
|
||||
return t.tx.Query(query, args...)
|
||||
}
|
||||
|
||||
func (t *rewritingTx) QueryRow(query string, args ...any) *sql.Row {
|
||||
if t.pg {
|
||||
query = RewritePlaceholdersPG(query)
|
||||
}
|
||||
return t.tx.QueryRow(query, args...)
|
||||
}
|
||||
|
||||
func (t *rewritingTx) Commit() error { return t.tx.Commit() }
|
||||
func (t *rewritingTx) Rollback() error { return t.tx.Rollback() }
|
||||
|
||||
// SQLDB is *sql.DB with optional Postgres `?` rewrite (RBAC / admin).
|
||||
type SQLDB interface {
|
||||
Exec(query string, args ...any) (sql.Result, error)
|
||||
Query(query string, args ...any) (*sql.Rows, error)
|
||||
QueryRow(query string, args ...any) *sql.Row
|
||||
Begin() (SQLTx, error)
|
||||
}
|
||||
|
||||
// SQLTx is a transaction with optional placeholder rewrite.
|
||||
type SQLTx interface {
|
||||
Exec(query string, args ...any) (sql.Result, error)
|
||||
Query(query string, args ...any) (*sql.Rows, error)
|
||||
QueryRow(query string, args ...any) *sql.Row
|
||||
Commit() error
|
||||
Rollback() error
|
||||
}
|
||||
|
||||
type sqlDBHandle struct {
|
||||
*rewritingDB
|
||||
}
|
||||
|
||||
func (h *sqlDBHandle) Begin() (SQLTx, error) {
|
||||
tx, err := h.rewritingDB.Begin()
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &rewritingTx{tx: tx, pg: h.pg}, nil
|
||||
}
|
||||
|
||||
// OpenSQLDB returns a pooled handle that rewrites `?` on Postgres.
|
||||
func OpenSQLDB(url string) (SQLDB, error) {
|
||||
raw, err := open(url)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &sqlDBHandle{rewritingDB: &rewritingDB{db: raw, pg: IsPostgres(url)}}, nil
|
||||
}
|
||||
@@ -23,14 +23,23 @@ type txnConn struct {
|
||||
}
|
||||
|
||||
func (t *txnConn) Exec(query string, args ...any) (sql.Result, error) {
|
||||
if IsPostgres(t.url) {
|
||||
query = RewritePlaceholdersPG(query)
|
||||
}
|
||||
return t.conn.ExecContext(context.Background(), query, args...)
|
||||
}
|
||||
|
||||
func (t *txnConn) Query(query string, args ...any) (*sql.Rows, error) {
|
||||
if IsPostgres(t.url) {
|
||||
query = RewritePlaceholdersPG(query)
|
||||
}
|
||||
return t.conn.QueryContext(context.Background(), query, args...)
|
||||
}
|
||||
|
||||
func (t *txnConn) QueryRow(query string, args ...any) *sql.Row {
|
||||
if IsPostgres(t.url) {
|
||||
query = RewritePlaceholdersPG(query)
|
||||
}
|
||||
return t.conn.QueryRowContext(context.Background(), query, args...)
|
||||
}
|
||||
|
||||
@@ -74,7 +83,11 @@ func connFor(url, txnID string) (dbConn, error) {
|
||||
}
|
||||
return t, nil
|
||||
}
|
||||
return open(url)
|
||||
raw, err := open(url)
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
return &rewritingDB{db: raw, pg: IsPostgres(url)}, nil
|
||||
}
|
||||
|
||||
func takeTxn(txnID string) (*txnConn, error) {
|
||||
@@ -98,7 +111,7 @@ func resetTxns() {
|
||||
}
|
||||
}
|
||||
|
||||
// Begin starts a SQLite transaction (BEGIN IMMEDIATE).
|
||||
// Begin starts a transaction (BEGIN IMMEDIATE on SQLite, BEGIN on Postgres).
|
||||
// Returns {"_type":"txn","txn":id,"url":url,"事务":id,"地址":url}.
|
||||
func Begin(url string) (map[string]any, error) {
|
||||
db, err := open(url)
|
||||
@@ -109,7 +122,11 @@ func Begin(url string) (map[string]any, error) {
|
||||
if err != nil {
|
||||
return nil, err
|
||||
}
|
||||
if _, err := conn.ExecContext(context.Background(), "BEGIN IMMEDIATE"); err != nil {
|
||||
beginSQL := "BEGIN IMMEDIATE"
|
||||
if IsPostgres(url) {
|
||||
beginSQL = "BEGIN"
|
||||
}
|
||||
if _, err := conn.ExecContext(context.Background(), beginSQL); err != nil {
|
||||
_ = conn.Close()
|
||||
return nil, err
|
||||
}
|
||||
|
||||
@@ -2,6 +2,7 @@
|
||||
package form
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"fmt"
|
||||
"strconv"
|
||||
"strings"
|
||||
@@ -17,6 +18,7 @@ var (
|
||||
typeKeys = []string{"类型", "type"}
|
||||
reqKeys = []string{"必填", "required"}
|
||||
defKeys = []string{"默认", "default"}
|
||||
sourceKeys = []string{"来源", "source"}
|
||||
ruleFieldKeys = []string{"字段", "field", "name"}
|
||||
ruleKeys = []string{"规则", "rule"}
|
||||
msgKeys = []string{"消息", "message", "msg"}
|
||||
@@ -45,6 +47,8 @@ func normalizeAction(action string) string {
|
||||
switch action {
|
||||
case "update", "更新":
|
||||
return "update"
|
||||
case "delete", "删除":
|
||||
return "delete"
|
||||
case "":
|
||||
return "insert"
|
||||
default:
|
||||
@@ -66,6 +70,24 @@ func SetRules(formBag map[string]any, rules any) map[string]any {
|
||||
return out
|
||||
}
|
||||
|
||||
// SetLabels stamps localized submit / cancel button copy (and optional cancel href).
|
||||
// When cancelHref is set, also stamps redirect so successful POST lands on the list
|
||||
// (or other cancel target) instead of the composing page's _mq_return path.
|
||||
func SetLabels(formBag map[string]any, submit, cancel, cancelHref string) map[string]any {
|
||||
out := cloneMap(formBag)
|
||||
if s := strings.TrimSpace(submit); s != "" {
|
||||
out["submit"] = s
|
||||
}
|
||||
if s := strings.TrimSpace(cancel); s != "" {
|
||||
out["cancel"] = s
|
||||
}
|
||||
if s := strings.TrimSpace(cancelHref); s != "" {
|
||||
out["cancel_href"] = s
|
||||
out["redirect"] = s
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func cloneMap(m map[string]any) map[string]any {
|
||||
out := map[string]any{}
|
||||
for k, v := range m {
|
||||
@@ -177,12 +199,19 @@ func asFormFields(fields any) []any {
|
||||
if v, ok := pick(m, defKeys); ok {
|
||||
def = cellStr(v)
|
||||
}
|
||||
source := "client"
|
||||
if v, ok := pick(m, sourceKeys); ok {
|
||||
if s := strings.TrimSpace(cellStr(v)); s != "" {
|
||||
source = s
|
||||
}
|
||||
}
|
||||
item := map[string]any{
|
||||
"name": name,
|
||||
"label": label,
|
||||
"type": ty,
|
||||
"required": required,
|
||||
"default": def,
|
||||
"source": normalizeSource(source),
|
||||
}
|
||||
if v, ok := m["pk"]; ok {
|
||||
item["pk"] = boolish(v)
|
||||
@@ -211,6 +240,10 @@ func asFormFields(fields any) []any {
|
||||
if v, ok := pick(t, defKeys); ok {
|
||||
defs = asStrList(v)
|
||||
}
|
||||
sources := []string{}
|
||||
if v, ok := pick(t, sourceKeys); ok {
|
||||
sources = asStrList(v)
|
||||
}
|
||||
var out []any
|
||||
for i, nameRaw := range names {
|
||||
name := table.NormalizeRef(nameRaw)
|
||||
@@ -233,12 +266,17 @@ func asFormFields(fields any) []any {
|
||||
if i < len(defs) {
|
||||
def = defs[i]
|
||||
}
|
||||
source := "client"
|
||||
if i < len(sources) && strings.TrimSpace(sources[i]) != "" {
|
||||
source = sources[i]
|
||||
}
|
||||
out = append(out, map[string]any{
|
||||
"name": name,
|
||||
"label": label,
|
||||
"type": ty,
|
||||
"required": required,
|
||||
"default": def,
|
||||
"source": normalizeSource(source),
|
||||
})
|
||||
}
|
||||
return out
|
||||
@@ -614,6 +652,11 @@ func strOf(m map[string]any, key, def string) string {
|
||||
|
||||
// RenderBody emits form markup only (no document shell).
|
||||
func RenderBody(formBag map[string]any, formID string, data, errors any, csrf string) string {
|
||||
return RenderBodyCtx(formBag, formID, data, errors, csrf, nil)
|
||||
}
|
||||
|
||||
// RenderBodyCtx is RenderBody plus request-context hidden fields for POST.
|
||||
func RenderBodyCtx(formBag map[string]any, formID string, data, errors any, csrf string, ctx *RequestContext) string {
|
||||
fields := fieldSlice(formBag)
|
||||
dataM := map[string]any{}
|
||||
if data != nil {
|
||||
@@ -646,6 +689,9 @@ func RenderBody(formBag map[string]any, formID string, data, errors any, csrf st
|
||||
if formBag != nil {
|
||||
rowID = cellStr(formBag["id"])
|
||||
}
|
||||
if rowID == "" {
|
||||
rowID = fieldText(dataM, "id")
|
||||
}
|
||||
showMeta := true
|
||||
if formBag != nil {
|
||||
if v, ok := formBag["show_meta"].(bool); ok {
|
||||
@@ -654,21 +700,28 @@ func RenderBody(formBag map[string]any, formID string, data, errors any, csrf st
|
||||
}
|
||||
|
||||
var body strings.Builder
|
||||
body.WriteString(`<div class="site-form">`)
|
||||
if showMeta {
|
||||
fmt.Fprintf(&body, `<p class="meta">table=<code>%s</code> · action=<code>%s</code> · id=<code>%s</code></p>`,
|
||||
esc(tableName), esc(action), esc(heading))
|
||||
}
|
||||
hasFile := false
|
||||
hasMarkdown := false
|
||||
for _, f := range fields {
|
||||
if fm, ok := f.(map[string]any); ok {
|
||||
ty, _ := fm["type"].(string)
|
||||
if strings.EqualFold(ty, "file") {
|
||||
hasFile = true
|
||||
break
|
||||
}
|
||||
if strings.EqualFold(ty, "markdown") {
|
||||
hasMarkdown = true
|
||||
}
|
||||
}
|
||||
}
|
||||
formClass := "site-form"
|
||||
if hasMarkdown {
|
||||
formClass += " editor-skin"
|
||||
}
|
||||
body.WriteString(`<div class="` + formClass + `">`)
|
||||
if showMeta {
|
||||
fmt.Fprintf(&body, `<p class="meta">table=<code>%s</code> · action=<code>%s</code> · id=<code>%s</code></p>`,
|
||||
esc(tableName), esc(action), esc(heading))
|
||||
}
|
||||
body.WriteString(`<form method="post" action="` + esc(postTo) + `"`)
|
||||
if hasFile {
|
||||
body.WriteString(` enctype="multipart/form-data"`)
|
||||
@@ -677,9 +730,32 @@ func RenderBody(formBag map[string]any, formID string, data, errors any, csrf st
|
||||
if csrf != "" {
|
||||
fmt.Fprintf(&body, `<input type="hidden" name="_csrf" value="%s"/>`, esc(csrf))
|
||||
}
|
||||
if action == "update" && rowID != "" {
|
||||
hasIDField := false
|
||||
for _, f := range fields {
|
||||
if fm, ok := f.(map[string]any); ok {
|
||||
if strOf(fm, "name", "") == "id" && IsClientSource(strOf(fm, "source", "client")) {
|
||||
hasIDField = true
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
if (action == "update" || action == "delete") && rowID != "" && !hasIDField {
|
||||
fmt.Fprintf(&body, `<input type="hidden" name="id" value="%s"/>`, esc(rowID))
|
||||
}
|
||||
if ctx != nil {
|
||||
if len(ctx.Params) > 0 {
|
||||
if b, err := json.Marshal(ctx.Params); err == nil {
|
||||
fmt.Fprintf(&body, `<input type="hidden" name="_mq_params" value="%s"/>`, esc(string(b)))
|
||||
}
|
||||
}
|
||||
ret := strings.TrimSpace(ctx.ReturnPath)
|
||||
if ret == "" {
|
||||
ret = strings.TrimSpace(ctx.Path)
|
||||
}
|
||||
if ret != "" && strings.HasPrefix(ret, "/") && !strings.HasPrefix(ret, "//") {
|
||||
fmt.Fprintf(&body, `<input type="hidden" name="_mq_return" value="%s"/>`, esc(ret))
|
||||
}
|
||||
}
|
||||
for _, f := range fields {
|
||||
fm, ok := f.(map[string]any)
|
||||
if !ok {
|
||||
@@ -689,6 +765,9 @@ func RenderBody(formBag map[string]any, formID string, data, errors any, csrf st
|
||||
if name == "" {
|
||||
continue
|
||||
}
|
||||
if !IsClientSource(strOf(fm, "source", "client")) {
|
||||
continue
|
||||
}
|
||||
label := strOf(fm, "label", name)
|
||||
ty := strOf(fm, "type", "text")
|
||||
required, _ := fm["required"].(bool)
|
||||
@@ -712,11 +791,26 @@ func RenderBody(formBag map[string]any, formID string, data, errors any, csrf st
|
||||
if required {
|
||||
reqAttr = " required"
|
||||
}
|
||||
if ty == "hidden" {
|
||||
fmt.Fprintf(&body, `<input type="hidden" name="%s" value="%s"/>`, esc(name), esc(value))
|
||||
continue
|
||||
}
|
||||
body.WriteString("<label>")
|
||||
body.WriteString(esc(label))
|
||||
if ty == "textarea" {
|
||||
fmt.Fprintf(&body, `<textarea name="%s" rows="5"%s>%s</textarea>`,
|
||||
esc(name), reqAttr, esc(value))
|
||||
if ty == "textarea" || ty == "markdown" {
|
||||
rows := "5"
|
||||
cls := ""
|
||||
if ty == "markdown" {
|
||||
rows = "18"
|
||||
cls = ` class="mq-markdown" data-mq-field="markdown"`
|
||||
body.WriteString(`<div class="md-field">`)
|
||||
fmt.Fprintf(&body, `<textarea name="%s" rows="%s"%s%s>%s</textarea>`,
|
||||
esc(name), rows, cls, reqAttr, esc(value))
|
||||
body.WriteString(`<div class="mq-md-preview md-pane-preview" aria-live="polite"></div></div>`)
|
||||
} else {
|
||||
fmt.Fprintf(&body, `<textarea name="%s" rows="%s"%s%s>%s</textarea>`,
|
||||
esc(name), rows, cls, reqAttr, esc(value))
|
||||
}
|
||||
} else {
|
||||
inputType := "text"
|
||||
switch ty {
|
||||
@@ -743,8 +837,28 @@ func RenderBody(formBag map[string]any, formID string, data, errors any, csrf st
|
||||
}
|
||||
body.WriteString("</label>")
|
||||
}
|
||||
fmt.Fprintf(&body, `<div class="actions"><button type="submit">Submit</button><a href="%s">cancel</a></div>`,
|
||||
esc(cancel))
|
||||
submitLabel := strOf(formBag, "submit", "")
|
||||
if submitLabel == "" {
|
||||
submitLabel = strOf(formBag, "提交", "")
|
||||
}
|
||||
if submitLabel == "" {
|
||||
submitLabel = "Submit"
|
||||
}
|
||||
cancelLabel := strOf(formBag, "cancel", "")
|
||||
if cancelLabel == "" {
|
||||
cancelLabel = strOf(formBag, "取消", "")
|
||||
}
|
||||
if cancelLabel == "" {
|
||||
cancelLabel = "cancel"
|
||||
}
|
||||
cancelHref := cancel
|
||||
if c := strOf(formBag, "cancel_href", ""); c != "" {
|
||||
cancelHref = c
|
||||
} else if c := strOf(formBag, "取消链接", ""); c != "" {
|
||||
cancelHref = c
|
||||
}
|
||||
fmt.Fprintf(&body, `<div class="actions"><button type="submit">%s</button><a href="%s">%s</a></div>`,
|
||||
esc(submitLabel), esc(cancelHref), esc(cancelLabel))
|
||||
body.WriteString(`</form></div>`)
|
||||
return body.String()
|
||||
}
|
||||
@@ -784,7 +898,7 @@ body{font-family:"IBM Plex Sans","Noto Sans SC",sans-serif;margin:1.5rem;backgro
|
||||
func Submit(formBag map[string]any, data any, dbURL string) (map[string]any, error) {
|
||||
action := strOf(formBag, "action", "insert")
|
||||
rowMap := dataMap(data)
|
||||
if action == "update" {
|
||||
if action == "update" || action == "delete" {
|
||||
if formBag != nil {
|
||||
if fid := cellStr(formBag["id"]); fid != "" {
|
||||
if _, ok := rowMap["id"]; !ok {
|
||||
@@ -793,14 +907,16 @@ func Submit(formBag map[string]any, data any, dbURL string) (map[string]any, err
|
||||
}
|
||||
}
|
||||
}
|
||||
v := Validate(formBag, nil, rowMap)
|
||||
ok, _ := v["ok"].(bool)
|
||||
if !ok {
|
||||
errs := v["errors"]
|
||||
if errs == nil {
|
||||
errs = []any{}
|
||||
if action != "delete" {
|
||||
v := Validate(formBag, nil, rowMap)
|
||||
ok, _ := v["ok"].(bool)
|
||||
if !ok {
|
||||
errs := v["errors"]
|
||||
if errs == nil {
|
||||
errs = []any{}
|
||||
}
|
||||
return map[string]any{"ok": false, "errors": errs}, nil
|
||||
}
|
||||
return map[string]any{"ok": false, "errors": errs}, nil
|
||||
}
|
||||
tableName := ""
|
||||
if formBag != nil {
|
||||
@@ -811,7 +927,20 @@ func Submit(formBag map[string]any, data any, dbURL string) (map[string]any, err
|
||||
}
|
||||
var result map[string]any
|
||||
var err error
|
||||
if action == "update" {
|
||||
switch action {
|
||||
case "delete":
|
||||
id := ""
|
||||
if formBag != nil {
|
||||
id = cellStr(formBag["id"])
|
||||
}
|
||||
if id == "" {
|
||||
id = cellStr(rowMap["id"])
|
||||
}
|
||||
if id == "" {
|
||||
return nil, fmt.Errorf("delete requires `id`")
|
||||
}
|
||||
result, err = db.Delete(dbURL, tableName, id)
|
||||
case "update":
|
||||
id := ""
|
||||
if formBag != nil {
|
||||
id = cellStr(formBag["id"])
|
||||
@@ -823,7 +952,7 @@ func Submit(formBag map[string]any, data any, dbURL string) (map[string]any, err
|
||||
return nil, fmt.Errorf("update requires `id`")
|
||||
}
|
||||
result, err = db.Update(dbURL, tableName, id, rowMap)
|
||||
} else {
|
||||
default:
|
||||
result, err = db.Insert(dbURL, tableName, []any{rowMap})
|
||||
}
|
||||
if err != nil {
|
||||
|
||||
@@ -68,3 +68,28 @@ func TestRenderContainsInputFields(t *testing.T) {
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func TestRenderMarkdownAndLabels(t *testing.T) {
|
||||
f := form.New("posts", "insert", "")
|
||||
f = form.SetFields(f, []any{
|
||||
map[string]any{"字段": "content", "标签": "正文", "类型": "markdown", "必填": true},
|
||||
})
|
||||
f = form.SetLabels(f, "发布文章", "返回列表", "/desk/posts")
|
||||
if f["redirect"] != "/desk/posts" || f["cancel_href"] != "/desk/posts" {
|
||||
t.Fatalf("labels should stamp redirect/cancel_href, got %#v %#v", f["redirect"], f["cancel_href"])
|
||||
}
|
||||
html := form.Render(f, "post", nil, nil, "")
|
||||
for _, want := range []string{
|
||||
`data-mq-field="markdown"`,
|
||||
`class="mq-markdown"`,
|
||||
`class="md-field"`,
|
||||
`mq-md-preview`,
|
||||
">发布文章</button>",
|
||||
`href="/desk/posts"`,
|
||||
">返回列表</a>",
|
||||
} {
|
||||
if !strings.Contains(html, want) {
|
||||
t.Fatalf("missing %q in:\n%s", want, html)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,128 @@
|
||||
package form
|
||||
|
||||
import (
|
||||
"encoding/json"
|
||||
"strings"
|
||||
"time"
|
||||
)
|
||||
|
||||
func normalizeSource(raw string) string {
|
||||
s := strings.TrimSpace(raw)
|
||||
if s == "" {
|
||||
return "client"
|
||||
}
|
||||
switch strings.ToLower(s) {
|
||||
case "client", "用户", "input", "form":
|
||||
return "client"
|
||||
case "user", "username", "session.user", "session.username", "用户名":
|
||||
return "session.username"
|
||||
case "now", "utc.now", "server.now", "时间", "utc":
|
||||
return "now"
|
||||
case "now_if_empty", "空则现在", "now?":
|
||||
return "now_if_empty"
|
||||
default:
|
||||
return s
|
||||
}
|
||||
}
|
||||
|
||||
// IsClientSource reports whether the field is filled by the browser.
|
||||
func IsClientSource(source string) bool {
|
||||
src := normalizeSource(source)
|
||||
return src == "client" || src == "now_if_empty"
|
||||
}
|
||||
|
||||
// RequestContext carries session user and route params for form source stamping
|
||||
// (design: ext-web-request-context.md). Domain-agnostic — no table-name branches.
|
||||
type RequestContext struct {
|
||||
Username string
|
||||
Params map[string]any
|
||||
ReturnPath string
|
||||
Path string
|
||||
Method string
|
||||
}
|
||||
|
||||
// ApplySources strips client-supplied values for non-client fields, then stamps
|
||||
// from ctx. Always overwrites server-owned keys. `now_if_empty` keeps a non-empty
|
||||
// client value and only stamps UTC now when the field was left blank.
|
||||
func ApplySources(formBag map[string]any, data map[string]any, ctx *RequestContext) {
|
||||
if data == nil {
|
||||
return
|
||||
}
|
||||
if ctx == nil {
|
||||
ctx = &RequestContext{}
|
||||
}
|
||||
for _, f := range fieldSlice(formBag) {
|
||||
fm, ok := f.(map[string]any)
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
name, _ := fm["name"].(string)
|
||||
if name == "" {
|
||||
continue
|
||||
}
|
||||
src := normalizeSource(strOf(fm, "source", "client"))
|
||||
switch src {
|
||||
case "client":
|
||||
continue
|
||||
case "now_if_empty":
|
||||
if data[name] != nil && strings.TrimSpace(cellStr(data[name])) != "" {
|
||||
continue
|
||||
}
|
||||
if v, ok := resolveSource("now", ctx); ok {
|
||||
data[name] = v
|
||||
}
|
||||
default:
|
||||
delete(data, name)
|
||||
if v, ok := resolveSource(src, ctx); ok {
|
||||
data[name] = v
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func resolveSource(src string, ctx *RequestContext) (any, bool) {
|
||||
src = normalizeSource(src)
|
||||
switch src {
|
||||
case "client":
|
||||
return nil, false
|
||||
case "session.username":
|
||||
if ctx.Username == "" {
|
||||
return nil, false
|
||||
}
|
||||
return ctx.Username, true
|
||||
case "now":
|
||||
return time.Now().UTC().Format("2006-01-02 15:04:05"), true
|
||||
}
|
||||
lower := strings.ToLower(src)
|
||||
for _, prefix := range []string{"route.", "param.", "params."} {
|
||||
if strings.HasPrefix(lower, prefix) {
|
||||
key := src[len(prefix):]
|
||||
if key == "" || ctx.Params == nil {
|
||||
return nil, false
|
||||
}
|
||||
if v, ok := ctx.Params[key]; ok {
|
||||
return v, true
|
||||
}
|
||||
for k, v := range ctx.Params {
|
||||
if strings.EqualFold(k, key) {
|
||||
return v, true
|
||||
}
|
||||
}
|
||||
return nil, false
|
||||
}
|
||||
}
|
||||
return nil, false
|
||||
}
|
||||
|
||||
// ParseMQParams decodes the hidden `_mq_params` JSON posted with forms.
|
||||
func ParseMQParams(raw string) map[string]any {
|
||||
raw = strings.TrimSpace(raw)
|
||||
if raw == "" {
|
||||
return nil
|
||||
}
|
||||
var out map[string]any
|
||||
if err := json.Unmarshal([]byte(raw), &out); err != nil {
|
||||
return nil
|
||||
}
|
||||
return out
|
||||
}
|
||||
Loaded 100 of 190 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user