Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
2e068e66d4 | ||
|
|
a4c346d4a2 | ||
|
|
fe14d1f7e3 | ||
|
|
f4b39dfe80 | ||
|
|
7d86ed1d9c | ||
|
|
506de65dae | ||
|
|
08384c7540 | ||
|
|
94ae6713aa | ||
|
|
838a2b425a | ||
|
|
1a5ee57a6f | ||
|
|
d539e6b96b | ||
|
|
3ade036d34 | ||
|
|
f3c49e86ae | ||
|
|
b2401b8458 | ||
|
|
51bb8767e3 | ||
|
|
c0fbe9b182 | ||
|
|
01287d9e7e | ||
|
|
70fb2fbfb2 | ||
|
|
b6f116108c | ||
|
|
03aca7cdac | ||
|
|
96da88e168 | ||
|
|
b6cceab218 | ||
|
|
95b16be714 | ||
|
|
d31ad79bc0 | ||
|
|
5745805a5d | ||
|
|
590f7a58fa | ||
|
|
027b19c5db | ||
|
|
7670673a39 | ||
|
|
824b9bf607 | ||
|
|
155183eb30 | ||
|
|
b10a84466b | ||
|
|
0aa0f47a9d | ||
|
|
5f91be7c21 | ||
|
|
e3e2cfa9d1 | ||
|
|
d1b4e62d4d | ||
|
|
ff1b846b73 | ||
|
|
ad47d4a0d2 | ||
|
|
c080b79c5b | ||
|
|
f19f614e0d | ||
|
|
8fbf617e05 | ||
|
|
a9d30cdf4a | ||
|
|
4c27c8afeb | ||
|
|
9d591674aa | ||
|
|
e40d21760a | ||
|
|
2445c290c9 | ||
|
|
04890e0c73 | ||
|
|
ab52db2037 | ||
|
|
aac896b044 | ||
|
|
fb037022ba | ||
|
|
a75b7a1c87 | ||
|
|
f2fd4fb34e | ||
|
|
2079577314 | ||
|
|
416914a346 |
No files matched your search
@@ -0,0 +1,144 @@
|
||||
---
|
||||
name: marqdo-dev
|
||||
description: >-
|
||||
Develop Marqdo programs and libraries the readable way: GFM tables as data,
|
||||
code-as-documentation, table.put over json.set chains, lib/ext authoring.
|
||||
Use when writing or refactoring .mq.md, creating lib/* or ext/*, reviewing
|
||||
Marqdo style, fixing unreadable json glue, or when the user asks how to
|
||||
develop Marqdo / 如何开发 marqdo.
|
||||
---
|
||||
|
||||
# Marqdo development (author + library)
|
||||
|
||||
Read this **before** writing or expanding `.mq.md`. Syntax basics stay in [marqdo](../marqdo/SKILL.md); this skill is the **style and library craft** contract.
|
||||
|
||||
## Non-negotiable: code is documentation
|
||||
|
||||
A `.mq.md` file must stay readable as Markdown. If a human cannot skim the data and intent without decoding nested `json.set` / `json.append` chains, the code is wrong.
|
||||
|
||||
| Prefer | Avoid |
|
||||
|--------|--------|
|
||||
| GFM tables for maps, lists, records, wire, commands | Building the same with `json.set` / `json.append` |
|
||||
| Named library helpers (`web.*`, `browser.*`, `table.*`) | Copy-paste effect-map glue in every handler |
|
||||
| `table.put` for **one** dynamic key | Long `json.set` pipelines |
|
||||
| `json.parse` / `json.stringify` / `json.quote` only | Using `json` as a general dict builder |
|
||||
|
||||
`lib/json` is for **parse / stringify / quote**. Collection edits use **GFM tables** and **`lib/table`** (`doc/design/stdlib-table.md`).
|
||||
|
||||
## How to shape data
|
||||
|
||||
### 1. GFM table geometry (memorize)
|
||||
|
||||
| Shape | Result |
|
||||
|-------|--------|
|
||||
| 1 column | list |
|
||||
| ≥2 columns, **one** data row | map (headers = keys) |
|
||||
| ≥2 columns, **many** rows | map of lists (column-oriented) |
|
||||
| First header `@` / `行` / `row` | **list of maps** (row records) |
|
||||
|
||||
Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = text, `` `var` `` = variable, quote paths/`/` ratios.
|
||||
|
||||
### 2. Good patterns
|
||||
|
||||
**Wire / steps / commands** — `@` record table:
|
||||
|
||||
```markdown
|
||||
`wire` =
|
||||
|
||||
| @ | 选择器 | 事件 | 调用 |
|
||||
|---|--------|------|------|
|
||||
| 1 | "#bump" | click | bump |
|
||||
```
|
||||
|
||||
**Multi-key return / boot** — map table with variable cells:
|
||||
|
||||
```markdown
|
||||
`boot` =
|
||||
|
||||
| wire | set_text |
|
||||
|------|----------|
|
||||
| `wire` | `set_text` |
|
||||
```
|
||||
|
||||
**Single dynamic key** — one `table.put` (or a helper), not a json chain:
|
||||
|
||||
```markdown
|
||||
*`set_text` = > table.put in=None at="#log" value=msg*
|
||||
**> table.put in=None at="set_text" value=set_text**
|
||||
```
|
||||
|
||||
Better still — call a named helper:
|
||||
|
||||
```markdown
|
||||
**> browser.set_text sel="#log" text=msg**
|
||||
```
|
||||
|
||||
### 3. Bad pattern (do not write)
|
||||
|
||||
```markdown
|
||||
*`ret` = > json.set map=None key="set_text" value=…*
|
||||
*`ret` = > json.set map=ret key="canvas" value=…*
|
||||
*`cmds` = > json.append list=cmds item=c0*
|
||||
```
|
||||
|
||||
## Writing application `.mq.md`
|
||||
|
||||
1. Frontmatter: title + imports (`table`, domain libs). **Do not import `json` unless parsing strings.**
|
||||
2. `# main`: state binds, then **tables** for wire/config, return boot map via table or helper.
|
||||
3. `##` handlers: short prose OK; data as tables; return via `browser.*` / `web.*` / one `table.put`.
|
||||
4. Blank line between comment paragraphs and code.
|
||||
5. Run `marqdo run path.mq.md` from repo root.
|
||||
|
||||
Browser client programs: prefer `import browser:lib/browser.mq.md` (no native plugin). Server sites: `ext/web` + GFM page/style tables.
|
||||
|
||||
## Developing libraries (`lib/*`, `ext/*`)
|
||||
|
||||
### Goals
|
||||
|
||||
- **Authors** see tables and short calls; **library** may hide `table.put` / host calls.
|
||||
- One concern per helper; name the effect (`set_text`, `canvas`, …), do not expose bag surgery.
|
||||
- EN + ZH pair when shipping user-facing libs (`lib/browser.mq.md` ↔ `lib/浏览器.mq.md`, `ext/web` ↔ `ext/web/网页.mq.md`).
|
||||
- `ext/**` never calls `host_*` — use plugins / public lib only (`doc/design/ext-agent.md`).
|
||||
|
||||
### Library checklist
|
||||
|
||||
- [ ] Public examples use **tables + helpers**, not json glue
|
||||
- [ ] Helpers documented with a one-line purpose above `##`
|
||||
- [ ] Defaults on `+` params; omit `None` fields in merged maps
|
||||
- [ ] No `json.set` chains in new code — use `table.put` / `table.merge` / GFM
|
||||
- [ ] `marqdo run` on a tiny demo under `examples/` or inline smoke
|
||||
|
||||
### Where helpers live
|
||||
|
||||
| Need | Place |
|
||||
|------|--------|
|
||||
| Browser effect maps (WASM client) | `lib/browser.mq.md` |
|
||||
| Site HTML / HTTP / DB | `ext/web` classes + compose from tables |
|
||||
| List/map primitives | `lib/table.mq.md` |
|
||||
| Parse JSON text | `lib/json.mq.md` only |
|
||||
|
||||
## Refactoring existing glue
|
||||
|
||||
When editing a file full of `json.set`:
|
||||
|
||||
1. Turn static structures into GFM tables.
|
||||
2. Replace repeated effect shapes with `browser.*` / `web.text_patch` / `web.dom_patch`.
|
||||
3. Leave at most sparse `table.put` for dynamic keys.
|
||||
4. Drop `import json:…` if unused.
|
||||
|
||||
## Anti-patterns
|
||||
|
||||
| Wrong | Right |
|
||||
|-------|-------|
|
||||
| `json.set` × N to build boot | GFM map table or `browser`/`web` helper |
|
||||
| `json.append` to build command list | `@` record table |
|
||||
| Dummy column to force a 1-key map | `table.put` or helper |
|
||||
| Importing `ext/web` only for `text_patch` in WASM | `lib/browser` (no native plugin) |
|
||||
| Unreadable nested maps as “clever” | Flatten into tables humans can read |
|
||||
|
||||
## Related
|
||||
|
||||
- Syntax: [marqdo/SKILL.md](../marqdo/SKILL.md) · [examples.md](../marqdo/examples.md)
|
||||
- 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)
|
||||
@@ -0,0 +1,166 @@
|
||||
---
|
||||
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 (CLI, stdlib, ext, public zip, VSIX, wasm notes), push
|
||||
tag, publish GitHub Release with detailed notes, and recover from network
|
||||
failures via proxy. Use when the user asks to release, cut a version, publish
|
||||
vX.Y.Z, ship a GitHub release, 发版, 发布新版本, or tag marqdo.
|
||||
---
|
||||
|
||||
# Marqdo release
|
||||
|
||||
Canonical release playbook for **cflmy/marqdo**. Read this skill **before** tagging or uploading assets. Details: [reference.md](reference.md).
|
||||
|
||||
## 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.
|
||||
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 Windows CLI + VSIX + zips. Local packaging is fallback / verification.
|
||||
7. After network errors: apply [reference.md § Proxy](reference.md); retry; do not silently skip uploads.
|
||||
|
||||
## Defaults (after version is confirmed)
|
||||
|
||||
Unless the user overrides, apply these automatically — **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) |
|
||||
| Deploy gh-pages after release | **no** (only if user asks) |
|
||||
|
||||
Phase 0 asks **only** for the next version (and optional overrides). Example ask:
|
||||
|
||||
> 当前最新是 **vA.B.C**。请指定下一个版本号(如 `0.3.2`)。其余按默认:同步扩展、立刻打 tag 发布、中英双语说明。
|
||||
|
||||
## 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`.
|
||||
|
||||
## Phase 1 — Preflight
|
||||
|
||||
Copy and track:
|
||||
|
||||
```
|
||||
Release progress:
|
||||
- [ ] Phase 0: version confirmed by user (TAG=…)
|
||||
- [ ] Phase 1: preflight green
|
||||
- [ ] Phase 2: docs + version bumps committed
|
||||
- [ ] Phase 3: extension branch (if needed)
|
||||
- [ ] Phase 4: main pushed; tag created & pushed
|
||||
- [ ] Phase 5: CI / assets / release notes verified
|
||||
- [ ] Phase 6: 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).
|
||||
|
||||
## 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:
|
||||
|
||||
```bash
|
||||
./scripts/build-public.sh
|
||||
# outputs under public/ (gitignored HTML); used by release zip / gh-pages
|
||||
```
|
||||
|
||||
Commit on `main` (HEREDOC message), e.g.:
|
||||
|
||||
```text
|
||||
release: vVER — <one-line highlight>
|
||||
|
||||
EOF
|
||||
```
|
||||
|
||||
Push `main`: `git push origin main` (with proxy/`all` perms if needed).
|
||||
|
||||
## Phase 3 — VS Code / Cursor extension
|
||||
|
||||
**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
|
||||
|
||||
```bash
|
||||
git tag -a "TAG" -m "TAG"
|
||||
git push origin "TAG"
|
||||
```
|
||||
|
||||
This runs `.github/workflows/release.yml` (Windows): CLI exe/zip, stdlib zip, ext zip, source zip, public zip, VSIX.
|
||||
|
||||
If tag push fails: [reference.md § Proxy](reference.md), retry once; then report.
|
||||
|
||||
## Phase 5 — Release notes & assets
|
||||
|
||||
1. Wait for Actions success: `gh run list --workflow=Release --limit 3` / open the run URL.
|
||||
2. Ensure GitHub Release for `TAG` exists with assets (workflow uses `softprops/action-gh-release`).
|
||||
3. **Rewrite release body** (workflow body is a stub) with **中英双语** — see [reference.md § Notes template](reference.md). `gh release edit TAG --notes-file …`.
|
||||
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.
|
||||
|
||||
Local Windows fallback: `scripts/release-full.ps1 -Tag TAG -Upload` (see script header).
|
||||
|
||||
## Phase 6 — Post-release
|
||||
|
||||
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.
|
||||
|
||||
## Failure matrix (short)
|
||||
|
||||
| Failure | Action |
|
||||
|---------|--------|
|
||||
| `gh` / git TLS or proxy `7890` refused | Unset bad proxy; use working `HTTP(S)_PROXY` or `required_permissions: ["all"]`; see reference |
|
||||
| Tag exists | Stop; ask user to bump or delete tag (no force on shared tags without explicit order) |
|
||||
| CI red | Fix on main, move tag only if user explicitly allows delete+re-push tag |
|
||||
| VSIX missing | Fetch `vscode-extension`, build locally, `gh release upload TAG dist/*.vsix` |
|
||||
| Partial assets | Re-run workflow or upload missing files only |
|
||||
|
||||
## 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.
|
||||
- Merge extension tree into `main`.
|
||||
@@ -0,0 +1,307 @@
|
||||
# Marqdo release — reference
|
||||
|
||||
Companion to [SKILL.md](SKILL.md). Use during a release; keep SKILL short.
|
||||
|
||||
## Detect versions (commands)
|
||||
|
||||
```bash
|
||||
# From repo root
|
||||
python3 .cursor/skills/marqdo-release/scripts/detect_version.py
|
||||
# or manually:
|
||||
git fetch --tags origin 2>/dev/null || true
|
||||
echo "Cargo: $(sed -n 's/^version = \"\(.*\)\"/\1/p' Cargo.toml | head -1)"
|
||||
echo "wasm: $(sed -n 's/^version = \"\(.*\)\"/\1/p' crates/marqdo-wasm/Cargo.toml | head -1)"
|
||||
echo "tags: $(git tag -l 'v*' --sort=-v:refname | head -3 | tr '\n' ' ')"
|
||||
gh release list --limit 3 2>/dev/null || true
|
||||
```
|
||||
|
||||
**SemVer guidance for the ask (do not choose for the user):**
|
||||
|
||||
| Kind | When |
|
||||
|------|------|
|
||||
| patch `x.y.(z+1)` | Fixes, docs, no public API / MQ surface break |
|
||||
| minor `x.(y+1).0` | New features (WASM route C, new ext APIs) backward compatible |
|
||||
| major `(x+1).0.0` | Breaking MQ / CLI / plugin ABI |
|
||||
|
||||
## Asset matrix (CI tag `v*`)
|
||||
|
||||
Produced by `.github/workflows/release.yml` on **windows-latest**:
|
||||
|
||||
| Asset | Role |
|
||||
|-------|------|
|
||||
| `marqdo-VER-x86_64-pc-windows-msvc.exe` | CLI (stdlib embedded) |
|
||||
| `marqdo-VER-x86_64-pc-windows-msvc.zip` | `marqdo.exe` + `lib/` |
|
||||
| `marqdo-VER-stdlib.zip` | `lib/` only |
|
||||
| `marqdo-VER-ext.zip` | Official `ext/` L1 |
|
||||
| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Prebuilt Windows plugins (`native/*.dll`) |
|
||||
| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Prebuilt Linux plugins (`native/lib*.so`) |
|
||||
| `marqdo-VER-source.zip` | `git archive` of tagged commit |
|
||||
| `marqdo-VER.vsix` | VS Code / Cursor (from branch `vscode-extension`) |
|
||||
| `marqdo-VER-public.zip` | Static user docs (`marqdo view output public`) |
|
||||
|
||||
Not CI-uploaded (document in notes): Linux/macOS build from source; WASM via `marqdo wasm build` → `dist/wasm/`.
|
||||
|
||||
## Doc sync checklist (Phase 2 detail)
|
||||
|
||||
### CHANGELOG.md
|
||||
|
||||
1. Ensure `## Unreleased` lists everything shipping.
|
||||
2. Rename to `## vVER — YYYY-MM-DD` (use release day in Asia/Shanghai unless user says otherwise).
|
||||
3. Add a short **Highlights** subsection (install snippet + 3–6 bullets).
|
||||
4. Insert empty:
|
||||
|
||||
```markdown
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
```
|
||||
|
||||
### README.md
|
||||
|
||||
Update every user-visible version pin, typically:
|
||||
|
||||
- Section title `## 现状(vVER)`
|
||||
- `### 如何使用最新 Marqdo(vVER)`
|
||||
- `git checkout vVER`
|
||||
- Release URL `…/releases/tag/vVER`
|
||||
|
||||
Keep install / `ext add` / plugin build instructions accurate for this release.
|
||||
|
||||
### `.cursor/skills/marqdo/SKILL.md`
|
||||
|
||||
- Sync hard rules / feature bullets that this release changes (e.g. WASM, web).
|
||||
- Do **not** dump full CHANGELOG into the skill.
|
||||
- If release-only process changed, point to `.cursor/skills/marqdo-release/`.
|
||||
|
||||
### `public/` (author Markdown sources)
|
||||
|
||||
User tutorials under `public/` (not generated HTML). Update when:
|
||||
|
||||
- New CLI (`marqdo wasm …`, `ext add`, `version`)
|
||||
- New tutorials (browser hello, web client embed)
|
||||
- Version badges / “requires vVER” lines
|
||||
|
||||
Then regenerate HTML for zip/pages:
|
||||
|
||||
```bash
|
||||
./scripts/build-public.sh
|
||||
# Windows: powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
HTML under `public/**/*.html` is typically gitignored — zip still ships from CI `marqdo view output public`.
|
||||
|
||||
### Workflow stub
|
||||
|
||||
Edit `.github/workflows/release.yml` `body:` **Highlights** so the first auto body matches this tag (agent still replaces with full notes via `gh release edit`).
|
||||
|
||||
### Roadmaps / ADRs
|
||||
|
||||
If this release closes a wave: set status Completed in `doc/roadmap/*`; leave ADRs immutable (link from CHANGELOG).
|
||||
|
||||
## Extension checklist (Phase 3 detail)
|
||||
|
||||
Branch policy: `doc/design/vscode-extension-commit.md`.
|
||||
|
||||
```bash
|
||||
git fetch origin vscode-extension
|
||||
git checkout vscode-extension
|
||||
# edit vscode-extension/package.json version → VER
|
||||
# npm ci && npm run compile
|
||||
git add vscode-extension/
|
||||
git commit -m "$(cat <<'EOF'
|
||||
vscode-extension: bump to VER for release
|
||||
|
||||
EOF
|
||||
)"
|
||||
git push origin vscode-extension
|
||||
git checkout main
|
||||
```
|
||||
|
||||
Local VSIX only (fallback):
|
||||
|
||||
```bash
|
||||
git fetch origin vscode-extension
|
||||
git checkout origin/vscode-extension -- vscode-extension
|
||||
(cd vscode-extension && npm ci && npm run compile && npx @vscode/vsce package --no-dependencies -o "../dist/marqdo-VER.vsix")
|
||||
# cleanup ignored tree if desired
|
||||
gh release upload "vVER" "dist/marqdo-VER.vsix" --clobber
|
||||
```
|
||||
|
||||
## Defaults (mirror of SKILL)
|
||||
|
||||
| Setting | Default |
|
||||
|---------|---------|
|
||||
| Sync `vscode-extension` to `VER` | yes |
|
||||
| Push main + annotated tag immediately | yes |
|
||||
| Release notes | 中英双语 |
|
||||
| Skip VSIX / docs-only / deploy pages | no |
|
||||
|
||||
Phase 0 asks **only** for the next version unless the user wants overrides.
|
||||
|
||||
## Notes template (中英双语 — default)
|
||||
|
||||
Save as `/tmp/marqdo-vVER-notes.md` then:
|
||||
|
||||
```bash
|
||||
gh release edit "vVER" --notes-file /tmp/marqdo-vVER-notes.md
|
||||
```
|
||||
|
||||
```markdown
|
||||
## Marqdo vVER
|
||||
|
||||
### 亮点 / Highlights
|
||||
|
||||
- **中文** … / **EN** …
|
||||
- …
|
||||
|
||||
### 安装 / Install
|
||||
|
||||
```bash
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout vVER
|
||||
cargo build --release
|
||||
./target/release/marqdo version
|
||||
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
|
||||
marqdo ext add web && marqdo ext add agent && marqdo ext add quantum
|
||||
# 中文 id:网页 / 智能体 / 量子
|
||||
```
|
||||
|
||||
**浏览器 WASM / Browser WASM**
|
||||
|
||||
```bash
|
||||
marqdo wasm build
|
||||
# → dist/wasm/marqdo_wasm_bg.wasm + marqdo-bridge.js
|
||||
# examples: examples/browser-hello/
|
||||
```
|
||||
|
||||
### 破坏性变更 / Breaking changes
|
||||
|
||||
- 无 / None
|
||||
- …
|
||||
|
||||
### 下载 / Downloads
|
||||
|
||||
| Asset | 内容 / Contents |
|
||||
|-------|-----------------|
|
||||
| `marqdo-*-windows-msvc.exe` | CLI(内置 stdlib) |
|
||||
| `marqdo-*-windows-msvc.zip` | exe + `lib/` |
|
||||
| `marqdo-*-stdlib.zip` | 仅 `lib/` |
|
||||
| `marqdo-*-ext.zip` | 官方 `ext/` |
|
||||
| `marqdo-*-source.zip` | 源码快照 |
|
||||
| `marqdo-*.vsix` | VS Code / Cursor 扩展 |
|
||||
| `marqdo-*-public.zip` | 用户文档站 |
|
||||
|
||||
扩展源码分支 / Extension branch: **`vscode-extension`** ([policy](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension-commit.md)).
|
||||
|
||||
### 链接 / Links
|
||||
|
||||
- [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md)
|
||||
- [README](https://github.com/cflmy/marqdo/blob/main/README.md)
|
||||
```
|
||||
|
||||
## Proxy & auth (network recovery)
|
||||
|
||||
Symptoms seen in this project: broken local proxy on `127.0.0.1:7890`, TLS failures, `gh` needing token, Cursor sandbox blocking git/gh.
|
||||
|
||||
### Diagnose
|
||||
|
||||
```bash
|
||||
env | grep -iE 'proxy|PROXY' || true
|
||||
curl -sI https://github.com | head -5
|
||||
gh auth status
|
||||
```
|
||||
|
||||
### Fix order
|
||||
|
||||
1. **Unset bad proxy** if connection refused:
|
||||
|
||||
```bash
|
||||
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy
|
||||
```
|
||||
|
||||
2. **Set a working proxy** only if the user provides one (or known working):
|
||||
|
||||
```bash
|
||||
export HTTPS_PROXY=http://HOST:PORT
|
||||
export HTTP_PROXY=http://HOST:PORT
|
||||
```
|
||||
|
||||
3. **Agent Shell**: retry `git push` / `gh` with `required_permissions: ["all"]` (and `full_network` if needed).
|
||||
|
||||
4. **`gh` auth**: if `gh auth status` fails, ask user to `gh auth login` or set `GH_TOKEN` / `GITHUB_TOKEN` for the session — **never commit tokens**. Fallback used in this repo: load password from `git credential fill` (`protocol=https` / `host=github.com`) into `GH_TOKEN` for the session only, then delete the temp env file.
|
||||
|
||||
5. **Git remote**: prefer `https://github.com/cflmy/marqdo.git`; SSH needs keys.
|
||||
|
||||
6. **Partial upload**:
|
||||
|
||||
```bash
|
||||
gh release upload "vVER" dist/FILE --clobber
|
||||
```
|
||||
|
||||
7. **Re-run CI** without retagging (if tag already correct):
|
||||
|
||||
```bash
|
||||
gh workflow run Release --ref "vVER" # only if workflow_dispatch exists; else fix + new patch tag
|
||||
```
|
||||
|
||||
Current Release workflow is **tag-push only**. Red CI after tag → fix on `main`, then either new patch tag or **user-approved** delete+recreate tag (dangerous; prefer patch).
|
||||
|
||||
## Local Windows fallback
|
||||
|
||||
```powershell
|
||||
powershell -File ./scripts/release-full.ps1 -Tag vVER -Upload
|
||||
# -SkipVsix / -SkipPublic / -DeployPages as needed
|
||||
```
|
||||
|
||||
Also: `scripts/release-windows.ps1`, `scripts/publish-release.py` if present.
|
||||
|
||||
## Commit message style
|
||||
|
||||
```text
|
||||
release: vVER — <highlight>
|
||||
|
||||
```
|
||||
|
||||
Extension:
|
||||
|
||||
```text
|
||||
vscode-extension: bump to VER for release
|
||||
|
||||
```
|
||||
|
||||
## Pre-tag test suggestions
|
||||
|
||||
Minimum:
|
||||
|
||||
```bash
|
||||
cargo test --test gold structure_hello
|
||||
./target/release/marqdo version # after cargo build --release
|
||||
```
|
||||
|
||||
Stronger (time permitting):
|
||||
|
||||
```bash
|
||||
cargo test --test gold
|
||||
cargo test -p marqdo-wasm -- --nocapture # if wasm tests exist
|
||||
# optional Node: node tests/wasm/smoke.mjs after marqdo wasm build
|
||||
```
|
||||
|
||||
## Ask-user prompt (copy)
|
||||
|
||||
```text
|
||||
版本探测结果:
|
||||
- Cargo.toml: A.B.C
|
||||
- crates/marqdo-wasm: …
|
||||
- 最新 git tag: v…
|
||||
- 最新 GitHub Release: v…
|
||||
- CHANGELOG Unreleased: 有 / 无(摘要:…)
|
||||
|
||||
请指定下一个版本号(例如 0.3.2)。
|
||||
默认(无需确认):同步 vscode-extension 同号、立刻 push tag 发版、发布说明中英双语。
|
||||
若要改默认请一并说明。
|
||||
```
|
||||
+76
@@ -0,0 +1,76 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Detect Marqdo version sources for release Phase 0. Never invent next SemVer."""
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from pathlib import Path
|
||||
|
||||
# …/marqdo/.cursor/skills/marqdo-release/scripts/this.py → parents[4] = repo root
|
||||
ROOT = Path(__file__).resolve().parents[4]
|
||||
|
||||
|
||||
def cargo_version(path: Path) -> str | None:
|
||||
if not path.is_file():
|
||||
return None
|
||||
m = re.search(r'^version\s*=\s*"([^"]+)"', path.read_text(encoding="utf-8"), re.M)
|
||||
return m.group(1) if m else None
|
||||
|
||||
|
||||
def run(cmd: list[str]) -> str:
|
||||
try:
|
||||
out = subprocess.check_output(cmd, cwd=ROOT, stderr=subprocess.DEVNULL, text=True)
|
||||
return out.strip()
|
||||
except (subprocess.CalledProcessError, FileNotFoundError):
|
||||
return ""
|
||||
|
||||
|
||||
def main() -> int:
|
||||
cargo = cargo_version(ROOT / "Cargo.toml")
|
||||
wasm = cargo_version(ROOT / "crates" / "marqdo-wasm" / "Cargo.toml")
|
||||
tags = run(["git", "tag", "-l", "v*", "--sort=-v:refname"])
|
||||
latest_tag = tags.splitlines()[0] if tags else "(none)"
|
||||
gh_list = run(["gh", "release", "list", "--limit", "3"])
|
||||
latest_gh = "(gh unavailable)"
|
||||
if gh_list:
|
||||
# first column is tag name for `gh release list`
|
||||
latest_gh = gh_list.splitlines()[0].split("\t")[0].strip()
|
||||
|
||||
changelog = ROOT / "CHANGELOG.md"
|
||||
unreleased = False
|
||||
unreleased_preview = ""
|
||||
if changelog.is_file():
|
||||
text = changelog.read_text(encoding="utf-8")
|
||||
m = re.search(r"^## Unreleased\s*\n(.*?)(?=^## |\Z)", text, re.M | re.S)
|
||||
if m:
|
||||
body = m.group(1).strip()
|
||||
# nonempty if any bullet or non-heading content beyond empty section headers
|
||||
content_lines = [
|
||||
ln
|
||||
for ln in body.splitlines()
|
||||
if ln.strip() and not re.match(r"^###\s+", ln.strip())
|
||||
]
|
||||
unreleased = bool(content_lines)
|
||||
unreleased_preview = " | ".join(content_lines[:3])[:200]
|
||||
|
||||
print("=== Marqdo version detect (do NOT invent next; ask the user) ===")
|
||||
print(f"repo: {ROOT}")
|
||||
print(f"Cargo.toml: {cargo or '(missing)'}")
|
||||
print(f"marqdo-wasm: {wasm or '(missing)'}")
|
||||
print(f"latest git tag: {latest_tag}")
|
||||
print(f"latest gh release: {latest_gh}")
|
||||
print(f"Unreleased notes: {'YES' if unreleased else 'NO/empty'}")
|
||||
if unreleased_preview:
|
||||
print(f"Unreleased peek: {unreleased_preview}")
|
||||
if cargo and latest_tag.lstrip("v") != cargo:
|
||||
print("WARN: Cargo version != latest tag (expected during pre-bump or lag)")
|
||||
if cargo and wasm and cargo != wasm:
|
||||
print("WARN: root Cargo.toml and marqdo-wasm versions differ — sync before release")
|
||||
print()
|
||||
print("ASK USER: next SemVer X.Y.Z (tag will be vX.Y.Z)")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -4,10 +4,11 @@ description: >-
|
||||
Author and edit Marqdo programs (.mq.md): Markdown markers are executable
|
||||
syntax (functions, calls, statements, returns, control flow). Use when writing
|
||||
or modifying .mq.md files, teaching Marqdo, generating Marqdo from prose,
|
||||
importing lib/* or ext/web or ext/quantum, running marqdo CLI, building dynamic
|
||||
sites with ext/web, quantum circuits with ext/quantum, or when the user
|
||||
mentions Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, or
|
||||
quantum/量子 extension.
|
||||
importing lib/* or ext/web or ext/quantum or ext/linalg, running marqdo CLI,
|
||||
building dynamic sites with ext/web, quantum circuits with ext/quantum,
|
||||
formula-first linear algebra with ext/linalg, or when the user mentions
|
||||
Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, quantum/量子,
|
||||
or linalg/线性代数 extension.
|
||||
---
|
||||
|
||||
# Marqdo development
|
||||
@@ -16,6 +17,10 @@ Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation a
|
||||
|
||||
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
|
||||
|
||||
**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.
|
||||
|
||||
## Hard rules (do not violate)
|
||||
|
||||
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
|
||||
@@ -24,9 +29,12 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
|
||||
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are **variables** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
|
||||
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
|
||||
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed.
|
||||
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division.
|
||||
8. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
|
||||
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
|
||||
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
|
||||
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug.
|
||||
|
||||
|
||||
## Markup → meaning (v0.2)
|
||||
|
||||
@@ -134,13 +142,27 @@ import clock:lib/time.mq.md
|
||||
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
|
||||
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
|
||||
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — document-driven agents: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)); **`ext/web`** — dynamic sites (W0–W7 + P3 complete; see below); **`ext/quantum`** — circuits + Q7 density/viz + Q8 themed SVG (see below).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum|linalg` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below); **`ext/linalg`** — formula-first linear algebra (see below).
|
||||
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
|
||||
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`).
|
||||
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
|
||||
|
||||
Stdlib map: [reference.md](reference.md).
|
||||
|
||||
## Official extension: `ext/agent` (document-driven)
|
||||
|
||||
Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --release -p marqdo_plugin_agent`.
|
||||
|
||||
**Constitution (do not dilute):**
|
||||
|
||||
1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag.
|
||||
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
|
||||
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only.
|
||||
|
||||
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import).
|
||||
|
||||
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
|
||||
|
||||
## Official extension: `ext/web` (dynamic sites)
|
||||
|
||||
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin first: `cargo build --release -p marqdo_plugin_web`.
|
||||
@@ -154,6 +176,7 @@ Import **one language file** — never mix EN/ZH API names in the same `.mq.md`:
|
||||
|
||||
- Authors use **GFM tables + `#` classes** — no `json.parse` / `json.set` glue, no hand-built part JSON.
|
||||
- Table cells stay **literal strings**; path text like `` `posts`.`title` `` is resolved by web classes.
|
||||
- **Quote path/MIME cells** that contain `/` (T5 cell expressions treat bare `/` as division): `"/static/logo.svg"`, `"image/png"`.
|
||||
- **`ext/**` never calls `host_*`** — hot path is native `plugins/web` ABI.
|
||||
- HTTPS: terminate at reverse proxy; set `cookie_secure=True` on auth (no in-process TLS).
|
||||
|
||||
@@ -164,17 +187,18 @@ index.mq.md # entry + home page table + listen
|
||||
pages/ # sub-pages
|
||||
components/ # reusable |属性|值|样式| tables
|
||||
styles/ # CSS modules
|
||||
public/ # static + favicon.ico|png|svg
|
||||
db/ # schema + open/init
|
||||
data/ # sqlite runtime (gitignore)
|
||||
```
|
||||
|
||||
**Core objects (EN / ZH):** `# page`/`页面`, `# style`/`样式`, `# db`/`数据库`, `# form`/`表单`, `# app`/`应用`, `# auth`/`鉴权`, `# cache`/`缓存`, `# storage`/`存储`.
|
||||
|
||||
**Typical flow:** `db.init` → `page.compose_components` + `page.compose_main` → `page.render` → `app` with `route` / `static` / `configure` / `listen`.
|
||||
**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):** 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.
|
||||
**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`).
|
||||
|
||||
Design: [ext-web.md](../../doc/design/ext-web.md) · capability matrix: [web-net-capabilities.md](../../doc/design/web-net-capabilities.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
|
||||
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/).
|
||||
|
||||
Web patterns: [examples.md](examples.md) §13 · API index: [reference.md](reference.md).
|
||||
|
||||
@@ -202,6 +226,19 @@ Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --relea
|
||||
|
||||
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
|
||||
|
||||
## Official extension: `ext/linalg` (formula-first LA)
|
||||
|
||||
Install: `marqdo ext add linalg` (ZH id: `线性代数`). Build: `cargo build --release -p marqdo_plugin_linalg`, then **`marqdo ext add linalg` again** so view loads the new native lib.
|
||||
|
||||
- EN: `import la:ext/linalg/linalg.mq.md`
|
||||
- ZH: `导入 la:ext/linalg/线性代数.mq.md`
|
||||
|
||||
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; prefer top-level `la.symbol` (not `matrix.symbol` without a receiver); quote `kind=` strings; dense `explicit` / factorize obey size guards.
|
||||
|
||||
APIs (EN): `symbol` → `# matrix`;中缀 `+`/`-`/`*`;方法 `` `A`.T `` / ``.simplify`` / ``.ascii`` · `from_formula` / `explicit` / `factorize` / `draw` · `lstsq` / `norm` / `cond` / `rank`.
|
||||
|
||||
Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../../examples/linalg-least-squares/). Design: [ext-linalg.md](../../doc/design/ext-linalg.md) · formula-doc: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
|
||||
|
||||
## AI authoring workflow
|
||||
|
||||
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
@@ -223,11 +260,14 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
|
||||
| Forgetting `---` after nested `##` helper | Add `---` / `***` / `****` |
|
||||
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
|
||||
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
|
||||
| `json.set` / `json.append` to build maps or lists | GFM tables; sparse `table.put`; named helpers (`browser.*`, `web.*`) |
|
||||
| `json.set` to build page parts | GFM tables + `page.compose_*` / `web.page` methods |
|
||||
| Import `json` for every browser handler | `import browser:lib/browser.mq.md` + tables ([marqdo-dev](../marqdo-dev/SKILL.md)) |
|
||||
| Mix `web.page` and `网页.页面` in one file | One import language per `.mq.md` |
|
||||
| Call `host_web_*` from `ext/web` | Use `# app` / `# db` methods; plugin ABI only |
|
||||
| Call `host_*` from `ext/quantum` | Use `# circuit` / `# density` methods; plugin ABI only |
|
||||
| Bare `kind=hinton` inside `*…*` | `kind="hinton"` — quote text literals |
|
||||
| Call `host_*` from `ext/linalg` | Use `la.*` L1 wrappers; plugin ABI only |
|
||||
| Bare `kind=eig` inside `*…*` | `kind="eig"` — quote text literals |
|
||||
| Bare `theme=dark` inside `*…*` | `theme="dark"` — quote; ZH `主题="dark"` |
|
||||
| Rebuild plugin but skip `ext add` | `cargo build -p marqdo_plugin_quantum` then `marqdo ext add quantum` (or set `MARQDO_QUANTUM_PLUGIN`) |
|
||||
|
||||
@@ -239,6 +279,8 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
|
||||
- [ ] `# main` exists when the file is an entry program
|
||||
- [ ] Nested functions ended with `---` / `***` / `****` when needed
|
||||
- [ ] Imports and call names share the same language file
|
||||
- [ ] Data shaped as **GFM tables** (or short helpers) — no `json.set` / `json.append` glue
|
||||
- [ ] Web sites: tables + web classes only (no JSON glue); `data/` gitignored
|
||||
- [ ] 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)
|
||||
@@ -78,6 +78,7 @@ Greeting via a nested function:
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
|
||||
## 6b. Map table + footnote get
|
||||
|
||||
```markdown
|
||||
@@ -109,6 +110,31 @@ Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of ma
|
||||
*名 = 订单[^1][^品名]*
|
||||
```
|
||||
|
||||
## 6c. Browser effects — tables + lib/browser (not json.set)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import browser:lib/browser.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`wire` =
|
||||
|
||||
| @ | 选择器 | 事件 | 调用 |
|
||||
|---|--------|------|------|
|
||||
| 1 | "#bump" | click | bump |
|
||||
|
||||
**`wire`**
|
||||
|
||||
## bump
|
||||
*`count` = count + 1*
|
||||
*`label` = > str count*
|
||||
**> browser.set_text sel="#count" text=label**
|
||||
```
|
||||
|
||||
Do **not** build effect maps with `json.set` chains. See [marqdo-dev](../marqdo-dev/SKILL.md).
|
||||
|
||||
## 7. Import text stdlib
|
||||
|
||||
```markdown
|
||||
@@ -123,6 +149,39 @@ import text:lib/text.mq.md
|
||||
> print text=`parts`
|
||||
```
|
||||
|
||||
## 7b. Mid M1 — regex + encoding (no plugin)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import re:lib/re.mq.md
|
||||
import enc:lib/encoding.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`ok` = > re.is_match text="a@b.c" pattern="@"*
|
||||
*`b64` = > enc.base64_encode text="hi"*
|
||||
> print text=`ok`
|
||||
> print text=`b64`
|
||||
```
|
||||
|
||||
## 7c. Mid M6 — log + uuid
|
||||
|
||||
```markdown
|
||||
---
|
||||
import log:lib/log.mq.md
|
||||
import uuid:lib/uuid.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> log.info text="start"
|
||||
> log.set_level level="debug"
|
||||
> log.debug text="detail"
|
||||
*id = > uuid.v4*
|
||||
> print text=`id`
|
||||
```
|
||||
|
||||
## 8. Comment paragraphs (blank-line rule)
|
||||
|
||||
```markdown
|
||||
@@ -300,3 +359,31 @@ import quantum:ext/quantum/quantum.mq.md
|
||||
- Full lab: `examples/quantum-entanglement/`. Bell-only: `examples/quantum-bell/`.
|
||||
- `theme="dark"|"light"|"bw"` (default dark) on `circuit` / `probs` / `bloch`. Quote `kind=` / `theme=`.
|
||||
- After rebuilding the plugin: `marqdo ext add quantum` so view loads the new native lib.
|
||||
|
||||
## 15. Linear algebra (ext/linalg)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`A` = > la.symbol name="A" rows=2 cols=2*
|
||||
*`B` = > la.symbol name="B" rows=2 cols=2*
|
||||
*`C` = `A` + `B`*
|
||||
*`P` = `A` * `B`*
|
||||
*`s` = > `P`.T.simplify* <!-- prefer: *`Pt` = > `P`.T* then simplify -->
|
||||
```
|
||||
|
||||
Prefer:
|
||||
|
||||
```markdown
|
||||
*`env` = > la.declare table=`shapes`*
|
||||
*`P` = env[^A] * env[^B]*
|
||||
*`t` = > `P`.T_ascii*
|
||||
```
|
||||
|
||||
- Infix `+` / `-` / `*`;`ascii` / `T_ascii` 默认化简(`raw=True` 可关)。
|
||||
- Formula-doc design: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
|
||||
- Examples: `examples/linalg-transpose/`, `examples/linalg-svd/`, `examples/linalg-least-squares/`.
|
||||
@@ -12,8 +12,8 @@ marqdo view PATH # docs browser, default port 7429
|
||||
marqdo debug PATH # debugger UI, default port 7430
|
||||
marqdo catalog PATH -o .marqdo
|
||||
marqdo ext list
|
||||
marqdo ext add llm|agent|web|quantum
|
||||
marqdo ext remove llm|agent|web|quantum
|
||||
marqdo ext add llm|agent|web|quantum|linalg
|
||||
marqdo ext remove llm|agent|web|quantum|linalg
|
||||
```
|
||||
|
||||
Diagnostics look like `path:line:col: message` (1-based line/col).
|
||||
@@ -44,18 +44,29 @@ Import one file; use **that** file’s function names.
|
||||
|-----------|-----------|-------------------------|
|
||||
| `lib/text.mq.md` | `lib/文本.mq.md` | text helpers / 去空白·拆分·拼接… |
|
||||
| `lib/table.mq.md` | `lib/表.mq.md` | `put`/`改` + list/map(见 `doc/design/stdlib-table.md`) |
|
||||
| `lib/re.mq.md` | `lib/正则.mq.md` | Mid:`is_match`/`find`/`replace`/… |
|
||||
| `lib/encoding.mq.md` | `lib/编码.mq.md` | Mid:base64/hex |
|
||||
| `lib/path.mq.md` | `lib/路径.mq.md` | Mid:join/normalize/… |
|
||||
| `lib/hash.mq.md` | `lib/哈希.mq.md` | Mid:sha256/hmac/… |
|
||||
| `lib/secrets.mq.md` | `lib/机密.mq.md` | Mid:token_hex/urlsafe |
|
||||
| `lib/csv.mq.md` | `lib/逗号表.mq.md` | Mid:parse/stringify |
|
||||
| `lib/cli.mq.md` | `lib/命令行.mq.md` | Mid:`parse` flags |
|
||||
| `lib/log.mq.md` | `lib/日志.mq.md` | Mid:level-filtered one-line logs |
|
||||
| `lib/uuid.mq.md` | `lib/标识.mq.md` | Mid:UUID v4 |
|
||||
| `lib/browser.mq.md` | `lib/浏览器.mq.md` | WASM client effect helpers(GFM + `set_text`/`canvas`/…;见 marqdo-dev) |
|
||||
| `lib/fs.mq.md` | `lib/文件.mq.md` | filesystem |
|
||||
| `lib/sys.mq.md` | `lib/系统.mq.md` | process / cwd / load_dotenv |
|
||||
| `lib/plugin.mq.md` | `lib/插件.mq.md` | load native ABI plugins (`doc/design/ext-abi.md`) |
|
||||
| `lib/time.mq.md` | `lib/时间.mq.md` | time/format |
|
||||
| `lib/net.mq.md` | `lib/网络.mq.md` | HTTP(S) helpers (+ optional headers) |
|
||||
| `lib/json.mq.md` | (see design) | JSON (+ `quote`) |
|
||||
| `lib/json.mq.md` | (see design) | **parse / stringify / quote only** — not a dict builder |
|
||||
| `lib/math.mq.md` | `lib/数学.mq.md` | num, trig, random, formula, plot |
|
||||
| `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks |
|
||||
| `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods |
|
||||
| `ext/agent.mq.md` | `ext/智能体.mq.md` | agent **framework** (layout now; LLM orchestration roadmap in `ext-agent.md`) |
|
||||
| `ext/agent.mq.md` | `ext/智能体.mq.md` | document-driven **step** / **plan** + OKF;示例 `examples/agent-pong` · `agent-okf-flywheel`;Wave B:[agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) |
|
||||
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | dynamic sites — see **ext/web** section below |
|
||||
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below |
|
||||
| `ext/linalg/linalg.mq.md` | `ext/linalg/线性代数.mq.md` | formula MatExpr + factorize/draw — see **ext/linalg** below |
|
||||
|
||||
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
|
||||
|
||||
@@ -97,6 +108,16 @@ Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p
|
||||
|
||||
Examples: `examples/quantum-bell/`, `examples/quantum-entanglement/`. Design: `doc/design/ext-quantum.md` · Q7: `doc/design/ext-quantum-q7.md` · Q8: `doc/design/ext-quantum-viz-style.md`.
|
||||
|
||||
## ext/linalg (formula-first linear algebra)
|
||||
|
||||
Install: `marqdo ext add linalg` (`线性代数`). Native: `cargo build --release -p marqdo_plugin_linalg`, then re-run `ext add`.
|
||||
|
||||
| EN import | ZH import | Notes |
|
||||
|-----------|-----------|-------|
|
||||
| `ext/linalg/linalg.mq.md` | `ext/linalg/线性代数.mq.md` | Top-level `symbol`/`mul`/`factorize`/`draw` |
|
||||
|
||||
Examples: `examples/linalg-svd/`, `examples/linalg-least-squares/`. Design: `doc/design/ext-linalg.md` · formula-doc: `doc/design/ext-linalg-formula-doc.md` · roadmap: `doc/roadmap/ext-linalg.md`.
|
||||
|
||||
## Formula + plot (math)
|
||||
|
||||
```markdown
|
||||
@@ -177,4 +198,6 @@ See `doc/design/call-arguments.md`.
|
||||
| `doc/design/ext-quantum.md` | `ext/quantum` circuits |
|
||||
| `doc/design/ext-quantum-q7.md` | Q7 density linear algebra + advanced SVG |
|
||||
| `doc/design/ext-quantum-viz-style.md` | Q8 themed SVG (`dark`/`light`/`bw`; circuit/probs/bloch) |
|
||||
| `doc/design/ext-linalg.md` | `ext/linalg` formula MatExpr + factorize/draw |
|
||||
| `doc/design/ext-linalg-formula-doc.md` | 公式文档面:跑通即正确 · 代数/计算两面 |
|
||||
| `doc/design/view-debug.md` | view / debug hosts |
|
||||
@@ -0,0 +1,12 @@
|
||||
# Local LLM for Marqdo agent / ext/ai/llm development.
|
||||
# Copy to `.env` in the repo root (gitignored) and fill secrets.
|
||||
# Never commit real keys.
|
||||
|
||||
OPENAI_API_KEY=
|
||||
OPENAI_BASE_URL=https://llm.cflmy.cn/v1
|
||||
OPENAI_MODEL=cflmy
|
||||
|
||||
# Aliases also accepted by ext/ai/llm:
|
||||
# MARQDO_LLM_API_KEY=
|
||||
# MARQDO_LLM_BASE_URL=
|
||||
# MARQDO_LLM_MODEL=
|
||||
@@ -25,8 +25,10 @@ jobs:
|
||||
with:
|
||||
node-version: "20"
|
||||
|
||||
- name: Build release
|
||||
run: cargo build --release
|
||||
- name: Build release CLI + official plugins
|
||||
run: |
|
||||
cargo build --release
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
|
||||
|
||||
- name: Checkout extension sources (branch vscode-extension only)
|
||||
run: git fetch origin vscode-extension && git checkout origin/vscode-extension -- vscode-extension
|
||||
@@ -55,6 +57,7 @@ jobs:
|
||||
$vsix = "marqdo-$ver.vsix"
|
||||
$public = "marqdo-$ver-public.zip"
|
||||
$extZip = "marqdo-$ver-ext.zip"
|
||||
$nativeZip = "marqdo-$ver-native-$target.zip"
|
||||
Copy-Item target/release/marqdo.exe "dist/$exe"
|
||||
git archive --format=zip -o "dist/$source" HEAD
|
||||
./target/release/marqdo view output public -o public
|
||||
@@ -65,11 +68,27 @@ jobs:
|
||||
Copy-Item ext "$stageExt/ext" -Recurse
|
||||
if (Test-Path "dist/$extZip") { Remove-Item "dist/$extZip" -Force }
|
||||
Compress-Archive -Path "$stageExt/*" -DestinationPath "dist/$extZip" -Force
|
||||
# Prebuilt native plugins (no Rust required for `marqdo ext add`)
|
||||
$stageNative = "dist/stage-native"
|
||||
if (Test-Path $stageNative) { Remove-Item $stageNative -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path "$stageNative/native" | Out-Null
|
||||
Copy-Item target/release/web.dll "$stageNative/native/web.dll"
|
||||
Copy-Item target/release/agent.dll "$stageNative/native/agent.dll"
|
||||
Copy-Item target/release/quantum.dll "$stageNative/native/quantum.dll"
|
||||
Copy-Item target/release/linalg.dll "$stageNative/native/linalg.dll"
|
||||
if (Test-Path "dist/$nativeZip") { Remove-Item "dist/$nativeZip" -Force }
|
||||
Compress-Archive -Path "$stageNative/*" -DestinationPath "dist/$nativeZip" -Force
|
||||
$stage = "dist/stage-bundle"
|
||||
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
|
||||
New-Item -ItemType Directory -Force -Path $stage | Out-Null
|
||||
Copy-Item target/release/marqdo.exe "$stage/marqdo.exe"
|
||||
Copy-Item lib "$stage/lib" -Recurse
|
||||
Copy-Item ext "$stage/ext" -Recurse
|
||||
New-Item -ItemType Directory -Force -Path "$stage/ext/native" | Out-Null
|
||||
Copy-Item target/release/web.dll "$stage/ext/native/web.dll"
|
||||
Copy-Item target/release/agent.dll "$stage/ext/native/agent.dll"
|
||||
Copy-Item target/release/quantum.dll "$stage/ext/native/quantum.dll"
|
||||
Copy-Item target/release/linalg.dll "$stage/ext/native/linalg.dll"
|
||||
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
|
||||
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
|
||||
$stageLib = "dist/stage-stdlib"
|
||||
@@ -85,6 +104,7 @@ jobs:
|
||||
echo "SOURCE=$source" >> $env:GITHUB_ENV
|
||||
echo "PUBLIC=$public" >> $env:GITHUB_ENV
|
||||
echo "EXT=$extZip" >> $env:GITHUB_ENV
|
||||
echo "NATIVE=$nativeZip" >> $env:GITHUB_ENV
|
||||
|
||||
- name: Upload release assets
|
||||
uses: softprops/action-gh-release@v2
|
||||
@@ -92,24 +112,21 @@ jobs:
|
||||
body: |
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### Highlights — v0.3
|
||||
- **`ext/web`**: W0–W7 + P3 complete (sessions, cache, upload, WebSocket, style assembly); see marqdo-blog
|
||||
- **`ext/quantum`**: Q7 linalg + Q8 themed SVG viz
|
||||
- **`ext/agent`**: A1–A4 (OKF reuse, events, context budget, RAG/MCP fixtures)
|
||||
- Install: `marqdo ext list` / `marqdo ext add llm|agent|web|quantum`
|
||||
- Native plugins: `cargo build --release -p marqdo_plugin_*` then `ext add`
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [README](https://github.com/cflmy/marqdo/blob/main/README.md)
|
||||
|
||||
Also: embedded stdlib, writeback/subtask, Variables modal in `view`, VSIX from branch **`vscode-extension`**.
|
||||
### 亮点 / Highlights
|
||||
- **中层标准库 Mid M1–M6**:`re`/`encoding`/`path`/`hash`/`secrets`/`csv`/`text++`/`cli`/`log`/`uuid`(中英对称,零插件)
|
||||
- **Mid stdlib M1–M6**: regex, encoding, path, hash, secrets, csv, thickened text/lists, cli, log, uuid
|
||||
- **`ext/linalg` 公式文档面 F1–F3**;agent/llm 写回与 SSE 稳健性修复
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [stdlib-mid.md](https://github.com/cflmy/marqdo/blob/main/doc/design/stdlib-mid.md)
|
||||
|
||||
### Downloads
|
||||
|
||||
| Asset | Contents |
|
||||
|-------|----------|
|
||||
| `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib |
|
||||
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` (optional disk override) |
|
||||
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` + `ext/`(含 native DLL) |
|
||||
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum` 插件 |
|
||||
| `marqdo-*-stdlib.zip` | `lib/` only |
|
||||
| `marqdo-*-ext.zip` | Official `ext/` L1 sources (for `MARQDO_EXT_SOURCE` / local `./ext`) |
|
||||
| `marqdo-*-ext.zip` | Official `ext/` L1 sources |
|
||||
| `marqdo-*-source.zip` | Source snapshot (`git archive`) |
|
||||
| `marqdo-*.vsix` | VS Code / Cursor extension |
|
||||
| `marqdo-*-public.zip` | Static user docs site |
|
||||
@@ -120,9 +137,42 @@ jobs:
|
||||
dist/${{ env.ZIP }}
|
||||
dist/${{ env.STDLIB }}
|
||||
dist/${{ env.EXT }}
|
||||
dist/${{ env.NATIVE }}
|
||||
dist/${{ env.VSIX }}
|
||||
dist/${{ env.SOURCE }}
|
||||
dist/${{ env.PUBLIC }}
|
||||
fail_on_unmatched_files: true
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
|
||||
linux-native:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v4
|
||||
|
||||
- name: Install Rust
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Build official plugins (release)
|
||||
run: cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
|
||||
|
||||
- name: Package native zip
|
||||
run: |
|
||||
set -euo pipefail
|
||||
VER="${GITHUB_REF_NAME#v}"
|
||||
TARGET="x86_64-unknown-linux-gnu"
|
||||
mkdir -p dist/stage-native/native
|
||||
cp target/release/libweb.so dist/stage-native/native/libweb.so
|
||||
cp target/release/libagent.so dist/stage-native/native/libagent.so
|
||||
cp target/release/libquantum.so dist/stage-native/native/libquantum.so
|
||||
cp target/release/liblinalg.so dist/stage-native/native/liblinalg.so
|
||||
(cd dist/stage-native && zip -r "../marqdo-${VER}-native-${TARGET}.zip" .)
|
||||
echo "NATIVE=marqdo-${VER}-native-${TARGET}.zip" >> "$GITHUB_ENV"
|
||||
|
||||
- name: Upload Linux native plugins
|
||||
uses: softprops/action-gh-release@v2
|
||||
with:
|
||||
files: dist/${{ env.NATIVE }}
|
||||
fail_on_unmatched_files: true
|
||||
env:
|
||||
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
|
||||
+12
@@ -23,6 +23,7 @@
|
||||
.DS_Store
|
||||
.marqdo/
|
||||
**/.marqdo/
|
||||
.marqdo-ext/
|
||||
.env
|
||||
|
||||
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
|
||||
@@ -39,6 +40,13 @@ spike/.pytest_cache/
|
||||
**/__pycache__/
|
||||
*.pyc
|
||||
|
||||
# Built browser WASM (rebuild via crates/marqdo-wasm README)
|
||||
/examples/browser-hello/marqdo_wasm.wasm
|
||||
/examples/browser-hello/pkg/
|
||||
/examples/web-client-site/static/marqdo_wasm.wasm
|
||||
/examples/browser-app/marqdo_wasm.wasm
|
||||
/examples/browser-media/marqdo_wasm.wasm
|
||||
|
||||
# Local sqlite / scratch
|
||||
/data/
|
||||
/tmp/
|
||||
@@ -55,8 +63,12 @@ plugins/*/tmp/
|
||||
|
||||
# Quantum draw/SVG runtime outputs (sources & gold .mq.md stay tracked)
|
||||
/tests/ext/quantum-*.svg
|
||||
/tests/ext/linalg-*.svg
|
||||
/examples/quantum-*/**/*.svg
|
||||
/examples/quantum-*/*.svg
|
||||
/examples/linalg-*/**/*.svg
|
||||
/examples/linalg-*/*.svg
|
||||
/examples/linalg-*.svg
|
||||
|
||||
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
|
||||
/ext/native/
|
||||
+158
@@ -2,6 +2,164 @@
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
|
||||
### Fixed
|
||||
|
||||
### Changed
|
||||
|
||||
## v0.3.6 — 2026-09-07
|
||||
|
||||
### Highlights
|
||||
|
||||
**中层标准库 Mid M1–M6 收口**:通用原语沉入 `lib/`(正则、编解码、路径、哈希、机密、CSV、加厚文本/集合、CLI、日志、UUID),写日常脚本与多数扩展库不再需要原生插件。另含 `ext/linalg` 公式文档面与 agent/llm 稳健性修复。
|
||||
|
||||
```bash
|
||||
git checkout v0.3.6
|
||||
# 或下载 Release 的 exe / zip
|
||||
marqdo run public/features/13-log-uuid.mq.md
|
||||
marqdo ext add linalg # 可选:公式文档 / 线性代数
|
||||
```
|
||||
|
||||
|
||||
### Added
|
||||
- **中层标准库 M6**:`lib/log` / `日志`(级别过滤的一行日志)与 `lib/uuid` / `标识`(v4);金样与 public `13-log-uuid`。设计 [stdlib-log-uuid.md](doc/design/stdlib-log-uuid.md)。**Mid M1–M6 收口。**
|
||||
- **中层标准库 M5**:`table`/`表` 加厚(sort/sort_by/unique/chunk/zip/flatten)与 `lib/cli`/`命令行`(parse);金样与 public `12-list-cli`。设计 [stdlib-list-cli.md](doc/design/stdlib-list-cli.md)。
|
||||
- **中层标准库 M4**:`lib/csv` / `逗号表`(parse/stringify)与 `lib/text` / `文本` 加厚(contains/replace/case/pad/…);金样与 public `11-csv-text`。设计 [stdlib-csv.md](doc/design/stdlib-csv.md) · [stdlib-text-mid.md](doc/design/stdlib-text-mid.md)。
|
||||
- **中层标准库 M3**:`lib/hash` / `哈希`(sha256/sha1/md5/hmac_sha256)与 `lib/secrets` / `机密`(token_hex/token_urlsafe);金样与 public `10-hash-secrets`。设计 [stdlib-hash.md](doc/design/stdlib-hash.md) · [stdlib-secrets.md](doc/design/stdlib-secrets.md)。
|
||||
- **中层标准库 M2**:`lib/path` / `lib/路径`(join/split/normalize/…)与 `fs`/`文件` 加厚(`copy_file`/`move`/`make_temp`);金样与 public `09-path-fs`。设计 [stdlib-path.md](doc/design/stdlib-path.md) · [stdlib-fs-mid.md](doc/design/stdlib-fs-mid.md)。
|
||||
- **中层标准库 M1**:`lib/re` / `lib/正则`(`is_match`/`find`/`find_all`/`replace`/`split`)与 `lib/encoding` / `lib/编码`(base64/hex);host `host_re_*` + `host_encoding_*`;金样与 public `08-re-encoding`。设计 [stdlib-mid.md](doc/design/stdlib-mid.md) · [stdlib-re.md](doc/design/stdlib-re.md) · [stdlib-encoding.md](doc/design/stdlib-encoding.md)。
|
||||
- **`ext/linalg`**:L0–L6 + 公式文档面 **F1–F3**(中缀、`declare`、展示/`explicit` 默认化简、`T_ascii`、public「如何写公式文档」);示例 `linalg-transpose` · `linalg-svd` · `linalg-least-squares`。设计:[ext-linalg-formula-doc.md](doc/design/ext-linalg-formula-doc.md)。
|
||||
|
||||
### Fixed
|
||||
- **`ext/agent`**:写回改走 `wb.record`(避免 `writeback` 形参遮蔽模块名),不再直调 `host_*`。
|
||||
- **`ext/llm`**:`stream_result` 忽略未知 SSE 类型(如 `reasoning`),不再因此退出。
|
||||
|
||||
### Changed
|
||||
|
||||
## v0.3.5 — 2026-09-04
|
||||
|
||||
### Highlights
|
||||
|
||||
**`marqdo ext add` 无需本机 Rust**:Release 发布预编译 native 插件;CLI 可自动下载 L1(`*-ext.zip`)与 `*-native-*.zip`。Windows 便携包内含 `ext/native/*.dll`。
|
||||
|
||||
```bash
|
||||
git checkout v0.3.5
|
||||
# 或下载 Release 的 exe / zip
|
||||
marqdo ext add web
|
||||
marqdo ext add agent
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
### Added
|
||||
- **预编译原生插件资产**:`marqdo-*-native-x86_64-pc-windows-msvc.zip`、`marqdo-*-native-x86_64-unknown-linux-gnu.zip`;Windows zip 捆绑 `ext/` + native DLL。
|
||||
- **`ext add` 下载回退**:本地无 `target/` 时从 GitHub Release 拉取;`MARQDO_EXT_NO_DOWNLOAD=1` / `MARQDO_EXT_VERSION` 可配置。
|
||||
|
||||
### Changed
|
||||
- 文档:[ext-cli.md](doc/design/ext-cli.md)、[08-ext-deploy-coupling](doc/design/ext-web-customization/08-ext-deploy-coupling.md)、README 安装步骤以预编译为默认路径。
|
||||
- Release workflow:Windows 编插件并上传 native zip;新增 Linux native job。
|
||||
|
||||
## v0.3.4 — 2026-09-04
|
||||
|
||||
### Highlights
|
||||
|
||||
**`ext/web` 定制波次 C0–C4 收口**:可配置 admin 前缀与登录回跳、段边界 gates、shell/layout、样式单元格 strict、脚本 defer/version/`asset_version`、条件导航 when/media。附智能体 Wave B0 示例与写回遮蔽修复。
|
||||
|
||||
```bash
|
||||
git checkout v0.3.4
|
||||
cargo build --release
|
||||
cargo build --release -p marqdo_plugin_web
|
||||
marqdo ext add web
|
||||
# golds: tests/ext/web-c0-admin-prefix … web-c4-nav-when
|
||||
```
|
||||
|
||||
### Added
|
||||
- **智能体 Wave B0**:宪法优先示例 [agent-pong](examples/agent-pong/)(call_site/源码注入)· [agent-okf-flywheel](examples/agent-okf-flywheel/)(OKF `cache=hit`);调研 [agent-framework-2026-09.md](doc/research/agent-framework-2026-09.md);离线 harness [`scripts/agent-harness.sh`](scripts/agent-harness.sh);金样 `agent-constitution-b0`。
|
||||
- **`.env.example`**:开发期 OpenAI 兼容网关变量模板(密钥仅本地 `.env`)。
|
||||
|
||||
### Fixed
|
||||
- **`agent.step` / `plan` 写回**:参数名 `writeback` 遮蔽 `lib/writeback` import,导致 `writeback=True` 时 `method receiver must be an object map`;改为 `host_writeback_record`。金样 `agent-writeback-shadow`。
|
||||
- **`ext/web` C0**:`admin=False` 不再挂载/保留 `/admin*`;可配 `admin_prefix` / `login_redirect` / `logout_redirect`;金样 `web-c0-admin-prefix`。
|
||||
- **`ext/web` C1**:门禁段边界匹配(不再误伤 `/admin-publish`);`gate` 支持 `match` / `on_deny` / `exclude`;`auth` 默认 `on_deny=redirect` + `login_path`;金样 `web-c1-gates`。
|
||||
- **`ext/web` C2**:`shell_css=full|minimal|off`;`layout=sidebar|stacked|bare|rail`;full 壳含小屏单列 media;金样 `web-c2-shell-layout`。
|
||||
- **`ext/web` C3**:样式装配对数字/布尔值单元格告警,`strict`/`strict_css_cells` 硬错误;`page.css` 作 raw CSS;head 表支持 `defer`/`async`/`version`,`asset_version` 统一 `?v=`;金样 `web-c3-style-head`。
|
||||
- **`ext/web` C4**:导航表 `当`/`when`(`auth`/`guest`/`hide`)与 `媒体`/`media`(响应式显隐);listen 注入 `_logged_in`;金样 `web-c4-nav-when`。
|
||||
|
||||
### Changed
|
||||
- `build_step_context`:call site 提前到 task 之后;开场白强调 code-as-documentation。
|
||||
- 中文 `构建单步上下文` 委托英文版(含预算 / READ);新增 `dump_step_context`;live 用例改用仓库根 `.env`。
|
||||
- 文档:[ext-web 定制限制](doc/research/ext-web-customization-limits.md) + [解决设计 C0–C4](doc/design/ext-web-customization/)。
|
||||
|
||||
## v0.3.3 — 2026-09-04
|
||||
|
||||
### Highlights
|
||||
|
||||
**浏览器作者零业务 JS(路线 D/E/F)**:官方 bridge 自启 + 宿主效应补齐(DOM/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM 表格写法;新增 [marqdo-dev](.cursor/skills/marqdo-dev/SKILL.md) 开发约定。
|
||||
|
||||
```bash
|
||||
git checkout v0.3.3
|
||||
cargo build --release
|
||||
marqdo wasm build
|
||||
# examples: browser-hello / browser-app / browser-media / web-client-site
|
||||
```
|
||||
|
||||
### Added
|
||||
- **路线 D(作者零 JS)**:[roadmap](doc/roadmap/browser-wasm-d.md) · 设计 §16。官方 bridge `mount` / `data-mq-*` 自启;`client_embed` 带 `wasm`/`source`/`boot`;DOM 效应;`examples/web-client-site/`。
|
||||
- **路线 E(前端补齐)**:[browser-wasm-e.md](doc/roadmap/browser-wasm-e.md)。多节点 DOM、`add_class`/`remove_class`、cookie、clipboard/download、`fetch_all`/`ws`/`interval`;示例 [browser-app](examples/browser-app/)。
|
||||
- **路线 F(媒体/文件,F1–F5)**:[browser-wasm-f.md](doc/roadmap/browser-wasm-f.md)。`read_file`、Canvas 2D、Audio beep、Intersection/ResizeObserver、drag/drop;示例 [browser-media](examples/browser-media/)。
|
||||
- **`lib/browser` / `lib/浏览器`**:WASM 客户端效应助手(GFM 表格 + named helpers;勿用 `json.set` 链)。
|
||||
- **Skill `marqdo-dev`**:代码即文档 / GFM-first / 库开发约定。
|
||||
|
||||
### Changed
|
||||
- 浏览器示例(hello / app / media / web-client)改为表格 + `lib/browser`;`ext/web` 效应助手改用 `table.put`。
|
||||
- 标准库模块表收录 `browser`;路线 F 收口 F1–F5(F6 Service Worker 仍可选)。
|
||||
|
||||
## v0.3.2 — 2026-09-01
|
||||
|
||||
### Highlights
|
||||
|
||||
**浏览器 Marqdo(路线 C)首版完备**:`wasm-core`、`marqdo wasm build`、会话 ABI、DOM/`fetch`/`after` 效应、官方 bridge、体积与冒烟;并修 Admin 长内容布局、`ext add` 原生插件预检、`@keyframes` 与样式表 `/` 比率约定。
|
||||
|
||||
```bash
|
||||
git checkout v0.3.2
|
||||
cargo build --release
|
||||
marqdo wasm build
|
||||
marqdo ext add web # 改插件后请重新 add
|
||||
```
|
||||
|
||||
### Added
|
||||
- **浏览器 Marqdo(路线 C)**: [ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [design](doc/design/browser-marqdo-wasm.md) · [roadmap C0–C5](doc/roadmap/browser-wasm.md)。
|
||||
- **C0/C1**:`wasm-core` feature 门控;`run_source`;crate `crates/marqdo-wasm`(`mq_run` ABI);示例 [examples/browser-hello](examples/browser-hello/)。
|
||||
- **C2/C3**:`marqdo wasm build`;会话 `mq_boot`/`mq_call`;GFM wire 表 + `set_text` DOM 回写;[interact.html](examples/browser-hello/interact.html) 计数器示例。
|
||||
- **C4**:[ADR 0003](doc/adr/0003-browser-async-effects.md) 效应表(`fetch` / `after`)+ bridge 续体;[fetch.html](examples/browser-hello/fetch.html)。
|
||||
- **C5**:`release-wasm` 体积配置;`marqdo wasm build` 报告 KiB 并可选 `wasm-opt`;`run_source` bytecode 单测;会话仍为 tree。
|
||||
- **WASM 收口**:规范 `crates/marqdo-wasm/js/marqdo-bridge.js`;`wasm build` 同时拷贝 bridge;Node 冒烟 `tests/wasm`;`web.client_embed` / `网页.客户端挂载`;路线图标 Completed。
|
||||
- **发版 Skill**:`.cursor/skills/marqdo-release/`(探测版本 → 用户确认 → 文档/资产/扩展/Release 说明)。
|
||||
|
||||
### Fixed
|
||||
- **Admin UI**:主区取消 `max-width:56rem` 限制,表格外包可横向滚动的 `.table-wrap`,单元格完整展示并自动换行;表单加宽且 textarea 可随内容增高。
|
||||
- **`marqdo ext add`**:安装含原生插件的扩展时**先**定位/自动 `cargo build` 再拷贝 `.mq.md`,避免只装上文稿、运行时报 `native plugin not found`;扩大 `.so` 搜索路径。
|
||||
- **`web_style` / 样式装配**:正确输出 `@keyframes` 块(停点为嵌套规则,不再写成 `0%: opacity: 0`)。
|
||||
- **样式表含 `/` 的值**:文档明确**引号优先**(`"16/9"`、`"1/5"`);不引入靠空格消歧的表单元格比率折叠。
|
||||
|
||||
## v0.3.1 — 2026-08-29
|
||||
|
||||
### Highlights
|
||||
|
||||
**W8 站点资源**:favicon / Head 资源表 / 图片装配一次补齐;并修复相对入口路径下 `entry_dir` 双重拼接导致的嵌套目录问题。
|
||||
|
||||
```bash
|
||||
git checkout v0.3.1
|
||||
cargo build --release
|
||||
marqdo ext add web # 改插件后请重新 add
|
||||
```
|
||||
|
||||
### Added
|
||||
- **`ext/web` W8(站点图标 / Head / 图片装配)** ([web-assets-and-images.md](doc/design/web-assets-and-images.md)):`app.icons` / `应用.图标` 挂 `GET /favicon.ico`;`page.head` / `头装配`;`make_images` / `图片装配`;`meta` 认 `icon`/`favicon`/`apple-touch-icon`;`static` 约定 `favicon.*`;金样 `web-assets-smoke` / `web-assets-live`;[marqdo-blog](examples/marqdo-blog/) 接入。
|
||||
|
||||
### Fixed
|
||||
- **`host_query("entry_dir")`**:相对入口脚本(如 `tests/ext/….mq.md`)时对进程 cwd 绝对化,避免与 `for_run` 已设的脚本目录 cwd 再次拼接成 `tests/ext/tests/ext/…`。
|
||||
|
||||
## v0.3.0 — 2026-08-29
|
||||
|
||||
### Highlights
|
||||
|
||||
Generated
+55
-4
@@ -463,6 +463,12 @@ dependencies = [
|
||||
"cfg-if",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "crossbeam-utils"
|
||||
version = "0.8.21"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
|
||||
|
||||
[[package]]
|
||||
name = "crypto-common"
|
||||
version = "0.1.7"
|
||||
@@ -1018,26 +1024,41 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
|
||||
|
||||
[[package]]
|
||||
name = "marqdo"
|
||||
version = "0.3.0"
|
||||
version = "0.3.5"
|
||||
dependencies = [
|
||||
"anyhow",
|
||||
"assert_cmd",
|
||||
"chrono",
|
||||
"clap",
|
||||
"futures-util",
|
||||
"getrandom 0.2.17",
|
||||
"hmac 0.12.1",
|
||||
"idna_adapter",
|
||||
"include_dir",
|
||||
"libc",
|
||||
"libloading",
|
||||
"md-5 0.10.6",
|
||||
"predicates",
|
||||
"pulldown-cmark",
|
||||
"regex",
|
||||
"serde_json",
|
||||
"sha1",
|
||||
"sha2 0.10.9",
|
||||
"thiserror 1.0.69",
|
||||
"tiny_http",
|
||||
"tokio",
|
||||
"tokio-tungstenite 0.24.0",
|
||||
"ureq",
|
||||
"zeroize",
|
||||
"zip",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo-wasm"
|
||||
version = "0.3.5"
|
||||
dependencies = [
|
||||
"marqdo",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
@@ -1055,6 +1076,14 @@ dependencies = [
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_linalg"
|
||||
version = "0.1.0"
|
||||
dependencies = [
|
||||
"serde",
|
||||
"serde_json",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "marqdo_plugin_quantum"
|
||||
version = "0.1.0"
|
||||
@@ -1092,6 +1121,16 @@ version = "0.8.4"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
|
||||
|
||||
[[package]]
|
||||
name = "md-5"
|
||||
version = "0.10.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "d89e7ee0cfbedfc4da3340218492196241d89eefb6dab27de5df917a6d2e78cf"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"digest 0.10.7",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "md-5"
|
||||
version = "0.11.0"
|
||||
@@ -1322,7 +1361,7 @@ dependencies = [
|
||||
"bytes",
|
||||
"fallible-iterator 0.2.0",
|
||||
"hmac 0.13.0",
|
||||
"md-5",
|
||||
"md-5 0.11.0",
|
||||
"memchr",
|
||||
"rand 0.10.2",
|
||||
"sha2 0.11.0",
|
||||
@@ -1710,9 +1749,9 @@ dependencies = [
|
||||
|
||||
[[package]]
|
||||
name = "sha1"
|
||||
version = "0.10.7"
|
||||
version = "0.10.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "a978451301f4db1d02937a4ab3ccce137717b81826e79b7d49ffe3244a13c3b8"
|
||||
checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"
|
||||
dependencies = [
|
||||
"cfg-if",
|
||||
"cpufeatures 0.2.17",
|
||||
@@ -2554,6 +2593,18 @@ version = "1.8.1"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "ced3678a2879b30306d323f4542626697a464a97c0a07c9aebf7ebca65cd4dde"
|
||||
|
||||
[[package]]
|
||||
name = "zip"
|
||||
version = "0.6.6"
|
||||
source = "registry+https://github.com/rust-lang/crates.io-index"
|
||||
checksum = "760394e246e4c28189f19d488c058bf16f564016aefac5d32bb1f3b51d5e9261"
|
||||
dependencies = [
|
||||
"byteorder",
|
||||
"crc32fast",
|
||||
"crossbeam-utils",
|
||||
"flate2",
|
||||
]
|
||||
|
||||
[[package]]
|
||||
name = "zmij"
|
||||
version = "1.0.23"
|
||||
|
||||
+51
-9
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.3.0"
|
||||
version = "0.3.6"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -10,25 +10,58 @@ repository = "https://github.com/cflmy/marqdo"
|
||||
[[bin]]
|
||||
name = "marqdo"
|
||||
path = "src/main.rs"
|
||||
required-features = ["cli"]
|
||||
|
||||
[features]
|
||||
default = ["native"]
|
||||
native = ["cli", "view", "net-host", "plugin-host", "exec-host", "fs-host", "tty"]
|
||||
cli = ["dep:clap"]
|
||||
view = ["dep:tiny_http"]
|
||||
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize", "dep:zip"]
|
||||
plugin-host = ["dep:libloading"]
|
||||
exec-host = []
|
||||
fs-host = []
|
||||
tty = ["dep:libc"]
|
||||
wasm-core = []
|
||||
|
||||
[dependencies]
|
||||
anyhow = "1"
|
||||
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
|
||||
clap = { version = "=4.4.18", features = ["derive"] }
|
||||
clap = { version = "=4.4.18", features = ["derive"], optional = true }
|
||||
pulldown-cmark = "0.12"
|
||||
serde_json = "1"
|
||||
thiserror = "1"
|
||||
tiny_http = "0.12"
|
||||
tiny_http = { version = "0.12", optional = true }
|
||||
sha2 = { version = "=0.10.9", default-features = false }
|
||||
sha1 = { version = "=0.10.6", default-features = false }
|
||||
md-5 = { version = "=0.10.6", default-features = false }
|
||||
hmac = { version = "=0.12.1", default-features = false }
|
||||
getrandom = { version = "=0.2.17", default-features = false, features = ["std"] }
|
||||
# Mid M1: Unicode regex for lib/re (no backrefs; RE2-like).
|
||||
regex = { version = "=1.13.1", default-features = false, features = ["std", "unicode"] }
|
||||
# Pin for Cargo/rustc 1.81 (newer rustls/idna/zeroize need edition2024).
|
||||
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"] }
|
||||
idna_adapter = "=1.1.0"
|
||||
zeroize = "=1.8.1"
|
||||
libloading = "=0.8.6"
|
||||
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"], optional = true }
|
||||
idna_adapter = { version = "=1.1.0", optional = true }
|
||||
zeroize = { version = "=1.8.1", optional = true }
|
||||
# Extract GitHub Release ext/native zips (`marqdo ext add` without local Rust).
|
||||
zip = { version = "=0.6.6", default-features = false, features = ["deflate"], optional = true }
|
||||
libloading = { version = "=0.8.6", optional = true }
|
||||
include_dir = "0.7"
|
||||
libc = "0.2"
|
||||
libc = { version = "0.2", optional = true }
|
||||
|
||||
[target.'cfg(target_arch = "wasm32")'.dependencies]
|
||||
# No `wasmbind`: keeps cdylib free of wasm-bindgen imports (raw mq_* ABI).
|
||||
chrono = { version = "0.4", default-features = false, features = ["alloc", "std"] }
|
||||
|
||||
[workspace]
|
||||
members = ["plugins/demo", "plugins/agent", "plugins/web", "plugins/quantum"]
|
||||
members = [
|
||||
"plugins/demo",
|
||||
"plugins/agent",
|
||||
"plugins/web",
|
||||
"plugins/quantum",
|
||||
"plugins/linalg",
|
||||
"crates/marqdo-wasm",
|
||||
]
|
||||
resolver = "2"
|
||||
|
||||
[dev-dependencies]
|
||||
@@ -37,3 +70,12 @@ predicates = "=3.1.0"
|
||||
tokio = { version = "1", features = ["rt-multi-thread", "macros", "time", "net"] }
|
||||
tokio-tungstenite = "0.24"
|
||||
futures-util = "0.3"
|
||||
|
||||
# Size-oriented profile for `marqdo-wasm` (C5). Use: cargo build -p marqdo-wasm --profile release-wasm --target wasm32-unknown-unknown
|
||||
[profile.release-wasm]
|
||||
inherits = "release"
|
||||
lto = true
|
||||
codegen-units = 1
|
||||
opt-level = "z"
|
||||
strip = true
|
||||
panic = "abort"
|
||||
@@ -99,7 +99,7 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v0.3.0)
|
||||
## 现状(v0.3.6)
|
||||
|
||||
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
@@ -107,24 +107,26 @@ marqdo catalog public -o .marqdo
|
||||
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
|
||||
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
|
||||
- **`marqdo version --check`**:与 GitHub 最新 release 对比
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**;**中层 Mid M1–M6**(`re`/`encoding`/`path`/`hash`/`secrets`/`csv`/`cli`/`log`/`uuid` 及中英对称库,见 [stdlib-mid.md](doc/design/stdlib-mid.md))
|
||||
- **官方扩展库 `ext/`**(**非** stdlib,本版收口):
|
||||
- **`web`**:W0–W7 + P3 完结(会话 / 缓存 / 上传 / WebSocket / 样式装配等);示例 [marqdo-blog](examples/marqdo-blog/);生产路径见 [web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)(反向代理 → 嵌入式 `listen`,非 Daphne/Uvicorn)
|
||||
- **`web`**:W0–W7 + P3 + **W8**;**定制 C0–C4**(admin 前缀/gates/`shell_css`/`layout`/样式 strict/脚本 defer·version/条件导航,见 [ext-web-customization](doc/design/ext-web-customization/));示例 [marqdo-blog](examples/marqdo-blog/);生产路径见 [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(OKF 复用、过程事件、上下文预算、RAG/MCP fixture);下一波缺口 [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
|
||||
- **`llm`**:OpenAI 兼容对话
|
||||
- 安装:`marqdo ext list` / `add …` / `remove`([ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`
|
||||
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum}`
|
||||
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum,linalg}`
|
||||
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
|
||||
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
|
||||
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
|
||||
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
|
||||
|
||||
### 如何使用最新 Marqdo(v0.3.0)
|
||||
### 如何使用最新 Marqdo(v0.3.6)
|
||||
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v0.3.0 # 或留在 main
|
||||
git checkout v0.3.6 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
@@ -137,19 +139,25 @@ marqdo view public --no-open
|
||||
marqdo debug public --no-open
|
||||
marqdo catalog public -o .marqdo
|
||||
|
||||
# 3) 安装官方扩展(需先编原生插件)
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
|
||||
marqdo ext add web # 或:网页
|
||||
# 3) 安装官方扩展(Release 用户:无需本机 Rust)
|
||||
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native
|
||||
marqdo ext add agent # 或:智能体
|
||||
marqdo ext add quantum # 或:量子
|
||||
marqdo ext add llm # 或:大模型
|
||||
marqdo ext add linalg # 或:线性代数
|
||||
marqdo ext add llm # 或:大模型(纯 .mq.md)
|
||||
# 开发者也可:cargo build --release -p marqdo_plugin_* 后在本机 target/ 安装
|
||||
# 离线:解压 Windows zip(已含 ext/native)或手动放下 native zip;MARQDO_EXT_NO_DOWNLOAD=1
|
||||
|
||||
# 4) 动态站示例(扩展装好后)
|
||||
marqdo run examples/marqdo-blog/index.mq.md
|
||||
# 浏览器打开终端打印的 listen 地址
|
||||
# 浏览器打开终端打印的 listen 地址;/favicon.ico 与 logo 装配见 W8
|
||||
|
||||
# 5) Windows:也可从 GitHub Releases 下载 exe / zip / vsix
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v0.3.0
|
||||
# 5) 浏览器 WASM(可选)
|
||||
marqdo wasm build
|
||||
# → dist/wasm/ … 见 examples/browser-hello/
|
||||
|
||||
# 6) Windows:也可从 GitHub Releases 下载 exe / zip / vsix
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v0.3.6
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "0.3.6"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
|
||||
repository = "https://github.com/cflmy/marqdo"
|
||||
publish = false
|
||||
|
||||
[lib]
|
||||
crate-type = ["cdylib", "rlib"]
|
||||
|
||||
[dependencies]
|
||||
marqdo = { path = "../..", default-features = false, features = ["wasm-core"] }
|
||||
serde_json = "1"
|
||||
@@ -0,0 +1,21 @@
|
||||
# Marqdo browser WASM (route C)
|
||||
|
||||
Raw `cdylib` exports — no `wasm-bindgen` CLI required.
|
||||
|
||||
| Export | Role |
|
||||
|--------|------|
|
||||
| `mq_alloc` / `mq_dealloc` | linear memory |
|
||||
| `mq_run` | one-shot `# main` (C1) |
|
||||
| `mq_boot` / `mq_call` | session + handlers (C3) |
|
||||
| `mq_version` | version C string |
|
||||
|
||||
```bash
|
||||
# from repo root (C5 size profile)
|
||||
marqdo wasm build -o examples/browser-hello
|
||||
# or:
|
||||
cargo build -p marqdo-wasm --target wasm32-unknown-unknown --profile release-wasm
|
||||
```
|
||||
|
||||
Prints size in KiB; runs `wasm-opt -Oz` when Binaryen is on `PATH`.
|
||||
|
||||
See [doc/design/browser-marqdo-wasm.md](../../doc/design/browser-marqdo-wasm.md).
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,201 @@
|
||||
//! Browser export surface for Marqdo (ADR 0002 / C1–C3).
|
||||
//!
|
||||
//! Raw `cdylib` ABI (no wasm-bindgen CLI):
|
||||
//! - `mq_alloc` / `mq_dealloc`
|
||||
//! - `mq_run` — one-shot `# main` (C1)
|
||||
//! - `mq_boot` — start session; return value often a `wire` table (C3)
|
||||
//! - `mq_call` — `(name_ptr, name_len, args_ptr, args_len) ->` JSON result (C3)
|
||||
//! - `mq_version`
|
||||
//!
|
||||
//! Packed results: little-endian `u32` length + UTF-8 JSON
|
||||
//! `{ ok, stdout, error, value }`.
|
||||
|
||||
use std::alloc::{alloc, dealloc, Layout};
|
||||
use std::cell::RefCell;
|
||||
use std::ptr;
|
||||
use std::slice;
|
||||
|
||||
use marqdo::{run_source, value_as_json, BrowserSession, RunOptions};
|
||||
use serde_json::json;
|
||||
|
||||
thread_local! {
|
||||
static SESSION: RefCell<Option<BrowserSession>> = const { RefCell::new(None) };
|
||||
}
|
||||
|
||||
/// Allocate `size` bytes in WASM linear memory (alignment 1).
|
||||
#[no_mangle]
|
||||
pub extern "C" fn mq_alloc(size: usize) -> *mut u8 {
|
||||
if size == 0 {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
let layout = match Layout::from_size_align(size, 1) {
|
||||
Ok(l) => l,
|
||||
Err(_) => return ptr::null_mut(),
|
||||
};
|
||||
unsafe { alloc(layout) }
|
||||
}
|
||||
|
||||
/// Free a buffer previously returned by [`mq_alloc`], [`mq_run`], [`mq_boot`], or [`mq_call`].
|
||||
#[no_mangle]
|
||||
pub extern "C" fn mq_dealloc(ptr: *mut u8, size: usize) {
|
||||
if ptr.is_null() || size == 0 {
|
||||
return;
|
||||
}
|
||||
let layout = match Layout::from_size_align(size, 1) {
|
||||
Ok(l) => l,
|
||||
Err(_) => return,
|
||||
};
|
||||
unsafe { dealloc(ptr, layout) }
|
||||
}
|
||||
|
||||
/// One-shot run (C1). Does not keep a session.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn mq_run(ptr: *const u8, len: usize) -> *mut u8 {
|
||||
let source = match read_utf8(ptr, len) {
|
||||
Ok(s) => s,
|
||||
Err(e) => return pack_json(&err_json(&e)),
|
||||
};
|
||||
pack_json(&run_to_json(&source))
|
||||
}
|
||||
|
||||
/// Boot a session: run `# main`, keep entry env. Replaces any prior session.
|
||||
#[no_mangle]
|
||||
pub extern "C" fn mq_boot(ptr: *const u8, len: usize) -> *mut u8 {
|
||||
let source = match read_utf8(ptr, len) {
|
||||
Ok(s) => s,
|
||||
Err(e) => return pack_json(&err_json(&e)),
|
||||
};
|
||||
match BrowserSession::boot(&source) {
|
||||
Ok((sess, value)) => {
|
||||
let stdout = String::new();
|
||||
let value_json = match value_as_json(&value) {
|
||||
Ok(j) => j,
|
||||
Err(e) => return pack_json(&err_json(&e)),
|
||||
};
|
||||
SESSION.with(|s| *s.borrow_mut() = Some(sess));
|
||||
pack_json(&json!({
|
||||
"ok": true,
|
||||
"stdout": stdout,
|
||||
"error": null,
|
||||
"value": value_json,
|
||||
}))
|
||||
}
|
||||
Err(e) => {
|
||||
SESSION.with(|s| *s.borrow_mut() = None);
|
||||
pack_json(&err_json(&format!("{e:#}")))
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/// Call a function in the current session.
|
||||
/// `args` is UTF-8 JSON object of named arguments (may be `{}`).
|
||||
#[no_mangle]
|
||||
pub extern "C" fn mq_call(
|
||||
name_ptr: *const u8,
|
||||
name_len: usize,
|
||||
args_ptr: *const u8,
|
||||
args_len: usize,
|
||||
) -> *mut u8 {
|
||||
let name = match read_utf8(name_ptr, name_len) {
|
||||
Ok(s) => s,
|
||||
Err(e) => return pack_json(&err_json(&e)),
|
||||
};
|
||||
let args = match read_utf8(args_ptr, args_len) {
|
||||
Ok(s) => s,
|
||||
Err(e) => return pack_json(&err_json(&e)),
|
||||
};
|
||||
SESSION.with(|cell| {
|
||||
let mut guard = cell.borrow_mut();
|
||||
let Some(sess) = guard.as_mut() else {
|
||||
return pack_json(&err_json("no session — call mq_boot first"));
|
||||
};
|
||||
match sess.call(&name, &args) {
|
||||
Ok(value) => {
|
||||
let stdout = sess.take_stdout();
|
||||
let value_json = match value_as_json(&value) {
|
||||
Ok(j) => j,
|
||||
Err(e) => return pack_json(&err_json(&e)),
|
||||
};
|
||||
pack_json(&json!({
|
||||
"ok": true,
|
||||
"stdout": stdout,
|
||||
"error": null,
|
||||
"value": value_json,
|
||||
}))
|
||||
}
|
||||
Err(e) => pack_json(&err_json(&format!("{e:#}"))),
|
||||
}
|
||||
})
|
||||
}
|
||||
|
||||
/// Package version (NUL-terminated C string in static memory — do not free).
|
||||
#[no_mangle]
|
||||
pub extern "C" fn mq_version() -> *const u8 {
|
||||
concat!(env!("CARGO_PKG_VERSION"), "\0").as_ptr()
|
||||
}
|
||||
|
||||
fn read_utf8(ptr: *const u8, len: usize) -> Result<String, String> {
|
||||
if ptr.is_null() || len == 0 {
|
||||
return Ok(String::new());
|
||||
}
|
||||
let bytes = unsafe { slice::from_raw_parts(ptr, len) };
|
||||
String::from_utf8(bytes.to_vec()).map_err(|e| format!("not utf-8: {e}"))
|
||||
}
|
||||
|
||||
fn run_to_json(source: &str) -> serde_json::Value {
|
||||
let mut opts = RunOptions::default();
|
||||
opts.allow_fs_write = false;
|
||||
opts.allow_exec = false;
|
||||
opts.allow_net = false;
|
||||
opts.sleep_limit_ms = Some(0);
|
||||
|
||||
match run_source(source, &opts) {
|
||||
Ok(cap) => match value_as_json(&cap.value) {
|
||||
Ok(value) => json!({
|
||||
"ok": true,
|
||||
"stdout": cap.stdout,
|
||||
"error": null,
|
||||
"value": value,
|
||||
}),
|
||||
Err(e) => err_json(&e),
|
||||
},
|
||||
Err(e) => err_json(&format!("{e:#}")),
|
||||
}
|
||||
}
|
||||
|
||||
fn err_json(msg: &str) -> serde_json::Value {
|
||||
json!({
|
||||
"ok": false,
|
||||
"stdout": "",
|
||||
"error": msg,
|
||||
"value": null,
|
||||
})
|
||||
}
|
||||
|
||||
fn pack_json(v: &serde_json::Value) -> *mut u8 {
|
||||
let s = v.to_string();
|
||||
let bytes = s.as_bytes();
|
||||
let total = 4 + bytes.len();
|
||||
let out = mq_alloc(total);
|
||||
if out.is_null() {
|
||||
return ptr::null_mut();
|
||||
}
|
||||
unsafe {
|
||||
let len = bytes.len() as u32;
|
||||
ptr::copy_nonoverlapping(len.to_le_bytes().as_ptr(), out, 4);
|
||||
ptr::copy_nonoverlapping(bytes.as_ptr(), out.add(4), bytes.len());
|
||||
}
|
||||
out
|
||||
}
|
||||
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[test]
|
||||
fn run_hello_json() {
|
||||
let v = run_to_json("# main\n\n> print text=Hello World!\n");
|
||||
assert_eq!(v["ok"], true);
|
||||
assert_eq!(v["stdout"], "Hello World!\n");
|
||||
}
|
||||
}
|
||||
+11
-3
@@ -40,6 +40,9 @@
|
||||
| [design/ext-agent-plan.md](design/ext-agent-plan.md) | **`## 多步` / `## plan` 锁定设计**(工作簿文件、subtask 执行、修订循环、`step` 默认写回) |
|
||||
| [design/ext-cli.md](design/ext-cli.md) | **`marqdo ext list/add/remove` 官方扩展安装器** |
|
||||
| [design/ext-web.md](design/ext-web.md) | **官方扩展 `ext/web`(页面/库表/绑定/后台;ABI + CLI;设计锁定)** |
|
||||
| [research/ext-web-customization-limits.md](research/ext-web-customization-limits.md) | **`ext/web` 定制限制踩坑盘点**(路由/壳 CSS/鉴权/样式/部署) |
|
||||
| [design/ext-web-customization/](design/ext-web-customization/) | **对应解决设计**(C0–C4:前缀可让出、shell_css、gate、布局…) |
|
||||
| [design/web-assets-and-images.md](design/web-assets-and-images.md) | **W8:favicon / Head 资源表 / 图片装配**(一次补齐) |
|
||||
| [design/web-asgi-servers-and-marqdo.md](design/web-asgi-servers-and-marqdo.md) | **Daphne/Uvicorn 等 vs Marqdo**:不能直接托管;反代 + axum `listen` |
|
||||
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
|
||||
| [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** |
|
||||
@@ -58,12 +61,17 @@
|
||||
| [roadmap/object-inheritance.md](roadmap/object-inheritance.md) | **对象继承**(`# 子类 = > 父类`;I0–I2 已落地) |
|
||||
| [roadmap/tables-maps-footnotes.md](roadmap/tables-maps-footnotes.md) | **表格语义**(竖表 / 横表字典 / 脚注取元 / 行向记录 / **单元格表达式 T5**) |
|
||||
| [design/table-cell-expressions.md](design/table-cell-expressions.md) | **表数据单元格 = 表达式**(同调用实参值语法;Accepted) |
|
||||
| [roadmap/ext-web.md](roadmap/ext-web.md) | **实现路线:`ext/web`**(W0–W4;设计见 [ext-web.md](../design/ext-web.md)) |
|
||||
| [roadmap/browser-wasm.md](roadmap/browser-wasm.md) | **浏览器 WASM 路线 C(C0–C5 Completed)** |
|
||||
| [roadmap/browser-wasm-d.md](roadmap/browser-wasm-d.md) | **路线 D:作者零 JS 前端(Completed)** |
|
||||
| [roadmap/browser-wasm-e.md](roadmap/browser-wasm-e.md) | **路线 E:前端能力补齐(Completed)** |
|
||||
| [roadmap/browser-wasm-f.md](roadmap/browser-wasm-f.md) | **路线 F:媒体/文件/Canvas 等(Completed,F1–F5;v0.3.3)** |
|
||||
| [design/browser-marqdo-wasm.md](design/browser-marqdo-wasm.md) | **浏览器 Marqdo(WASM)设计** |
|
||||
| [roadmap/ext-quantum.md](roadmap/ext-quantum.md) | **规划:`ext/quantum` 量子模拟**(基础门·电路·ABI·`ext add`) |
|
||||
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
|
||||
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
|
||||
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点**(产品化 / 评测 / MCP / resume) |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` 深入优化 A0–A4**(已完成) |
|
||||
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** |
|
||||
| [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** |
|
||||
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** |
|
||||
|
||||
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
|
||||
|
||||
|
||||
@@ -0,0 +1,57 @@
|
||||
# ADR 0002:浏览器内 Marqdo = WASM 解释器(路线 C)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted** |
|
||||
| 日期 | 2026-09-01 |
|
||||
| 决策者 | chaungming + 协作 |
|
||||
| 相关 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [roadmap/browser-wasm.md](../roadmap/browser-wasm.md) · [interpreter.md](../roadmap/interpreter.md) · [0001](0001-implementation-language.md) |
|
||||
|
||||
---
|
||||
|
||||
## 背景
|
||||
|
||||
`ext/web` 已把站点装配成「源码以 `.mq.md` 为主、服务端 Rust 解释执行」。作者面仍缺**浏览器内**的同一语言:事件、局部状态、客户端 fetch/WS 回调今天要么手写 JS,要么完全不做。
|
||||
|
||||
候选路线:
|
||||
|
||||
| 代号 | 做法 |
|
||||
|------|------|
|
||||
| **A** | 服务端驱动 + 极薄固定增强(类 HTMX) |
|
||||
| **B** | 把 Marqdo **编译/翻译成 JavaScript** |
|
||||
| **C** | 把 **Rust 解释器/字节码 VM 编成 WASM**,浏览器跑同一套语义 |
|
||||
|
||||
产品叙事目标:**网络项目源码树可以只有 `.mq.md`**(JS/WASM 为生成或发行物,不是第二作者语言)。
|
||||
|
||||
---
|
||||
|
||||
## 决策
|
||||
|
||||
1. **选定路线 C**:浏览器内运行 **与主机同构的 Marqdo 语义**(parse → tree 和/或 bytecode VM),制品为 `marqdo.wasm` + 极薄 JS 宿主桥。
|
||||
2. **不选定 B 作为主路径**:翻译到 JS 易语义漂移,长期要维护两套后端;B 至多作实验,不替代 C。
|
||||
3. **A 不对立**:内容站 / SSR / 表单 POST 仍以服务端 `ext/web` 为主;C 负责「必须在客户端执行的 Marqdo」。
|
||||
4. **同一内核、两套宿主**:`server`(今日 CLI + axum 插件)与 `browser`(DOM / `fetch` / 定时器 / storage);**不是**把 axum、`plugins/web`、SQLite 服务端塞进浏览器。
|
||||
5. **另开设计与路线图**(见相关链接);实现按 **C0→C5** 切片,金样对齐主机行为。
|
||||
6. **与「编译 mq.md → WASM 机器码」区分**:本 ADR 是 **解释器/VM 上 WASM**;把 `.mq.md` 直接编译成独立 wasm 模块仍属 `interpreter.md` Phase III 可选项,**另案**,不替代本决策。
|
||||
|
||||
---
|
||||
|
||||
## 后果
|
||||
|
||||
- 核心库必须可 **feature-gate** 掉 `libloading` / `ureq` / `tiny_http` / TTY `libc` 等,以便 `wasm32-unknown-unknown` 链接。
|
||||
- 新增公共 API:`run_source`(内存源码 + 可选导入图),供 WASM 与测试共用。
|
||||
- 浏览器侧宿主 API 以表驱动「交互装配」暴露(对称于 `样式装配`);`ext/**` 仍不直接调 `host_*`。
|
||||
- 发行物可包含 `.wasm` / 生成的 loader;**作者仓库可不提交手写业务 JS**。
|
||||
- view 断点 / 静态文档站调试可复用同一 WASM 解释器(与 `next-phase.md` 所述一致)。
|
||||
|
||||
---
|
||||
|
||||
## 否决 / 非目标(本 ADR)
|
||||
|
||||
| 方案 / 目标 | 原因 |
|
||||
|-------------|------|
|
||||
| 以 B(编译到 JS)为主交付 | 语义双轨;与「一种语言」冲突 |
|
||||
| 浏览器内完整复刻 `plugins/web` 服务器 | 协议与权限模型不同;服务端仍 axum |
|
||||
| 浏览器 `dlopen` 原生插件 | WASM 无 POSIX 动态库模型 |
|
||||
| v1 消灭一切 JS 字节 | 胶水与发行 loader 允许存在;禁止的是**业务手写 JS** |
|
||||
| 用 Daphne/ASGI 托管 Marqdo | 已否决,见 [web-asgi-servers-and-marqdo.md](../design/web-asgi-servers-and-marqdo.md) |
|
||||
@@ -0,0 +1,48 @@
|
||||
# ADR 0003:浏览器异步 I/O(fetch / 定时)— 效应表 + 续体回调
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted** |
|
||||
| 日期 | 2026-09-01 |
|
||||
| 决策者 | chaungming + 协作 |
|
||||
| 相关 | [0002-browser-marqdo-wasm.md](0002-browser-marqdo-wasm.md) · [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [roadmap/browser-wasm.md](../roadmap/browser-wasm.md) |
|
||||
|
||||
---
|
||||
|
||||
## 背景
|
||||
|
||||
Marqdo 调用面今日以**同步**为主。浏览器 `fetch` / `setTimeout` 是异步的;若在 WASM 里阻塞等待,会卡死 UI,且 `wasm32-unknown-unknown` 无真实阻塞 HTTP。
|
||||
|
||||
C3 已有:`mq_call` 返回 Map(如 `set_text`)由官方 bridge 执行。C4 在同一通道上扩展异步效应。
|
||||
|
||||
---
|
||||
|
||||
## 决策
|
||||
|
||||
1. **不**在语言内核引入 async/await 关键字或假同步 `fetch`。
|
||||
2. 处理器返回值可含**效应字段**(与 `set_text` 并列),由 **JS bridge** 执行:
|
||||
- `fetch`: `{ url, method?, then, headers?, body? }`
|
||||
- `after`: `{ ms, then }`(定时续体)
|
||||
3. 异步完成后 bridge 调用 `mq_call(then, payload)`:
|
||||
- fetch 成功/失败:`{ ok, status, body, error? }`
|
||||
- after:`{ ok: true }`
|
||||
4. 能力默认关网络语义仍由**返回效应**显式开启(站点作者主动返回 `fetch`);CORS / 鉴权仍是浏览器与服务端责任。
|
||||
5. 服务端 `lib/net` / `plugins/web` **不变**;本 ADR 仅浏览器 WASM 宿主。
|
||||
|
||||
---
|
||||
|
||||
## 后果
|
||||
|
||||
- 作者用表格/Map 声明「请求谁、完成后调谁」,无手写业务 JS。
|
||||
- Bridge 必须串行处理效应(先 `set_text`,再调度 `fetch`/`after`)。
|
||||
- 深层 Promise 链靠多次 `then` 回调;不在 C4 做通用 async 运行时。
|
||||
|
||||
---
|
||||
|
||||
## 否决
|
||||
|
||||
| 方案 | 原因 |
|
||||
|------|------|
|
||||
| WASM 内同步阻塞 `fetch` | 卡死主线程;平台不支持 |
|
||||
| 编译期把 Marqdo 译成 async JS | 回到路线 B |
|
||||
| 在核心加 `await` 关键字 | 违反 Markup-as-Syntax / 关键字纪律 |
|
||||
@@ -0,0 +1,397 @@
|
||||
# 浏览器 Marqdo(WASM 解释器)设计
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted(设计锁定)** · 实现见路线图 C0–C5 |
|
||||
| 日期 | 2026-09-01 |
|
||||
| ADR | [0002-browser-marqdo-wasm.md](../adr/0002-browser-marqdo-wasm.md) |
|
||||
| 路线图 | [roadmap/browser-wasm.md](../roadmap/browser-wasm.md) |
|
||||
| 相关 | [ext-web.md](ext-web.md) · [bytecode.md](bytecode.md) · [web-assets-and-images.md](web-assets-and-images.md) · [table-cell-expressions.md](table-cell-expressions.md) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**源码只有 `.mq.md`;浏览器跑与 CLI 同构的 Marqdo VM(WASM);JS 只做宿主桥与加载器,不做业务语言。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标与非目标
|
||||
|
||||
### 1.1 目标
|
||||
|
||||
| # | 目标 |
|
||||
|---|------|
|
||||
| G1 | 浏览器内执行合法 `.mq.md`(至少 `# main` + 打印/绑定/分支/循环/表/调用) |
|
||||
| G2 | 与主机 **tree**(及后续 **bytecode**)金样在共享子集上 stdout/返回值一致 |
|
||||
| G3 | 作者用 GFM 表声明交互(选择器 / 事件 / 调用),对称于 `样式装配` |
|
||||
| G4 | 仓库源码树可不含业务 `.js`;允许提交或由工具生成 `marqdo.wasm` + 官方 loader |
|
||||
| G5 | `import lib/…` 在浏览器可用(嵌入式 `lib/` 或打包进 wasm) |
|
||||
|
||||
### 1.2 非目标(本波 / C0–C3)
|
||||
|
||||
| # | 非目标 |
|
||||
|---|--------|
|
||||
| N1 | 在浏览器复刻 axum、`web_listen`、SQLite 服务端、admin UI |
|
||||
| N2 | `plugin.load` 加载原生 `.so` / 浏览器内 dlopen |
|
||||
| N3 | 把整站 `plugins/web` ABI 原样搬进 WASM |
|
||||
| N4 | 把 `.mq.md` 编译成独立机器码 WASM(异于「解释器上 WASM」) |
|
||||
| N5 | 强制内容站必须加载 WASM(纯 SSR 站可继续零客户端逻辑) |
|
||||
|
||||
---
|
||||
|
||||
## 2. 架构
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────┐
|
||||
│ Page (HTML shell from ext/web SSR or static) │
|
||||
│ ┌──────────────┐ ┌─────────────────────────────────┐ │
|
||||
│ │ DOM / CSS │ │ Official JS loader (thin) │ │
|
||||
│ └──────▲───────┘ │ - WebAssembly.instantiate │ │
|
||||
│ │ bridge │ - marqdo_run_source / on_event │ │
|
||||
│ │ └──────────────┬──────────────────┘ │
|
||||
│ │ │ │
|
||||
│ │ ┌──────────▼──────────┐ │
|
||||
│ │ │ marqdo.wasm │ │
|
||||
│ │ │ parse → load → │ │
|
||||
│ └──────────────│ Interpreter | Vm │ │
|
||||
│ host_dom_* │ HostContext(browser)│ │
|
||||
│ host_fetch_* │ embedded lib/ │ │
|
||||
│ └─────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────┘
|
||||
|
||||
Server (unchanged):
|
||||
marqdo run / plugins/web (axum) — SSR, DB, auth, full site
|
||||
```
|
||||
|
||||
**原则:** 一套语言语义;**HostContext 分型**(`native` vs `browser`),不是两套语法。
|
||||
|
||||
---
|
||||
|
||||
## 3. 与现有流水线对齐
|
||||
|
||||
主机今日(见 `src/lib.rs`):
|
||||
|
||||
```
|
||||
path → fs::read → load_module → Interpreter|Vm → HostContext(native)
|
||||
```
|
||||
|
||||
浏览器目标:
|
||||
|
||||
```
|
||||
source: &str (+ optional import map)
|
||||
→ load_module_from_memory
|
||||
→ Interpreter|Vm (capture stdout)
|
||||
→ HostContext(browser caps)
|
||||
→ { ok, stdout, value_json, error }
|
||||
```
|
||||
|
||||
公共库 API(C0/C1 必须落地):
|
||||
|
||||
| API | 职责 |
|
||||
|-----|------|
|
||||
| `run_source(source, opts) -> Result<RunCapture>` | 无路径入口;cwd/fs_root 虚拟 |
|
||||
| `RunOptions` 浏览器默认 | `allow_fs_write=false`, `allow_exec=false`, `allow_net=false`(net 经显式 bridge 再开) |
|
||||
| `load` 导入 | `lib/**` → `embedded_lib`;用户模块 → JS 注入的 `HashMap<path, source>` |
|
||||
|
||||
后端优先级:
|
||||
|
||||
1. **C1:tree**(与默认 CLI 一致,调试简单)
|
||||
2. **C2+:bytecode** 可选(体积/性能;金样双后端)
|
||||
|
||||
---
|
||||
|
||||
## 4. Cargo / 制品布局
|
||||
|
||||
### 4.1 Feature 门(核心 crate `marqdo`)
|
||||
|
||||
| Feature | 默认(native) | `wasm-core` | 作用 |
|
||||
|---------|----------------|-------------|------|
|
||||
| `cli` | on | off | `main` / clap 仅 bin |
|
||||
| `view` | on | off | `tiny_http` 文档浏览器 |
|
||||
| `net-host` | on | off | `ureq` HTTP 客户端 |
|
||||
| `plugin-host` | on | off | `libloading` 原生插件 |
|
||||
| `exec-host` | on | off | `std::process` / foreign |
|
||||
| `fs-host` | on | off | 真实磁盘读写(可读可后续经 VFS 桥) |
|
||||
| `wasm-core` | off | on | 浏览器子集编译开关 |
|
||||
|
||||
`wasm32-unknown-unknown` 构建:**不得**链接 `libloading`、`ureq`、`tiny_http`、TTY `libc`。
|
||||
|
||||
### 4.2 包
|
||||
|
||||
| 路径 | 角色 |
|
||||
|------|------|
|
||||
| `marqdo`(根) | 核心;feature-gate |
|
||||
| `crates/marqdo-wasm` | `cdylib`:`mq_*` ABI + `js/marqdo-bridge.js` |
|
||||
| `ext/web` 或 `web/browser` | L1:`浏览器.运行` / `交互装配`(C3+) |
|
||||
| `examples/browser-hello/` | 静态页 + wasm 冒烟 |
|
||||
| `tests/browser/` 或金样脚本 | Node/wasmtime 跑 `run_source` 对齐 |
|
||||
|
||||
发行:`marqdo wasm build`(C2 CLI 糖)或 `wasm-pack build crates/marqdo-wasm`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 宿主能力矩阵
|
||||
|
||||
| 能力 | Native | Browser C1 | Browser C3+ |
|
||||
|------|--------|------------|-------------|
|
||||
| `print` / 捕获 stdout | ✓ | ✓ → 可镜像 `console` | ✓ |
|
||||
| `input` | stdin / preset | **仅 preset / JS 喂入** | 可选 prompt 桥 |
|
||||
| builtins / 表 / 算术 | ✓ | ✓ | ✓ |
|
||||
| `lib/math` `lib/json` `lib/collection` | ✓ | ✓(embedded) | ✓ |
|
||||
| `lib/fs` 真磁盘 | ✓ | ✗ 明确报错 | 可选 OPFS/VFS 桥 |
|
||||
| `lib/net` ureq | ✓ | ✗ | `fetch` 桥(异步模型见 §7) |
|
||||
| `plugin.load` | ✓ | ✗ | ✗(改 L1 浏览器专用) |
|
||||
| `exec` / foreign | ✓ | ✗ | ✗ |
|
||||
| DOM / 事件 | ✗ | stub | **交互装配** |
|
||||
| `sleep` | thread | 0 或 JS timer(异步) | timer |
|
||||
|
||||
错误策略:**显式失败**(诊断字符串含 `unavailable in browser wasm`),禁止静默空成功。
|
||||
|
||||
---
|
||||
|
||||
## 6. 交互装配(C3,对称样式装配)
|
||||
|
||||
### 6.1 作者面(示例)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import json:lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`count` = 0*
|
||||
|
||||
`wire` =
|
||||
|
||||
| @ | 选择器 | 事件 | 调用 |
|
||||
|---|--------|------|------|
|
||||
| 1 | "#bump" | click | bump |
|
||||
|
||||
**`wire`**
|
||||
|
||||
## bump
|
||||
*`count` = count + 1*
|
||||
*`label` = > str count*
|
||||
*`patch` = > json.set map=None key="#count" value=label*
|
||||
**> json.set map=None key="set_text" value=patch**
|
||||
```
|
||||
|
||||
`# main` 的返回值是 **wire 表**(`@` 行向记录列表)。Loader 调用 `mq_boot`,再 `wireEvents`。
|
||||
|
||||
### 6.2 桥约定
|
||||
|
||||
| 步骤 | API |
|
||||
|------|-----|
|
||||
| 启动 | `mq_boot(source)` → `{ ok, value }`;`value` = wire 列表或 `{ wire: [...] }` |
|
||||
| 事件 | Loader `addEventListener` → `mq_call(fn, {"event":"click"})` |
|
||||
| 回写 | 返回 Map 可含 `set_text`: `{ "#sel": "text" }`(仅 `textContent`) |
|
||||
|
||||
行键名认:`选择器`/`selector`、`事件`/`event`、`调用`/`call`。
|
||||
|
||||
含 `/` 的 CSS 等单元格仍 **引号优先**(见 [table-cell-expressions.md](table-cell-expressions.md))。
|
||||
|
||||
L1 `浏览器.交互装配`(ext)可后置;C3 以 bridge + 返回 wire 表即可验收。
|
||||
|
||||
---
|
||||
|
||||
## 7. 异步模型(C4)
|
||||
|
||||
锁定:[ADR 0003](../adr/0003-browser-async-effects.md)。
|
||||
|
||||
处理器返回 Map 可含(与 `set_text` 并列):
|
||||
|
||||
| 字段 | 含义 | 完成后 `mq_call` 实参 |
|
||||
|------|------|----------------------|
|
||||
| `fetch` | `{ url, method?, then, headers?, body? }` | `{ ok, status, body, error? }` |
|
||||
| `after` | `{ ms, then }` | `{ ok: true }` |
|
||||
|
||||
Bridge:`applyEffects(exports, value)` — 先 DOM,再调度异步;**不**在 WASM 内阻塞。
|
||||
|
||||
示例见 `examples/browser-hello/fetch.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 安全
|
||||
|
||||
| 项 | 规则 |
|
||||
|----|------|
|
||||
| 默认能力 | 无磁盘写、无 exec、无任意 net |
|
||||
| 源码来源 | 同源或构建时嵌入;不默认 `eval` 远程不可信脚本除非站点显式开启 |
|
||||
| DOM | 仅经装配表/白名单 API;不暴露任意 `innerHTML` 字符串执行第三方脚本 |
|
||||
| CSRF / Cookie | 浏览器 Marqdo **不替代**服务端鉴权;cookie 仍走 HTTP |
|
||||
|
||||
---
|
||||
|
||||
## 9. 与 `ext/web` 分工
|
||||
|
||||
| 层 | 负责 |
|
||||
|----|------|
|
||||
| 服务端 `plugins/web` | 路由、DB、会话、SSR HTML、样式/头/图装配 |
|
||||
| 页面壳 | `头装配` 挂 `module` → `marqdo-bridge.js`;`static` 提供 `.wasm` |
|
||||
| 浏览器 L1 | `客户端挂载` / `client_embed`;效应约定见 ADR 0003 |
|
||||
| 核心 / crate | `run_source`、`BrowserSession`、`marqdo-wasm` ABI |
|
||||
|
||||
挂载示例:
|
||||
|
||||
```markdown
|
||||
`头` =
|
||||
|
||||
| 关系 | 地址 |
|
||||
|------|------|
|
||||
| module | /static/marqdo-bridge.js |
|
||||
|
||||
*p = > page.头装配 表=头*
|
||||
```
|
||||
|
||||
```bash
|
||||
marqdo wasm build -o static # marqdo_wasm.wasm + marqdo-bridge.js
|
||||
# app.static dir=static
|
||||
```
|
||||
|
||||
业务页再 `boot` 自己的 `.mq.md`(见 `examples/browser-hello/`)。
|
||||
|
||||
---
|
||||
|
||||
## 10. 测试与验收
|
||||
|
||||
| 级 | 内容 |
|
||||
|----|------|
|
||||
| 单元 | `run_source("…# main\n> print…")` native 与 wasm 同测 |
|
||||
| 金样子集 | `tests/structure/hello.mq.md` 等无 fs/net/plugin 的样例 |
|
||||
| 浏览器冒烟 | `examples/browser-hello`:按钮点击 → Marqdo 函数 → 改 DOM 文本 |
|
||||
| 回归 | CI:`cargo test` native;另 job `wasm-pack build` / `cargo check --target wasm32-unknown-unknown --no-default-features --features wasm-core` |
|
||||
|
||||
---
|
||||
|
||||
## 11. 文档与技能同步
|
||||
|
||||
- ADR 0002、本文、路线图 C0–C5。
|
||||
- `.cursor/skills/marqdo/SKILL.md`:补充「浏览器 WASM / 交互装配 / 引号 CSS」。
|
||||
- `CHANGELOG`:Unreleased 记录设计锁定与各 C 完成项。
|
||||
|
||||
---
|
||||
|
||||
## 12. 风险
|
||||
|
||||
| 风险 | 缓解 |
|
||||
|------|------|
|
||||
| wasm 体积过大 | `release-wasm` profile(`opt-level=z` + LTO + strip);`marqdo wasm build` 打印 KiB,有则跑 `wasm-opt -Oz` |
|
||||
| 异步拖垮语言 | ADR 0003 效应表;不阻塞 WASM |
|
||||
| Feature-gate 伤 native | 默认 features = 今日行为;CI 全绿再合 |
|
||||
| 作者误以浏览器替代服务器安全 | 文档强调鉴权在服务端 |
|
||||
| 会话要 bytecode | **未做**:`BrowserSession` 固定 tree(缺 entry-env invoke);`run_source` 已支持 bytecode |
|
||||
|
||||
---
|
||||
|
||||
## 14. C5 硬化(已落地)
|
||||
|
||||
| 项 | 状态 |
|
||||
|----|------|
|
||||
| `profile.release-wasm` + `marqdo wasm build` 体积报告 | done(~0.9 MiB) |
|
||||
| 可选 `wasm-opt` | done |
|
||||
| `run_source` bytecode 金样 | done |
|
||||
| 规范 bridge + 构建拷贝 | done(`crates/marqdo-wasm/js/`) |
|
||||
| Node ABI 冒烟 | done(`tests/wasm`) |
|
||||
| 站点 `头装配` / L1 `client_embed` | done |
|
||||
| 会话 bytecode / view 断点复用 | **非本版目标** |
|
||||
|
||||
---
|
||||
|
||||
## 16. 路线 D — 作者零 JS(Active)
|
||||
|
||||
路线图:[browser-wasm-d.md](../roadmap/browser-wasm-d.md)。
|
||||
|
||||
**原则:** 业务与交互 100% `.mq.md`;`marqdo-bridge.js` 仅宿主胶。作者仓库可不含自写 `.js`。
|
||||
|
||||
### 16.1 一键挂载
|
||||
|
||||
| API | 含义 |
|
||||
|-----|------|
|
||||
| `mount({ wasmUrl, source \| sourceUrl, … })` | `loadWasm` → `boot` → `wireEvents` → 初始效应 |
|
||||
| `script[data-mq-source-url]` / `data-mq-wasm` | 模块脚本属性自启 |
|
||||
| `#marqdo-boot` | `application/json` 配置块 |
|
||||
| `data-mq-playground` | 官方 playground(`#src,#run,#out`),仍非业务 JS |
|
||||
|
||||
`ext/web`:`client_embed` / `客户端挂载` 参数 `bridge`、`wasm`、`source`、`boot`(默认 true)。
|
||||
|
||||
```bash
|
||||
marqdo wasm build -o static # marqdo_wasm.wasm + marqdo-bridge.js
|
||||
# app.static dir=static
|
||||
# intro 或主区嵌入 > web.client_embed source="/static/client.mq.md"
|
||||
```
|
||||
|
||||
### 16.2 DOM / 表单效应(D3)
|
||||
|
||||
与 `set_text` / `fetch` / `after` 并列(白名单;**默认无**任意脚本注入):
|
||||
|
||||
| 字段 | 作用 |
|
||||
|------|------|
|
||||
| `set_text` | `textContent` |
|
||||
| `set_value` | input/textarea/select 的 `value` |
|
||||
| `set_attr` | 属性;值为 `null`/`false` 则 `removeAttribute` |
|
||||
| `set_class` | `className` 字符串 |
|
||||
| `toggle_class` | `{ "#sel": "cls" }` 切换 class |
|
||||
| `set_html` | **仅**键前缀 `#trusted` 的选择器才写 `innerHTML`;其它键忽略 |
|
||||
|
||||
Wire 行可选 `值选择器` / `value_from`:事件触发时把该节点内容写入实参 `value`。
|
||||
事件实参默认含:`event`、`value`、`checked`、`id`(来自 event.target);`submit` 另含 `fields` 表单字典。
|
||||
|
||||
L1:`web.dom_patch` / `网页.DOM补丁` 合并效应键;`web.text_patch` / `网页.文本补丁` 快捷 `set_text`。
|
||||
|
||||
### 16.3 非目标(D)
|
||||
|
||||
| # | 非目标 |
|
||||
|---|--------|
|
||||
| D-N1 | 用 Marqdo 重写 bridge 自身 |
|
||||
| D-N2 | 作者手写业务 JS / TS(官方桥内机制允许) |
|
||||
| D-N3 | ~~开放无前缀的 set_html~~(E 已允许任意选择器;内容由 MQ 产出) |
|
||||
|
||||
---
|
||||
|
||||
## 17. 路线 E — 前端能力补齐(Active)
|
||||
|
||||
路线图:[browser-wasm-e.md](../roadmap/browser-wasm-e.md)。
|
||||
|
||||
**原则:** 唯一硬禁是**作者手写业务 JS**。官方 bridge 可实现列表装配、路由、storage、WebSocket、内部模板/轻量 VDOM 等;作者只写 `.mq.md` + 效应表。
|
||||
|
||||
| 波 | 要点 |
|
||||
|----|------|
|
||||
| E1 | `set_style` / `focus` / `blur` / `scroll_into`;wire `委托`;键盘事件 |
|
||||
| E2 | `set_html` / `replace_children` / `render_list` |
|
||||
| E3 | `navigate` + `popstate`(选择器 `window`) |
|
||||
| E4 | `storage` `{ op, key, value?, scope?, then? }` |
|
||||
| E5 | `ws` `{ op: open\|send\|close, … }` |
|
||||
| E6 | `fetch_all` / `interval` / `clear_interval` / fetch `fields` |
|
||||
|
||||
### 17.1 效应速查(E)
|
||||
|
||||
| 字段 | 含义 |
|
||||
|------|------|
|
||||
| `set_style` | `{ "#sel": { color: "red" } }` 或 `{ "#sel": "color:red" }` |
|
||||
| `focus` / `blur` | `"#sel"` 或选择器数组 |
|
||||
| `scroll_into` | `"#sel"` |
|
||||
| `set_html` / `append_html` / `replace_children` | 写/追加 HTML(MQ 产出;XSS 自负) |
|
||||
| `render_list` | `{ "#sel": { tag, items } }` |
|
||||
| `remove` | 选择器或数组,删除节点 |
|
||||
| `add_class` / `remove_class` | classList |
|
||||
| `navigate` | `{ url, replace?: bool }` |
|
||||
| `storage` | `{ op, key, value?, scope?: local\|session\|cookie, days?, then? }` |
|
||||
| `ws` | `{ op: open\|send\|close, … }` |
|
||||
| `fetch_all` | `{ requests: []\|map, then }` |
|
||||
| `interval` / `clear_interval` | 定时 |
|
||||
| `clipboard` / `download` | 剪贴板 / 触发下载 |
|
||||
| `fetch.fields` | → FormData |
|
||||
|
||||
Wire 列:`委托` / `delegate` = 在容器上监听,目标须 `closest(delegate)`;选择器 `window` 绑 `window`。
|
||||
|
||||
## 15. 决策摘要
|
||||
|
||||
| 问题 | 答案 |
|
||||
|------|------|
|
||||
| 路线? | **C**:解释器/VM → WASM |
|
||||
| 作者语言? | 仅 `.mq.md` |
|
||||
| JS 角色? | Loader + 宿主桥 |
|
||||
| 服务端? | 保留;不塞进浏览器 |
|
||||
| 第一步实现? | C0 门控可编译 + C1 `run_source` 打印闭环 |
|
||||
@@ -82,6 +82,9 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`import x:x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
|
||||
| **regex** (=1.13.1) | 正则 | Mid M1 `lib/re`;`default-features=false` + `std`/`unicode`;无回溯引用 |
|
||||
| **sha2** (=0.10.9) / **sha1** (=0.10.6) / **md-5** (=0.10.6) / **hmac** (=0.12.1) | 摘要 | Mid M3 `lib/hash` |
|
||||
| **getrandom** (=0.2.17) | OS 熵 | Mid M3 `lib/secrets` |
|
||||
|
||||
#### 强烈建议
|
||||
|
||||
|
||||
+64
-26
@@ -2,9 +2,9 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| Status | **Accepted (v0.1)** |
|
||||
| Date | 2026-08-07 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) |
|
||||
| Status | **Accepted (v0.3.5 prep)** — prebuilt native download |
|
||||
| Date | 2026-09-04 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) · [08-ext-deploy-coupling.md](ext-web-customization/08-ext-deploy-coupling.md) |
|
||||
|
||||
## Commands
|
||||
|
||||
@@ -12,8 +12,8 @@
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext remove llm
|
||||
marqdo ext remove agent
|
||||
```
|
||||
|
||||
## Install root
|
||||
@@ -23,50 +23,88 @@ marqdo ext remove agent
|
||||
|
||||
Imports use paths like `import llm:ext/ai/llm.mq.md` (see [`load.rs`](../../src/load.rs)).
|
||||
|
||||
## Source for `add`
|
||||
## Goal: no local Rust required
|
||||
|
||||
End users who install Marqdo from **GitHub Releases** should run:
|
||||
|
||||
```bash
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
and get both L1 `.mq.md` **and** the matching native plugin (`.dll` / `.so`) **without** `cargo build`.
|
||||
|
||||
### Resolution order (`add` with native crate)
|
||||
|
||||
1. Local artifact (`MARQDO_*_PLUGIN`, `target/{debug,release}`, beside `marqdo`, `MARQDO_EXT_SOURCE/native`, …)
|
||||
2. **Download** `marqdo-{VER}-native-{target}.zip` from the GitHub Release for this CLI version → cache under `~/.marqdo/cache/`
|
||||
3. If Rust/`cargo` is available → `cargo build -p marqdo_plugin_*` (developers)
|
||||
4. Else fail with a clear message pointing at the Release assets
|
||||
|
||||
L1 sources:
|
||||
|
||||
1. `MARQDO_EXT_SOURCE` / repo `./ext` / beside binary
|
||||
2. Else download `marqdo-{VER}-ext.zip` into `~/.marqdo/cache/ext-src-v{VER}/`
|
||||
|
||||
### Env knobs
|
||||
|
||||
| Variable | Meaning |
|
||||
|----------|---------|
|
||||
| `MARQDO_EXT_VERSION` | Override SemVer used for Release asset names (default: CLI `CARGO_PKG_VERSION`) |
|
||||
| `MARQDO_EXT_NO_DOWNLOAD=1` | Never hit the network (CI / air-gap); local/cargo only |
|
||||
| `MARQDO_WEB_PLUGIN` / `MARQDO_AGENT_PLUGIN` / `MARQDO_QUANTUM_PLUGIN` | Explicit native path |
|
||||
|
||||
Windows Release **zip** also ships `ext/` + `ext/native/*.dll` next to `marqdo.exe` so a portable unzip works offline after one download.
|
||||
|
||||
## Source for `add` (developers)
|
||||
|
||||
1. `MARQDO_EXT_SOURCE` — directory containing `ai/llm.mq.md` …
|
||||
2. Else repo `./ext` near cwd / binary
|
||||
2. Else repo `./ext` near cwd / binary
|
||||
3. Else Release `marqdo-*-ext.zip` (see above)
|
||||
|
||||
## Layout (`ext/`)
|
||||
|
||||
Official extensions live under **`ext/ai/`** (LLM + agent framework only). Do not add flat `.mq.md` files at `ext/` root — keeps the tree from accumulating unrelated modules.
|
||||
|
||||
```text
|
||||
ext/
|
||||
ai/
|
||||
llm.mq.md
|
||||
大模型.mq.md
|
||||
agent.mq.md
|
||||
智能体.mq.md
|
||||
ai/ # llm + agent L1
|
||||
web/
|
||||
quantum/
|
||||
```
|
||||
|
||||
Future optional ext domains get their own subdirs (e.g. `ext/web/`, `ext/quantum/`), not mixed into `ai/`.
|
||||
Installed tree (`~/.marqdo/ext` or `MARQDO_EXT`):
|
||||
|
||||
```text
|
||||
web/web.mq.md
|
||||
web/网页.mq.md
|
||||
native/libweb.so # or web.dll / libweb.dylib
|
||||
web.plugin # absolute path hint
|
||||
```
|
||||
|
||||
## Catalog
|
||||
|
||||
| Id | Installs under `MARQDO_EXT` |
|
||||
|----|-----------------------------|
|
||||
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **`native/libagent.so`** (or `.dylib`) |
|
||||
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **`native/libweb.so`** — 见 [ext-web.md](ext-web.md) · [roadmap](../roadmap/ext-web.md) |
|
||||
| `quantum` | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **`native/libquantum.so`** — 见 [ext-quantum.md](ext-quantum.md) · [roadmap](../roadmap/ext-quantum.md) |
|
||||
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **native `agent`** |
|
||||
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **native `web`** |
|
||||
| `quantum` | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **native `quantum`** |
|
||||
|
||||
`add agent` copies the built native plugin into `MARQDO_EXT/native/`. Build it first:
|
||||
## Release assets (native)
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo_plugin_agent
|
||||
marqdo ext add agent
|
||||
```
|
||||
| Asset | Platform |
|
||||
|-------|----------|
|
||||
| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Windows x64 (`native/*.dll`) |
|
||||
| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Linux x64 (`native/lib*.so`) |
|
||||
|
||||
Without install, runtime resolves the plugin via `plugin.native_path name=agent` (see [ext-abi.md](ext-abi.md)): `MARQDO_AGENT_PLUGIN` → `CARGO_TARGET_DIR/{debug,release}/` → cwd `target/…` → beside `marqdo` binary → `MARQDO_EXT/native/`.
|
||||
macOS: use local `cargo build` until CI adds Darwin natives (same zip naming pattern reserved).
|
||||
|
||||
## Tests
|
||||
|
||||
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` ([`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md); needs `tests/ext/.env` + built `libagent`).
|
||||
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_cli_add_web` (local build path; set `MARQDO_EXT_NO_DOWNLOAD=1` in sandboxes if needed).
|
||||
|
||||
Unit: `ext_fetch` URL / triple tests.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Third-party registry
|
||||
- Merging into `lib/`
|
||||
- Bundling domain/task helpers in official ext
|
||||
- Merging domain helpers into `lib/`
|
||||
- Guaranteeing plugin **source** ABI stability (author `.mq.md` API is the contract)
|
||||
@@ -0,0 +1,235 @@
|
||||
# `ext/linalg` — 公式文档面(跑通即正确)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Draft · 锁定作者面哲学与分期** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 父设计 | [ext-linalg.md](ext-linalg.md) |
|
||||
| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) |
|
||||
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
|
||||
| 对照 | [stdlib-math.md](stdlib-math.md)(高中标量公式) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**`.mq.md` 里的线性代数应当读起来像一份可运行的公式讲义**:式子能跑通,就在库承诺的规则与维数下代表正确;`lib/math` 守高中边界,大学符号矩阵与更深层计算由 **`ext/linalg` 正当承担**。
|
||||
|
||||
---
|
||||
|
||||
## 1. 产品哲学
|
||||
|
||||
### 1.1 与 Marqdo 总原则对齐
|
||||
|
||||
| Marqdo | 在线性代数上的含义 |
|
||||
|--------|-------------------|
|
||||
| 代码即文档 | 矩阵代数段落用数学式书写,而不是 API 调用清单 |
|
||||
| 标记即语法 | `$$`、中缀、`# matrix` 方法都是可读标记,不是「库胶水」 |
|
||||
| 跑通可验收 | 金样 / 课堂作业:文件 exit 0 + 断言化简结果 = 式子合法 |
|
||||
|
||||
### 1.2 「跑通即正确」的精确定义
|
||||
|
||||
**不是**「任意高深定理自动证明」。
|
||||
**是**在声明的能力边界内,下列任一成立则文档该段视为正确:
|
||||
|
||||
1. **形状层**:不相容维数的乘加在构造时硬错误(写不出可运行的坏式)。
|
||||
2. **恒等式层**:文档断言的规范形(如 `(AB)^\top → B^\top A^\top`)经规则集得到。
|
||||
3. **数值核对层**(可选):小 `$$` 数值阵 `explicit` 后与手算一致——验算,不是符号证明。
|
||||
|
||||
更高深主题(矩阵微积分、表示、特殊函数矩阵等)通过**扩展同一公式面的规则表**分期加入,而不是另起一套函数库叙事。
|
||||
|
||||
### 1.3 与 `lib/math` 的边界(再次锁定)
|
||||
|
||||
| | `lib/math` | `ext/linalg` |
|
||||
|--|------------|--------------|
|
||||
| 教育边界 | 高中标量公式 | 大学经典线性代数及更深(官方 ext) |
|
||||
| 值类型 | `Value::Formula`(标量 AST) | `_type=matrix` / `矩阵`(MatExpr + 稠密) |
|
||||
| 作者感觉 | `$$sin(x)+x$$` + `diff` / `plot` | `A*B`、`(AB)^T`、分块、分解图 |
|
||||
| 是否「数学库」 | 是(stdlib) | **是数学库的官方扩展**,不是旁路工具箱 |
|
||||
|
||||
把大学 LA 塞进 `lib/math` ❌;在 `ext/linalg` 做大学符号计算乃至更深 ✅。
|
||||
|
||||
---
|
||||
|
||||
## 2. 两面模型:代数面 vs 计算面
|
||||
|
||||
文档里应能一眼分清「推导」与「动手算」。
|
||||
|
||||
### 2.1 代数面(默认;公式文档)
|
||||
|
||||
| 意图 | 写法(目标) | 语义 |
|
||||
|------|--------------|------|
|
||||
| 引入符号阵 | 见 §3 | 惰性 `MatrixSymbol` |
|
||||
| 加减乘 | `` `C` = `A` + `B` `` · `` `P` = `A` * `B` `` | 建树 + 形状检查 |
|
||||
| 转置 / 逆 | `` `At` = > `A`.T `` · `` `Ai` = > `A`.inv `` | 惰性节点 |
|
||||
| 化简 / 展示 | 见 §4(默认化简策略) | 规则不动点 → ASCII / KaTeX |
|
||||
| 分块 / Kronecker | 表或 `block` / `kron`(可保留具名,但结果仍是公式) | 惰性 |
|
||||
|
||||
**读者感受**:像在抄黑板,而不是在调 `la.mul`。
|
||||
|
||||
### 2.2 计算面(显式步骤;可单独成段)
|
||||
|
||||
| 意图 | 写法 | 语义 |
|
||||
|------|------|------|
|
||||
| 稠密求值 | `` `E` = > `A`.explicit `` / `la.explicit` | 展开数值 |
|
||||
| 分解 | `` `f` = > la.factorize matrix=`A` kind="svd" `` | `linalg_factor` |
|
||||
| 求解 / 最小二乘 | `solve` / `lstsq` | 数值解 |
|
||||
| 度量 | `norm` / `cond` / `rank` / `det`(数值路径) | 标量或条件对象 |
|
||||
| 作图 | `draw` / `show` | SVG / 公式卡 |
|
||||
|
||||
**读者感受**:「于是我们计算 / 画出…」——与纯代数叙述分段书写。
|
||||
|
||||
---
|
||||
|
||||
## 3. 目标作者语法(公式文档优先)
|
||||
|
||||
### 3.1 已落地(v1 中缀 / 方法)
|
||||
|
||||
```markdown
|
||||
*`A` = > la.symbol name="A" rows=2 cols=2*
|
||||
*`B` = > la.symbol name="B" rows=2 cols=2*
|
||||
*`C` = `A` + `B`*
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
*`s` = > `Pt`.simplify*
|
||||
*`t` = > `s`.ascii*
|
||||
```
|
||||
|
||||
数值 `$$` 矩阵可直接参与 `+` / `*`(经插件吸收为稠密叶)。
|
||||
|
||||
### 3.2 目标形态(文档感更强;分期实现)
|
||||
|
||||
**叙事理想(不必一次做完):**
|
||||
|
||||
```markdown
|
||||
# 正规方程
|
||||
|
||||
令 \(A\) 为 \(m\times n\) 设计矩阵,\(b\) 为观测。
|
||||
|
||||
*`AtA` = > `A`.T * `A`* # 或未来更紧凑的 postfix / 混合写法
|
||||
*`xty` = > `A`.T * `b`*
|
||||
*`xhat` = > `AtA`.solve b=`xty`* # 计算面
|
||||
```
|
||||
|
||||
**符号引入(减少 `la.symbol` 噪音)——候选(F2 选定一种):**
|
||||
|
||||
| 候选 | 例 | 利 | 弊 |
|
||||
|------|----|----|-----|
|
||||
| A. 构造糖 | `` `A` = > la.matrix name=A rows=m cols=n `` | 已有 `# matrix` | 仍是调用 |
|
||||
| B. 维数表 | GFM 表声明符号与形状,一行绑定 | 很「文档」 | 需新约定 |
|
||||
| C. `$$` 符号方言 | `$$A_{m\times n}$$` → MatExpr | 最像讲义 | 解析歧义;勿污染标量 formula |
|
||||
| D. 保持 `symbol` + 短别名 | `` `A` = > la.A rows=m cols=n `` | 实现便宜 | 文档感一般 |
|
||||
|
||||
**锁定倾向:** 短期 **A + 默认化简(F1)**;**F2 采用 B(GFM `@` 表 + `la.declare`)**;受限 C(`$$` 符号方言)仍待评估且不得污染核心 formula。
|
||||
|
||||
### 3.3 明确不做(本波语法)
|
||||
|
||||
- 把符号 MatExpr 塞进核心 `formula::Expr`
|
||||
- 发明与 Markdown 列表冲突的行首 `+` 矩阵语法
|
||||
- 用未定义的 `$$矩阵A$$` 伪方言冒充已实现语义
|
||||
|
||||
---
|
||||
|
||||
## 4. 默认化简与「写出即规范」
|
||||
|
||||
### 4.1 策略
|
||||
|
||||
| 操作 | 是否自动 `simplify` | 理由 |
|
||||
|------|---------------------|------|
|
||||
| `ascii` / `latex` / `show` | **是(F1 done)** | 展示面应接近讲义规范形;`raw=True` 可关 |
|
||||
| 中缀 `+` `*` `-` 的构造结果 | **否** | 保留用户书写结构;需要时再化简 |
|
||||
| `.simplify` | 显式不动点 | 文档断言 / 金样 |
|
||||
| `explicit` 前 | 可选先 simplify(F1.1) | 减少无效稠密路径 |
|
||||
|
||||
### 4.2 验收句式(金样)
|
||||
|
||||
```markdown
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
*`t` = > `Pt`.ascii* # F1:无需再 .simplify 即得 B^T*A^T
|
||||
1. `t` == "B^T*A^T"
|
||||
> print text=ok
|
||||
```
|
||||
|
||||
「跑通 + 断言」= 这段公式文档正确。
|
||||
|
||||
---
|
||||
|
||||
## 5. 正确性分层与错误体验
|
||||
|
||||
| 层 | 失败时 | 作者应看到 |
|
||||
|----|--------|------------|
|
||||
| 形状 | `A*B` 列行不配 | 含双方 shape 的硬错误,指向调用点 |
|
||||
| 规则 | 无法化到文档期望形 | 金样失败;或 `ascii` 仍为未化简形(需补规则) |
|
||||
| 插件未加载 | 中缀矩阵运算 | 提示 `ext add linalg` / `ensure_plugin` |
|
||||
| 超维 | `explicit` / 分解 | 护栏错误,建议保持符号 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 与实现现状的对照
|
||||
|
||||
| 能力 | 状态 |
|
||||
|------|------|
|
||||
| MatExpr 惰性树 + R1–R5 / 分块 / kron | done(L1–L3) |
|
||||
| 稠密 / 分解 / 度量 / draw theme | done(L2–L6) |
|
||||
| 中缀 `+` `-` `*` + `# matrix` 方法 | done(v1) |
|
||||
| `ascii`/`latex`/`show` 默认 simplify | **done(F1)** |
|
||||
| 更少噪音的符号引入 | **done(F2:`declare` + 表)** |
|
||||
| 更紧凑转置 / 混合公式书写 | **done(F3:`T_ascii`)** |
|
||||
| `explicit` 前可选 auto-simplify | **done(F3,默认开)** |
|
||||
| public「如何写公式文档」 | **done(F3)** |
|
||||
| 矩阵微积分等 | L7+ / 规则表扩展 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 分期(公式文档面)
|
||||
|
||||
| 阶段 | 内容 | 出口 |
|
||||
|------|------|------|
|
||||
| **F1** | 展示路径默认 simplify;金样「`.T` + `ascii` → 规范形」;设计本文落地 | **done** |
|
||||
| **F2** | 符号引入降噪(选定 §3.2 候选);更新 examples 使其读起来像讲义 | **done**(`declare` + `linalg-transpose`) |
|
||||
| **F3** | 可选 postfix / 链式糖;`explicit` 前可选 auto-simplify;public 短文「如何写公式文档」 | **done** |
|
||||
| **F4+** | 新规则(伴随、多项式矩阵…);矩阵微积分仅当明确需要 | 规则表可测 |
|
||||
|
||||
---
|
||||
|
||||
## 8. 示例叙事(目标文档骨架)
|
||||
|
||||
````markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# 转置反序
|
||||
|
||||
*`A` = > la.symbol name="A" rows=2 cols=3*
|
||||
*`B` = > la.symbol name="B" rows=3 cols=2*
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
|
||||
叙述:\((AB)^\top = B^\top A^\top\)。
|
||||
|
||||
*`t` = > `Pt`.ascii*
|
||||
1. `t` == "B^T*A^T"
|
||||
> print text=identity-ok
|
||||
2. *
|
||||
> print text=identity-fail
|
||||
````
|
||||
|
||||
计算面示例保持 `examples/linalg-least-squares/`(`lstsq` + heatmap),与代数面示例分目录或分章节。
|
||||
|
||||
---
|
||||
|
||||
## 9. 开放问题
|
||||
|
||||
1. **自动 simplify 是否改变 `ascii` 金样**——凡依赖「未化简乘积串」的测试需改期望或改调 `repr_raw`(若提供)。
|
||||
2. **中文 `_type=矩阵` 与展示**——方法链已 retag;view 是否统一显示英文 kind。
|
||||
3. **`$$` 符号方言**——若做,必须经 `from_formula` 扩展,禁止改核心高中 formula 语义。
|
||||
|
||||
---
|
||||
|
||||
## 10. 收束
|
||||
|
||||
`ext/linalg` 的北极星不是「功能最多的矩阵库」,而是:
|
||||
|
||||
> **让大学线性代数(及更深)以可运行公式文档的形式存在于 Marqdo;跑通即在规则集内正确;计算与作图是显式步骤,不淹没代数叙述。**
|
||||
@@ -0,0 +1,345 @@
|
||||
# `ext/linalg` — 公式优先的线性代数扩展
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Draft · L0–L6 + 中缀 v1 · 公式文档面见专文** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
|
||||
| **公式文档面** | [ext-linalg-formula-doc.md](ext-linalg-formula-doc.md)(跑通即正确 · 代数面/计算面) |
|
||||
| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) |
|
||||
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [view.md](view.md) · [ext-quantum-q7.md](ext-quantum-q7.md) |
|
||||
| 安装(规划) | `marqdo ext add linalg`(`linalg` / `线性代数`) |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**经典线性代数以「矩阵公式」为一等公民**:抽象表达式可化简、可展示、可选求值;稠密数值与分解图走 ABI 插件——**不**并入 `lib/math`,**不**挂在 `ext/quantum` 作者面。
|
||||
|
||||
作者面北极星见 **[ext-linalg-formula-doc.md](ext-linalg-formula-doc.md)**:跑通即正确;代数面像讲义,计算面是显式步骤。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标与非目标
|
||||
|
||||
### 1.1 目标
|
||||
|
||||
1. **公式类扩展**:在现有标量 `formula` 之上,引入 **矩阵表达式(MatExpr)**——`MatrixSymbol`、乘加、转置、逆、迹、行列式、分块、Kronecker——默认**不展开**。
|
||||
2. **大规模优化**:形状检查 + 重写规则 + 惰性求值 + 分解对象复用(见 §5)。
|
||||
3. **易于展示**:KaTeX 公式卡、结构 SVG(SVD/QR/消元/特征)、数值热力图;CLI 可断言的 ASCII。
|
||||
4. **文档即实验**:GFM 表声明矩阵 / 步骤;`.mq.md` 可读可跑。
|
||||
|
||||
### 1.2 非目标(首版)
|
||||
|
||||
| 不做 | 原因 |
|
||||
|------|------|
|
||||
| 塞进 `lib/math` | 高中标量范围已锁定;大学 LA 属官方 ext |
|
||||
| 复用 `quantum.*` 作者 API | 领域混淆;量子 Q7 保持量子语义 |
|
||||
| 完整 SymPy / Mathematica | 规则表可控子集即可 |
|
||||
| 稀疏格式 / GPU / 分布式 | 超出文档语言定位 |
|
||||
| 矩阵微积分闭式(Jacobian 积木) | 记入路线图远期 |
|
||||
| 在 `ext/**` 调 `host_*` | 硬约束;数值走插件名 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层架构
|
||||
|
||||
```text
|
||||
作者 .mq.md
|
||||
│ import la:ext/linalg/linalg.mq.md
|
||||
▼
|
||||
L1 官方 ext(GFM + ## 包装,中英分文件)
|
||||
│ plugin.load name=linalg
|
||||
▼
|
||||
plugins/linalg(ABI v2)
|
||||
├── matexpr:符号树构造 / 重写 / latex
|
||||
├── dense:稠密 f64(可选复数)运算与分解
|
||||
└── draw:结构 SVG / heatmap
|
||||
│
|
||||
▼(可选)
|
||||
核心 Value::Formula 仅保留「数值矩阵字面量」现状;
|
||||
符号 MatExpr 以 **map `_type=matrix`(中文构造为 `矩阵`)** 承载,避免撑爆高中 formula AST;遗留标签 `linalg_expr` / `linalg_dense` 仍可解析。
|
||||
```
|
||||
|
||||
### 2.1 为何 MatExpr 不直接塞进 `formula::Expr`
|
||||
|
||||
| 方案 | 利 | 弊 | 决策 |
|
||||
|------|----|----|------|
|
||||
| 扩展 `formula::Expr` | 与 `$$` 一体 | 核心膨胀;高中/大学边界糊 | ❌ |
|
||||
| 插件侧表达式 + L1 对象 | 核心干净;可独立发版 | 需稳定 `_type` 与 latex 桥 | ✅ **采用** |
|
||||
| 仅 list-of-list 数值 | 简单 | 无法公式优化与符号展示 | ❌ 仅作 `explicit` 结果 |
|
||||
|
||||
**既有** `formula::Expr::Matrix`(数值 `$$`)继续服务量子门 / 小例子;`ext/linalg` 通过 `la.matrix` / `la.from_formula` 吸收为稠密叶子。
|
||||
|
||||
### 2.2 与量子的边界
|
||||
|
||||
| | `ext/linalg` | `ext/quantum` Q7 |
|
||||
|--|--------------|------------------|
|
||||
| 域 | 经典实/复矩阵 | 态 / 密度 / Pauli |
|
||||
| Kronecker | 经典 ⊗ | 复合量子系统 |
|
||||
| 图 | SVD/QR/GE/heatmap | hinton/city/qsphere/… |
|
||||
| 复用 | 插件**私有**可共享 Jacobi/SVD 代码 | 作者面 API **分离** |
|
||||
|
||||
---
|
||||
|
||||
## 3. 运行时对象(锁定草案)
|
||||
|
||||
全部经插件构造,L1 返回 **map**(`_type` 稳定,金样可断言):
|
||||
|
||||
| `_type`(英) | 中文标签 | 字段(最小) | 含义 |
|
||||
|---------------|----------|--------------|------|
|
||||
| `linalg_expr` | `线性式` | `repr`(S-expr 或内部 id)、`shape`=`[m,n]` 或符号维、`latex`、`ascii` | 抽象矩阵公式 |
|
||||
| `linalg_dense` | `稠密阵` | `rows`, `cols`, `data`(行主 list[list])、`dtype`=`real`\|`complex` | 显式数值 |
|
||||
| `linalg_factor` | `分解` | `kind`=`lu`\|`qr`\|`svd`\|`eig`\|`chol`,因子字段,`latex`,可选 `svg` | 分解结果 |
|
||||
| `linalg_svg` | — | `kind`, `svg` 文本 | 与 quantum_svg 同构展示约定 |
|
||||
| `linalg_solve` | `求解` | `x`, `residual`, `method` | 线性系 / 最小二乘 |
|
||||
|
||||
形状:`shape` 允许整数或符号维名(字符串 `"n"`);不相容 → 硬错误。
|
||||
|
||||
---
|
||||
|
||||
## 4. 作者面 API(英文 `ext/linalg/linalg.mq.md`)
|
||||
|
||||
中文镜像:`ext/linalg/线性代数.mq.md`(`矩阵` / `化简` / `求值` / `绘图`…)。
|
||||
|
||||
### 4.1 构造
|
||||
|
||||
```markdown
|
||||
# matrix
|
||||
|
||||
## symbol
|
||||
+ `name`
|
||||
+ `rows`
|
||||
+ `cols`
|
||||
# → linalg_expr MatrixSymbol
|
||||
|
||||
## eye / zeros / ones / diag
|
||||
+ …
|
||||
|
||||
## from_list
|
||||
+ `data` # list[list] 或 table
|
||||
|
||||
## from_formula
|
||||
+ `formula` # 吸收 Value::Formula Matrix 字面量
|
||||
|
||||
## block
|
||||
+ `blocks` # 表或嵌套 list of expr
|
||||
```
|
||||
|
||||
文档写法偏好:
|
||||
|
||||
````markdown
|
||||
`A` = > la.symbol name=A rows=n cols=n
|
||||
|
||||
`b` =
|
||||
$$
|
||||
\begin{pmatrix}1\\0\\0\end{pmatrix}
|
||||
$$
|
||||
|
||||
*`b` = > la.from_formula formula=`b` *
|
||||
````
|
||||
|
||||
作者面优先顶层 `la.symbol` / `la.mul`(`la.matrix.symbol` 无接收者会硬错误,见 [module-namespace.md](module-namespace.md) §4.3)。
|
||||
### 4.2 公式代数(返回 `linalg_expr`,惰性)
|
||||
|
||||
| 英文 | 中文 | 语义 |
|
||||
|------|------|------|
|
||||
| `mul` / `add` / `sub` | `乘` / `加` / `减` | 形状检查后建树 |
|
||||
| `transpose` / `T` | `转置` | |
|
||||
| `inv` | `逆` | 符号逆;不立即求数值 |
|
||||
| `pow` | `幂` | 整数幂 |
|
||||
| `trace` / `det` | `迹` / `行列式` | 可得到标量 expr 或数值 |
|
||||
| `kron` | `克罗内克` | **禁止**默认 expand |
|
||||
| `simplify` | `化简` | 应用 §5 规则集 |
|
||||
| `collapse` | `分块化简` | 对标 `block_collapse` |
|
||||
| `latex` / `ascii` | `乳胶` / `文本` | 展示字符串 |
|
||||
| `shape` | `形状` | |
|
||||
|
||||
链式 / 中缀(v1 已落地):
|
||||
|
||||
```markdown
|
||||
*`C` = `A` + `B`*
|
||||
*`P` = `A` * `B`*
|
||||
*`Pt` = > `P`.T*
|
||||
*`s` = > `Pt`.simplify*
|
||||
```
|
||||
|
||||
运行时对双方为 `matrix` / `矩阵` / 数值 `$$` 矩阵 / 遗留 `linalg_expr` 的 `+` `-` `*` 分派到插件;结果保留左操作数 `_type` 以便中英方法链。
|
||||
### 4.3 求值与分解(热路径 → 稠密)
|
||||
|
||||
| 英文 | 说明 |
|
||||
|------|------|
|
||||
| `eval` / `explicit` | 符号树 + 绑定表 → `linalg_dense`;超维硬错误 |
|
||||
| `factorize` | `kind=lu\|qr\|svd\|eig\|chol` → `linalg_factor` |
|
||||
| `solve` | `A`,`b`;或 `factor` + `b` |
|
||||
| `lstsq` | 最小二乘 |
|
||||
| `rank` / `norm` / `cond` | 数值度量 |
|
||||
| `matmul` | 稠密乘(已 explicit 时) |
|
||||
|
||||
维数上限(草案,可配置):
|
||||
|
||||
| 操作 | 默认上限 |
|
||||
|------|----------|
|
||||
| `explicit` 稠密元素总数 | \(n\cdot m \le 10^4\)(如 100×100) |
|
||||
| SVD / eig 方阵边长 | \(\le 64\)(与 quantum 密度同级) |
|
||||
| 结构 SVG(无元素) | 边长示意可达数百(只画框) |
|
||||
| KaTeX 完整数字阵 | \(\le 8\times 8\);更大只出摘要 + 结构图 |
|
||||
|
||||
### 4.4 展示
|
||||
|
||||
| 英文 | `kind` | 说明 |
|
||||
|------|--------|------|
|
||||
| `show` | — | 写入 view:优先 `latex` 公式卡 |
|
||||
| `draw` | `structure` | 形状/分块矩形(drawmatrix 风格) |
|
||||
| `draw` | `heatmap` / `hinton` | 数值幅度 |
|
||||
| `draw` | `svd` / `qr` / `ge` / `eig` | 分解结构图(对标 LAFigureSpecs) |
|
||||
| `draw` | `path`= | 可选落盘 SVG |
|
||||
|
||||
`show` 应对符号式**始终可用**(无需 `eval`)。
|
||||
|
||||
### 4.5 最小可运行示例(设计验收叙事)
|
||||
|
||||
````markdown
|
||||
---
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`A` = > la.symbol name=A rows=3 cols=3 *
|
||||
*`x` = > la.symbol name=x rows=3 cols=1 *
|
||||
*`b` = > la.mul a=`A` b=`x` *
|
||||
|
||||
*`s` = > la.simplify expr=`b` *
|
||||
> la.show expr=`s`
|
||||
|
||||
`M` =
|
||||
$$
|
||||
\begin{bmatrix}2&0\\0&3\end{bmatrix}
|
||||
$$
|
||||
|
||||
*`M` = > la.from_list data=[[2,0],[0,3]] *
|
||||
*`f` = > la.factorize matrix=`M` kind=eig *
|
||||
> la.draw factor=`f` kind=eig path=eig.svg
|
||||
````
|
||||
---
|
||||
|
||||
## 5. 公式重写与「大规模优化」(核心)
|
||||
|
||||
### 5.1 原则
|
||||
|
||||
1. **构造便宜,展开昂贵**——乘加只分配节点。
|
||||
2. **形状是类型系统**——`(m×k)·(k×n)` 合法;否则错误指向调用点。
|
||||
3. **化简是规则不动点**——有限规则表,可测、可文档化。
|
||||
4. **expand 显式开启**——`expand=True` 才对 Kronecker / 多项式矩阵做爆炸性展开。
|
||||
5. **数值路径旁路符号**——已 `explicit` 的叶子用稠密核,不再走规则。
|
||||
|
||||
### 5.2 v1 规则集(最小够用)
|
||||
|
||||
| ID | 规则 | 例 |
|
||||
|----|------|-----|
|
||||
| R1 | 单位元 | `I*A → A`,`A*I → A`,`A+0 → A` |
|
||||
| R2 | 双逆 | `(A^{-1})^{-1} → A` |
|
||||
| R3 | 转置反序 | `(AB)^\top → B^\top A^\top`,`(A^\top)^\top → A` |
|
||||
| R4 | 逆转置 | `(A^{-1})^\top → (A^\top)^{-1}` |
|
||||
| R5 | 结合扁平 | `MatMul` 链扁平化 |
|
||||
| R6 | 分块塌缩 | 对标 `block_collapse`(乘/加在块级分配) |
|
||||
| R7 | Kronecker 结合 | `(A⊗B)⊗C → A⊗B⊗C`;**不**展开成元素 |
|
||||
| R8 | 标量提出 | `c*(A+B) → c*A+c*B`(可选;默认关以免树变宽) |
|
||||
|
||||
### 5.3 数值侧优化
|
||||
|
||||
| 策略 | 说明 |
|
||||
|------|------|
|
||||
| `factorize` 一次 | 多 RHS `solve` 复用 |
|
||||
| 小阵专用核 | 2×2 / 3×3 闭式逆 / det(教学友好、可对照公式) |
|
||||
| 复杂度护栏 | 超限错误信息建议「保持符号 / 降维 / 分块」 |
|
||||
| 禁止静默降精度 | 病态 `cond` 可警告(stderr 或结果字段) |
|
||||
|
||||
---
|
||||
|
||||
## 6. 展示设计(效果)
|
||||
|
||||
### 6.1 通道
|
||||
|
||||
| 通道 | 符号 MatExpr | 稠密 | 分解 |
|
||||
|------|--------------|------|------|
|
||||
| view Structure | KaTeX `latex` 卡 | 小阵 KaTeX;大阵摘要 | 公式 + 可选 SVG |
|
||||
| view Execution plots | — | heatmap SVG | `kind=svd|…` SVG |
|
||||
| CLI `print` | `ascii` | `[[…],…]` 或摘要 | `svd(U,S,V)` 摘要 |
|
||||
| writeback | 可选记录 latex | 可选 | 可选 |
|
||||
|
||||
### 6.2 LaTeX 约定
|
||||
|
||||
- 符号:`A`,`A^{\top}`,`A^{-1}`,`AB`,`A \otimes B`
|
||||
- 数值小阵:`\begin{bmatrix}…\end{bmatrix}`
|
||||
- 分块:`\begin{bmatrix} A & B \\ C & D \end{bmatrix}`
|
||||
- 喂给既有 view:与 `formula-card` / KaTeX 同源路径(L1 `show` → `host_query("record_plot")` 或扩展「record_math」若已有;无则复用 writeback + plot 列表)
|
||||
|
||||
### 6.3 结构 SVG(教学主视觉)
|
||||
|
||||
对标 LAFigureSpecs / drawmatrix,**不**依赖 Matplotlib:
|
||||
|
||||
| `kind` | 画什么 |
|
||||
|--------|--------|
|
||||
| `structure` | 矩形块 + 标签(零块灰色) |
|
||||
| `svd` | \(U\Sigma V^{\top}\) 块布局 + 秩分隔 |
|
||||
| `qr` | 瘦/胖 QR 示意 |
|
||||
| `ge` | 消元后上三角高亮 |
|
||||
| `eig` | \(A=PDP^{-1}\) 或谱列表 + 对角 |
|
||||
| `heatmap` | 单元填色(实数蓝红;复数幅值) |
|
||||
|
||||
主题:`theme=light|dark|bw`(与 quantum Q8 令牌对齐;默认 `light`)。
|
||||
|
||||
---
|
||||
|
||||
## 7. L1 / 插件 / CLI 约定
|
||||
|
||||
1. **`ext/linalg/**` 禁止 `host_*`**;只调 `plugin.*` 注册名(如 `linalg_simplify`)。
|
||||
2. **中英分文件**,CATALOG 双 id:`linalg` / `线性代数`。
|
||||
3. **`marqdo ext add linalg`**:与 web/agent/quantum 相同——优先 Release 预编译 native zip。
|
||||
4. **金样**:离线、确定性;SVG 断言含关键子串或稳定 hash 前缀。
|
||||
5. **依赖**:插件内自研稠密核(或慎重引入单一 crate,如 `nalgebra`——**实现期再议**;设计默认「可自研小维 + 可选 crate」)。
|
||||
|
||||
---
|
||||
|
||||
## 8. 分期(摘要;细节见路线图)
|
||||
|
||||
| 阶段 | 交付 |
|
||||
|------|------|
|
||||
| **L0** | CATALOG + ping + L1 `ensure_plugin` |
|
||||
| **L1** | `matrix.symbol` / dense 构造 / `mul`·`T`·`inv` 树 + `simplify` R1–R5 + `latex`/`show` |
|
||||
| **L2** | `explicit` / 小阵运算 / `solve` / `det`·`trace` 数值 |
|
||||
| **L3** | 分块 + `collapse`;Kronecker 惰性 |
|
||||
| **L4** | `factorize` LU/QR/SVD/eig + 结构 SVG |
|
||||
| **L5** | heatmap/hinton;examples + public 文档 + skill 摘要 |
|
||||
| **L6+** | 矩阵微积分 / 更大 BLAS(仅当用户明确要求);复数全路径算子 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 验收标准(设计级)
|
||||
|
||||
1. 符号式 `(AB)^\top` 经 `simplify` 得 `B^\top A^\top`,**不**产生稠密数据。
|
||||
2. 不相容形状在符号 `mul` 即失败。
|
||||
3. `$$` 数值阵 → `from_formula` → `factorize kind=eig` → view 含 SVG 或 latex。
|
||||
4. Kronecker 默认不 expand;显式 `expand` 受维数护栏。
|
||||
5. 中英 L1 金样各至少一条;`ext add linalg` 路径文档化。
|
||||
6. 与 `ext/quantum` 无作者面符号冲突。
|
||||
|
||||
---
|
||||
|
||||
## 10. 风险与开放问题
|
||||
|
||||
| 项 | 备注 |
|
||||
|----|------|
|
||||
| MatExpr 序列化 | 金样 / write:倾向可打印 S-expr 或稳定 latex+shape,避免不透明指针跨进程 |
|
||||
| 与标量 `formula` 混运算 | v1:标量只作 `c*A` 系数;`det` 结果若符号则另型或降为 `formula` 文本 |
|
||||
| nalgebra 等依赖 | 实现 L2 时评估二进制体积与 ABI 体积 |
|
||||
| record_math vs plot | 若仅 SVG/KaTeX 字符串,可先复用 plot/writeback |
|
||||
|
||||
---
|
||||
|
||||
## 11. 一句话(收束)
|
||||
|
||||
**`ext/linalg` 让线性代数公式保持可优化的表达式,用规则与结构图服务文档阅读,用受控稠密核服务验算——公式优先,数值可选,展示分层。**
|
||||
@@ -210,7 +210,7 @@
|
||||
- >6 qubit 稠密 ρ 的谱 / Hinton(请用态向量 API)
|
||||
- Matplotlib / WebGL / 交互拖拽
|
||||
- 量子线性系统算法(HHL)、QSVT 电路构造
|
||||
- 把线性代数并入 `lib/math`
|
||||
- 把线性代数并入 `lib/math`(经典公式优先的 LA 见规划 [ext-linalg.md](ext-linalg.md),作者面与 quantum 分离)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
# 解决 1:路由与 `/admin` 前缀可让出
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §1](../../research/ext-web-customization-limits.md#1-路由与路径被框架强占) |
|
||||
| 优先级 | **P0** · 波次 **C0** |
|
||||
| 触点 | `plugins/web/src/lib.rs`(`normalize_route_path`、`web_app_new`、redirect)· `plugins/web/src/http.rs`(admin 路由挂载、login redirect)· `ext/web/web.mq.md` / `网页.mq.md` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 关闭内置后台后,**整段前缀可被站点路由占用**(含自研 `/admin`)。
|
||||
2. 开启内置后台时,前缀**可配置**(默认仍 `/admin`),登录成功/登出落地页可配置。
|
||||
3. `app.route` / `app.redirect` 只禁止**当前生效**的框架保留段,不再永久霸占 `/admin`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
```markdown
|
||||
*应用 = > web.app page=`首页` db=`库` admin=False*
|
||||
|
||||
# 或:仍用内置 CRUD,但挂到旁路前缀 + 自定义回跳
|
||||
*应用 = > web.app page=`首页` db=`库` admin=True*
|
||||
*应用 = > `应用`.auth users=`用户表` admin_prefix="/desk" login_redirect="/desk" logout_redirect="/desk/login"*
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 含义 |
|
||||
|------|------|------|
|
||||
| `admin` / `后台` | `False` | `False`:**不注册**任何内置 admin HTTP 路由 |
|
||||
| `admin_prefix` / `后台前缀` | `"/admin"` | 内置 CRUD + 登录页挂载根;仅 `admin=True` 时生效 |
|
||||
| `login_redirect` / `登录回跳` | `{admin_prefix}` | 登录成功 303 目标 |
|
||||
| `logout_redirect` / `登出回跳` | `{admin_prefix}/login` | 登出后目标 |
|
||||
|
||||
中文别名与英文一一对应,写进 `网页.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| `normalize_route_path(app)` | reserved 列表改为:`/_form`、`/_part`、`/static` + **当前** `admin_prefix`(仅当 `admin=True`) |
|
||||
| `listen` 路由表 | `admin=False` → **不** `.route("/admin…")`;为真则用 `admin_prefix` 拼路径 |
|
||||
| `admin_login_post` / `admin_logout` | 使用配置的 redirect,禁止写死 `"/admin"` |
|
||||
| `web_app_redirect` | 校验目标时用同一套动态 reserved,允许指向已让出的 `/admin` |
|
||||
| disabled 文案路径 | 删除「挂路由但只显示 Admin is disabled」;无路由则 404 或落入站点自定义页 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 缺省参数下:现有 `examples/web-site`、`web-net-site`、`marqdo-blog` 行为不变(仍 `/admin` + 跳 `/admin`)。
|
||||
- 文档明确:`admin=False` 后若仍要登录能力,用 §3 的通用 `auth`/`gate`,不必再依赖内置 admin 壳。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 金样 / 手工 | 期望 |
|
||||
|-------------|------|
|
||||
| `admin=False` + `route path="/admin/news"` | 注册成功;GET 渲染站点页,**不是** Admin is disabled |
|
||||
| `admin_prefix="/desk"` | 内置登录在 `/desk/login`;成功跳 `login_redirect` |
|
||||
| 默认 `admin=True` 无新参数 | 与现网一致 |
|
||||
| `redirect` 到已让出的 `/admin` | 允许 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 已落地
|
||||
|
||||
~~继续用 `/desk` 旁路 + JS 调 `/admin/login`。~~
|
||||
|
||||
**C0 已落地(2026-09):** `admin=False` 可直接 `route path="/admin/…"`;或 `admin=True` + `admin_prefix="/desk"` + `login_redirect` / `logout_redirect`。见金样 `tests/ext/web-c0-admin-prefix.mq.md`。
|
||||
@@ -0,0 +1,72 @@
|
||||
# 解决 2:`SHELL_CSS` 可关 / 可分层
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §2](../../research/ext-web-customization-limits.md#2-内置-shell_css-难以彻底覆盖) |
|
||||
| 优先级 | **P1** · 波次 **C2** |
|
||||
| 触点 | `plugins/web/src/render.rs`(`SHELL_CSS`、`<style>` 拼接)· page/app 元数据 · `ext/web` 样式装配 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 站点主题可选择:**不要**框架栅格/卡片默认,或只要 reset 级变量。
|
||||
2. 壳 CSS 与主题 CSS 的级联顺序**可声明、可文档化**。
|
||||
3. 默认仍注入完整壳(兼容旧站);新主题显式 `shell_css=off` 即可干净起步。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
```markdown
|
||||
*应用 = > web.app page=`首页` … shell_css="minimal"*
|
||||
# 或页面级覆盖
|
||||
*页 = > `页`.meta …* # 或 page 选项 shell_css=
|
||||
```
|
||||
|
||||
| 值 | 行为 |
|
||||
|----|------|
|
||||
| `full`(默认) | 现网 `SHELL_CSS` 全文 |
|
||||
| `minimal` | 仅 `:root` 变量 + `body` margin/字体;**不含** `has-sidebar` 双列栅格与卡片表单皮肤 |
|
||||
| `off` / `none` | 不注入框架壳样式;只输出站点 `style` / 外链 CSS |
|
||||
|
||||
级联顺序锁定为文档约定:
|
||||
|
||||
1. (可选)框架 `SHELL_CSS`
|
||||
2. 站点全局 style 表 / `site.css`
|
||||
3. 页面级 style
|
||||
|
||||
禁止再出现「主题写在 extra,却被同特异性壳规则在小屏打穿且无媒体查询」而无开关可关的情况。
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| 拆分 `SHELL_CSS` | `SHELL_VARS` / `SHELL_LAYOUT` / `SHELL_WIDGETS` 三段;`full`=`all`,`minimal`=vars(+极简 layout) |
|
||||
| `render` 读 `app.shell_css` / `page.shell_css` | 页面覆盖应用 |
|
||||
| 为 `has-sidebar` 布局加基础媒体查询 | 即使 `full`,小屏改为单列(减轻幽灵双列);`minimal`/`off` 不负责响应式 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 默认 `full`:视觉与现网一致。
|
||||
- Tutorial 增加一节「品牌主题请用 `shell_css=minimal|off`」。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| `shell_css=off` + 站点只写单列 grid | 响应里**无** `grid-template-columns:14rem` |
|
||||
| `minimal` | 有 CSS 变量;无 `.content.cards article` 边框默认(或等价皮肤段) |
|
||||
| 默认示例站 | HTML 仍含完整壳 CSS |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 已落地
|
||||
|
||||
**C2 已落地(2026-09):** `shell_css=full|minimal|off`;页面/应用可设;`full` 含 `@media (max-width:720px)` 单列。金样 `tests/ext/web-c2-shell-layout.mq.md`。
|
||||
@@ -0,0 +1,72 @@
|
||||
# 解决 3:鉴权 / 门禁可配置且行为一致
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §3](../../research/ext-web-customization-limits.md#3-鉴权--门禁模型偏固定) |
|
||||
| 优先级 | **P0** · 波次 **C1**(依赖 [01](01-routes-and-admin-prefix.md) 的 prefix) |
|
||||
| 触点 | `plugins/web/src/http.rs`(`rbac_middleware`、`path_matches`、login 表单)· `lib.rs`(`web_app_auth` / `web_app_gate`)· `ext/web` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. **未登录策略一致**:可配置 `redirect`(303 登录)或 `forbid`(403),对任意 gate 路径生效,不再「仅 `/admin*` 会跳登录」。
|
||||
2. **匹配语义清晰**:支持精确路径、前缀、以及排除列表;`/desk` 默认**不**误伤 `/desk/login`。
|
||||
3. 默认 admin gate 使用 **路径段边界**(`/admin` 与 `/admin/…`),不匹配 `/admin-publish`。
|
||||
4. 登录 URL、表单 `action`、成功/失败回跳均可配置(与 C0 对齐)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.auth users=`用户表` login_path="/desk/login" login_redirect="/desk"*
|
||||
*应用 = > `应用`.gate path="/desk" roles="admin" match="prefix" on_deny="redirect" exclude="/desk/login"*
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `login_path` | 登录页 URL(GET 表单 + POST 处理);默认 `{admin_prefix}/login` |
|
||||
| `match` | `exact` \| `prefix`(默认对自定义 gate 建议 `prefix` + `exclude`) |
|
||||
| `on_deny` | `redirect` \| `forbid`;`redirect` 时跳 `login_path`(可带 `?next=`) |
|
||||
| `exclude` | 逗号分隔或表列:匹配前缀时放行的路径 |
|
||||
|
||||
`auth` 注册默认 gate 时:
|
||||
|
||||
- 使用 `{admin_prefix}` + 段边界,**不要** `starts_with("/admin")` 裸前缀。
|
||||
- 自动把 `login_path` 加入放行列表。
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| `path_matches` | 增加 `exact`;`prefix` 要求下一字符为 `/` 或结尾;可选 exclude |
|
||||
| `rbac_middleware` | 按 gate 的 `on_deny` 分支;通用放行 `login_path`,不写死 `/admin/login` |
|
||||
| 登录 HTML | `action={login_path}`;hidden `next` 可选 |
|
||||
| Session/CSRF | 短期仍用框架实现;文档标明字段名;中期再开放 `login_form` 自定义字段映射(非本波次必做) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 未传新字段:行为对齐现网(`/admin*` → redirect 登录;其它自定义 gate → 403)。
|
||||
- 新增金样:`/desk` gate + `/desk/login` 可匿名打开。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| visitor 访问 `/desk`(`on_deny=redirect`) | 303 → `/desk/login`,不是 403 |
|
||||
| visitor 访问 `/desk/login`(exclude) | 200 登录页 |
|
||||
| `/admin-publish` 无显式 gate | **不**被默认 admin gate 拦住 |
|
||||
| 旧站仅 `app.auth` | 仍保护 `/admin*` |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 已落地
|
||||
|
||||
**C1 已落地(2026-09):** `auth` 默认段边界 prefix + `on_deny=redirect` + 排除 `login_path`;自定义 `gate` 可设 `match` / `on_deny` / `exclude`。金样 `tests/ext/web-c1-gates.mq.md`;单元测试 `http::gate_tests`。
|
||||
@@ -0,0 +1,69 @@
|
||||
# 解决 4:样式表作者体验
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §4](../../research/ext-web-customization-limits.md#4-样式作者体验受限) |
|
||||
| 优先级 | **P2** · 波次 **C3** |
|
||||
| 触点 | 表单元格表达式(T5)· `ext/web` style 装配 · 教程 / Skill · 可选校验 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 含 `/`、`,`、括号的 CSS 值**不易被静默算坏**。
|
||||
2. 复杂选择器 / `@keyframes` / 多层 media 有**官方推荐写法**(表内 vs 外链 vs raw 块)。
|
||||
3. 与壳 CSS 的层叠关系在文档中一句话写清(并链到 [02](02-shell-css.md))。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API / 约定(草案)
|
||||
|
||||
### 2.1 立即固化的文档约定(可不改代码)
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| 含 `/` 的值必须引号 | `"1 / 5"`、`"image/png"`(已有;Skill/教程加醒目反例) |
|
||||
| 复杂皮肤优先外链 | `static/theme.css` + `page.head` / `app.icons` 同类资源表 |
|
||||
| `@keyframes` / 长 media | 放外链 CSS,不塞进 GFM 单元格 |
|
||||
| 调试 | `shell_css=off` 后只看主题文件,避免同页双源 |
|
||||
|
||||
### 2.2 产品增强(C3)
|
||||
|
||||
| 能力 | 说明 |
|
||||
|------|------|
|
||||
| `style` 装配时对可疑单元格告警 | 未加引号且含 `/` → listen/assemble 警告或硬错误(可开关) |
|
||||
| 可选 `##` raw CSS 块绑定 | 例如页面附属 ````css` 具名块,**不经**表表达式求值 |
|
||||
| 文档示例 | `min-width` + `max-width` 外链表;引用 [table-cell-expressions.md](../table-cell-expressions.md) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件 / 核心改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| web style 编译 | 可选 `strict_css_cells=True`:裸 `/` 报错 |
|
||||
| (可选)`web_page_css_raw` | 把文本 CSS 追加到页面,跳过 T5 |
|
||||
| Skill `marqdo` / tutorial 14 | 增加「样式踩坑」小节 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 默认不硬错误(避免打碎旧表);新 scaffold 默认 `strict_css_cells` 或文档强制引号。
|
||||
- 不把完整 CSS 语法塞进表格方言——复杂内容走文件。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| 文档反例 `grid-column` 裸 `1 / 5` | 在 strict 模式下失败或警告 |
|
||||
| 外链 `theme.css` + `shell_css=off` | 无壳栅格串扰 |
|
||||
| 现有 web 示例 | 默认模式仍绿 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 workaround
|
||||
|
||||
全部敏感值加引号;响应式与 keyframes 只写在 `static/*.css`;小屏问题优先关壳([02](02-shell-css.md))再调主题。
|
||||
@@ -0,0 +1,85 @@
|
||||
# 解决 5:页面壳与插槽松绑
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §5](../../research/ext-web-customization-limits.md#5-页面壳与插槽约定僵硬) |
|
||||
| 优先级 | **P1** · 波次 **C2/C4** |
|
||||
| 触点 | `plugins/web/src/render.rs`(body class、四区 HTML)· page 槽位装配 · nav 组件表 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 作者可选**非侧栏栅格**布局,而不必用 CSS 硬怼掉 `has-sidebar`。
|
||||
2. 侧栏存在 ≠ 强制桌面双列;提供 stacked / bare 等预设。
|
||||
3. 为「条件导航」留扩展点(先文档 + 简单 hook,完整运行时条件可后置)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
```markdown
|
||||
*首页 = > web.page … layout="stacked"*
|
||||
*应用 = > web.app page=`首页` … layout="bare"*
|
||||
```
|
||||
|
||||
| `layout` | DOM / class | 说明 |
|
||||
|----------|-------------|------|
|
||||
| `sidebar`(默认,有 side 槽时) | `body.has-sidebar` | 现网行为 |
|
||||
| `stacked` | `body.layout-stacked`;side 在 main 上或折叠区 | 单列流式,适合杂志/营销 |
|
||||
| `bare` | 无 top/side/foot 强制栅格;只渲染 `main`(+ 显式槽) | 登录页、落地页 |
|
||||
| `rail`(可选) | 保留站点已有 `has-rail` 约定并文档化 | 避免「只有首页有 class」 |
|
||||
|
||||
规则:**有 side 组件但 `layout=stacked|bare` 时,不自动加 `has-sidebar`。**
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| `render` 读 `page.layout` / `app.layout` | 决定 body class 与 HTML 骨架 |
|
||||
| `SHELL_LAYOUT`(见 [02](02-shell-css.md)) | 为 `layout-stacked` / `layout-bare` 提供最小样式;`shell_css=off` 时不注入 |
|
||||
| Nav 表 | 短期保持声明式;文档说明「条件项用两套 nav 组件 + 媒体查询隐藏」 |
|
||||
| 中期 hook(非阻断) | `navigate` 已有字段可扩展 `when`/`media` 列(单独 RFC) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 未设 `layout`:有 side → 与现网 `has-sidebar` 相同。
|
||||
- 金样增加 `layout=bare` 登录页(可与 C0 自研 `/desk/login` 共用)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| 有 side + `layout=stacked` | body **无** `has-sidebar`;无 `14rem` 双列(在 full 壳下用 stacked 规则) |
|
||||
| `layout=bare` | 输出不含 `<aside class="side">`(或 empty 不占栅格) |
|
||||
| 默认站 | 不变 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 已落地
|
||||
|
||||
**C2 已落地(2026-09):** `layout=sidebar|stacked|bare|rail`;有 side 时 `stacked`/`bare` 不再强制 `has-sidebar`。金样 `web-c2-shell-layout`。
|
||||
|
||||
**C4 已落地(2026-09):** 导航 / 侧栏 / 页脚绑定表可选列:
|
||||
|
||||
| 列 | 说明 |
|
||||
|----|------|
|
||||
| `媒体` / `media` | CSS media;不匹配时 `display:none`(生成 `nav-mq-*` + `@media not …`) |
|
||||
| `当` / `when` | `hide` 省略;`auth` / `guest` 按登录态过滤;空 = 总是显示 |
|
||||
|
||||
```markdown
|
||||
| 属性 | 值 | 样式 | 媒体 | 当 |
|
||||
|------|-----|------|------|-----|
|
||||
| Home | / | | | |
|
||||
| Menu | /m | | (max-width: 720px) | |
|
||||
| Admin | /admin | | | auth |
|
||||
| Login | /login | | | guest |
|
||||
```
|
||||
|
||||
Listen 渲染时写入 `_logged_in` / `_nav_user`(来自 session)。离线 `page.render` 可自行 `table.put` `_logged_in`。金样 `web-c4-nav-when`。
|
||||
@@ -0,0 +1,67 @@
|
||||
# 解决 6:后台 CRUD 与表单能力边界
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §6](../../research/ext-web-customization-limits.md#6-后台-crud-与表单能力边界) |
|
||||
| 优先级 | **P3** · 随 C0 文档化;增强可选 |
|
||||
| 触点 | `plugins/web/src/http.rs` / `form.rs`(内置 admin)· 站点自研页 + `db.*` · `/_form` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. **产品叙事澄清**:内置 `/admin`(或可配置前缀)= 通用表浏览器,**不是** CMS;关则彻底让路(见 [01](01-routes-and-admin-prefix.md))。
|
||||
2. 自研后台的推荐路径写清楚:`page` + `form` + `db` + gate,而不是改插件壳。
|
||||
3. 对「链接前缀 / new / edit」给出约定或薄辅助,减少前端状态机拼装。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API / 文档(草案)
|
||||
|
||||
### 2.1 推荐架构(文档为主)
|
||||
|
||||
| 需求 | 做法 |
|
||||
|------|------|
|
||||
| 产品级编辑器、专栏联动 | 自研 `# page` + 组件;写库用 `db.insert`/`update`;鉴权用 `gate` |
|
||||
| 简单表维护 | 开 `admin=True`(可换前缀) |
|
||||
| 关内置仍要 CRUD | 自研列表/编辑页;**不要**依赖 disabled 壳 |
|
||||
|
||||
### 2.2 可选薄增强(非 CMS)
|
||||
|
||||
| 能力 | 说明 |
|
||||
|------|------|
|
||||
| `form` 支持 `mode=new\|edit` 查询参数约定 | 文档 + 示例;必要时 `web.form` 读 `id`/`new` |
|
||||
| `list` 组件 `link_prefix` | 已有则补示例;缺失则加一列「详情路径模板」 |
|
||||
| Markdown 字段 | 继续「存库 + 前台渲染」;分栏编辑器保持外挂 JS(明确不做进 ABI) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 优先级 |
|
||||
|------|--------|
|
||||
| C0:disabled 不占路径 | 必需(属 [01](01-routes-and-admin-prefix.md)) |
|
||||
| 示例 `examples/web-custom-desk/` | 展示自研列表/编辑,零内置 admin |
|
||||
| form 查询参数助手 | 可选 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 不扩展内置 admin 成 CMS(避免范围爆炸)。
|
||||
- Tutorial 增加「何时用内置 admin / 何时自研」。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| 文档 + 示例 desk | 无 `/admin` 也能完成一文增删改 |
|
||||
| 内置 admin 金样 | 仍绿 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 workaround
|
||||
|
||||
自研 `/desk` + 调用 `/_form` 或直接 DB API;复杂编辑器继续外挂 JS。
|
||||
@@ -0,0 +1,71 @@
|
||||
# 解决 7:静态资源与脚本生命周期
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §7](../../research/ext-web-customization-limits.md#7-静态资源与脚本生命周期) |
|
||||
| 优先级 | **P2** · 波次 **C3** |
|
||||
| 触点 | `web_page_head` / `web_head` · `render.rs` head 输出 · static 挂载 · [web-assets-and-images.md](../web-assets-and-images.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 默认脚本加载方式**不假设**作者手写 IIFE 抢在 DOM 前执行成功;提供 `defer` / `module` 一等约定。
|
||||
2. 静态资源变更可发现:文档化 `?v=`,并提供可选自动指纹或 listen 时 mtime 查询参数。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
Head 资源表扩展列(向后兼容):
|
||||
|
||||
| 列 | 说明 |
|
||||
|----|------|
|
||||
| `rel` / `关系` | 已有;`script` / `module` |
|
||||
| `defer` / `推迟` | `真` → `<script defer>`(**建议默认对 script 为真**) |
|
||||
| `async` / `异步` | 可选 |
|
||||
| `version` / `版本` | 非空则自动追加 `?v=` |
|
||||
|
||||
```markdown
|
||||
`头` =
|
||||
| 关系 | 地址 | 推迟 | 版本 |
|
||||
|------|------|------|------|
|
||||
| script | /static/theme.js | 真 | 2026-09-04 |
|
||||
| module | /static/desk.js | 真 | 3 |
|
||||
```
|
||||
|
||||
全局:`app.asset_version="2026-09-04"` 为所有 static 链接统一 bump(可选)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| head 渲染 | 尊重 defer/async;`module` → `type="module"`(已有则核对) |
|
||||
| 默认 | 新建 scaffold 的 script 行带 `defer` |
|
||||
| (可选)`asset_version` | listen 时重写 head / 页面内 static URL |
|
||||
| 文档 | 「禁止在同步 head 脚本里直接 `getElementById` 主节点;用 defer 或 `DOMContentLoaded`」 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 旧表无 `defer` 列:保持现网同步行为(或仅对 scaffold/新文档默认 defer,避免静默改变旧站时序)。
|
||||
- 更安全:缺省仍同步;**Skill 与 scaffold 默认写 defer=真**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| defer 脚本读 DOM | 登录跳转逻辑在 DOM 就绪后执行 |
|
||||
| `version` 列 | HTML 中出现 `theme.js?v=…` |
|
||||
| 旧示例无新列 | 仍通过 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 workaround
|
||||
|
||||
脚本改 `type=module` 或放 body 末;手动 `?v=` bump;登录逻辑用 `DOMContentLoaded`。
|
||||
@@ -0,0 +1,68 @@
|
||||
# 解决 8:扩展与部署耦合
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §8](../../research/ext-web-customization-limits.md#8-扩展与部署耦合) |
|
||||
| 优先级 | **P3** · 文档 + 发布流程 |
|
||||
| 触点 | `marqdo ext add web` · ABI 版本 · Docker/发布说明 · [ext-cli.md](../ext-cli.md) · [marqdo-release](../../../.cursor/skills/marqdo-release/SKILL.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 站点作者**不必 fork 插件**才能完成 P0/P1 定制(把能力收进官方参数,见 01–05)。
|
||||
2. 版本耦合可预期:changelog / 扩展清单标明「web 插件需 ≥ x.y.z」。
|
||||
3. 升级路径文档化:二进制、`.marqdo-ext`、Docker 镜像三者对齐检查。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 / 运维约定(草案)
|
||||
|
||||
| 约定 | 说明 |
|
||||
|------|------|
|
||||
| 定制优先走 `.mq.md` 开关 | `admin_prefix`、`shell_css`、`layout`、`gate`… 进官方 API 后,禁止文档再教「改 plugins/web」 |
|
||||
| 兼容性矩阵 | 在 [web-net-capabilities.md](../web-net-capabilities.md) 或本目录维护「Marqdo ↔ libweb 最低版本」表 |
|
||||
| `marqdo ext add web` | 安装后打印当前插件路径与版本;与 CLI 版本不符时警告 |
|
||||
| Docker | 示例 Dockerfile 注释:升级需同时换 `marqdo` 与 `ext add` 产物 |
|
||||
| 样式引号等行为变更 | 写入 CHANGELOG **Breaking / migration** 小节(如 0.3.2 T5) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 工程改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| 插件/Crate 版本可见 | `web_listen` 或 `ext list` 显示 web ABI/包版本 |
|
||||
| CI | 金样使用仓库内 `plugins/web`;发布技能检查 VSIX/CLI/插件三件套 |
|
||||
| 研究→设计→路线图 | C0–C4 进 [ext-web roadmap](../../roadmap/ext-web.md),避免只活在私有 fork |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 不承诺插件源码级稳定 API;承诺 **`.mq.md` 作者 API** 在小版本尽量兼容,破坏性变更进 CHANGELOG。
|
||||
- Fork 插件仅作为「官方尚未交付」的临时手段,并在 issue/路线图留归还项。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| 升级说明文档 | 运维按清单升级后 web 金样通过 |
|
||||
| C0–C2 落地 | 自研后台场景**无需**改 `plugins/web` 源码 |
|
||||
| `ext list` / 文档 | 能核对版本 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 预编译路径(进行中)
|
||||
|
||||
**目标:** 用户 `marqdo ext add web` **不必**本机 Rust。
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| Release `marqdo-*-native-*.zip` | Windows / Linux 预编译 `web`/`agent`/`quantum` |
|
||||
| Windows portable zip | 内含 `ext/` + `ext/native/*.dll` |
|
||||
| `ext add` 下载回退 | 本地无 `.so`/`.dll` 时从 GitHub Release 拉取(`MARQDO_EXT_NO_DOWNLOAD=1` 可关) |
|
||||
|
||||
仍保留开发者 `cargo build -p marqdo_plugin_*` 路径。详见 [ext-cli.md](../ext-cli.md)。
|
||||
@@ -0,0 +1,50 @@
|
||||
# `ext/web` 定制修复:解决文档索引
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **C0–C4 done** |
|
||||
| 日期 | 2026-09-04 |
|
||||
| 问题盘点 | [../../research/ext-web-customization-limits.md](../../research/ext-web-customization-limits.md) |
|
||||
| 相关 | [../ext-web.md](../ext-web.md) · [../ext-web-net.md](../ext-web-net.md) · [../../roadmap/ext-web.md](../../roadmap/ext-web.md) |
|
||||
|
||||
对应研究文 §1–§8,每项一份解决文档:**目标 → 作者 API → 插件改动点 → 兼容策略 → 验收**。
|
||||
|
||||
实现时优先 **不破坏现有金样**(`tests/ext/web-*`、`examples/web-*`);新能力用显式 opt-in 参数打开。
|
||||
|
||||
---
|
||||
|
||||
## 文档一览
|
||||
|
||||
| # | 主题 | 文档 | 建议优先级 |
|
||||
|---|------|------|------------|
|
||||
| 1 | 路由与 `/admin` 前缀可让出 | [01-routes-and-admin-prefix.md](01-routes-and-admin-prefix.md) | P0 |
|
||||
| 2 | `SHELL_CSS` 可关 / 可层 | [02-shell-css.md](02-shell-css.md) | P1 |
|
||||
| 3 | 鉴权门禁可配置且行为一致 | [03-auth-gates.md](03-auth-gates.md) | P0 |
|
||||
| 4 | 样式表作者体验 | [04-stylesheet-authoring.md](04-stylesheet-authoring.md) | P2 |
|
||||
| 5 | 页面壳与插槽松绑 | [05-page-shell-slots.md](05-page-shell-slots.md) | P1 |
|
||||
| 6 | 后台 CRUD / 表单边界 | [06-admin-crud-forms.md](06-admin-crud-forms.md) | P3 |
|
||||
| 7 | 静态资源与脚本生命周期 | [07-assets-script-lifecycle.md](07-assets-script-lifecycle.md) | P2 |
|
||||
| 8 | 扩展与部署耦合 | [08-ext-deploy-coupling.md](08-ext-deploy-coupling.md) | P3 |
|
||||
|
||||
---
|
||||
|
||||
## 波次建议(实现用)
|
||||
|
||||
| 波次 | 内容 | 依赖 |
|
||||
|------|------|------|
|
||||
| **C0** | 可配置 `admin_prefix`;`admin=False` 时不挂内置路由;`login_redirect` / `logout_redirect` | — |
|
||||
| **C1** | gate:统一未登录策略;精确/前缀匹配;登录页自动放行;默认 gate 不再误伤 `/admin-*` | C0 |
|
||||
| **C2** | `shell_css=off\|minimal\|full`;主题在壳前或隔离层;可选 `layout=bare` | — |
|
||||
| **C3** | 样式:校验警告 / `strict`;`page.css` raw;脚本 `defer`/`async`/`version` + `asset_version` | **done** |
|
||||
| **C4** | 壳:`layout` 预设(C2);条件导航 `when` / `media` | **done** |
|
||||
|
||||
路线图入口可在 [ext-web.md](../../roadmap/ext-web.md) 增补「定制波次 C0–C4」行,落地后再改状态。
|
||||
|
||||
---
|
||||
|
||||
## 产品原则(解法共同约束)
|
||||
|
||||
1. **`.mq.md` 仍是真相源** — 能声明的不进隐藏默认;新开关写在 `app` / `page` / `listen` 参数表。
|
||||
2. **内置 admin 是可选产品**,不是不可替换的内核路由命名空间。
|
||||
3. **默认行为保持兼容** — 现有 tutorial / 示例零改动仍能跑;新站显式打开定制。
|
||||
4. **禁止**为单站需求永久硬编码第二套旁路(如永远推荐 `/desk` + JS fetch 登录)。
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · W0–W7 + P3 完结**(SQLite/Postgres 作者面:页面装配 / db CRUD+`where` / form / 嵌入主区 / `app.route` / 路由 `/_part` / admin UI / RBAC / 上传相册 / SEO·RSS·sitemap;Postgres 等见 §9) |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 相关 | [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) |
|
||||
| 状态 | **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) |
|
||||
| 安装(目标) | `marqdo ext add web`(中英:`web` / `网页`) |
|
||||
| 本文目的 | 锁定**作者面**与**类 API**;指导实现 |
|
||||
|
||||
|
||||
@@ -268,7 +268,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
| **首列表头 `@` / `行` / `row`** | **行向** `List` of `Map`(标记列不进入字段;任意数据行数) |
|
||||
| 重复表头 | 诊断错误 |
|
||||
|
||||
**数据单元格是表达式**(与调用实参值语法相同:裸词、数字、`` `var` ``、算术、引号串;URL / `gpt-4o-mini` 等按路径·连字符折叠为文本)。表头仍是键名文本。细则:[table-cell-expressions.md](table-cell-expressions.md)。
|
||||
**数据单元格是表达式**(与调用实参值语法相同:裸词、数字、`` `var` ``、算术、引号串;URL / `gpt-4o-mini` 等按路径·连字符折叠为文本;含 `/` 的 CSS 比率等请用引号 `"1/5"`,裸 `1/5` 为除法)。表头仍是键名文本。细则:[table-cell-expressions.md](table-cell-expressions.md)。
|
||||
|
||||
```markdown
|
||||
*`k` = secret *
|
||||
|
||||
@@ -0,0 +1,29 @@
|
||||
# `lib/csv` — 逗号表(Mid M4)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M4)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-text-mid.md](stdlib-text-mid.md) · [stdlib-mid.md](stdlib-mid.md) |
|
||||
| 导入 | `lib/csv.mq.md` · `lib/逗号表.mq.md` |
|
||||
| Host | `host_csv_*`(RFC4180 最小集,无第三方 crate) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `parse` | `解析` | `text` | **list of maps**:首行为表头 |
|
||||
| `stringify` | `序列化` | `rows` | CSV 文本(表头 = 首行 map 的键顺序) |
|
||||
|
||||
## 2. 方言(v1)
|
||||
|
||||
- 分隔符 `,`;引号 `"`;`""` 转义。
|
||||
- 换行 `\n` / `\r\n`;忽略末尾空行。
|
||||
- 字段内可含逗号与换行(须加引号)。
|
||||
- **不**支持自定义分隔符 / 无表头模式(可后续加)。
|
||||
|
||||
## 3. 刻意不做
|
||||
|
||||
流式大文件、类型推断、Excel 方言。
|
||||
@@ -0,0 +1,32 @@
|
||||
# `lib/encoding` — 编解码(Mid M1)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M1)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [stdlib-re.md](stdlib-re.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 导入 | `lib/encoding.mq.md` · `lib/编码.mq.md` |
|
||||
| Host | `host_encoding_*`(无第三方 crate:标准 Base64 / hex) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `base64_encode` | `基64编码` | `text` | 文本(UTF-8 字节 → 标准 Base64,含 `=` 填充) |
|
||||
| `base64_decode` | `基64解码` | `text` | 文本(解码后须为合法 UTF-8) |
|
||||
| `hex_encode` | `十六进制编码` | `text` | 小写 hex |
|
||||
| `hex_decode` | `十六进制解码` | `text` | 文本(偶数字节;合法 UTF-8) |
|
||||
|
||||
## 2. 与 `net.url_encode` 的边界
|
||||
|
||||
| 能力 | 归属 |
|
||||
|------|------|
|
||||
| `application/x-www-form-urlencoded` 风格 | `net.url_encode` |
|
||||
| Base64 / hex | **本库** |
|
||||
| 百分号编解码通用版 | 可日后加 `encoding.percent_*`;本波不做 |
|
||||
|
||||
## 3. 刻意不做(v1)
|
||||
|
||||
URL-safe Base64 变体开关、忽略空白的宽松解码、二进制 `bytes` 类型(仍经 UTF-8 文本往返)。
|
||||
@@ -0,0 +1,24 @@
|
||||
# `lib/fs` 加厚 — 复制 / 移动 / 临时文件(Mid M2)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M2)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-path.md](stdlib-path.md) · [stdlib-mid.md](stdlib-mid.md) |
|
||||
| 边界 | **文本与普通文件**;不引入 `bytes` 类型(`read_bytes` 延后) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 新增 API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `copy_file` | `复制文件` | `src`, `dest` | `None`(覆盖已存在的目标文件) |
|
||||
| `move` | `移动` | `src`, `dest` | `None`(rename;跨设备失败则报错) |
|
||||
| `make_temp` | `建临时` | 可选 `prefix` | 相对 `cwd`/`fs_root` 的新空文件路径文本 |
|
||||
|
||||
均走现有 `resolve_path` 沙箱;写操作受 `fs_write` 策略约束。
|
||||
|
||||
## 2. 刻意不做
|
||||
|
||||
目录树 `copy_tree`、原子替换、`read_bytes`、权限 chmod。
|
||||
@@ -0,0 +1,26 @@
|
||||
# `lib/hash` — 摘要与 HMAC(Mid M3)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M3)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [stdlib-secrets.md](stdlib-secrets.md) |
|
||||
| 导入 | `lib/hash.mq.md` · `lib/哈希.mq.md` |
|
||||
| Host | `host_hash_*`(`sha2` / `sha1` / `md-5` / `hmac`) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `sha256` | `哈希256` | `text` | 小写 hex |
|
||||
| `sha1` | `哈希1` | `text` | 小写 hex |
|
||||
| `md5` | `md5` | `text` | 小写 hex |
|
||||
| `hmac_sha256` | `密钥哈希256` | `key`, `text` | 小写 hex |
|
||||
|
||||
输入按 **UTF-8 字节**摘要。文档标明:用于完整性标识 / 缓存键,**不是**密码存储(无 Argon2/bcrypt)。
|
||||
|
||||
## 2. 刻意不做
|
||||
|
||||
密码哈希、流式大文件哈希 API、非 UTF-8 二进制类型。
|
||||
@@ -0,0 +1,36 @@
|
||||
# `lib/table` 集合加厚 + `lib/cli`(Mid M5)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M5)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 集合 | 加厚现有 `lib/table` / `lib/表`(不另开 `listx`) |
|
||||
| CLI | `lib/cli.mq.md` / `lib/命令行.mq.md` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 集合新增
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `sort` | `排序` | `list` | 升序列表(int/num/text 优先;其它按显示文本) |
|
||||
| `sort_by` | `按键排序` | `list`, `key` | 对 **map 列表**按键值排序 |
|
||||
| `unique` | `去重` | `list` | 保序去重 |
|
||||
| `chunk` | `分块` | `list`, `size` | 列表的列表 |
|
||||
| `zip` | `拉链` | `a`, `b` | `[[a0,b0], …]`(取较短长度) |
|
||||
| `flatten` | `展平` | `list` | 一层展平 |
|
||||
|
||||
`reverse` 已有。
|
||||
|
||||
## 2. CLI
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `parse` | `解析` | 可选 `args` | map:`--k v` / `--k=v` → 文本;裸 `--flag` → `True`;位置参 → 键 `_` 列表 |
|
||||
|
||||
`args` 缺省时用 `sys.args`(经宿主 `argv`)。
|
||||
|
||||
## 3. 刻意不做
|
||||
|
||||
稳定自定义比较器、惰性迭代器、完整 argparse 互斥组。
|
||||
@@ -0,0 +1,30 @@
|
||||
# `lib/log` + `lib/uuid`(Mid M6)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 日志 `lib/log` / `lib/日志`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `set_level` | `设级别` | `level`(`debug`/`info`/`warn`/`error`) | `None` |
|
||||
| `debug` / `info` / `warn` / `error` | `调试` / `信息` / `警告` / `错误` | `text` | 达级别则 `print` 一行 `LEVEL message`;否则无输出 |
|
||||
|
||||
默认级别:`info`(隐藏 `debug`)。中文级别别名:`调试`/`信息`/`警告`/`错误`。
|
||||
|
||||
实现:宿主记最小级别;`host_log_line` 返回待打印文本或 `None`;L1 再 `print`(接入现有 stdout / capture)。
|
||||
|
||||
## 2. UUID `lib/uuid` / `lib/标识`
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `v4` | `版本4` | (无) | 标准 8-4-4-4-12 小写 hex(`getrandom`) |
|
||||
|
||||
## 3. 刻意不做
|
||||
|
||||
结构化 JSON 日志、远程 sink、UUID v1/v7、yaml。
|
||||
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| 状态 | **已实现(M1–M4)** |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) · 大学线性代数见规划 [ext-linalg.md](ext-linalg.md) |
|
||||
| 导入 | `lib/math.mq.md`(英)· `lib/数学.mq.md`(中) |
|
||||
| 范围 | **高中数学**(初等函数、导数、圆锥曲线、简单方程);非大学 CAS |
|
||||
|
||||
@@ -92,7 +92,7 @@ $$
|
||||
| 代入求值 | `subs` → `num` 或公式 |
|
||||
| 求解 | 一元一次 / 二次闭式;其它用数值求根并标明 |
|
||||
|
||||
**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、矩阵、复数完备、任意证明。
|
||||
**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、**大学线性代数**(符号矩阵表达式 / 分解 —— 见 [ext-linalg.md](ext-linalg.md))、复数完备、任意证明。数值小矩阵字面量可在 `$$` 中解析为 `formula::Matrix`,但符号 MatExpr 与分解不在 `lib/math`。
|
||||
|
||||
### 3.2 作图(P)
|
||||
|
||||
@@ -210,6 +210,7 @@ Interpreter.plots: Vec<Stringimport math:lib/math.mq.md · lib/数学.mq.md
|
||||
- `$$:name` 模块级具名绑定(已废除)。
|
||||
- 无名 `$$` 自动进运行时。
|
||||
- 大学级数 / 完备积分 / 定理证明。
|
||||
- **大学线性代数扩展**(见 [ext-linalg.md](ext-linalg.md);不在本库做符号 MatExpr)。
|
||||
- 通用隐函数作图引擎。
|
||||
- 3D、交互式图表库。
|
||||
|
||||
|
||||
@@ -0,0 +1,170 @@
|
||||
# 中层标准库(Mid Stdlib)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **M1–M6 已落地** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-abi.md](ext-abi.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 目标 | 在接下来数个发版周期内,把「通用编程」能力沉到 **L0.5 宿主 + L1 `.mq.md`**,减少「凡是稍有能力就必须 ABI 插件」的路径依赖 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 为什么现在做
|
||||
|
||||
现状分层(已落地):
|
||||
|
||||
```text
|
||||
L0 内置 print / len / split / …
|
||||
L0.5 宿主原语 src/host/*(供 L1 包装,作者原则上不直调)
|
||||
L1 官方库 lib/*.mq.md(嵌入二进制 / 可覆盖)
|
||||
ext 官方扩展 .mq.md + 可选 cdylib(web / agent / quantum / linalg)
|
||||
```
|
||||
|
||||
痛点:
|
||||
|
||||
1. **通用语言能力缺口**:`lib/text` 几乎只是 `trim/split/join`;无正则、无编解码、无哈希、无路径代数、无 CSV……日常脚本要么外联 Python,要么新开插件。
|
||||
2. **插件路径过重**:ABI 插件适合**领域热路径**(量子核、公式矩阵、HTTP 服务+SQLite),不适合「再来一个 base64」。每加一个插件都要:crate、Release 资产、`ext add`、CI、WASM 缺口。
|
||||
3. **扩展作者被逼进插件**:`ext/**` 禁止 `host_*`。若 L1 没有正则 / 哈希 / 路径,扩展只能 `plugin.load`,导致「库」与「原生模块」边界模糊。
|
||||
4. **对照成熟语言**:Go 的 `strings` / `regexp` / `encoding/*` / `crypto` / `path/filepath`、Python 的「难写对才进 stdlib」标准——都把**通用原语**留在语言自带层,把**领域产品**留给第三方。Marqdo 的「通用」应对齐前者;`ext/` 对齐后者。
|
||||
|
||||
中层标准库 = **在现有 L1 之上、在官方 ext 之下**,专门补「写通用程序必备、又不该做成插件」的那一档。
|
||||
|
||||
---
|
||||
|
||||
## 2. 分层命名(本波约定)
|
||||
|
||||
| 名称 | 位置 | 用户导入 | 实现形态 |
|
||||
|------|------|----------|----------|
|
||||
| **核心 L1** | 已有 `lib/{fs,sys,time,json,net,math,…}` | 是 | 薄包装 → 已有 `host_*` |
|
||||
| **中层 L1(Mid)** | 新增 / 加厚 `lib/{re,encoding,hash,path,…}` | 是(仍属 `lib/` / `std/`) | **优先**薄 `host_*` + L1;能纯 `.mq.md` 则纯库 |
|
||||
| **官方 ext** | `ext/{web,agent,quantum,linalg,ai}` | 显式 `ext/` | `.mq.md`;**仅**领域热路径允许 ABI 插件 |
|
||||
| **catalog / 用户库** | 发版外收录 | 各自约定 | 应能主要靠 Mid + 核心 L1 写成,**默认无插件** |
|
||||
|
||||
> **不**新开第三棵目录树。中层仍落在 `lib/`,用文档与路线图分期交付,避免 `lib/` vs `lib-mid/` 分裂。
|
||||
|
||||
---
|
||||
|
||||
## 3. 准入 / 不准入(宪法)
|
||||
|
||||
### 3.1 进入中层的条件(须同时满足多数)
|
||||
|
||||
| # | 条件 | 说明 |
|
||||
|---|------|------|
|
||||
| 1 | **跨领域高频** | 脚本、站点、智能体、教学示例都会用到 |
|
||||
| 2 | **难写对或不可移植** | 正则、Unicode、密码学、路径跨平台——纯 Marqdo 成本过高 |
|
||||
| 3 | **解锁「无插件写库」** | 有了它,更多 `ext/` / catalog 可用纯 `.mq.md` |
|
||||
| 4 | **宿主面积极小** | 一个或少数 `host_*` + 稳定 crate;不把巨型框架链进主二进制 |
|
||||
| 5 | **API 可长期冻住** | 宁可窄接口,也不提前做成第二个 Requests |
|
||||
|
||||
参考(外部):
|
||||
|
||||
- Python:[stdlib 准入](https://devguide.python.org/developer-workflow/stdlib/) 与 [Language Summit:stdlib 何用](https://blog.python.org/2023/05/the-python-language-summit-2023-what-is.html)——偏「启动器 / 新手脚本 / 难写对的协议」,而非「万物入 std」。
|
||||
- Go:日常几乎离不开的 `strings`、`regexp`、`encoding/*`、`crypto`、`path/filepath`、`slices`——对标我们的 Mid 候选,而非 `database/sql` 驱动全家桶。
|
||||
- 反面:PEP 594「死电池」——过窄协议、过时格式、与生态脱节的模块不要进 Mid。
|
||||
|
||||
### 3.2 明确不准入(继续走 ext + 可选插件)
|
||||
|
||||
| 领域 | 原因 |
|
||||
|------|------|
|
||||
| HTTP **服务端** / ASGI / 路由框架 | 产品面;已有 `ext/web` |
|
||||
| SQLite / ORM / 管理后台 | 同上 |
|
||||
| LLM / 智能体编排 / OKF | `ext/ai` · `ext/agent` |
|
||||
| 量子线路 / 密度矩阵核 | `ext/quantum` |
|
||||
| 大学线性代数 CAS / 分解可视化 | `ext/linalg`(公式文档面) |
|
||||
| 完整图像 / 音视频 / ML | 体积与依赖爆炸 |
|
||||
| 任意第三方云 SDK | 不属于语言 |
|
||||
|
||||
### 3.3 插件仍保留的边界
|
||||
|
||||
ABI 插件 **不废除**。规则收紧为:
|
||||
|
||||
```text
|
||||
若能力可用「少量 host_* + lib/*.mq.md」表达 → 必须走中层,禁止新开官方插件。
|
||||
若能力是领域数值核 / 长生命周期服务 / 可选重依赖 → 才允许官方插件。
|
||||
```
|
||||
|
||||
`lib/plugin` 继续服务:本地实验、第三方原生、官方领域包。
|
||||
|
||||
---
|
||||
|
||||
## 4. 实现分工(怎么长)
|
||||
|
||||
```text
|
||||
用户 / catalog / 官方 ext(纯 mq 优先)
|
||||
│ import re:lib/re.mq.md
|
||||
▼
|
||||
中层 L1(.mq.md,中英分文件,除 json 类共用外)
|
||||
│ **> host_re_find …**
|
||||
▼
|
||||
L0.5 宿主(Rust:regex / sha2 / …)
|
||||
│
|
||||
▼
|
||||
OS / 算法库(精选 crate,默认 features 最小化)
|
||||
```
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| `ext/**` 仍禁止 `host_*` | 中层补齐后,ext 经 `lib/re` 等调用 |
|
||||
| 每个新 `host_*` | 必须有 L1 包装 + 金样 + 中英对称(见 [stdlib-i18n.md](stdlib-i18n.md)) |
|
||||
| 能纯 mq 的 | 例如在 `table` 上的 `sort_by` 若性能可接受,可先纯库;热路径再下沉 host |
|
||||
| WASM | 新 host 须标注是否进浏览器构建;不能 WASM 的在文档标 `host-only` |
|
||||
| 依赖 | 新增 crate 写进 [dependencies.md](dependencies.md) 动机;禁止「顺手」拉大型框架 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 模块候选总表(按优先级波次)
|
||||
|
||||
完整排期与验收见 [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md)。摘要:
|
||||
|
||||
| 波次 | 模块(英 / 中) | 典型能力 | 主要形态 |
|
||||
|------|-----------------|----------|----------|
|
||||
| **M1** | `re` / `正则` · `encoding` / `编码` | match / find / replace;base64 / hex | **done** |
|
||||
| **M2** | `path` / `路径` · `fs` 加厚 | join / normalize;copy / move / temp | **done** |
|
||||
| **M3** | `hash` / `哈希` · `secrets` / `机密` | sha256 / hmac;token | **done** |
|
||||
| **M4** | `csv` / `逗号表` · `text` 加厚 | parse / stringify;contains / replace | **done** |
|
||||
| **M5** | `table` 加厚 · `cli` / `命令行` | sort / zip;flags | **done** |
|
||||
| **M6** | `log` / `日志` · `uuid` / `标识` | level 日志;v4 | 薄 host 或纯 mq |
|
||||
| **可选** | `yaml` / `Toml` | 仅当 public/catalog 强需求 | 慎入 |
|
||||
|
||||
**刻意延后:** 完整 `datetime` 时区库、连接池、异步 runtime、模板引擎、完整 `collections` 类型系统——等中层前几波用起来再议。
|
||||
|
||||
---
|
||||
|
||||
## 6. 与现有库的关系
|
||||
|
||||
| 现有 | 中层策略 |
|
||||
|------|----------|
|
||||
| `lib/text` | **加厚**,不另起 `strings` 英文名(保持 Marqdo 习惯);中文 `文本` |
|
||||
| `lib/table` | Mid 集合算法优先挂这里或薄 `listx`;避免与 GFM 表语义打架 |
|
||||
| `lib/net` | HTTP 客户端保留;编解码类能力与 `encoding` 边界写清(url 组件归谁) |
|
||||
| `lib/math` | 保持**高中**;哈希 / 安全随机不进 math |
|
||||
| `lib/json` | 仍只 parse/stringify/quote;CSV/YAML 另库 |
|
||||
| `lib/plugin` | 不变;文档写明「通用能力请先查 Mid」 |
|
||||
| `ext/*` | 逐步**改写依赖**:能改用 `lib/re` 的路由/校验,去掉不必要的原生 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 文档与工程节奏
|
||||
|
||||
每个 Mid 波次固定流水线(与现有发版习惯对齐):
|
||||
|
||||
1. 本设计不变的前提下,在 roadmap 勾选该波次工作项。
|
||||
2. `doc/design/stdlib-<module>.md`(可短)→ `host_*` → `lib/` 中英 → `tests/lib/*` 金样 → `public/features` 短文。
|
||||
3. 更新 [stdlib-modules.md](stdlib-modules.md) 模块表。
|
||||
4. **不**为 Mid 单开 SemVer 故事;随正常产品发版收进 CHANGELOG「标准库」小节。
|
||||
5. 发版技能 / Release 资产:仅当新增 **必须** 随 CLI 分发的东西时改 release 脚本——Mid 默认已嵌入 stdlib,**无** native zip。
|
||||
|
||||
---
|
||||
|
||||
## 8. 成功标准(数个版本后)
|
||||
|
||||
1. 用 Mid + 核心 L1 **不加载任何插件**,能写:日志采集脚本、CSV 清洗、带正则的文本管线、带哈希校验的下载器、简单 CLI 工具。
|
||||
2. 新的官方 **非领域** 能力默认进 `lib/`,评审时问:「能否不做成插件?」
|
||||
3. `ext/web` / `ext/agent` 等仍可有插件,但依赖面写进文档:哪些能力已改走 Mid。
|
||||
4. 主二进制体积与依赖可解释;WASM 可用性有清单。
|
||||
|
||||
---
|
||||
|
||||
## 9. 一句话
|
||||
|
||||
**中层标准库把「通用原语」沉回语言自带层,让插件专属于真正的领域引擎——这样 Marqdo 才像一门通用语言,而不是「Markdown + 一堆 .so」。**
|
||||
@@ -2,10 +2,10 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin** |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
|
||||
| 状态 | **核心已落地**;**中层 Mid:M1–M6 已落地** · [stdlib-mid.md](stdlib-mid.md) / [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精;**通用能力优先 Mid,插件留给领域核** |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-mid.md](stdlib-mid.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
|
||||
|
||||
---
|
||||
|
||||
@@ -15,12 +15,22 @@
|
||||
|
||||
| 模块族 | 英文库 | 中文库 | 状态 |
|
||||
|--------|--------|--------|------|
|
||||
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
|
||||
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有(`put`/`改` + list/map;见 [stdlib-table.md](stdlib-table.md)) |
|
||||
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 |
|
||||
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 + **Mid M4** 加厚 |
|
||||
| **正则** | `lib/re.mq.md` | `lib/正则.mq.md` | **Mid M1** |
|
||||
| **编解码** | `lib/encoding.mq.md` | `lib/编码.mq.md` | **Mid M1** |
|
||||
| **路径** | `lib/path.mq.md` | `lib/路径.mq.md` | **Mid M2** |
|
||||
| **哈希** | `lib/hash.mq.md` | `lib/哈希.mq.md` | **Mid M3** |
|
||||
| **机密** | `lib/secrets.mq.md` | `lib/机密.mq.md` | **Mid M3** |
|
||||
| **逗号表** | `lib/csv.mq.md` | `lib/逗号表.mq.md` | **Mid M4** |
|
||||
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有 + Mid M4/M5:`sort`/`unique`/`zip`/… |
|
||||
| **命令行** | `lib/cli.mq.md` | `lib/命令行.mq.md` | **Mid M5** |
|
||||
| **日志** | `lib/log.mq.md` | `lib/日志.mq.md` | **Mid M6** |
|
||||
| **标识** | `lib/uuid.mq.md` | `lib/标识.mq.md` | **Mid M6** |
|
||||
| 浏览器效应 | `lib/browser.mq.md` | `lib/浏览器.mq.md` | WASM 客户端效应助手(GFM + helpers;勿用 `json.set` 链) |
|
||||
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 + Mid M2:`copy_file` / `move` / `make_temp` |
|
||||
| 系统 | `lib/sys.mq.md` | `lib/系统.mq.md` | 已有(含 `load_dotenv`) |
|
||||
| 时间 | `lib/time.mq.md` | `lib/时间.mq.md` | 已有 |
|
||||
| JSON | `lib/json.mq.md` | **同文件** | 已有(含 `quote`) |
|
||||
| JSON | `lib/json.mq.md` | **同文件** | **仅** parse / stringify / quote;集合请用 table / GFM |
|
||||
| 网络 | `lib/net.mq.md` | `lib/网络.mq.md` | 已有(HTTPS + headers) |
|
||||
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | 已有 |
|
||||
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | 已有 |
|
||||
@@ -28,7 +38,9 @@
|
||||
| **自写回** | `lib/writeback.mq.md` | `lib/自写回.mq.md` | **已有**(Jupyter 式输出写回) |
|
||||
| **子任务** | `lib/subtask.mq.md` | `lib/子任务.mq.md` | **已有**(OS 子进程 + KillOnDrop) |
|
||||
|
||||
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` — 见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` · `ext/web` · `ext/quantum` · `ext/linalg` — 见各 `ext-*.md`。
|
||||
|
||||
**中层已落地:** M1–M6(含 log / uuid)— 见 [stdlib-mid.md](stdlib-mid.md) · [stdlib-log-uuid.md](stdlib-log-uuid.md)。
|
||||
|
||||
设计细节:[stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md)。
|
||||
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
# `lib/path` — 路径代数(Mid M2)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M2)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 导入 | `lib/path.mq.md` · `lib/路径.mq.md` |
|
||||
| Host | `host_path_*`(`std::path`;无 I/O、不经 `fs_root`) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `join` | `拼接` | `a`, `b` | 文本路径 |
|
||||
| `split` | `拆分` | `path` | 组件文本列表(去空段) |
|
||||
| `file_name` | `文件名` | `path` | 最后一段;根路径可为空文本 |
|
||||
| `parent` | `父目录` | `path` | 父路径文本;无父则 `"."` |
|
||||
| `extension` | `扩展名` | `path` | 不含点;无扩展名为 `""` |
|
||||
| `normalize` | `规范化` | `path` | 清理 `.` / `..`(纯字符串,不访问磁盘) |
|
||||
| `is_absolute` | `是绝对` | `path` | 布尔 |
|
||||
|
||||
## 2. 语义
|
||||
|
||||
- 分隔符与绝对路径判定跟随 **宿主 OS**(Linux CI 为 `/`)。
|
||||
- **不做** I/O;逃逸检查仍由 `lib/fs` 在读写时执行。
|
||||
- `join`:若 `b` 为绝对路径,结果为 `b`(同 `Path::join`)。
|
||||
|
||||
## 3. 刻意不做(v1)
|
||||
|
||||
`glob`、符号链接解析、`relative_to`、Windows UNC 专项文档。
|
||||
@@ -0,0 +1,33 @@
|
||||
# `lib/re` — 正则(Mid M1)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M1)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
|
||||
| 导入 | `lib/re.mq.md` · `lib/正则.mq.md` |
|
||||
| Host | `host_re_*`(`regex` crate,默认 Unicode) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `is_match` | `匹配` | `text`, `pattern` | 布尔 |
|
||||
| `find` | `查找` | `text`, `pattern` | 首个匹配文本,或 `None` |
|
||||
| `find_all` | `查找全部` | `text`, `pattern` | 文本列表 |
|
||||
| `replace` | `替换` | `text`, `pattern`, `with`, 可选 `count` | 文本(`count` 缺省 = 全部) |
|
||||
| `split` | `拆分` | `text`, `pattern` | 文本列表 |
|
||||
|
||||
非法 pattern → 诊断失败(含 crate 错误信息)。
|
||||
|
||||
## 2. 语义
|
||||
|
||||
- 引擎:Rust [`regex`](https://docs.rs/regex)(无回溯引用;与 RE2 同族限制)。
|
||||
- 按 **UTF-8 文本**匹配,不做字节模式。
|
||||
- `find` / `find_all` 返回整段匹配(不含捕获组拆分;捕获组 v1 不做)。
|
||||
|
||||
## 3. 刻意不做(v1)
|
||||
|
||||
命名捕获、替换回调、`Regex` 对象缓存 API、字节模式。
|
||||
@@ -0,0 +1,24 @@
|
||||
# `lib/secrets` — 安全随机令牌(Mid M3)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M3)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-hash.md](stdlib-hash.md) · [stdlib-mid.md](stdlib-mid.md) |
|
||||
| 导入 | `lib/secrets.mq.md` · `lib/机密.mq.md` |
|
||||
| Host | `host_secrets_*`(`getrandom`) |
|
||||
|
||||
---
|
||||
|
||||
## 1. API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `token_hex` | `十六进制令牌` | 可选 `n`(字节数,默认 16) | 小写 hex,长度 `2*n` |
|
||||
| `token_urlsafe` | `网址安全令牌` | 可选 `n`(字节数,默认 16) | URL-safe Base64(无填充) |
|
||||
|
||||
**不要**用 `math.random` / `math.seed` 生成令牌。
|
||||
|
||||
## 2. 刻意不做
|
||||
|
||||
密钥派生、加密/解密、密码哈希。
|
||||
@@ -0,0 +1,30 @@
|
||||
# `lib/text` 加厚(Mid M4)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地(M4)** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-csv.md](stdlib-csv.md) · [stdlib-mid.md](stdlib-mid.md) |
|
||||
| 导入 | `lib/text.mq.md` · `lib/文本.mq.md` |
|
||||
| Host | `host_text_*`(Unicode 大小写 / 子串;非正则替换) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 新增 API
|
||||
|
||||
| 英文 | 中文 | 形参 | 结果 |
|
||||
|------|------|------|------|
|
||||
| `contains` | `包含` | `text`, `sub` | 布尔 |
|
||||
| `starts_with` | `开头是` | `text`, `prefix` | 布尔 |
|
||||
| `ends_with` | `结尾是` | `text`, `suffix` | 布尔 |
|
||||
| `replace` | `替换` | `text`, `old`, `new`, 可选 `count` | 文本(字面替换,非正则) |
|
||||
| `to_upper` | `大写` | `text` | 文本(Unicode) |
|
||||
| `to_lower` | `小写` | `text` | 文本 |
|
||||
| `repeat` | `重复` | `text`, `n` | 文本 |
|
||||
| `pad` | `填充` | `text`, `width`, 可选 `fill`=`" "`,可选 `align`=`left`/`right`/`center` | 文本 |
|
||||
|
||||
保留原有 `str_trim` / `str_split` / `str_join`(及中文去空白/拆分/拼接)。
|
||||
|
||||
## 2. 刻意不做
|
||||
|
||||
正则替换(用 `lib/re`)、完整 `format` 模板引擎。
|
||||
@@ -2,12 +2,13 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **S0–S3 + L1 全模块落地** |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) |
|
||||
| 状态 | **S0–S3 + 核心 L1 已落地 · 中层 L1(Mid)规划中** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [**stdlib-mid.md**](stdlib-mid.md) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) |
|
||||
|
||||
> **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。
|
||||
> **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。
|
||||
> **中层标准库(数个版本)**:通用原语沉 `lib/`、减少「事事插件」——设计 [stdlib-mid.md](stdlib-mid.md) · 路线 [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md)。
|
||||
> **`ext/` 不是 stdlib**:官方可选扩展见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
|
||||
|
||||
---
|
||||
@@ -17,9 +18,10 @@
|
||||
| 层 | 内容 |
|
||||
|----|------|
|
||||
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at`(`type` 可含 `map`) |
|
||||
| **L1 官方库** | 仓库根目录 [`lib/`](../../lib/)(`.mq.md`);可用 `lib/…` 或别名 `std/…` 导入 |
|
||||
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1 |
|
||||
| **L2** | catalog / 用户站收录(随发版) |
|
||||
| **L1 核心** | 已有 [`lib/`](../../lib/):fs/sys/time/json/net/math/foreign/plugin/table/text/… |
|
||||
| **L1 中层(Mid)** | 规划中:re / encoding / path / hash / csv / … — 仍在 `lib/`,见 [stdlib-mid.md](stdlib-mid.md) |
|
||||
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1;插件仅领域热路径 |
|
||||
| **L2** | catalog / 用户站收录(随发版);应主要靠核心+中层、默认无插件 |
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -44,10 +44,11 @@ v1 把 GFM 数据单元格一律收成 **字面量**(`Int` / `Text`)。结
|
||||
| `` `api_key` `` | 变量引用 |
|
||||
| `` `a` + `b` `` | 普通表达式 |
|
||||
| `True` / `假` / `None` | 布尔 / 空 |
|
||||
| `"https://…"` / `".marqdo/x"` | 引号字符串(可含 `/`、插值) |
|
||||
| `"https://…"` / `".marqdo/x"` / `"1/5"` / `"16/9"` | 引号字符串(可含 `/`、插值;**CSS 比率等含 `/` 的值请用引号**,勿依赖空格消歧) |
|
||||
| `https://api.openai.com/v1` | **路径折叠**:无空格的 `Text/Text/…` 除法链收成整段文本(同调用实参) |
|
||||
| `gpt-4o-mini` | **连字符散文**:不拆成减法(同调用实参) |
|
||||
| `` /about ``、`` /chat/completions `` | 以 `/` 开头的路径散文 → 整段文本 |
|
||||
| `1/5` | **整数除法**(同表达式 / 调用实参;今日整除得 `0`)——要文本请写 `"1/5"` |
|
||||
| 空单元格 | 空文本 `""` |
|
||||
|
||||
### 2.2 表头仍是键名文本
|
||||
@@ -111,9 +112,10 @@ v1 把 GFM 数据单元格一律收成 **字面量**(`Int` / `Text`)。结
|
||||
|--------|------|
|
||||
| 纯中文/英文词、整数 | **不变** |
|
||||
| `gpt-4o-mini`、URL、`/path` | **不变**(折叠规则与调用实参一致) |
|
||||
| 真正要做除法 / 减法 | 用空格或括号:`` `n` / 2 ``、`` `a` - 1 ``;或先在表外算再 `` `x` `` 填入 |
|
||||
| 真正要做除法 / 减法 | 裸写 `1/5` 或空格/括号:`` `n` / 2 ``、`` `a` - 1 ``;或先在表外算再 `` `x` `` 填入 |
|
||||
| CSS / 含 `/` 的散文值 | **引号优先**:`"1/5"`、`"16/9"`、`"image/png"`(不靠空格把算术「关掉」) |
|
||||
|
||||
破坏性:几乎无。唯一需注意的是「想在单元格里写算术且两侧是裸词」——与调用实参同一套消歧。
|
||||
破坏性:几乎无。唯一需注意的是「想在单元格里写算术且两侧是裸词」——与调用实参同一套消歧;含 `/` 的**文本**一律用引号。
|
||||
|
||||
---
|
||||
|
||||
@@ -132,6 +134,7 @@ v1 把 GFM 数据单元格一律收成 **字面量**(`Int` / `Text`)。结
|
||||
|----|------|
|
||||
| 金样 | 横表单元格 `` `var` `` 读环境;竖表旧金样全绿 |
|
||||
| 路径 | `https://…`、`/chat/completions`、`gpt-4o-mini` 仍为文本 |
|
||||
| 含 `/` 文本 | 表单元格用引号:`"1/5"`、`"16/9"`;裸 `1/5` 为除法 |
|
||||
| 扩展 | `ext/ai/llm` 构造可用表写入运行时字段,去掉无必要的 `json.set` 链 |
|
||||
| 文档 | 本页 + roadmap T5 + markdown-mapping §9 同步 |
|
||||
|
||||
|
||||
@@ -34,7 +34,7 @@
|
||||
| 中 | 静态类型 / 可维护 AST | 长期改解释器不疼 |
|
||||
| 中 | CLI 与打包 | 单二进制或 `npx`/等价体验 |
|
||||
| 低 | 极致性能 | v0 样例很小 |
|
||||
| 低 | 浏览器内运行 | 可后置 |
|
||||
| 低 | 浏览器内运行 | **已后置落地规划**:见 [ADR 0002](../adr/0002-browser-marqdo-wasm.md)(WASM 解释器) |
|
||||
|
||||
非准则:跟风、先写再选、与「生成 OKF」强绑某一云厂商。
|
||||
|
||||
|
||||
@@ -0,0 +1,328 @@
|
||||
# `ext/web` — 站点图标、Head 资源与图片装配
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · W8 已落地** |
|
||||
| 日期 | 2026-08-29 |
|
||||
| 父设计 | [ext-web.md](ext-web.md) · [web-net-capabilities.md](web-net-capabilities.md) |
|
||||
| 相关 | [web-asgi-servers-and-marqdo.md](web-asgi-servers-and-marqdo.md)(静态仍由嵌入式 `listen` 提供) |
|
||||
| 硬约束 | `ext/**` 不调 `host_*`;作者面禁止袋胶水;中英库文件分文件 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
把 **浏览器默认图标(`/favicon.ico`)**、**`<head>` 里的 link/script**、**正文/品牌图片** 都做成与 `样式装配` 同构的能力:**GFM 表即数据,装配即函数**;由 `plugins/web` ABI 渲染/挂路由,`ext/web` 只做 L1 包装。
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机与现状缺口
|
||||
|
||||
### 1.1 已有
|
||||
|
||||
| 能力 | 说明 |
|
||||
|------|------|
|
||||
| `app.static` / `应用.静态` | 目录挂到 `/static`(或自定义 mount) |
|
||||
| `page.meta` / `页面.元数据` | `title` / `description` / `canonical` / `og:*` → `<head>` |
|
||||
| `app.upload` + `gallery` | **运行时**用户上传媒体,不是站点品牌资源 |
|
||||
|
||||
### 1.2 缺口(本设计一次补齐)
|
||||
|
||||
| # | 缺口 | 影响 |
|
||||
|---|------|------|
|
||||
| G1 | 浏览器默认请求 **`GET /favicon.ico`**,静态挂在 `/static` 时根路径 404 | 标签页无图标 |
|
||||
| G2 | `page.meta` 未知键一律变成 `<meta name="…">`,**不能**正确写出 `<link rel="icon">` | 作者写 `icon` 无效 |
|
||||
| G3 | 无 **Head 资源表**(stylesheet / preload / script / manifest / apple-touch-icon) | 只能手写进 `intro` 或改插件 |
|
||||
| G4 | 无 **图片装配**(表 → `<figure>`/`<img>`),与样式装配不对齐 | logo / 头图 / 插图只能拼 HTML 字符串 |
|
||||
| G5 | 无 **站点级图标表 → 根路径文件服务 + 默认 head 注入** | 多页站点要在每页重复声明 |
|
||||
|
||||
---
|
||||
|
||||
## 2. 设计原则
|
||||
|
||||
1. **配置即数据、装配即函数** — 与 `web_style` / `应用.装配` 同构。
|
||||
2. **应用层管「可达性」**(磁盘文件 → HTTP 路径);**页面层管「声明」**(`<head>` / 正文 HTML)。
|
||||
3. **站点图标可自动注入所有页面**,页面仍可用 `头装配` / `元数据` 覆盖或追加。
|
||||
4. **约定优于配置**:若已 `静态` 且目录内存在 `favicon.ico`(或 `favicon.png` / `favicon.svg`),未显式配置时仍挂 `GET /favicon.ico`(及对应静态 URL 由作者自选)。
|
||||
5. **中英分文件**:`web.mq.md` ↔ `网页.mq.md`,禁止混排。
|
||||
|
||||
---
|
||||
|
||||
## 3. 作者面 API(一次交付全集)
|
||||
|
||||
### 3.1 模块级装配(返回字符串,可与主题拼装)
|
||||
|
||||
| EN | ZH | FFI | 输入 | 输出 |
|
||||
|----|----|-----|------|------|
|
||||
| `make_style`(已有) | `样式装配` | `web_style` | 样式表 | CSS 文本 |
|
||||
| **`make_images`** | **`图片装配`** | **`web_images`** | 图片表 | HTML 片段 |
|
||||
| **`make_head`** | **`头资源装配`** | **`web_head`** | Head 表 | 供调试/预览的 HTML 片段(可选;页面方法主路径不强制调用) |
|
||||
|
||||
### 3.2 `# page` / `# 页面`
|
||||
|
||||
| EN | ZH | FFI | 作用 |
|
||||
|----|----|-----|------|
|
||||
| `meta`(增强) | `元数据` | `web_page_meta` | 认 `icon` / `favicon` / `apple-touch-icon` → `<link>`,不再误写成 `<meta name>` |
|
||||
| **`head`** | **`头装配`** | **`web_page_head`** | 挂 Head 资源表到 `page.head`,渲染时写入 `<head>` |
|
||||
| **`images`** | **`图片装配`**(方法) | **`web_page_images`** | 图片表 → HTML,写入 `page.images_html`,渲染进主区 |
|
||||
|
||||
### 3.3 `# app` / `# 应用`
|
||||
|
||||
| EN | ZH | FFI | 作用 |
|
||||
|----|----|-----|------|
|
||||
| **`icons`** | **`图标`** | **`web_app_icons`** | 站点图标表:根路径文件服务 + 默认 head 链接注入全站 |
|
||||
| `static`(增强) | `静态`(增强) | `web_app_static` | 约定:目录内 `favicon.ico|png|svg` → 自动注册 `/favicon.ico`(可被 `icons` 显式行覆盖) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 表形约定
|
||||
|
||||
单元格仍为**字面量**;列名中英等价(任选一套,勿混列名语义)。
|
||||
|
||||
### 4.1 站点图标表(`app.icons` / `应用.图标`)
|
||||
|
||||
| 列(ZH) | 列(EN) | 必填 | 说明 |
|
||||
|----------|----------|------|------|
|
||||
| `路径` | `path` | ✅* | 磁盘路径(相对进程 cwd 或入口目录解析规则与 `static` 一致) |
|
||||
| `关系` | `rel` | | 默认 `icon`;常用 `icon` / `apple-touch-icon` / `mask-icon` |
|
||||
| `类型` | `type` | | 缺省按扩展名推断 |
|
||||
| `尺寸` | `sizes` | | 如 `16x16`、`180x180`、`any` |
|
||||
| `地址` | `url` / `href` | | 对外 URL。缺省:首个 `rel=icon` 且扩展名为 `.ico` → `/favicon.ico`;否则 `/icons/{文件名}` |
|
||||
|
||||
\* 若仅提供 `地址` 指向已由 `静态` 提供的 URL、不落盘服务,则 `路径` 可空(只注入 head,不挂新路由)。
|
||||
|
||||
**Listen 行为**
|
||||
|
||||
1. 规范化为数组 `{path, rel, type, sizes, url}`。
|
||||
2. 对每个非空 `path`:注册 **`GET {url}`**,读文件返回,`Content-Type` = `type` 或推断;`Cache-Control` 可用 `public, max-age=86400`。
|
||||
3. 若存在至少一个 `rel` 含 `icon` 的行,保证浏览器默认路径:若没有任何 `url=/favicon.ico`,则把**第一行 icon** 额外挂到 `/favicon.ico`(同一文件,可选)。
|
||||
4. 将图标行转为默认 head 链接列表,存入 `app.site_head`,listen 时写入 `AppState`,渲染任意页面前 **merge**(页面自有 `head` / meta 图标 **追加且可同 href 去重**)。
|
||||
|
||||
**`static` 约定自动图标**
|
||||
|
||||
在 `listen` 解析完 `static_dir` 后:若 `app.icons` 为空,且 `{static_dir}/favicon.ico` 或 `.png` / `.svg` 存在,则等价注册:
|
||||
|
||||
```text
|
||||
path = {static_dir}/favicon.{ico|png|svg}
|
||||
rel = icon
|
||||
url = /favicon.ico
|
||||
```
|
||||
|
||||
(文件仍可通过 `/static/favicon.*` 访问;根路径额外可达。)
|
||||
|
||||
### 4.2 Head 资源表(`page.head` / `页面.头装配`)
|
||||
|
||||
| 列(ZH) | 列(EN) | 说明 |
|
||||
|----------|----------|------|
|
||||
| `关系` | `rel` | `icon` / `apple-touch-icon` / `stylesheet` / `preload` / `modulepreload` / `manifest` / `canonical` / **`script`** / **`module`** |
|
||||
| `地址` | `href` / `src` / `url` | 资源 URL |
|
||||
| `类型` | `type` | MIME 或 `module` |
|
||||
| `尺寸` | `sizes` | icons |
|
||||
| `媒体` | `media` | CSS media |
|
||||
| `作为` | `as` | preload `as` |
|
||||
| `跨域` | `crossorigin` | 空 / `anonymous` / `use-credentials` |
|
||||
| `推迟` | `defer` | 经典 `script` 为真时输出 `defer`(缺省同步,兼容旧站) |
|
||||
| `异步` | `async` | 为真时输出 `async` |
|
||||
| `版本` | `version` / `v` | 非空则自动追加 `?v=`;否则用页面/应用 `asset_version` |
|
||||
|
||||
**渲染规则**
|
||||
|
||||
| `rel` | 输出 |
|
||||
|-------|------|
|
||||
| `script` | `<script … src="…"></script>`(可选 `defer`/`async`;`type` 非空则写出) |
|
||||
| `module` | `<script type="module" src="…"></script>`(浏览器默认 defer 语义) |
|
||||
| 其他 | `<link rel="…" href="…" …>`(按列附加 `type`/`sizes`/`media`/`as`/`crossorigin`) |
|
||||
|
||||
空 `地址` 的行跳过。
|
||||
|
||||
### 4.3 元数据表增强(`page.meta`)
|
||||
|
||||
| 键 | 行为 |
|
||||
|----|------|
|
||||
| `title` / `description` / `canonical` / `og:*` | **不变** |
|
||||
| **`icon`** / **`favicon`** | `<link rel="icon" href="{值}"/>`(可选若值含空格后 MIME:本切片仅 href) |
|
||||
| **`apple-touch-icon`** | `<link rel="apple-touch-icon" href="{值}"/>` |
|
||||
| 其他 | 仍为 `<meta name="…" content="…"/>` |
|
||||
|
||||
### 4.4 图片表(`make_images` / `page.images`)
|
||||
|
||||
| 列(ZH) | 列(EN) | 说明 |
|
||||
|----------|----------|------|
|
||||
| `源` | `src` | 必填,图片 URL |
|
||||
| `替代` | `alt` | `alt` 文本,默认空 |
|
||||
| `标题` | `title` | `title` 属性 |
|
||||
| `类` | `class` | 加在 `<figure>`(无 figure 时加在 `<img>`) |
|
||||
| `链接` | `href` / `link` | 非空则用 `<a>` 包裹 `<img>` |
|
||||
| `宽度` | `width` | 像素,可选 |
|
||||
| `高度` | `height` | 像素,可选 |
|
||||
| `加载` | `loading` | `lazy` / `eager`;默认 `lazy`(首行可写 `eager`) |
|
||||
| `图注` | `caption` | 非空则 `<figcaption>` |
|
||||
| `槽` | `slot` | 预留:`main`(默认)。本切片只支持主区 |
|
||||
|
||||
**输出 HTML(多行)**
|
||||
|
||||
```html
|
||||
<div class="mq-images" data-slot="main">
|
||||
<figure class="mq-img …">…</figure>
|
||||
…
|
||||
</div>
|
||||
```
|
||||
|
||||
单行且无图注/类时仍包在 `div.mq-images` 内,保证主题可统一选中。
|
||||
|
||||
**`page.images`**:调用 `web_images` 逻辑,结果写入 `page.images_html`。
|
||||
|
||||
**渲染位置**:`render_page` 主区中,在 `intro` **之前**插入 `images_html`(品牌图/头图常见需求);`render_fragment` 的 main 槽同样插入。
|
||||
|
||||
路径与 MIME 单元格若含 `/`,须写成引号字面量(T5 单元格表达式会把裸 `/` 当除法):`"/favicon.ico"`、`"image/png"`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 插件 / 状态形状
|
||||
|
||||
### 5.1 页面对象新增字段
|
||||
|
||||
```json
|
||||
{
|
||||
"meta": { "title": "…", "icon": "/favicon.ico" },
|
||||
"head": [
|
||||
{ "rel": "stylesheet", "href": "/static/print.css", "media": "print" }
|
||||
],
|
||||
"images_html": "<div class=\"mq-images\">…</div>"
|
||||
}
|
||||
```
|
||||
|
||||
### 5.2 应用对象新增字段
|
||||
|
||||
```json
|
||||
{
|
||||
"static_dir": "public",
|
||||
"static_mount": "/static",
|
||||
"icons": [
|
||||
{
|
||||
"path": "public/favicon.ico",
|
||||
"rel": "icon",
|
||||
"type": "image/x-icon",
|
||||
"sizes": "32x32",
|
||||
"url": "/favicon.ico"
|
||||
}
|
||||
],
|
||||
"site_head": [
|
||||
{ "rel": "icon", "href": "/favicon.ico", "type": "image/x-icon", "sizes": "32x32" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
`site_head` 由 `web_app_icons`(及 static 约定)生成,作者不必手写。
|
||||
|
||||
### 5.3 `AppState` / `listen` 签名
|
||||
|
||||
新增:
|
||||
|
||||
- `icon_routes: Vec<IconRoute { url, path, content_type }>`
|
||||
- `site_head: Vec<HeadLink>`
|
||||
|
||||
在 `home` / 动态与静态 `route` 渲染前:`merge_site_head(&mut page, &state.site_head)`。
|
||||
|
||||
---
|
||||
|
||||
## 6. MIME 推断
|
||||
|
||||
| 扩展名 | Content-Type |
|
||||
|--------|----------------|
|
||||
| `.ico` | `image/x-icon` |
|
||||
| `.png` | `image/png` |
|
||||
| `.svg` | `image/svg+xml` |
|
||||
| `.webp` | `image/webp` |
|
||||
| `.jpg` / `.jpeg` | `image/jpeg` |
|
||||
| `.gif` | `image/gif` |
|
||||
| `.webmanifest` / `.json` | `application/manifest+json` |
|
||||
| 其他 | `application/octet-stream` |
|
||||
|
||||
---
|
||||
|
||||
## 7. 作者示例(中文)
|
||||
|
||||
```markdown
|
||||
## 站点图标
|
||||
|
||||
|路径|关系|类型|尺寸|地址|
|
||||
|---|---|---|---|---|
|
||||
|public/favicon.ico|icon|image/x-icon|32x32|/favicon.ico|
|
||||
|public/apple-touch-icon.png|apple-touch-icon|image/png|180x180|/static/apple-touch-icon.png|
|
||||
|
||||
## 头资源
|
||||
|
||||
|关系|地址|类型|媒体|
|
||||
|---|---|---|---|
|
||||
|icon|/favicon.ico|image/x-icon|
|
||||
|stylesheet|/static/print.css|text/css|print|
|
||||
|script|/static/live.js||
|
||||
|
||||
## 品牌图
|
||||
|
||||
|源|替代|类|链接|宽度|加载|
|
||||
|---|---|---|---|---|---|
|
||||
|/static/logo.svg|Marqdo|brand-logo|/|48|eager|
|
||||
|
||||
# main
|
||||
|
||||
*page = > 网页.页面 标题="博客"*
|
||||
*page = > page.头装配 表=`头资源`*
|
||||
*page = > page.图片装配 表=`品牌图`*
|
||||
*page = > page.元数据 元数据=`seo表`*
|
||||
|
||||
*app = > 网页.应用 页面=`page` …*
|
||||
*app = > app.静态 目录="public" 挂载="/static"*
|
||||
*app = > app.图标 表=`站点图标`*
|
||||
> app.监听
|
||||
```
|
||||
|
||||
英文对称:`web.page` / `head` / `images` / `meta`;`web.app` / `static` / `icons`;模块 `web.make_images`。
|
||||
|
||||
---
|
||||
|
||||
## 8. 实现清单(本切片必须全部完成)
|
||||
|
||||
| # | 项 | 归属 |
|
||||
|---|----|------|
|
||||
| I1 | `assets.rs`:表解析、MIME、`web_images` HTML、`web_head` HTML、图标规范化 | `plugins/web` |
|
||||
| I2 | `web_page_head` / `web_page_images` / `web_images` / `web_head` / `web_app_icons` FFI + 注册 | `plugins/web` |
|
||||
| I3 | `head_html`:meta 图标键 + `page.head` + 合并 `site_head` | `render.rs` |
|
||||
| I4 | `images_html` 插入主区;fragment main 同理 | `render.rs` |
|
||||
| I5 | `listen`:图标文件路由 + static 约定 favicon + `AppState` 注入 | `http.rs` / `lib.rs` |
|
||||
| I6 | `ext/web/web.mq.md` + `网页.mq.md` L1 方法与叙述 | `ext/web` |
|
||||
| I7 | 金样:离线装配 + live `GET /favicon.ico` + HTML 含 link/img | `tests/ext/` |
|
||||
| I8 | `examples/marqdo-blog`:真实 favicon + logo 装配 + README | `examples/` |
|
||||
| I9 | 更新 [web-net-capabilities.md](web-net-capabilities.md)、[ext-web.md](ext-web.md)、[doc/README.md](../README.md)、CHANGELOG Unreleased;Skill 专节一句 | 文档 |
|
||||
|
||||
**非目标(本切片不做)**
|
||||
|
||||
- 服务端图片缩放 / WebP 转码
|
||||
- CDN 签名 URL
|
||||
- 把上传相册(`gallery`)与品牌图混为一谈
|
||||
- 进程内 TLS(仍见反代文档)
|
||||
|
||||
---
|
||||
|
||||
## 9. 验收标准
|
||||
|
||||
1. `marqdo run tests/ext/web-assets-smoke.mq.md` 离线:icons/head/images 字段与 HTML 片段断言通过。
|
||||
2. Live:`GET /favicon.ico` → 200 + 正确 Content-Type;首页 HTML 含 `rel="icon"` 与 `mq-images`。
|
||||
3. `examples/marqdo-blog`:`curl /favicon.ico` 与页面源码可见图标与 logo。
|
||||
4. 旧金样(`web-static-smoke`、`web-content-smoke` 等)不回归。
|
||||
5. `ext/**` 无 `host_*`。
|
||||
|
||||
---
|
||||
|
||||
## 10. 与能力矩阵的关系
|
||||
|
||||
在 [web-net-capabilities.md](web-net-capabilities.md) **类 D** 增补:
|
||||
|
||||
| # | 能力 | 状态 |
|
||||
|---|------|------|
|
||||
| **D10** | 站点图标 / `/favicon.ico` / apple-touch-icon | ✅ 本设计 |
|
||||
| **D11** | Head 资源表(link / script / preload / manifest) | ✅ 本设计 |
|
||||
| **D12** | 图片装配(GFM → figure/img)+ 主区注入 | ✅ 本设计 |
|
||||
|
||||
波次标签:**W8(站点资源与图片装配)** — 在 W7+P3 完结之上的内容站体验补齐,不推翻既有边界。
|
||||
@@ -166,6 +166,9 @@
|
||||
| D7 | **评论系统**(表单 + 审核 + 反垃圾) | ✅ 约定:表+表单+where(W6);反垃圾属应用层 | `ext/web` | P2 ✅ |
|
||||
| D8 | **草稿/发布/定时**(状态字段 + 过滤查询) | ✅ 约定:`status` + where(W6) | `ext/web` + db where | P2 ✅ |
|
||||
| D9 | **图片/附件库**(依赖 A5 上传 + 相册页) | ✅ **已实现(P3)**:`app.gallery` HTML 相册 + A5 上传/下载 | `ext/web` + `plugins/web` | P3 ✅ |
|
||||
| **D10** | **站点图标 / favicon**(`/favicon.ico` + apple-touch-icon) | ✅ **已实现(W8)**:`app.icons` / `应用.图标`;`static` 约定 `favicon.*`;设计 [web-assets-and-images.md](web-assets-and-images.md) | `plugins/web` + `ext/web` | W8 ✅ |
|
||||
| **D11** | **Head 资源表**(link / script / preload / manifest) | ✅ **已实现(W8)**:`page.head` / `页面.头装配`;`meta` 认 `icon`/`favicon` | `plugins/web` + `ext/web` | W8 ✅ |
|
||||
| **D12** | **图片装配**(GFM → figure/img + 主区注入) | ✅ **已实现(W8)**:`make_images` / `网页.图片装配`;`page.images` | `plugins/web` + `ext/web` | W8 ✅ |
|
||||
|
||||
---
|
||||
|
||||
@@ -184,6 +187,7 @@
|
||||
| **W6** | 进阶 | 全文搜索(FTS5) + 迁移机制 + 评论系统 + 草稿/发布 + WS 广播 | B6 B9 ✅;WS 广播 + access_log ✅;D7/D8 用表+where ✅ |
|
||||
| **W7** | 完结打磨 | Cache-Control、自定义 404/500、301 重定向、sitemap/robots、init 唯一/索引、HTTPS 反代文档 | A6 A7 A9 A10 B7 D2 ✅ |
|
||||
| **P3** | 真·网络扩展补齐 | 审计时间戳、外键、RBAC 门禁、媒体相册、下载 ETag | B10 C8 D9 + ETag/FK ✅ |
|
||||
| **W8** | 站点资源与图片装配 | favicon 根路由、Head 资源表、图片装配、meta 图标键 | D10 D11 D12 ✅ |
|
||||
|
||||
### 4.2 边界判定要点(严格遵守既有约束)
|
||||
|
||||
|
||||
@@ -0,0 +1,54 @@
|
||||
# 调研刷新:2026-09 智能体框架与 Marqdo「代码即文档」
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Wave B1 Active**(B0/B0.5 已完成;宪法优先) |
|
||||
| 日期 | 2026-09-04 |
|
||||
| 前置 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) |
|
||||
| 路线 | [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) |
|
||||
|
||||
## 0. 结论
|
||||
|
||||
业界框架(LangGraph / Microsoft Agent Framework / CrewAI / OpenAI Agents SDK)在编排、工具、检查点、MCP、评测上继续收敛;**权威真相仍默认在对象图 + transcript + 外置 Store**。
|
||||
|
||||
Marqdo 的差异化不是「再做一个 loop」,而是:
|
||||
|
||||
1. **代码即文档** — 编排 `.mq.md` = 提示词工作面
|
||||
2. **调用位置可见** — `agent_call_site`(路径 / 函数 / 行)是一等上下文
|
||||
3. **文档即知识库(OKF)** — 写回 → promote / solidify → 二次命中 / `llm_free`
|
||||
|
||||
Wave B 的目标函数:**证明并硬化上述三点**;产品化示例与评测必须服务差异化,禁止做成无源码上下文的 chatbot demo。
|
||||
|
||||
## 1. 业界快照(2026)
|
||||
|
||||
| 模式 | 代表 | 状态记忆 | 对 Marqdo |
|
||||
|------|------|----------|-----------|
|
||||
| 图 + checkpointer | LangGraph | typed state 持久化 | 续跑应对齐**文件化工作簿**,不造 Python 图 DSL |
|
||||
| Agent vs Workflow | Microsoft AF | 自主 + 确定性流 | 已有 step / plan,强化即可 |
|
||||
| 角色班组 | CrewAI | Task 管道 | 多 Agent 低优先;父 CALL + 多工作簿 |
|
||||
| Handoff + Guardrails | OpenAI Agents SDK | 显式交接 | 可借鉴语义;权威仍在 `.mq.md` |
|
||||
|
||||
## 2. 深远影响(开发硬约束)
|
||||
|
||||
| 约束 | 含义 |
|
||||
|------|------|
|
||||
| 提示不黑盒 | standing / 工具 / 任务写在文件;拼装可审查 |
|
||||
| 位置感知 | 每次推理注入 call_site;示例与评测可断言 |
|
||||
| 源码工作面 | `source_brief` + `READ:source\|skill`;禁止藏整份 Skill 进不可见提示 |
|
||||
| 写回即记忆 | ok/error 槽 + view;非默认向量库 |
|
||||
| OKF 飞轮 | promote / solidify / hit / llm_free |
|
||||
| 外置工具 | corpus / MCP 仅证据,`authority=workbook` |
|
||||
|
||||
## 3. Wave B 范围
|
||||
|
||||
| 波次 | 主题 |
|
||||
|------|------|
|
||||
| **B0** | 宪法可见示例 + 上下文管道可读性 + Skill/文档 |
|
||||
| **B0.5** | 本机 live(`.env` → cflmy)验证「模型用上了文档」 |
|
||||
| **B1** | 评测锁住 call_site / OKF / 写回 / 预算 |
|
||||
|
||||
暂缓:真 MCP、resume/HITL view、kb stats、并行、A2A。
|
||||
|
||||
## 4. 开发期 LLM
|
||||
|
||||
仓库根目录 `.env`(gitignore):`OPENAI_*` 或 `MARQDO_LLM_*`。模板见 `.env.example`。
|
||||
@@ -0,0 +1,113 @@
|
||||
# 调研:线性代数 × 公式类 × 展示
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 调研纪要(为 [ext-linalg](../design/ext-linalg.md) 供输入) |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 相关 | [stdlib-math.md](../design/stdlib-math.md) · [ext-quantum-q7.md](../design/ext-quantum-q7.md) · SymPy MatrixExpr · Symbolics.jl · LAFigureSpecs |
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题陈述
|
||||
|
||||
Marqdo 已有:
|
||||
|
||||
- `Value::Formula` + `` `f` = `` + `$$…$$`(高中标量符号)
|
||||
- `formula::Expr::Matrix`:**数值**稠密矩阵字面量(`[[…]]` / `\begin{pmatrix}`),供量子门核对与 view KaTeX
|
||||
- `ext/quantum` Q7:**量子语境**下的密度矩阵 / Kronecker / 谱 / SVD 风格图(ABI)
|
||||
|
||||
缺口:一门**经典线性代数**扩展——作者用**公式级矩阵表达式**写 \(A^\top A\)、\((X^\top X)^{-1}X^\top y\)、分块、Kronecker,在**不立刻展开成巨大稠密矩阵**的前提下做重写与化简,并在文档 / view 中**好看地呈现**分解与结构。
|
||||
|
||||
---
|
||||
|
||||
## 2. 业界对照
|
||||
|
||||
### 2.1 符号矩阵表达式(大规模优化的关键)
|
||||
|
||||
| 系统 | 模型 | 对 Marqdo 的启示 |
|
||||
|------|------|------------------|
|
||||
| **SymPy `MatrixExpr`** | `MatrixSymbol(name, n, m)` + `MatMul` / `MatAdd` / `Inverse` / `Transpose` / `Trace` / `Determinant` / `BlockMatrix` / `KroneckerProduct`;`as_explicit()` 才展开 | **默认保持抽象**;形状元数据传播;显式求值是可选动作 |
|
||||
| SymPy `block_collapse` | 分块表达式在块级化简,避免整块稠密展开 | 分块是教学与优化的第一公民 |
|
||||
| SymPy Kronecker | `KroneckerProduct` 惰性 + `combine_kronecker` 规则 | Kronecker **绝不能**默认 `expand`(维数爆炸) |
|
||||
| SymPy 矩阵求导 | 经 array expr 再收回 MatrixExpr;闭式导数 | v1 **不做**;记入远期 |
|
||||
| **Symbolics.jl** | 「数组的符号」vs「符号数组」:后者 O(1) 表示整阵,保留 `A*B` 不展开 | 与 MatrixExpr 同构;强调 **shape / eltype 元数据** |
|
||||
| NumPy / Eigen / nalgebra | 数值热路径,无公式树 | 对应 Marqdo **插件数值层**,不是文档作者主路径 |
|
||||
|
||||
**结论:** 「公式类线性代数」= **抽象表达式 DAG + 形状检查 + 重写规则**;稠密数值是 `eval` / `as_explicit` 的终点,不是默认形态。
|
||||
|
||||
### 2.2 教学与展示(效果最好的做法)
|
||||
|
||||
| 做法 | 来源 | 效果 | Marqdo 映射 |
|
||||
|------|------|------|-------------|
|
||||
| KaTeX / MathJax 渲染 `bmatrix` / `pmatrix` | SymPy `latex()` + Jupyter `init_printing` | 公式即排版;多式用 `display` 并列 | 既有 view `formula-card` + KaTeX |
|
||||
| 标签化等式 `A = UΣV^\top` | 教材 / Qiita display+Math | 步骤可读 | `show` / writeback 多卡片 |
|
||||
| **结构图**(SVD / QR / 消元轨) | [LAFigureSpecs](https://github.com/ea42gh/LAFigureSpecs) + matrixlayout;TeX `drawmatrix` | 比数字表更能讲「秩 / 零空间 / 对角结构」 | SVG `kind=svd|qr|ge|eig` |
|
||||
| 热力图 / Hinton | Qiskit / QuTiP / 既有 quantum | 稠密数值矩阵的幅度/符号 | `kind=heatmap|hinton`(经典实/复) |
|
||||
| 分块着色矩形 | CTAN `drawmatrix` | 零块 / 三角 / 带状一目了然 | `kind=structure`(形状示意图,可无元素值) |
|
||||
| 仅打印 ASCII | CLI 默认 | 金样可断言 | `str` / `print` → 规范 ASCII / LaTeX 源 |
|
||||
|
||||
**展示优先级(锁定建议):**
|
||||
|
||||
1. **符号式**:始终可 `latex` → view KaTeX(不依赖数值)
|
||||
2. **结构式 SVG**:分解 / 分块 / 秩示意(教学主图)
|
||||
3. **数值热力图**:仅在 `eval` 后、维数可控时
|
||||
4. CLI:短 ASCII;大矩阵默认摘要 `m×n …` + 可选 `preview=`
|
||||
|
||||
### 2.3 一门「够用」的线性代数库需要什么
|
||||
|
||||
按大学一学期 + 数据科学入门,能力桶:
|
||||
|
||||
| 桶 | 内容 | 符号层 | 数值层 |
|
||||
|----|------|--------|--------|
|
||||
| A 构造 | 符号阵、常数阵、单位/零/对角、从 `$$` / 表 / list | ✅ | ✅ |
|
||||
| B 代数 | 加减乘、转置、逆、伴随、幂、Kronecker、分块 | ✅ 重写 | ✅ |
|
||||
| C 分解 | LU / QR / 特征 / SVD / Cholesky(对称) | 结果对象 + 结构图 | ✅ |
|
||||
| D 系统 | `Ax=b`、最小二乘、伪逆 | 公式写法 + 数值解 | ✅ |
|
||||
| E 度量 | 行列式、迹、秩、范数、条件数 | 部分可符号 | ✅ |
|
||||
| F 展示 | latex / ASCII / SVG 结构 / heatmap | ✅ | ✅ |
|
||||
| G 微积分 | 矩阵导数、Jacobian 积木 | 远期 | — |
|
||||
|
||||
**不做(首版):** 稀疏专用格式、GPU、分布式、完整 CAS 证明、通用张量网络、与 `lib/math` 高中标量混成一个巨模块。
|
||||
|
||||
---
|
||||
|
||||
## 3. 与现有 Marqdo 的衔接点
|
||||
|
||||
| 已有 | 用法 | 扩展时注意 |
|
||||
|------|------|------------|
|
||||
| `$$` + Matrix 数值字面量 | 小门矩阵、手算核对 | 保留;符号阵用 `MatrixSymbol` 或 `matrix.symbol`,勿与数值 Matrix 混为一谈 |
|
||||
| `lib/math` formula | 标量 simplify/diff/plot | **不**把大学线性代数塞进 `lib/math`(与 Q7 结论一致) |
|
||||
| view KaTeX | formula-card | 符号 MatExpr 的 `latex` 字符串直接喂 KaTeX |
|
||||
| `ext/quantum` Q7 linop | 量子密度 / 纠缠 | **经典 API 不复用 quantum 命名空间**;共享算法可在插件内私有复用,作者面分离 |
|
||||
| `plugins/*` ABI | 重数值 / SVG | 稠密分解与大图走 `plugins/linalg` |
|
||||
| GFM 表 | 数据即代码 | 矩阵输入:表或 `$$`;分解步骤:`@` 记录表 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 「大规模优化」具体指什么
|
||||
|
||||
在公式类语境下,优化 ≠ BLAS 微内核,而是:
|
||||
|
||||
1. **惰性**:`A*B*C` 保持乘积树,直到 `eval` / `explicit`
|
||||
2. **形状短路**:不相容维数在符号阶段报错,不跑数值
|
||||
3. **代数恒等**:`(A^{-1})^{-1}→A`,`(AB)^\top→B^\top A^\top`,`I*A→A`,分块 `block_collapse`
|
||||
4. **禁止爆炸展开**:Kronecker / 高维符号积默认不 `expand`
|
||||
5. **数值批处理**:同形状多 RHS、分解一次多用(`factorize` 对象)
|
||||
6. **展示成本**:大矩阵不默认内嵌完整 KaTeX 数字阵;结构图 + 摘要
|
||||
|
||||
---
|
||||
|
||||
## 5. 推荐产品叙事(一句)
|
||||
|
||||
**线性代数文档用公式写变换,用规则做化简,用结构图讲分解,用可控数值做验算——公式是一等公民,稠密矩阵是可选终点。**
|
||||
|
||||
---
|
||||
|
||||
## 6. 参考链接
|
||||
|
||||
- SymPy Matrix Expressions: https://docs.sympy.org/latest/modules/matrices/expressions.html
|
||||
- SymPy Matrix derivatives (远期): https://docs.sympy.org/dev/explanation/modules/matrices/matrixderivatives.html
|
||||
- Symbolics.jl Symbolic Arrays: https://docs.sciml.ai/Symbolics/v6.54/manual/arrays/
|
||||
- LAFigureSpecs(教学结构图): https://github.com/ea42gh/LAFigureSpecs
|
||||
- CTAN drawmatrix: 矩阵形状示意
|
||||
- 既有:`doc/design/stdlib-math.md` · `doc/design/ext-quantum-q7.md`
|
||||
@@ -0,0 +1,154 @@
|
||||
# `ext/web` 定制限制:开发者不易定制的问题盘点
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研锁定(踩坑整理)** |
|
||||
| 日期 | 2026-09-04 |
|
||||
| 相关 | [ext-web.md](../design/ext-web.md) · [ext-web-net.md](../design/ext-web-net.md) · [web-net-capabilities.md](../design/web-net-capabilities.md) |
|
||||
| 解决索引 | [../design/ext-web-customization/](../design/ext-web-customization/) |
|
||||
|
||||
结合自研后台、样式迁移与响应式改造中的实际踩坑,整理当前 `plugins/web` + `ext/web` 对站点作者的**强占与难定制点**。本文只陈述问题与证据;逐项解法见解决索引。
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
内置 `/admin` 壳、固定鉴权路径、注入式 `SHELL_CSS` 与四区栅格,让「只写 `.mq.md`」的产品路径在**自研后台 / 品牌主题 / 移动端**上反复撞墙;作者被迫旁路前缀 + `!important` + 前端 JS 兜底。
|
||||
|
||||
---
|
||||
|
||||
## 1. 路由与路径被框架强占
|
||||
|
||||
**现象**
|
||||
|
||||
- `/admin` 及 `/admin/*` 整段保留,无法 `app.route` 注册自定义页(错误:`route path … is reserved`)。
|
||||
- `app.重定向` / `redirect` 目标若落在 reserved 前缀,同样被校验拒绝。
|
||||
- `后台=False`(`admin=False`)后,访问 `/admin/news` 等仍进内置壳,只显示 *Admin is disabled*,**不能**换成自研页。
|
||||
- 登录/登出硬绑 `/admin/login`、`/admin/logout`;登录成功硬编码 `Redirect::to("/admin")`,无法配置回跳到 `/desk`。
|
||||
|
||||
**代码证据**
|
||||
|
||||
| 位置 | 行为 |
|
||||
|------|------|
|
||||
| `plugins/web/src/lib.rs` → `normalize_route_path` | `/admin`、`/_form`、`/_part`、`/static` 一律 reserved |
|
||||
| `plugins/web/src/http.rs` | 始终挂 `/admin…` 路由;disabled 时仍 `admin_shell` + 文案 |
|
||||
| 同文件 `admin_login_post` | 成功跳转写死 `/admin` |
|
||||
|
||||
**结果**
|
||||
|
||||
自研后台只能用 `/desk` 等旁路前缀;入口与鉴权路径分裂,还要靠前端 JS(`fetch('/admin/login')` 再 `replace('/desk')`)做跳转兜底。
|
||||
|
||||
→ 解决:[01-routes-and-admin-prefix.md](../design/ext-web-customization/01-routes-and-admin-prefix.md)
|
||||
|
||||
---
|
||||
|
||||
## 2. 内置 `SHELL_CSS` 难以彻底覆盖
|
||||
|
||||
**现象**
|
||||
|
||||
- 每个页面都会注入框架壳样式,例如 `body.has-sidebar { grid-template-columns:14rem 1fr; … }`、默认卡片/表单/侧栏色。
|
||||
- 规则**无媒体查询**、选择器优先级不低;站点主题选择器不够强时,小屏双列、侧栏占位等「幽灵布局」反复出现。
|
||||
- 首页有额外 class(如 `has-rail`)时碰巧盖住,其他页没有同类 class 就暴露——表现为「只修了首页」。
|
||||
- 实务上经常要 `!important` + 更高选择器,与「干净主题层」冲突。
|
||||
|
||||
**代码证据**
|
||||
|
||||
| 位置 | 行为 |
|
||||
|------|------|
|
||||
| `plugins/web/src/render.rs` → `SHELL_CSS` | 常量内联进每个 HTML |
|
||||
| 同文件壳渲染 | `<style>{SHELL_CSS}{extra}</style>`,主题只能接在后面 |
|
||||
|
||||
→ 解决:[02-shell-css.md](../design/ext-web-customization/02-shell-css.md)
|
||||
|
||||
---
|
||||
|
||||
## 3. 鉴权 / 门禁模型偏固定
|
||||
|
||||
**现象**
|
||||
|
||||
- 未登录访问受保护路径:对 `/admin*` 会 **303 → 登录页**;对 `/desk` 等自定义路径往往是 **403 HTML**,行为不一致。
|
||||
- 门禁匹配偏宽:`path.starts_with` / `path_matches` 使 `/desk` 匹配 `/desk/login`,公开登录页易被误伤。
|
||||
- 默认鉴权挂上 `/admin*` → `admin`;`/admin-publish` 这类名字也会被当成 admin 域(`starts_with("/admin")`)。
|
||||
- 会话 cookie、CSRF、登录表单字段均固定在框架实现;难换登录 UI 或改成功落地页。
|
||||
|
||||
**代码证据**
|
||||
|
||||
| 位置 | 行为 |
|
||||
|------|------|
|
||||
| `http.rs` → `rbac_middleware` | visitor + `/admin*` → redirect;其它 gate → 403 |
|
||||
| `http.rs` → `path_matches` | 前缀匹配,无「精确路径 + 子路径排除」DSL |
|
||||
| `lib.rs` → `web_app_auth` | 默认塞入 `/admin*` gate |
|
||||
|
||||
→ 解决:[03-auth-gates.md](../design/ext-web-customization/03-auth-gates.md)
|
||||
|
||||
---
|
||||
|
||||
## 4. 样式作者体验受限
|
||||
|
||||
**现象**
|
||||
|
||||
- 样式表是 GFM 表格;含 `/` 的值必须加引号(如 `"1 / 5"`),否则单元格表达式把 `/` 当除法(曾出现 `grid-column` 变成 `0`)。
|
||||
- `@keyframes`、复杂选择器、多层媒体查询(`min-width` and `max-width`)表达能力有限,装配顺序要小心。
|
||||
- 主题 CSS 与 `SHELL_CSS` 同页串联,级联顺序不透明,调试成本高。
|
||||
- 响应式不能指望框架;壳层几乎不提供移动端抽屉/折叠。
|
||||
|
||||
→ 解决:[04-stylesheet-authoring.md](../design/ext-web-customization/04-stylesheet-authoring.md)
|
||||
|
||||
---
|
||||
|
||||
## 5. 页面壳与插槽约定僵硬
|
||||
|
||||
**现象**
|
||||
|
||||
- 壳结构固定为 `topnav` / `side` / `main` / `foot` 栅格命名区。
|
||||
- 侧栏一旦装配,`body` 即 `has-sidebar`,套上框架双列;杂志风单列、抽屉必须自己拆布局。
|
||||
- 组件表驱动导航,难做运行时条件导航(小屏合并顶栏+侧栏),通常再补 `theme.js`。
|
||||
|
||||
→ 解决:[05-page-shell-slots.md](../design/ext-web-customization/05-page-shell-slots.md)
|
||||
|
||||
---
|
||||
|
||||
## 6. 后台 CRUD 与表单能力边界
|
||||
|
||||
**现象**
|
||||
|
||||
- 内置 admin 是通用表管理,不是产品级 CMS;**关了又占着 `/admin` 路径**(与 §1 叠加)。
|
||||
- 表单以声明式字段表为主;Markdown 分栏、专栏元数据联动等只能外挂 JS。
|
||||
- 列表「链接前缀」等约定简单;编辑/新建状态机常靠前端拼(`?id=`、`?new=1`)。
|
||||
|
||||
→ 解决:[06-admin-crud-forms.md](../design/ext-web-customization/06-admin-crud-forms.md)
|
||||
|
||||
---
|
||||
|
||||
## 7. 静态资源与脚本生命周期
|
||||
|
||||
**现象**
|
||||
|
||||
- 头资源脚本常在 `<head>` **同步**加载;若脚本假设 DOM 已就绪会直接失败(登录页曾因此不跳转)。
|
||||
- 缓存靠 `?v=` 手动 bump;无构建管线时易出现「改了 JS 浏览器仍用旧文件」。
|
||||
|
||||
→ 解决:[07-assets-script-lifecycle.md](../design/ext-web-customization/07-assets-script-lifecycle.md)
|
||||
|
||||
---
|
||||
|
||||
## 8. 扩展与部署耦合
|
||||
|
||||
**现象**
|
||||
|
||||
- 能力依赖 web 插件 ABI / Marqdo 版本(如 0.3.2 起的样式引号约定);升级要同步 Docker / 本机二进制。
|
||||
- 定制若依赖改插件源码(放宽 `/admin` reserved、可配置 login redirect),就脱离「只写 `.mq.md`」的产品路径,维护成本陡增。
|
||||
|
||||
→ 解决:[08-ext-deploy-coupling.md](../design/ext-web-customization/08-ext-deploy-coupling.md)
|
||||
|
||||
---
|
||||
|
||||
## 9. 优先级建议(给实现排期)
|
||||
|
||||
| 优先级 | 项 | 理由 |
|
||||
|--------|-----|------|
|
||||
| P0 | §1 路由/前缀 + §3 鉴权一致 | 阻塞自研后台产品路径 |
|
||||
| P1 | §2 SHELL_CSS + §5 壳布局 | 阻塞品牌主题与响应式 |
|
||||
| P2 | §4 样式作者体验 + §7 脚本生命周期 | 降低日常踩坑,不改架构也能缓解 |
|
||||
| P3 | §6 CRUD 边界 + §8 部署耦合 | 文档/约定/可选增强为主 |
|
||||
|
||||
详细验收与实现切片见解决索引 README。
|
||||
@@ -0,0 +1,35 @@
|
||||
# 路线图:浏览器 Marqdo 路线 D(作者零 JS)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Completed**(D0–D4 已落地;续作见 [browser-wasm-e.md](browser-wasm-e.md)) |
|
||||
| 日期 | 2026-09-03 |
|
||||
| 前置 | [browser-wasm.md](browser-wasm.md)(C0–C5 **Completed**) |
|
||||
| ADR | [0002](../adr/0002-browser-marqdo-wasm.md) · [0003](../adr/0003-browser-async-effects.md) |
|
||||
| 设计 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §16 |
|
||||
|
||||
## 一句话
|
||||
|
||||
作者侧**零业务 JS**:页面逻辑与交互只写 `.mq.md`;官方 `marqdo-bridge.js` 仍作不透明宿主胶(加载 WASM / DOM / fetch),由 `mount` + `client_embed` 自动启动。
|
||||
|
||||
## 阶段
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **D0** | 路线图 + 设计增补 | **done** |
|
||||
| **D1** | bridge `mount` + data-mq / `#marqdo-boot` 自启;hello 去掉 loader/interact/fetch.js | **done** |
|
||||
| **D2** | `client_embed` / `客户端挂载`:`wasm` / `source` / `boot` | **done** |
|
||||
| **D3** | DOM/表单效应 + wire 传 `value`;`dom_patch` L1 | **done** |
|
||||
| **D4** | `examples/web-client-site` + skill / README | **done** |
|
||||
|
||||
## 非目标
|
||||
|
||||
- 消灭官方 bridge 文件本身(宿主胶必须存在)
|
||||
- 任意 `eval(JS)` / React 式 VDOM
|
||||
- 把 axum / SQLite 搬进浏览器(仍属 C 非目标)
|
||||
|
||||
## 验收
|
||||
|
||||
- 示例无作者业务 `.js`(允许构建拷贝的 `marqdo-bridge.js`)
|
||||
- `ext/web` 一行挂载即可 boot + wire
|
||||
- 点击、表单 input、`fetch` 效应可演示
|
||||
@@ -0,0 +1,32 @@
|
||||
# 路线图:浏览器 Marqdo 路线 E(前端能力补齐)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Completed** |
|
||||
| 日期 | 2026-09-04 |
|
||||
| 前置 | [browser-wasm-d.md](browser-wasm-d.md)(D0–D4 **Completed**) |
|
||||
| 续作 | [browser-wasm-f.md](browser-wasm-f.md)(媒体 / 文件 / Canvas 等) |
|
||||
| 设计 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §16–§17 |
|
||||
|
||||
## 原则(已修正)
|
||||
|
||||
**禁止的只有:作者手写业务 JS。**
|
||||
官方 `marqdo-bridge.js` / 构建生成物可以包含任意宿主机制(含轻量列表装配、路由、存储、WebSocket、内部模板等)。
|
||||
|
||||
## 阶段
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **E0** | 原则修正 + 能力矩阵 | **done** |
|
||||
| **E1** | `set_style` / `focus` / `blur` / `scroll_into`;键盘;wire `委托`;多节点 `querySelectorAll` | **done** |
|
||||
| **E2** | `set_html` / `append_html` / `replace_children` / `render_list` / `remove`;L1 `list_html` | **done** |
|
||||
| **E3** | `navigate` / `replace`;`window`+`popstate` | **done** |
|
||||
| **E4** | `storage` local/session/**cookie** | **done** |
|
||||
| **E5** | `ws` open/send/close + callbacks | **done** |
|
||||
| **E6** | `fetch_all`(数组或 map)/ `interval` / FormData / `clipboard` / `download` | **done** |
|
||||
| **E7** | `add_class` / `remove_class`;示例列表真删除 + net 面板 | **done** |
|
||||
|
||||
## 验收
|
||||
|
||||
- [examples/browser-app/](../../examples/browser-app/):列表 CRUD、storage、三页路由、interval、fetch_all、ws、clipboard、download
|
||||
- 冒烟:`tests/wasm/smoke.mjs`
|
||||
@@ -0,0 +1,26 @@
|
||||
# 路线图:浏览器 Marqdo 路线 F(进阶宿主能力)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Completed**(F1–F5;F6 Service Worker 可选未做) |
|
||||
| 日期 | 2026-09-04 |
|
||||
| 发布 | **v0.3.3** |
|
||||
| 前置 | [browser-wasm-e.md](browser-wasm-e.md)(E **Completed**) |
|
||||
| 写法 | 客户端 `.mq.md`:**GFM 表格 + `lib/browser`**,禁止 `json.set` 链([marqdo-dev](../../.cursor/skills/marqdo-dev/SKILL.md)) |
|
||||
|
||||
## 原则
|
||||
|
||||
同 E:禁止作者手写业务 JS;官方 bridge 可扩展。作者数据与效应用**可读表格/助手**表达。
|
||||
|
||||
## 阶段
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **F1** | `read_file` → text / DataURL → `mq_call` | **done** |
|
||||
| **F2** | Canvas 2D 指令表(`canvas.commands`) | **done** |
|
||||
| **F3** | Audio play / pause / stop;`src=beep` Web Audio | **done** |
|
||||
| **F4** | `observe` / `unobserve`(Intersection / Resize) | **done** |
|
||||
| **F5** | drag/drop wire + `data-drag` / `drop_text` | **done** |
|
||||
| **F6** | Service Worker / 离线缓存 | optional / skipped |
|
||||
|
||||
示例:[examples/browser-media/](../../examples/browser-media/) · 助手:`lib/browser.mq.md`。
|
||||
@@ -0,0 +1,40 @@
|
||||
# 路线图:浏览器 Marqdo(WASM)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Completed**(路线 C 首版功能完备;续作见 [browser-wasm-d.md](browser-wasm-d.md)) |
|
||||
| 日期 | 2026-09-01 |
|
||||
| ADR | [0002](../adr/0002-browser-marqdo-wasm.md) · [0003](../adr/0003-browser-async-effects.md) |
|
||||
| 设计 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) |
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **C0** | feature 门控;`wasm32` check | **done** |
|
||||
| **C1** | `run_source` + `mq_run` | **done** |
|
||||
| **C2** | loader + `marqdo wasm build`(含 bridge 拷贝) | **done** |
|
||||
| **C3** | session wire + `set_text` | **done** |
|
||||
| **C4** | `fetch` / `after` 效应 | **done** |
|
||||
| **C5** | `release-wasm` 体积;冒烟;站点挂载文档 / L1 | **done** |
|
||||
|
||||
## 交付物
|
||||
|
||||
| 产物 | 路径 |
|
||||
|------|------|
|
||||
| ABI crate | `crates/marqdo-wasm` |
|
||||
| 官方 bridge | `crates/marqdo-wasm/js/marqdo-bridge.js` |
|
||||
| CLI | `marqdo wasm build -o DIR` |
|
||||
| 示例 | `examples/browser-hello/` |
|
||||
| 冒烟 | `tests/wasm/smoke.mjs` · `tests/wasm_smoke.rs` |
|
||||
| L1 | `web.client_embed` / `网页.客户端挂载` |
|
||||
|
||||
## 明确非目标(本版不做)
|
||||
|
||||
- 浏览器会话 bytecode(缺 entry-env invoke;一发 `run_source` 已支持 bytecode)
|
||||
- 把 axum / SQLite 服务端搬进 WASM
|
||||
- 业务手写 JS 框架
|
||||
|
||||
## 进度
|
||||
|
||||
| 日期 | 记录 |
|
||||
|------|------|
|
||||
| 2026-09-01 | C0–C5 完结并 push;收口 bridge 规范路径 + 冒烟 + 挂载 L1 |
|
||||
@@ -2,9 +2,9 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **A0–A4 完成**(调研驱动优化闭环;A4:corpus/MCP 证据工具,权威仍是 `.mq.md`) |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · **缺口盘点** [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) |
|
||||
| 状态 | **A0–A4 完成**;**Wave B Active**(宪法优先:代码即文档 / call_site / OKF) |
|
||||
| 日期 | 2026-09-04 |
|
||||
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) · **[agent-framework-2026-09.md](../research/agent-framework-2026-09.md)** |
|
||||
| 设计 | [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md) · [okf.md](../design/okf.md) |
|
||||
| 邻近 | [agent-streaming.md](agent-streaming.md) · [okf-near-match.md](okf-near-match.md) |
|
||||
|
||||
@@ -13,21 +13,32 @@
|
||||
## 1. 优化原则(来自调研)
|
||||
|
||||
1. **强化差异化,不向 LangChain 薄循环回退**(禁止隐藏 TOOL: 主路径、禁止整文件 LLM 重写工作簿)。
|
||||
2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视**。
|
||||
2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视、源码/调用位置注入**。
|
||||
3. 外部 RAG/MCP 只作**工具**,不升为权威真相源。
|
||||
|
||||
自评四问见调研 §9。A0–A4 之后的缺口与建议分期 **B0–B5** 见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md)。
|
||||
自评四问见调研 §9。A0–A4 之后的缺口见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md)。**2026-09 Wave B** 锁定见 [agent-framework-2026-09.md](../research/agent-framework-2026-09.md)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 建议分期(摘要)
|
||||
## 2. A0–A4(已完成)
|
||||
|
||||
| 波次 | 主题 | 验收线索 |
|
||||
|------|------|----------|
|
||||
| **A0** | 工作簿补丁 / 固化可靠性 | **done** — 整文件 FIND 护栏;`soft` 仅 miss;decompose `n` 检查;`workbook_solidify` 单测;金样 `agent-workbook-patch-a0`(双 CONTINUE + solidify) |
|
||||
| **A1** | OKF 复用飞轮(lookup / near / soft_match UX) | **done** — `list_tasks` 含 description/aliases/status/llm_free/hits;`plan` 命中路径暴露 `match`/`score`;soft_match 策展行含 meta;view plan 卡显示 match;金样 `agent-kb-plan-hit`(exact hit + near soft-hit) |
|
||||
| **A2** | 过程可见(stream + view 过程卡) | **done** — `plan_append_*` / `plan_finish_stream` 始终写入 `events`(SSE 仍仅 `stream=True`);OKF REUSE 记 `decision`;view `plan-card` 渲染过程时间线(跳过 delta);金样断言 `events-ok`;对齐 [agent-streaming.md](agent-streaming.md) |
|
||||
| **A3** | 上下文预算(源码/Skill 渐进披露) | **done** — `source_brief` / 加深 `skill_brief`;`build_step_context` 默认预算 + `READ:source|skill`;`step max_reads`;父 `READ:skill`;金样 `agent-context-budget-a3` |
|
||||
| **A4** | 可选:RAG/MCP 工具适配器 | **done** — `corpus_search`(本地语料关键词);`mcp_list_tools` / `mcp_call`(JSON fixture);`authority=workbook`;金样 `agent-tools-rag-a4` |
|
||||
| **A0** | 工作簿补丁 / 固化可靠性 | **done** — 金样 `agent-workbook-patch-a0` |
|
||||
| **A1** | OKF 复用飞轮 | **done** — 金样 `agent-kb-plan-hit` |
|
||||
| **A2** | 过程可见 | **done** — events + view plan 卡 |
|
||||
| **A3** | 上下文预算 | **done** — `source_brief` / `READ:`;金样 `agent-context-budget-a3` |
|
||||
| **A4** | RAG/MCP 证据工具 | **done** — 金样 `agent-tools-rag-a4` |
|
||||
|
||||
细节与行业对照以调研正文为准;本文件只跟踪 **A0–A4** 实现分期。后续产品化 / 评测 / live MCP 等见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) §5(草案 B0–B5)。
|
||||
---
|
||||
|
||||
## 3. Wave B(Active — 宪法优先)
|
||||
|
||||
| 波次 | 主题 | 状态 |
|
||||
|------|------|------|
|
||||
| **B0** | 官方示例演示 call_site/源码/OKF;Skill/文档;上下文管道可读 | **done** |
|
||||
| **B0.5** | 本机 live(`.env` → 开发模型)验证「模型用上了文档」 | **done**(`AGENT_LIVE` / `AGENT_HARNESS_LIVE`) |
|
||||
| **B1** | 评测 harness 锁差异化指标(constitution / dump / writeback 遮蔽) | **Active** |
|
||||
| **B2–B5** | 真 MCP / resume+HITL / stats / 并行 | 暂缓 |
|
||||
|
||||
示例:`examples/agent-pong/` · `examples/agent-okf-flywheel/`。
|
||||
@@ -0,0 +1,126 @@
|
||||
# 官方扩展:`ext/linalg` 实现路线图
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **L0–L6 + 公式文档面 F1–F3 已落地 · L7+ 远期** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| **锁定设计** | [design/ext-linalg.md](../design/ext-linalg.md) · [design/ext-linalg-formula-doc.md](../design/ext-linalg-formula-doc.md) |
|
||||
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
|
||||
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [view.md](../design/view.md) · [ext-quantum-q7.md](../design/ext-quantum-q7.md) |
|
||||
| 安装(规划) | `marqdo ext add linalg`(`linalg` / `线性代数`) |
|
||||
|
||||
本文只跟踪**实现阶段**。作者面、公式规则、展示以设计文为准。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标回顾(一句)
|
||||
|
||||
**可运行的线性代数公式文档**:矩阵公式可化简、可 KaTeX 展示;跑通即在规则集内正确;需要时再稠密求值与分解,并内嵌结构 SVG。
|
||||
|
||||
---
|
||||
|
||||
## 2. 落地阶段
|
||||
|
||||
| 阶段 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **L0** | CATALOG + `plugins/linalg` ping + L1 `ensure_plugin`;`ext add` 条目 | **done** |
|
||||
| **L1** | MatExpr:`symbol` / 稠密叶子 / `mul`·`add`·`T`·`inv`;`simplify` R1–R5;`latex`·`ascii`·`show` | **done** |
|
||||
| **L2** | `explicit` / 小阵 gemm·解系·`det`·`trace`;维数护栏;金样 `linalg-basic-smoke` | **done** |
|
||||
| **L3** | `block` + `collapse`;`kron` 惰性 + R7;金样 `linalg-block-kron` | **done** |
|
||||
| **L4** | `factorize` LU/QR/SVD/eig(+ 可选 chol);结构 SVG `svd|qr|ge|eig`;金样 `linalg-factor-smoke` | **done** |
|
||||
| **L5** | `heatmap`/`hinton`;examples(最小二乘 / SVD 示意);public + skill 摘要 | **done** |
|
||||
| **L6** | 复数 dtype;`lstsq`;`norm`/`cond`;主题令牌对齐 | **done** |
|
||||
| **F1** | 展示路径默认 simplify;公式文档金样 | **done** |
|
||||
| **F2** | 符号引入降噪;examples 讲义化 | **done** |
|
||||
| **F3** | 紧凑糖 + public「如何写公式文档」 | **done** |
|
||||
| **L7+** | 矩阵微积分 / 更大 BLAS 依赖(仅当用户明确要求) | **deferred** |
|
||||
|
||||
验收金样(规划路径):`tests/ext/linalg-*-smoke.mq.md`;示例:`examples/linalg-least-squares/`、`examples/linalg-svd/`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 每阶段出口检查
|
||||
|
||||
### L0
|
||||
|
||||
- [x] `ext/linalg` CATALOG 含 `linalg`
|
||||
- [x] 插件 `ping` → ok
|
||||
- [x] 文档:`marqdo ext add linalg`
|
||||
|
||||
### L1
|
||||
|
||||
- [x] `(AB)^\top` → `simplify` → `B^T*A^T`(无 dense)
|
||||
- [x] 形状错误含行列信息
|
||||
- [x] CLI `ascii` / `show` SVG 通道
|
||||
- [x] 中英 L1 各一 smoke
|
||||
|
||||
### L2
|
||||
|
||||
- [x] `from_formula` 吸收 `$$` 数值阵
|
||||
- [x] `solve` 与手算 2×2 一致
|
||||
- [x] 超维 `explicit` 硬错误(单元测护栏)
|
||||
|
||||
### L3
|
||||
|
||||
- [x] 分块乘 `collapse` 后块级正确
|
||||
- [x] Kronecker 默认不膨胀元素个数(惰性 `A⊗B`)
|
||||
|
||||
### L4
|
||||
|
||||
- [x] SVD/特征结果对象字段稳定
|
||||
- [x] SVG 含可断言标记(如 `data-linalg="eig"`)
|
||||
- [x] `factorize` + 二次 `solve` 复用(LU)
|
||||
|
||||
### L5
|
||||
|
||||
- [x] 至少 1 个 examples 可 `marqdo run`
|
||||
- [x] public/features 或 tutorial 短页
|
||||
- [x] skill / CHANGELOG Unreleased 条目
|
||||
|
||||
### L6
|
||||
|
||||
- [x] `lstsq` / `norm` / `cond` / `rank` 金样
|
||||
- [x] `dtype=complex` 基线(Frobenius;分解仍为实数)
|
||||
- [x] `draw theme=light|dark|bw` 与 quantum Q8 令牌对齐(`data-theme`)
|
||||
|
||||
### F1
|
||||
|
||||
- [x] `ascii` / `latex` / `show` 默认 simplify
|
||||
- [x] 金样:`.T` 后直接 `ascii` 得 `B^T*A^T`(无需显式 simplify)
|
||||
- [x] 设计文 [ext-linalg-formula-doc.md](../design/ext-linalg-formula-doc.md) 落地
|
||||
|
||||
### F2
|
||||
|
||||
- [x] 符号引入降噪(选定候选) — GFM `@` 表 + `la.declare`
|
||||
- [x] 至少 1 个 example 以代数面为主叙述 — `examples/linalg-transpose/`
|
||||
|
||||
### F3
|
||||
|
||||
- [x] `T_ascii` / `转置文本` 一步展示糖
|
||||
- [x] `explicit` 默认先 simplify(`raw=` 可关)
|
||||
- [x] public `07-linalg` / `07-线性代数`「如何写公式文档」
|
||||
|
||||
---
|
||||
|
||||
## 4. 依赖与并行
|
||||
|
||||
| 依赖 | 说明 |
|
||||
|------|------|
|
||||
| ABI v2 + ext CLI | 已有 |
|
||||
| view KaTeX / plot | 已有;L1 `show` 接现成通道 |
|
||||
| Release native zip | 随首次含 `plugins/linalg` 的发版接入 |
|
||||
| quantum 数值核 | **可选**私有复用;不阻塞 L1–L2 |
|
||||
|
||||
不阻塞项:浏览器 WASM 上的 linalg(默认 host/native;WASM 另议)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议开发顺序(下一手)
|
||||
|
||||
1. **L7+** 仅当用户明确要求更深符号(微积分等)。公式文档面 F1–F3 已收口。
|
||||
|
||||
---
|
||||
|
||||
## 6. 一句话
|
||||
|
||||
**代数面像讲义、计算面是步骤;跑通即在规则集内正确;每阶段都有可跑金样。**
|
||||
@@ -35,6 +35,18 @@
|
||||
| **W7** | Cache-Control / 404·500 / 重定向 / sitemap·robots / init 唯一·索引 / HTTPS 反代说明 | **done** |
|
||||
| **P3** | 审计时间戳 / 外键 / RBAC / 相册 / ETag | **done** |
|
||||
|
||||
### 定制波次(规划中)
|
||||
|
||||
自研后台 / 主题 / 响应式踩坑见 [ext-web-customization-limits.md](../research/ext-web-customization-limits.md);解法索引 [ext-web-customization/](../design/ext-web-customization/)。
|
||||
|
||||
| 波次 | 内容 | 状态 |
|
||||
|------|------|------|
|
||||
| **C0** | `admin` 关则不占路径;`admin_prefix` / 登录回跳可配 | **done** |
|
||||
| **C1** | gate 匹配与未登录策略一致;段边界默认 admin gate | **done** |
|
||||
| **C2** | `shell_css` + `layout` 松绑 | **done** |
|
||||
| **C3** | 样式 strict / 脚本 defer·version | **done** |
|
||||
| **C4** | 条件导航 when/media(layout 见 C2) | **done** |
|
||||
|
||||
验收金样:`tests/ext/web-smoke.mq.md`、`tests/ext/web-security-smoke.mq.md`、`tests/ext/web-drivers-smoke.mq.md`、`tests/ext/web-upload-smoke.mq.md`、`tests/ext/web-db-w6-smoke.mq.md`、`tests/ext/web-w7-finish-smoke.mq.md`、`tests/ext/web-p3-smoke.mq.md`、`ext_cli_add_web`。
|
||||
|
||||
---
|
||||
|
||||
@@ -109,7 +109,8 @@ Phase I 对齐 Crafting Interpreters 的 **jlox(树遍历)**;Phase II 对
|
||||
|
||||
- 更完整表达式文法、错误模型、外联围栏 FFI
|
||||
- 生成 OKF 依赖目录
|
||||
- (可选)另一后端:编译到 Python/WASM——**另开 ADR**,不替代自研语义
|
||||
- (可选)另一后端:编译到 Python/WASM——**另开 ADR**,不替代自研语义
|
||||
- **浏览器内运行(路线 C)**:解释器/VM 上 WASM(**非**把 `.mq.md` 译成 JS)——已锁定 [ADR 0002](../adr/0002-browser-marqdo-wasm.md) · [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [roadmap/browser-wasm.md](browser-wasm.md)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -18,7 +18,7 @@
|
||||
| **诊断** | 语句级 `path:line:col: message`;字节码指令带 `spans`;errors 金样例双后端断言位置 | **P0 完成** |
|
||||
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
|
||||
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
|
||||
| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
|
||||
| **标准库** | 核心 L1 已完成([stdlib-modules.md](../design/stdlib-modules.md));下一主线 = **中层 Mid**([stdlib-mid.md](../design/stdlib-mid.md) · [stdlib-mid 路线](stdlib-mid.md)) | **P2 完成;Mid M1–M6 规划中** |
|
||||
| **模块** | [module-namespace.md](../design/module-namespace.md):**M1+M2 已落地**(库名绑定、`库.成员` / `use`;无扁平合并) | — |
|
||||
|
||||
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
|
||||
@@ -174,7 +174,7 @@ flowchart LR
|
||||
|
||||
### 风险与边界
|
||||
|
||||
- 静态 `gh-pages` **无法**真断点(无常驻 VM);调试仅 **live view**(或未来 WASM 解释器)。
|
||||
- 静态 `gh-pages` **无法**真断点(无常驻 VM);调试仅 **live view**(或 [浏览器 WASM 解释器](browser-wasm.md) C5)。
|
||||
- 字节码调试可晚于树遍历一个迭代。
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,199 @@
|
||||
# 路线图:中层标准库(数个版本)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **M1–M6 已落地** |
|
||||
| 日期 | 2026-09-07 |
|
||||
| 设计 | [stdlib-mid.md](../design/stdlib-mid.md) |
|
||||
| 相关 | [stdlib-modules.md](../design/stdlib-modules.md) · [next-phase.md](next-phase.md) · [ext-cli.md](../design/ext-cli.md) |
|
||||
|
||||
> **不预标 SemVer。** 每一波随当时产品发版合入;下文用 **M1…M6** 波次名。每波须可单独演示、可回滚。
|
||||
|
||||
---
|
||||
|
||||
## 0. 总序
|
||||
|
||||
```text
|
||||
M1 文本与编解码地基 re + encoding ← 最先解锁「无插件写库」
|
||||
M2 路径与文件中层 path + fs 加厚
|
||||
M3 完整性与机密 hash + secrets
|
||||
M4 表格数据与文本加厚 csv + text++
|
||||
M5 集合与 CLI 糖 table/listx + cli
|
||||
M6 可观测与标识 log + uuid(+ 可选 yaml)
|
||||
```
|
||||
|
||||
原则:
|
||||
|
||||
1. **先原语、后糖**:正则 / 编解码 / 路径先于 CLI 糖与日志格式。
|
||||
2. **每波必须有金样 + public 短页**;无文档不算完成。
|
||||
3. **并行约束**:不阻塞 `ext/linalg` 等已定领域工作;但新官方能力评审优先问 Mid。
|
||||
4. **插件冻结规则**:自 M1 起,官方新增「通用」ABI 插件默认 **拒绝**,除非设计文档论证无法用 host+L1。
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状缺口(开工依据)
|
||||
|
||||
| 能力 | 现状 | 后果 |
|
||||
|------|------|------|
|
||||
| 正则 | 无 | 校验、替换、简单解析只能 foreign 或插件 |
|
||||
| base64 / hex | 无(仅有 `url_encode`) | 令牌、摘要、嵌二进制文本困难 |
|
||||
| 路径代数 | `fs` 只做 I/O | 拼接靠字符串,跨平台易错 |
|
||||
| 哈希 / HMAC | 无 | 校验、缓存键、签名只能外联 |
|
||||
| CSV | 无 | 数据脚本推向外联 Python |
|
||||
| `lib/text` | 3 个包装函数 | 「有 text 库」名不副实 |
|
||||
| 安全随机 | 仅 `math.random` | 易误用于 token |
|
||||
| 结构化日志 / flags | 无 | 每个脚本自造 |
|
||||
|
||||
对照:Go 日常高频包(`regexp`、`encoding/*`、`crypto`、`path/filepath`、`slices`)与 Python「难写对才进 stdlib」——正是 M1–M5 的选型来源;**不**把 HTTP 服务端、数据库驱动塞进 Mid(见设计文 §3.2)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 波次明细
|
||||
|
||||
### M1 — 正则与编解码(最高优先) — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/re.mq.md` / `lib/正则.mq.md` | `is_match` / `find` / `find_all` / `replace` / `split` |
|
||||
| `lib/encoding.mq.md` / `lib/编码.mq.md` | `base64_*` / `hex_*` |
|
||||
| Host | `host_re_*`(`regex`)、`host_encoding_*`(无第三方编解码 crate) |
|
||||
| 金样 | `tests/lib/re-smoke` · `正则-烟测` · `encoding-smoke` · `编码-烟测` |
|
||||
| 文档 | [stdlib-re.md](../design/stdlib-re.md) · [stdlib-encoding.md](../design/stdlib-encoding.md) · public `08-re-encoding` |
|
||||
| 验收 | 无插件:邮箱式校验 + base64/hex 往返 |
|
||||
|
||||
**刻意不做:** 回溯引用极致兼容、替换回调、完整 PCRE 方言文档化——先 RE2/ Rust `regex` 语义并写清。
|
||||
|
||||
---
|
||||
|
||||
### M2 — 路径与文件中层 — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/path.mq.md` / `lib/路径.mq.md` | `join` / `split` / `file_name` / `parent` / `extension` / `normalize` / `is_absolute` |
|
||||
| `lib/fs` 加厚 | `copy_file` / `move` / `make_temp`(文本边界;无 `read_bytes`) |
|
||||
| Host | `host_path_*`、`host_copy_file` / `host_move` / `host_make_temp` |
|
||||
| 金样 | `path-smoke` · `路径-烟测` · `fs-copy-move` · `文件-复制` |
|
||||
| 文档 | [stdlib-path.md](../design/stdlib-path.md) · [stdlib-fs-mid.md](../design/stdlib-fs-mid.md) · public `09-path-fs` |
|
||||
| 验收 | 规范化 + 沙箱内复制/移动 |
|
||||
|
||||
**刻意不做:** 完整 `shutil`、监视 `inotify`、权限 ACL 全家桶。
|
||||
|
||||
---
|
||||
|
||||
### M3 — 哈希与机密 — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/hash.mq.md` / `lib/哈希.mq.md` | `sha256` / `sha1` / `md5` / `hmac_sha256` |
|
||||
| `lib/secrets.mq.md` / `lib/机密.mq.md` | `token_hex` / `token_urlsafe` |
|
||||
| Host | `host_hash_*`、`host_secrets_*`(`sha2`/`sha1`/`md-5`/`hmac`/`getrandom`) |
|
||||
| 金样 | `hash-smoke` · `哈希-烟测` · `secrets-smoke` · `机密-烟测` |
|
||||
| 文档 | [stdlib-hash.md](../design/stdlib-hash.md) · [stdlib-secrets.md](../design/stdlib-secrets.md) · public `10-hash-secrets` |
|
||||
| 验收 | 已知向量 + 令牌长度 |
|
||||
|
||||
**刻意不做:** 密码哈希(Argon2/bcrypt)、完整 TLS、证书管理——仍属服务端/安全产品。
|
||||
|
||||
---
|
||||
|
||||
### M4 — CSV 与文本加厚 — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/csv.mq.md` / `lib/逗号表.mq.md` | `parse` / `stringify`(首行表头 → list of maps) |
|
||||
| `lib/text` / `文本` 加厚 | `contains` / `starts_with` / `ends_with` / `replace` / `to_upper`/`to_lower` / `repeat` / `pad` |
|
||||
| Host | `host_csv_*`、`host_text_*` |
|
||||
| 金样 | `csv-smoke` · `逗号表-烟测` · `text-mid-smoke` · `文本-加厚-烟测` |
|
||||
| 文档 | [stdlib-csv.md](../design/stdlib-csv.md) · [stdlib-text-mid.md](../design/stdlib-text-mid.md) · public `11-csv-text` |
|
||||
| 验收 | CSV 往返 + 文本清洗小例 |
|
||||
|
||||
**可选同波:** 极简 `format`(`{name}` 替换),若与引用语法冲突则延后。
|
||||
|
||||
---
|
||||
|
||||
### M5 — 集合算法与 CLI — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/table` / `表` 加厚 | `sort` / `sort_by` / `unique` / `chunk` / `zip` / `flatten`(`reverse` 已有) |
|
||||
| `lib/cli.mq.md` / `lib/命令行.mq.md` | `parse`(`--k v` / `--k=v` / `--flag`;位置参 `_`) |
|
||||
| Host | `host_list_sort*` / `unique` / `chunk` / `zip` / `flatten`、`host_cli_parse` |
|
||||
| 金样 | `table-list-mid` · `cli-sort-smoke` · `表-命令行-烟测` |
|
||||
| 文档 | [stdlib-list-cli.md](../design/stdlib-list-cli.md) · public `12-list-cli` |
|
||||
| 验收 | CSV 按键排序 + 参数解析 |
|
||||
|
||||
**刻意不做:** 泛型迭代器协议、惰性流、完整 argparse 互斥组。
|
||||
|
||||
---
|
||||
|
||||
### M6 — 日志、UUID、收口 — **done**
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| `lib/log.mq.md` / `lib/日志.mq.md` | `debug`/`info`/`warn`/`error`;level 过滤;一行文本 |
|
||||
| `lib/uuid.mq.md` / `lib/标识.mq.md` | `v4` |
|
||||
| Host | `host_log_set_level` / `host_log_line`、`host_uuid_v4` |
|
||||
| 金样 | `log-uuid-smoke` · `日志-标识-烟测` |
|
||||
| 文档 | [stdlib-log-uuid.md](../design/stdlib-log-uuid.md) · public `13-log-uuid` |
|
||||
| 文档收口 | `stdlib-modules.md` 总表;设计文状态 → **M1–M6 已落地** |
|
||||
| 可选未做 | `yaml` 只读子集(默认不做) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 跨波次工程清单
|
||||
|
||||
每波共用:
|
||||
|
||||
- [ ] 中英 L1 对称([stdlib-i18n.md](../design/stdlib-i18n.md))
|
||||
- [ ] `host_*` 形参在 L1 **全量转发**([stdlib-modules.md](../design/stdlib-modules.md) §2.1)
|
||||
- [ ] 双后端金样(tree + bytecode,若该 host 已接线)
|
||||
- [ ] WASM:标注 `host-only` 或实现 stub
|
||||
- [ ] CHANGELOG「标准库」条目
|
||||
- [ ] skill `examples.md` 增加 Mid 惯用写法(GFM 优先)
|
||||
|
||||
宿主膨胀守卫:
|
||||
|
||||
- 新增 crate 须在 PR/设计中写清:**为何不能纯 mq**、**features 如何裁剪**、**许可证**。
|
||||
- 禁止借 Mid 把 `ext/web` 的服务端栈链进主二进制。
|
||||
|
||||
---
|
||||
|
||||
## 4. 与官方扩展的互动(减插件)
|
||||
|
||||
| 扩展 | Mid 落地后可做的减负 |
|
||||
|------|----------------------|
|
||||
| `ext/web` | 路由/校验用 `re`;ETag/缓存键用 `hash`;静态路径用 `path` |
|
||||
| `ext/agent` | 工具参数校验、密钥材料用 `secrets`/`hash`(领域核仍插件) |
|
||||
| `ext/ai/llm` | 头/体编解码走 `encoding` |
|
||||
| `ext/linalg` / `quantum` | **不**迁入 Mid;继续插件;仅共用 `path`/`hash` 等通用面 |
|
||||
|
||||
跟踪方式:某波完成后,开短 issue/清单「ext X 可删除的原生辅助」,不强迫同波大改。
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议人力切分(示意)
|
||||
|
||||
| 波次 | 大致体量 | 可演示产物 |
|
||||
|------|----------|------------|
|
||||
| M1 | 中 | 「正则替换 + base64 往返」用户页 |
|
||||
| M2 | 中 | 「安全拼接路径写文件」 |
|
||||
| M3 | 小–中 | 「下载内容 sha256 校验」 |
|
||||
| M4 | 中 | 「CSV → 表 → 打印」 |
|
||||
| M5 | 小–中 | 「零插件数据 CLI」 |
|
||||
| M6 | 小 | 「带 log level 的脚本」 |
|
||||
|
||||
若只能开一条线:**M1 → M3 → M2 → M4 → M5 → M6**(完整性校验常比路径代数更刚需时,M3 可紧贴 M1)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 完成定义(整条 Mid 叙事)
|
||||
|
||||
当 M1–M6 完成时,对外可宣称:
|
||||
|
||||
> Marqdo 自带中层标准库:正则、编解码、路径、哈希、CSV、加厚文本与集合/CLI 糖,以及日志与 UUID;**写通用脚本与多数扩展库不再需要原生插件。**
|
||||
> 插件保留给 web 运行时、智能体、量子与线性代数等**领域引擎**。
|
||||
|
||||
---
|
||||
|
||||
## 7. 一句话
|
||||
|
||||
**按 M1→M6 把通用原语沉进 `lib/`,用数个发版周期换掉「事事插件」——领域 `ext/` 继续尖,语言本体变宽。**
|
||||
@@ -0,0 +1,13 @@
|
||||
# agent-okf-flywheel(Wave B0)
|
||||
|
||||
演示 **文档即知识库(OKF)**:固化工作簿 promote 后,相同 goal 的 `plan` 走 `cache=hit`(`llm_free` 路径),无需再问模型。
|
||||
|
||||
```bash
|
||||
cargo build --release -p marqdo -p marqdo_plugin_agent
|
||||
export MARQDO_EXT="$PWD/.marqdo-ext"
|
||||
./target/release/marqdo run examples/agent-okf-flywheel/index.mq.md
|
||||
```
|
||||
|
||||
期望:`promoted` · `hit` · `flywheel-ok`。
|
||||
|
||||
见 [okf.md](../../doc/design/okf.md) · [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md)。
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: agent-okf-flywheel (Wave B0)
|
||||
description: Promote solidified workbook; second plan is cache=hit — document as knowledge base (OKF).
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import fs:lib/fs.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import plugin:lib/plugin.mq.md
|
||||
import sys:lib/sys.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
OKF flywheel offline: promote → plan same goal → `cache=hit` (no live LLM required for the hit path).
|
||||
|
||||
*p = > plugin.native_path name="agent"*
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=no-agent-plugin
|
||||
> sys.exit code=1
|
||||
|
||||
> sys.env_set name="OPENAI_API_KEY" value="offline-okf-dummy"
|
||||
*model = > llm.llm*
|
||||
*tools = > json.parse text=[]*
|
||||
*助手 = > agent.agent model=`model` tools=`tools` standing="offline okf flywheel"*
|
||||
|
||||
*kb = ".marqdo/agent-kb-example-flywheel"*
|
||||
*wb = ".marqdo/agent-runs/example-pong-solid.mq.md"*
|
||||
*goal = "Reply with exactly the word pong and nothing else."*
|
||||
*body = "---\ntitle: okf pong\n---\n\n# main\n\n*msg = \"pong\"*\n\n**msg**\n"*
|
||||
|
||||
1. > fs.exists path=`kb`
|
||||
> fs.remove path=`kb`
|
||||
2. *
|
||||
---
|
||||
|
||||
> fs.write_text path=`wb` text=`body`
|
||||
|
||||
*prom = > agent_kb_promote kb_dir=`kb` goal=`goal` workbook=`wb`*
|
||||
*okp = > json.get value=`prom` key="promoted"*
|
||||
1. `okp`
|
||||
> print text=promoted
|
||||
2. *
|
||||
> print text=promote-fail
|
||||
> sys.exit code=1
|
||||
|
||||
*out = > `助手`.plan goal=`goal` max_rounds=2 writeback=False kb_dir=`kb` explore_n=0 promote=False*
|
||||
*cache = > json.get value=`out` key="cache"*
|
||||
> print text=`cache`
|
||||
*match = > json.get value=`out` key="match"*
|
||||
> print text=`match`
|
||||
*val = > json.get value=`out` key="result"*
|
||||
> print text=`val`
|
||||
|
||||
1. `cache` == "hit"
|
||||
> print text=flywheel-ok
|
||||
2. *
|
||||
> print text=flywheel-miss
|
||||
> sys.exit code=1
|
||||
@@ -0,0 +1,16 @@
|
||||
# agent-pong(Wave B0)
|
||||
|
||||
演示 Marqdo 智能体宪法:**代码即文档** — 模型上下文含 **call site** 与本文件 **source**;工具是同文件里的 `## 获取时间`。
|
||||
|
||||
```bash
|
||||
# 仓库根目录
|
||||
cargo build --release -p marqdo -p marqdo_plugin_agent
|
||||
export MARQDO_EXT="$PWD/.marqdo-ext" # 或: marqdo ext add agent
|
||||
# 可选 live:仓库根 `.env` + `AGENT_LIVE=1 marqdo run examples/agent-pong/index.mq.md`
|
||||
./target/release/marqdo run examples/agent-pong/index.mq.md
|
||||
```
|
||||
|
||||
期望离线输出含:`call-site-ok` · `source-ok` · `tool-in-source-ok`。
|
||||
配置真实 `.env` 时还会跑一次 `step`(CALL 工具)。
|
||||
|
||||
见 [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md)。
|
||||
@@ -0,0 +1,89 @@
|
||||
---
|
||||
title: agent-pong (Wave B0)
|
||||
description: >-
|
||||
Constitution demo — call_site + source in step context; optional live CALL via .env.
|
||||
Code is documentation; tools are ## in this same file.
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import plugin:lib/plugin.mq.md
|
||||
import sys:lib/sys.mq.md
|
||||
import time:lib/time.mq.md
|
||||
---
|
||||
|
||||
## 获取时间
|
||||
|
||||
Return today's date string (tool visible in source to the model).
|
||||
|
||||
*u = > time.now_unix*
|
||||
**> time.format unix=`u` pattern="%Y-%m-%d"**
|
||||
|
||||
# main
|
||||
|
||||
*p = > plugin.native_path name="agent"*
|
||||
1. `p`
|
||||
> plugin.load path=`p`
|
||||
2. *
|
||||
> print text=no-agent-plugin
|
||||
> sys.exit code=1
|
||||
|
||||
> llm.load_env path="../../.env"
|
||||
|
||||
`工具表` =
|
||||
|
||||
| 工具 |
|
||||
|------|
|
||||
| 获取时间 |
|
||||
|
||||
*model = > llm.llm*
|
||||
*助手 = > agent.agent model=`model` tools=`工具表` standing="You are a Marqdo agent. Prefer CALL:获取时间 when the task needs today's date."*
|
||||
|
||||
Assert constitution markers in the assembled prompt (call site before how-to-act):
|
||||
|
||||
*ctx = > agent.build_step_context agent=`助手` task="What is today's date? Use the tool in this runbook."*
|
||||
|
||||
*parts = > split value=`ctx` sep="--- call site ---"*
|
||||
*n = > len value=`parts`*
|
||||
1. `n` > 1
|
||||
> print text=call-site-ok
|
||||
2. *
|
||||
> print text=call-site-missing
|
||||
> sys.exit code=1
|
||||
|
||||
*parts2 = > split value=`ctx` sep="--- source (.mq.md) ---"*
|
||||
*n2 = > len value=`parts2`*
|
||||
1. `n2` > 1
|
||||
> print text=source-ok
|
||||
2. *
|
||||
> print text=source-missing
|
||||
> sys.exit code=1
|
||||
|
||||
*parts3 = > split value=`ctx` sep="获取时间"*
|
||||
*n3 = > len value=`parts3`*
|
||||
1. `n3` > 1
|
||||
> print text=tool-in-source-ok
|
||||
2. *
|
||||
> print text=tool-in-source-missing
|
||||
> sys.exit code=1
|
||||
|
||||
*site = > agent_call_site*
|
||||
*fn = > json.get value=`site` key="function"*
|
||||
> print text=`fn`
|
||||
|
||||
Optional live step — set env AGENT_LIVE=1 and put keys in repo-root `.env`:
|
||||
|
||||
*live = > sys.env_get name="AGENT_LIVE"*
|
||||
*key = > sys.env_get name="OPENAI_API_KEY"*
|
||||
1. `live` == "1"
|
||||
1. `key`
|
||||
*out = > `助手`.step task="请调用获取时间工具,然后只回复日期字符串。" writeback=False*
|
||||
*status = > json.get value=`out` key="status"*
|
||||
> print text=`status`
|
||||
*tool = > json.get value=`out` key="tool"*
|
||||
> print text=`tool`
|
||||
*result = > json.get value=`out` key="result"*
|
||||
> print text=`result`
|
||||
2. *
|
||||
> print text=live-skipped-no-key
|
||||
2. *
|
||||
> print text=live-skipped
|
||||
@@ -0,0 +1,21 @@
|
||||
# browser-app(路线 E)
|
||||
|
||||
作者**零业务 JS**;逻辑用 **GFM 表格 + `lib/browser`**(无 `json.set` 链)。
|
||||
|
||||
| 能力 | 演示 |
|
||||
|------|------|
|
||||
| 列表 CRUD | 添加 / 委托删除(`bag` + `set_html`) |
|
||||
| storage | 草稿 localStorage |
|
||||
| navigate | `/` `/about` `/net` + `popstate` |
|
||||
| interval | 计时起停 |
|
||||
| fetch_all | 并行两个 uuid |
|
||||
| ws | `wss://echo.websocket.events`(依赖外网) |
|
||||
| clipboard / download | 复制/下载列表文本 |
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo --release
|
||||
./target/release/marqdo wasm build -o examples/browser-app
|
||||
cd examples/browser-app && python3 -m http.server 8766
|
||||
```
|
||||
|
||||
写法:[marqdo-dev](../../.cursor/skills/marqdo-dev/SKILL.md) · 路线图:[browser-wasm-e.md](../../doc/roadmap/browser-wasm-e.md)。
|
||||
@@ -0,0 +1,283 @@
|
||||
---
|
||||
title: browser-app (route E+)
|
||||
description: list CRUD, storage, navigate, interval, fetch_all, ws — GFM + lib/browser
|
||||
import browser:lib/browser.mq.md
|
||||
import table:lib/table.mq.md
|
||||
import text:lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`ticks` = 0*
|
||||
*`bag` = ""*
|
||||
*`path` = "/"*
|
||||
*`ws_id` = "echo"*
|
||||
|
||||
`wire` =
|
||||
|
||||
| @ | 选择器 | 事件 | 调用 | 委托 | 值选择器 |
|
||||
|---|--------|------|------|------|----------|
|
||||
| 1 | "#add" | click | add | | "#draft" |
|
||||
| 2 | "#save" | click | save_draft | | "#draft" |
|
||||
| 3 | "#load" | click | load_draft | | |
|
||||
| 4 | "#start-tick" | click | start_tick | | |
|
||||
| 5 | "#stop-tick" | click | stop_tick | | |
|
||||
| 6 | "#nav-home" | click | go_home | | |
|
||||
| 7 | "#nav-about" | click | go_about | | |
|
||||
| 8 | "#nav-net" | click | go_net | | |
|
||||
| 9 | "window" | popstate | on_pop | | |
|
||||
| 10 | "#items" | click | on_item | "button[data-id]" | |
|
||||
| 11 | "#fetch-all" | click | do_fetch_all | | |
|
||||
| 12 | "#ws-open" | click | ws_open | | |
|
||||
| 13 | "#ws-send" | click | ws_send | | "#ws-msg" |
|
||||
| 14 | "#ws-close" | click | ws_close | | |
|
||||
| 15 | "#copy-log" | click | copy_log | | |
|
||||
| 16 | "#dl-list" | click | dl_list | | |
|
||||
|
||||
`nav` =
|
||||
|
||||
| url | replace |
|
||||
|-----|---------|
|
||||
| / | False |
|
||||
|
||||
`st` =
|
||||
|
||||
| op | key | then |
|
||||
|----|-----|------|
|
||||
| get | mq-draft | on_draft |
|
||||
|
||||
`boot` =
|
||||
|
||||
| wire | navigate | storage |
|
||||
|------|----------|---------|
|
||||
| `wire` | `nav` | `st` |
|
||||
|
||||
**boot**
|
||||
|
||||
## add
|
||||
+ `value`=""
|
||||
|
||||
1. `value` != ""
|
||||
1. `bag` == ""
|
||||
*`bag` = value*
|
||||
2. *
|
||||
*`bag` = bag + "\n" + value*
|
||||
*`parts` = > text.str_split s=bag sep="\n"*
|
||||
*`html` = ""*
|
||||
- [item](parts)
|
||||
1. `item` != ""
|
||||
*`html` = html + "<li><span>" + item + "</span> <button type=\"button\" data-id=\"" + item + "\">删</button></li>"*
|
||||
*`ret` = > browser.set_html sel="#items" html=html*
|
||||
*`clr` = > browser.set_value sel="#draft" value=""*
|
||||
*`ret` = > browser.merge a=ret b=clr*
|
||||
*`f` = > browser.focus sel="#draft"*
|
||||
**> browser.merge a=ret b=f**
|
||||
2. *
|
||||
****
|
||||
|
||||
## on_item
|
||||
+ `data_id`=""
|
||||
|
||||
1. `data_id` != ""
|
||||
*`parts` = > text.str_split s=bag sep="\n"*
|
||||
*`next` = ""*
|
||||
- [item](parts)
|
||||
1. `item` != ""
|
||||
1. `item` != `data_id`
|
||||
1. `next` == ""
|
||||
*`next` = item*
|
||||
2. *
|
||||
*`next` = next + "\n" + item*
|
||||
*`bag` = next*
|
||||
*`parts2` = > text.str_split s=bag sep="\n"*
|
||||
*`html` = ""*
|
||||
- [item](parts2)
|
||||
1. `item` != ""
|
||||
*`html` = html + "<li><span>" + item + "</span> <button type=\"button\" data-id=\"" + item + "\">删</button></li>"*
|
||||
*`ret` = > browser.set_html sel="#items" html=html*
|
||||
*`msg` = "removed " + data_id*
|
||||
*`t` = > browser.set_text sel="#log" text=msg*
|
||||
**> browser.merge a=ret b=t**
|
||||
2. *
|
||||
****
|
||||
|
||||
## save_draft
|
||||
+ `value`=""
|
||||
|
||||
`st` =
|
||||
|
||||
| op | key | value |
|
||||
|----|-----|-------|
|
||||
| set | mq-draft | `value` |
|
||||
|
||||
*`msg` = > browser.set_text sel="#log" text="draft saved"*
|
||||
*`s` = > browser.storage spec=st*
|
||||
**> browser.merge a=msg b=s**
|
||||
|
||||
## load_draft
|
||||
|
||||
`st` =
|
||||
|
||||
| op | key | then |
|
||||
|----|-----|------|
|
||||
| get | mq-draft | on_draft |
|
||||
|
||||
**> browser.storage spec=st**
|
||||
|
||||
## on_draft
|
||||
+ `ok`=True
|
||||
+ `value`=""
|
||||
+ `found`=False
|
||||
|
||||
1. `found`
|
||||
*`ret` = > browser.set_value sel="#draft" value=value*
|
||||
*`msg` = > browser.set_text sel="#log" text="draft loaded"*
|
||||
**> browser.merge a=ret b=msg**
|
||||
2. *
|
||||
**> browser.set_text sel="#log" text="no draft"**
|
||||
|
||||
## start_tick
|
||||
**> browser.interval ms=1000 then="on_tick" id="tick"**
|
||||
|
||||
## stop_tick
|
||||
**> browser.clear_interval id="tick"**
|
||||
|
||||
## on_tick
|
||||
+ `ok`=True
|
||||
+ `id`=""
|
||||
|
||||
*`ticks` = ticks + 1*
|
||||
*`label` = > str ticks*
|
||||
**> browser.set_text sel="#tick" text=label**
|
||||
|
||||
## go_home
|
||||
*`path` = "/"*
|
||||
**> show_path**
|
||||
|
||||
## go_about
|
||||
*`path` = "/about"*
|
||||
**> show_path**
|
||||
|
||||
## go_net
|
||||
*`path` = "/net"*
|
||||
**> show_path**
|
||||
|
||||
## on_pop
|
||||
+ `path`=""
|
||||
|
||||
*`path` = path*
|
||||
**> show_path**
|
||||
|
||||
## show_path
|
||||
*`hide` = > table.put in=None at="hidden" value=""*
|
||||
*`show` = > table.put in=None at="hidden" value=False*
|
||||
1. `path` == "/about"
|
||||
`attrs` =
|
||||
|
||||
| #panel-about | #panel-home | #panel-net |
|
||||
|--------------|-------------|------------|
|
||||
| `show` | `hide` | `hide` |
|
||||
2. *
|
||||
1. `path` == "/net"
|
||||
`attrs` =
|
||||
|
||||
| #panel-net | #panel-home | #panel-about |
|
||||
|------------|-------------|--------------|
|
||||
| `show` | `hide` | `hide` |
|
||||
2. *
|
||||
`attrs` =
|
||||
|
||||
| #panel-home | #panel-about | #panel-net |
|
||||
|-------------|--------------|------------|
|
||||
| `show` | `hide` | `hide` |
|
||||
*`label` = "path: " + path*
|
||||
*`ret` = > browser.set_text sel="#path" text=label*
|
||||
*`a` = > browser.wrap key="set_attr" value=attrs*
|
||||
*`ret` = > browser.merge a=ret b=a*
|
||||
*`nav` = > browser.navigate url=path*
|
||||
**> browser.merge a=ret b=nav**
|
||||
|
||||
## do_fetch_all
|
||||
|
||||
`reqs` =
|
||||
|
||||
| @ | url |
|
||||
|---|-----|
|
||||
| 1 | "https://httpbin.org/uuid" |
|
||||
| 2 | "https://httpbin.org/uuid" |
|
||||
|
||||
*`msg` = > browser.set_text sel="#net-out" text="fetch_all…"*
|
||||
*`fa` = > browser.fetch_all requests=reqs then="on_fetch_all"*
|
||||
**> browser.merge a=msg b=fa**
|
||||
|
||||
## on_fetch_all
|
||||
+ `ok`=True
|
||||
+ `results`=None
|
||||
|
||||
**> browser.set_text sel="#net-out" text="fetch_all done (see console / results in session)"**
|
||||
|
||||
## ws_open
|
||||
|
||||
`w` =
|
||||
|
||||
| op | id | url | then_open | then_message | then_error | then_close |
|
||||
|----|----|-----|-----------|--------------|------------|------------|
|
||||
| open | `ws_id` | "wss://echo.websocket.events" | on_ws_open | on_ws_msg | on_ws_err | on_ws_close |
|
||||
|
||||
**> browser.ws spec=w**
|
||||
|
||||
## on_ws_open
|
||||
+ `ok`=True
|
||||
+ `id`=""
|
||||
|
||||
**> browser.set_text sel="#net-out" text="ws open"**
|
||||
|
||||
## on_ws_msg
|
||||
+ `ok`=True
|
||||
+ `data`=""
|
||||
|
||||
*`msg` = "ws ← " + data*
|
||||
**> browser.set_text sel="#net-out" text=msg**
|
||||
|
||||
## on_ws_err
|
||||
+ `ok`=False
|
||||
+ `error`=""
|
||||
|
||||
*`msg` = "ws error: " + error*
|
||||
**> browser.set_text sel="#net-out" text=msg**
|
||||
|
||||
## on_ws_close
|
||||
+ `ok`=True
|
||||
|
||||
**> browser.set_text sel="#net-out" text="ws closed"**
|
||||
|
||||
## ws_send
|
||||
+ `value`=""
|
||||
|
||||
`w` =
|
||||
|
||||
| op | id | data |
|
||||
|----|----|------|
|
||||
| send | `ws_id` | `value` |
|
||||
|
||||
**> browser.ws spec=w**
|
||||
|
||||
## ws_close
|
||||
|
||||
`w` =
|
||||
|
||||
| op | id |
|
||||
|----|----|
|
||||
| close | `ws_id` |
|
||||
|
||||
**> browser.ws spec=w**
|
||||
|
||||
## copy_log
|
||||
*`msg` = > browser.set_text sel="#log" text="copied bag to clipboard"*
|
||||
*`c` = > browser.clipboard text=bag*
|
||||
**> browser.merge a=msg b=c**
|
||||
|
||||
## dl_list
|
||||
*`msg` = > browser.set_text sel="#log" text="download started"*
|
||||
*`d` = > browser.download body=bag filename="items.txt"*
|
||||
**> browser.merge a=msg b=d**
|
||||
@@ -0,0 +1,96 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-Hans">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>Marqdo · browser-app (route E)</title>
|
||||
<style>
|
||||
:root { --ink: #1a1f1c; --paper: #e8efe6; --accent: #2f6f4e; --muted: #5a6b60; }
|
||||
* { box-sizing: border-box; }
|
||||
body {
|
||||
margin: 0; min-height: 100vh; font-family: "IBM Plex Sans", "Noto Sans SC", sans-serif;
|
||||
color: var(--ink);
|
||||
background: linear-gradient(165deg, #f3f7f2, var(--paper));
|
||||
padding: 2rem clamp(1rem, 4vw, 3rem);
|
||||
}
|
||||
h1 { font-family: "IBM Plex Serif", "Noto Serif SC", serif; margin: 0 0 0.35rem; }
|
||||
.lead { color: var(--muted); max-width: 42rem; }
|
||||
nav a { margin-right: 0.75rem; color: var(--accent); }
|
||||
section { margin: 1.5rem 0; padding: 1rem 0; border-top: 1px solid #c5d4c9; }
|
||||
#path { font-family: ui-monospace, monospace; color: var(--muted); }
|
||||
#items { list-style: none; padding: 0; margin: 0.75rem 0; }
|
||||
#items li {
|
||||
display: flex; align-items: center; gap: 0.5rem;
|
||||
padding: 0.4rem 0.6rem; margin-bottom: 0.35rem;
|
||||
background: rgba(255,255,255,0.65); border: 1px solid #b7c7bb;
|
||||
}
|
||||
#items button { margin-left: auto; }
|
||||
input[type="text"] { padding: 0.45rem 0.65rem; border: 1px solid #b7c7bb; width: min(16rem, 70%); }
|
||||
button {
|
||||
padding: 0.45rem 0.9rem; border: 0; background: var(--accent); color: #f5faf6;
|
||||
font: inherit; cursor: pointer; margin: 0.2rem 0.35rem 0.2rem 0;
|
||||
}
|
||||
button.secondary { background: #3a4740; }
|
||||
#tick, #net-out { font-variant-numeric: tabular-nums; }
|
||||
#net-out {
|
||||
min-height: 2.5rem; padding: 0.6rem 0.75rem; background: rgba(255,255,255,0.55);
|
||||
border: 1px solid #b7c7bb; white-space: pre-wrap; word-break: break-all;
|
||||
}
|
||||
pre {
|
||||
margin-top: 1rem; padding: 0.85rem 1rem; background: #122018; color: #d7eadc;
|
||||
font-size: 0.8rem; overflow: auto; max-width: 42rem;
|
||||
}
|
||||
.err { color: #ffb4a8; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Marqdo browser-app</h1>
|
||||
<p class="lead">路线 E:列表 CRUD / storage / navigate / interval / fetch_all / ws / clipboard / download — <strong>无作者业务 JS</strong>。</p>
|
||||
<p id="path">path: /</p>
|
||||
<nav>
|
||||
<a href="#/" id="nav-home">首页</a>
|
||||
<a href="#/about" id="nav-about">关于</a>
|
||||
<a href="#/net" id="nav-net">网络</a>
|
||||
</nav>
|
||||
|
||||
<section id="panel-home">
|
||||
<h2>待办</h2>
|
||||
<input id="draft" type="text" placeholder="新项…" disabled />
|
||||
<button id="add" type="button" disabled>添加</button>
|
||||
<button id="save" class="secondary" type="button" disabled>存草稿</button>
|
||||
<button id="load" class="secondary" type="button" disabled>读草稿</button>
|
||||
<button id="copy-log" class="secondary" type="button" disabled>复制列表</button>
|
||||
<button id="dl-list" class="secondary" type="button" disabled>下载列表</button>
|
||||
<ul id="items"></ul>
|
||||
<p>计时:<span id="tick">0</span>s
|
||||
<button id="start-tick" type="button" disabled>开始</button>
|
||||
<button id="stop-tick" class="secondary" type="button" disabled>停止</button>
|
||||
</p>
|
||||
</section>
|
||||
|
||||
<section id="panel-about" hidden>
|
||||
<h2>关于</h2>
|
||||
<p>作者只写 <code>app.mq.md</code>。官方 bridge 提供 DOM / 路由 / storage / ws / fetch_all 等宿主能力。</p>
|
||||
</section>
|
||||
|
||||
<section id="panel-net" hidden>
|
||||
<h2>网络</h2>
|
||||
<p id="net-out">idle</p>
|
||||
<button id="fetch-all" type="button" disabled>fetch_all ×2 uuid</button>
|
||||
<button id="ws-open" type="button" disabled>WS 打开</button>
|
||||
<input id="ws-msg" type="text" placeholder="ws 消息" disabled />
|
||||
<button id="ws-send" type="button" disabled>WS 发送</button>
|
||||
<button id="ws-close" class="secondary" type="button" disabled>WS 关闭</button>
|
||||
</section>
|
||||
|
||||
<pre id="log">loading…</pre>
|
||||
<script
|
||||
type="module"
|
||||
src="./marqdo-bridge.js"
|
||||
data-mq-wasm="./marqdo_wasm.wasm"
|
||||
data-mq-source-url="./app.mq.md"
|
||||
data-mq-ready="#log"
|
||||
data-mq-enable="#draft,#add,#save,#load,#start-tick,#stop-tick,#fetch-all,#ws-open,#ws-msg,#ws-send,#ws-close,#copy-log,#dl-list"
|
||||
></script>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,21 @@
|
||||
# browser-hello(WASM C1–C4 / 路线 D)
|
||||
|
||||
浏览器内跑 Marqdo。**无作者业务 JS**——只保留官方 `marqdo-bridge.js`(`marqdo wasm build` 拷贝)。客户端 `.mq.md` 用 **GFM 表格 + `lib/browser`**。
|
||||
|
||||
```bash
|
||||
# 仓库根目录
|
||||
cargo build -p marqdo --release
|
||||
./target/release/marqdo wasm build -o examples/browser-hello
|
||||
|
||||
cd examples/browser-hello
|
||||
python3 -m http.server 8765
|
||||
```
|
||||
|
||||
| 页 | 说明 |
|
||||
|----|------|
|
||||
| [/](http://127.0.0.1:8765/) | playground:`data-mq-playground` + textarea → `mq_run` |
|
||||
| [/interact.html](http://127.0.0.1:8765/interact.html) | `counter.mq.md` wire → 点击改 DOM |
|
||||
| [/fetch.html](http://127.0.0.1:8765/fetch.html) | `fetch` / `after` 效应 |
|
||||
| [/form.html](http://127.0.0.1:8765/form.html) | `input` + `value` / `set_class`(D3) |
|
||||
|
||||
自启方式:脚本上的 `data-mq-source-url` / `data-mq-playground`,或 `#marqdo-boot` JSON。详见 [browser-wasm-d.md](../../doc/roadmap/browser-wasm-d.md)。
|
||||
@@ -0,0 +1,27 @@
|
||||
---
|
||||
title: browser counter (C3)
|
||||
description: wire table + browser.set_text — no json glue
|
||||
import browser:lib/browser.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`count` = 0*
|
||||
|
||||
`wire` =
|
||||
|
||||
| @ | 选择器 | 事件 | 调用 |
|
||||
|---|--------|------|------|
|
||||
| 1 | "#bump" | click | bump |
|
||||
| 2 | "#reset" | click | reset |
|
||||
|
||||
**`wire`**
|
||||
|
||||
## bump
|
||||
*`count` = count + 1*
|
||||
*`label` = > str count*
|
||||
**> browser.set_text sel="#count" text=label**
|
||||
|
||||
## reset
|
||||
*`count` = 0*
|
||||
**> browser.set_text sel="#count" text="0"**
|
||||
@@ -0,0 +1,86 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-Hans">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>Marqdo · fetch / after (C4)</title>
|
||||
<style>
|
||||
:root {
|
||||
--ink: #1a1f1c;
|
||||
--paper: #e8efe6;
|
||||
--accent: #2f6f4e;
|
||||
--muted: #5a6b60;
|
||||
}
|
||||
* { box-sizing: border-box; }
|
||||
body {
|
||||
margin: 0;
|
||||
min-height: 100vh;
|
||||
font-family: "IBM Plex Sans", "Noto Sans SC", sans-serif;
|
||||
color: var(--ink);
|
||||
background:
|
||||
radial-gradient(800px 420px at 0% 100%, #d5e4d8 0%, transparent 55%),
|
||||
linear-gradient(165deg, #f3f7f2, var(--paper));
|
||||
padding: 2rem clamp(1rem, 4vw, 3rem);
|
||||
}
|
||||
h1 {
|
||||
font-family: "IBM Plex Serif", "Noto Serif SC", serif;
|
||||
font-weight: 600;
|
||||
font-size: clamp(1.6rem, 3vw, 2.2rem);
|
||||
margin: 0 0 0.35rem;
|
||||
}
|
||||
.lead { color: var(--muted); margin: 0 0 1.25rem; max-width: 38rem; }
|
||||
#status {
|
||||
font-family: "IBM Plex Mono", ui-monospace, monospace;
|
||||
font-size: 0.95rem;
|
||||
line-height: 1.45;
|
||||
white-space: pre-wrap;
|
||||
word-break: break-all;
|
||||
min-height: 4rem;
|
||||
margin: 1rem 0 1.25rem;
|
||||
padding: 0.85rem 1rem;
|
||||
background: rgba(255,255,255,0.55);
|
||||
border: 1px solid #b7c7bb;
|
||||
}
|
||||
button {
|
||||
margin-right: 0.5rem;
|
||||
margin-bottom: 0.4rem;
|
||||
padding: 0.55rem 1.1rem;
|
||||
border: 0;
|
||||
background: var(--accent);
|
||||
color: #f5faf6;
|
||||
font: inherit;
|
||||
cursor: pointer;
|
||||
}
|
||||
button.secondary { background: #3a4740; }
|
||||
button:disabled { opacity: 0.5; cursor: wait; }
|
||||
pre {
|
||||
margin-top: 1.5rem;
|
||||
width: min(42rem, 100%);
|
||||
padding: 0.9rem 1rem;
|
||||
background: #122018;
|
||||
color: #d7eadc;
|
||||
overflow: auto;
|
||||
font-size: 0.8rem;
|
||||
line-height: 1.4;
|
||||
}
|
||||
.err { color: #ffb4a8; }
|
||||
a { color: var(--accent); }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Marqdo</h1>
|
||||
<p class="lead">C4/D:返回 <code>fetch</code> / <code>after</code> 效应;bridge 自启(ADR 0003)。业务只在 <code>fetch.mq.md</code>。<a href="./interact.html">计数器</a> · <a href="./form.html">表单</a> · <a href="./">打印</a></p>
|
||||
<div id="status">idle</div>
|
||||
<button id="load" type="button" disabled>请求 UUID</button>
|
||||
<button id="ping" class="secondary" type="button" disabled>延迟 pong</button>
|
||||
<pre id="log">loading…</pre>
|
||||
<script
|
||||
type="module"
|
||||
src="./marqdo-bridge.js"
|
||||
data-mq-wasm="./marqdo_wasm.wasm"
|
||||
data-mq-source-url="./fetch.mq.md"
|
||||
data-mq-ready="#log"
|
||||
data-mq-enable="#load,#ping"
|
||||
></script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,42 @@
|
||||
---
|
||||
title: browser fetch (C4)
|
||||
description: fetch/after effects via lib/browser — no json glue
|
||||
import browser:lib/browser.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`wire` =
|
||||
|
||||
| @ | 选择器 | 事件 | 调用 |
|
||||
|---|--------|------|------|
|
||||
| 1 | "#load" | click | load |
|
||||
| 2 | "#ping" | click | ping |
|
||||
|
||||
**`wire`**
|
||||
|
||||
## load
|
||||
*`msg` = > browser.set_text sel="#status" text="loading…"*
|
||||
*`req` = > browser.fetch url="https://httpbin.org/uuid" then="on_uuid"*
|
||||
**> browser.merge a=msg b=req**
|
||||
|
||||
## on_uuid
|
||||
+ `ok`
|
||||
+ `status`
|
||||
+ `body`=""
|
||||
+ `error`=""
|
||||
|
||||
1. ok
|
||||
**> browser.set_text sel="#status" text=body**
|
||||
2. *
|
||||
**> browser.set_text sel="#status" text="fetch failed"**
|
||||
|
||||
## ping
|
||||
*`msg` = > browser.set_text sel="#status" text="wait 600ms…"*
|
||||
*`t` = > browser.after ms=600 then="on_ping"*
|
||||
**> browser.merge a=msg b=t**
|
||||
|
||||
## on_ping
|
||||
+ `ok`=True
|
||||
|
||||
**> browser.set_text sel="#status" text="pong"**
|
||||
@@ -0,0 +1,76 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-Hans">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>Marqdo · 表单 (D3)</title>
|
||||
<style>
|
||||
:root {
|
||||
--ink: #1a1f1c;
|
||||
--paper: #e8efe6;
|
||||
--accent: #2f6f4e;
|
||||
--muted: #5a6b60;
|
||||
}
|
||||
* { box-sizing: border-box; }
|
||||
body {
|
||||
margin: 0;
|
||||
min-height: 100vh;
|
||||
font-family: "IBM Plex Sans", "Noto Sans SC", sans-serif;
|
||||
color: var(--ink);
|
||||
background:
|
||||
radial-gradient(700px 400px at 100% 20%, #d0e0d4 0%, transparent 50%),
|
||||
linear-gradient(165deg, #f3f7f2, var(--paper));
|
||||
padding: 2rem clamp(1rem, 4vw, 3rem);
|
||||
}
|
||||
h1 {
|
||||
font-family: "IBM Plex Serif", "Noto Serif SC", serif;
|
||||
font-weight: 600;
|
||||
font-size: clamp(1.6rem, 3vw, 2.2rem);
|
||||
margin: 0 0 0.35rem;
|
||||
}
|
||||
.lead { color: var(--muted); margin: 0 0 1.25rem; max-width: 38rem; }
|
||||
label { display: block; font-size: 0.85rem; color: var(--muted); margin: 0.75rem 0 0.35rem; }
|
||||
input[type="text"] {
|
||||
width: min(24rem, 100%);
|
||||
padding: 0.5rem 0.75rem;
|
||||
border: 1px solid #b7c7bb;
|
||||
background: rgba(255,255,255,0.75);
|
||||
font: inherit;
|
||||
}
|
||||
#echo {
|
||||
margin-top: 1rem;
|
||||
font-size: 1.25rem;
|
||||
min-height: 1.5em;
|
||||
}
|
||||
#echo.hi { color: var(--accent); font-weight: 600; }
|
||||
pre {
|
||||
margin-top: 1.5rem;
|
||||
width: min(42rem, 100%);
|
||||
padding: 0.9rem 1rem;
|
||||
background: #122018;
|
||||
color: #d7eadc;
|
||||
overflow: auto;
|
||||
font-size: 0.8rem;
|
||||
line-height: 1.4;
|
||||
}
|
||||
.err { color: #ffb4a8; }
|
||||
a { color: var(--accent); }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Marqdo</h1>
|
||||
<p class="lead">D3:<code>input</code> 事件把 <code>value</code> 传入 Marqdo;<code>set_value</code> / <code>set_class</code> / <code>set_attr</code> 回写 DOM。业务只在 <code>form.mq.md</code>。<a href="./interact.html">计数器</a> · <a href="./">打印</a></p>
|
||||
<label for="name">名字</label>
|
||||
<input id="name" type="text" placeholder="输入…" disabled />
|
||||
<div id="echo">(等待输入)</div>
|
||||
<pre id="log">loading…</pre>
|
||||
<script
|
||||
type="module"
|
||||
src="./marqdo-bridge.js"
|
||||
data-mq-wasm="./marqdo_wasm.wasm"
|
||||
data-mq-source-url="./form.mq.md"
|
||||
data-mq-ready="#log"
|
||||
data-mq-enable="#name"
|
||||
></script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,33 @@
|
||||
---
|
||||
title: browser form (D3)
|
||||
description: input wire passes value; effects via lib/browser
|
||||
import browser:lib/browser.mq.md
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`wire` =
|
||||
|
||||
| @ | 选择器 | 事件 | 调用 |
|
||||
|---|--------|------|------|
|
||||
| 1 | "#name" | input | on_input |
|
||||
|
||||
**`wire`**
|
||||
|
||||
## on_input
|
||||
+ `value`=""
|
||||
+ `event`=""
|
||||
|
||||
1. `value` != ""
|
||||
*`label` = "你好," + value*
|
||||
*`ret` = > browser.set_text sel="#echo" text=label*
|
||||
*`cls` = > browser.set_class sel="#echo" class="hi"*
|
||||
*`ret` = > browser.merge a=ret b=cls*
|
||||
*`attrs` = > table.put in=None at="data-name" value=value*
|
||||
*`attr` = > browser.set_attr sel="#echo" attrs=attrs*
|
||||
**> browser.merge a=ret b=attr**
|
||||
2. *
|
||||
*`ret` = > browser.set_text sel="#echo" text="(等待输入)"*
|
||||
*`cls` = > browser.set_class sel="#echo" class=""*
|
||||
**> browser.merge a=ret b=cls**
|
||||
@@ -0,0 +1,88 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-Hans">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>Marqdo browser hello (WASM C1)</title>
|
||||
<style>
|
||||
:root {
|
||||
--ink: #1a1f1c;
|
||||
--paper: #e8efe6;
|
||||
--accent: #2f6f4e;
|
||||
--muted: #5a6b60;
|
||||
}
|
||||
* { box-sizing: border-box; }
|
||||
body {
|
||||
margin: 0;
|
||||
min-height: 100vh;
|
||||
font-family: "IBM Plex Sans", "Noto Sans SC", sans-serif;
|
||||
color: var(--ink);
|
||||
background:
|
||||
radial-gradient(1200px 600px at 10% -10%, #c5dcc8 0%, transparent 55%),
|
||||
linear-gradient(165deg, #f3f7f2, var(--paper));
|
||||
padding: 2rem clamp(1rem, 4vw, 3rem);
|
||||
}
|
||||
h1 {
|
||||
font-family: "IBM Plex Serif", "Noto Serif SC", serif;
|
||||
font-weight: 600;
|
||||
font-size: clamp(1.6rem, 3vw, 2.2rem);
|
||||
margin: 0 0 0.35rem;
|
||||
letter-spacing: -0.02em;
|
||||
}
|
||||
.lead { color: var(--muted); margin: 0 0 1.5rem; max-width: 36rem; }
|
||||
label { display: block; font-size: 0.85rem; color: var(--muted); margin-bottom: 0.35rem; }
|
||||
textarea {
|
||||
width: min(40rem, 100%);
|
||||
min-height: 10rem;
|
||||
padding: 0.75rem 0.9rem;
|
||||
border: 1px solid #b7c7bb;
|
||||
border-radius: 2px;
|
||||
background: rgba(255,255,255,0.7);
|
||||
font-family: "IBM Plex Mono", ui-monospace, monospace;
|
||||
font-size: 0.9rem;
|
||||
line-height: 1.45;
|
||||
}
|
||||
button {
|
||||
margin-top: 0.85rem;
|
||||
padding: 0.55rem 1.1rem;
|
||||
border: 0;
|
||||
background: var(--accent);
|
||||
color: #f5faf6;
|
||||
font: inherit;
|
||||
cursor: pointer;
|
||||
}
|
||||
button:disabled { opacity: 0.5; cursor: wait; }
|
||||
pre {
|
||||
margin-top: 1.25rem;
|
||||
width: min(40rem, 100%);
|
||||
padding: 0.9rem 1rem;
|
||||
background: #122018;
|
||||
color: #d7eadc;
|
||||
overflow: auto;
|
||||
font-size: 0.85rem;
|
||||
line-height: 1.4;
|
||||
}
|
||||
.err { color: #ffb4a8; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Marqdo</h1>
|
||||
<p class="lead">浏览器内 WASM(路线 C/D):源码是 <code>.mq.md</code>,官方 bridge 自启 playground,无作者业务 JS。<a href="./interact.html">交互</a> · <a href="./fetch.html">fetch</a> · <a href="./form.html">表单</a></p>
|
||||
<label for="src">程序</label>
|
||||
<textarea id="src"># main
|
||||
|
||||
> print text=Hello from browser WASM!
|
||||
</textarea>
|
||||
<div>
|
||||
<button id="run" disabled>运行</button>
|
||||
</div>
|
||||
<pre id="out">loading wasm…</pre>
|
||||
<script
|
||||
type="module"
|
||||
src="./marqdo-bridge.js"
|
||||
data-mq-wasm="./marqdo_wasm.wasm"
|
||||
data-mq-playground="#src,#run,#out"
|
||||
data-mq-ready="#out"
|
||||
></script>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,79 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-Hans">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>Marqdo · 交互装配 (C3)</title>
|
||||
<style>
|
||||
:root {
|
||||
--ink: #1a1f1c;
|
||||
--paper: #e8efe6;
|
||||
--accent: #2f6f4e;
|
||||
--muted: #5a6b60;
|
||||
}
|
||||
* { box-sizing: border-box; }
|
||||
body {
|
||||
margin: 0;
|
||||
min-height: 100vh;
|
||||
font-family: "IBM Plex Sans", "Noto Sans SC", sans-serif;
|
||||
color: var(--ink);
|
||||
background:
|
||||
radial-gradient(900px 500px at 90% 0%, #cfe0d2 0%, transparent 50%),
|
||||
linear-gradient(165deg, #f3f7f2, var(--paper));
|
||||
padding: 2rem clamp(1rem, 4vw, 3rem);
|
||||
}
|
||||
h1 {
|
||||
font-family: "IBM Plex Serif", "Noto Serif SC", serif;
|
||||
font-weight: 600;
|
||||
font-size: clamp(1.6rem, 3vw, 2.2rem);
|
||||
margin: 0 0 0.35rem;
|
||||
}
|
||||
.lead { color: var(--muted); margin: 0 0 1.5rem; max-width: 36rem; }
|
||||
#count {
|
||||
font-family: "IBM Plex Serif", serif;
|
||||
font-size: 4rem;
|
||||
line-height: 1;
|
||||
margin: 1rem 0 1.25rem;
|
||||
letter-spacing: -0.04em;
|
||||
}
|
||||
button {
|
||||
margin-right: 0.5rem;
|
||||
padding: 0.55rem 1.1rem;
|
||||
border: 0;
|
||||
background: var(--accent);
|
||||
color: #f5faf6;
|
||||
font: inherit;
|
||||
cursor: pointer;
|
||||
}
|
||||
button.secondary { background: #3a4740; }
|
||||
pre {
|
||||
margin-top: 1.5rem;
|
||||
width: min(40rem, 100%);
|
||||
padding: 0.9rem 1rem;
|
||||
background: #122018;
|
||||
color: #d7eadc;
|
||||
overflow: auto;
|
||||
font-size: 0.8rem;
|
||||
line-height: 1.4;
|
||||
}
|
||||
.err { color: #ffb4a8; }
|
||||
a { color: var(--accent); }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Marqdo</h1>
|
||||
<p class="lead">C3/D:GFM 交互表装配事件;官方 <code>mount</code> 自启,业务只在 <code>counter.mq.md</code>。<a href="./fetch.html">fetch</a> · <a href="./form.html">表单</a> · <a href="./">打印</a></p>
|
||||
<div id="count">0</div>
|
||||
<button id="bump" type="button" disabled>加一</button>
|
||||
<button id="reset" class="secondary" type="button" disabled>清零</button>
|
||||
<pre id="log">loading…</pre>
|
||||
<script
|
||||
type="module"
|
||||
src="./marqdo-bridge.js"
|
||||
data-mq-wasm="./marqdo_wasm.wasm"
|
||||
data-mq-source-url="./counter.mq.md"
|
||||
data-mq-ready="#log"
|
||||
data-mq-enable="#bump,#reset"
|
||||
></script>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,20 @@
|
||||
# browser-media(路线 F)
|
||||
|
||||
作者**零业务 JS**;`.mq.md` 用 **GFM 表格 + `lib/browser`**(禁止 `json.set` 链)。
|
||||
|
||||
| 能力 | 演示 |
|
||||
|------|------|
|
||||
| read_file | 文本 / DataURL |
|
||||
| canvas | `@` 指令表 |
|
||||
| audio | beep(Web Audio) |
|
||||
| observe | Intersection + Resize |
|
||||
| drag/drop | `data-drag` → `drop_text` |
|
||||
|
||||
```bash
|
||||
cargo build -p marqdo --release
|
||||
./target/release/marqdo wasm build -o examples/browser-media
|
||||
cd examples/browser-media && python3 -m http.server 8767
|
||||
```
|
||||
|
||||
写法约定见 [.cursor/skills/marqdo-dev/SKILL.md](../../.cursor/skills/marqdo-dev/SKILL.md)。
|
||||
路线图:[browser-wasm-f.md](../../doc/roadmap/browser-wasm-f.md)。
|
||||
@@ -0,0 +1,98 @@
|
||||
<!DOCTYPE html>
|
||||
<html lang="zh-Hans">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>Marqdo · browser-media (route F)</title>
|
||||
<style>
|
||||
:root { --ink: #1a1f1c; --paper: #e8efe6; --accent: #2f6f4e; --muted: #5a6b60; }
|
||||
* { box-sizing: border-box; }
|
||||
body {
|
||||
margin: 0; min-height: 100vh; font-family: "IBM Plex Sans", "Noto Sans SC", sans-serif;
|
||||
color: var(--ink);
|
||||
background: linear-gradient(165deg, #f3f7f2, var(--paper));
|
||||
padding: 2rem clamp(1rem, 4vw, 3rem);
|
||||
}
|
||||
h1 { font-family: "IBM Plex Serif", "Noto Serif SC", serif; margin: 0 0 0.35rem; }
|
||||
.lead { color: var(--muted); max-width: 42rem; }
|
||||
section { margin: 1.5rem 0; padding: 1rem 0; border-top: 1px solid #c5d4c9; }
|
||||
button {
|
||||
padding: 0.45rem 0.9rem; border: 0; background: var(--accent); color: #f5faf6;
|
||||
font: inherit; cursor: pointer; margin: 0.2rem 0.35rem 0.2rem 0;
|
||||
}
|
||||
button.secondary { background: #3a4740; }
|
||||
#pad {
|
||||
display: block; background: #fff; border: 1px solid #b7c7bb;
|
||||
margin-top: 0.75rem;
|
||||
}
|
||||
#chips { display: flex; gap: 0.5rem; flex-wrap: wrap; margin: 0.75rem 0; }
|
||||
#chips span {
|
||||
padding: 0.45rem 0.75rem; background: rgba(255,255,255,0.75);
|
||||
border: 1px dashed #2f6f4e; cursor: grab; user-select: none;
|
||||
}
|
||||
#dropzone {
|
||||
min-height: 3.5rem; padding: 0.85rem; border: 2px dashed #7a9584;
|
||||
background: rgba(255,255,255,0.45); color: var(--muted);
|
||||
}
|
||||
#beacon {
|
||||
margin-top: 8rem; padding: 2rem; background: #2f6f4e; color: #f5faf6;
|
||||
text-align: center;
|
||||
}
|
||||
#preview { margin-top: 0.5rem; min-height: 1rem; }
|
||||
pre {
|
||||
margin-top: 1rem; padding: 0.85rem 1rem; background: #122018; color: #d7eadc;
|
||||
font-size: 0.8rem; overflow: auto; max-width: 42rem;
|
||||
}
|
||||
.err { color: #ffb4a8; }
|
||||
</style>
|
||||
</head>
|
||||
<body>
|
||||
<h1>Marqdo browser-media</h1>
|
||||
<p class="lead">路线 F:文件 / Canvas / Audio / Observer / 拖放 — <strong>无作者业务 JS</strong>。</p>
|
||||
|
||||
<section>
|
||||
<h2>F1 文件</h2>
|
||||
<input id="file" type="file" accept="image/*,text/*,.txt,.md" disabled />
|
||||
<button id="read-text" type="button" disabled>读文本</button>
|
||||
<button id="read-dataurl" type="button" disabled>读 DataURL</button>
|
||||
<div id="preview"></div>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2>F2 Canvas · F3 Audio</h2>
|
||||
<button id="draw" type="button" disabled>绘制</button>
|
||||
<button id="play" type="button" disabled>蜂鸣</button>
|
||||
<canvas id="pad" width="280" height="120"></canvas>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2>F4 Observer</h2>
|
||||
<button id="watch" type="button" disabled>开始观察</button>
|
||||
<button id="unwatch" class="secondary" type="button" disabled>停止</button>
|
||||
<p id="obs">idle</p>
|
||||
<p>向下滚动可触发 Intersection;改窗口大小触发 Resize。</p>
|
||||
</section>
|
||||
|
||||
<section>
|
||||
<h2>F5 拖放</h2>
|
||||
<div id="chips">
|
||||
<span draggable="true" data-drag="alpha">alpha</span>
|
||||
<span draggable="true" data-drag="beta">beta</span>
|
||||
<span draggable="true" data-drag="gamma">gamma</span>
|
||||
</div>
|
||||
<div id="dropzone">拖到这里</div>
|
||||
</section>
|
||||
|
||||
<div id="beacon">beacon(滚到可见)</div>
|
||||
|
||||
<pre id="log">loading…</pre>
|
||||
<script
|
||||
type="module"
|
||||
src="./marqdo-bridge.js"
|
||||
data-mq-wasm="./marqdo_wasm.wasm"
|
||||
data-mq-source-url="./media.mq.md"
|
||||
data-mq-ready="#log"
|
||||
data-mq-enable="#file,#read-text,#read-dataurl,#draw,#play,#watch,#unwatch"
|
||||
></script>
|
||||
</body>
|
||||
</html>
|
||||
File diff suppressed because it is too large.
Load diff
@@ -0,0 +1,162 @@
|
||||
---
|
||||
title: browser-media (route F)
|
||||
description: file / canvas / audio / observers / drag — GFM tables + lib/browser
|
||||
import browser:lib/browser.mq.md
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
Route F demo: author data stays in tables; effects via `browser.*`.
|
||||
|
||||
*`obs_on` = False*
|
||||
|
||||
`wire` =
|
||||
|
||||
| @ | 选择器 | 事件 | 调用 | 委托 |
|
||||
|---|--------|------|------|------|
|
||||
| 1 | "#read-text" | click | read_text | |
|
||||
| 2 | "#read-dataurl" | click | read_dataurl | |
|
||||
| 3 | "#draw" | click | draw_box | |
|
||||
| 4 | "#play" | click | play_tone | |
|
||||
| 5 | "#watch" | click | start_watch | |
|
||||
| 6 | "#unwatch" | click | stop_watch | |
|
||||
| 7 | "#chips" | dragstart | on_drag | "[data-drag]" |
|
||||
| 8 | "#dropzone" | dragover | on_dragover | |
|
||||
| 9 | "#dropzone" | drop | on_drop | |
|
||||
|
||||
*`ready` = > browser.set_text sel="#log" text="ready (route F)"*
|
||||
*`boot` = > table.put in=None at="wire" value=wire*
|
||||
**> browser.merge a=boot b=ready**
|
||||
|
||||
## read_text
|
||||
**> browser.read_file sel="#file" then="on_file" as="text"**
|
||||
|
||||
## read_dataurl
|
||||
**> browser.read_file sel="#file" then="on_file" as="data_url"**
|
||||
|
||||
## on_file
|
||||
+ `ok`=False
|
||||
+ `name`=""
|
||||
+ `size`=0
|
||||
+ `body`=""
|
||||
+ `data_url`=""
|
||||
+ `as`=""
|
||||
+ `error`=""
|
||||
|
||||
1. `ok`
|
||||
1. `as` == "data_url"
|
||||
*`n` = > len value=data_url*
|
||||
*`ns` = > str `n`*
|
||||
*`preview` = name + " data_url chars=" + ns*
|
||||
*`ret` = > browser.set_text sel="#log" text=preview*
|
||||
1. `data_url` != ""
|
||||
*`h` = "<img alt=\"preview\" src=\"" + data_url + "\" style=\"max-width:12rem;max-height:8rem\" />"*
|
||||
*`img` = > browser.set_html sel="#preview" html=h*
|
||||
**> browser.merge a=ret b=img**
|
||||
2. *
|
||||
**ret**
|
||||
2. *
|
||||
*`n` = > len value=body*
|
||||
*`ns` = > str `n`*
|
||||
*`ss` = > str `size`*
|
||||
*`preview` = name + " (" + ss + " B, chars=" + ns + ") ok"*
|
||||
**> browser.set_text sel="#log" text=preview**
|
||||
2. *
|
||||
*`preview` = "file error: " + error*
|
||||
**> browser.set_text sel="#log" text=preview**
|
||||
|
||||
## draw_box
|
||||
|
||||
Canvas commands as a readable `@` table:
|
||||
|
||||
`commands` =
|
||||
|
||||
| @ | op | x | y | w | h | fill | stroke | text |
|
||||
|---|----|---|---|---|---|------|--------|------|
|
||||
| 1 | fillrect | 10 | 10 | 120 | 80 | "#2f6f4e" | | |
|
||||
| 2 | strokerect | 20 | 20 | 100 | 60 | | "#122018" | |
|
||||
| 3 | filltext | 40 | 55 | | | "#f5faf6" | | Marqdo |
|
||||
|
||||
*`cv` = > browser.canvas sel="#pad" commands=commands clear=True*
|
||||
*`msg` = > browser.set_text sel="#log" text="canvas drawn"*
|
||||
**> browser.merge a=cv b=msg**
|
||||
|
||||
## play_tone
|
||||
*`tone` = > browser.audio op="play" id="demo" src="beep" freq=523 ms=220*
|
||||
*`msg` = > browser.set_text sel="#log" text="audio beep"*
|
||||
**> browser.merge a=tone b=msg**
|
||||
|
||||
## start_watch
|
||||
*`obs_on` = True*
|
||||
|
||||
`obs` =
|
||||
|
||||
| @ | kind | sel | id | then | threshold |
|
||||
|---|------|-----|----|------|-----------|
|
||||
| 1 | intersect | "#beacon" | beacon | on_intersect | 0.25 |
|
||||
| 2 | resize | "#pad" | pad | on_resize | |
|
||||
|
||||
*`o` = > browser.observe specs=obs*
|
||||
*`msg` = > browser.set_text sel="#log" text="observers on"*
|
||||
**> browser.merge a=o b=msg**
|
||||
|
||||
## stop_watch
|
||||
*`obs_on` = False*
|
||||
|
||||
`ids` =
|
||||
|
||||
| @ | id |
|
||||
|---|----|
|
||||
| 1 | beacon |
|
||||
| 2 | pad |
|
||||
|
||||
*`u` = > browser.unobserve specs=ids*
|
||||
*`msg` = > browser.set_text sel="#log" text="observers off"*
|
||||
**> browser.merge a=u b=msg**
|
||||
|
||||
## on_intersect
|
||||
+ `intersecting`=False
|
||||
+ `ratio`=0
|
||||
|
||||
1. `obs_on`
|
||||
*`state` = "hidden"*
|
||||
1. `intersecting`
|
||||
*`state` = "visible"*
|
||||
2. *
|
||||
---
|
||||
*`r` = > str `ratio`*
|
||||
*`msg` = "beacon " + state + " ratio=" + r*
|
||||
**> browser.set_text sel="#obs" text=msg**
|
||||
2. *
|
||||
****
|
||||
|
||||
## on_resize
|
||||
+ `width`=0
|
||||
+ `height`=0
|
||||
|
||||
1. `obs_on`
|
||||
*`w` = > str `width`*
|
||||
*`h` = > str `height`*
|
||||
*`msg` = "pad size " + w + "×" + h*
|
||||
**> browser.set_text sel="#obs" text=msg**
|
||||
2. *
|
||||
****
|
||||
|
||||
## on_drag
|
||||
+ `drag`=""
|
||||
|
||||
*`msg` = "dragging: " + drag*
|
||||
**> browser.set_text sel="#log" text=msg**
|
||||
|
||||
## on_dragover
|
||||
****
|
||||
|
||||
## on_drop
|
||||
+ `drop_text`=""
|
||||
|
||||
*`msg` = "dropped: " + drop_text*
|
||||
*`h` = "<strong>" + drop_text + "</strong>"*
|
||||
*`t` = > browser.set_text sel="#log" text=msg*
|
||||
*`box` = > browser.set_html sel="#dropzone" html=h*
|
||||
**> browser.merge a=t b=box**
|
||||
@@ -0,0 +1,12 @@
|
||||
# linalg-least-squares
|
||||
|
||||
Overdetermined least squares via `ext/linalg`: `factorize kind=qr`, `Qᵀb`, solve `R`, plus a heatmap SVG of `A`.
|
||||
|
||||
```bash
|
||||
cargo build --release -p marqdo_plugin_linalg
|
||||
marqdo ext add linalg # once (re-run after rebuilding the plugin)
|
||||
marqdo run examples/linalg-least-squares/index.mq.md
|
||||
# optional: marqdo view examples/linalg-least-squares/
|
||||
```
|
||||
|
||||
Design: [ext-linalg.md](../../doc/design/ext-linalg.md) · sibling: [linalg-svd](../linalg-svd/).
|
||||
@@ -0,0 +1,35 @@
|
||||
---
|
||||
title: Least squares via lstsq
|
||||
description: Overdetermined Ax≈b with ext/linalg lstsq + heatmap.
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
import math:lib/math.mq.md
|
||||
---
|
||||
|
||||
# Least squares from a runnable document
|
||||
|
||||
Fit a line through three points with an overdetermined `A x ≈ b` using `lstsq` (QR path). A heatmap makes the design matrix visible in `view`.
|
||||
|
||||
# main
|
||||
|
||||
`A` =
|
||||
$$
|
||||
\begin{bmatrix}1&0\\1&1\\1&2\end{bmatrix}
|
||||
$$
|
||||
|
||||
`b` =
|
||||
$$
|
||||
\begin{pmatrix}1\\2\\2\end{pmatrix}
|
||||
$$
|
||||
|
||||
*`A` = > la.from_formula formula=`A`*
|
||||
*`b` = > la.from_formula formula=`b`*
|
||||
|
||||
*`_` = > la.draw factor=`A` kind="heatmap" theme="light" path="ls-heatmap.svg"*
|
||||
|
||||
*`ls` = > la.lstsq a=`A` b=`b`*
|
||||
*`x` = ls[^x]*
|
||||
*`resid` = ls[^residual_fro]*
|
||||
|
||||
> print text=`x`
|
||||
> print text=`resid`
|
||||
> print text=ls-ok
|
||||
@@ -0,0 +1,12 @@
|
||||
# linalg-svd
|
||||
|
||||
Dense SVD via `ext/linalg`: singular values + structure / hinton SVG.
|
||||
|
||||
```bash
|
||||
cargo build --release -p marqdo_plugin_linalg
|
||||
marqdo ext add linalg
|
||||
marqdo run examples/linalg-svd/index.mq.md
|
||||
# optional: marqdo view examples/linalg-svd/
|
||||
```
|
||||
|
||||
Design: [ext-linalg.md](../../doc/design/ext-linalg.md) · sibling: [linalg-least-squares](../linalg-least-squares/).
|
||||
@@ -0,0 +1,25 @@
|
||||
---
|
||||
title: SVD structure demo
|
||||
description: Diagonal SVD + structure SVG via ext/linalg.
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# SVD from a runnable document
|
||||
|
||||
A diagonal matrix has singular values on the diagonal. Prefer matrix values and methods; `factorize` / `draw` stay explicit for teaching SVGs.
|
||||
|
||||
# main
|
||||
|
||||
`M` =
|
||||
$$
|
||||
\begin{bmatrix}4&0\\0&2\end{bmatrix}
|
||||
$$
|
||||
|
||||
*`M` = > la.from_formula formula=`M`*
|
||||
*`f` = > la.factorize matrix=`M` kind="svd"*
|
||||
*`S` = f[^S]*
|
||||
*`_` = > la.draw factor=`f` kind="svd" theme="light" path="svd-structure.svg"*
|
||||
*`hm` = > la.draw factor=`M` kind="hinton" path="svd-hinton.svg"*
|
||||
|
||||
> print text=`S`
|
||||
> print text=svd-ok
|
||||
@@ -0,0 +1,11 @@
|
||||
# linalg-transpose
|
||||
|
||||
Formula-document example: declare symbols with a GFM table, check \((AB)^\top = B^\top A^\top\) via `ascii` (auto-simplify).
|
||||
|
||||
```bash
|
||||
cargo build --release -p marqdo_plugin_linalg
|
||||
marqdo ext add linalg
|
||||
marqdo run examples/linalg-transpose/index.mq.md
|
||||
```
|
||||
|
||||
Design: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
|
||||
@@ -0,0 +1,29 @@
|
||||
---
|
||||
title: Transpose identity (formula document)
|
||||
description: (AB)^T = B^T A^T as a runnable lecture fragment.
|
||||
import la:ext/linalg/linalg.mq.md
|
||||
---
|
||||
|
||||
# Transpose reverses products
|
||||
|
||||
Declare shapes in a table, form \(P = AB\), then check \((AB)^\top = B^\top A^\top\) by running the document.
|
||||
|
||||
# main
|
||||
|
||||
`shapes` =
|
||||
|
||||
| @ | name | rows | cols |
|
||||
|---|------|------|------|
|
||||
| 1 | A | 2 | 3 |
|
||||
| 2 | B | 3 | 2 |
|
||||
|
||||
*`env` = > la.declare table=`shapes`*
|
||||
*`A` = env[^A]*
|
||||
*`B` = env[^B]*
|
||||
*`P` = `A` * `B`*
|
||||
*`t` = > `P`.T_ascii*
|
||||
> print text=`t`
|
||||
1. `t` == "B^T*A^T"
|
||||
> print text=identity-ok
|
||||
2. *
|
||||
> print text=identity-fail
|
||||
@@ -18,7 +18,8 @@ cargo run -- examples/marqdo-blog/index.mq.md
|
||||
- `/about` — 关于页
|
||||
- `/admin` — 会话门禁后台,登录 `admin` / `marqdo`,可增删改文章与标签
|
||||
- `/live` — WebSocket 回显端点
|
||||
- `/static/*` — 静态资源(`public/` 下的 `live.js`)
|
||||
- `/static/*` — 静态资源(`public/` 下的 `live.js`、favicon、logo)
|
||||
- `/favicon.ico` — 站点图标(`应用.图标` 表装配)
|
||||
|
||||
## 设计亮点(文档即代码)
|
||||
|
||||
@@ -29,6 +30,9 @@ cargo run -- examples/marqdo-blog/index.mq.md
|
||||
每个 `## 段`(基础/顶栏/侧栏/主体/卡片/页脚/表单/响应式)导出一张样式表,
|
||||
`## 全局` 用 `网页.样式装配` 函数把每张表装配成 CSS 文本,再 `text.str_join` 拼成完整样式表,
|
||||
最后经 `页面.样式` 注入页面。样式保持可读的数据表格,不写胶水代码。
|
||||
- **图标 / 头资源 / 图片装配**(W8):`应用.图标` 表挂 `/favicon.ico` 与 SVG;
|
||||
`页面.头装配` 写 apple-touch-icon;`页面.图片装配` 把 logo 表注入主区(`mq-images`)。
|
||||
含 `/` 的路径与 MIME 单元格需加引号(如 `"/static/logo.svg"`、`"image/png"`)。
|
||||
- **页面 = 组件装配 + 主体绑定**(`index.mq.md`):
|
||||
导航/侧栏/页脚用 `|组件|样式|` 表装配,文章列表用 `|属性|值|` 绑定 SQLite 字段。
|
||||
- **动态路由**:`/post/{slug}` 的 `slug` 注入查询条件,`页面.详情` 把首行渲染成文章。
|
||||
|
||||
@@ -64,6 +64,25 @@ import db:db/index.mq.md
|
||||
|----|--------|------|
|
||||
| 1 | admin | marqdo |
|
||||
|
||||
`站点图标` =
|
||||
|
||||
| 路径 | 关系 | 类型 | 尺寸 | 地址 |
|
||||
|------|------|------|------|------|
|
||||
| "public/favicon.png" | icon | "image/png" | 32x32 | "/favicon.ico" |
|
||||
| "public/favicon.svg" | icon | "image/svg+xml" | any | "/static/favicon.svg" |
|
||||
|
||||
`头资源` =
|
||||
|
||||
| 关系 | 地址 | 类型 |
|
||||
|------|------|------|
|
||||
| apple-touch-icon | "/static/favicon.png" | "image/png" |
|
||||
|
||||
`品牌图` =
|
||||
|
||||
| 源 | 替代 | 类 | 链接 | 宽度 | 加载 |
|
||||
|----|------|----|------|------|------|
|
||||
| "/static/logo.svg" | Marqdo | brand-logo | "/" | 40 | eager |
|
||||
|
||||
*store = > db.打开*
|
||||
|
||||
*首页CSS = > theme.全局*
|
||||
@@ -73,6 +92,8 @@ import db:db/index.mq.md
|
||||
*page = > page.主体装配 主体=`列表`*
|
||||
*page = > page.排序 排序="-created_at"*
|
||||
*page = > page.样式 样式=`首页CSS`*
|
||||
*page = > page.头装配 表=`头资源`*
|
||||
*page = > page.图片装配 表=`品牌图`*
|
||||
|
||||
*about = > 网页.页面 标题="关于" 引言="<h1>关于本站</h1><p>一个用 Marqdo 的 web 扩展库(ext/web)写成的博客系统。</p><p>它演示了:GFM 表格装配导航与侧栏、SQLite 驱动的主体绑定、动态路由 /post/{slug}、标签归档、以及受 session 保护的后台 CRUD。</p>"*
|
||||
*about = > about.组件装配 组件=`首页`*
|
||||
@@ -104,6 +125,7 @@ import db:db/index.mq.md
|
||||
*app = > app.路由 路径="/tags" 页面=tags*
|
||||
*app = > app.路由 路径="/tag/{slug}" 页面=tagged*
|
||||
*app = > app.静态 目录="public" 挂载="/static"*
|
||||
*app = > app.图标 表=`站点图标`*
|
||||
*app = > app.路由实时 路径="/live" 回显=True*
|
||||
*app = > app.鉴权 用户表=`管理员` 会话时长=3600*
|
||||
> `app`.监听
|
||||
@@ -0,0 +1,2 @@
|
||||
‰PNG
|
||||
|
||||
|
After Width: | Height: | Size: 8 B |
@@ -0,0 +1 @@
|
||||
<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><rect width="32" height="32" rx="6" fill="#1a5f4a"/><text x="16" y="22" text-anchor="middle" font-size="16" font-family="Georgia,serif" fill="#f4f7f5">M</text></svg>
|
||||
|
After Width: | Height: | Size: 226 B |
Loaded 100 of 254 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user