Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
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 | ||
|
|
1e5e6f4891 | ||
|
|
4c37e79dae | ||
|
|
9a8545b725 | ||
|
|
ee3116513b | ||
|
|
729357b7c0 | ||
|
|
07ab7d52c6 | ||
|
|
d7be903297 | ||
|
|
d0b184939f | ||
|
|
c36383bf28 | ||
|
|
eba0d703c5 | ||
|
|
dfb27d41dc | ||
|
|
cf4dbdeade | ||
|
|
f3fe7f268e | ||
|
|
88fe076216 | ||
|
|
4956460773 | ||
|
|
eafa203205 | ||
|
|
7317a653c7 | ||
|
|
0fddc3bf05 | ||
|
|
724a22e48d | ||
|
|
6db3da1cc0 | ||
|
|
86bfb0648c | ||
|
|
c6360adccb | ||
|
|
2d51f29199 | ||
|
|
323449c2c3 | ||
|
|
6808d56c9d | ||
|
|
e3b0314382 | ||
|
|
a900fd550f | ||
|
|
034f52b7e7 | ||
|
|
e7c9c21a49 | ||
|
|
be6223f1fb | ||
|
|
da9fc75b1e | ||
|
|
7645dd4c1f | ||
|
|
7dfa161422 | ||
|
|
b84e82eb56 | ||
|
|
d7924ea8c7 | ||
|
|
bd5555afaa | ||
|
|
f275d1e030 | ||
|
|
1bf414c745 | ||
|
|
ecc92f473a | ||
|
|
56b9bfa5a3 | ||
|
|
209dc4fc5d |
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
|
||||
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())
|
||||
+119
-18
@@ -4,8 +4,10 @@ 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/*, running marqdo CLI, or when the user mentions Marqdo,
|
||||
mq.md, markup-as-syntax, or code-as-documentation.
|
||||
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.
|
||||
---
|
||||
|
||||
# Marqdo development
|
||||
@@ -14,17 +16,24 @@ 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).
|
||||
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
|
||||
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
|
||||
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
|
||||
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are variables (strings need `"…"` / `'…'`; ticks still ok).
|
||||
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)
|
||||
|
||||
@@ -38,11 +47,11 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
|
||||
| Line `N. *` | Else arm |
|
||||
| `> fn args` | Call (named `k=v` or positional) |
|
||||
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
|
||||
| Frontmatter `> path.mq.md` [`as` / `作为` name] | Import (binds library name) |
|
||||
| Frontmatter `> use lib.member` [`as` name] / `使用` | Bind short name to a library path |
|
||||
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
|
||||
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
|
||||
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
|
||||
| `*…*` | Statement (bind / expr) |
|
||||
| `**…**` | Return value |
|
||||
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
|
||||
| `****` or `**` + spaces + `**` | Return `None` and end function body |
|
||||
| Lone `---` / `***` in function body | End function body (no value) |
|
||||
| GFM table after empty RHS bind | Collection (1-col list / ≥2-col map / `@`·`行`·`row` → list of maps); `` `x`[^1] `` / `` `m`[^key] `` |
|
||||
@@ -90,17 +99,17 @@ Chinese builtins (same functions, no import):
|
||||
## Statements, returns, branches
|
||||
|
||||
```markdown
|
||||
*`x` = 1*
|
||||
*`y` = `x` + 2*
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
```markdown
|
||||
*`n` = 0*
|
||||
*n = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
@@ -112,33 +121,110 @@ Chinese builtins (same functions, no import):
|
||||
|
||||
## Frontmatter imports + stdlib
|
||||
|
||||
Imports bind a **library name** (default = file stem; optional `as` / `作为`). Members are **not** flattened into the caller. Call with a bare dotted path:
|
||||
Imports use `import bind:target` (`导入` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: example
|
||||
> lib/text.mq.md
|
||||
> lib/time.mq.md as clock
|
||||
import text:lib/text.mq.md
|
||||
import clock:lib/time.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`xs` = > text.split value=a,b,c sep=,*
|
||||
*xs = > text.split value="a,b,c" sep=","*
|
||||
> print text=`xs`
|
||||
*`t` = > clock.now_unix *
|
||||
*t = > clock.now_unix*
|
||||
```
|
||||
|
||||
- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages).
|
||||
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
|
||||
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
|
||||
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
|
||||
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm` / `add agent` (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)).
|
||||
- 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 (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (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`.
|
||||
|
||||
Import **one language file** — never mix EN/ZH API names in the same `.mq.md`:
|
||||
|
||||
- EN: `import web:ext/web/web.mq.md`
|
||||
- ZH: `导入 网页:ext/web/网页.mq.md`
|
||||
|
||||
**Hard rules (web):**
|
||||
|
||||
- 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).
|
||||
|
||||
**Typical layout:**
|
||||
|
||||
```text
|
||||
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_*` → `app` + `static` / `listen`. Client: `marqdo wasm build -o static` + `web.client_embed source="/static/client.mq.md"` — **no author JS**; bridge may implement rich host effects ([browser-wasm-e.md](../../doc/roadmap/browser-wasm-e.md) · [browser-app](../../examples/browser-app/)).
|
||||
|
||||
**Shipped surface (W0–W7 + P3 + W8 + route D mount):** middleware + JSON API (`app.configure`); transactions, pagination, FTS search (`db.migrate`, `db.fts`, `db.search`); security (argon2, CSRF, SQLite sessions, login rate limit); SEO / RSS / Markdown (`page.meta`, `route_rss`, `lib/net.markdown_parse`); upload / download / gallery; sitemap / robots / error pages / redirects; RBAC (`app.gate`, user `role`); audit timestamps + FK in `db.init`; ETag on downloads; **W8** site icons (`app.icons` → `/favicon.ico`), head resource tables (`page.head`), image assembly (`make_images` / `page.images`); **D** `client_embed` auto-mount + DOM effect helpers (`text_patch` / `dom_patch`).
|
||||
|
||||
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).
|
||||
|
||||
## Official extension: `ext/quantum` (circuits + Q7/Q8)
|
||||
|
||||
Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --release -p marqdo_plugin_quantum`, then **`marqdo ext add quantum` again** so view loads the new `libquantum.so` (stale plugin = old black/white circuits).
|
||||
|
||||
- EN: `import quantum:ext/quantum/quantum.mq.md`
|
||||
- ZH: `导入 量子:ext/quantum/量子.mq.md`
|
||||
|
||||
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; ≤12 qubits for statevector; density-matrix ops ≤6 qubits; one language file per program; quote draw string args (`kind="…"`, `theme="…"`).
|
||||
|
||||
**Core:** `# circuit` / `# gate` / `# density` — table `steps=` or method chain; `simulate` / `probabilities` / `run` / `draw`.
|
||||
|
||||
**Q7 linear algebra:** `density`, `partial_trace`, `eig`, `expect` (Pauli string, left=high bit), `purity`, `kron`, `schmidt`, `fidelity`.
|
||||
|
||||
**Draw kinds:** `circuit|probs|bloch|hinton|city|density|paulivec|qsphere|multibloch`.
|
||||
|
||||
**Q8 themes (circuit / probs / bloch):** `theme="dark"|"light"|"bw"` (ZH `主题=`; **default `dark`** — slate lab look, gate-family colors, label chips so wires never cross `q0` text). View plot chrome follows `data-theme` on the SVG. Advanced kinds (hinton/…) still Q8c pending full re-skin.
|
||||
|
||||
```markdown
|
||||
*_ = > `qc`.draw kind="circuit" theme="dark"*
|
||||
*_ = > `qc`.draw kind="probs" theme="light"*
|
||||
```
|
||||
|
||||
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/).
|
||||
|
||||
## AI authoring workflow
|
||||
|
||||
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
|
||||
@@ -155,9 +241,20 @@ Stdlib map: [reference.md](reference.md).
|
||||
| `# main` then prose then code with no blank line | Blank line before code |
|
||||
| `if x > 0:` | `1. `x` > 0` |
|
||||
| `* > print text=hi *` | `> print text=hi` |
|
||||
| `` *`a` = 1 * `` (trailing space + backticks) | `*a = 1*` — bare bind, no trailing space before `*` / `**` |
|
||||
| `*xs = > text.split value=a,b sep=,*` (bare text args) | `*xs = > text.split value="a,b" sep=","*` — quote text literals; bare words are variables |
|
||||
| Forgetting `---` after nested `##` helper | Add `---` / `***` / `****` |
|
||||
| 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 |
|
||||
| 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`) |
|
||||
|
||||
## Checklist before finishing
|
||||
|
||||
@@ -167,4 +264,8 @@ Stdlib map: [reference.md](reference.md).
|
||||
- [ ] `# 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)
|
||||
@@ -38,14 +38,14 @@ Greeting via a nested function:
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*`a` = 2*
|
||||
*`b` = > add_one n=`a`*
|
||||
*a = 2*
|
||||
*b = > add_one n=`a`*
|
||||
> print text=`b`
|
||||
|
||||
## add_one
|
||||
+ `n`
|
||||
|
||||
**`n` + 1**
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
## 5. Branch with else
|
||||
@@ -53,7 +53,7 @@ Greeting via a nested function:
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*`n` = 0*
|
||||
*n = 0*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=positive
|
||||
@@ -78,6 +78,7 @@ Greeting via a nested function:
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
|
||||
## 6b. Map table + footnote get
|
||||
|
||||
```markdown
|
||||
@@ -89,10 +90,10 @@ Greeting via a nested function:
|
||||
|------|------|
|
||||
| 水果 | 蔬菜 |
|
||||
|
||||
*`种` = 分类[^苹果] *
|
||||
*种 = 分类[^苹果]*
|
||||
> print text=`种`
|
||||
|
||||
*`第一` = 篮子[^1] *
|
||||
*第一 = 篮子[^1]*
|
||||
```
|
||||
|
||||
One column → list; ≥2 columns + one data row → map; ≥2 columns + many rows → map of lists. Data cells are expressions (same as call-arg values): bare words, numbers, `` `var` ``, quoted strings; URLs and `gpt-4o-mini` stay text via path/hyphen folding. Footnotes: lists use 1-based digit indices; maps use key text (including digit keys like `[^00]`). Foreach on a map walks **keys**.
|
||||
@@ -106,20 +107,45 @@ Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of ma
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
|
||||
*`名` = `订单`[^1][^品名] *
|
||||
*名 = 订单[^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
|
||||
---
|
||||
title: split demo
|
||||
> lib/text.mq.md
|
||||
import text:lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`parts` = > split value=a,b,c sep=,*
|
||||
*parts = > split value=a,b,c sep=,*
|
||||
> print text=`parts`
|
||||
```
|
||||
|
||||
@@ -129,7 +155,7 @@ title: split demo
|
||||
# main
|
||||
|
||||
This whole paragraph is a comment, including lines that look like code:
|
||||
*`not_executed` = 1*
|
||||
*not_executed = 1*
|
||||
> print text=also still comment
|
||||
|
||||
After a blank line, code runs:
|
||||
@@ -142,12 +168,12 @@ After a blank line, code runs:
|
||||
```markdown
|
||||
---
|
||||
description: loads math
|
||||
> lib/math.mq.md
|
||||
import math:lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`t` = > num value=3.5*
|
||||
*t = > num value=3.5*
|
||||
> print text=`t`
|
||||
```
|
||||
|
||||
@@ -163,16 +189,16 @@ See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` construc
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*`msg` = "Hello, `who`!" *
|
||||
**`msg`**
|
||||
*msg = "Hello, `who`!"*
|
||||
**msg**
|
||||
|
||||
# Loud = > Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*`msg` = "HELLO, `who`!" *
|
||||
**`msg`**
|
||||
*msg = "HELLO, `who`!"*
|
||||
**msg**
|
||||
```
|
||||
|
||||
`_type` stays the most specific name (`Loud`). Methods walk the base chain; same-name `##` on the child overrides. **No implicit super** — if the child needs parent fields, call the parent explicitly:
|
||||
@@ -181,24 +207,24 @@ See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` construc
|
||||
# Child = > Parent
|
||||
+ `name`
|
||||
|
||||
*`self` = > Parent name=`name` *
|
||||
*`self` = > json.set map=`self` key=extra value=1 *
|
||||
**`self`**
|
||||
*self = > Parent name=`name`*
|
||||
*self = > json.set map=`self` key=extra value=1*
|
||||
**self**
|
||||
```
|
||||
|
||||
## 11. Agent layout (ABI)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/agent.mq.md
|
||||
import agent:ext/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
> load_native
|
||||
|
||||
*`ws` = > agent *
|
||||
*`n` = > `ws`.ensure_layout *
|
||||
*ws = > agent*
|
||||
*n = > `ws`.ensure_layout*
|
||||
> print text=`n`
|
||||
```
|
||||
|
||||
@@ -232,3 +258,71 @@ if x > 0:
|
||||
2. *
|
||||
> print text=y-other
|
||||
```
|
||||
|
||||
## 13. Dynamic site (ext/web, minimal)
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: hello-site
|
||||
import web:ext/web/web.mq.md
|
||||
import db:db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`shell` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav | |
|
||||
|
||||
`main` =
|
||||
|
||||
| 属性 | 值 | 样式 |
|
||||
|------|-----|------|
|
||||
| title | posts.title | |
|
||||
| body | posts.summary | |
|
||||
|
||||
*store = > db.open*
|
||||
*css = "body{font-family:sans-serif}"*
|
||||
*page = > web.page title="Hello"*
|
||||
*page = > page.compose_components components=`shell`*
|
||||
*page = > page.compose_main main=`main`*
|
||||
*page = > page.css css=`css`*
|
||||
*app = > web.app page=`page` port=8080*
|
||||
*app = > app.static prefix="/static" dir="static"*
|
||||
> listen app=`app`
|
||||
```
|
||||
|
||||
- Import `ext/web/web.mq.md` **or** `ext/web/网页.mq.md` — not both; match API language to the file.
|
||||
- Full blog/CMS patterns: `examples/marqdo-blog/` (routes, SEO, RSS, auth, upload, WS).
|
||||
- Run after `marqdo ext add web` and building `marqdo_plugin_web`.
|
||||
|
||||
## 14. Quantum entanglement lab (ext/quantum Q7/Q8)
|
||||
|
||||
```markdown
|
||||
---
|
||||
import quantum:ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`steps` =
|
||||
|
||||
| step | gate | qubits |
|
||||
|------|------|--------|
|
||||
| 1 | H | 0 |
|
||||
| 2 | CX | 0,1 |
|
||||
|
||||
*qc = > quantum.circuit qubits=2 steps=`steps`*
|
||||
*rho = > `qc`.density*
|
||||
*red = > `rho`.partial_trace keep=0*
|
||||
*sch = > `qc`.schmidt cut=1*
|
||||
*_ = > `qc`.draw kind="circuit" theme="dark"*
|
||||
*_ = > `qc`.draw kind="hinton"*
|
||||
> print text=`red`
|
||||
```
|
||||
|
||||
- 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.
|
||||
@@ -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
|
||||
marqdo ext remove llm|agent
|
||||
marqdo ext add llm|agent|web|quantum
|
||||
marqdo ext remove llm|agent|web|quantum
|
||||
```
|
||||
|
||||
Diagnostics look like `path:line:col: message` (1-based line/col).
|
||||
@@ -22,7 +22,7 @@ Diagnostics look like `path:line:col: message` (1-based line/col).
|
||||
|
||||
Stdlib search order for `lib/…` imports: `MARQDO_LIB`, `./lib`, directory of the `marqdo` executable (and a few parents). Prefer the **bundle zip** (`marqdo.exe` + `lib/`) over a bare exe.
|
||||
|
||||
官方扩展(`ext/…`,非 stdlib):`marqdo ext add` 装到 `MARQDO_EXT` 或 `~/.marqdo/ext`;导入仍写 `> ext/llm.mq.md`。解析还含 cwd `ext/`、二进制旁 `ext/`。对象:`doc/design/objects.md`。Agent:`doc/design/ext-agent.md` · 安装器:`doc/design/ext-cli.md`。
|
||||
官方扩展(`ext/…`,非 stdlib):`marqdo ext add` 装到 `MARQDO_EXT` 或 `~/.marqdo/ext`;导入仍写 `import llm:ext/llm.mq.md`。解析还含 cwd `ext/`、二进制旁 `ext/`。对象:`doc/design/objects.md`。Agent:`doc/design/ext-agent.md` · 安装器:`doc/design/ext-cli.md`。
|
||||
|
||||
## Builtins (no import)
|
||||
|
||||
@@ -44,24 +44,65 @@ 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/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 |
|
||||
|
||||
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
|
||||
|
||||
## ext/web (dynamic sites)
|
||||
|
||||
Install: `marqdo ext add web` (`网页`). Native: `cargo build --release -p marqdo_plugin_web`.
|
||||
|
||||
| EN import | ZH import | Core types |
|
||||
|-----------|-----------|------------|
|
||||
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | `# page` `# style` `# db` `# form` `# app` `# auth` `# cache` `# storage` |
|
||||
|
||||
| Area | EN methods (representative) | Notes |
|
||||
|------|----------------------------|-------|
|
||||
| Page | `compose_components`, `compose_main`, `render`, `meta`, `paginate` | GFM tables; cells are literal path strings |
|
||||
| DB | `init`, `insert`, `select`, `paginate`, `get`, `update`, `delete`, `migrate`, `fts`, `search`, `count`, `事务`/`txn` | init supports `unique`/`index`/`fk`; auto `created_at`/`updated_at` |
|
||||
| App | `route`, `static`, `configure`, `listen`, `auth`, `gate`, `upload`, `download`, `gallery`, `route_rss`, `redirect`, `error_page`, `sitemap`, `robots` | W0–W7 + P3 complete |
|
||||
| Auth | `login`, `check`, `logout`, `hash_password` | argon2 + CSRF + SQLite sessions; `role` for RBAC |
|
||||
|
||||
Drivers (Postgres / Redis / S3): `db url=postgres://…`, `cache url=memory:`, `storage url=file:…` — see `doc/design/ext-web-drivers.md`.
|
||||
|
||||
Example project: `examples/marqdo-blog/`. Capability matrix: `doc/design/web-net-capabilities.md`.
|
||||
|
||||
## ext/quantum (circuits + Q7/Q8)
|
||||
|
||||
Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p marqdo_plugin_quantum`, then re-run `ext add` so view picks up the new `.so`.
|
||||
|
||||
| EN import | ZH import | Core types |
|
||||
|-----------|-----------|------------|
|
||||
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | `# circuit` `# gate` `# density` |
|
||||
|
||||
| Area | EN APIs | Notes |
|
||||
|------|---------|-------|
|
||||
| Circuit | `h`/`cx`/…, `simulate`, `probabilities`, `run`, `draw`, `noise` | `steps=` GFM table; ≤12 qubits |
|
||||
| Gate | `matrix`, `matches_matrix`, `draw` | named or `matrix=` custom unitary |
|
||||
| Density (Q7) | `purity`, `partial_trace`, `eig`, `expect`, `draw` | ≤6 qubits for dense ρ |
|
||||
| Free (Q7) | `kron`, `schmidt`, `fidelity` | top-level on import bind |
|
||||
| Draw kinds | `circuit\|probs\|bloch\|hinton\|city\|density\|paulivec\|qsphere\|multibloch` | quote `kind="…"` |
|
||||
| Themes (Q8) | `theme="dark"\|"light"\|"bw"` (ZH `主题=`) | default **dark**; circuit/probs/bloch themed; SVG `data-theme` |
|
||||
|
||||
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`.
|
||||
|
||||
## Formula + plot (math)
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/math.mq.md
|
||||
import math:lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -71,7 +112,7 @@ $$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*`_svg` = > plot formula=`f` var=x min=-3 max=3 *
|
||||
*_svg = > plot formula=`f` var=x min=-3 max=3*
|
||||
```
|
||||
|
||||
Empty RHS assignment + following `$$…$$` binds a formula value. Narrative-only `$$` without binding is display, not assignment.
|
||||
@@ -80,7 +121,7 @@ Empty RHS assignment + following `$$…$$` binds a formula value. Narrative-only
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/foreign.mq.md
|
||||
import foreign:lib/foreign.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -132,4 +173,9 @@ See `doc/design/call-arguments.md`.
|
||||
| `doc/design/ext-llm.md` | `ext/llm` |
|
||||
| `doc/design/ext-agent.md` | `ext/agent` agent **framework** (layout shipped; LLM orchestration roadmap) |
|
||||
| `doc/design/ext-cli.md` | `marqdo ext list/add/remove` |
|
||||
| `doc/design/ext-web.md` | `ext/web` dynamic sites (author API) |
|
||||
| `doc/design/web-net-capabilities.md` | ext/web capability matrix (W0–W7 + P3) |
|
||||
| `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/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=
|
||||
@@ -11,6 +11,7 @@ on:
|
||||
- "Cargo.lock"
|
||||
- ".github/workflows/pages.yml"
|
||||
- "scripts/build-public.*"
|
||||
- "scripts/run-public-pages.sh"
|
||||
workflow_dispatch:
|
||||
|
||||
permissions:
|
||||
@@ -26,11 +27,8 @@ jobs:
|
||||
uses: dtolnay/rust-toolchain@stable
|
||||
|
||||
- name: Build & export site
|
||||
run: |
|
||||
cargo build --release
|
||||
find public -name '*.mq.md' ! -name 'utils.mq.md' ! -name '¹¤¾ß.mq.md' -print0 \
|
||||
| xargs -0 -n1 ./target/release/marqdo run
|
||||
./target/release/marqdo view output public -o public
|
||||
shell: bash
|
||||
run: bash scripts/run-public-pages.sh
|
||||
|
||||
- name: Verify site shape
|
||||
run: |
|
||||
|
||||
@@ -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
|
||||
|
||||
- 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,25 @@ 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"
|
||||
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"
|
||||
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
|
||||
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
|
||||
$stageLib = "dist/stage-stdlib"
|
||||
@@ -85,6 +102,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,22 +110,21 @@ jobs:
|
||||
body: |
|
||||
## Marqdo ${{ github.ref_name }}
|
||||
|
||||
### Highlights — extension libraries
|
||||
- Official **`ext/`** packages: `llm`, `agent`, `web`, `quantum` (not stdlib)
|
||||
- Install: `marqdo ext list` / `marqdo ext add llm|agent|web|quantum`
|
||||
- Native plugins: `cargo build --release -p marqdo_plugin_*` then `ext add`
|
||||
### 亮点 / Highlights
|
||||
- **`marqdo ext add` 无需本机 Rust**:发布附带预编译 native 插件;`ext add` 可自动下载
|
||||
- **Prebuilt native plugins**: `marqdo-*-native-*.zip`; Windows zip includes `ext/native/`
|
||||
- Install: `marqdo ext add web|agent|quantum|llm`(零源码编译)
|
||||
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [ext-cli.md](https://github.com/cflmy/marqdo/blob/main/doc/design/ext-cli.md)
|
||||
|
||||
Also: embedded stdlib, writeback/subtask, Variables modal in `view`, VSIX from branch **`vscode-extension`**.
|
||||
|
||||
### 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 |
|
||||
@@ -118,9 +135,41 @@ 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
|
||||
|
||||
- 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
|
||||
(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 }}
|
||||
+20
@@ -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/
|
||||
@@ -46,5 +54,17 @@ plugins/*/tmp/
|
||||
# web smoke/example DBs (cwd-relative or fixture data dirs)
|
||||
/web-fixtures/
|
||||
/tests/ext/web-fixtures/data/
|
||||
/tests/ext/entrydir-fixtures/data/
|
||||
/examples/web-site/data/
|
||||
/examples/web-site-zh/data/
|
||||
/examples/web-net-site/data/
|
||||
/examples/web-net-site-zh/data/
|
||||
/examples/marqdo-blog/data/
|
||||
|
||||
# Quantum draw/SVG runtime outputs (sources & gold .mq.md stay tracked)
|
||||
/tests/ext/quantum-*.svg
|
||||
/examples/quantum-*/**/*.svg
|
||||
/examples/quantum-*/*.svg
|
||||
|
||||
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
|
||||
/ext/native/
|
||||
+177
@@ -1,5 +1,182 @@
|
||||
# Changelog
|
||||
|
||||
## Unreleased
|
||||
|
||||
### Added
|
||||
|
||||
### Fixed
|
||||
|
||||
### 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
|
||||
|
||||
本版把 **`ext/web` 网络能力(W0–W7 + P3)**、**`ext/quantum` Q7/Q8**、**`ext/agent` A1–A4** 一并收口到正式发布;并修了网页扩展叙述行误解析、补充 ASGI/生产部署说明与 agent 下一波(B0–B5)缺口调研。
|
||||
|
||||
**如何拿到本版**
|
||||
|
||||
```bash
|
||||
# 从源码(推荐跟 main / 本 tag)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v0.3.0
|
||||
cargo build --release
|
||||
./target/release/marqdo version
|
||||
|
||||
# 或从 GitHub Releases 下载 Windows 包 / 源码 zip(见 Release 资产)
|
||||
marqdo version --check
|
||||
```
|
||||
|
||||
**扩展(非 stdlib)**
|
||||
|
||||
```bash
|
||||
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
|
||||
marqdo ext add web && marqdo ext add agent && marqdo ext add quantum
|
||||
# 中文 id:网页 / 智能体 / 量子 / 大模型
|
||||
```
|
||||
|
||||
### Added
|
||||
- **调研:`ext/agent` A0–A4 之后缺口** ([agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)):产品化示例、评测 harness、真 MCP、plan resume/HITL、飞轮指标与建议分期 B0–B5;挂到 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md) 与 [doc/README.md](doc/README.md)。
|
||||
- **生产部署调研(ASGI)** ([web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)):不能挂 Daphne/Uvicorn;路径为反向代理 → 嵌入式 `listen`(axum)。
|
||||
- **`ext/agent` A4(RAG/MCP 证据工具)**: `corpus_search` 本地语料关键词检索;`mcp_list_tools` / `mcp_call` 读 JSON fixture;返回 `authority=workbook`。金样 `agent-tools-rag-a4`。
|
||||
- **`ext/agent` A3(上下文预算)**: `source_brief` / 加深版 `skill_brief`;`build_step_context` 默认截断并提示 `READ:source|skill`;`step` 支持最多 `max_reads` 次加深;父 `READ:skill`。金样 `agent-context-budget-a3`。
|
||||
- **`ext/agent` A2(过程可见)**: `plan` 过程事件默认写入返回 map 的 `events`(SSE 仍仅 `stream=True`);OKF 命中记 `REUSE` decision;view plan 卡渲染过程时间线。对齐 [agent-streaming.md](doc/roadmap/agent-streaming.md)。
|
||||
- **`ext/agent` A1(OKF 复用飞轮)**: `agent_kb_list_tasks` 返回 description/aliases/status/llm_free/hits;`plan` 命中路径暴露 `match`/`score`(summary 含 match kind);soft_match 策展提示带 status/llm_free/description;view plan 卡显示 match。金样 `agent-kb-plan-hit`。路线 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md)。
|
||||
- **`ext/web` 样式装配(`web_style` / `网页.样式装配`)**: 样式即数据表格 —— GFM 样式表(`|选择器|属性|值|`,可用 `|媒体|` 列分组进 `@media` 块)经 `样式装配` 函数转成 CSS 文本,再拼装成完整主题。替代"整段手写 CSS 字符串"的写法,贯彻 文档即代码。见 [marqdo-blog](examples/marqdo-blog/styles/theme.mq.md)。
|
||||
- **网络能力调研(`doc/design/web-net-capabilities.md`)**: 盘点 `ext/web` + `plugins/web` + `lib/net` 现状,对照主流语言网络栈(FastAPI / Express / Flask / axum),给出「开发一个完整 Web 项目」所需能力的差距清单与分波次补强路线(W1–W7 + P3,**2026-08-28 已全部落地**)。
|
||||
- **AI Skill + 文档(ext/web 完结复核)**: `skills/marqdo/` 与 `.cursor/skills/marqdo/` 增加 **ext/web 动态站** 专节(硬规则、API 摘要、§13 最小站点样例);`doc/design/web-net-capabilities.md` 结论/对照表与 W7+P3 实现对齐;`doc/design/ai-skill.md` 更新用途说明。
|
||||
- **`ext/quantum` Q7(高阶线性代数 + 高级可视化)**: 密度矩阵 / 部分迹 / Hermitian 谱 / Schmidt / Pauli 期望 / 纯度;SVG:hinton、city、density、paulivec、qsphere、multibloch。全部经 `plugins/quantum` ABI。设计 [ext-quantum-q7.md](doc/design/ext-quantum-q7.md);金样 `quantum-linalg-smoke`、`quantum-viz-advanced-smoke`;示例 [quantum-entanglement](examples/quantum-entanglement/)。
|
||||
- **`ext/quantum` Q8a/Q8b(可视化美学)**: `draw theme=dark|light|bw`(默认 dark);标签芯片 + gutter 消除线穿字;门族分色;probs/bloch 共用令牌;view 对 `data-theme` 换图框。设计 [ext-quantum-viz-style.md](doc/design/ext-quantum-viz-style.md)。改插件后须 `marqdo ext add quantum` 再开 view。
|
||||
|
||||
### Fixed
|
||||
- **`ext/web` / `网页.mq.md`**:叙述行勿以反引号开头,避免被解析为语句(`examples/marqdo-blog` 可正常 `listen`)。
|
||||
|
||||
### Changed
|
||||
- **Frontmatter import syntax**: `import bind:target` / `导入 bind:target` (file `.mq.md` or short name `lib.member`). Removed legacy `> path.mq.md` / `> use` imports. See [module-namespace.md](doc/design/module-namespace.md).
|
||||
|
||||
## v0.2.0 — 2026-08-12
|
||||
|
||||
### Highlights — official extension libraries
|
||||
|
||||
Generated
+935
-8
File diff suppressed because it is too large.
Load diff
+46
-9
@@ -1,6 +1,6 @@
|
||||
[package]
|
||||
name = "marqdo"
|
||||
version = "0.2.0"
|
||||
version = "0.3.5"
|
||||
edition = "2021"
|
||||
license = "Apache-2.0"
|
||||
description = "Marqdo — Markdown markers as an interpreted programming language"
|
||||
@@ -10,27 +10,64 @@ 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 }
|
||||
# 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",
|
||||
"crates/marqdo-wasm",
|
||||
]
|
||||
resolver = "2"
|
||||
|
||||
[dev-dependencies]
|
||||
assert_cmd = "=2.0.14"
|
||||
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"
|
||||
@@ -89,6 +89,8 @@ marqdo sync [PATH] -o OUT_DIR # catalog 的别名
|
||||
|
||||
产物示例:`catalog.yaml`、`index.md`、`modules/*.md`(`type: Marqdo Module` 等)。设计见 [generated-yaml-manifest.md](doc/design/generated-yaml-manifest.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
|
||||
|
||||
智能体框架横向调研(LangGraph / CrewAI / 厂商 SDK 等 vs Marqdo 文档驱动优势):[agent-frameworks-and-marqdo.md](doc/research/agent-frameworks-and-marqdo.md) · 优化路线 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md)。
|
||||
|
||||
```bash
|
||||
cargo run -- catalog public -o .marqdo
|
||||
# 或已安装二进制时:
|
||||
@@ -97,7 +99,7 @@ marqdo catalog public -o .marqdo
|
||||
|
||||
---
|
||||
|
||||
## 现状(v0.2.0)
|
||||
## 现状(v0.3.5)
|
||||
|
||||
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
|
||||
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
|
||||
@@ -105,27 +107,69 @@ 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、网络、数学、外联、插件、**自写回**、**子任务**
|
||||
- **官方扩展库 `ext/`**(本版重点,**非** stdlib):`llm` · `agent` · `web` · `quantum`。安装:`marqdo ext list` / `add …` / `remove`(见 [ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext` 或 `MARQDO_EXT`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`。设计:[ext-llm](doc/design/ext-llm.md) · [ext-agent](doc/design/ext-agent.md) · [ext-web](doc/design/ext-web.md) · [ext-quantum](doc/design/ext-quantum.md)
|
||||
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**
|
||||
- **官方扩展库 `ext/`**(**非** stdlib,本版收口):
|
||||
- **`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/)
|
||||
- **`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}`
|
||||
- **用户静态站**:`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.5)
|
||||
|
||||
```bash
|
||||
# 1) 源码安装(跟 tag 或 main)
|
||||
git clone https://github.com/cflmy/marqdo.git && cd marqdo
|
||||
git checkout v0.3.5 # 或留在 main
|
||||
cargo build --release
|
||||
export PATH="$PWD/target/release:$PATH"
|
||||
marqdo version
|
||||
marqdo version --check
|
||||
|
||||
# 2) 跑解释器 / 文档站 / catalog
|
||||
marqdo run tests/structure/hello.mq.md
|
||||
marqdo run tests/structure/hello.mq.md --backend bytecode
|
||||
marqdo view public --no-open
|
||||
marqdo debug public --no-open
|
||||
marqdo catalog public -o .marqdo
|
||||
|
||||
# 3) 安装官方扩展(Release 用户:无需本机 Rust)
|
||||
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native
|
||||
marqdo ext add agent # 或:智能体
|
||||
marqdo ext add quantum # 或:量子
|
||||
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 地址;/favicon.ico 与 logo 装配见 W8
|
||||
|
||||
# 5) 浏览器 WASM(可选)
|
||||
marqdo wasm build
|
||||
# → dist/wasm/ … 见 examples/browser-hello/
|
||||
|
||||
# 6) Windows:也可从 GitHub Releases 下载 exe / zip / vsix
|
||||
# https://github.com/cflmy/marqdo/releases/tag/v0.3.5
|
||||
```
|
||||
|
||||
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
|
||||
|
||||
```bash
|
||||
cargo run -- run tests/structure/hello.mq.md
|
||||
cargo run -- run tests/structure/hello.mq.md --backend bytecode
|
||||
cargo run -- view public --no-open
|
||||
cargo run -- debug public --no-open
|
||||
cargo run -- catalog public -o .marqdo
|
||||
cargo run -- view output public -o public
|
||||
powershell -File ./scripts/build-public.ps1
|
||||
```
|
||||
|
||||
**发布包(GitHub Releases)**:单独二进制 **已内置**官方 `lib/`(`> lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发。**扩展库**用 `marqdo ext add llm|agent|web|quantum` 安装(见 [CHANGELOG](CHANGELOG.md) 与 [ext-cli.md](doc/design/ext-cli.md));原生 `.so`/`.dll` 需本地编译或从带 `native/` 的安装目录解析。`marqdo version --check` 可查看是否有新版本。
|
||||
|
||||
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md)
|
||||
**发布包(GitHub Releases)**:单独二进制 **已内置**官方 `lib/`(`import …:lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发。**扩展库**用 `marqdo ext add …` 安装(见 [CHANGELOG](CHANGELOG.md) 与 [ext-cli.md](doc/design/ext-cli.md));原生 `.so`/`.dll` 需本地编译或从带 `native/` 的安装目录解析。
|
||||
|
||||
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md) · 变更 [CHANGELOG.md](CHANGELOG.md)
|
||||
---
|
||||
|
||||
## 命名
|
||||
|
||||
@@ -0,0 +1,15 @@
|
||||
[package]
|
||||
name = "marqdo-wasm"
|
||||
version = "0.3.5"
|
||||
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");
|
||||
}
|
||||
}
|
||||
+13
-1
@@ -40,6 +40,10 @@
|
||||
| [design/ext-agent-plan.md](design/ext-agent-plan.md) | **`## 多步` / `## plan` 锁定设计**(工作簿文件、subtask 执行、修订循环、`step` 默认写回) |
|
||||
| [design/ext-cli.md](design/ext-cli.md) | **`marqdo ext list/add/remove` 官方扩展安装器** |
|
||||
| [design/ext-web.md](design/ext-web.md) | **官方扩展 `ext/web`(页面/库表/绑定/后台;ABI + CLI;设计锁定)** |
|
||||
| [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/ 金样例目录布局** |
|
||||
| [design/view.md](design/view.md) | **`marqdo view` / `view output` 黑白极简 + 静态文档** |
|
||||
@@ -57,9 +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 之后缺口盘点** |
|
||||
| [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 / 关键字纪律 |
|
||||
@@ -3,22 +3,22 @@
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | 已提供 |
|
||||
| 日期 | 2026-08-05 |
|
||||
| 日期 | 2026-08-05(初版)· 2026-08-28(ext/web 完结复核 · ext/quantum Q8) |
|
||||
| 路径 | [`skills/marqdo/`](../../skills/marqdo/)(权威);Cursor 镜像 [`.cursor/skills/marqdo/`](../../.cursor/skills/marqdo/) |
|
||||
|
||||
---
|
||||
|
||||
## 目的
|
||||
|
||||
让接入方(Cursor Agent、其它支持 Agent Skills 的模型宿主)在**加载本 skill 后**即可按 v0.1 语法正确编写 / 修改 `.mq.md`,而不把 Markdown 习惯或 Python 控制流误套到 Marqdo。
|
||||
让接入方(Cursor Agent、其它支持 Agent Skills 的模型宿主)在**加载本 skill 后**即可按 v0.2 语法正确编写 / 修改 `.mq.md`,并在使用 **`ext/web` 动态站** 或 **`ext/quantum` 电路/可视化** 时遵循官方作者面(不混中英 API、不写 JSON 袋胶水;量子绘图须引用 `kind=`/`theme=` 字符串)。
|
||||
|
||||
## 内容
|
||||
|
||||
| 文件 | 用途 |
|
||||
|------|------|
|
||||
| `SKILL.md` | 必读:硬规则、标记表、工作流、反模式 |
|
||||
| `reference.md` | 按需:CLI、stdlib 索引、边界 |
|
||||
| `examples.md` | 按需:可复制样例 |
|
||||
| `SKILL.md` | 必读:硬规则、标记表、**ext/web**、**ext/quantum(Q7/Q8)**、工作流、反模式 |
|
||||
| `reference.md` | 按需:CLI、stdlib/ext 索引、web/quantum API 摘要 |
|
||||
| `examples.md` | 按需:可复制样例(§13 最小站点 · §14 纠缠实验) |
|
||||
|
||||
## 使用
|
||||
|
||||
|
||||
@@ -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` 打印闭环 |
|
||||
@@ -32,6 +32,9 @@ positional ::= value_token
|
||||
|
||||
- `value`(具名右侧):可含空格与 `` `var` `` 插值,直到下一个 `ident=` 边界。
|
||||
- `value_token`(位置):空白分隔的一个词法单元——数字、`` `名` ``、标识/文本词;**不含空格**。多词字符串请用具名,例如 `> print text=Hello World!`。
|
||||
- 实参值中 `` `变量` `` 后**紧跟** `[^…]` 时按**脚注取元**解析(可链式),而非文本:`> print text=苹果单价:`水果价格`[^苹果]`、`> print text=`订单`[^2][^品名]`。
|
||||
- **独立 `>` 调用**:裸词 = 文本字面量。
|
||||
- **`*…*` / `**…**` 段内的调用**(如 `*x = > text.split value=src sep=","*`):裸词 = **变量**(Python 统一命名空间),文本字面量必须加引号(`value="a,b"`);`` `名` `` 变量形式仍合法。
|
||||
- 内置 `print` / `打印` 形参:`text` ≡ `内容`。
|
||||
- `input` / `输入`:`prompt` ≡ `提示`。
|
||||
- `len` / `长度`、`str` / `文本`、`int` / `整数`:`value` ≡ `值`。
|
||||
|
||||
@@ -41,7 +41,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
│
|
||||
├─① 行分类(自研) 无标记 → 注释;有标记 → 代码行
|
||||
├─② GFM 块/行内(库) 标题、表、强调、列表结构
|
||||
├─③ 行扫描补强(自研) 保留 '-' / '+';frontmatter `> file.mq.md`
|
||||
├─③ 行扫描补强(自研) 保留 '-' / '+';frontmatter `import file:file.mq.md`
|
||||
└─④ Marqdo 语法(自研) 递归下降:Module/Fun/Stmt/Expr → AST
|
||||
└─ 表达式子语言 可手写,或仅对 Expr 用 pest/nom
|
||||
```
|
||||
@@ -80,7 +80,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
|
||||
| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 |
|
||||
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
|
||||
| **clap** | CLI | `marqdo run [path]` |
|
||||
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`> x.mq.md` 仍按**行**抽取(见 Spike) |
|
||||
| **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`) |
|
||||
|
||||
#### 强烈建议
|
||||
|
||||
@@ -61,7 +61,7 @@ Unknown names fail. Queries are only valid during a plugin function call (host s
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/plugin.mq.md
|
||||
import plugin:lib/plugin.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -82,8 +82,11 @@
|
||||
| `stderr_tail` / `stdout_tail` | 子任务捕获尾部 ~2KiB | `READ:stderr` / `READ:stdout` |
|
||||
| `value` | ≤200 字;否则 `value_preview` + `value_len` | (一般不必加深) |
|
||||
| `slots` | `{key,line,body_len}`;`error` 槽可带短预览 | `READ:slots` |
|
||||
| `skill_brief`(父 / 子) | ~1.2KiB(`skill_brief`) | `READ:skill` → ~4KiB |
|
||||
| `has_worker_step` / `solidify_on_done` | 布尔提示 | — |
|
||||
|
||||
`## step` 同样默认注入 **预算后的** `source_brief` + `skill_brief`(非全文);截断处带 `[truncated …; emit READ:…]` 标记,子轮最多 `max_reads` 次加深后再 CALL/作答。
|
||||
|
||||
`quiet=True` **只表示不污染父 TTY**;file `wait` 仍返回截断后的 `stdout` / `stderr` 供父观察。
|
||||
|
||||
---
|
||||
@@ -100,6 +103,10 @@
|
||||
| `workbook_excerpt` | 结构摘录(默认观察同源) |
|
||||
| `lib_catalog` | 枚举 `lib/*.mq.md` 能力摘要 |
|
||||
| `scratch_tool_write` | 写入 `.marqdo/agent-runs/tools/<name>.mq.md` |
|
||||
| `corpus_search` | 本地语料关键词检索(RAG-lite;`ARGS.query` / `root`) |
|
||||
| `mcp_list_tools` / `mcp_call` | MCP 形 JSON fixture 列工具 / 调用(离线证据) |
|
||||
|
||||
以上 **corpus / mcp** 返回一律带 `authority=workbook`:检索与外置工具只是证据,**可跑的 `.mq.md` 工作簿 / OKF 技能仍是权威真相**。
|
||||
|
||||
### 6.2 标准库与造工具
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@
|
||||
| 状态 | **Accepted;D2a–D2f 已落地;父 Plan-and-Move / OKF 软命中见配套文档** |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 父文档 | [ext-agent.md](ext-agent.md) |
|
||||
| 相关 | [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move 行动面**) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [module-namespace.md](module-namespace.md) · [ai-skill.md](ai-skill.md) · [objects.md](objects.md) |
|
||||
| 相关 | [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move 行动面**) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [module-namespace.md](module-namespace.md) · [ai-skill.md](ai-skill.md) · [objects.md](objects.md) · [调研:主流框架与 Marqdo](../research/agent-frameworks-and-marqdo.md) |
|
||||
|
||||
---
|
||||
|
||||
@@ -159,11 +159,11 @@ REPLACE
|
||||
```markdown
|
||||
---
|
||||
title: agent-run-…
|
||||
> ext/ai/llm.mq.md
|
||||
> ext/ai/agent.mq.md
|
||||
> lib/json.mq.md
|
||||
> lib/writeback.mq.md
|
||||
> lib/subtask.mq.md
|
||||
import llm:ext/ai/llm.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import json:lib/json.mq.md
|
||||
import writeback:lib/writeback.mq.md
|
||||
import subtask:lib/subtask.mq.md
|
||||
---
|
||||
|
||||
# 总目标
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|---|---|
|
||||
| Status | **Accepted · redesign**(取代「thin TOOL: loop」方案) |
|
||||
| Date | 2026-08-07 |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
|
||||
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [**调研:主流框架与 Marqdo 优势**](../research/agent-frameworks-and-marqdo.md) · [**缺口:A0–A4 之后**](../research/agent-framework-gaps-after-a4.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
|
||||
|
||||
## 0. 为什么要改掉旧方案
|
||||
|
||||
@@ -72,10 +72,10 @@ Marqdo 的宪法是 **代码即文档、文档即知识库**:
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/ai/智能体.mq.md
|
||||
> ext/ai/大模型.mq.md
|
||||
> lib/自写回.mq.md
|
||||
> lib/时间.mq.md
|
||||
导入 智能体:ext/ai/智能体.mq.md
|
||||
导入 大模型:ext/ai/大模型.mq.md
|
||||
导入 自写回:lib/自写回.mq.md
|
||||
导入 时间:lib/时间.mq.md
|
||||
---
|
||||
|
||||
## 获取时间
|
||||
@@ -152,7 +152,7 @@ ext/
|
||||
| **`lib/writeback`** | 持久化输出块 |
|
||||
| **`lib/subtask`** | **工具调用与(多步时)子智能体并行的执行通道**;见 [stdlib-subtask.md](stdlib-subtask.md) |
|
||||
|
||||
安装:[`ext-cli.md`](ext-cli.md) — `marqdo ext add agent` / `add llm`(`.mq.md` + `native/libagent.so`)。导入:`> ext/ai/智能体.mq.md`。
|
||||
安装:[`ext-cli.md`](ext-cli.md) — `marqdo ext add agent` / `add llm`(`.mq.md` + `native/libagent.so`)。导入:`导入 智能体:ext/ai/智能体.mq.md`。
|
||||
|
||||
**原生插件(ABI v2)**:`ext/ai/agent` 经 `lib/plugin` 加载;优先 `> plugin.native_path name=agent`,否则按序查找:
|
||||
|
||||
|
||||
+65
-27
@@ -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
|
||||
@@ -21,52 +21,90 @@ marqdo ext remove agent
|
||||
1. `MARQDO_EXT` if set
|
||||
2. Else `~/.marqdo/ext`
|
||||
|
||||
Imports use paths like `> ext/ai/llm.mq.md` (see [`load.rs`](../../src/load.rs)).
|
||||
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)
|
||||
@@ -12,7 +12,7 @@
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/ai/llm.mq.md
|
||||
import llm:ext/ai/llm.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
@@ -22,7 +22,7 @@ Other official ext: [ext-agent.md](ext-agent.md) / [ext-agent-plan.md](ext-agent
|
||||
|
||||
Streaming: `complete stream=True` returns an event list (`reasoning` / `delta` / `done` / `error`); `echo=True` prints thinking (`reasoning_content`) and answer tokens as they arrive. See [agent-streaming.md](../roadmap/agent-streaming.md). Default (`stream=False`) is unchanged (answer string).
|
||||
|
||||
**Note:** Prefer `marqdo ext add llm`. Import `> ext/ai/llm.mq.md` from repo or install root.
|
||||
**Note:** Prefer `marqdo ext add llm`. Import `import llm:ext/ai/llm.mq.md` from repo or install root.
|
||||
|
||||
## Platform prerequisites
|
||||
|
||||
@@ -43,7 +43,7 @@ Streaming: `complete stream=True` returns an event list (`reasoning` / `delta` /
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/ai/llm.mq.md
|
||||
import llm:ext/ai/llm.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -0,0 +1,230 @@
|
||||
# `ext/quantum` Q7 — 高阶线性代数 + 高级可视化
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · Q7a/Q7b/Q7c 已落地** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 父设计 | [ext-quantum.md](ext-quantum.md) |
|
||||
| 路线图 | [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
|
||||
| 对照 | [IBM Quantum state plots](https://quantum.cloud.ibm.com/docs/en/guides/plot-quantum-states) · [QuTiP visualization](https://qutip.readthedocs.io/en/latest/guide/guide-visualization.html) · Cirq `plot_density_matrix` |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
在 **Q0–Q6 态向量教学模拟**之上,补齐两块「教科书级」能力:
|
||||
|
||||
1. **高阶线性代数**(密度矩阵、Kronecker、部分迹、Hermitian 谱分解、Schmidt / SVD、Pauli 期望值)
|
||||
2. **高级静态 SVG 展示**(Hinton / City / Pauli 向量 / QSphere 风格 / 多比特布洛赫)
|
||||
|
||||
全部经 **`plugins/quantum` ABI**;`ext/quantum/**` 只做 L1 表包装,**禁止** `host_*`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机与业界对照(联网调研 2026-08)
|
||||
|
||||
### 1.1 为何现在做
|
||||
|
||||
| 已有(Q0–Q6) | 缺口 |
|
||||
|---------------|------|
|
||||
| 纯态态向量 + 施门 + 采样 | 混态 / 约化子系统无法一等公民表达 |
|
||||
| `bloch` 单比特约化 | 纠缠与多比特关联只能猜 |
|
||||
| `gate.draw kind=matrix` 热力图 | 无密度矩阵 / Pauli 分解 / 球面振幅布局 |
|
||||
| 内部 `apply_unitary` / Kronecker | **未**暴露为作者面 API |
|
||||
|
||||
教学文档写「贝尔态纠缠」时,读者需要:**约化密度矩阵 → 纯度 < 1 → Schmidt 系数 → Hinton/QSphere 图**。这些正是 Qiskit / QuTiP / Cirq 的标配。
|
||||
|
||||
### 1.2 可视化对标(只取可静态 SVG 落地的子集)
|
||||
|
||||
| 业界 | 含义 | Q7 决策 |
|
||||
|------|------|---------|
|
||||
| Qiskit `plot_state_hinton` | 元大小表示幅值,色表示正负 | ✅ `kind=hinton` |
|
||||
| Qiskit `plot_state_city` | Re/Im 三维条 | ✅ **2.5D 等轴测 SVG**(非 Matplotlib) |
|
||||
| Qiskit `plot_state_paulivec` | Pauli 串期望值柱 | ✅ `kind=paulivec` |
|
||||
| Qiskit `plot_state_qsphere` | 振幅点在球面上,色=相位 | ✅ `kind=qsphere`(教学投影) |
|
||||
| Qiskit `plot_bloch_multivector` | 每比特一球 | ✅ `kind=multibloch` |
|
||||
| Cirq density Argand 格 | 每元幅值圆 + 相位针 | ✅ 并入 `kind=density`(默认) |
|
||||
| QuTiP Wigner / 过程层析 | 连续相空间 / χ 矩阵 | ❌ 本切片不做 |
|
||||
|
||||
### 1.3 线性代数对标(经典模拟侧,非量子算法)
|
||||
|
||||
| 能力 | 教学用途 | Q7 |
|
||||
|------|----------|-----|
|
||||
| ρ = \|ψ⟩⟨ψ\| | 纯→密度 | ✅ |
|
||||
| Kronecker / 张量积 | 复合系统 | ✅ |
|
||||
| 部分迹 | 约化、纠缠证据 | ✅ |
|
||||
| Hermitian 本征分解 | 谱 / 测量可观测量 | ✅(小维) |
|
||||
| Schmidt(纯态二分)= 整形 SVD | 纠缠熵入口 | ✅ |
|
||||
| Pauli 期望 ⟨P⟩ | 布洛赫 / paulivec 数据源 | ✅ |
|
||||
| 纯度 Tr(ρ²)、保真度 | 混态度量 | ✅ 最小 |
|
||||
| 量子奇异值变换 / VQSVD / 云后端 | 算法研究 | ❌ |
|
||||
|
||||
---
|
||||
|
||||
## 2. 硬约束(沿用 + 本切片追加)
|
||||
|
||||
1. **仅 ABI**:新 FFI 全部注册在 `marqdo_plugin_init`;L1 经 `plugin.load`。
|
||||
2. **`ext/**` 无 `host_*`**。
|
||||
3. **中英分文件**,禁止混 API。
|
||||
4. **维数上限**:
|
||||
- 态向量模拟:仍 ≤ 12 qubits(既有)。
|
||||
- **密度矩阵稠密运算**(部分迹结果展示、谱分解、Hinton/City):默认 **≤ 6 qubits**(dim ≤ 64);超限显式报错。
|
||||
5. **无新核心依赖**:插件内手写复数矩阵 + Jacobi / 薄 SVD;**不**捆绑 BLAS / nalgebra(可后续再议)。
|
||||
6. **view**:仍走 `host_query("record_plot")` + `quantum_svg`;无外链字体/CDN。
|
||||
|
||||
---
|
||||
|
||||
## 3. 新运行时类型
|
||||
|
||||
| `_type`(英) | 中文 | 字段(锁定) |
|
||||
|---------------|------|----------------|
|
||||
| `quantum_state` | `量子态` | 既有:`qubits`, `amplitudes:[{re,im}]` |
|
||||
| `quantum_density` | `密度矩阵` | `qubits`, `dim`, `matrix`(dim×dim 嵌套 `{re,im}`) |
|
||||
| `quantum_spectrum` | `谱` | `eigenvalues:[f64]`, `eigenvectors`(列向量嵌套 list) |
|
||||
| `quantum_schmidt` | `施密特` | `coeffs:[f64]`, `ua`, `ub`(局域基),`entropy`(可选) |
|
||||
| `quantum_svg` | — | 既有;`kind` 扩展见 §5 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 作者面 API
|
||||
|
||||
### 4.1 英文(`ext/quantum/quantum.mq.md`)
|
||||
|
||||
在既有 `# circuit` / `# gate` 之外增加(或扩展方法):
|
||||
|
||||
```markdown
|
||||
# density
|
||||
+ `state`=None # quantum_state 或 circuit(先 simulate)
|
||||
+ `matrix`=None # 直接给定 ρ
|
||||
|
||||
## matrix # → 嵌套 list
|
||||
## purity # Tr(ρ²)
|
||||
## expect
|
||||
+ `obs` # Pauli 串 "ZI" / "XX" 或门矩阵
|
||||
## partial_trace
|
||||
+ `keep` # 保留的比特列表(LSB=0)
|
||||
## eig # Hermitian 谱 → quantum_spectrum
|
||||
## draw
|
||||
+ `kind`=hinton # hinton|city|density|paulivec
|
||||
+ `path`=None
|
||||
|
||||
# linop # 自由线性代数(也可挂在 quantum.* 模块函数)
|
||||
## kron
|
||||
+ `a`
|
||||
+ `b` # 矩阵或态 → 张量积
|
||||
## schmidt
|
||||
+ `state`
|
||||
+ `cut`=1 # 前 cut 个比特为 A,其余为 B
|
||||
## fidelity
|
||||
+ `a`
|
||||
+ `b` # 两态或两密度(纯态公式优先)
|
||||
```
|
||||
|
||||
**电路侧便捷方法**(返回新句柄,不改旧对象):
|
||||
|
||||
```markdown
|
||||
## density # simulate 后 ρ=|ψ⟩⟨ψ|
|
||||
## expect
|
||||
+ `obs`
|
||||
## schmidt
|
||||
+ `cut`=1
|
||||
## draw
|
||||
+ `kind`=… # 扩展:hinton|city|density|paulivec|qsphere|multibloch
|
||||
```
|
||||
|
||||
### 4.2 中文对称
|
||||
|
||||
| 英文 | 中文 |
|
||||
|------|------|
|
||||
| `density` | `密度` |
|
||||
| `partial_trace` | `部分迹` |
|
||||
| `purity` | `纯度` |
|
||||
| `expect` | `期望` |
|
||||
| `eig` | `本征` |
|
||||
| `kron` | `张量积` |
|
||||
| `schmidt` | `施密特` |
|
||||
| `fidelity` | `保真度` |
|
||||
| `hinton` / `city` / `paulivec` / `qsphere` / `multibloch` | 同音译或 `欣顿`/`城市`/`泡利向量`/`球`/`多布洛赫`(L1 锁定中英别名表) |
|
||||
|
||||
### 4.3 ABI 函数名(稳定英文)
|
||||
|
||||
| FFI | 作用 |
|
||||
|-----|------|
|
||||
| `quantum_density_from_state` | 态 / 电路 → `quantum_density` |
|
||||
| `quantum_density_from_matrix` | 校验 Hermitian / 维数 → 句柄 |
|
||||
| `quantum_density_matrix` | 取出嵌套矩阵 |
|
||||
| `quantum_density_purity` | Tr(ρ²) |
|
||||
| `quantum_density_partial_trace` | keep 列表 |
|
||||
| `quantum_density_eig` | Jacobi Hermitian |
|
||||
| `quantum_density_expect` | Pauli 串或矩阵 |
|
||||
| `quantum_density_draw` | hinton/city/density/paulivec |
|
||||
| `quantum_kron` | 两矩阵或两态振幅 |
|
||||
| `quantum_schmidt` | 纯态二分 |
|
||||
| `quantum_fidelity` | 两态 |
|
||||
| `quantum_draw_circuit` | **扩展** kind 枚举(向后兼容) |
|
||||
|
||||
---
|
||||
|
||||
## 5. 高级绘图语义
|
||||
|
||||
| `kind` | 输入 | SVG 要点 |
|
||||
|--------|------|----------|
|
||||
| `hinton` | ρ | 网格方块;边长 ∝ √\|ρᵢⱼ\|;正 Re 浅 / 负深;小 dim 可标数值 |
|
||||
| `city` | ρ | 等轴测「楼宇」:左 Re、右 Im 两城,或单城双色柱 |
|
||||
| `density` | ρ | Cirq 风格:每格幅值圆 + 相位线段;对角概率矩形 |
|
||||
| `paulivec` | 态或 ρ | 全 Pauli 基(n≤3)或用户 `ops=` 列表;柱高 = ⟨P⟩ |
|
||||
| `qsphere` | 纯态 | 基矢点映射到球/圆;半径∝振幅,色相∝arg;n≤4 推荐 |
|
||||
| `multibloch` | 纯态 | 每比特约化布洛赫并排 |
|
||||
|
||||
既有 `circuit|probs|bloch|gate|matrix` **不变**。
|
||||
|
||||
---
|
||||
|
||||
## 6. 数值语义(锁定)
|
||||
|
||||
| 项 | 规则 |
|
||||
|----|------|
|
||||
| 比特序 | **qubit 0 = LSB**(与既有概率标签一致) |
|
||||
| `partial_trace keep=` | 保留比特升序组成新系统的 LSB…MSB |
|
||||
| Pauli 串 | 左→右 = **高位→低位** 或文档写死「左=qubit n-1」——**锁定:字符串左端 = 最高比特(qubit n−1)**,与 Qiskit 习惯一致;文档 + 金样双锁 |
|
||||
| Hermitian 检查 | ‖ρ−ρ†‖_F < 1e-8,否则报错 |
|
||||
| 谱 | 实特征值降序;特征向量列归一 |
|
||||
| Schmidt | 将 \|ψ⟩ 整形为 `2^cut × 2^(n-cut)` 复矩阵做薄 SVD;奇异值 = Schmidt 系数 |
|
||||
| 纯度 | 纯态 ≈ 1;最大混态 = 1/dim |
|
||||
|
||||
---
|
||||
|
||||
## 7. 分期交付
|
||||
|
||||
| 子阶段 | 内容 | 验收 |
|
||||
|--------|------|------|
|
||||
| **Q7a** | density / kron / partial_trace / eig / schmidt / expect / purity / fidelity + L1 中英 | `tests/ext/quantum-linalg-smoke.mq.md`(+ zh) |
|
||||
| **Q7b** | draw kinds:hinton, city, density, paulivec, qsphere, multibloch | `tests/ext/quantum-viz-advanced-smoke.mq.md`(SVG 含关键标记) |
|
||||
| **Q7c** | 示例页 + 用户站短页 + skill/reference 摘要 | `examples/quantum-entanglement/` 或扩展 bell |
|
||||
|
||||
---
|
||||
|
||||
## 8. 刻意不做(本 Q7)
|
||||
|
||||
- 任意 Kraus / 完整 CPTP 通道库(仍用 Q5 轨迹噪声)
|
||||
- >6 qubit 稠密 ρ 的谱 / Hinton(请用态向量 API)
|
||||
- Matplotlib / WebGL / 交互拖拽
|
||||
- 量子线性系统算法(HHL)、QSVT 电路构造
|
||||
- 把线性代数并入 `lib/math`
|
||||
|
||||
---
|
||||
|
||||
## 9. 评审清单
|
||||
|
||||
1. 密度矩阵上限 6 qubits 是否可接受?
|
||||
2. Pauli 串左右端比特约定是否锁定为「左=高比特」?
|
||||
3. City 用 2.5D SVG 而非真 3D 是否足够?
|
||||
4. `# density` 独立类 vs 仅 `circuit.density` —— **两者都提供**(类用于给定矩阵;电路方法便捷)?
|
||||
|
||||
评审默认:**全部锁定为上文**;实现按 Q7a → Q7b → Q7c。
|
||||
|
||||
---
|
||||
|
||||
## 10. 一句话
|
||||
|
||||
**Q7 让 Marqdo 量子文档能「算清纠缠、画清态」:线性代数在 ABI 里跑,高级图用自绘 SVG 进 view——仍是代码即文档。**
|
||||
@@ -0,0 +1,153 @@
|
||||
# `ext/quantum` Q8 — 可视化美学升级(科技感电路图)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · Q8a/Q8b landed · Q8c pending** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 父设计 | [ext-quantum.md](ext-quantum.md) · [ext-quantum-q7.md](ext-quantum-q7.md) |
|
||||
| 路线图 | [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
|
||||
| 对照 | [IBM Quantum Composer](https://quantum.cloud.ibm.com/docs/guides/composer) · [Qiskit `iqp` / `iqp-dark`](https://quantum.cloud.ibm.com/docs/api/qiskit/qiskit.visualization.circuit_drawer) · Cirq / Quirk 视觉习惯 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
修复 view 内嵌量子 SVG 的**文字–导线粘连**,并把电路 / 概率 / 布洛赫 / 密度类图统一到一套**量子实验室科技感**视觉令牌(深底、门族分色、清晰留白)——仍只输出自包含 SVG,无外链字体/CDN。
|
||||
|
||||
---
|
||||
|
||||
## 1. 问题诊断(对照用户截图)
|
||||
|
||||
| 现象 | 根因(`plugins/quantum/src/draw.rs`) |
|
||||
|------|----------------------------------------|
|
||||
| `q0`/`q1` 与导线穿过文字 | 导线从 `x=8` 起画满宽;标签 `x=4` 且基线对齐导线中心 → 线穿字 |
|
||||
| 「不好看 / 无科技感」 | 单色 `#1a1a1a` + 浅灰盒;无门族色、无背景板、无线宽层次 |
|
||||
| 门盒贴线、略挤 | `COL_W=56`、盒 28×28、标签栏与第一列无独立 gutter |
|
||||
| 测量/控点辨识弱 | 与单比特门同色同描边,缺少语义色 |
|
||||
|
||||
**不在本切片**:交互拖拽、WebGL、外链字体、第二套 view 皮肤。
|
||||
|
||||
---
|
||||
|
||||
## 2. 业界对照(联网 2026-08)
|
||||
|
||||
| 来源 | 可借鉴点 | 本仓取舍 |
|
||||
|------|----------|----------|
|
||||
| **Qiskit `iqp` / `iqp-dark`** | 门族 `displaycolor`(面色+字色);深色底;线色弱于门 | 移植**色板与分类**,不绑 matplotlib |
|
||||
| **IBM Composer** | 经典门深蓝、相位门浅蓝、非酉灰;导出 light/dark | 默认 **dark tech**(view 卡片上更醒目);可选 `theme=light` |
|
||||
| **Quirk** | 高对比栅格、测量仪表清晰 | 测量盒保留仪表符号,加强描边/填充对比 |
|
||||
| **教科书 bw** | 印刷友好 | 保留为 `theme=bw` 后备,非默认 |
|
||||
|
||||
**刻意避开**:紫白渐变「AI 默认皮肤」;过重 glow 光晕(打印/浅底卡片会糊)。科技感靠:**深 slate 底 + 青/靛门色 + 清晰层级 + 留白**,而非堆霓虹。
|
||||
|
||||
---
|
||||
|
||||
## 3. 视觉令牌(锁定 `marqdo-iqp`)
|
||||
|
||||
### 3.1 主题
|
||||
|
||||
| `theme` | 用途 |
|
||||
|---------|------|
|
||||
| `dark`(**默认**) | view / 教学演示科技感 |
|
||||
| `light` | 浅底文档打印 |
|
||||
| `bw` | 无彩色、高对比 |
|
||||
|
||||
作者面:
|
||||
|
||||
```markdown
|
||||
*`svg` = > `qc`.draw kind="circuit" theme="dark"*
|
||||
*`svg` = > `qc`.draw kind="probs" theme="light"*
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `kind` | `circuit` | 既有枚举不变 |
|
||||
| `theme` | `dark` | 新增;非法值报错 |
|
||||
| `path` | — | 既有 |
|
||||
|
||||
中文:`主题=dark|light|bw`。ABI:`quantum_draw_circuit` 增可选 `theme`(circuit/probs/bloch 已生效;gate/density 高级图见 Q8c)。
|
||||
|
||||
### 3.2 Dark 色板(默认)
|
||||
|
||||
| 令牌 | 色 | 用途 |
|
||||
|------|-----|------|
|
||||
| `bg` | `#0a0e14` → `#141c28` 渐变 | SVG 圆角底板 |
|
||||
| `wire` | `#6b7f96` | 比特线(双层描边) |
|
||||
| `label` / `chip` | `#e8eef6` / `#1e2a3a` | `q0` 芯片标签(线不穿字) |
|
||||
| `gate.clifford` | 面 `#4c6fff` / 字 `#f2f6ff` | H、X、Y、CX、SWAP… |
|
||||
| `gate.phase` | 面 `#2de2e6` / 字 `#042024` | S、T、Rz、CZ… |
|
||||
| `gate.rotation` | 面 `#3dd6c6` / 字 `#041a18` | Rx、Ry |
|
||||
| `gate.measure` | 面 `#8fa3b8` / 字 `#0a1018` | MEASURE |
|
||||
| `barrier` | `#9aafc0` 虚线 | BARRIER |
|
||||
| `ctrl` | `#f0f5ff` | 控制点 / ⊕ |
|
||||
|
||||
Light / bw 在实现里各给一套平行表;金样以 dark 主断言(SVG 含 `data-theme="dark"` 与背景色)。
|
||||
|
||||
### 3.3 布局(消灭粘连)
|
||||
|
||||
```text
|
||||
| pad | label_col | gutter | col0 | … | colN | pad |
|
||||
^q0 芯片标签 ^导线从此开始(不穿过文字)
|
||||
```
|
||||
|
||||
| 常量 | 实现值 |
|
||||
|------|--------|
|
||||
| `LABEL_W` | 52 |
|
||||
| `GUTTER` | 20 |
|
||||
| `PAD_X` / `PAD_Y` | 24 / 36 |
|
||||
| `COL_W` | 80 |
|
||||
| `ROW_H` | 64 |
|
||||
| 门盒 | 40×40,`rx=8` |
|
||||
| 线宽 | 导线双层 3.2+1.8;门描边 ~1.1;控制竖线 2.25 |
|
||||
|
||||
标签:圆角芯片 + 居中文字;导线 `x1 = PAD_X + LABEL_W + GUTTER`。
|
||||
|
||||
### 3.4 门族映射
|
||||
|
||||
| 族 | 门名(归一化后) |
|
||||
|----|------------------|
|
||||
| clifford | I X Y Z H CX CNOT SWAP |
|
||||
| phase | S T RZ CZ |
|
||||
| rotation | RX RY |
|
||||
| measure | MEASURE M |
|
||||
| barrier | BARRIER |
|
||||
| custom / U | clifford 色或中性 `#546e7a` |
|
||||
|
||||
---
|
||||
|
||||
## 4. 作者面(增量,向后兼容)
|
||||
|
||||
见 §3.1。字符串参数须加引号:`kind="circuit"`、`theme="dark"`(中文 `种类=` / `主题=`)。改插件后须 `marqdo ext add quantum` 再开 view,否则仍加载旧 `.so`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 分期
|
||||
|
||||
| 子阶段 | 内容 | 验收 |
|
||||
|--------|------|------|
|
||||
| **Q8a** | 电路轨线:布局 gutter + dark/light/bw 令牌 + 门族分色 | 标签不与线相交;SVG 含 `data-theme`;更新 draw smoke |
|
||||
| **Q8b** | probs / bloch / gate heatmap 共用令牌 | 柱/球/热力与电路同族色 |
|
||||
| **Q8c** | hinton / city / qsphere / paulivec / multibloch 换肤 | 高级图不「脱节」;viz-advanced smoke 仍绿 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 实现约束
|
||||
|
||||
1. 仅改 `plugins/quantum` 绘图 + L1 透传 `theme`;**不**改 Marqdo 核心。
|
||||
2. SVG **内联**颜色与字体栈(`ui-sans-serif, system-ui, …`);无 `@import` / CDN。
|
||||
3. view 仍走 `record_plot`;底板自带圆角矩形,避免白底卡片上「漂浮黑线」。
|
||||
4. 金样:断言结构标记(`data-theme`、`data-gate-family`)+ 既有 kind;不像素比对。
|
||||
|
||||
---
|
||||
|
||||
## 7. 非目标
|
||||
|
||||
- 复制 Qiskit matplotlib 像素级一致
|
||||
- 动画 / 3D 电路
|
||||
- 用户自定义完整 JSON 主题文件(可 Q9)
|
||||
|
||||
---
|
||||
|
||||
## 8. 一句话
|
||||
|
||||
**先把字从线上挪开,再给门族涂上实验室色——默认 dark tech,打印用 light,论文用 bw。**
|
||||
@@ -2,8 +2,8 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · Q0–Q5.5 已落地**(教学噪声含振幅阻尼;完整开放系统另文) |
|
||||
| 日期 | 2026-08-12 |
|
||||
| 状态 | **Accepted · Q0–Q7 完结 · Q8a/Q8b 完结**([ext-quantum-q7.md](ext-quantum-q7.md) · [ext-quantum-viz-style.md](ext-quantum-viz-style.md);Q8c 高级态图换肤待做) |
|
||||
| 日期 | 2026-08-12(初版)· 2026-08-28(Q7 · Q8 viz) |
|
||||
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [ext-web.md](ext-web.md) · [view.md](view.md) · [stdlib-i18n.md](stdlib-i18n.md) · [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
|
||||
| 安装(目标) | `marqdo ext add quantum`(中英:`quantum` / `量子`) |
|
||||
| 本文目的 | 锁定**作者面**、**模拟语义**、**view 可视化**与**分期**;指导 ABI 插件实现 |
|
||||
@@ -101,11 +101,11 @@ marqdo ext add quantum
|
||||
|
||||
```markdown
|
||||
---
|
||||
> ext/quantum/quantum.mq.md
|
||||
import quantum:ext/quantum/quantum.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
或中文:`> ext/quantum/量子.mq.md`。
|
||||
或中文:`导入 量子:ext/quantum/量子.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
@@ -191,6 +191,8 @@ $$
|
||||
+ `seed`=None # → quantum_result(计数直方图)
|
||||
## draw
|
||||
+ `path`=None # SVG;无 path 时仍可进 view 产物
|
||||
+ `kind`=circuit # circuit|probs|bloch|hinton|…(见 Q7)
|
||||
+ `theme`=dark # dark|light|bw(Q8;电路/概率/布洛赫)
|
||||
## state # 当前缓存态(若已 simulate)
|
||||
```
|
||||
|
||||
@@ -211,6 +213,8 @@ $$
|
||||
| `probabilities` | `概率` |
|
||||
| `run` | `运行` |
|
||||
| `draw` | `绘图` |
|
||||
| `kind` | `种类` |
|
||||
| `theme` | `主题` |
|
||||
| `measure` | `测量` |
|
||||
| `qubits` | `比特数` |
|
||||
| `steps` | `步骤` |
|
||||
@@ -295,13 +299,14 @@ CLI:`draw path=bell.svg` 写沙箱文件;无 path 时不把整段 SVG 灌 st
|
||||
|
||||
| 图 | v1 | 说明 |
|
||||
|----|----|------|
|
||||
| 电路轨线(qubit 线 + 门盒 + 控点) | **必须** | `circuit.draw` |
|
||||
| 电路轨线(qubit 线 + 门盒 + 控点) | **必须** | `circuit.draw`;Q8 默认 `theme=dark`(标签芯片 + 门族分色) |
|
||||
| 测量概率条形图 | **必须** | `probabilities` / `run` 后可 `draw kind=probs` |
|
||||
| 单比特布洛赫球(SVG) | 应有 | 仅 n=1 或指定 qubit 约化(纯态投影) |
|
||||
| 门矩阵热力图 | **必须** | `gate.draw kind=matrix`(幅值热图 + 小数标注) |
|
||||
| 高级态图(hinton/city/…) | Q7 | 见 [ext-quantum-q7.md](ext-quantum-q7.md);换肤见 Q8c |
|
||||
| 交互拖拽编辑电路 | **不做** | 静态文档足够 |
|
||||
|
||||
视觉:内联 CSS;**无外链**字体/CDN(同 view 硬规则)。
|
||||
视觉:内联 SVG 色与字体栈;**无外链**字体/CDN(同 view 硬规则)。主题令牌与布局:[ext-quantum-viz-style.md](ext-quantum-viz-style.md)。view 对 `svg[data-theme=dark]` 使用深色图框。
|
||||
|
||||
---
|
||||
|
||||
@@ -323,6 +328,9 @@ Q5 教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext-
|
||||
| **Q3** | `steps=` 表;`draw` SVG 在 `view` HTML 含 `<svg` | 与 math-plot 同级断言 |
|
||||
| **Q4** | 概率图 + 布洛赫;`matches_matrix`;用户文档页 | `quantum-draw-smoke` / `quantum-gate-matrix-smoke`;`view output` 可浏览示例 |
|
||||
| **Q5** | `noise` 轨迹;`barrier`/`measure`/`append`/`state` | `quantum-noise-smoke` / `quantum-author-api-smoke` |
|
||||
| **Q6** | 公式/`matrix=` 自定义门 | [ext-quantum-custom-gate.md](ext-quantum-custom-gate.md) |
|
||||
| **Q7** | 密度矩阵线性代数 + Hinton/City/QSphere 等 SVG + 纠缠示例 | [ext-quantum-q7.md](ext-quantum-q7.md) ✅ |
|
||||
| **Q8** | 可视化美学:`theme` + 标签 gutter + 门族分色 | [ext-quantum-viz-style.md](ext-quantum-viz-style.md) · Q8a/Q8b ✅ · Q8c 待做 |
|
||||
|
||||
实现路线图跟踪见 [roadmap/ext-quantum.md](../roadmap/ext-quantum.md)。
|
||||
|
||||
@@ -333,7 +341,7 @@ Q5 教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext-
|
||||
```markdown
|
||||
---
|
||||
title: Bell state
|
||||
> ext/quantum/quantum.mq.md
|
||||
import quantum:ext/quantum/quantum.mq.md
|
||||
---
|
||||
|
||||
# Bell |Φ+⟩
|
||||
|
||||
@@ -0,0 +1,74 @@
|
||||
# 解决 1:路由与 `/admin` 前缀可让出
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §1](../../research/ext-web-customization-limits.md#1-路由与路径被框架强占) |
|
||||
| 优先级 | **P0** · 波次 **C0** |
|
||||
| 触点 | `plugins/web/src/lib.rs`(`normalize_route_path`、`web_app_new`、redirect)· `plugins/web/src/http.rs`(admin 路由挂载、login redirect)· `ext/web/web.mq.md` / `网页.mq.md` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 关闭内置后台后,**整段前缀可被站点路由占用**(含自研 `/admin`)。
|
||||
2. 开启内置后台时,前缀**可配置**(默认仍 `/admin`),登录成功/登出落地页可配置。
|
||||
3. `app.route` / `app.redirect` 只禁止**当前生效**的框架保留段,不再永久霸占 `/admin`。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
```markdown
|
||||
*应用 = > web.app page=`首页` db=`库` admin=False*
|
||||
|
||||
# 或:仍用内置 CRUD,但挂到旁路前缀 + 自定义回跳
|
||||
*应用 = > web.app page=`首页` db=`库` admin=True*
|
||||
*应用 = > `应用`.auth users=`用户表` admin_prefix="/desk" login_redirect="/desk" logout_redirect="/desk/login"*
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 含义 |
|
||||
|------|------|------|
|
||||
| `admin` / `后台` | `False` | `False`:**不注册**任何内置 admin HTTP 路由 |
|
||||
| `admin_prefix` / `后台前缀` | `"/admin"` | 内置 CRUD + 登录页挂载根;仅 `admin=True` 时生效 |
|
||||
| `login_redirect` / `登录回跳` | `{admin_prefix}` | 登录成功 303 目标 |
|
||||
| `logout_redirect` / `登出回跳` | `{admin_prefix}/login` | 登出后目标 |
|
||||
|
||||
中文别名与英文一一对应,写进 `网页.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| `normalize_route_path(app)` | reserved 列表改为:`/_form`、`/_part`、`/static` + **当前** `admin_prefix`(仅当 `admin=True`) |
|
||||
| `listen` 路由表 | `admin=False` → **不** `.route("/admin…")`;为真则用 `admin_prefix` 拼路径 |
|
||||
| `admin_login_post` / `admin_logout` | 使用配置的 redirect,禁止写死 `"/admin"` |
|
||||
| `web_app_redirect` | 校验目标时用同一套动态 reserved,允许指向已让出的 `/admin` |
|
||||
| disabled 文案路径 | 删除「挂路由但只显示 Admin is disabled」;无路由则 404 或落入站点自定义页 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 缺省参数下:现有 `examples/web-site`、`web-net-site`、`marqdo-blog` 行为不变(仍 `/admin` + 跳 `/admin`)。
|
||||
- 文档明确:`admin=False` 后若仍要登录能力,用 §3 的通用 `auth`/`gate`,不必再依赖内置 admin 壳。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 金样 / 手工 | 期望 |
|
||||
|-------------|------|
|
||||
| `admin=False` + `route path="/admin/news"` | 注册成功;GET 渲染站点页,**不是** Admin is disabled |
|
||||
| `admin_prefix="/desk"` | 内置登录在 `/desk/login`;成功跳 `login_redirect` |
|
||||
| 默认 `admin=True` 无新参数 | 与现网一致 |
|
||||
| `redirect` 到已让出的 `/admin` | 允许 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 已落地
|
||||
|
||||
~~继续用 `/desk` 旁路 + JS 调 `/admin/login`。~~
|
||||
|
||||
**C0 已落地(2026-09):** `admin=False` 可直接 `route path="/admin/…"`;或 `admin=True` + `admin_prefix="/desk"` + `login_redirect` / `logout_redirect`。见金样 `tests/ext/web-c0-admin-prefix.mq.md`。
|
||||
@@ -0,0 +1,72 @@
|
||||
# 解决 2:`SHELL_CSS` 可关 / 可分层
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §2](../../research/ext-web-customization-limits.md#2-内置-shell_css-难以彻底覆盖) |
|
||||
| 优先级 | **P1** · 波次 **C2** |
|
||||
| 触点 | `plugins/web/src/render.rs`(`SHELL_CSS`、`<style>` 拼接)· page/app 元数据 · `ext/web` 样式装配 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 站点主题可选择:**不要**框架栅格/卡片默认,或只要 reset 级变量。
|
||||
2. 壳 CSS 与主题 CSS 的级联顺序**可声明、可文档化**。
|
||||
3. 默认仍注入完整壳(兼容旧站);新主题显式 `shell_css=off` 即可干净起步。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
```markdown
|
||||
*应用 = > web.app page=`首页` … shell_css="minimal"*
|
||||
# 或页面级覆盖
|
||||
*页 = > `页`.meta …* # 或 page 选项 shell_css=
|
||||
```
|
||||
|
||||
| 值 | 行为 |
|
||||
|----|------|
|
||||
| `full`(默认) | 现网 `SHELL_CSS` 全文 |
|
||||
| `minimal` | 仅 `:root` 变量 + `body` margin/字体;**不含** `has-sidebar` 双列栅格与卡片表单皮肤 |
|
||||
| `off` / `none` | 不注入框架壳样式;只输出站点 `style` / 外链 CSS |
|
||||
|
||||
级联顺序锁定为文档约定:
|
||||
|
||||
1. (可选)框架 `SHELL_CSS`
|
||||
2. 站点全局 style 表 / `site.css`
|
||||
3. 页面级 style
|
||||
|
||||
禁止再出现「主题写在 extra,却被同特异性壳规则在小屏打穿且无媒体查询」而无开关可关的情况。
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| 拆分 `SHELL_CSS` | `SHELL_VARS` / `SHELL_LAYOUT` / `SHELL_WIDGETS` 三段;`full`=`all`,`minimal`=vars(+极简 layout) |
|
||||
| `render` 读 `app.shell_css` / `page.shell_css` | 页面覆盖应用 |
|
||||
| 为 `has-sidebar` 布局加基础媒体查询 | 即使 `full`,小屏改为单列(减轻幽灵双列);`minimal`/`off` 不负责响应式 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 默认 `full`:视觉与现网一致。
|
||||
- Tutorial 增加一节「品牌主题请用 `shell_css=minimal|off`」。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| `shell_css=off` + 站点只写单列 grid | 响应里**无** `grid-template-columns:14rem` |
|
||||
| `minimal` | 有 CSS 变量;无 `.content.cards article` 边框默认(或等价皮肤段) |
|
||||
| 默认示例站 | HTML 仍含完整壳 CSS |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 已落地
|
||||
|
||||
**C2 已落地(2026-09):** `shell_css=full|minimal|off`;页面/应用可设;`full` 含 `@media (max-width:720px)` 单列。金样 `tests/ext/web-c2-shell-layout.mq.md`。
|
||||
@@ -0,0 +1,72 @@
|
||||
# 解决 3:鉴权 / 门禁可配置且行为一致
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §3](../../research/ext-web-customization-limits.md#3-鉴权--门禁模型偏固定) |
|
||||
| 优先级 | **P0** · 波次 **C1**(依赖 [01](01-routes-and-admin-prefix.md) 的 prefix) |
|
||||
| 触点 | `plugins/web/src/http.rs`(`rbac_middleware`、`path_matches`、login 表单)· `lib.rs`(`web_app_auth` / `web_app_gate`)· `ext/web` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. **未登录策略一致**:可配置 `redirect`(303 登录)或 `forbid`(403),对任意 gate 路径生效,不再「仅 `/admin*` 会跳登录」。
|
||||
2. **匹配语义清晰**:支持精确路径、前缀、以及排除列表;`/desk` 默认**不**误伤 `/desk/login`。
|
||||
3. 默认 admin gate 使用 **路径段边界**(`/admin` 与 `/admin/…`),不匹配 `/admin-publish`。
|
||||
4. 登录 URL、表单 `action`、成功/失败回跳均可配置(与 C0 对齐)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
```markdown
|
||||
*应用 = > `应用`.auth users=`用户表` login_path="/desk/login" login_redirect="/desk"*
|
||||
*应用 = > `应用`.gate path="/desk" roles="admin" match="prefix" on_deny="redirect" exclude="/desk/login"*
|
||||
```
|
||||
|
||||
| 字段 | 说明 |
|
||||
|------|------|
|
||||
| `login_path` | 登录页 URL(GET 表单 + POST 处理);默认 `{admin_prefix}/login` |
|
||||
| `match` | `exact` \| `prefix`(默认对自定义 gate 建议 `prefix` + `exclude`) |
|
||||
| `on_deny` | `redirect` \| `forbid`;`redirect` 时跳 `login_path`(可带 `?next=`) |
|
||||
| `exclude` | 逗号分隔或表列:匹配前缀时放行的路径 |
|
||||
|
||||
`auth` 注册默认 gate 时:
|
||||
|
||||
- 使用 `{admin_prefix}` + 段边界,**不要** `starts_with("/admin")` 裸前缀。
|
||||
- 自动把 `login_path` 加入放行列表。
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| `path_matches` | 增加 `exact`;`prefix` 要求下一字符为 `/` 或结尾;可选 exclude |
|
||||
| `rbac_middleware` | 按 gate 的 `on_deny` 分支;通用放行 `login_path`,不写死 `/admin/login` |
|
||||
| 登录 HTML | `action={login_path}`;hidden `next` 可选 |
|
||||
| Session/CSRF | 短期仍用框架实现;文档标明字段名;中期再开放 `login_form` 自定义字段映射(非本波次必做) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 未传新字段:行为对齐现网(`/admin*` → redirect 登录;其它自定义 gate → 403)。
|
||||
- 新增金样:`/desk` gate + `/desk/login` 可匿名打开。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| visitor 访问 `/desk`(`on_deny=redirect`) | 303 → `/desk/login`,不是 403 |
|
||||
| visitor 访问 `/desk/login`(exclude) | 200 登录页 |
|
||||
| `/admin-publish` 无显式 gate | **不**被默认 admin gate 拦住 |
|
||||
| 旧站仅 `app.auth` | 仍保护 `/admin*` |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 已落地
|
||||
|
||||
**C1 已落地(2026-09):** `auth` 默认段边界 prefix + `on_deny=redirect` + 排除 `login_path`;自定义 `gate` 可设 `match` / `on_deny` / `exclude`。金样 `tests/ext/web-c1-gates.mq.md`;单元测试 `http::gate_tests`。
|
||||
@@ -0,0 +1,69 @@
|
||||
# 解决 4:样式表作者体验
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §4](../../research/ext-web-customization-limits.md#4-样式作者体验受限) |
|
||||
| 优先级 | **P2** · 波次 **C3** |
|
||||
| 触点 | 表单元格表达式(T5)· `ext/web` style 装配 · 教程 / Skill · 可选校验 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 含 `/`、`,`、括号的 CSS 值**不易被静默算坏**。
|
||||
2. 复杂选择器 / `@keyframes` / 多层 media 有**官方推荐写法**(表内 vs 外链 vs raw 块)。
|
||||
3. 与壳 CSS 的层叠关系在文档中一句话写清(并链到 [02](02-shell-css.md))。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API / 约定(草案)
|
||||
|
||||
### 2.1 立即固化的文档约定(可不改代码)
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| 含 `/` 的值必须引号 | `"1 / 5"`、`"image/png"`(已有;Skill/教程加醒目反例) |
|
||||
| 复杂皮肤优先外链 | `static/theme.css` + `page.head` / `app.icons` 同类资源表 |
|
||||
| `@keyframes` / 长 media | 放外链 CSS,不塞进 GFM 单元格 |
|
||||
| 调试 | `shell_css=off` 后只看主题文件,避免同页双源 |
|
||||
|
||||
### 2.2 产品增强(C3)
|
||||
|
||||
| 能力 | 说明 |
|
||||
|------|------|
|
||||
| `style` 装配时对可疑单元格告警 | 未加引号且含 `/` → listen/assemble 警告或硬错误(可开关) |
|
||||
| 可选 `##` raw CSS 块绑定 | 例如页面附属 ````css` 具名块,**不经**表表达式求值 |
|
||||
| 文档示例 | `min-width` + `max-width` 外链表;引用 [table-cell-expressions.md](../table-cell-expressions.md) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件 / 核心改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| web style 编译 | 可选 `strict_css_cells=True`:裸 `/` 报错 |
|
||||
| (可选)`web_page_css_raw` | 把文本 CSS 追加到页面,跳过 T5 |
|
||||
| Skill `marqdo` / tutorial 14 | 增加「样式踩坑」小节 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 默认不硬错误(避免打碎旧表);新 scaffold 默认 `strict_css_cells` 或文档强制引号。
|
||||
- 不把完整 CSS 语法塞进表格方言——复杂内容走文件。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| 文档反例 `grid-column` 裸 `1 / 5` | 在 strict 模式下失败或警告 |
|
||||
| 外链 `theme.css` + `shell_css=off` | 无壳栅格串扰 |
|
||||
| 现有 web 示例 | 默认模式仍绿 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 workaround
|
||||
|
||||
全部敏感值加引号;响应式与 keyframes 只写在 `static/*.css`;小屏问题优先关壳([02](02-shell-css.md))再调主题。
|
||||
@@ -0,0 +1,85 @@
|
||||
# 解决 5:页面壳与插槽松绑
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §5](../../research/ext-web-customization-limits.md#5-页面壳与插槽约定僵硬) |
|
||||
| 优先级 | **P1** · 波次 **C2/C4** |
|
||||
| 触点 | `plugins/web/src/render.rs`(body class、四区 HTML)· page 槽位装配 · nav 组件表 |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 作者可选**非侧栏栅格**布局,而不必用 CSS 硬怼掉 `has-sidebar`。
|
||||
2. 侧栏存在 ≠ 强制桌面双列;提供 stacked / bare 等预设。
|
||||
3. 为「条件导航」留扩展点(先文档 + 简单 hook,完整运行时条件可后置)。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
```markdown
|
||||
*首页 = > web.page … layout="stacked"*
|
||||
*应用 = > web.app page=`首页` … layout="bare"*
|
||||
```
|
||||
|
||||
| `layout` | DOM / class | 说明 |
|
||||
|----------|-------------|------|
|
||||
| `sidebar`(默认,有 side 槽时) | `body.has-sidebar` | 现网行为 |
|
||||
| `stacked` | `body.layout-stacked`;side 在 main 上或折叠区 | 单列流式,适合杂志/营销 |
|
||||
| `bare` | 无 top/side/foot 强制栅格;只渲染 `main`(+ 显式槽) | 登录页、落地页 |
|
||||
| `rail`(可选) | 保留站点已有 `has-rail` 约定并文档化 | 避免「只有首页有 class」 |
|
||||
|
||||
规则:**有 side 组件但 `layout=stacked|bare` 时,不自动加 `has-sidebar`。**
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| `render` 读 `page.layout` / `app.layout` | 决定 body class 与 HTML 骨架 |
|
||||
| `SHELL_LAYOUT`(见 [02](02-shell-css.md)) | 为 `layout-stacked` / `layout-bare` 提供最小样式;`shell_css=off` 时不注入 |
|
||||
| Nav 表 | 短期保持声明式;文档说明「条件项用两套 nav 组件 + 媒体查询隐藏」 |
|
||||
| 中期 hook(非阻断) | `navigate` 已有字段可扩展 `when`/`media` 列(单独 RFC) |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 未设 `layout`:有 side → 与现网 `has-sidebar` 相同。
|
||||
- 金样增加 `layout=bare` 登录页(可与 C0 自研 `/desk/login` 共用)。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| 有 side + `layout=stacked` | body **无** `has-sidebar`;无 `14rem` 双列(在 full 壳下用 stacked 规则) |
|
||||
| `layout=bare` | 输出不含 `<aside class="side">`(或 empty 不占栅格) |
|
||||
| 默认站 | 不变 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 已落地
|
||||
|
||||
**C2 已落地(2026-09):** `layout=sidebar|stacked|bare|rail`;有 side 时 `stacked`/`bare` 不再强制 `has-sidebar`。金样 `web-c2-shell-layout`。
|
||||
|
||||
**C4 已落地(2026-09):** 导航 / 侧栏 / 页脚绑定表可选列:
|
||||
|
||||
| 列 | 说明 |
|
||||
|----|------|
|
||||
| `媒体` / `media` | CSS media;不匹配时 `display:none`(生成 `nav-mq-*` + `@media not …`) |
|
||||
| `当` / `when` | `hide` 省略;`auth` / `guest` 按登录态过滤;空 = 总是显示 |
|
||||
|
||||
```markdown
|
||||
| 属性 | 值 | 样式 | 媒体 | 当 |
|
||||
|------|-----|------|------|-----|
|
||||
| Home | / | | | |
|
||||
| Menu | /m | | (max-width: 720px) | |
|
||||
| Admin | /admin | | | auth |
|
||||
| Login | /login | | | guest |
|
||||
```
|
||||
|
||||
Listen 渲染时写入 `_logged_in` / `_nav_user`(来自 session)。离线 `page.render` 可自行 `table.put` `_logged_in`。金样 `web-c4-nav-when`。
|
||||
@@ -0,0 +1,67 @@
|
||||
# 解决 6:后台 CRUD 与表单能力边界
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §6](../../research/ext-web-customization-limits.md#6-后台-crud-与表单能力边界) |
|
||||
| 优先级 | **P3** · 随 C0 文档化;增强可选 |
|
||||
| 触点 | `plugins/web/src/http.rs` / `form.rs`(内置 admin)· 站点自研页 + `db.*` · `/_form` |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. **产品叙事澄清**:内置 `/admin`(或可配置前缀)= 通用表浏览器,**不是** CMS;关则彻底让路(见 [01](01-routes-and-admin-prefix.md))。
|
||||
2. 自研后台的推荐路径写清楚:`page` + `form` + `db` + gate,而不是改插件壳。
|
||||
3. 对「链接前缀 / new / edit」给出约定或薄辅助,减少前端状态机拼装。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API / 文档(草案)
|
||||
|
||||
### 2.1 推荐架构(文档为主)
|
||||
|
||||
| 需求 | 做法 |
|
||||
|------|------|
|
||||
| 产品级编辑器、专栏联动 | 自研 `# page` + 组件;写库用 `db.insert`/`update`;鉴权用 `gate` |
|
||||
| 简单表维护 | 开 `admin=True`(可换前缀) |
|
||||
| 关内置仍要 CRUD | 自研列表/编辑页;**不要**依赖 disabled 壳 |
|
||||
|
||||
### 2.2 可选薄增强(非 CMS)
|
||||
|
||||
| 能力 | 说明 |
|
||||
|------|------|
|
||||
| `form` 支持 `mode=new\|edit` 查询参数约定 | 文档 + 示例;必要时 `web.form` 读 `id`/`new` |
|
||||
| `list` 组件 `link_prefix` | 已有则补示例;缺失则加一列「详情路径模板」 |
|
||||
| Markdown 字段 | 继续「存库 + 前台渲染」;分栏编辑器保持外挂 JS(明确不做进 ABI) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 优先级 |
|
||||
|------|--------|
|
||||
| C0:disabled 不占路径 | 必需(属 [01](01-routes-and-admin-prefix.md)) |
|
||||
| 示例 `examples/web-custom-desk/` | 展示自研列表/编辑,零内置 admin |
|
||||
| form 查询参数助手 | 可选 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 不扩展内置 admin 成 CMS(避免范围爆炸)。
|
||||
- Tutorial 增加「何时用内置 admin / 何时自研」。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| 文档 + 示例 desk | 无 `/admin` 也能完成一文增删改 |
|
||||
| 内置 admin 金样 | 仍绿 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 workaround
|
||||
|
||||
自研 `/desk` + 调用 `/_form` 或直接 DB API;复杂编辑器继续外挂 JS。
|
||||
@@ -0,0 +1,71 @@
|
||||
# 解决 7:静态资源与脚本生命周期
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §7](../../research/ext-web-customization-limits.md#7-静态资源与脚本生命周期) |
|
||||
| 优先级 | **P2** · 波次 **C3** |
|
||||
| 触点 | `web_page_head` / `web_head` · `render.rs` head 输出 · static 挂载 · [web-assets-and-images.md](../web-assets-and-images.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 默认脚本加载方式**不假设**作者手写 IIFE 抢在 DOM 前执行成功;提供 `defer` / `module` 一等约定。
|
||||
2. 静态资源变更可发现:文档化 `?v=`,并提供可选自动指纹或 listen 时 mtime 查询参数。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 API(草案)
|
||||
|
||||
Head 资源表扩展列(向后兼容):
|
||||
|
||||
| 列 | 说明 |
|
||||
|----|------|
|
||||
| `rel` / `关系` | 已有;`script` / `module` |
|
||||
| `defer` / `推迟` | `真` → `<script defer>`(**建议默认对 script 为真**) |
|
||||
| `async` / `异步` | 可选 |
|
||||
| `version` / `版本` | 非空则自动追加 `?v=` |
|
||||
|
||||
```markdown
|
||||
`头` =
|
||||
| 关系 | 地址 | 推迟 | 版本 |
|
||||
|------|------|------|------|
|
||||
| script | /static/theme.js | 真 | 2026-09-04 |
|
||||
| module | /static/desk.js | 真 | 3 |
|
||||
```
|
||||
|
||||
全局:`app.asset_version="2026-09-04"` 为所有 static 链接统一 bump(可选)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 插件改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| head 渲染 | 尊重 defer/async;`module` → `type="module"`(已有则核对) |
|
||||
| 默认 | 新建 scaffold 的 script 行带 `defer` |
|
||||
| (可选)`asset_version` | listen 时重写 head / 页面内 static URL |
|
||||
| 文档 | 「禁止在同步 head 脚本里直接 `getElementById` 主节点;用 defer 或 `DOMContentLoaded`」 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 旧表无 `defer` 列:保持现网同步行为(或仅对 scaffold/新文档默认 defer,避免静默改变旧站时序)。
|
||||
- 更安全:缺省仍同步;**Skill 与 scaffold 默认写 defer=真**。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| defer 脚本读 DOM | 登录跳转逻辑在 DOM 就绪后执行 |
|
||||
| `version` 列 | HTML 中出现 `theme.js?v=…` |
|
||||
| 旧示例无新列 | 仍通过 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 workaround
|
||||
|
||||
脚本改 `type=module` 或放 body 末;手动 `?v=` bump;登录逻辑用 `DOMContentLoaded`。
|
||||
@@ -0,0 +1,68 @@
|
||||
# 解决 8:扩展与部署耦合
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 问题 | [研究 §8](../../research/ext-web-customization-limits.md#8-扩展与部署耦合) |
|
||||
| 优先级 | **P3** · 文档 + 发布流程 |
|
||||
| 触点 | `marqdo ext add web` · ABI 版本 · Docker/发布说明 · [ext-cli.md](../ext-cli.md) · [marqdo-release](../../../.cursor/skills/marqdo-release/SKILL.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 目标
|
||||
|
||||
1. 站点作者**不必 fork 插件**才能完成 P0/P1 定制(把能力收进官方参数,见 01–05)。
|
||||
2. 版本耦合可预期:changelog / 扩展清单标明「web 插件需 ≥ x.y.z」。
|
||||
3. 升级路径文档化:二进制、`.marqdo-ext`、Docker 镜像三者对齐检查。
|
||||
|
||||
---
|
||||
|
||||
## 2. 作者 / 运维约定(草案)
|
||||
|
||||
| 约定 | 说明 |
|
||||
|------|------|
|
||||
| 定制优先走 `.mq.md` 开关 | `admin_prefix`、`shell_css`、`layout`、`gate`… 进官方 API 后,禁止文档再教「改 plugins/web」 |
|
||||
| 兼容性矩阵 | 在 [web-net-capabilities.md](../web-net-capabilities.md) 或本目录维护「Marqdo ↔ libweb 最低版本」表 |
|
||||
| `marqdo ext add web` | 安装后打印当前插件路径与版本;与 CLI 版本不符时警告 |
|
||||
| Docker | 示例 Dockerfile 注释:升级需同时换 `marqdo` 与 `ext add` 产物 |
|
||||
| 样式引号等行为变更 | 写入 CHANGELOG **Breaking / migration** 小节(如 0.3.2 T5) |
|
||||
|
||||
---
|
||||
|
||||
## 3. 工程改动点
|
||||
|
||||
| 改动 | 说明 |
|
||||
|------|------|
|
||||
| 插件/Crate 版本可见 | `web_listen` 或 `ext list` 显示 web ABI/包版本 |
|
||||
| CI | 金样使用仓库内 `plugins/web`;发布技能检查 VSIX/CLI/插件三件套 |
|
||||
| 研究→设计→路线图 | C0–C4 进 [ext-web roadmap](../../roadmap/ext-web.md),避免只活在私有 fork |
|
||||
|
||||
---
|
||||
|
||||
## 4. 兼容策略
|
||||
|
||||
- 不承诺插件源码级稳定 API;承诺 **`.mq.md` 作者 API** 在小版本尽量兼容,破坏性变更进 CHANGELOG。
|
||||
- Fork 插件仅作为「官方尚未交付」的临时手段,并在 issue/路线图留归还项。
|
||||
|
||||
---
|
||||
|
||||
## 5. 验收
|
||||
|
||||
| 场景 | 期望 |
|
||||
|------|------|
|
||||
| 升级说明文档 | 运维按清单升级后 web 金样通过 |
|
||||
| C0–C2 落地 | 自研后台场景**无需**改 `plugins/web` 源码 |
|
||||
| `ext list` / 文档 | 能核对版本 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 过渡期 → 预编译路径(进行中)
|
||||
|
||||
**目标:** 用户 `marqdo ext add web` **不必**本机 Rust。
|
||||
|
||||
| 交付 | 说明 |
|
||||
|------|------|
|
||||
| Release `marqdo-*-native-*.zip` | Windows / Linux 预编译 `web`/`agent`/`quantum` |
|
||||
| Windows portable zip | 内含 `ext/` + `ext/native/*.dll` |
|
||||
| `ext add` 下载回退 | 本地无 `.so`/`.dll` 时从 GitHub Release 拉取(`MARQDO_EXT_NO_DOWNLOAD=1` 可关) |
|
||||
|
||||
仍保留开发者 `cargo build -p marqdo_plugin_*` 路径。详见 [ext-cli.md](../ext-cli.md)。
|
||||
@@ -0,0 +1,50 @@
|
||||
# `ext/web` 定制修复:解决文档索引
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **C0–C4 done** |
|
||||
| 日期 | 2026-09-04 |
|
||||
| 问题盘点 | [../../research/ext-web-customization-limits.md](../../research/ext-web-customization-limits.md) |
|
||||
| 相关 | [../ext-web.md](../ext-web.md) · [../ext-web-net.md](../ext-web-net.md) · [../../roadmap/ext-web.md](../../roadmap/ext-web.md) |
|
||||
|
||||
对应研究文 §1–§8,每项一份解决文档:**目标 → 作者 API → 插件改动点 → 兼容策略 → 验收**。
|
||||
|
||||
实现时优先 **不破坏现有金样**(`tests/ext/web-*`、`examples/web-*`);新能力用显式 opt-in 参数打开。
|
||||
|
||||
---
|
||||
|
||||
## 文档一览
|
||||
|
||||
| # | 主题 | 文档 | 建议优先级 |
|
||||
|---|------|------|------------|
|
||||
| 1 | 路由与 `/admin` 前缀可让出 | [01-routes-and-admin-prefix.md](01-routes-and-admin-prefix.md) | P0 |
|
||||
| 2 | `SHELL_CSS` 可关 / 可层 | [02-shell-css.md](02-shell-css.md) | P1 |
|
||||
| 3 | 鉴权门禁可配置且行为一致 | [03-auth-gates.md](03-auth-gates.md) | P0 |
|
||||
| 4 | 样式表作者体验 | [04-stylesheet-authoring.md](04-stylesheet-authoring.md) | P2 |
|
||||
| 5 | 页面壳与插槽松绑 | [05-page-shell-slots.md](05-page-shell-slots.md) | P1 |
|
||||
| 6 | 后台 CRUD / 表单边界 | [06-admin-crud-forms.md](06-admin-crud-forms.md) | P3 |
|
||||
| 7 | 静态资源与脚本生命周期 | [07-assets-script-lifecycle.md](07-assets-script-lifecycle.md) | P2 |
|
||||
| 8 | 扩展与部署耦合 | [08-ext-deploy-coupling.md](08-ext-deploy-coupling.md) | P3 |
|
||||
|
||||
---
|
||||
|
||||
## 波次建议(实现用)
|
||||
|
||||
| 波次 | 内容 | 依赖 |
|
||||
|------|------|------|
|
||||
| **C0** | 可配置 `admin_prefix`;`admin=False` 时不挂内置路由;`login_redirect` / `logout_redirect` | — |
|
||||
| **C1** | gate:统一未登录策略;精确/前缀匹配;登录页自动放行;默认 gate 不再误伤 `/admin-*` | C0 |
|
||||
| **C2** | `shell_css=off\|minimal\|full`;主题在壳前或隔离层;可选 `layout=bare` | — |
|
||||
| **C3** | 样式:校验警告 / `strict`;`page.css` raw;脚本 `defer`/`async`/`version` + `asset_version` | **done** |
|
||||
| **C4** | 壳:`layout` 预设(C2);条件导航 `when` / `media` | **done** |
|
||||
|
||||
路线图入口可在 [ext-web.md](../../roadmap/ext-web.md) 增补「定制波次 C0–C4」行,落地后再改状态。
|
||||
|
||||
---
|
||||
|
||||
## 产品原则(解法共同约束)
|
||||
|
||||
1. **`.mq.md` 仍是真相源** — 能声明的不进隐藏默认;新开关写在 `app` / `page` / `listen` 参数表。
|
||||
2. **内置 admin 是可选产品**,不是不可替换的内核路由命名空间。
|
||||
3. **默认行为保持兼容** — 现有 tutorial / 示例零改动仍能跑;新站显式打开定制。
|
||||
4. **禁止**为单站需求永久硬编码第二套旁路(如永远推荐 `/desk` + JS fetch 登录)。
|
||||
@@ -0,0 +1,124 @@
|
||||
# `ext/web` 驱动:Postgres · Redis · S3
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 已落地** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 相关 | [ext-web.md](ext-web.md) · [roadmap/ext-web.md](../roadmap/ext-web.md) · [ext-abi.md](ext-abi.md) |
|
||||
| 目标 | 在**不改作者面 CRUD 心智**的前提下,用 URL 方案切换数据库;另增缓存与对象存储两类驱动。贯彻「表格 + 类方法」:配置即数据,装配即函数。 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**`# db` 的 `url=` 决定后端**:`sqlite:` 默认;`postgres://` / `postgresql://` 走 Postgres,作者面 API 不变。
|
||||
**缓存**与**对象存储**是独立类(`# cache` / `# storage`),不塞进 `# db`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 边界
|
||||
|
||||
| 能力 | 归属 | 理由 |
|
||||
|------|------|------|
|
||||
| SQLite / Postgres CRUD | `plugins/web` + `ext/web` `# db` | 同一套 `init/select/insert/…`;热路径 ABI |
|
||||
| Redis 缓存 | `plugins/web` + `ext/web` `# cache` | 键值语义,不是表 CRUD |
|
||||
| S3 / MinIO 对象 | `plugins/web` + `ext/web` `# storage` | 对象键 + 字节/路径,不是行 |
|
||||
| 禁止 | 核心 `src/host/` | 驱动依赖重,只进 ABI 插件 |
|
||||
|
||||
---
|
||||
|
||||
## 2. URL 方案(锁定)
|
||||
|
||||
| 方案 | 含义 | 例 |
|
||||
|------|------|-----|
|
||||
| `sqlite:` / 裸路径 | SQLite 文件(既有) | `sqlite:data/site.db` |
|
||||
| `postgres://` / `postgresql://` | Postgres | `postgres://user:pass@127.0.0.1:5432/app` |
|
||||
| `redis://` / `rediss://` | Redis | `redis://127.0.0.1:6379/0` |
|
||||
| `memory:` | **进程内** Redis 兼容后端(金样/离线) | `memory:` |
|
||||
| `s3://bucket` + 查询参数 | S3 兼容(含 MinIO) | `s3://mybucket?endpoint=http://127.0.0.1:9000®ion=us-east-1` |
|
||||
| `file:` | **本地目录**对象存储(金样/离线) | `file:data/blobs` |
|
||||
|
||||
凭证:优先 URL 内嵌;S3 亦读环境变量 `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`(或 `S3_ACCESS_KEY` / `S3_SECRET_KEY`)。
|
||||
|
||||
---
|
||||
|
||||
## 3. 作者面(代码即文档)
|
||||
|
||||
### 3.1 数据库 — 只换 URL
|
||||
|
||||
英文:
|
||||
|
||||
```markdown
|
||||
import web:ext/web/web.mq.md
|
||||
|
||||
# main
|
||||
|
||||
*store = > web.db url="postgres://marqdo:marqdo@127.0.0.1:5432/site"*
|
||||
*store = > store.init name="posts" fields=`schema`*
|
||||
```
|
||||
|
||||
中文:`网页.数据库` + `url=` 同形。`init` / `select` / `insert` / `paginate` / `事务` **API 不变**。
|
||||
|
||||
Postgres 差异(实现层消化,作者尽量无感):
|
||||
|
||||
- `id INTEGER PRIMARY KEY` → `SERIAL PRIMARY KEY`(或 `GENERATED …`)
|
||||
- 占位符 `?` → `$1,$2,…`
|
||||
- 标识符双引号规则对齐
|
||||
|
||||
### 3.2 缓存 `# cache` / `# 缓存`
|
||||
|
||||
```markdown
|
||||
*c = > web.cache url="memory:"*
|
||||
*c = > c.set key="k" value="v" ttl=60*
|
||||
*v = > c.get key="k"*
|
||||
*c = > c.del key="k"*
|
||||
```
|
||||
|
||||
方法:`get` · `set`(可选 `ttl` 秒)· `del` · `exists` · `ttl`。
|
||||
|
||||
配置表可选(装配时合并进 url / 默认 TTL):
|
||||
|
||||
| 键 | 值 |
|
||||
|----|-----|
|
||||
| url | redis://127.0.0.1:6379/0 |
|
||||
| ttl | 3600 |
|
||||
|
||||
### 3.3 对象存储 `# storage` / `# 存储`
|
||||
|
||||
```markdown
|
||||
*blob = > web.storage url="file:data/blobs"*
|
||||
> `blob`.put key="avatar/1.png" path="local.png" content_type="image/png"
|
||||
*got = > `blob`.get key="avatar/1.png"*
|
||||
> `blob`.delete key="avatar/1.png"
|
||||
*keys = > `blob`.list prefix="avatar/"*
|
||||
```
|
||||
|
||||
方法:`put`(`path=` 本地文件或 `body=` 文本)· `get`(返回 `{ok, body|path, content_type}`)· `delete` · `list`。
|
||||
|
||||
---
|
||||
|
||||
## 4. ABI 名
|
||||
|
||||
| ABI | 说明 |
|
||||
|-----|------|
|
||||
| 既有 `web_db_*` | 内部按 `url` 方案分发 SQLite / Postgres |
|
||||
| `web_cache_new/get/set/del/exists/ttl` | 缓存 |
|
||||
| `web_storage_new/put/get/delete/list` | 对象存储 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 测试
|
||||
|
||||
| 金样 | 内容 |
|
||||
|------|------|
|
||||
| `tests/ext/web-drivers-smoke.mq.md` | `memory:` 缓存往返;`file:` 存储 put/get/list/delete;`web_db_new` 接受 `postgres://` 句柄形状(不要求本机有库) |
|
||||
| 可选 live | `MARQDO_TEST_POSTGRES` / `MARQDO_TEST_REDIS` / `MARQDO_TEST_S3` 非空时跑真实连通(CI 默认关) |
|
||||
|
||||
---
|
||||
|
||||
## 6. 非本波次
|
||||
|
||||
- 连接池大小 / 读写分离配置表
|
||||
- Redis 集群 / Sentinel
|
||||
- S3 预签名 URL 作者面糖(可后续加方法)
|
||||
- 把 session 默认改存 Redis(仍默认 SQLite 表;可选后续)
|
||||
@@ -0,0 +1,285 @@
|
||||
# 网络扩展波次:`ext/web` 鉴权 · WebSocket · 标准库网络原语
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Draft(本波次锁定设计)** |
|
||||
| 日期 | 2026-08-24 |
|
||||
| 相关 | [ext-web.md](ext-web.md) · [ext-abi.md](ext-abi.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-cli.md](ext-cli.md) |
|
||||
| 目标 | 补齐 `ext/web` 登录鉴权(session/cookie)、WebSocket 端点;为网络扩展所需的**基础设施解析原语**适当补强 `lib/net`(标准库)。 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话
|
||||
|
||||
**领域能力(鉴权、WebSocket 服务器)全部走 ABI 插件 `plugins/web`;纯解析基础设施(cookie / multipart 解析、WS 客户端)按需进入标准库 `lib/net`,因为标准库需要支撑扩展库开发。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 边界判定:什么进标准库 `lib/net`,什么进扩展
|
||||
|
||||
### 1.1 跨语言调研结论
|
||||
|
||||
| 语言 | 标准库 | 扩展/生态 | 边界准则 |
|
||||
|------|--------|----------|---------|
|
||||
| Python | `urllib`(URL/基础 HTTP)、`http.cookies`(**cookie 解析器在标准库**) | `requests`/`httpx`(session/连接池/便利层) | 标准库 = 基础设施原语(解析器);便利层 = 第三方 |
|
||||
| Node.js | `http`/`https`/`http2`(低层流式,不解析 body) | express、ws、formidable | 足够 fancy 就不进核心;核心只放几乎人人要用的低层原语;**先 userland 验证再拉进 core** |
|
||||
| Go | `net/http`(服务器+客户端都在标准库)、`net/http/cookiejar`(**RFC 6265 cookie jar 在标准库**) | `golang.org/x/net`(publicsuffix 等演进性) | HTTP 是「与 stdin 同级」的核心能力;**cookie 解析/管理进标准库**;持久化等演进性能力在外 |
|
||||
| Rust | 极小 std(无 HTTP) | `http`(词汇)→ `hyper`(传输)→ `reqwest`(便利) | 分层;HTTP 因生态多样不进 std |
|
||||
|
||||
**共识**:
|
||||
1. **cookie 解析/管理(RFC 6265)**在 Python/Go 都是**标准库**(`http.cookies`、`net/http/cookiejar`)。
|
||||
2. **multipart/form-data 解析**在 Go 是标准库(`net/http`),在 Python 是第三方 `multipart`。
|
||||
3. **WebSocket** 几乎总在扩展/第三方(Node `ws`、Python `websockets`、Go `gorilla/websocket`),**很少进语言标准库**。
|
||||
4. **session 是领域级便利**,几乎所有语言都在框架层(express-session、Django session),不在语言标准库。
|
||||
|
||||
### 1.2 Marqdo 判定(锁定)
|
||||
|
||||
| 能力 | 类型 | 归属 | 理由 |
|
||||
|------|------|------|------|
|
||||
| `cookie.parse` / `cookie.parse_response` | 基础设施解析 | **`lib/net`(标准库)** | 对齐 Go/Python 标准库;`ext/web` 鉴权依赖 |
|
||||
| `multipart.parse` | 基础设施解析 | **`lib/net`(标准库)** | 对齐 Go 标准库;`ext/web` 文件上传依赖 |
|
||||
| `ws.connect`(客户端) | 基础连接 | **`plugins/web`(ABI)+ `ext/web`** | WS 栈(tokio-tungstenite)已在 web 插件依赖链;核心 `Cargo.toml` 锁定 rustc 1.81 不宜再引入 WS 栈;符合「尽量只 ABI」 |
|
||||
| `web.session_*`(session 管理) | 领域 | **`plugins/web`(ABI)+ `ext/web`** | session 是框架层便利,不进标准库 |
|
||||
| `/admin` 登录鉴权 | 领域 | **`plugins/web`(ABI)+ `ext/web`** | 网站领域能力 |
|
||||
| `web_ws`(服务器端点) | 领域 | **`plugins/web`(ABI)+ `ext/web`** | WebSocket 服务器是网站能力 |
|
||||
|
||||
**实现约束(用户要求)**:
|
||||
- 标准库新增的**解析原语**(cookie/multipart)是纯函数、无网络 I/O,作为 L0.5 宿主原语进 `src/host/`(与 `url_encode` 同模式),由 `lib/net` 薄包装——这符合「标准库需要支持扩展库开发」。
|
||||
- **涉及网络 I/O 的 WS 能力**(客户端 + 服务器端点)一律进 `plugins/web`(ABI v2),由 `ext/web` / `ext/web/网页.mq.md` 包装。核心运行时(rustc 1.81 锁定)**不再新增** WS 栈依赖。
|
||||
- **网站领域能力**(session、鉴权中间件)一律进 `plugins/web`(ABI v2),由 `ext/web` 包装。
|
||||
- **禁止**:为这些能力修改核心语法;禁止在 `src/host/` 塞领域逻辑。
|
||||
|
||||
---
|
||||
|
||||
## 2. 标准库 `lib/net` 新增(基础设施原语)
|
||||
|
||||
### 2.1 `cookie.parse` / `解析Cookie`
|
||||
- 形参:`text`(`Cookie:` 请求头或 `Set-Cookie:` 响应头)
|
||||
- 结果:`[{name, value, path, domain, expires, max_age, secure, http_only, same_site}]`
|
||||
- 行为:RFC 6265 解析;`Set-Cookie` 多 cookie 分条;无属性则字段为空。
|
||||
|
||||
**英文(`lib/net.mq.md`):**
|
||||
```markdown
|
||||
## cookie_parse
|
||||
+ `text`
|
||||
|
||||
**> host_cookie_parse text=`text`**
|
||||
```
|
||||
|
||||
**中文(`lib/网络.mq.md`):**
|
||||
```markdown
|
||||
## 解析Cookie
|
||||
+ `内容`
|
||||
|
||||
**> host_cookie_parse text=`内容`**
|
||||
```
|
||||
|
||||
### 2.2 `multipart.parse` / `解析多部分`
|
||||
- 形参:`body`(文本)、`boundary`
|
||||
- 结果:`[{name, filename, content_type, value}]`(`value` 为字段值;文件字段用 `filename` + `content_type` + `value`(base64 或文本))
|
||||
- 行为:解析 `multipart/form-data` 正文;字段名 → value;文件字段带 filename。
|
||||
|
||||
**英文:**
|
||||
```markdown
|
||||
## multipart_parse
|
||||
+ `body`
|
||||
+ `boundary`
|
||||
|
||||
**> host_multipart_parse body=`body` boundary=`boundary`**
|
||||
```
|
||||
|
||||
**中文:**
|
||||
```markdown
|
||||
## 解析多部分
|
||||
+ `正文`
|
||||
+ `边界`
|
||||
|
||||
**> host_multipart_parse body=`正文` boundary=`边界`**
|
||||
```
|
||||
|
||||
### 2.3 WebSocket 客户端 — 见 §3.4(`plugins/web` ABI)
|
||||
|
||||
WS 客户端为领域能力,放 `plugins/web`(ABI)而非标准库,理由见 §1.2。`lib/net` 不新增 WS 客户端包装,避免标准库依赖 ext 插件。
|
||||
|
||||
---
|
||||
|
||||
## 3. `plugins/web`(ABI v2)新增:领域能力
|
||||
|
||||
### 3.1 Session 存储(`web_session_*`)
|
||||
插件进程内 `static` 内存存储(`HashMap<session_id, HashMap<String,Value>>`),与 `web_listen` 同生命周期。
|
||||
|
||||
| ABI 名 | 形参 | 结果 |
|
||||
|--------|------|------|
|
||||
| `web_session_new` | 可选 `ttl_sec` | `{id}`(新 session id) |
|
||||
| `web_session_set` | `id`, `key`, `value` | `{ok:true}` |
|
||||
| `web_session_get` | `id`, `key` | 值或 `{ok:false}` |
|
||||
| `web_session_del` | `id`, `key` | `{ok:true}` |
|
||||
| `web_session_destroy` | `id` | `{ok:true}` |
|
||||
|
||||
### 3.2 `/admin` 登录鉴权(`web_auth_*`)
|
||||
- 作者面:`web.auth` 类(`网页.鉴权`),形参 `admin_users`(`|用户名|密码|` 表)、可选 `session_ttl`。
|
||||
- `listen` 时若配置了 auth:`/admin*` 未登录 → 跳转 `/admin/login`;登录页 `POST` → 校验 `admin_users` 表 → 写 session cookie → 重定向。
|
||||
- 登出:`/admin/logout` → 销毁 session。
|
||||
|
||||
| ABI 名 | 形参 | 结果 |
|
||||
|--------|------|------|
|
||||
| `web_auth_login` | `username`, `password`, `users`, `session_ttl` | `{ok:true, session_id}` 或 `{ok:false}` |
|
||||
| `web_auth_check` | `session_id`, `users` | `{ok:true}` 或 `{ok:false}` |
|
||||
| `web_auth_logout` | `session_id` | `{ok:true}` |
|
||||
|
||||
### 3.3 WebSocket 服务器端点(`web_ws_route`)
|
||||
- 作者面:`app.route_ws` / `应用.路由实时`,形参 `path`、可选 `echo=True`。
|
||||
- `listen` 时 `{path}` 升级为 WS:`echo=True` 回发原文;否则接收并丢弃(扩展点)。
|
||||
|
||||
| ABI 名 | 形参 | 结果 |
|
||||
|--------|------|------|
|
||||
| `web_app_route_ws` | `app`, `path`, `echo` | `{app}`(登记 WS 端点) |
|
||||
|
||||
### 3.4 WebSocket 客户端(`web_ws_connect`)
|
||||
- 作者面:`web.ws` / `网页.实时`,形参 `url`、`message`、可选 `headers`、`timeout_sec`。
|
||||
- 行为:客户端连接一次 WS,发 `message`,收**全部**服务器回文后关闭。**单请求-响应式**(非长驻),与 Marqdo 同步模型一致。
|
||||
|
||||
| ABI 名 | 形参 | 结果 |
|
||||
|--------|------|------|
|
||||
| `web_ws_connect` | `url`, `message`, `headers`(map), `timeout_sec` | `{ok:true, messages:[…]}` 或 `{ok:false, error}` |
|
||||
|
||||
**英文(`ext/web/web.mq.md`):**
|
||||
```markdown
|
||||
# ws
|
||||
+ `timeout_sec`=30
|
||||
|
||||
## connect
|
||||
+ `url`
|
||||
+ `message`
|
||||
+ `headers`=None
|
||||
```
|
||||
|
||||
**中文(`ext/web/网页.mq.md`):**
|
||||
```markdown
|
||||
# 实时
|
||||
+ `超时秒`=30
|
||||
|
||||
## 连接
|
||||
+ `地址`
|
||||
+ `消息`
|
||||
+ `headers`=None
|
||||
```
|
||||
|
||||
> `plugins/web` 用 `tokio-tungstenite`(与 axum WS 同栈,版本兼容 rustc 1.81)。
|
||||
|
||||
---
|
||||
|
||||
## 4. `ext/web` 作者面新增
|
||||
|
||||
### 4.1 英文面(`web.mq.md`)
|
||||
|
||||
```markdown
|
||||
# auth
|
||||
+ `users` # |用户名|密码| 表
|
||||
+ `session_ttl`=3600
|
||||
|
||||
## login
|
||||
+ `username`
|
||||
+ `password`
|
||||
|
||||
## check
|
||||
+ `session_id`
|
||||
|
||||
## logout
|
||||
+ `session_id`
|
||||
```
|
||||
|
||||
`# app` 新增 `## route_ws`:
|
||||
```markdown
|
||||
## route_ws
|
||||
+ `path`
|
||||
+ `echo`=True
|
||||
```
|
||||
|
||||
### 4.2 中文面(`网页.mq.md`)
|
||||
|
||||
```markdown
|
||||
# 鉴权
|
||||
+ `用户表`
|
||||
+ `会话时长`=3600
|
||||
|
||||
## 登录
|
||||
+ `用户名`
|
||||
+ `密码`
|
||||
|
||||
## 校验
|
||||
+ `会话id`
|
||||
|
||||
## 登出
|
||||
+ `会话id`
|
||||
```
|
||||
|
||||
`# 应用` 新增 `## 路由实时`:
|
||||
```markdown
|
||||
## 路由实时
|
||||
+ `路径`
|
||||
+ `回显`=真
|
||||
```
|
||||
|
||||
### 4.3 用法示例(英文)
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`admins` =
|
||||
| 用户名 | 密码 |
|
||||
|--------|------|
|
||||
| admin | secret |
|
||||
|
||||
*store = > db.open *
|
||||
*page = > web.page title="Site" *
|
||||
*app = > web.app page=`page` db=`store` admin=True host=127.0.0.1 port=18081 *
|
||||
*app = > `app`.route_ws path="/live" echo=True *
|
||||
*app = > web.auth users=`admins` *
|
||||
> `app`.listen
|
||||
|
||||
*echo = > web.ws.connect url="ws://127.0.0.1:18081/live" message="hi" *
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. form 完善(现有功能验证 + 补测试)
|
||||
|
||||
现状已具备(无需改代码,需验证):
|
||||
- `action=update`:hidden `id` + `db.update`(form.rs `from_schema`/`submit` 已实现)
|
||||
- 校验失败页级回显:`submit_and_respond` → `render_page_ex`(http.rs 已实现)
|
||||
|
||||
本波次为 update 流程和页级回显补 gold 测试,确认端到端可用。
|
||||
|
||||
---
|
||||
|
||||
## 6. 测试与验收
|
||||
|
||||
| 测试 | 内容 |
|
||||
|------|------|
|
||||
| `tests/ext/web-net-smoke.mq.md` | session new/set/get/del + auth login/check/logout + `route_ws`/`app.auth` 登记 + ws 连接失败路径(离线) |
|
||||
| `tests/lib/net-cookie.mq.md` | `cookie_parse` 解析 |
|
||||
| `tests/lib/net-multipart.mq.md` | `multipart_parse` 解析 |
|
||||
| `tests/ext/web-admin-smoke.mq.md` | form `action=update` 全流程 + 校验失败 `errors` 回显 |
|
||||
| 现有 gold | 全量回归(树遍历 + 字节码) |
|
||||
|
||||
验收:`cargo test --test gold` 全绿(除网络 live),双后端一致。
|
||||
|
||||
### 6.1 字典操作约束(作者面)
|
||||
|
||||
Marqdo 原生字典操作:GFM 横表**构造**、脚注取元 `变量[^键]` **读取**。`ext/web` 作者面**不使用** `json.get` / `json.set` 做字典读取/改写——所有字段读取一律 `self[^键]`(或实例变量 `[^键]`),避免"用 json 标准库做字典操作"的反模式。`json.parse` / `json.stringify` 仅用于文本 ↔ 结构化数据的序列化转换(如 HTTP body 解析),不用于本地字典读写。
|
||||
|
||||
### 6.2 相对路径按入口脚本解析(host_query `entry_dir`)
|
||||
|
||||
`static_dir`(如 `public`)与相对 db 路径(如 `sqlite:data/site.db`)此前按**进程 cwd** 解析——从仓库根目录跑 `examples/*/index.mq.md` 时,`/static` 404、db 会建到根目录,这是错误行为。
|
||||
|
||||
本波次修复:宿主新增 `host_query("entry_dir")`(返回入口 `.mq.md` 所在目录的绝对路径,回退 cwd),`plugins/web` 的 `web_listen` 将相对 `static_dir`、`db_url_of` 将相对 db 路径统一 `entry_dir().join(...)` 到绝对路径。于是无论从仓库根目录还是示例目录运行,静态资源与数据库都落在**脚本目录**下。绝对路径不受影响;`host_query` 不可用时回退旧 cwd 行为。
|
||||
|
||||
---
|
||||
|
||||
## 7. 非本波次
|
||||
|
||||
- Postgres / Redis / S3 驱动(roadmap W4,另行)
|
||||
- WS 广播房间、多客户端(先 echo 单连接)
|
||||
- session 持久化到 SQLite / 文件(先内存)
|
||||
- 复杂权限 / RBAC
|
||||
+20
-20
@@ -2,9 +2,9 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · 完成**(SQLite 作者面:页面装配 / db CRUD+`where` / form / 嵌入主区 / `app.route` / 路由 `/_part` / admin UI / `app.static`;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**;指导实现 |
|
||||
|
||||
@@ -112,10 +112,10 @@ myapp/
|
||||
|
||||
| 导入 | 库名(默认茎) | 类 / 方法 / 形参 |
|
||||
|------|----------------|------------------|
|
||||
| `> ext/web/web.mq.md` | `web` | **仅英文**:`page` · `compose_components` · `db` · `app` · `components=` … |
|
||||
| `> ext/web/网页.mq.md` | `网页` | **仅中文**:`页面` · `组件装配` · `数据库` · `应用` · `组件=` … |
|
||||
| `import web:ext/web/web.mq.md` | `web` | **仅英文**:`page` · `compose_components` · `db` · `app` · `components=` … |
|
||||
| `导入 网页:ext/web/网页.mq.md` | `网页` | **仅中文**:`页面` · `组件装配` · `数据库` · `应用` · `组件=` … |
|
||||
|
||||
禁止:`> ext/web/web.mq.md` 后写 `web.页面` / `` `页`.组件装配 ``(英文库混中文成员)。
|
||||
禁止:`import web:ext/web/web.mq.md` 后写 `web.页面` / `` `页`.组件装配 ``(英文库混中文成员)。
|
||||
禁止:在 `web.mq.md` 文件内定义中文 `## 组件装配` 别名。中英对等靠**两个文件**,不靠同一文件双份导出。
|
||||
|
||||
### 4.1 英文面(导入 `web.mq.md`)
|
||||
@@ -124,13 +124,13 @@ myapp/
|
||||
---
|
||||
title: web-site
|
||||
description: Home = page table; main may be inline; class methods assemble.
|
||||
> ext/web/web.mq.md
|
||||
> styles/shell.mq.md
|
||||
> components/nav.mq.md
|
||||
> components/side.mq.md
|
||||
> components/foot.mq.md
|
||||
> db/articles.mq.md
|
||||
> db/index.mq.md as db
|
||||
import web:ext/web/web.mq.md
|
||||
import shell:styles/shell.mq.md
|
||||
import nav:components/nav.mq.md
|
||||
import side:components/side.mq.md
|
||||
import foot:components/foot.mq.md
|
||||
import articles:db/articles.mq.md
|
||||
import db:db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -167,13 +167,13 @@ Main content is not a reusable component, so it is authored here.
|
||||
```markdown
|
||||
---
|
||||
title: 站点
|
||||
> ext/web/网页.mq.md
|
||||
> styles/shell.mq.md
|
||||
> components/nav.mq.md
|
||||
> components/side.mq.md
|
||||
> components/foot.mq.md
|
||||
> db/articles.mq.md
|
||||
> db/index.mq.md as db
|
||||
导入 网页:ext/web/网页.mq.md
|
||||
import shell:styles/shell.mq.md
|
||||
import nav:components/nav.mq.md
|
||||
import side:components/side.mq.md
|
||||
import foot:components/foot.mq.md
|
||||
import articles:db/articles.mq.md
|
||||
import db:db/index.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -28,7 +28,7 @@ Marqdo 项目中的 **YAML(及由其组成的 OKF 风格知识包)是工具
|
||||
|
||||
**唯一手写真相**仍是 `.mq.md` 源文件正文。YAML 清单是派生工件;过时则重新生成,禁止当成第二套权威配置去手改(除非工具链明确支持的「生成后微调」流程,且须可复现)。
|
||||
|
||||
**与源 frontmatter 的分工**(见 [markdown-mapping.md](markdown-mapping.md)):源文件 `---` 块可含 `title` 等元信息,以及人手声明的跨文件导入行 `> other.mq.md`。那是**源上的导入声明**,不是工程依赖锁。工具仍应据此(及正文 `>` 调用)**生成** OKF 风格依赖/模块目录;不要把生成目录手改成权威。
|
||||
**与源 frontmatter 的分工**(见 [markdown-mapping.md](markdown-mapping.md)):源文件 `---` 块可含 `title` 等元信息,以及人手声明的跨文件导入行 `import other:other.mq.md`。那是**源上的导入声明**,不是工程依赖锁。工具仍应据此(及正文 `>` 调用)**生成** OKF 风格依赖/模块目录;不要把生成目录手改成权威。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -26,7 +26,7 @@ Marqdo 要中英文都能自然书写。标准库已约定「**库文件名区
|
||||
| 层 | 是否导入 | 中英怎么区分 |
|
||||
|----|----------|--------------|
|
||||
| **L0 内核** | 否 | **同一文件内双名**:`print` ≡ `打印`;`True` ≡ `真` |
|
||||
| **L1 标准库** | 是(`> lib/…`) | **不同文件**:`text.mq.md` vs `文本.mq.md`(见 i18n 草案) |
|
||||
| **L1 标准库** | 是(`import …:lib/…`) | **不同文件**:`text.mq.md` vs `文本.mq.md`(见 i18n 草案) |
|
||||
|
||||
L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英文,写中文名就用中文,可在同一程序里混用。
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
**豁免:**
|
||||
- foreach 头 `` - [项](集合) `` 允许裸名或反引号(可混用),推荐裸名;循环体内引用仍用 `` `名` ``。
|
||||
- 脚注取元 `` 名[^键] ``:基名在紧跟 `` [^…] `` 时可省略反引号(`` `名`[^键] `` 仍合法);链式同理。
|
||||
- **斜体语句 / 粗体返回内部**:裸标识符默认是**变量**;字符串须 `"…"` 或 `'…'`;`` `名` `` 仍合法。
|
||||
- **斜体语句 / 粗体返回内部**:裸标识符默认是**变量**(含调用实参与方法接收者);文本字面量须 `"…"` 或 `'…'` 或引号实参(`key="文本"`);`` `名` `` 仍合法。这是 **Python 统一命名空间**:裸点号 `a.b` 在 `a` 为局部变量时为方法调用,否则为库路径。
|
||||
|
||||
---
|
||||
|
||||
@@ -50,9 +50,9 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
| 体内 `-` | **循环**(`while` 条件,或 `[项](集合)` / `` [`项`](`集合`) `` 遍历) |
|
||||
| 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` |
|
||||
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
|
||||
| `` > `对象`.方法 … `` | 方法调用(实例 map 须含 `_type`) |
|
||||
| frontmatter `> path.mq.md` [`as` / `作为` name] | 导入(绑定库名;默认 = 文件名茎) |
|
||||
| frontmatter `> use lib.member` [`as` name] / `使用` | 将库路径成员绑为本地短名 |
|
||||
| `` > `对象`.方法 … `` | 方法调用(独立 `>`;实例 map 须含 `_type`)。`*…*` 段内接收者裸名:`*x = > 对象.方法 …*` |
|
||||
| frontmatter `import bind:path.mq.md` / `导入` | 导入文件并绑定库名 |
|
||||
| frontmatter `import bind:lib.member` / `导入` | 将库路径成员绑为本地短名(与文件导入同形) |
|
||||
| `> lib.member …` / `> lib.Type.member …` | 点号路径调用(路径段裸名、无反引号) |
|
||||
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
|
||||
| `**…**` | **返回值**(架构级;函数结果) |
|
||||
@@ -93,7 +93,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
*answer = ev[^message]*
|
||||
*`亦可用` = 1*
|
||||
*亦可用 = 1*
|
||||
```
|
||||
|
||||
斜体内部:裸标识符 = 变量;字符串写 `"…"` / `'…'`。行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
|
||||
@@ -129,7 +129,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
|
||||
## 5. Frontmatter 与跨文件
|
||||
|
||||
文件头 `---` 对为元信息。其中 `> file.mq.md` 为**导入**(绑定库名,成员不倒进全局);`> use lib.member` / `> 使用 库.成员` 引入本地短名。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法须 `` > `var`.method ``。详见 [module-namespace.md](module-namespace.md)。
|
||||
文件头 `---` 对为元信息。其中 `import bind:path.mq.md` / `导入` 为**文件导入**;`import bind:lib.member` 为**短名**(废除独立 `use` 与 frontmatter `>` 导入)。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法在独立 `>` 调用须 `` > `var`.method ``(`*…*` 段内接收者裸名)。详见 [module-namespace.md](module-namespace.md)。
|
||||
|
||||
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
|
||||
|
||||
@@ -190,8 +190,11 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
| `\r` | 回车 |
|
||||
| `\\` | `\` |
|
||||
| `\"` | `"` |
|
||||
| `\'` | `'` |
|
||||
| `\xHH` | 十六进制字符(如 `\x22` → `"`) |
|
||||
| `\u{...}` | Unicode 码点(如 `\u{4e2d}` → `中`) |
|
||||
|
||||
引号内仍可用 `` `变量` `` 插值。字面反斜杠+n 写 `\\n`(裸 token `\\n` 则就是两个字符)。
|
||||
引号内仍可用 `` `变量` `` 插值。字面反斜杠+n 写 `\\n`(裸 token `\\n` 则就是两个字符)。未知转义(如 `\q`)按字面保留,不报错。
|
||||
|
||||
---
|
||||
|
||||
@@ -265,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 *
|
||||
@@ -302,6 +305,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
|
||||
- **List**:标签须为纯数字(1-based);`[^0]` / 越界 → 报错。
|
||||
- **Map**:标签为键文本(含 `"00"` 这类数字串键);缺键 → 报错。同一外形按接收值类型分派,不把 map 上的 `[^1]` 当成「第 1 个条目」。
|
||||
- 基名:`` `名`[^键] `` 与 `` 名[^键] `` 等价;无 `` [^ `` 时裸词仍是**文本字面量**(不是变量)。
|
||||
- **插值中的取元**:在调用实参值 / 引号字符串里,`` `变量` `` 后**紧跟**(无空白)`` [^…] `` 时按取元解析,而不是字面文本:`> print text=苹果单价:`水果价格`[^苹果]`;链式 `` `货架`[^苹果][^1] `` 同理。`` `变量` [^…] ``(有空白)则 `` [^…] `` 仍是文本。
|
||||
- 文末 `[^1]: …` 定义块仍是注释,与取元无关。
|
||||
- foreach:`List` 遍历元素;`Map` 遍历**键**(值用脚注取)。
|
||||
|
||||
|
||||
+90
-136
@@ -2,23 +2,23 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted;M1+M2 已落地** |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 状态 | **Accepted;统一 `import bind:target` 已锁定** |
|
||||
| 日期 | 2026-08-13 |
|
||||
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [ext-agent.md](ext-agent.md) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 动机
|
||||
|
||||
今日加载器把每个导入文件的顶层 `#` / `##` **扁平合并**进同一全局函数表;同名则**后导入静默覆盖**(`merge_top_level`)。
|
||||
加载器曾把每个导入文件的顶层 `#` / `##` **扁平合并**进同一全局函数表;同名则**后导入静默覆盖**。
|
||||
|
||||
后果:
|
||||
|
||||
- `lib/json` 的 `parse` 与 `lib/time` 的 `parse` 不能共存;import 顺序决定谁赢,错误表现为「缺 `pattern`」这类误导信息。
|
||||
- `lib/writeback` 的 `get` 盖住 `lib/json` 的 `get`。
|
||||
- `lib/json` 的 `parse` 与 `lib/time` 的 `parse` 不能共存。
|
||||
- 官方 ext / 多库编排无法按大型语言习惯书写 `time.parse` / `json.parse`。
|
||||
- 旧 frontmatter `import path:path.mq.md` 对 Markdown / 编辑器不友好,且与调用标记 `>` 抢外形。
|
||||
|
||||
**结论**:Marqdo 必须支持**模块命名空间**与**点号寻址**。扁平静默覆盖不是可保留的「兼容糖」,而是会**掩盖冲突**的缺陷行为;本设计予以废除(落地时为破坏性变更,不设双轨裸名回退)。
|
||||
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为可读的 `import bind:target`。
|
||||
|
||||
---
|
||||
|
||||
@@ -27,17 +27,17 @@
|
||||
### 2.1 目标
|
||||
|
||||
1. **导入绑定库名**:导入一个 `.mq.md` 得到一个**库(模块)绑定**,成员不倒进全局。
|
||||
2. **点号寻址调用**:`库.成员`、并预留 `库.对象.成员` 等多段路径;`.` 表示在定义树上的寻址,不是字段运算。
|
||||
3. **库名不是变量**:寻址段为**裸标识符**,**不加**反引号。反引号只用于值槽位(变量 / 形参 / 实例句柄)。
|
||||
4. **模块内名字默认不进全局**;需要本地短名时必须**显式** `use`,且冲突**报错**。
|
||||
5. **中英对等**:路径中英分文件;`as` / `作为` 与默认库名规则双语一致。
|
||||
2. **点号寻址调用**:`库.成员`、`库.对象.成员`;`.` 表示定义树寻址。
|
||||
3. **库名不是变量**:路径段为**裸标识符**,不加反引号。
|
||||
4. **短名与文件导入同形**:`import fmt:time.format`,废除独立 `use` 关键字。
|
||||
5. **中英对等**:`import` / `导入`。
|
||||
|
||||
### 2.2 非目标
|
||||
|
||||
- 第三方包管理 / 版本求解。
|
||||
- 在兼容期内继续支持扁平合并旧语义。
|
||||
- 「裸名仍可从最后一次导入解析」——**明确拒绝**。
|
||||
- 把库名写成 `` `time`.parse ``——**明确拒绝**(会把库名误当成变量)。
|
||||
- 旧 `> path.mq.md` / `> use` 双轨兼容。
|
||||
- `` `time`.parse ``(库名加反引号)。
|
||||
- `import fmt:time.*` 通配。
|
||||
|
||||
---
|
||||
|
||||
@@ -45,45 +45,46 @@
|
||||
|
||||
### 3.1 模块 / 库
|
||||
|
||||
每个可导入的 `.mq.md` 文件是一个**库模块**:
|
||||
|
||||
| 内容 | 归属 |
|
||||
|------|------|
|
||||
| 顶层 `##` 自由函数 | 库根下的**函数** |
|
||||
| 顶层 `#` 对象 | 库根下的**类型(对象)** |
|
||||
| 类型下的 `##` 方法 | 该对象节点下的**成员函数**(可被路径寻址;实例调用见 §4.4) |
|
||||
| 类型下的 `##` 方法 | 该对象节点下的**成员函数** |
|
||||
| 被导入文件的 `# main` | **不**作为入口执行 |
|
||||
|
||||
### 3.2 导入句法(frontmatter)
|
||||
|
||||
| 英文 | 中文 | 含义 |
|
||||
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。
|
||||
|
||||
| 含义 | 英文 | 中文 |
|
||||
|------|------|------|
|
||||
| `> lib/time.mq.md` | `> lib/时间.mq.md` | 导入;默认库名见 §3.3 |
|
||||
| `> lib/time.mq.md as time` | `> lib/时间.mq.md 作为 时间` | 导入并以给定库名绑定 |
|
||||
| 导入文件 | `import utils:utils.mq.md` | `导入 utils:utils.mq.md` |
|
||||
| 标准库 | `import json:lib/json.mq.md` | `导入 json:lib/json.mq.md` |
|
||||
| 短名(成员) | `import fmt:time.format` | `导入 fmt:时间.格式化` |
|
||||
|
||||
规则:
|
||||
|
||||
- `as` / `作为` 后为**裸库名**(不加反引号)。
|
||||
- 同一文件内两个导入不得绑定同一库名 → 硬错误。
|
||||
- 禁止「只写路径、成员洒进全局」的旧语义。
|
||||
- **绑定名必填**,在 `:` 左侧(裸名,无反引号)。
|
||||
- `:` 右侧 `target`:
|
||||
- 以 `.mq.md` 结尾 → **文件导入**;
|
||||
- 否则为 **点号路径**(≥2 段),把该成员绑为本地短名(须先有对应文件导入)。
|
||||
- 同一文件内绑定名不得冲突(文件库名与短名共用命名空间)→ 硬错误。
|
||||
- 旧写法 `> ….mq.md`、`> … as …`、`> use …`、`> 使用 …` → **硬错误**,并提示新句法。
|
||||
|
||||
### 3.3 默认库名
|
||||
### 3.3 废除的旧规则
|
||||
|
||||
省略 `as` / `作为` 时,库名 = **文件名茎**(去掉 `.mq.md`):
|
||||
不再支持:
|
||||
|
||||
| 路径 | 默认库名 |
|
||||
|------|----------|
|
||||
| `lib/time.mq.md` | `time` |
|
||||
| `lib/时间.mq.md` | `时间` |
|
||||
| `ext/ai/agent.mq.md` | `agent` |
|
||||
| `ext/ai/智能体.mq.md` | `智能体` |
|
||||
- 省略绑定名时用文件名茎作库名;
|
||||
- 导入侧 `as` / `作为`;
|
||||
- 独立关键字 `use` / `使用`。
|
||||
|
||||
### 3.4 调用解析顺序
|
||||
|
||||
1. **点号路径 callee**(§4)→ 按段在导入库 / 类型树上寻址。
|
||||
2. **当前文件**顶层 `#` / `##`(无点号的短名)。
|
||||
2. **当前文件**顶层 `#` / `##` 与 frontmatter **短名绑定**。
|
||||
3. **L0 内置**。
|
||||
4. **插件注册名**(`lib/plugin` 加载后的全局表)。
|
||||
4. **插件注册名**。
|
||||
5. 否则 → 未知 callee。
|
||||
|
||||
---
|
||||
@@ -96,78 +97,66 @@
|
||||
path_callee ::= ident ('.' ident)+
|
||||
```
|
||||
|
||||
- 每一段都是**裸标识符**(库名、类型名、函数名)。
|
||||
- **整条路径都不使用反引号**。
|
||||
- `.` 只表示寻址分隔,与「变量上的方法调用」分流(§4.4)。
|
||||
|
||||
### 4.2 二段:`库.成员`
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/time.mq.md
|
||||
> lib/json.mq.md
|
||||
import time:lib/time.mq.md
|
||||
import json:lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*`t` = > time.now_unix *
|
||||
*`s` = > time.format unix=`t` pattern=%Y-%m-%d *
|
||||
*`obj` = > json.parse text={"a":1} *
|
||||
*`a` = > json.get value=`obj` key=a *
|
||||
*t = > time.now_unix*
|
||||
*s = > time.format unix=`t` pattern="%Y-%m-%d"*
|
||||
*obj = > json.parse text={"a":1}*
|
||||
*a = > json.get value=`obj` key="a"*
|
||||
> print text=`s`
|
||||
```
|
||||
|
||||
| 路径 | 解析 |
|
||||
|------|------|
|
||||
| `time.now_unix` | 库 `time` → 函数 `now_unix` |
|
||||
| `json.parse` | 库 `json` → 函数 `parse` |
|
||||
| `agent.agent` | 库 `agent` → **类型** `agent`(构造) |
|
||||
|
||||
库根下的函数调用**不**注入 `self` / `自`。
|
||||
|
||||
### 4.3 三段及以上:`库.对象.成员`(预留并锁定语义)
|
||||
|
||||
后续常见形态:
|
||||
### 4.3 三段:`库.对象.成员`
|
||||
|
||||
```markdown
|
||||
> agent.agent # 库 → 类型:构造
|
||||
> 某库.某对象.某函数 # 库 → 类型 → 该类型下的 ## 成员
|
||||
```
|
||||
|
||||
解析规则(锁定):
|
||||
实例方法须 `` > `var`.method ``;无接收者的 `库.类型.方法` → 硬错误。
|
||||
|
||||
1. 第一段必须是**已导入库名**。
|
||||
2. 第二段起在上一段节点的子表中查找:类型节点或函数节点。
|
||||
3. 若最终落在**函数**上则发起调用;若落在**类型**上则发起构造。
|
||||
4. 路径中任一段缺失 → 硬错误(禁止模糊回落到全局短名)。
|
||||
### 4.4 变量 / 实例 vs 库路径(Python 统一命名空间)
|
||||
|
||||
实例方法若需要接收者,仍走 §4.4;`库.对象.方法` 表示定义树上的该成员(无接收者时:仅当该成员可作为无 `self` 的关联函数调用,否则报错「需要实例」)。这样 `.` 始终是**定义寻址**,逻辑一致。
|
||||
| 写法 | 含义 |
|
||||
|------|------|
|
||||
| `time.parse` | 库路径(裸名,第一段非变量) |
|
||||
| `` > `助手`.step `` | 独立 `>` 调用:实例方法(接收者反引号) |
|
||||
| `*回复 = > 助手.step …*` | `*…*` 段内:若 `助手` 是变量 → 实例方法;否则 → 库路径 |
|
||||
|
||||
中文库同理:`时间.格式化`、`智能体.智能体`、`智能体.智能体.单步`(若对类型成员做路径调用)。
|
||||
**统一规则**(与 Python 一致):对裸点号 `a.b`,当 `a` 是当前作用域**局部变量**时解释为**方法调用**(`a` 为接收者);否则解释为**库路径**(`lib.a.b`)。此规则同时应用于树遍历与字节码两后端。
|
||||
|
||||
### 4.4 变量 / 实例 vs 库路径(反引号分界)
|
||||
- 在**独立 `>` 调用**中裸词 = 文本,故方法接收者仍须反引号:`` > `助手`.step ``。
|
||||
- 在 **`*…*` / `**…**` 段内**裸词 = 变量,接收者不加反引号:`*回复 = 助手.step …*`。
|
||||
|
||||
| 写法 | 左侧重 | 是否反引号 |
|
||||
|------|--------|------------|
|
||||
| `time.parse` | 库名(绑定) | 路径段皆**裸名** |
|
||||
| `agent.agent` | 库名.类型名 | 裸名 |
|
||||
| `` > `助手`.step `` | **变量**(实例句柄) | 接收者**必须**反引号 |
|
||||
| `` > `out`.… `` | 变量 | 反引号 |
|
||||
|
||||
原则:
|
||||
|
||||
- **名在定义/导入空间里** → 点号路径,无 `` ` ` ``。
|
||||
- **名在值环境里**(绑定结果、形参、`self`)→ 反引号标识符;方法调用保持现有 `` > `obj`.method ``。
|
||||
|
||||
禁止混写 `` > `time`.parse ``(把库当成变量)。
|
||||
|
||||
### 4.5 应用侧完整示例
|
||||
### 4.5 短名示例
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/time.mq.md
|
||||
> lib/writeback.mq.md
|
||||
> ext/ai/agent.mq.md
|
||||
import time:lib/time.mq.md
|
||||
import fmt:time.format
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*t = > time.now_unix*
|
||||
*s = > fmt unix=`t` pattern="%Y-%m-%d"*
|
||||
```
|
||||
|
||||
### 4.6 应用侧完整示例
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import writeback:lib/writeback.mq.md
|
||||
import agent:ext/ai/agent.mq.md
|
||||
import json:lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -178,89 +167,54 @@ path_callee ::= ident ('.' ident)+
|
||||
> writeback.record value=`body` key=ok
|
||||
```
|
||||
|
||||
(上例假定 `json` 已导入;`stringify` 为该库成员。)
|
||||
|
||||
---
|
||||
|
||||
## 5. 导出面
|
||||
|
||||
默认:库内顶层 `#` / `##` 均可被路径访问。
|
||||
|
||||
类型下的 `##` 挂在该类型节点下,供 `库.类型.成员` 寻址;实例调用仍用 `` `变量`.成员 ``。
|
||||
|
||||
本版不引入 `private`。
|
||||
默认:库内顶层 `#` / `##` 均可被路径访问。本版不引入 `private`。
|
||||
|
||||
---
|
||||
|
||||
## 6. 显式 `use`(可选短名,非静默兼容)
|
||||
|
||||
| 英文 | 中文 |
|
||||
|------|------|
|
||||
| `> use time.format` | `> 使用 时间.格式化` |
|
||||
| `> use time.format as fmt` | `> 使用 时间.格式化 作为 fmt` |
|
||||
|
||||
- `use` 右侧为**点号路径**(裸名寻址)。
|
||||
- 引入后本地短名可见;与导入库名或当前文件顶层同名 → **硬错误**。
|
||||
- **禁止** `use time.*`(无通配 `use`)。
|
||||
|
||||
---
|
||||
|
||||
## 7. 与旧行为的关系(破坏性变更)
|
||||
## 6. 与旧行为的关系(破坏性变更)
|
||||
|
||||
| 旧 | 新 |
|
||||
|----|----|
|
||||
| 导入 = 合并进全局 | 导入 = 绑定库名 |
|
||||
| 同名后写覆盖 | 无跨库扁平同名 |
|
||||
| `> parse` 来源不明 | 必须 `json.parse` 或显式 `use` |
|
||||
| (若曾设想)`` `time`.parse `` | **否**;库路径不加反引号 |
|
||||
| `import time:lib/time.mq.md` | `import time:lib/time.mq.md` |
|
||||
| `import t`:lib/time.mq.md | `import t:lib/time.mq.md` |
|
||||
| `import fmt`:time.format
|
||||
| 茎名默认库名 | 绑定名始终显式 |
|
||||
| 扁平合并进全局 | 仅库绑定 + 可选短名 |
|
||||
|
||||
不提供扁平合并过渡开关。
|
||||
不提供旧 `>` 导入过渡开关。
|
||||
|
||||
---
|
||||
|
||||
## 8. 对分层与 ext 的影响
|
||||
## 7. 对分层与 ext 的影响
|
||||
|
||||
| 层 | 影响 |
|
||||
|----|------|
|
||||
| L0 内置 | 仍为全局短名 |
|
||||
| L1 / 官方 ext | 经库路径调用;**`ext/**/*.mq.md` 严禁 `host_*`** |
|
||||
| ABI 插件 | 插件注册表;agent/OKF 等领域逻辑放这里,**不得**塞进 `HostFn` |
|
||||
|
||||
**硬规则**:不得为「方便」把 `ext/ai` 领域能力写进 `src/host/dispatch.rs` / `src/host/*.rs`。标准库可走 `lib/*` → 薄 `host_*`;智能体专属走 `plugins/agent` 注册名(见 [ext-agent.md](ext-agent.md) §4)。
|
||||
| ABI 插件 | 插件注册表 |
|
||||
|
||||
---
|
||||
|
||||
## 9. 实现要点
|
||||
## 8. 实现要点
|
||||
|
||||
1. 加载返回模块树(库 → 类型 → 成员);取消跨文件 `merge_top_level` 泼洒。
|
||||
2. 调用方解析 `path_callee`:按 `.` 分段,自导入表下行。
|
||||
3. 区分路径 callee 与 `` `变量`.方法 ``(词法:首段是否反引号 / 是否含裸点号路径)。
|
||||
4. 金样例与 stdlib 文档改为 `time.parse` 形态。
|
||||
1. frontmatter 只解析 `import` / `导入` 行;右侧分流文件 / 成员。
|
||||
2. AST 仍用 `Import`(文件)与 `Use`(短名)存储,对外无 `use` 关键字。
|
||||
3. 金样例:`tests/structure/import/`、`tests/structure/ns/`。
|
||||
|
||||
| 阶段 | 内容 |
|
||||
|------|------|
|
||||
| M0 | 本文 Accepted(含本修订) |
|
||||
| M1 | 二段路径 `库.成员` + 破坏旧扁平 — **已落地**(tree + bytecode;`as`/`作为`;stdlib/ext/tests 已迁) |
|
||||
| M2 | 三段 `库.对象.成员`;`use` / `使用` — **已落地**(实例方法路径调用报错,须 `` `var`.method ``) |
|
||||
| M3 | 诊断工具(可选) |
|
||||
|
||||
**双后端**:tree 与 bytecode 均支持点号路径调用与 `use` / `使用`(与 M1/M2 同语义)。
|
||||
|
||||
**金样例**:
|
||||
|
||||
| 路径 | 测什么 |
|
||||
|------|--------|
|
||||
| `tests/structure/ns/` | 二段/三段路径、`use`、导入 `as` |
|
||||
| `tests/errors/ns-instance-method.mq.md` | `库.类型.方法` 无接收者 → 硬错误(须 `` `var`.method ``) |
|
||||
|
||||
**L1 薄包装**:命名空间下 `net.http_post` 等解析到 **`lib/*.mq.md` 的 `##` 包装**,不是宿主别名。包装未声明的可选形参会被静默丢弃(曾导致 live agent 401:`headers` 未传到 `host_http_post`)。规则见 [stdlib-modules.md](stdlib-modules.md) §2.1。
|
||||
| M1+M2 | 点号路径 + 短名 — 已落地 |
|
||||
| **Import 句法** | 统一 `import bind:target` — **本波次** |
|
||||
|
||||
---
|
||||
|
||||
## 10. 决议摘要
|
||||
## 9. 决议摘要
|
||||
|
||||
1. 导入绑定**库名**;成员不进全局。
|
||||
2. 调用以**裸名点号路径**寻址:`库.成员`,并支持 `库.对象.成员`;`.` = 定义树寻址。
|
||||
3. **库名 / 路径段不加反引号**;反引号只用于值变量与实例接收者。
|
||||
4. 拒绝扁平合并与裸名双轨兼容;短名仅显式单成员 `use`。
|
||||
5. M1/M2 已实现;M3 另开。
|
||||
1. 导入 = `import bind:target`(`导入` 等价)。
|
||||
2. target = `.mq.md` 文件 **或** `库.成员` 点号路径。
|
||||
3. 调用以裸名点号路径寻址;实例方法用反引号接收者(仅独立 `>` 调用;`*…*`/`**…**` 段内接收者不加反引号)。
|
||||
4. 裸点号 `a.b`:`a` 为局部变量 → 方法调用,否则 → 库路径(Python 统一命名空间)。
|
||||
+10
-10
@@ -33,24 +33,24 @@
|
||||
# 大模型
|
||||
+ `模型名`
|
||||
|
||||
*`自` = …配置 map…*
|
||||
**`自`**
|
||||
*自 = …配置 map…*
|
||||
**自**
|
||||
|
||||
## 运行
|
||||
+ `提示`
|
||||
|
||||
…使用 `自` …
|
||||
**`内容`**
|
||||
**内容**
|
||||
|
||||
# main
|
||||
|
||||
*`模型` = > 大模型 模型名=gpt-4o-mini *
|
||||
*`回复` = > `模型`.运行 提示=你好 *
|
||||
*模型 = > 大模型 模型名="gpt-4o-mini"*
|
||||
*回复 = > 模型.运行 提示="你好"*
|
||||
> print text=`回复`
|
||||
```
|
||||
|
||||
- `> 大模型 …` — 构造
|
||||
- `` > `模型`.运行 … `` — 方法(接收者 + `.` + 方法名)
|
||||
- `` > `模型`.运行 … `` — 方法(接收者 + `.` + 方法名;**独立 `>` 调用**需反引号接收者 `` `模型` ``;**在 `*…*` / `**…**` 段内**接收者不加反引号:`*回复 = > 模型.运行 提示="你好"*`)
|
||||
- `## 自由函数` 挂在模块顶层(非某对象子标题)— 与旧版顶层 `# http_get` 对等,现写为 `## http_get`
|
||||
|
||||
## 4. 标准库
|
||||
@@ -66,16 +66,16 @@
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*`msg` = "Hello, `who`!" *
|
||||
**`msg`**
|
||||
*msg = "Hello, `who`!"*
|
||||
**msg**
|
||||
|
||||
# Loud = > Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*`msg` = "HELLO, `who`!" *
|
||||
**`msg`**
|
||||
*msg = "HELLO, `who`!"*
|
||||
**msg**
|
||||
```
|
||||
|
||||
| 规则 | 说明 |
|
||||
|
||||
+10
-10
@@ -26,16 +26,16 @@
|
||||
|
||||
| 导入 | 库内函数名(示例) |
|
||||
|------|-------------------|
|
||||
| `> lib/text.mq.md` | `trim` · `split` · `join` |
|
||||
| `> lib/文本.mq.md` | `去空白` · `拆分` · `拼接` |
|
||||
| `> lib/table.mq.md` | `put` · `rows` · `row_at` · list/map(见 [stdlib-table.md](stdlib-table.md)) |
|
||||
| `> lib/表.mq.md` | `行数` · `取行` |
|
||||
| `import text:lib/text.mq.md` | `trim` · `split` · `join` |
|
||||
| `导入 文本:lib/文本.mq.md` | `去空白` · `拆分` · `拼接` |
|
||||
| `import table:lib/table.mq.md` | `put` · `rows` · `row_at` · list/map(见 [stdlib-table.md](stdlib-table.md)) |
|
||||
| `导入 表:lib/表.mq.md` | `行数` · `取行` |
|
||||
|
||||
示例:
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/text.mq.md
|
||||
import text:lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -44,7 +44,7 @@
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/文本.mq.md
|
||||
导入 文本:lib/文本.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
@@ -59,8 +59,8 @@
|
||||
|
||||
| 导入 | 含义 |
|
||||
|------|------|
|
||||
| `> lib/text-en.mq.md` | 英文 API |
|
||||
| `> lib/text-zh.mq.md` | 中文 API |
|
||||
| `import text-en:lib/text-en.mq.md` | 英文 API |
|
||||
| `import text-zh:lib/text-zh.mq.md` | 中文 API |
|
||||
|
||||
这与 §2.1 **等价可选**,不是第二套解析器:仍然是「写哪个路径就加载哪个文件」。
|
||||
**优先推荐 §2.1**(`text` / `文本`),后缀形式留给需要 ASCII-only 路径的环境。
|
||||
@@ -81,7 +81,7 @@
|
||||
`JSON` 为专有缩写,**不强求**中文库名或中文 API 翻译。官方只提供:
|
||||
|
||||
```text
|
||||
lib/json.mq.md # 中英文档均 `> lib/json.mq.md`;函数 parse / stringify / get / keys
|
||||
lib/json.mq.md # 中英文档均 `import json:lib/json.mq.md`;函数 parse / stringify / get / keys
|
||||
```
|
||||
|
||||
不设 `lib/数据.mq.md` 等平行文件。其余模块仍遵守 §2.1。详见 [stdlib-modules.md](stdlib-modules.md) §3.4。
|
||||
@@ -93,7 +93,7 @@ lib/json.mq.md # 中英文档均 `> lib/json.mq.md`;函数 parse / stringif
|
||||
| 层 | 内容 | 如何获得 |
|
||||
|----|------|----------|
|
||||
| **内置(L0)** | 极少:`print` `input` `len` `str` `int`(及语言字面量关键字) | 直接调用,无需导入 |
|
||||
| **标准库(L1)** | 文本/表等扩展 API;**通常**中英各一套文件、各一套函数名(**JSON 例外**:仅 `lib/json.mq.md`) | frontmatter `> lib/…` |
|
||||
| **标准库(L1)** | 文本/表等扩展 API;**通常**中英各一套文件、各一套函数名(**JSON 例外**:仅 `lib/json.mq.md`) | frontmatter `import …:lib/…` |
|
||||
| **宿主原语(实现细节)** | 若 `trim`/`split` 等暂由解释器实现 | 仅供标准库包装调用;**文档与用户站引导走 L1**,不鼓励当「关键字」堆砌 |
|
||||
|
||||
日后若某能力足够「核心」,可再升格为 L0;升格前先留在 L1。
|
||||
|
||||
@@ -198,8 +198,7 @@ src/host/math.rs # 数值、随机、对 formula 的 host 入口
|
||||
src/host/plot.rs # SVG
|
||||
lex/parse:空 RHS 赋值 + $$ 围栏 → Expr::Formula
|
||||
Value::Num / Value::Formula
|
||||
Interpreter.plots: Vec<String>
|
||||
lib/math.mq.md · lib/数学.mq.md
|
||||
Interpreter.plots: Vec<Stringimport math:lib/math.mq.md · lib/数学.mq.md
|
||||
```
|
||||
|
||||
依赖:纯 Rust;不绑 SymPy。公式复杂度、采样点、SVG 大小设硬上限。
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin** |
|
||||
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin**/browser |
|
||||
| 日期 | 2026-08-07 |
|
||||
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 |
|
||||
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
|
||||
@@ -17,10 +17,11 @@
|
||||
|--------|--------|--------|------|
|
||||
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
|
||||
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有(`put`/`改` + list/map;见 [stdlib-table.md](stdlib-table.md)) |
|
||||
| 浏览器效应 | `lib/browser.mq.md` | `lib/浏览器.mq.md` | WASM 客户端效应助手(GFM + helpers;勿用 `json.set` 链) |
|
||||
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 |
|
||||
| 系统 | `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` | 已有 |
|
||||
@@ -38,7 +39,7 @@
|
||||
|
||||
```text
|
||||
用户 .mq.md
|
||||
│ > lib/fs.mq.md / > ext/llm.mq.md
|
||||
│ import fs:lib/fs.mq.md / import llm:ext/llm.mq.md
|
||||
▼
|
||||
L1 官方库 / 官方 ext(.mq.md)
|
||||
│
|
||||
|
||||
@@ -17,7 +17,7 @@
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/table.mq.md
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
@@ -46,12 +46,12 @@ Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可
|
||||
|
||||
```markdown
|
||||
---
|
||||
> lib/text.mq.md
|
||||
> lib/table.mq.md
|
||||
import text:lib/text.mq.md
|
||||
import table:lib/table.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
调用示例:`> time.now_unix`、`> json.parse text=…`。需要本地短名时用 `> use time.format`(冲突 → 硬错误)。
|
||||
调用示例:`> time.now_unix`、`> json.parse text=…`。需要本地短名时用 `导入 format`(冲突:time.format`(冲突 → 硬错误)。
|
||||
|
||||
`std/text.mq.md` 等价于 `lib/text.mq.md`。解析顺序:
|
||||
|
||||
|
||||
@@ -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」强绑某一云厂商。
|
||||
|
||||
@@ -130,7 +130,7 @@
|
||||
- 候选 A:TS + remark-gfm — 能否区分 `-`/`+` bullet、解析单列表格、读 strong/emphasis。
|
||||
- 候选 B:Rust + comrak/pulldown — 同上。
|
||||
- (可选)C 或 D 若团队有偏好再做。
|
||||
2. **对照验收用例**(固定):`tests/structure/hello.mq.md`、`branch.mq.md`(`+`)、`collection.mq.md`(表)、含 `> x.mq.md` 的 frontmatter 行。
|
||||
2. **对照验收用例**(固定):`tests/structure/hello.mq.md`、`branch.mq.md`(`+`)、`collection.mq.md`(表)、含 `import x:x.mq.md` 的 frontmatter 行。
|
||||
3. **出 ADR**:选定「验证期实现」与(可选)「生产目标实现」是否同一语言。
|
||||
4. **再**建仓库脚手架与测试——禁止在 ADR 前默认生成 `package.json` / `Cargo.toml` 当既成事实。
|
||||
|
||||
|
||||
@@ -0,0 +1,164 @@
|
||||
# 调研:Marqdo `ext/web` 能否对接 Daphne / 业界应用服务器
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记** |
|
||||
| 日期 | 2026-08-29 |
|
||||
| 范围 | Daphne、Uvicorn、Gunicorn、Hypercorn 等 ASGI/WSGI 服务器;对照 Marqdo `plugins/web`(axum) |
|
||||
| 相关 | [web-net-capabilities.md](web-net-capabilities.md) · [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) |
|
||||
| 触发 | `app.listen` 已能本地起站;问「能否像业界一样用 Daphne 等服务器」 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**不能把 Marqdo 站点「塞进」Daphne / Uvicorn / Gunicorn 当 Python ASGI/WSGI 应用跑。**
|
||||
|
||||
Marqdo 的 HTTP 服务**已经是**应用服务器:`plugins/web` 内嵌 **axum + tokio**,由 `` `app`.listen `` / `` `应用`.监听 `` 绑定端口。这在 Rust 生态里的角色,约等于 Python 里的 **Uvicorn/Daphne**,而不是 Django/Flask「应用代码」。
|
||||
|
||||
业界生产部署要支持的,通常不是「换成 Daphne」,而是:
|
||||
|
||||
1. **反代 + TLS**(Nginx / Caddy / Traefik)→ 已文档锁定;
|
||||
2. **进程监督**(systemd / Docker / k8s)→ 运维层,与框架无关;
|
||||
3. (可选)多进程 / 多副本水平扩展 → 需会话外置等,见下文。
|
||||
|
||||
---
|
||||
|
||||
## 1. Daphne「等」服务器是什么
|
||||
|
||||
| 名称 | 协议面 | 典型搭档 | 角色 |
|
||||
|------|--------|----------|------|
|
||||
| **Daphne** | ASGI | Django Channels | Python 异步/WebSocket 参考服务器 |
|
||||
| **Uvicorn** | ASGI | FastAPI、Django ASGI | 高性能 ASGI(常作 Gunicorn worker) |
|
||||
| **Gunicorn** | 主要为 WSGI | Django/Flask | 进程管理 + worker;**不能**直接跑 ASGI/WebSocket |
|
||||
| **Hypercorn** | ASGI | 需 HTTP/2/3 时 | ASGI 另一实现 |
|
||||
| **Granian** | ASGI(Rust 实现) | Python 应用 | 用 Rust 加速 Python ASGI |
|
||||
|
||||
共同点:它们都假设应用暴露 **Python ASGI/WSGI callable**(`application` / `asgi.py`)。服务器负责 accept、协议解析、生命周期;**业务在 Python 进程里**。
|
||||
|
||||
2026 常见生产组合示例:
|
||||
|
||||
```text
|
||||
Internet → Nginx/Caddy (TLS) → Uvicorn/Daphne (ASGI) → Django/FastAPI 应用
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 2. Marqdo 今天怎么起服务
|
||||
|
||||
```text
|
||||
.mq.md(ext/web 作者面)
|
||||
→ ABI:web_listen / 路由装配
|
||||
→ plugins/web:组装 axum::Router
|
||||
→ tokio TcpListener + axum::serve ← 这里就是「应用服务器」
|
||||
```
|
||||
|
||||
关键事实(实现):
|
||||
|
||||
- `plugins/web/src/http.rs`:`TcpListener::bind` + `axum::serve`;
|
||||
- 依赖:`axum` 0.8、`tokio` multi-thread;含 WS、multipart、中间件层;
|
||||
- HTTPS:设计上 **进程内 TLS 不作为默认**;生产用反代终止 TLS + `cookie_secure`(见 [web-net-capabilities.md](web-net-capabilities.md) W7)。
|
||||
|
||||
因此:
|
||||
|
||||
| 问法 | 答案 |
|
||||
|------|------|
|
||||
| 能否 `daphne marqdo_app:app`? | **否** — 没有 Python ASGI 入口 |
|
||||
| 能否 `gunicorn -k uvicorn.workers…`? | **否** — 同上 |
|
||||
| 能否用 Nginx 反代到 `127.0.0.1:18085`? | **是** — 推荐生产路径 |
|
||||
| Marqdo 有没有「业界级」HTTP 栈? | **有** — axum/hyper 即 Rust 侧业界默认之一 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 分层对照(避免角色错位)
|
||||
|
||||
| 层级 | Python 典型 | Marqdo 对应 |
|
||||
|------|-------------|-------------|
|
||||
| 应用 / 路由 / 模板 / DB | Django / FastAPI | `ext/web` + `plugins/web` 装配 |
|
||||
| 应用服务器(accept / HTTP / WS) | Daphne / Uvicorn | **内嵌 axum::serve** |
|
||||
| 反代 / TLS / 静态边缘 | Nginx / Caddy | **外置反代**(文档已写) |
|
||||
| 进程管理 | systemd / Gunicorn master | systemd / Docker / k8s |
|
||||
|
||||
把 Daphne 接到 Marqdo,相当于要求「用 Python ASGI 服务器去托管 Rust axum 应用」——协议面不匹配,没有现成插槽。
|
||||
|
||||
---
|
||||
|
||||
## 4. 若目标是「生产级部署」,已支持什么 / 还差什么
|
||||
|
||||
### 4.1 已支持(或已锁定)
|
||||
|
||||
| 能力 | 状态 |
|
||||
|------|------|
|
||||
| 本地 / 内网 `listen` | ✅ |
|
||||
| HTTP + WebSocket | ✅(axum) |
|
||||
| 反代终止 HTTPS | ✅ 文档路径 |
|
||||
| 访问日志、限速、CORS、安全头等 | ✅ W1–W7 |
|
||||
| 会话可 SQLite 持久化 | ✅(单机多启需注意) |
|
||||
|
||||
### 4.2 与「Daphne 集群」对等时仍需注意
|
||||
|
||||
| 主题 | 说明 |
|
||||
|------|------|
|
||||
| **多进程副本** | 每进程各自 `listen` 时,内存会话 / 内存 cache / 内存 WS hub **不共享**;多副本需 sticky session,或会话/缓存外置(Redis 等,驱动面已有雏形) |
|
||||
| **优雅重启 / 零停机** | axum 可接 signal;未做成一等作者 API(运维可用 systemd + 反代) |
|
||||
| **HTTP/2 末端** | 多由反代提供;进程内 HTTP/1.1 足够常见场景 |
|
||||
| **与 Python 生态混部** | 可同机 Nginx 分流:`/api/py` → Uvicorn,`/` → Marqdo;**不是**共用一个 Daphne |
|
||||
|
||||
### 4.3 不建议的路线
|
||||
|
||||
1. **实现完整 ASGI 适配器让 Daphne 加载 Marqdo**
|
||||
成本高、收益低:等于在 Python 进程里再调一层 FFI/子进程,丢掉 axum 直驱优势。
|
||||
2. **把 axum 拆掉、改写为「纯应用、外挂任意服务器」**
|
||||
Rust 没有统一 ASGI;外挂只能是自定义协议或「只当 CGI」,与当前架构相反。
|
||||
|
||||
### 4.4 可选增强(若要对标「可换服务器」的体验)
|
||||
|
||||
| 方向 | 含义 | 优先级建议 |
|
||||
|------|------|------------|
|
||||
| **A. 部署文档 + 示例 Compose** | Nginx/Caddy + `marqdo run` + systemd | **高**(满足绝大多数「业界部署」诉求) |
|
||||
| **B. listen 运维旋钮** | workers 说明、graceful shutdown、Unix socket | 中 |
|
||||
| **C. 多副本清单** | 会话/WS/cache 外置检查表 | 中 |
|
||||
| **D. 反向:Marqdo 作边缘、反代到既有 ASGI** | 已可用 HTTP 客户端/路由外置服务 | 按需 |
|
||||
| **E. ASGI bridge** | 明确 **非目标** | 不做 |
|
||||
|
||||
---
|
||||
|
||||
## 5. 推荐生产拓扑(等价于「Nginx + Daphne」)
|
||||
|
||||
```text
|
||||
客户端
|
||||
│ HTTPS
|
||||
▼
|
||||
Nginx / Caddy / Traefik ← TLS、压缩、限流、静态可旁路
|
||||
│ HTTP proxy_pass
|
||||
▼
|
||||
marqdo run index.mq.md ← 内部 axum::serve(角色 ≈ Uvicorn/Daphne)
|
||||
(host=127.0.0.1 port=18085,cookie_secure=True)
|
||||
```
|
||||
|
||||
要点:
|
||||
|
||||
- Marqdo **只绑回环**;对外只暴露反代。
|
||||
- WebSocket:反代需 `Upgrade` / `Connection` 正确转发(与反代 Daphne 相同注意点)。
|
||||
- 多机:共享 DB(或 Postgres 驱动)、共享会话存储;WS 广播跨机需外置 pub/sub(当前 hub 为进程内)。
|
||||
|
||||
---
|
||||
|
||||
## 6. 结论与建议
|
||||
|
||||
| 问题 | 结论 |
|
||||
|------|------|
|
||||
| 能支持 Daphne 吗? | **不能直接托管**;协议是 Python ASGI,Marqdo 是 Rust axum 自托管。 |
|
||||
| 能支持「业界服务器」吗? | **能**:用 **Nginx/Caddy 等业界反代** 挂在 `listen` 前面;应用服务器层已由 axum 承担。 |
|
||||
| 缺的是换 Daphne,还是缺部署体验? | 主要是 **部署文档 / Compose / 多副本约定**,不是再嵌一套 ASGI 运行时。 |
|
||||
|
||||
**建议下一刀(若产品化):** 写一份 `examples/` 或 `doc/design` 下的「反代部署」最小样例(Caddyfile / nginx.conf + `cookie_secure`),而不是调研 ASGI bridge。
|
||||
|
||||
---
|
||||
|
||||
## 7. 参考
|
||||
|
||||
- 本仓:[web-net-capabilities.md](web-net-capabilities.md)(HTTPS 反代锁定)· [ext-web.md](ext-web.md)
|
||||
- Daphne:Django Channels 参考 ASGI 服务器
|
||||
- Uvicorn / Gunicorn worker:当代 Python ASGI 生产主流组合
|
||||
- axum:Tokio 生态 HTTP 应用框架(Rust 侧与 Uvicorn 同层)
|
||||
@@ -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 完结之上的内容站体验补齐,不推翻既有边界。
|
||||
@@ -0,0 +1,269 @@
|
||||
# 网络能力调研:从「能跑」到「完整项目」
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Accepted · W0–W7 + P3 完结**(2026-08-28 复核) |
|
||||
| 日期 | 2026-08-26(初稿)· 2026-08-28(完结复核) |
|
||||
| 相关 | [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [stdlib-modules.md](stdlib-modules.md) |
|
||||
| 目标 | 盘点 `ext/web` + `plugins/web` + `lib/net` 现状,对照主流语言网络栈,给出「开发一个完整 Web 项目」所需能力的差距清单与补强路线 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
**`ext/web` + `plugins/web` 已完成 W0–W7 + P3 路线图**:中间件/JSON API、数据层(连接池/事务/分页/FTS/迁移/外键/审计时间戳)、安全硬化(argon2/CSRF/会话持久化/限速/RBAC)、内容站点标配(SEO/RSS/Markdown/分页 UI)、上传下载/相册/ETag、sitemap/robots/错误页/重定向、WebSocket 广播与访问日志。足以在 Marqdo 上实现博客/CMS/中小型 API 站点;**未内置**的仅剩标签页模板(D6,可用路由+`db.count` 自建)与应用层反垃圾。边界不变:**纯解析进 `lib/net`,HTTP 服务器与领域能力进 `plugins/web` + `ext/web` 作者面**。
|
||||
|
||||
|
||||
---
|
||||
|
||||
## 1. 现状盘点(2026-08-26 实测)
|
||||
|
||||
### 1.1 `lib/net`(标准库,L0.5 宿主原语薄包装)
|
||||
|
||||
| 能力 | 归属 | 现状 |
|
||||
|---|---|---|
|
||||
| `http_get` / `获取` | host `net.rs` (ureq) | ✅ GET,返回 `{status, body}` |
|
||||
| `http_post` / `提交` | host `net.rs` | ✅ POST,默认 JSON CT |
|
||||
| `http_request` / `请求` | host `net.rs` | ✅ 通用 method+body+headers |
|
||||
| `http_post_sse` / `提交流式` | host `net.rs` | ✅ OpenAI 兼容 SSE 流式消费 |
|
||||
| `openai_sse_parse` / `解析流式` | host `net.rs` | ✅ 离线 SSE 解析 |
|
||||
| `url_encode` / `编码地址` | host `net.rs` | ✅ URL 编码 |
|
||||
| `cookie_parse` / `解析Cookie` | host `net.rs` | ✅ RFC6265 子集(请求头/响应头) |
|
||||
| `multipart_parse` / `解析多部分` | host `net.rs` | ✅ multipart/form-data 解析 |
|
||||
| `markdown_parse` / `解析Markdown` | host `net.rs` | ✅ GFM/Markdown → HTML(纯解析,W4c) |
|
||||
|
||||
**标准库网络原语已齐备**:客户端 GET/POST/SSE、URL 编码、cookie、multipart、Markdown 解析。服务器侧上传/下载/ETag 在 `plugins/web`(A5/P3)。
|
||||
|
||||
### 1.2 `plugins/web`(ABI v2,领域能力)
|
||||
|
||||
**服务器侧已实现:**
|
||||
|
||||
| 域 | ABI | 能力 |
|
||||
|---|---|---|
|
||||
| 页面 | `web_page_new` · `web_compose_components` · `web_compose_main` · `web_page_query` · `web_page_order` · `web_page_link_prefix` · `web_page_css` · `web_page_detail` | 页面装配、列表/排序、CSS、详情页 |
|
||||
| 样式 | `web_style` | GFM 表 → CSS(`make_style`/`样式装配`) |
|
||||
| 表单 | `web_form_new/fields/rules/validate/render/submit/from_schema` · `web_compose_form` | 字段表、校验表、渲染、提交、schema→form |
|
||||
| 数据库 | `web_db_new/init/insert/select/get/update/delete/exec/table_info/list_tables` | SQLite CRUD + where + order + limit |
|
||||
| 应用 | `web_app_new/route/mount_form/static/auth` · `web_app_route_ws` | 路由、静态目录、admin、鉴权、WS 端点 |
|
||||
| 会话 | `web_session_new/set/get/del/destroy` | 内存 TTL 会话 |
|
||||
| 鉴权 | `web_auth_login/check/logout/new` · `web_app_auth` | `/admin` 登录门禁 |
|
||||
| WebSocket | `web_ws_connect`(客户端)· `web_app_route_ws`(服务器) | 单请求-响应式客户端 + echo 服务器 |
|
||||
|
||||
**关键实现事实(2026-08-28 W7+P3 后):**
|
||||
|
||||
- **中间件 + JSON API**(W1):`app.configure` 装配 CORS、安全头、gzip、请求体上限、JSON 端点。
|
||||
- **数据层**(W2/W6/W7/P3):连接池、事务、分页、OR/IN/BETWEEN、`db.count`、迁移、FTS5 搜索、init 唯一/索引/外键、审计时间戳。
|
||||
- **安全**(W3s/P3):argon2、CSRF、SQLite 会话、CSPRNG session id、登录限速、RBAC(`app.gate` + 用户 `role`)。
|
||||
- **内容站点**(W4c/W7):SEO `page.meta`、RSS、Markdown 正文、`page.paginate`、sitemap/robots。
|
||||
- **媒体**(W5/P3):multipart 上传、下载、`app.gallery`、ETag/Cache-Control。
|
||||
- **运维向**(W6/W7):访问日志、自定义 404/500、301/307 重定向、WS 广播;HTTPS 由反代终止 + `cookie_secure`。
|
||||
- **仍属应用层约定**:标签聚合页模板(D6)、评论反垃圾、草稿/定时发布(表+where 即可)。
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 2. 主流网络栈对照(联网调研 2026-08)
|
||||
|
||||
### 2.1 分层共识(决定「标准库 vs 扩展」边界)
|
||||
|
||||
| 语言 | 标准库网络能力 | 扩展/框架能力 | 边界准则 |
|
||||
|---|---|---|---|
|
||||
| Python | `urllib`(HTTP 客户端)、`http.cookies`(cookie 解析器)、`http.server`(简易服务器)、`email` 多部分解析 | `requests`/`httpx`(连接池/session)、`FastAPI`/`Flask`(中间件/校验/模板) | 解析器进标准库;便利层/框架层在第三方 |
|
||||
| Node.js | `node:http`(低层流式,**不解析 body**)、`node:https` | express、fastify、ws、formidable | 低层原语进核心;fancy 功能 userland 验证后再进 core |
|
||||
| Go | `net/http`(服务器+客户端**都在标准库**)、`net/http/cookiejar`(RFC6265)、`net/smtp` | `golang.org/x/net`(演进性)、gin/echo | HTTP 与 stdin 同级的核心能力;cookie 解析进标准库 |
|
||||
| Rust | 极小 std(无 HTTP) | `hyper`→`reqwest`→`axum` | 分层;HTTP 生态多样不进 std |
|
||||
|
||||
**对本项目的三处判定(与 [ext-web-net.md](ext-web-net.md) 一致并延伸):**
|
||||
|
||||
1. **纯解析原语**(cookie / multipart / url)→ `lib/net` 标准库。✅ 已达成。
|
||||
2. **HTTP 服务器结构能力**(JSON / 中间件 / 上传下载 / HTTPS / 缓存头)→ `plugins/web`(ABI)。这是 axum 本身就在依赖链里的,不需要新增核心依赖。
|
||||
3. **领域能力**(session / auth / 分页 / 搜索 / RSS / SEO / 限流)→ `plugins/web` + `ext/web` 作者面。
|
||||
|
||||
### 2.2 「完整 Web 框架」能力清单(FastAPI / Express / Flask / axum 共通项)
|
||||
|
||||
> **marqdo 列**反映 **2026-08-28 W7+P3 完结** 后状态(见 §3 差距表)。
|
||||
|
||||
| 能力 | FastAPI | Express | Flask | axum | marqdo |
|
||||
|---|---|---|---|---|---|
|
||||
| 路由(含动态参数) | ✅ | ✅ | ✅ | ✅ | ✅ 动态路由 `/post/{slug}` |
|
||||
| 中间件管道 | ✅ | ✅ | ✅ | ✅(tower) | ✅ W1 `app.configure` |
|
||||
| CORS | ✅ 内置 | ✅ 中间件 | ✅ flask-cors | ✅ tower-http | ✅ W1 |
|
||||
| JSON 请求/响应 | ✅ 原生 | ✅ | ✅ | ✅ | ✅ W1 JSON API 表 |
|
||||
| 校验(schema/字段) | ✅ Pydantic | 手动(zod) | 手动 | ✅ extractor | ✅ form 校验表 |
|
||||
| 静态文件 | ✅ Starlette | ✅ | ✅ | ✅ | ✅ `app.static` |
|
||||
| 模板/渲染 | ✅ Jinja | ✅ | ✅ | ✅ | ✅ GFM 表装配 |
|
||||
| 会话 | ✅ | ✅ express-session | ✅ | ✅ | ✅ SQLite 持久化(W3s) |
|
||||
| 鉴权 | ✅ OAuth2/APIKey | ✅ | ✅ | ✅ | ✅ admin + RBAC(P3) |
|
||||
| 文件上传 | ✅ | ✅ multer | ✅ | ✅ | ✅ W5 upload |
|
||||
| WebSocket | ✅ | ✅ ws | ✅ Flask-SocketIO | ✅ | ✅ echo + 广播(W6) |
|
||||
| 安全头 | ✅ | ✅ helmet | ✅ | ✅ tower-http | ✅ W1 |
|
||||
| 限流 | ✅ | ✅ | ✅ | ✅ | ✅ 登录限速(W3s) |
|
||||
| 日志 | ✅ | ✅ morgan | ✅ | ✅ | ✅ access_log(W6) |
|
||||
| gzip 压缩 | ✅ | ✅ | ✅ | ✅ | ✅ W1 |
|
||||
| 分页 | 手动 | 手动 | ✅ paginate | ✅ | ✅ db + page UI(W2/W4c) |
|
||||
| 迁移 | ✅ alembic | ✅ | ✅ | ✅ sqlx | ✅ W6 `db.migrate` |
|
||||
| 测试工具 | ✅ TestClient | ✅ supertest | ✅ | ✅ | gold 测试(`tests/ext/web-*`) |
|
||||
| HTTPS/TLS | 反代 | 反代 | 反代 | ✅ rustls | 反代 + `cookie_secure`(W7 文档锁定) |
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 3. 差距分析:按「完整项目」四类需求
|
||||
|
||||
### 3.1 类 A:结构化 HTTP 基础设施(做 API / 前后端分离 / SPA 支撑)
|
||||
|
||||
| # | 缺失能力 | 影响 | 归属 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| A1 | **JSON 请求/响应**(`Json` extractor、`application/json` 响应、body 大小限制) | ✅ **已实现(W1)**:`接口` 表声明 JSON API 端点;`请求体上限` 配置 body 限制 | `plugins/web` | **P0 ✅** |
|
||||
| A2 | **中间件管道**(`app.configure` / `应用.装配`:CORS、安全头、压缩、请求体限制统一挂载) | ✅ **已实现(W1)**:`middleware.rs` 装配 GFM 表并 `app.layer` 挂到 axum | `plugins/web` | **P0 ✅** |
|
||||
| A3 | **CORS 支持**(`Access-Control-Allow-Origin` 可配) | ✅ **已实现(W1)**:`跨域` 表 `|允许来源|方法|头|暴露头|凭证|` | `plugins/web` | P1 ✅ |
|
||||
| A4 | **安全响应头**(CSP / X-Frame-Options / X-Content-Type-Options / HSTS / Referrer-Policy / 去 `X-Powered-By`) | ✅ **已实现(W1)**:`安全` 表 `|头|值|` | `plugins/web` | P1 ✅ |
|
||||
| A5 | **文件上传接收**(multipart extractor → 校验类型/大小 → 落盘)与**下载**(`Content-Disposition`) | ✅ **已实现(W5)**:`app.upload` / `app.download`;`file:` storage;离线 + curl live 金样 | `plugins/web` | P1 ✅ |
|
||||
| A6 | **HTTPS / TLS**(rustls 终止或反代提示) | ✅ **文档锁定(W7)**:进程内 TLS 不启用;反代终止 HTTPS,并设 `cookie_secure=True` | 文档 + `cookie_secure` | P2 ✅ |
|
||||
| A7 | **gzip / br 压缩** + **ETag / Cache-Control 缓存头** | gzip ✅(W1);Cache-Control ✅(W7);ETag ✅ **已实现(P3,下载/相册 + If-None-Match→304)** | `plugins/web` | P2 ✅ |
|
||||
| A8 | **访问日志**(请求方法/路径/状态/耗时) | ✅ **已实现(W6b)**:`configure access_log=True` → stderr | `plugins/web` | P2 ✅ |
|
||||
| A9 | **自定义 404/500 错误页** | ✅ **已实现(W7)**:`app.error_page` / `应用.错误页`;404 fallback + 500 页袋 | `plugins/web` | P2 ✅ |
|
||||
| A10 | **重定向增强**(permanent/自定义状态码) | ✅ **已实现(W7)**:`app.redirect` → 301/307 | `plugins/web` | P3 ✅ |
|
||||
|
||||
### 3.2 类 B:数据层深化(内容站点/社区的根基)
|
||||
|
||||
| # | 缺失能力 | 影响 | 归属 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| B1 | **连接池 / busy_timeout / WAL** | 高并发下 `database is locked`、每请求重连开销 | `plugins/web`(db.rs) | **P0 ✅** |
|
||||
| B2 | **事务 API**(`begin` / `commit` / `rollback`,或 `with_transaction` 包装) | 批量/多表写无原子性 | `plugins/web` | **P0 ✅** |
|
||||
| B3 | **结果集型裸查询**(exec 返回 rows) | count / join / group / 子查询完全不可用 | `plugins/web` | P1 ✅ |
|
||||
| B4 | **分页**(db 层 `limit`+`offset`;页面层上一页/下一页) | 列表页只能限量 | `plugins/web` + `ext/web` | P1 ✅(db 层;页面 UI 属 D4) |
|
||||
| B5 | **查询表达力**:OR / IN / BETWEEN / IS NULL / LIKE 转义 / 括号组合 | where 只能 AND | `plugins/web` | P1 ✅ |
|
||||
| B6 | **迁移机制**(schema 版本表 + 迁移脚本) | ✅ **已实现(W6)**:`db.migrate` + `_marqdo_migrations`(SQLite) | `plugins/web` + `ext/web` | P2 ✅ |
|
||||
| B7 | **索引 / 唯一 / 外键声明**(init 表增强) | ✅ **已实现(W7+P3)**:`唯一`/`索引`/`外键`(`posts.id` / `posts`) | `plugins/web` | P2 ✅ |
|
||||
| B8 | **聚合辅助**:count / group 便捷 API | 统计面板、标签计数 | `plugins/web` | P2 ✅(`db.count`) |
|
||||
| B9 | **全文搜索**(SQLite FTS5) | ✅ **已实现(W6)**:`db.fts` + `db.search`(bm25) | `plugins/web`(FTS5 现成) | P2 ✅ |
|
||||
| B10 | **时间戳 / 审计字段自动维护** | ✅ **已实现(P3)**:表含 `created_at`/`updated_at` 时 insert/update 自动写入 | `plugins/web` | P3 ✅ |
|
||||
|
||||
### 3.3 类 C:安全硬化(能上线的前提)
|
||||
|
||||
| # | 缺失能力 | 影响 | 归属 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| C1 | **密码哈希**(argon2/bcrypt/sha+盐,替代明文) | ✅ **已实现(W3s)**:argon2 | `plugins/web` | **P0 ✅** |
|
||||
| C2 | **CSRF 防护**(session-bound token,写操作校验) | ✅ **已实现(W3s)** | `plugins/web` | **P0 ✅** |
|
||||
| C3 | **登录限速/失败锁定**(每 IP/用户名 5 次/15min) | ✅ **已实现(W3s)** | `plugins/web` | P1 ✅ |
|
||||
| C4 | **会话持久化**(SQLite/文件,替代内存) | ✅ **已实现(W3s)** | `plugins/web` | P1 ✅ |
|
||||
| C5 | **加密安全 session id**(CSPRNG + 碰撞重试) | ✅ **已实现(W3s)** | `plugins/web` | P1 ✅ |
|
||||
| C6 | **cookie 增强**:`Secure` 标志、签名、滑动过期 | ✅ **已实现**:`cookie_secure` + 滑动 TTL(touch);cookie 签名未单独做 | `plugins/web` | P2 ✅ |
|
||||
| C7 | **防暴力破解 / 会话上限 / 后台过期清理** | ✅ 限速 + prune;会话条数硬上限可后续 | `plugins/web` | P2 ✅ |
|
||||
| C8 | **RBAC / 多角色**(作者/管理员/访客) | ✅ **已实现(P3)**:用户表 `role`/`角色`;`app.gate`;`/admin*` 默认需 `admin` | `plugins/web` + `ext/web` | P3 ✅ |
|
||||
|
||||
### 3.4 类 D:内容站点标配(博客/CMS 特有)
|
||||
|
||||
| # | 缺失能力 | 影响 | 归属 | 优先级 |
|
||||
|---|---|---|---|---|
|
||||
| D1 | **SEO**:每页 `<title>`/`meta description`/OG 标签/`canonical`/结构化数据 | ✅ **已实现(W4c)**:`page.meta` | `ext/web` | **P0 ✅** |
|
||||
| D2 | **sitemap.xml / robots.txt** 生成 | ✅ **已实现(W7)**:`app.sitemap` / `app.robots` | `plugins/web` + `ext/web` | P1 ✅ |
|
||||
| D3 | **RSS/Atom 输出**(`content_type=application/rss+xml` 路由) | ✅ **已实现(W4c)**:`route_rss` | `ext/web` + 插件 | P1 ✅ |
|
||||
| D4 | **分页导航 UI**(上一页/下一页,依赖 B4) | ✅ **已实现(W4c)**:`page.paginate` | `ext/web` | P1 ✅ |
|
||||
| D5 | **Markdown 渲染**(正文存储为 Markdown,渲染为 HTML) | ✅ **已实现(W4c)**:`lib/net` + 页面装配 | `lib/net` | **P0 ✅** |
|
||||
| D6 | **标签/分类聚合页**(`/tag/{slug}` 动态路由 + 计数) | 可用路由+`db.count` 自建(未内置模板) | `ext/web` | P2 |
|
||||
| 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 ✅ |
|
||||
|
||||
---
|
||||
|
||||
|
||||
## 4. 补强路线(分波次,按「标准库 vs 扩展」边界)
|
||||
|
||||
### 4.1 波次建议(每波独立可交付、可回归)
|
||||
|
||||
| 波次 | 主题 | 内容 | 对应差距 |
|
||||
|---|---|---|---|
|
||||
| **W1** | 服务器基础设施 | 中间件管道(CORS/安全头/压缩/请求体限制)+ JSON API(`application/json` 响应 + DB 查询端点) | A1 A2 A3 A4 A7 ✅ **已完成** |
|
||||
| **W2** | 数据层深化 | 连接池/busy_timeout/WAL + 事务 API + 结果集裸查询 + 分页(offset) + OR/IN/BETWEEN + 聚合 count | B1 B2 B3 B4 B5 B8 ✅ **已完成** |
|
||||
| **W3** | 安全硬化 | 密码哈希 + CSRF + 会话持久化 + CSPRNG session id + cookie 增强 + 登录限速/锁定 | C1–C7 ✅ |
|
||||
| **W4** | 内容站点标配 | SEO 元数据 + sitemap/robots + RSS + Markdown 渲染 + 分页导航 UI + 标签/分类 | D1–D5 ✅;D6 约定 |
|
||||
| **W5** | 上传与媒体 | multipart 文件上传接收 + 落盘 + 下载 + 图片库 | A5 ✅;D9 相册 P3 ✅ |
|
||||
| **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 边界判定要点(严格遵守既有约束)
|
||||
|
||||
1. **进标准库 `lib/net`**(纯解析、无网络 I/O、支持扩展库开发):
|
||||
- `markdown_parse`(GFM/Markdown → HTML,纯解析)→ D5 ✅。
|
||||
- `xml_escape` / RSS/Atom 纯文本装配辅助(如需)→ D3(作者面 `route_rss` 已够用)。
|
||||
- **不得**放进标准库:JSON API、中间件、上传接收、事务、会话(均涉 I/O 或领域语义)。
|
||||
2. **进 `plugins/web`(ABI)**:A1–A10、B1–B10、C1–C8、D7–D8 的插件侧 — **均已落地**(2026-08-28)。
|
||||
3. **进 `ext/web` 作者面(Marqdo)**:D1–D4、A5/D2/D9 等 GFM 表包装 — **均已落地**(中英 `web.mq.md` / `网页.mq.md`)。
|
||||
4. **已具备、无需新增**:动态路由、静态文件、表单校验/回显、session、admin/RBAC、WebSocket、SSE 客户端、cookie/multipart/Markdown 解析。
|
||||
|
||||
### 4.3 作者面示例(示 W4 落地形态,保持「代码即文档」)
|
||||
|
||||
**SEO 元数据(扩展页面表):**
|
||||
|
||||
```markdown
|
||||
`meta` =
|
||||
|
||||
| 键 | 值 |
|
||||
|---|---|
|
||||
| `title` | 文章标题 |
|
||||
| `description` | 摘要 |
|
||||
| `og_type` | article |
|
||||
| `canonical` | /post/{slug} |
|
||||
```
|
||||
|
||||
页面装配时并入 `<head>` —— 仍是「表 + 函数装配」,不引入 `json.*` 袋。
|
||||
|
||||
**RSS(扩展路由,响应头 `content_type=application/rss+xml`):**
|
||||
|
||||
```markdown
|
||||
*feed = > 页面.列出表 rows=`文章` 分页=20 排序="published desc"*
|
||||
*xml = > 文本.拼装 xs=`rss 片段们`*
|
||||
*`app` = > `应用`.路由 路径="/feed.xml" 内容=`xml` 类型="application/rss+xml"*
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. 结论
|
||||
|
||||
**W0–W7 + P3 已全部落地**(路线图见 [roadmap/ext-web.md](../roadmap/ext-web.md))。验收覆盖:
|
||||
|
||||
- 离线/在线 gold:`tests/ext/web-*-smoke.mq.md`(含 security、drivers、upload、w6、w7、p3)
|
||||
- 完整示例:`examples/marqdo-blog/`(列表/详情/标签/RSS/后台/上传/WS)
|
||||
- 作者面:`ext/web/web.mq.md` · `ext/web/网页.mq.md`
|
||||
- AI 编写指引:`skills/marqdo/`(§ ext/web)
|
||||
|
||||
**后续可选(非阻塞)**:标签页内置模板(D6)、cookie 签名、会话条数硬上限、应用层反垃圾、进程内 TLS(仍建议反代)。
|
||||
|
||||
**部署对照(Daphne / Uvicorn / 反代):** 见 [web-asgi-servers-and-marqdo.md](web-asgi-servers-and-marqdo.md) — Marqdo **不能**被 Daphne 托管;生产等价路径是 **反代 → 内嵌 axum `listen`**。
|
||||
|
||||
**一句话:`ext/web` 已是可上线级别的 Marqdo 动态站扩展;博客/CMS/中小型 API 可在表格 + 类方法作者面上完整实现。**
|
||||
|
||||
---
|
||||
|
||||
## 6. 附:博客示例能力对照(`examples/marqdo-blog`)
|
||||
|
||||
| 博客功能 | 现状 |
|
||||
|---|---|
|
||||
| 文章列表(首页) | ✅ |
|
||||
| 文章详情(动态路由) | ✅ |
|
||||
| 标签/分类 | ✅ 路由 + `db.where` + `db.count` |
|
||||
| 分页 | ✅ `db.paginate` + `page.paginate` |
|
||||
| 搜索 | ✅ FTS5 `db.search` |
|
||||
| SEO 元数据 | ✅ `page.meta` |
|
||||
| RSS | ✅ `app.route_rss` |
|
||||
| 评论 | ✅ 表 + form + where(反垃圾属应用层) |
|
||||
| 后台写文章 | ✅ admin CRUD + RBAC |
|
||||
| 草稿/发布 | ✅ `status` 字段 + where |
|
||||
| 上传配图 | ✅ `app.upload` + `app.gallery` |
|
||||
| 用户登录 | ✅ argon2 + CSRF + SQLite 会话 + 限速 |
|
||||
| sitemap / robots | ✅ W7 |
|
||||
| 实时终端(WS) | ✅ W6 广播 |
|
||||
|
||||
---
|
||||
|
||||
## 7. 附:Markdown 正文渲染(D5,已落地)
|
||||
|
||||
博客详情页正文经 `lib/net.markdown_parse`(`host_markdown_parse`)解析为 HTML,由 `plugins/web` 渲染层在页面装配时调用(W4c)。作者存储 Markdown 字符串于 DB,展示侧自动渲染 GFM 子集(标题、列表、链接、代码块等)。纯解析留在标准库;**不得**在 `ext/web` 作者面直接调 `host_*`。
|
||||
@@ -68,6 +68,28 @@ proxy = "http://127.0.0.1:7890"
|
||||
|
||||
---
|
||||
|
||||
## 3.5 Git 推送(遇网络失败时使用代理)
|
||||
|
||||
直连 `git push` 偶尔会报 `RPC failed; curl 35 Recv failure: Connection reset by peer` 或 `curl 56`(远端挂断,常见于数据包稍大时)。此时**通过本机代理 7890 推送**:
|
||||
|
||||
```bash
|
||||
# Linux/macOS(本机 clash 监听 127.0.0.1:7890)
|
||||
git -c http.proxy=http://127.0.0.1:7890 -c http.postBuffer=524288000 push origin main
|
||||
```
|
||||
|
||||
要点:
|
||||
|
||||
- 代理可用性先探测:`curl -x http://127.0.0.1:7890 -o /dev/null -w "%{http_code}\n" https://github.com`,返回 `200` 再推。
|
||||
- `http.postBuffer=524288000`(500 MB)用于规避推送大包被断开(`curl 56`);两个 `-c` 可叠加。
|
||||
- 该命令**一次性生效**,不写死仓库配置。若想长期默认走代理,可执行:
|
||||
```bash
|
||||
git config http.proxy http://127.0.0.1:7890
|
||||
git config http.postBuffer 524288000
|
||||
```
|
||||
- 若是别的代理端口,把 `7890` 换成实际端口(如 Windows 示例里 `$env:HTTPS_PROXY` 的同款端口)。
|
||||
|
||||
---
|
||||
|
||||
## 4. 目录约定
|
||||
|
||||
| 路径 | 含义 |
|
||||
|
||||
@@ -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,190 @@
|
||||
# 调研:`ext/agent` 在 A0–A4 之后还差什么
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记 · 缺口盘点(A0–A4 闭环之后)** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 前置调研 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md)(优势与优化原则) |
|
||||
| 已落地路线 | [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md)(**A0–A4 done**) |
|
||||
| 设计 | [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](../roadmap/agent-streaming.md) · [okf-near-match.md](../roadmap/okf-near-match.md) |
|
||||
| 外部对照(2026) | LangGraph persistence / CrewAI+Flows / MCP 工具协议 / 业界 Agent 评测与记忆层讨论 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
调研驱动的 **A0–A4** 已把 Marqdo 智能体的**差异化内核**补齐:工作簿补丁可靠、OKF 复用飞轮可读可用、过程事件可审、上下文有预算、外置检索/MCP 只作证据。
|
||||
|
||||
相对 2026 年主流框架(LangGraph、CrewAI、厂商 SDK、MCP 生态),Marqdo **不再缺「能跑的 Agent loop」**;缺口集中在:
|
||||
|
||||
1. **产品化与可发现性**(示例、文档新鲜度、上手路径)
|
||||
2. **生产配套**(评测 harness、真 MCP、断点续跑、HITL、飞轮指标)
|
||||
3. **可选扩展面**(并行 fan-out、多 Agent/A2A、trace 外发)
|
||||
|
||||
**不要**用缺口清单去证明应回退到隐藏 TOOL: 循环或把向量库升为权威真相——那与宪法冲突,也抵消已落地的优势。
|
||||
|
||||
---
|
||||
|
||||
## 1. 已落地基线(A0–A4)
|
||||
|
||||
| 波次 | 主题 | 验收要点 |
|
||||
|------|------|----------|
|
||||
| **A0** | 工作簿补丁 / 固化 | 整文件 FIND 护栏;`soft` 仅 miss;`workbook_solidify`;金样 `agent-workbook-patch-a0` |
|
||||
| **A1** | OKF 复用飞轮 | `list_tasks` 策展字段;`plan` 暴露 `match`/`score`;金样 `agent-kb-plan-hit` |
|
||||
| **A2** | 过程可见 | `events` 默认落盘;view plan 过程卡;SSE 仍仅 `stream=True` |
|
||||
| **A3** | 上下文预算 | `source_brief` / `skill_brief`;`READ:source|skill`;`step max_reads` |
|
||||
| **A4** | RAG/MCP 证据工具 | `corpus_search`;fixture `mcp_*`;`authority=workbook` |
|
||||
|
||||
原则回顾(见前置调研 §9):强化差异化;资源砸在工作簿 / 写回 / 固化 / OKF / 过程可视;外置 RAG/MCP **只作工具**。
|
||||
|
||||
---
|
||||
|
||||
## 2. 相对业界:已经「够格」的部分
|
||||
|
||||
下列能力若取消「可执行 Markdown 为权威」即消失——这是护城河,不是功能点攀比:
|
||||
|
||||
| 能力 | Marqdo 形态 | 业界常见替代 |
|
||||
|------|-------------|--------------|
|
||||
| 单一真相源 | 源码即提示 + 调用点注入 | Prompt Hub / 字符串 system |
|
||||
| 过程可审 | 写回块 + `events` + view 过程卡 | Langfuse / LangSmith 外挂 |
|
||||
| 成功可复用 | OKF 任务技能再跑 | transcript 再聊 / 向量片段召回 |
|
||||
| 复杂任务边界 | 工作簿文件 + `subtask` | 无限加长 chat / 临时工具输出 |
|
||||
| 确定步骤降本 | solidify → `llm_free` 快路径 | 每轮仍问模型 |
|
||||
|
||||
自评四问(前置调研 §9)粗判:
|
||||
|
||||
| 问 | 现状 |
|
||||
|----|------|
|
||||
| 新人能否只读一份 `.mq.md` 理解 Agent? | **部分** — 机制在,缺 canonical 示例教程 |
|
||||
| 失败后能否在 git + view 复盘、不强制外部 trace? | **基本可以** |
|
||||
| 成功任务下周能否以同一技能复用? | **可以**(金样已锁二次命中) |
|
||||
| 确定步骤是否越来越多变成普通 `##`、模型调用下降? | **路径有**(solidify / llm_free),缺量化看板证明 |
|
||||
|
||||
---
|
||||
|
||||
## 3. 缺口总表(按优先级)
|
||||
|
||||
| 优先级 | 缺口 | 为何还缺 | 建议验收线索 |
|
||||
|--------|------|----------|--------------|
|
||||
| **高** | 官方端到端示例 + 文档新鲜度 | 无独立 `examples/agent-*`;Skill/参考里仍有「layout / roadmap」陈旧表述;外人难「照抄即跑通 plan→固化→二次命中」 | `examples/agent-pong`(或同类)+ README;Skill 专节与 A0–A4 对齐 |
|
||||
| **高** | Agent 评测 / 回归 harness | 有离线金样,缺成本·恢复·命中率·补丁质量的系统评测;业界强调 evaluation 先于上线 | `tests/` 或脚本:命中率、llm_free 占比、失败恢复、可选 live 预算 |
|
||||
| **高** | 真 MCP(HTTP/SSE)与凭证 | A4 仅 JSON fixture;缺 streamable HTTP、鉴权、resources/prompts | 金样打 mock MCP server;返回仍带 `authority=workbook` |
|
||||
| **中** | Plan 断点续跑 | 工作簿在盘上,缺显式 checkpoint / resume(对标 LangGraph checkpointer) | `plan resume=` 从第 N 轮 DECISION 继续;进程崩溃可恢复 |
|
||||
| **中** | 人机协同(HITL)加深 | 仅有 `confirm=True` 建簿即停;缺审批卡、拒绝重开、view 一键继续 | view 审批控件 + 金样 |
|
||||
| **中** | 飞轮可观测指标 | `hits` / `improve_every` / `llm_free` 有字段,缺汇总与 CLI/view 报表 | `agent_kb_stats` 或 view 面板:命中率、探索浪费 |
|
||||
| **中** | 受控并行 fan-out | `subtask` 能并行,plan 主路径偏串行 | 父协议允许有界并行调研再合并 |
|
||||
| **低** | 多 Agent / A2A | dual skeleton 有;缺角色班组、跨进程 A2A | 多数场景可用「多工作簿 + 父 CALL」覆盖;有明确跨组织需求再开 |
|
||||
| **低** | Trace 外发(OTLP / Langfuse) | 本地复盘已够;外发是集成题 | 可选 adapter;默认不依赖 |
|
||||
| **刻意不做** | Dense embedding 默认化 | [okf-near-match.md](../roadmap/okf-near-match.md) **E** 仅在 n-gram 证据不足时评估 | 不宣传为默认向量库 |
|
||||
| **刻意不做** | 私有 JSON TOOL 主路径 / 整文件 LLM 重写 | 与宪法及 parent 设计冲突 | 继续禁止 |
|
||||
|
||||
---
|
||||
|
||||
## 4. 分项说明
|
||||
|
||||
### 4.1 产品化(高)
|
||||
|
||||
**问题**
|
||||
内核能力已超过「能演示」门槛,但**可感知产品体验**仍依赖读设计文档与翻 `tests/ext/`。对照 quantum / web 已有 `examples/`,agent 侧空白最明显。
|
||||
|
||||
**建议**
|
||||
1. 一份最小可运行示例:`step` → `plan` → promote → 二次 `plan` 打印 `cache=hit`。
|
||||
2. 同步 Skill / `doc/README` / 公开页,删掉「仅 layout」类过时句。
|
||||
3. 示例强调「权威在 `.mq.md`」,corpus/mcp 仅作证据旁路。
|
||||
|
||||
### 4.2 评测 harness(高)
|
||||
|
||||
**问题**
|
||||
金样锁行为正确性;不锁「飞轮是否在变好」「一次失败后能否恢复」「live 成本是否失控」。2026 多 Agent 讨论普遍把 **evaluation** 列为上线前缺失步骤。
|
||||
|
||||
**建议**
|
||||
- 离线:命中路径、补丁护栏、预算截断(已有)再加 **stats 断言**。
|
||||
- 半自动 / live:固定小 goal 集,记录 rounds、cache 分布、token 粗估(若可从供应商响应取得)。
|
||||
- 明确:评测消费的是工作簿与 kb,而不是外部 transcript 库。
|
||||
|
||||
### 4.3 真 MCP(高)与「证据≠权威」(不变)
|
||||
|
||||
**问题**
|
||||
Fixture 证明协议形状与权威字段;生产要接真实 MCP server(工具、资源、鉴权)。
|
||||
|
||||
**约束**
|
||||
- 工具结果进入 observation / CALL 回执,**不得**静默写成 OKF 权威技能。
|
||||
- 晋升仍走 promote / solidify / 人审(既有路径)。
|
||||
|
||||
### 4.4 断点续跑与 HITL(中)
|
||||
|
||||
**问题**
|
||||
LangGraph 类框架的 checkpointer / interrupt 是生产差异点。Marqdo 已有文件化状态(工作簿、写回、events),差的是**一等恢复 API**与**可视审批**。
|
||||
|
||||
**建议方向**
|
||||
- Resume:序列化「当前 round、path、last observation、events」到约定槽或旁路文件,重启后跳过已完成子跑。
|
||||
- HITL:扩展 `confirm` 语义(建簿 / 危险 PATCH / promote);view 展示 pending 卡。
|
||||
|
||||
### 4.5 飞轮指标与并行(中)
|
||||
|
||||
**问题**
|
||||
第四问(模型调用是否下降)需要数字。并行能缩短探索,但须有界,避免工作簿爆炸(见 [ext-agent.md](../design/ext-agent.md) §9)。
|
||||
|
||||
### 4.6 多 Agent / A2A / 外发 trace(低)
|
||||
|
||||
**问题**
|
||||
业界热度高(Crews、A2A、共享记忆层)。Marqdo 的「父 + 多工作簿」已覆盖多数单组织编排;跨组织 A2A 与共享记忆库是另一产品层,可用 MCP/证据工具接入,而不必把记忆权威搬出 `.mq.md`。
|
||||
|
||||
---
|
||||
|
||||
## 5. 建议的下一波分期(草案 B)
|
||||
|
||||
> 非正式锁定;落地时再写入 [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) 或独立 `ext-agent-productize.md`。
|
||||
|
||||
| 波次 | 主题 | 验收线索 |
|
||||
|------|------|----------|
|
||||
| **B0** | 官方示例 + Skill/文档去陈 | `examples/agent-*` 可 `marqdo run`;Skill 与 A0–A4 一致 |
|
||||
| **B1** | 评测 harness | 命中率 / llm_free / 恢复用例可一键跑 |
|
||||
| **B2** | Live MCP 客户端 | mock server 金样;`authority=workbook` 不变 |
|
||||
| **B3** | Plan resume + HITL | 崩溃可续;view 审批 |
|
||||
| **B4** | kb stats 面板 | CLI 或 view 展示飞轮数字 |
|
||||
| **B5** | 有界并行(可选) | fan-out 上限 + 合并观察 |
|
||||
|
||||
---
|
||||
|
||||
## 6. 明确「不是缺口」的清单
|
||||
|
||||
避免把差异化优势误判为缺陷:
|
||||
|
||||
1. **没有默认 dense 向量库** — 有意;OKF near 是稀疏词法;corpus 是关键词证据。
|
||||
2. **没有隐藏 TOOL: JSON 主协议** — 有意;CALL/READ/DECISION 与文档同构。
|
||||
3. **子任务默认 quiet** — 有意;答案走返回值,过程走 events/stream。
|
||||
4. **ext 不直调 host_*** — 有意;Agent 域在插件,防核心膨胀。
|
||||
5. **不捆绑领域工单技能** — 有意;官方框架保持可教、可审、可扩展。
|
||||
|
||||
---
|
||||
|
||||
## 7. 结论与推荐下一刀
|
||||
|
||||
A0–A4 之后,Marqdo `ext/agent` 在「文档驱动智能体」叙事上已经**自洽且可演示**。相对业界,短板是 **被人用起来的路径** 与 **生产级配套**,不是再堆一条编排 DSL。
|
||||
|
||||
**推荐下一刀顺序:**
|
||||
|
||||
1. **B0 官方示例 + 文档去陈**(最低成本、最高感知)
|
||||
2. **B1 评测 harness**(锁住飞轮与质量,防止回退)
|
||||
3. 按真实用户需求选 **B2 live MCP** 或 **B3 resume/HITL**
|
||||
|
||||
若四问在 B0–B1 后均可回答「是」,再考虑 B4/B5 与低优先级项。
|
||||
|
||||
---
|
||||
|
||||
## 8. 参考
|
||||
|
||||
### 本仓
|
||||
|
||||
- [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md)
|
||||
- [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md)
|
||||
- [okf-near-match.md](../roadmap/okf-near-match.md)(E dense 仍非默认)
|
||||
- [agent-streaming.md](../roadmap/agent-streaming.md)
|
||||
|
||||
### 外部(抽样,2026)
|
||||
|
||||
- LangGraph Persistence(checkpointer / store)
|
||||
- CrewAI Crews + Flows;MCP 作为工具连接层而非编排本体
|
||||
- 业界对 Agent evaluation、durable memory / A2A 状态层的讨论(共享记忆 ≠ 应取代可执行文档权威)
|
||||
@@ -0,0 +1,533 @@
|
||||
# 调研:主流智能体开发框架与 Marqdo「代码即文档 / 文档即知识库」优势
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **调研笔记 · 供 `ext/agent` 深入优化参考** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| 范围 | 2025–2026 开源/厂商智能体框架形态;对照 Marqdo `ext/ai/agent` 设计 |
|
||||
| 相关设计 | [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) · [stdlib-writeback.md](../design/stdlib-writeback.md) · [stdlib-subtask.md](../design/stdlib-subtask.md) |
|
||||
| 姊妹调研 | [okf-and-marqdo.md](okf-and-marqdo.md) · **A0–A4 后缺口** [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) |
|
||||
| 外部对照(抽样) | [Langfuse 框架对比(2026-07)](https://langfuse.com/blog/2025-03-19-ai-agent-comparison) · [LangGraph persistence](https://docs.langchain.com/oss/python/langgraph/persistence) · [Microsoft Agent Framework / AutoGen 维护模式](https://github.com/microsoft/autogen) · CrewAI / OpenAI Agents SDK / Claude Agent SDK / Google ADK / LlamaIndex 公开文档 |
|
||||
|
||||
---
|
||||
|
||||
## 0. 一句话结论
|
||||
|
||||
主流智能体框架几乎都在解决同一组工程问题——**编排、工具、状态、记忆、可观测、人机协同**——但它们的「权威真相」默认落在 **Python/TS 对象图 + 会话 transcript + 外部 Store/向量库** 上。
|
||||
|
||||
Marqdo 的宪法把权威真相定在 **可执行 Markdown(`.mq.md`)**:人写的程序、模型读的提示、执行后的写回、可复用的任务技能,是**同一份文档的不同生命阶段**。这不是「又一个 Agent SDK」,而是把 **Agent 开发本身做成文档工程**。
|
||||
|
||||
由此产生的突出优势(后文展开):
|
||||
|
||||
1. **编排可读 = 提示词不再黑盒**(源码即上下文)
|
||||
2. **过程可审 = 写回进源文件,而不是只进遥测平台**
|
||||
3. **记忆可 git = 成功经验晋升为任务知识包(OKF),审计=仓库历史**
|
||||
4. **复杂任务=子程序,而不是无限加长的 chat**(工作簿 + `subtask`)
|
||||
5. **确定步骤固化为代码,不确定步骤才问模型**(父 Plan-and-Move)
|
||||
6. **语言与知识形态同构**(与 Google OKF「Markdown 知识包」同向,但多走「可执行」一步)
|
||||
|
||||
**优化 `ext/agent` 时应守住这些差异化,而不是向 LangChain 类「隐藏循环 + TOOL: 协议」回退。**
|
||||
|
||||
---
|
||||
|
||||
## 1. 调研方法与边界
|
||||
|
||||
### 1.1 做了什么
|
||||
|
||||
| 动作 | 说明 |
|
||||
|------|------|
|
||||
| 横向扫盘 | 2026 年主流开源框架:LangGraph / LangChain DeepAgents、CrewAI、OpenAI Agents SDK、Claude Agent SDK、Google ADK、Microsoft Agent Framework(AutoGen 继承者)、Pydantic AI、LlamaIndex、Strands、Mastra / Vercel AI SDK、smolagents 等 |
|
||||
| 结构抽象 | 抽取「框架如何形成」的共性分层,而不是比 GitHub stars |
|
||||
| 对照本仓 | 精读 `ext-agent*`、`okf`、`writeback`、`subtask`、parent Plan-and-Move;对照旧 TOOL: 薄循环为何被否定 |
|
||||
| 找优越点 | 只保留 **Marqdo 结构上必然领先**、而非「以后可以加插件追上」的点 |
|
||||
|
||||
### 1.2 不做的
|
||||
|
||||
- 不宣称 Marqdo 在吞吐、多模态、托管运维上已全面领先(这些不是当前差异化)。
|
||||
- 不把「有没有向量检索」当成胜负手——那是应用层可加能力。
|
||||
- 不做厂商营销话术复读;优缺点按**开发者体验与系统真相源**评。
|
||||
|
||||
---
|
||||
|
||||
## 2. 智能体框架是怎么「形成」的
|
||||
|
||||
无论品牌如何包装,成熟框架通常收敛为同一条装配线:
|
||||
|
||||
```text
|
||||
┌─────────────────────────────────────────────────────────────┐
|
||||
│ 1. Model I/O │
|
||||
│ 补全 / 工具调用 / 流式 / 多模供应商适配 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 2. Agent 单元 │
|
||||
│ 指令(system) + 工具表 + 可选角色/人设 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 3. 编排(Orchestration) │
|
||||
│ 图 / 角色队 / 对话群 / 工作流 API / supervisor │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 4. 状态与记忆 │
|
||||
│ 短:thread checkpoint / 会话历史 │
|
||||
│ 长:Store / 向量 RAG / 用户偏好库 │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 5. 工具与行动面 │
|
||||
│ 函数 schema、MCP、沙箱、权限、CodeAct │
|
||||
├─────────────────────────────────────────────────────────────┤
|
||||
│ 6. 可观测与治理 │
|
||||
│ Trace、评测、护栏、HITL、配额 │
|
||||
└─────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
### 2.1 三种主流「编排哲学」
|
||||
|
||||
| 范式 | 核心隐喻 | 代表 | 可预测性 | 原型速度 |
|
||||
|------|----------|------|----------|----------|
|
||||
| **图 / 状态机** | 节点=步骤,边=转移,状态显式 | LangGraph、Google ADK workflow、MAF workflows | 高 | 中–慢(先画图) |
|
||||
| **角色协作** | Agent=工种,Crew=班组 | CrewAI、早期 AutoGen 群聊 | 中 | 快 |
|
||||
| **薄循环 + 工具** | 「模型自己决定下一步」 | OpenAI Agents SDK、Claude Agent SDK、Strands、smolagents | 低–中(靠护栏) | 最快 |
|
||||
|
||||
2026 年的趋势不是「哪个范式消灭其它」,而是:
|
||||
|
||||
- **生产复杂流** → 图(可控、可恢复、HITL)。
|
||||
- **内容/研究班组** → 角色。
|
||||
- **编码助手 / 生态绑定** → 厂商 SDK 自带 hardened loop。
|
||||
- **LangChain DeepAgents** 等开始把「规划器 + 子代理 + 文件记忆」打包成 opinionated harness——说明业界也意识到:纯 chat 不够,需要**文件与子上下文**。
|
||||
|
||||
### 2.2 记忆层的行业共识(与 Marqdo 对照的关键)
|
||||
|
||||
以 LangGraph 文档为代表(行业事实上的标准划分):
|
||||
|
||||
| 层 | 行业做法 | 作用 |
|
||||
|----|----------|------|
|
||||
| **短时** | Checkpointer / thread_id | 会话续跑、崩溃恢复、time-travel |
|
||||
| **长时** | BaseStore / 向量库 / Mem0·Zep 等 | 跨会话事实、偏好 |
|
||||
| **检索知识** | RAG corpus | 领域文档,不与会话状态混用 |
|
||||
|
||||
常见架构错误:把 checkpointer 当成长时记忆——换 `thread_id` 就「失忆」。
|
||||
|
||||
**这一点对 Marqdo 极关键:**
|
||||
行业把「记忆」拆成多个后端;Marqdo 默认把**任务级成功经验**落成 **`.mq.md` + agent-kb(OKF)**,用文件系统与 git 当记忆平面——见 §7。
|
||||
|
||||
### 2.3 框架「形成产品」的路径
|
||||
|
||||
```text
|
||||
PoC(脚本循环)
|
||||
→ SDK(Agent + tools)
|
||||
→ 编排(图 / 多代理)
|
||||
→ 持久化(checkpoint / store)
|
||||
→ 平台(托管、评测、护栏、计费)
|
||||
```
|
||||
|
||||
越往后,**编排源码与运行时真相越分离**:提示在字符串常量或 Prompt Hub,状态在 DB,轨迹在 Langfuse,知识在向量库。人要复盘一次失败,往往要开四个系统。
|
||||
|
||||
Marqdo 的赌注是:**尽量把真相拉回单一 `.mq.md` 时间线**。
|
||||
|
||||
---
|
||||
|
||||
## 3. 代表框架解剖(如何形成 + 优缺点)
|
||||
|
||||
### 3.1 LangGraph(显式状态图)
|
||||
|
||||
**如何形成**
|
||||
|
||||
- 把 Agent 步骤建模为 **有向图**:节点读/写共享 state,条件边决定下一跳。
|
||||
- 编译为可执行应用;挂 checkpointer → 持久化、HITL interrupt、故障续跑。
|
||||
- 长时记忆另挂 Store;生态上接 LangChain 工具与 LangSmith/Langfuse 轨迹。
|
||||
|
||||
**优点**
|
||||
|
||||
- 生产向可控性最强;分支、重试、并行边清晰。
|
||||
- 状态类型化后,测试与回放(time-travel)可行。
|
||||
- 云中立:图在你自己的进程里跑。
|
||||
|
||||
**缺点**
|
||||
|
||||
- 上手成本高:先设计图,再写节点。
|
||||
- 「提示词 / 业务说明」仍常散落在 Python 字符串;**图代码 ≠ 给人读的说明书**。
|
||||
- 记忆与知识仍依赖外置 Store/RAG;审计链路长。
|
||||
- DeepAgents 等上层 harness 说明:光有图仍不够「文件化协作」。
|
||||
|
||||
**对 Marqdo 的启示**
|
||||
|
||||
- 要学其「显式控制与可恢复」;不要学其「状态默认在对象里」。
|
||||
- Marqdo 多步的工作簿修订环 ≈ **把图展开成磁盘上的可执行文档**。
|
||||
|
||||
---
|
||||
|
||||
### 3.2 CrewAI(角色班组 + Flows)
|
||||
|
||||
**如何形成**
|
||||
|
||||
- Agent = role / goal / backstory;Crew 协调任务;近年加 **Flows** 把确定性业务逻辑包住自治班组。
|
||||
|
||||
**优点**
|
||||
|
||||
- 多代理叙事直观,原型极快。
|
||||
- 适合内容流水线、调研班组。
|
||||
|
||||
**缺点**
|
||||
|
||||
- 协作转移大量靠描述,**可预测性弱于图**。
|
||||
- 过程真相仍是运行时对象与日志;与「文档即程序」无关。
|
||||
- HITL / 企业治理相对弱。
|
||||
|
||||
**对 Marqdo 的启示**
|
||||
|
||||
- 「多角色」可用多个 `# 智能体` / 多个工作簿表达,但应以**可跑文档**为边界,而不是隐式群聊。
|
||||
|
||||
---
|
||||
|
||||
### 3.3 AutoGen → Microsoft Agent Framework(MAF)
|
||||
|
||||
**如何形成**
|
||||
|
||||
- AutoGen:对话对 / 群聊驱动;历史在内存。
|
||||
- 2026:AutoGen **维护模式**;能力并入 **Microsoft Agent Framework**(与 Semantic Kernel 合流):ChatAgent + 多种编排(sequential / concurrent / handoff / group / Magentic)+ 工作流图 + Azure Foundry 治理面。
|
||||
|
||||
**优点**
|
||||
|
||||
- 企业栈(.NET / Azure)一体;A2A、MCP、护栏、托管轨迹。
|
||||
- CodeAct 等模式:让 Agent **写代码执行**而非只吐 JSON——与「固化为代码」方向有共鸣。
|
||||
|
||||
**缺点**
|
||||
|
||||
- 生产治理深度常绑定云平台;开源核心与托管能力分层。
|
||||
- 编排语言仍是通用编程语言;**业务知识与程序不同构**。
|
||||
- 对话范式易导致「无限闲聊」式多代理。
|
||||
|
||||
**对 Marqdo 的启示**
|
||||
|
||||
- CodeAct / 固化步骤:与 Marqdo「确定步骤写成 `##`」同向,但 MAF 写的是 Python;Marqdo 写的是**人与模型共用的 `.mq.md`**。
|
||||
|
||||
---
|
||||
|
||||
### 3.4 OpenAI Agents SDK / Claude Agent SDK / Google ADK / Strands
|
||||
|
||||
**如何形成(共性)**
|
||||
|
||||
- 提供 **hardened agent loop**(工具、handoff、权限、会话)。
|
||||
- 深度绑定自家模型或云(OpenAI / Anthropic Claude Code harness / Gemini+ADK / Bedrock)。
|
||||
|
||||
**优点**
|
||||
|
||||
- 最快接入「能干活的助手」;权限与工具路径经过产品锤炼(尤其 Claude Code 同源 SDK)。
|
||||
- 官方 tracing、realtime 等增值。
|
||||
|
||||
**缺点**
|
||||
|
||||
- 编排与提示仍在宿主语言;**跨团队知识复用靠复制仓库或 Prompt 平台**。
|
||||
- 供应商锁定风险;换模时常换范式。
|
||||
- 「记忆」默认会话式;企业知识仍外挂。
|
||||
|
||||
**对 Marqdo 的启示**
|
||||
|
||||
- 模型 I/O 应继续放在 `ext/llm`,**不要**在 agent 里重造聊天栈。
|
||||
- 不要把「官方 loop」当哲学:Marqdo 的哲学是文档驱动,不是 SDK 驱动。
|
||||
|
||||
---
|
||||
|
||||
### 3.5 LlamaIndex / Haystack(文档与 RAG 优先)
|
||||
|
||||
**如何形成**
|
||||
|
||||
- 以索引、检索、查询引擎为中心;Agent 是检索之上的编排层。
|
||||
|
||||
**优点**
|
||||
|
||||
- 企业文档智能、多格式摄取成熟。
|
||||
- 「知识」有一等公民地位。
|
||||
|
||||
**缺点**
|
||||
|
||||
- 知识默认是 **被检索的被动语料**,不是 **可执行的任务程序**。
|
||||
- Agent 编排能力弱于 LangGraph 系;常需再叠一层框架。
|
||||
- 索引与源文档易漂移(双源真相)。
|
||||
|
||||
**对 Marqdo 的启示(尖锐对比)**
|
||||
|
||||
- LlamaIndex:**文档 → 向量 → 检索 → 回答**。
|
||||
- Marqdo:**文档 → 可执行语法 → 运行 → 写回 →(可选)晋升为任务知识包**。
|
||||
同一「Markdown 知识」在 Marqdo 里可以是 **会跑的技能**,而不仅是 chunk。
|
||||
|
||||
---
|
||||
|
||||
### 3.6 Pydantic AI / Mastra / Vercel AI SDK
|
||||
|
||||
**如何形成**
|
||||
|
||||
- 强调类型安全(Pydantic)或 TS 全栈 DX(Mastra / Vercel)。
|
||||
- 把 Agent 当普通后端组件:校验、otel、耐久执行。
|
||||
|
||||
**优点**
|
||||
|
||||
- 工程化体验好;与现有 Web/API 栈融合。
|
||||
|
||||
**缺点**
|
||||
|
||||
- 仍是「代码库里的 Agent」;非技术干系人无法直接打开同一份编排当说明书。
|
||||
- 知识沉淀路径仍外置。
|
||||
|
||||
---
|
||||
|
||||
### 3.7 横向对比表(开发者真相源)
|
||||
|
||||
| 维度 | 典型框架落点 | Marqdo 落点 |
|
||||
|------|--------------|-------------|
|
||||
| 编排定义 | Python/TS 图或类 | `.mq.md` 标题/表/调用 |
|
||||
| 系统提示 | 字符串 / Prompt Hub | 站立提示写在同一文档 |
|
||||
| 工具 | 装饰器函数 / MCP | runbook 内 `##` + `subtask` |
|
||||
| 短时状态 | checkpoint / session | 工作簿文件 + 写回块 + view |
|
||||
| 长时记忆 | Store / 向量 | agent-kb(OKF)+ git |
|
||||
| 复杂任务 | 子图 / 子代理上下文窗 | **子 `.mq.md` 程序** `spawn path=` |
|
||||
| 复盘 | Langfuse trace | `git log` + 打开工作簿 + view output-card |
|
||||
| 成功复用 | 手工抽 prompt / 存 Store | **固化 + OKF 晋升 / lookup** |
|
||||
|
||||
---
|
||||
|
||||
## 4. 行业共性痛点(框架越强,痛点越清晰)
|
||||
|
||||
下列痛点在 LangGraph、CrewAI、厂商 SDK 文档与实践文章中反复出现;它们正是 Marqdo 要正面打穿的:
|
||||
|
||||
### 4.1 提示词与编排分离
|
||||
|
||||
- 行为由 system prompt + 隐藏模板决定;code review 审不到「模型真正看见什么」。
|
||||
- Prompt 漂移与代码漂移双轨发生。
|
||||
|
||||
### 4.2 过程不透明或只对平台透明
|
||||
|
||||
- 本地只有最终返回值;细节在 SaaS trace。
|
||||
- 合规团队要的「这份文档当时怎么决策的」难以直接交付。
|
||||
|
||||
### 4.3 记忆碎片化
|
||||
|
||||
- thread / store / RAG / 日志四套系统;「上次同类任务怎么做成的」检索成本高。
|
||||
- 成功经验很少自动变成**可再执行资产**。
|
||||
|
||||
### 4.4 多步任务变成超长 transcript
|
||||
|
||||
- 上下文窗口被工具输出撑爆;DeepAgents 才开始「卸到文件系统」。
|
||||
- 说明业界被迫走向 **文件化**——而 Marqdo **一开始就以文件为执行边界**。
|
||||
|
||||
### 4.5 确定性逻辑仍反复问模型
|
||||
|
||||
- 已验证的步骤下一轮又被重新「推理」,浪费且不稳。
|
||||
- 缺少「晋升为普通代码」的一等路径。
|
||||
|
||||
### 4.6 Agent 框架与知识格式断裂
|
||||
|
||||
- Google OKF 等推动「知识用 Markdown 包交换」,但主流 Agent 框架并不把 **可执行程序** 当作知识页。
|
||||
- 结果:知识包给人策展,Agent 另跑一套 Python。
|
||||
|
||||
---
|
||||
|
||||
## 5. Marqdo 在智能体域的设计思想(必须找准)
|
||||
|
||||
### 5.1 宪法重申
|
||||
|
||||
| 口号 | 在 Agent 语境下的含义 |
|
||||
|------|------------------------|
|
||||
| **代码即文档** | 智能体编排、工具表、站立提示、任务叙述写在同一份 `.mq.md`;打开即读、即可跑 |
|
||||
| **文档即知识库** | 写回块、工作簿、OKF 任务页都是知识;Agent 与人共用同一交换面 |
|
||||
| **文档能跑通 = 约定成立** | 金样 / `marqdo run` / view 是验收,不是「旁边另有一份真实现状」 |
|
||||
|
||||
旧「TOOL: 黑盒循环」被官方设计明确否定,正是因为它把 Marqdo **降级成了 LangChain 的薄壳**。
|
||||
|
||||
### 5.2 两级执行(与业界范式对齐但不抄袭)
|
||||
|
||||
| Marqdo | 业界近似 | 关键差异 |
|
||||
|--------|----------|----------|
|
||||
| `## step` 单步 | 薄 Agent loop | 注入**本文件源码 + 调用位置 + Skill**;默认写回 |
|
||||
| `## plan` 多步 | 规划器 + 子代理 | 产物是 **工作簿 `.mq.md`**;经 `subtask` 整文件执行;父以补丁演进 |
|
||||
| 父 Plan-and-Move | supervisor / orchestrator | 行动面:READ/CALL/DECISION;**禁止整文件 LLM 重写** |
|
||||
| OKF agent-kb | long-term store | 命中的是 **可再跑的任务技能**,不是抽象 embedding 片段(可再叠加 soft near) |
|
||||
|
||||
### 5.3 执行与隔离
|
||||
|
||||
- 工具与子工作簿走 `lib/subtask`(`spawn fn=` / `spawn path=`),与主推理隔离——对应业界「子代理独立上下文」,但边界是 **文件与子进程语义**,不是仅换一个 message list。
|
||||
|
||||
---
|
||||
|
||||
## 6. Marqdo 的必要突出优势(核心章节)
|
||||
|
||||
下列优势要求满足:**若取消「可执行 Markdown 为权威」,优势即消失**。这才是「必要」优越点,而不是功能清单攀比。
|
||||
|
||||
### 6.1 单一真相源:编排 / 提示 / 结果共址
|
||||
|
||||
**优势陈述**
|
||||
模型在 `step`/`plan` 中看到的上下文,可以就是**人类正在编辑的那份源码**(及调用点)。站立提示不是隐藏 system blob,而是文档段落。
|
||||
|
||||
**为何必要**
|
||||
消除「提示词仓库 vs 代码仓库」双源;code review、教学、合规审计面对同一人造物。
|
||||
|
||||
**相对框架**
|
||||
LangGraph/CrewAI/SDK:提示常在字符串或控制台配置;trace 在另一系统。Marqdo:`view` 在语句下挂 output-card,与源同行。
|
||||
|
||||
### 6.2 写回 = 内建的「Notebook 输出单元」式过程记忆
|
||||
|
||||
**优势陈述**
|
||||
`lib/writeback` 把成功/失败写入 `<!-- marqdo-out … -->`,锚在调用行下。智能体默认写回后,**过程留在源文件**,不是只留在遥测。
|
||||
|
||||
**为何必要**
|
||||
教学与调试要「看见刚才那一步」;失败成为可读避坑记录;成功可被后续命中。
|
||||
|
||||
**相对框架**
|
||||
业界靠 Langfuse/LangSmith;本地仓库往往是空的。Marqdo 仓库本身就是过程库(可再导出到 trace,但不依赖它才能复盘)。
|
||||
|
||||
### 6.3 复杂任务 = 生成并演进子程序,而不是堆 transcript
|
||||
|
||||
**优势陈述**
|
||||
`plan` 创建 `.marqdo/agent-runs/*.mq.md`,用 `spawn path=` 跑完整 `# main`。父观察**真实退出码、返回值、写回、源码**,再 FIND/REPLACE 补丁。
|
||||
|
||||
**为何必要**
|
||||
上下文窗口有限;长工具输出必须卸出。DeepAgents 用「文件系统抽象」补课;Marqdo **语言层原生就是文件程序**。
|
||||
|
||||
**相对框架**
|
||||
子代理多是「新对话 + 摘要」;Marqdo 子任务是 **可独立 `marqdo run` 的文档**,可被人类直接打开修改后重跑。
|
||||
|
||||
### 6.4 确定步骤固化为代码;模型只处理不确定残差
|
||||
|
||||
**优势陈述**
|
||||
父作为「智能体开发大师」:能写成 `##` 的就固化;子智能体只跑不确定的 `step`。`DECISION: DONE` 可 solidify + OKF 晋升。
|
||||
|
||||
**为何必要**
|
||||
降本、降方差、形成组织资产。业界常把每次任务重新推理;Marqdo 把「学会的技能」编译回语言。
|
||||
|
||||
**相对框架**
|
||||
MAF CodeAct 写出的是通用语言脚本;Marqdo 固化的是 **仍保持文档属性的 `.mq.md` 技能**——人不用会 Python 也能读懂并改。
|
||||
|
||||
### 6.5 文档即知识库 + OKF:记忆可交换、可策展、可信任
|
||||
|
||||
**优势陈述**
|
||||
任务知识包(`.marqdo/agent-kb/`)以 OKF 形承载 `Marqdo Task` / skill,`resource:` 必须指向可执行 `.mq.md`。lookup / near / soft_match 走插件,不进核心 host。
|
||||
|
||||
**为何必要**
|
||||
Google OKF 证明行业需要「Markdown 知识包」;Marqdo 多走一步:**知识页声明的可执行资源真能跑**。记忆不是不可解释的向量命中,而是 **带路径的技能复用**。
|
||||
|
||||
**相对框架**
|
||||
LlamaIndex 检索散文块;Store 存 JSON 事实。Marqdo agent-kb:**命中 → 再跑同一技能路径**(精确 / 规范化 / near / 父裁决)。
|
||||
|
||||
### 6.6 审计与协作默认路径 = Git
|
||||
|
||||
**优势陈述**
|
||||
工作簿演进、写回、晋升都是文件变更 → `git log` / PR / blame。
|
||||
|
||||
**为何必要**
|
||||
企业已有代码治理;不必为 Agent 另建「提示治理平台」才能起步。
|
||||
|
||||
**相对框架**
|
||||
多数框架的状态在 DB;要审计得接专用平台。Marqdo 从第一天就兼容软件工程工作流。
|
||||
|
||||
### 6.7 中英双面 API 与「说明书即程序」教学属性
|
||||
|
||||
**优势陈述**
|
||||
`# 智能体` / `# agent`、`单步`/`step`、`多步`/`plan` 对称;教程文档可以直接是金样。
|
||||
|
||||
**为何必要**
|
||||
智能体开发教育成本高;Marqdo 把教材和运行物合一(与 quantum/math 扩展同一哲学)。
|
||||
|
||||
### 6.8 分层纪律:扩展不脏核心
|
||||
|
||||
**优势陈述**
|
||||
`ext/**` 禁 `host_*`;agent-kb 在 `plugins/agent`;核心保持瘦。
|
||||
|
||||
**为何必要**
|
||||
避免「Agent 框架把语言运行时变成巨石」——这是许多 Python Agent 栈的终局病。
|
||||
|
||||
---
|
||||
|
||||
## 7. 优势地图(一图看懂定位)
|
||||
|
||||
```text
|
||||
可预测性 / 生产控制
|
||||
▲
|
||||
│ LangGraph / MAF workflows
|
||||
│
|
||||
│ ★ Marqdo plan
|
||||
│ (workbook = program)
|
||||
│
|
||||
角色班组 ──────────┼────────────── 薄循环 SDK
|
||||
CrewAI │ OpenAI / Claude SDK
|
||||
│
|
||||
│ LlamaIndex (RAG)
|
||||
│
|
||||
└────────────────────────────►
|
||||
文档/知识一等公民程度
|
||||
|
||||
★ Marqdo 同时偏右上:控制来自「可执行文档+补丁环」,
|
||||
知识来自「同源 Markdown + OKF」,而非向量库单独称王。
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 8. 诚实边界:什么时候不该硬吹 Marqdo
|
||||
|
||||
| 场景 | 更合适的选择 | 原因 |
|
||||
|------|--------------|------|
|
||||
| 超大规模并行图、成熟 Python 数据栈 | LangGraph + 现有 infra | 生态与库广度 |
|
||||
| 强绑定 Azure 治理 / .NET | MAF | 平台一体 |
|
||||
| 纯文档问答 / 海量非结构化语料 | LlamaIndex 等 | 摄取与检索成熟;Marqdo 可 **调用** 它们作工具,不必重造 |
|
||||
| 只要一个 ChatGPT 式助手周末原型 | 厂商 Agents SDK | 启动最快 |
|
||||
| 需要强实时语音 / 多模原生 | 厂商 SDK | 非 Marqdo 当前主场 |
|
||||
|
||||
Marqdo 的正确叙事不是「取代所有 Agent 框架」,而是:
|
||||
|
||||
> **当你希望智能体开发成果沉淀为组织可维护的文档资产,并且编排本身必须可教、可审、可跑时——选 Marqdo。**
|
||||
|
||||
---
|
||||
|
||||
## 9. 对 `ext/agent` 深入优化的建议方向(调研导出)
|
||||
|
||||
优化应强化 §6 优势,避免回退到「隐藏 TOOL 循环」。
|
||||
|
||||
| 优先级 | 方向 | 理由 |
|
||||
|--------|------|------|
|
||||
| P0 | **工作簿质量与补丁可靠性**(精确 FIND/REPLACE、固化、观察切片) | 直接决定「子程序演进」是否优于 transcript |
|
||||
| P0 | **OKF 命中体验**(精确 / near / soft_match 默认真策略、策展 UX) | 落实「文档即知识库」的复用飞轮 |
|
||||
| P1 | **过程可见**(streaming / view 过程卡,见 [agent-streaming.md](../roadmap/agent-streaming.md)) | 对标 Langfuse,但真相仍写回文档 |
|
||||
| P1 | **Skill / 源码注入的预算与渐进披露** | 避免上下文爆炸,同时保持「源码即提示」 |
|
||||
| P2 | **与外部 RAG/MCP 的工具化接入** | 补齐语料检索,但不把向量库升为权威真相 |
|
||||
| P2 | **评测金样:同类任务二次 plan 应命中 kb 快路径** | 用测试锁住差异化 |
|
||||
| 避免 | 再引入私有 JSON 工具协议作主路径 | 与宪法冲突 |
|
||||
| 避免 | 整文件 LLM 重写工作簿 | 已在 parent 设计禁止 |
|
||||
|
||||
验收提问(产品自评):
|
||||
|
||||
1. 新人能否只读一份 `.mq.md` 理解 Agent 在干什么?
|
||||
2. 失败后能否在 git 与 view 内完成复盘,不强制打开外部 trace?
|
||||
3. 成功任务下周能否以 **跑同一技能** 的方式复用,而不是「再聊一遍」?
|
||||
4. 确定步骤是否越来越多地变成普通 `##`,模型调用是否下降?
|
||||
|
||||
若四问皆是——优化方向正确。
|
||||
|
||||
---
|
||||
|
||||
## 10. 结论
|
||||
|
||||
2026 年的智能体框架市场在 **图控、角色班组、厂商 hardened loop、RAG 知识** 四条线上分化;共同短板是 **真相源碎片化** 与 **成功经验难以变成可执行组织资产**。
|
||||
|
||||
Marqdo 用「代码即文档、文档即知识库」把 Agent 开发收束到 **可执行 Markdown 生命循环**:
|
||||
|
||||
**书写 → 注入模型 → 执行 → 写回 →(多步)补丁演进 → 固化 → OKF 晋升 → 再命中。**
|
||||
|
||||
这不是功能点堆砌,而是架构级选择。深入优化 `ext/agent` 时,应把资源砸在 **工作簿、写回、固化、知识包命中、过程可视** 上,把「文档驱动的智能体开发框架」做成可感知的产品体验——这才是相对 LangGraph / CrewAI / 厂商 SDK **不可替代** 的优越点。
|
||||
|
||||
---
|
||||
|
||||
## 11. 参考与延伸阅读
|
||||
|
||||
### 本仓
|
||||
|
||||
- [ext-agent.md](../design/ext-agent.md) — 框架总设计(否定 TOOL 薄循环)
|
||||
- [ext-agent-plan.md](../design/ext-agent-plan.md) — 多步工作簿
|
||||
- [ext-agent-parent.md](../design/ext-agent-parent.md) — 父 Plan-and-Move
|
||||
- [okf.md](../design/okf.md) · [okf-and-marqdo.md](okf-and-marqdo.md)
|
||||
- [stdlib-writeback.md](../design/stdlib-writeback.md) · [stdlib-subtask.md](../design/stdlib-subtask.md)
|
||||
- [roadmap/agent-streaming.md](../roadmap/agent-streaming.md) · [roadmap/okf-near-match.md](../roadmap/okf-near-match.md) · [roadmap/ext-agent-optimize.md](../roadmap/ext-agent-optimize.md)
|
||||
- [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) — A0–A4 之后还差什么
|
||||
|
||||
### 外部(抽样,2025–2026)
|
||||
|
||||
- Langfuse: *Comparing Open-Source AI Agent Frameworks*(2026-07 更新盘点)
|
||||
- LangGraph docs: Persistence(checkpointer vs store)
|
||||
- Microsoft: AutoGen maintenance → Agent Framework migration
|
||||
- CrewAI: Crews + Flows
|
||||
- OpenAI Agents SDK / Claude Agent SDK / Google ADK 公开 README
|
||||
- Google OKF SPEC v0.2(知识包形态;与 Marqdo 可执行源对照)
|
||||
@@ -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 |
|
||||
@@ -0,0 +1,44 @@
|
||||
# `ext/agent` 深入优化(调研驱动)
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **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) |
|
||||
|
||||
---
|
||||
|
||||
## 1. 优化原则(来自调研)
|
||||
|
||||
1. **强化差异化,不向 LangChain 薄循环回退**(禁止隐藏 TOOL: 主路径、禁止整文件 LLM 重写工作簿)。
|
||||
2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视、源码/调用位置注入**。
|
||||
3. 外部 RAG/MCP 只作**工具**,不升为权威真相源。
|
||||
|
||||
自评四问见调研 §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. A0–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` |
|
||||
|
||||
---
|
||||
|
||||
## 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/`。
|
||||
@@ -2,8 +2,8 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **Q0–Q6 已落地**(含公式自定义门;更大 n / 完整开放系统另文) |
|
||||
| 日期 | 2026-08-12 |
|
||||
| 状态 | **Q0–Q7 完结 · Q8a/Q8b 完结 · Q8c 待做** |
|
||||
| 日期 | 2026-08-28 |
|
||||
| **锁定设计** | [design/ext-quantum.md](../design/ext-quantum.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) |
|
||||
| 安装 | `marqdo ext add quantum`(`quantum` / `量子`) |
|
||||
@@ -30,8 +30,14 @@
|
||||
| **Q5** | 教学噪声 + barrier/measure/append/state — [ext-quantum-q5.md](../design/ext-quantum-q5.md) | **done(最小)** |
|
||||
| **Q5.5** | `amplitude_damping` 轨迹 — [ext-quantum-q5.5.md](../design/ext-quantum-q5.5.md) | **done** |
|
||||
| **Q6** | 公式/`matrix=` 自定义门 + `apply` — [ext-quantum-custom-gate.md](../design/ext-quantum-custom-gate.md) | **done** |
|
||||
| **Q7a** | 密度矩阵 / Kronecker / 部分迹 / Hermitian 谱 / Schmidt / Pauli 期望 / 纯度·保真度 — [ext-quantum-q7.md](../design/ext-quantum-q7.md) | **done** |
|
||||
| **Q7b** | 高级 SVG:hinton / city / density / paulivec / qsphere / multibloch | **done** |
|
||||
| **Q7c** | 纠缠示例 + 用户文档 / skill 摘要 | **done** |
|
||||
| **Q8a** | 电路 SVG:标签 gutter + dark/light/bw 门族分色 — [ext-quantum-viz-style.md](../design/ext-quantum-viz-style.md) | **done** |
|
||||
| **Q8b** | probs / bloch / heatmap 共用令牌 | **done** (probs/bloch;heatmap → Q8c) |
|
||||
| **Q8c** | 高级态图(hinton/city/…)换肤 | **pending** |
|
||||
|
||||
验收金样:`tests/ext/quantum-bell-smoke.mq.md`、`quantum-draw-smoke.mq.md`、`quantum-gate-matrix-smoke.mq.md`、`quantum-gate-heatmap-smoke.mq.md`、`quantum-author-api-smoke.mq.md`、`quantum-noise-smoke.mq.md`、`quantum-amp-damp-smoke.mq.md`、`quantum-custom-gate-smoke.mq.md`、中文对称样例。
|
||||
验收金样:既有 `tests/ext/quantum-*-smoke.mq.md`;Q7:`quantum-linalg-smoke`、`quantum-viz-advanced-smoke`。示例:`examples/quantum-bell/`、`examples/quantum-entanglement/`。
|
||||
|
||||
---
|
||||
|
||||
|
||||
+23
-5
@@ -2,8 +2,8 @@
|
||||
|
||||
| | |
|
||||
|---|---|
|
||||
| 状态 | **W0–W3 骨架已落地;W4 待** |
|
||||
| 日期 | 2026-08-11 |
|
||||
| 状态 | **W0–W7 + P3 完结**(审计/RBAC/相册/ETag/外键已落地) |
|
||||
| 日期 | 2026-08-28 |
|
||||
| **锁定设计** | [design/ext-web.md](../design/ext-web.md) |
|
||||
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [ext-llm.md](../design/ext-llm.md) |
|
||||
| 安装 | `marqdo ext add web`(`web` / `网页`) |
|
||||
@@ -25,11 +25,29 @@
|
||||
| **W0** | CATALOG + L1 + `web_listen` Hello | **done** |
|
||||
| **W1** | env 端口;`page` 四栏;nav 表;static | **done** |
|
||||
| **W2** | SQLite `define`/`migrate`/`all` | **done** |
|
||||
| **W3** | 三列绑定;变量名即表名;`/admin` CRUD+日志+布局 | **done**(登录鉴权仍简) |
|
||||
| **W3** | 三列绑定;变量名即表名;`/admin` CRUD+日志+布局 | **done** |
|
||||
| **W3s** | 安全硬化:argon2 密码哈希、CSRF、SQLite 会话持久化、CSPRNG、登录限速 | **done** |
|
||||
| **W3.5** | 人写面首版:`web.assemble` + `` `表`.`字段` `` + `examples/man-write-site` | **done**(编排袋仍可再瘦) |
|
||||
| **W4** | Postgres;Redis / S3 驱动 | pending |
|
||||
| **W4** | Postgres;Redis / S3 驱动(见 [ext-web-drivers.md](../design/ext-web-drivers.md)) | **done** |
|
||||
| **W4c** | 内容标配:SEO / Markdown / RSS / 分页 UI(见 [web-net-capabilities.md](../design/web-net-capabilities.md)) | **done** |
|
||||
| **W5** | 上传与媒体:multipart 接收 + 落盘 + 下载(见 [web-net-capabilities.md](../design/web-net-capabilities.md) A5) | **done** |
|
||||
| **W6** | 迁移 + FTS5 搜索;草稿/评论用既有 where/表;WS 广播 + 访问日志 | **done** |
|
||||
| **W7** | Cache-Control / 404·500 / 重定向 / sitemap·robots / init 唯一·索引 / HTTPS 反代说明 | **done** |
|
||||
| **P3** | 审计时间戳 / 外键 / RBAC / 相册 / ETag | **done** |
|
||||
|
||||
验收金样:`tests/ext/web-smoke.mq.md`、`ext_cli_add_web`。
|
||||
### 定制波次(规划中)
|
||||
|
||||
自研后台 / 主题 / 响应式踩坑见 [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`。
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -47,7 +47,7 @@ index.mq.md (+ 导入的 .mq.md)
|
||||
│
|
||||
▼
|
||||
┌───────────────────┐
|
||||
│ 0. 源加载 / 模块图 │ frontmatter `> a.mq.md` → 依赖图
|
||||
│ 0. 源加载 / 模块图 │ frontmatter `import a:a.mq.md` → 依赖图
|
||||
└─────────┬─────────┘
|
||||
▼
|
||||
┌───────────────────┐
|
||||
@@ -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)
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -131,7 +131,7 @@ L2 生态约定 catalog 收录;用户站专章
|
||||
|------|------|------|
|
||||
| **S0** | `len`(文本/表)、`str`、`int` | keywords.md 已列候选;字节码已有闲置 `Op::Len` 可接线 |
|
||||
| **S1** | 表工具:取列、行数;字符串 trim/split(先内置或纯 mq 实现二选一) | 文档型语言高频 |
|
||||
| **S2** | 官方 `lib/` 或 `std/` + 导入约定(仍可用 frontmatter;或日后 `> std/text.mq.md`) | 可生长而不破现有导入 |
|
||||
| **S2** | 官方 `lib/` 或 `std/` + 导入约定(仍可用 frontmatter;或日后 `import text:std/text.mq.md`) | 可生长而不破现有导入 |
|
||||
| **S3** | 错误类型约定(如非法 `int` 文本 → 诊断) | 依赖 P0 |
|
||||
|
||||
### 完成定义(S0)
|
||||
@@ -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,88 @@
|
||||
# 第 1 章:Marqdo 是什么
|
||||
|
||||
## 1.1 一句话介绍
|
||||
|
||||
**Marqdo = Markdown(Marq)+ 执行(do)**。它把 Markdown 的**标记当作编程语法**:同一个 `.mq.md` 文件,打开给人看是文档,运行给机器看是程序。
|
||||
|
||||
在大型项目里,说明、示例与实现往往分叉成三份「真相」,改一处忘另一处。Marqdo 让这三者**同源**——你写的文档本身就是可执行的代码。
|
||||
|
||||
## 1.2 与其他语言的区别
|
||||
|
||||
传统编程语言(如 Python)需要单独写文档和注释;Marqdo 反过来了——**文档本身就是程序**。
|
||||
|
||||
| 传统语言 | Marqdo |
|
||||
|----------|--------|
|
||||
| 代码在 `.py`,文档在 `.md` | 代码与文档同在 `.mq.md` |
|
||||
| `def` / `if` / `for` / `return` 是关键字 | 用 Markdown 标记 `##` / `1.` / `-` / `**…**` 表达 |
|
||||
| 注释用 `#` 或 `//` | **无标记的叙述就是注释** |
|
||||
| 大括号 `{}` 或缩进界定代码块 | 标题层级 `#` / `##` 界定作用域 |
|
||||
|
||||
关键点:**不要**试图写 `if`、`else`、`while`、`for`、`def`、`return` 这些关键字——它们不是 Marqdo 的语法。控制流由 Markdown 承担。
|
||||
|
||||
## 1.3 安装
|
||||
|
||||
Marqdo 用 Rust 编写。从以下任一方式获取:
|
||||
|
||||
- **发布包**:从 GitHub Releases 下载预编译二进制(已内置标准库)。
|
||||
- **源码构建**:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/cflmy/marqdo.git
|
||||
cd marqdo
|
||||
cargo build --release
|
||||
# 二进制位于 target/release/marqdo
|
||||
```
|
||||
|
||||
验证安装:
|
||||
|
||||
```bash
|
||||
marqdo --version
|
||||
```
|
||||
|
||||
## 1.4 第一个程序
|
||||
|
||||
创建一个文件 `hello.mq.md`:
|
||||
|
||||
```markdown
|
||||
# Hello World
|
||||
|
||||
这是叙述文字,也就是注释。
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
- `# Hello World` —— 对象标题。`# main` 是入口;当文件只有唯一一个顶层 `#` 对象时,它也可作为入口。
|
||||
- 空行后的普通文字是**注释**(叙述)。
|
||||
- `> print text=Hello World!` —— 调用内置函数 `print` 输出一行文本。
|
||||
|
||||
运行:
|
||||
|
||||
```bash
|
||||
marqdo run hello.mq.md
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
Hello World!
|
||||
```
|
||||
|
||||
## 1.5 中英双语内核
|
||||
|
||||
Marqdo 内核内置函数都有中英别名,**无需导入,可混用**:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 打印 内容=你好,世界!
|
||||
```
|
||||
|
||||
`打印` 与 `print` 是同一个内置函数,`内容` 与 `text` 是同一个参数名。
|
||||
|
||||
## 1.6 文件后缀:`.mq.md`
|
||||
|
||||
Marqdo 程序的**后缀必须是 `.mq.md`**(可执行源文件),不能用普通的 `.md`。一个 `.md` 文件默认只是文档;一个 `.mq.md` 文件既是文档又是程序。
|
||||
|
||||
## 1.7 下一步
|
||||
|
||||
你已经能写出并运行第一个程序了。接下来学习[第 2 章:基本语法](./02-基本语法.md)——理解 `.mq.md` 里哪些是代码、哪些是注释,以及标识符的写法。
|
||||
@@ -0,0 +1,151 @@
|
||||
# 第 2 章:基本语法
|
||||
|
||||
## 2.1 文件结构
|
||||
|
||||
一个 `.mq.md` 文件由以下几部分组成:
|
||||
|
||||
1. **Frontmatter**(可选):文件开头的成对 `---` 之间的元信息,如标题、导入。
|
||||
2. **对象 / 函数定义**:以 `#` / `##` 开头的标题。
|
||||
3. **叙述注释**:无标记的普通文字段落。
|
||||
4. **可执行语句**:以标记开头的行。
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 我的程序
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
这是叙述段落,整段都是注释。
|
||||
|
||||
> print text=Hello
|
||||
```
|
||||
|
||||
## 2.2 代码 vs 注释:空行分段规则
|
||||
|
||||
Marqdo 的注释规则很特别:**无标记的叙述就是注释**,靠空行分段。
|
||||
|
||||
规则:
|
||||
|
||||
- 空行之后的第一行若**无标记**(普通文字)→ 这一段是**注释**。
|
||||
- 注释段内的**每一行**(直到下一个空行)都是注释——即使它长得像代码。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
这段注释里有一行看起来像代码,但它不会执行:
|
||||
*not_executed = 1*
|
||||
> print text=这也是注释
|
||||
|
||||
空行之后,代码开始运行:
|
||||
|
||||
> print text=这行会运行
|
||||
```
|
||||
|
||||
> **注意**:叙述与可执行代码之间**必须空一行**。忘记空行会让本意是注释的文字被当作代码,或让代码被吞进注释段。
|
||||
|
||||
## 2.3 标记一览表
|
||||
|
||||
以下标记表示「这是代码」:
|
||||
|
||||
| 标记 | 含义 |
|
||||
|------|------|
|
||||
| `#` | 对象 / 类型(`# main` = 入口) |
|
||||
| `##` … `######` | 函数 / 方法(嵌套按标题深度) |
|
||||
| `` + `名` `` | 函数标题下的形参 |
|
||||
| `1.` `2.` … | 条件分支 |
|
||||
| `-` | 循环(遍历或 while) |
|
||||
| `> 函数 参数` | 调用 |
|
||||
| `*…*` | 程序语句(赋值 / 表达式) |
|
||||
| `**…**` | 返回值 |
|
||||
| `|` 开头的 GFM 表格 | 集合(列表 / 字典) |
|
||||
| `---` / `***`(函数体内) | 结束函数体 |
|
||||
|
||||
## 2.4 标识符与反引号
|
||||
|
||||
Marqdo 中,**变量、参数名用反引号 `` ` `` 包裹**,这与 Markdown 的代码/链接语法脱钩,避免歧义。
|
||||
|
||||
```markdown
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello, `谁`!
|
||||
```
|
||||
|
||||
- `+ `谁`` —— 声明形参 `谁`
|
||||
- `> print text=Hello, `谁`!` —— 在字符串中引用变量 `谁`
|
||||
|
||||
> **注意**:反引号规则有例外。在 `*…*`(斜体语句)和 `**…**`(粗体返回)内部,**裸标识符就是变量**,反引号可以省略(详见 [第 3 章](./03-变量与赋值.md))。
|
||||
|
||||
## 2.5 字面量
|
||||
|
||||
Marqdo 的字面量:
|
||||
|
||||
| 类型 | 示例 | 说明 |
|
||||
|------|------|------|
|
||||
| 数字 | `1` `3.14` `-5` | 整数 / 浮点 / 负数 |
|
||||
| 布尔 | `True` `False`(`真` `假`) | 布尔值 |
|
||||
| 空值 | `None`(`空`) | 空值 |
|
||||
| 文本 | `hello`(裸 token) | 无转义,按字面量 |
|
||||
| 字符串 | `"Hello\n"` | 双引号,支持转义与变量插值 |
|
||||
| 列表 | `[1, 2, 3]` | 通过表格构造 |
|
||||
| 字典 | `{"a": 1}` | 通过表格构造 |
|
||||
|
||||
文本 vs 字符串的区别:
|
||||
|
||||
- **裸 token**(如 `hello`、`路径`):按字面量,不转义,适合简短文本。
|
||||
- **双引号字符串**:需要转义(`\n` 等)或嵌入变量时使用。
|
||||
|
||||
```markdown
|
||||
> print text=Hello World! # 裸 token,按字面量
|
||||
*msg = "Hello, `name`!\n"* # 字符串,可插值、可转义
|
||||
```
|
||||
|
||||
## 2.6 关键字(不可作变量名)
|
||||
|
||||
以下单词是 Marqdo 的**保留关键字**,不能用作变量名:
|
||||
|
||||
| 英文 | 中文 | 含义 |
|
||||
|------|------|------|
|
||||
| `True` | `真` | 布尔真 |
|
||||
| `False` | `假` | 布尔假 |
|
||||
| `None` | `空` | 空值 |
|
||||
| `and` | `且` | 逻辑与 |
|
||||
| `or` | `或` | 逻辑或 |
|
||||
| `not` | `非` | 逻辑非 |
|
||||
|
||||
**不要**尝试用 `if` / `else` / `while` / `for` / `def` / `return` ——它们不是关键字,也没有意义。
|
||||
|
||||
## 2.7 一个完整的例子
|
||||
|
||||
把学到的串起来:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
这是一个完整示例:定义函数、调用、输出。
|
||||
|
||||
> 问候 谁=Marqdo
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=你好,`谁`!
|
||||
|
||||
---
|
||||
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
运行输出:
|
||||
|
||||
```text
|
||||
你好,Marqdo!
|
||||
```
|
||||
|
||||
## 2.8 下一步
|
||||
|
||||
你已经理解 `.mq.md` 的基本结构了。接下来学习[第 3 章:变量与赋值](./03-变量与赋值.md),掌握 Marqdo 的值存储方式。
|
||||
@@ -0,0 +1,121 @@
|
||||
# 第 3 章:变量与赋值
|
||||
|
||||
## 3.1 什么是变量
|
||||
|
||||
变量是给数据起的一个名字。Marqdo 中,变量在**斜体语句 `*…*`** 中通过 `=` 绑定:
|
||||
|
||||
```markdown
|
||||
*x = 1*
|
||||
*name = "Marqdo"*
|
||||
*ok = True*
|
||||
```
|
||||
|
||||
> **重要**:在 `*…*` / `**…**` 内部,**裸标识符就是变量**——不需要反引号。这是 Marqdo 的关键约定。
|
||||
|
||||
## 3.2 绑定的三种写法
|
||||
|
||||
### 写法一:斜体语句 `*…*`(推荐)
|
||||
|
||||
```markdown
|
||||
*x = 1*
|
||||
*y = x + 2*
|
||||
```
|
||||
|
||||
这是最常用的绑定方式。裸标识符就是变量。
|
||||
|
||||
### 写法二:行首反引号绑定(无 `*…*`)
|
||||
|
||||
```markdown
|
||||
`x` = 1
|
||||
```
|
||||
|
||||
不带 `*…*` 的绑定,变量名**需要反引号**。常用于绑定集合(表格)或公式:
|
||||
|
||||
```markdown
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
```
|
||||
|
||||
### 写法三:绑定调用结果
|
||||
|
||||
```markdown
|
||||
*len_s = > len value="hello"*
|
||||
```
|
||||
|
||||
`*…*` 内用 `= >` 表示「把调用结果赋给变量」。
|
||||
|
||||
## 3.3 引用变量
|
||||
|
||||
在 `*…*` 内部,直接写变量名即可:
|
||||
|
||||
```markdown
|
||||
*a = 5*
|
||||
*b = a * 2*
|
||||
> print text=`b` # 独立 > 调用中,变量要反引号
|
||||
```
|
||||
|
||||
> **关键区别**:在**独立 `>` 调用**(如 `> print …`)里,裸词是**文本**,所以引用变量要加反引号:`> print text=`b``。而在 `*…*` / `**…**` 内,裸词是**变量**:`*b = a * 2*`。
|
||||
|
||||
## 3.4 字符串与插值
|
||||
|
||||
### 双引号字符串
|
||||
|
||||
```markdown
|
||||
*msg = "Hello, World!"*
|
||||
```
|
||||
|
||||
### 转义字符
|
||||
|
||||
| 转义 | 含义 |
|
||||
|------|------|
|
||||
| `\n` | 换行 |
|
||||
| `\t` | 制表 |
|
||||
| `\r` | 回车 |
|
||||
| `\\` | 反斜杠 `\` |
|
||||
| `\"` | 双引号 `"` |
|
||||
| `\'` | 单引号 `'` |
|
||||
| `\xHH` | 十六进制字符(如 `\x22` → `"`) |
|
||||
| `\u{...}` | Unicode 码点(如 `\u{4e2d}` → `中`) |
|
||||
|
||||
未知转义(如 `\q`)**按字面保留**(`\q` → `\q`),不报错。
|
||||
|
||||
### 变量插值
|
||||
|
||||
字符串内用 `` `变量` `` 插值:
|
||||
|
||||
```markdown
|
||||
*name = "Marqdo"*
|
||||
*msg = "Hello, `name`!"*
|
||||
> print text=`msg` # 输出:Hello, Marqdo!
|
||||
```
|
||||
|
||||
## 3.5 完整示例
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*name = "Alice"*
|
||||
*age = 30*
|
||||
*next_age = age + 1*
|
||||
|
||||
> print text=名字:`name`
|
||||
> print text=明年:`next_age` 岁
|
||||
|
||||
*msg = "你好,`name`!你明年 `next_age` 岁。"*
|
||||
> print text=`msg`
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
名字:Alice
|
||||
明年:31 岁
|
||||
你好,Alice!你明年 31 岁。
|
||||
```
|
||||
|
||||
## 3.6 下一步
|
||||
|
||||
你已经会存取数据了。接下来学习[第 4 章:输出与输入](./04-输出与输入.md),与用户交互。
|
||||
@@ -0,0 +1,93 @@
|
||||
# 第 4 章:输出与输入
|
||||
|
||||
## 4.1 输出:`print` / `打印`
|
||||
|
||||
`print`(中文 `打印`)是内置函数,用于向标准输出写一行文本。**输出不是 `**粗体**`**——粗体是返回值,不是打印。
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello World!
|
||||
```
|
||||
|
||||
中英等价:
|
||||
|
||||
```markdown
|
||||
> 打印 内容=你好,世界!
|
||||
```
|
||||
|
||||
| 英文 | 中文 | 参数 |
|
||||
|------|------|------|
|
||||
| `> print text=…` | `> 打印 内容=…` | `text` ≡ `内容` |
|
||||
|
||||
### 输出变量
|
||||
|
||||
独立 `>` 调用中,变量用反引号:
|
||||
|
||||
```markdown
|
||||
*x = 42*
|
||||
> print text=`x` # 输出:42
|
||||
```
|
||||
|
||||
### 输出拼接
|
||||
|
||||
```markdown
|
||||
*name = "Marqdo"*
|
||||
> print text=欢迎使用 `name`!
|
||||
```
|
||||
|
||||
## 4.2 输入:`input` / `输入`
|
||||
|
||||
`input`(中文 `输入`)读取一行用户输入:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> input prompt=你叫什么名字?
|
||||
```
|
||||
|
||||
| 英文 | 中文 | 参数 |
|
||||
|------|------|------|
|
||||
| `> input prompt=…` | `> 输入 提示=…` | `prompt` ≡ `提示` |
|
||||
|
||||
### 读取并保存输入
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*name = > input prompt="请输入名字:"*
|
||||
> print text=你好,`name`!
|
||||
```
|
||||
|
||||
> `input` 的 `prompt` 参数可省略(缺省)。
|
||||
|
||||
## 4.3 完整示例:一个问答程序
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
这是一个人机问答程序。
|
||||
|
||||
*name = > input prompt="你叫什么名字?\n"*
|
||||
> print text=你好,`name`!
|
||||
|
||||
*age = > int value=`age_input`*
|
||||
```
|
||||
|
||||
> **注意**:上面的示例为了展示 `int` 用法,`age_input` 尚未定义。实际中你需要先从 `input` 得到字符串,再用 `int` 转换。完整可运行版本:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*name = > input prompt="你叫什么名字?\n"*
|
||||
> print text=你好,`name`!
|
||||
|
||||
*age_str = > input prompt="你几岁?\n"*
|
||||
*age = > int value=`age_str`*
|
||||
*next_age = age + 1*
|
||||
> print text=`name`,你明年 `next_age` 岁。
|
||||
```
|
||||
|
||||
## 4.4 下一步
|
||||
|
||||
你已经能与用户交互了。接下来学习[第 5 章:运算符与比较](./05-运算符与比较.md)。
|
||||
@@ -0,0 +1,122 @@
|
||||
# 第 5 章:运算符与比较
|
||||
|
||||
## 5.1 算术运算符
|
||||
|
||||
在 `*…*` 表达式内部:
|
||||
|
||||
```markdown
|
||||
*a = 10*
|
||||
*b = 3*
|
||||
|
||||
*sum = a + b* # 13
|
||||
*diff = a - b* # 7
|
||||
*prod = a * b* # 30
|
||||
*quo = a / b* # 3.33…(浮点除法)
|
||||
```
|
||||
|
||||
| 运算符 | 含义 |
|
||||
|--------|------|
|
||||
| `+` | 加法 / 拼接 |
|
||||
| `-` | 减法 |
|
||||
| `*` | 乘法 |
|
||||
| `/` | 除法 |
|
||||
|
||||
> **注意**:在裸表达式里 `/` 是除法;但在**调用实参 / 参数默认值**中,不空格相连的 `a/b` 会被当作路径文本(详见[第 11 章](./11-模块与导入.md))。
|
||||
|
||||
## 5.2 字符串拼接
|
||||
|
||||
`+` 也可以拼接字符串:
|
||||
|
||||
```markdown
|
||||
*first = "Hello, "*
|
||||
*second = "World!"*
|
||||
*msg = first + second*
|
||||
> print text=`msg` # Hello, World!
|
||||
```
|
||||
|
||||
> 在 `*…*` 内变量是裸名;若拼接的是字符串字面量,要加引号。
|
||||
|
||||
## 5.3 比较运算符
|
||||
|
||||
| 运算符 | 含义 |
|
||||
|--------|------|
|
||||
| `==` | 相等 |
|
||||
| `>` | 大于 |
|
||||
| `<` | 小于 |
|
||||
| `>=` | 大于等于 |
|
||||
| `<=` | 小于等于 |
|
||||
|
||||
```markdown
|
||||
*n = 5*
|
||||
|
||||
1. `n` > 3
|
||||
> print text=大于 3
|
||||
2. *
|
||||
> print text=小于等于 3
|
||||
```
|
||||
|
||||
## 5.4 逻辑运算符
|
||||
|
||||
| 英文 | 中文 | 含义 |
|
||||
|------|------|------|
|
||||
| `and` | `且` | 逻辑与 |
|
||||
| `or` | `或` | 逻辑或 |
|
||||
| `not` | `非` | 逻辑非 |
|
||||
|
||||
```markdown
|
||||
*age = 20*
|
||||
*has_id = True*
|
||||
|
||||
1. `age` >= 18 and `has_id`
|
||||
> print text=可以进入
|
||||
2. *
|
||||
> print text=不能进入
|
||||
```
|
||||
|
||||
## 5.5 布尔值
|
||||
|
||||
布尔值字面量:`True` / `False`(中文 `真` / `假`)。
|
||||
|
||||
```markdown
|
||||
*is_admin = False*
|
||||
|
||||
1. `is_admin` == True
|
||||
> print text=管理员
|
||||
2. *
|
||||
> print text=普通用户
|
||||
```
|
||||
|
||||
也可以直接用布尔变量作条件:
|
||||
|
||||
```markdown
|
||||
*flag = True*
|
||||
|
||||
1. `flag`
|
||||
> print text=为真
|
||||
2. *
|
||||
> print text=为假
|
||||
```
|
||||
|
||||
## 5.6 完整示例
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*score = 85*
|
||||
*passed = score >= 60*
|
||||
*bonus = passed and score >= 80*
|
||||
|
||||
> print text=及格:`passed`
|
||||
> print text=优秀:`bonus`
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
及格:True
|
||||
优秀:True
|
||||
```
|
||||
|
||||
## 5.7 下一步
|
||||
|
||||
你已经能计算和判断了。接下来学习[第 6 章:函数](./06-函数.md),把逻辑封装起来复用。
|
||||
@@ -0,0 +1,188 @@
|
||||
# 第 6 章:函数
|
||||
|
||||
## 6.1 定义函数
|
||||
|
||||
在 Marqdo 中,函数用 `##`(及更深)标题定义:
|
||||
|
||||
```markdown
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
- `## 加一` —— 函数名
|
||||
- `+ `n`` —— 参数
|
||||
- `**n + 1**` —— 返回值(**粗体 = 返回**)
|
||||
|
||||
函数可以挂在 `# main` 之下作为嵌套函数,也可以作为顶层自由函数。
|
||||
|
||||
## 6.2 调用函数
|
||||
|
||||
使用 `>` 调用(具名参数或位置参数):
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> greet who=World # 具名参数
|
||||
> greet World # 位置参数
|
||||
|
||||
## greet
|
||||
+ `who`
|
||||
|
||||
> print text=Hello, `who`!
|
||||
|
||||
---
|
||||
```
|
||||
|
||||
### 具名 vs 位置
|
||||
|
||||
```markdown
|
||||
> 问候 谁=Marqdo # 具名:名=值
|
||||
> 问候 Marqdo # 位置:按形参顺序
|
||||
```
|
||||
|
||||
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。
|
||||
|
||||
> 具名实参的值可以含空格,直到下一个 `名=` 边界;位置实参是单个词法单元(不含空格)。
|
||||
|
||||
## 6.3 参数与默认值
|
||||
|
||||
可选参数用 `=默认值`:
|
||||
|
||||
```markdown
|
||||
## 问候
|
||||
+ `谁`
|
||||
+ `礼貌`=False
|
||||
|
||||
1. `礼貌`
|
||||
> print text=您好,`谁`!
|
||||
2. *
|
||||
> print text=嗨,`谁`!
|
||||
```
|
||||
|
||||
调用:
|
||||
|
||||
```markdown
|
||||
> 问候 谁=小明
|
||||
> 问候 谁=小明 礼貌=True
|
||||
```
|
||||
|
||||
## 6.4 返回值:`**…**`
|
||||
|
||||
用 `**…**` 返回表达式结果:
|
||||
|
||||
```markdown
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
调用并绑定结果:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*b = > 加一 n=1*
|
||||
> print text=`b` # 2
|
||||
```
|
||||
|
||||
### 返回 None:`****`
|
||||
|
||||
`****`(或空粗体 `**` + 空白 + `**`)返回 `None` 并结束函数体:
|
||||
|
||||
```markdown
|
||||
## 静默
|
||||
+ `x`
|
||||
|
||||
****
|
||||
```
|
||||
|
||||
### 字符串返回
|
||||
|
||||
```markdown
|
||||
## 问候语
|
||||
+ `谁`
|
||||
|
||||
**"你好," + 谁 + "!"**
|
||||
```
|
||||
|
||||
## 6.5 结束函数体:`---` / `***`
|
||||
|
||||
对于**没有返回值、只有副作用**的函数,用单独一行 `---` 或 `***` 结束函数体,避免后续兄弟语句被吞掉:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello, `谁`!
|
||||
|
||||
---
|
||||
|
||||
## 下一个函数
|
||||
...
|
||||
```
|
||||
|
||||
> `---` 仅在**函数体顶层单独一行**时表示「结束本函数」;文件开头的成对 `---` 是 frontmatter,不会混淆。
|
||||
|
||||
## 6.6 完整示例
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 问候 谁=Alice 礼貌=True
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
+ `礼貌`=False
|
||||
|
||||
1. `礼貌`
|
||||
> print text=您好,`谁`!
|
||||
2. *
|
||||
> print text=嗨,`谁`!
|
||||
|
||||
---
|
||||
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
您好,Alice!
|
||||
```
|
||||
|
||||
## 6.7 函数嵌套(标题深度)
|
||||
|
||||
嵌套辅助函数用更深的标题:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 处理 名字=小明
|
||||
|
||||
## 处理
|
||||
+ `名字`
|
||||
|
||||
*上 = > 大写 文本=`名字`*
|
||||
> print text=`上`
|
||||
|
||||
### 大写
|
||||
+ `文本`
|
||||
|
||||
**> str `文本`**
|
||||
```
|
||||
|
||||
> 深度约定:`##` 是 `#` 的子级,`###` 是 `##` 的子级……按标题深度嵌套。
|
||||
|
||||
## 6.8 下一步
|
||||
|
||||
你已经会封装函数了。接下来学习[第 7 章:条件分支](./07-条件分支.md)。
|
||||
@@ -0,0 +1,138 @@
|
||||
# 第 7 章:条件分支
|
||||
|
||||
## 7.1 基本分支:`1.` `2.` …
|
||||
|
||||
Marqdo 用**有序列表** `1.` `2.` `3.` … 表达条件分支:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*n = 5*
|
||||
|
||||
1. `n` > 0
|
||||
> print text=正数
|
||||
2. `n` < 0
|
||||
> print text=负数
|
||||
3. *
|
||||
> print text=零
|
||||
```
|
||||
|
||||
- `1. 条件` —— 第一个分支(条件为真时执行其下的缩进行)
|
||||
- `2. 条件` —— 第二个分支
|
||||
- `3. *` —— else 臂(`N. *` = 否则)
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
正数
|
||||
```
|
||||
|
||||
## 7.2 else 臂:`N. *`
|
||||
|
||||
在 `1.` 之后的任意臂上,**整行恰为 `*`** 表示 else:
|
||||
|
||||
```markdown
|
||||
*age = 15*
|
||||
|
||||
1. `age` >= 18
|
||||
> print text=成年
|
||||
2. *
|
||||
> print text=未成年
|
||||
```
|
||||
|
||||
## 7.3 布尔分支
|
||||
|
||||
```markdown
|
||||
*is_admin = False*
|
||||
|
||||
1. `is_admin`
|
||||
> print text=管理员
|
||||
2. *
|
||||
> print text=普通用户
|
||||
```
|
||||
|
||||
## 7.4 多条件分支
|
||||
|
||||
```markdown
|
||||
*score = 85*
|
||||
|
||||
1. `score` >= 90
|
||||
> print text=优秀
|
||||
2. `score` >= 80
|
||||
> print text=良好
|
||||
3. `score` >= 60
|
||||
> print text=及格
|
||||
4. *
|
||||
> print text=不及格
|
||||
```
|
||||
|
||||
## 7.5 逻辑组合条件
|
||||
|
||||
```markdown
|
||||
*age = 25*
|
||||
*has_id = True*
|
||||
|
||||
1. `age` >= 18 and `has_id`
|
||||
> print text=可以进入
|
||||
2. *
|
||||
> print text=不能进入
|
||||
```
|
||||
|
||||
## 7.6 多个独立分支语句
|
||||
|
||||
**一条分支语句 = 从 `1.` 起、序号递增的一段有序列表。** 同级缩进上**再次出现 `1.`** 会开启**下一条**独立分支语句:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*a = True*
|
||||
*b = False*
|
||||
|
||||
1. `a`
|
||||
> print text=A 为真
|
||||
2. *
|
||||
> print text=A 为假
|
||||
|
||||
1. `b`
|
||||
> print text=B 为真
|
||||
2. *
|
||||
> print text=B 为假
|
||||
```
|
||||
|
||||
这是**两次独立判断**,不是「四个臂的一个分支」。输出:
|
||||
|
||||
```text
|
||||
A 为真
|
||||
B 为假
|
||||
```
|
||||
|
||||
> 臂序号在同一分支内递增(`1.` → `2.` → `3.` …);不要在同一分支中途把序号重置为 `1.`。
|
||||
|
||||
## 7.7 完整示例:成绩评级
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*score = 72*
|
||||
|
||||
1. `score` >= 90
|
||||
> print text=评级:A
|
||||
2. `score` >= 80
|
||||
> print text=评级:B
|
||||
3. `score` >= 70
|
||||
> print text=评级:C
|
||||
4. `score` >= 60
|
||||
> print text=评级:D
|
||||
5. *
|
||||
> print text=评级:F
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
评级:C
|
||||
```
|
||||
|
||||
## 7.8 下一步
|
||||
|
||||
你已经能根据条件走不同路线了。接下来学习[第 8 章:循环](./08-循环.md)。
|
||||
@@ -0,0 +1,179 @@
|
||||
# 第 8 章:循环
|
||||
|
||||
## 8.1 遍历循环:`- [项](集合)`
|
||||
|
||||
Marqdo 用 `-`(无序列表)表达循环。遍历列表用 `- [项](集合)`:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
| 桃 |
|
||||
|
||||
- [果](篮子)
|
||||
> print text=今天吃`果`
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
今天吃苹果
|
||||
今天吃梨
|
||||
今天吃桃
|
||||
```
|
||||
|
||||
- `[果](篮子)` —— 遍历 `篮子` 列表,每个元素绑定到 `果`
|
||||
- 循环体内用 `` `果` `` 引用元素(独立 `>` 调用中变量要反引号)
|
||||
|
||||
反引号形式等价(可混用):
|
||||
|
||||
```markdown
|
||||
- [`果`](`篮子`)
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
## 8.2 遍历字典:遍历键
|
||||
|
||||
`Map`(字典)用 `- [键](映射)` 遍历**键**:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`分类` =
|
||||
|
||||
| 苹果 | 黄瓜 |
|
||||
|------|------|
|
||||
| 水果 | 蔬菜 |
|
||||
|
||||
- [键](分类)
|
||||
> print text=`键`
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
苹果
|
||||
黄瓜
|
||||
```
|
||||
|
||||
> 遍历字典遍历的是键;要取值,用脚注取元(见[第 9 章](./09-集合.md))。
|
||||
|
||||
## 8.3 while 循环:`- 条件`
|
||||
|
||||
`-` 后直接写条件就是 while 循环:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*n = 3*
|
||||
|
||||
- `n` > 0
|
||||
> print text=`n`
|
||||
*n = n - 1*
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
3
|
||||
2
|
||||
1
|
||||
```
|
||||
|
||||
> 循环体内用 `*…*` 语句更新变量。
|
||||
|
||||
## 8.4 嵌套循环
|
||||
|
||||
循环可以嵌套:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`外层` =
|
||||
|
||||
| 项 |
|
||||
|----|
|
||||
| A |
|
||||
| B |
|
||||
|
||||
`内层` =
|
||||
|
||||
| 项 |
|
||||
|----|
|
||||
| 1 |
|
||||
| 2 |
|
||||
|
||||
- [o](外层)
|
||||
- [i](内层)
|
||||
> print text=`o``i`
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
A1
|
||||
A2
|
||||
B1
|
||||
B2
|
||||
```
|
||||
|
||||
## 8.5 循环 + 分支组合
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`数字` =
|
||||
|
||||
| 值 |
|
||||
|----|
|
||||
| 1 |
|
||||
| 2 |
|
||||
| 3 |
|
||||
| 4 |
|
||||
|
||||
- [n](数字)
|
||||
1. `n` >= 3
|
||||
> print text=`n` 是大数
|
||||
2. *
|
||||
> print text=`n` 是小数
|
||||
```
|
||||
|
||||
> 循环体里的 `1.` / `2.` 是分支语句(见[第 7 章](./07-条件分支.md)),与 `-` 循环嵌套使用。
|
||||
|
||||
## 8.6 完整示例:累计求和
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`数字` =
|
||||
|
||||
| 值 |
|
||||
|----|
|
||||
| 1 |
|
||||
| 2 |
|
||||
| 3 |
|
||||
| 4 |
|
||||
| 5 |
|
||||
|
||||
*sum = 0*
|
||||
|
||||
- [n](数字)
|
||||
*sum = sum + n*
|
||||
|
||||
> print text=总和:`sum`
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
总和:15
|
||||
```
|
||||
|
||||
## 8.7 下一步
|
||||
|
||||
你已经掌握循环了。接下来学习[第 9 章:集合(表格)](./09-集合.md),深入理解列表、字典与记录。
|
||||
@@ -0,0 +1,203 @@
|
||||
# 第 9 章:集合(表格)
|
||||
|
||||
Marqdo 用 **GFM 表格**直接构造数据集合。表格的**几何形状**决定值的类型——这是 Marqdo 最有特色的部分:你看到的 Markdown 表格就是数据结构。
|
||||
|
||||
## 9.1 绑定一个集合
|
||||
|
||||
集合绑定用「空右侧赋值 + 表格」:
|
||||
|
||||
```markdown
|
||||
`名字` =
|
||||
|
||||
| 表头1 | 表头2 |
|
||||
|-------|-------|
|
||||
| 值 | 值 |
|
||||
```
|
||||
|
||||
表格绑定变量名**需要反引号**(不在 `*…*` 内)。
|
||||
|
||||
## 9.2 单列竖表 → 列表(List)
|
||||
|
||||
**恰好 1 列** → 列表:
|
||||
|
||||
```markdown
|
||||
`篮子` =
|
||||
|
||||
| 果 |
|
||||
|----|
|
||||
| 苹果 |
|
||||
| 梨 |
|
||||
| 桃 |
|
||||
```
|
||||
|
||||
等价于 `["苹果", "梨", "桃"]`。表头 `果` 是元素逻辑名(foreach 绑定名),**不进入列表元素**。
|
||||
|
||||
```markdown
|
||||
- [果](篮子)
|
||||
> print text=`果`
|
||||
```
|
||||
|
||||
## 9.3 多列 + 一行 → 字典(Map)
|
||||
|
||||
**≥2 列 + 恰好 1 行数据** → 字典,键 = 表头:
|
||||
|
||||
```markdown
|
||||
`分类` =
|
||||
|
||||
| 苹果 | 黄瓜 |
|
||||
|------|------|
|
||||
| 水果 | 蔬菜 |
|
||||
```
|
||||
|
||||
等价于 `{"苹果": "水果", "黄瓜": "蔬菜"}`。
|
||||
|
||||
## 9.4 多列 + 多行 → 字典套列表
|
||||
|
||||
**≥2 列 + ≥2 行数据** → 字典,值为该列的列表(列向聚合):
|
||||
|
||||
```markdown
|
||||
`货架` =
|
||||
|
||||
| 苹果 | 黄瓜 |
|
||||
|------|------|
|
||||
| 红富士 | 青瓜 |
|
||||
| 嘎啦 | 黄瓜条 |
|
||||
```
|
||||
|
||||
等价于:
|
||||
|
||||
```text
|
||||
{"苹果": ["红富士", "嘎啦"], "黄瓜": ["青瓜", "黄瓜条"]}
|
||||
```
|
||||
|
||||
## 9.5 行向记录表 → 记录列表
|
||||
|
||||
首列表头为 `@` / `行` / `row` 时,整表改为**行向**(SQL/CSV 风格):
|
||||
|
||||
```markdown
|
||||
`订单` =
|
||||
|
||||
| 行 | 品名 | 数量 |
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
| 2 | 梨 | 3 |
|
||||
```
|
||||
|
||||
等价于:
|
||||
|
||||
```text
|
||||
[{"品名": "苹果", "数量": 2}, {"品名": "梨", "数量": 3}]
|
||||
```
|
||||
|
||||
标记列(`行`)不进入记录字段。
|
||||
|
||||
## 9.6 表格形状速查
|
||||
|
||||
| 形状 | 值类型 |
|
||||
|------|--------|
|
||||
| 1 列 | `List` |
|
||||
| ≥2 列 + 1 行 | `Map`(标量值) |
|
||||
| ≥2 列 + ≥2 行 | `Map`(值均为 `List`) |
|
||||
| ≥2 列 + 0 行 | `Map`(键存在,值空列表) |
|
||||
| 首列 `@`/`行`/`row` | `List` of `Map`(行向记录) |
|
||||
|
||||
## 9.7 脚注取元:`[^…]`
|
||||
|
||||
用 Markdown 脚注外形从集合取元素(**表达式级**,可链式)。
|
||||
|
||||
### 从列表按下标取
|
||||
|
||||
**下标是 1-based**(与人类读表一致):
|
||||
|
||||
```markdown
|
||||
*第一 = 篮子[^1]*
|
||||
> print text=`第一` # 苹果
|
||||
```
|
||||
|
||||
### 从字典按键取
|
||||
|
||||
```markdown
|
||||
*种 = 分类[^苹果]*
|
||||
> print text=`种` # 水果
|
||||
```
|
||||
|
||||
### 嵌套取元
|
||||
|
||||
```markdown
|
||||
*第一种苹果 = 货架[^苹果][^1]* # 先键,再下标 → 红富士
|
||||
```
|
||||
|
||||
### 基名的反引号
|
||||
|
||||
`` 名[^键] `` 与 `` `名`[^键] `` 等价(紧跟 `[^` 时可省略反引号):
|
||||
|
||||
```markdown
|
||||
*种 = `分类`[^苹果]*
|
||||
```
|
||||
|
||||
### 插值中的取元
|
||||
|
||||
在**调用实参值 / 引号字符串**里,`` `变量` `` 后**紧跟**(无空白)`[^…]` 时也按取元解析,而不必先绑定再输出:
|
||||
|
||||
```markdown
|
||||
> print text=苹果单价:`水果价格`[^苹果] # 输出:苹果单价:5
|
||||
> print text=第一种:`货架`[^苹果][^1] # 链式取元 → 红富士
|
||||
> print text="价 `水果价格`[^香蕉] 元" # 引号字符串内也可取元 → 价 3 元
|
||||
```
|
||||
|
||||
> 规则:`` `变量` [^…] ``(**有空白**)时 `[^…]` 仍是普通文本;只有 `` `变量`[^…] ``(无空白)才算取元。
|
||||
|
||||
> 规则:
|
||||
> - **List**:标签须为纯数字(1-based);`[^0]` 或越界 → 报错。
|
||||
> - **Map**:标签为键文本(含纯数字键,如 `[^00]`);缺键 → 报错。
|
||||
> - 文末的 `[^1]: …` 定义块仍是注释,与取元无关。
|
||||
|
||||
## 9.8 表格单元格是表达式
|
||||
|
||||
数据单元格支持表达式(与调用实参值语法相同):裸词、数字、`` `var` ``、算术、引号串。URL / `gpt-4o-mini` 等按路径/连字符折叠为文本。
|
||||
|
||||
```markdown
|
||||
*k = "secret"*
|
||||
|
||||
`cfg` =
|
||||
|
||||
| api_key | model |
|
||||
|---------|-------|
|
||||
| `k` | gpt-4o-mini |
|
||||
```
|
||||
|
||||
## 9.9 完整示例
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
`水果价格` =
|
||||
|
||||
| 苹果 | 香蕉 |
|
||||
|------|------|
|
||||
| 5 | 3 |
|
||||
|
||||
> print text=苹果单价:`水果价格`[^苹果]
|
||||
|
||||
`购物单` =
|
||||
|
||||
| 行 | 品名 | 数量 |
|
||||
|----|------|------|
|
||||
| 1 | 苹果 | 2 |
|
||||
| 2 | 香蕉 | 3 |
|
||||
|
||||
- [行](购物单)
|
||||
> print text=`行`[^品名] × `行`[^数量]
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
苹果单价:5
|
||||
苹果 × 2
|
||||
香蕉 × 3
|
||||
```
|
||||
|
||||
## 9.10 下一步
|
||||
|
||||
你已经掌握 Marqdo 的数据组织了。接下来学习[第 10 章:对象与方法](./10-对象与方法.md)。
|
||||
@@ -0,0 +1,195 @@
|
||||
# 第 10 章:对象与方法
|
||||
|
||||
Marqdo 用 `#` 标题定义**对象 / 类型**,用 `##` 定义其下的**方法**。这是一种轻量、可读的面向对象写法。
|
||||
|
||||
## 10.1 定义对象(类型)
|
||||
|
||||
`#`(恰好一层)定义一个对象 / 类型,其正文是**构造体**:
|
||||
|
||||
```markdown
|
||||
# 大模型
|
||||
+ `模型名`
|
||||
|
||||
*配置 = > json.parse text={"model":"gpt-4o-mini"}*
|
||||
**配置**
|
||||
```
|
||||
|
||||
- `# 大模型` —— 类型名
|
||||
- `+ `模型名`` —— 构造参数
|
||||
- 构造体执行后 `**…**` 返回一个 map,运行时写入 `_type` 字段,形成实例句柄
|
||||
|
||||
## 10.2 构造实例
|
||||
|
||||
调用类型名即可构造实例:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*模型 = > 大模型 模型名="gpt-4o-mini"*
|
||||
```
|
||||
|
||||
## 10.3 定义方法
|
||||
|
||||
对象下的 `##` 标题是方法:
|
||||
|
||||
```markdown
|
||||
# 计数器
|
||||
+ `初始值`
|
||||
|
||||
*状态 = > json.parse text={"n":0}*
|
||||
*状态 = > json.set map=`状态` key="n" value=`初始值`*
|
||||
**状态**
|
||||
|
||||
## 加一
|
||||
|
||||
*n = > json.get value=`self` key="n"*
|
||||
*n2 = n + 1*
|
||||
*t = > json.set map=`self` key="n" value=`n2`*
|
||||
**t**
|
||||
```
|
||||
|
||||
方法体内自动绑定:
|
||||
|
||||
- `self`(英文)
|
||||
- `自`(中文)
|
||||
|
||||
二者是同一个接收者,指向当前实例。
|
||||
|
||||
## 10.4 调用方法
|
||||
|
||||
### 独立 `>` 调用(接收者加反引号)
|
||||
|
||||
```markdown
|
||||
*计数器 = > 计数器 初始值=3*
|
||||
*新值 = > `计数器`.加一*
|
||||
```
|
||||
|
||||
### `*…*` 段内调用(接收者裸名)
|
||||
|
||||
```markdown
|
||||
*计数器 = > 计数器 初始值=3*
|
||||
*新值 = > 计数器.加一*
|
||||
```
|
||||
|
||||
> **重要**:在 `*…*` / `**…**` 段内,裸词是变量,所以**方法接收者不加反引号**:`*新值 = > 计数器.加一*`。而在独立 `>` 调用中,裸词是文本,接收者需要反引号:`> `计数器`.加一`。
|
||||
|
||||
## 10.5 完整对象示例
|
||||
|
||||
对象(`#`)定义在**顶层**,与 `# main` 平级:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import json:lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*c = > 计数器 初始值=5*
|
||||
*ty = > json.get value=`c` key="_type"*
|
||||
> print text=类型:`ty`
|
||||
|
||||
*c2 = > c.加一*
|
||||
*n = > json.get value=`c2` key="n"*
|
||||
> print text=加一后:`n`
|
||||
|
||||
# 计数器
|
||||
+ `初始值`
|
||||
|
||||
*状态 = > json.parse text={"n":0}*
|
||||
*状态 = > json.set map=`状态` key="n" value=`初始值`*
|
||||
**状态**
|
||||
|
||||
## 加一
|
||||
|
||||
*n = > json.get value=`self` key="n"*
|
||||
*n2 = n + 1*
|
||||
*t = > json.set map=`self` key="n" value=`n2`*
|
||||
**t**
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
类型:计数器
|
||||
加一后:6
|
||||
```
|
||||
|
||||
## 10.6 继承:`# Child = > Parent`
|
||||
|
||||
```markdown
|
||||
# Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*msg = "Hello, `who`!"*
|
||||
**msg**
|
||||
|
||||
# Loud = > Greeter
|
||||
|
||||
## hello
|
||||
+ `who`
|
||||
|
||||
*msg = "HELLO, `who`!"*
|
||||
**msg**
|
||||
```
|
||||
|
||||
规则:
|
||||
|
||||
| 规则 | 说明 |
|
||||
|------|------|
|
||||
| 语法 | `# Child = > Parent` |
|
||||
| `_type` | 构造后仍为**最具体子类名** |
|
||||
| 方法查找 | 先子类 `##`,未命中再沿基类链;同名则子类覆盖 |
|
||||
| 构造 | **不**隐式调用父构造(无 auto-super) |
|
||||
| 多继承 | 不支持 |
|
||||
|
||||
### 显式调用父构造
|
||||
|
||||
子类需要父字段时,在子类正文首行显式调用父构造:
|
||||
|
||||
```markdown
|
||||
# Child = > Parent
|
||||
+ `name`
|
||||
|
||||
*self = > Parent name=`name`*
|
||||
*self = > json.set map=`self` key="role" value="child"*
|
||||
**self**
|
||||
```
|
||||
|
||||
## 10.7 完整继承示例
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
*c = > Child name="Ada"*
|
||||
*ty = > json.get value=`c` key="_type"*
|
||||
*role = > json.get value=`c` key="role"*
|
||||
> print text=`ty`
|
||||
> print text=`role`
|
||||
|
||||
# Parent
|
||||
+ `name`
|
||||
|
||||
*out = > json.parse text={"role":"parent"}*
|
||||
*out = > json.set map=`out` key="name" value=`name`*
|
||||
**out**
|
||||
|
||||
# Child = > Parent
|
||||
+ `name`
|
||||
|
||||
*self = > Parent name=`name`*
|
||||
*self = > json.set map=`self` key="role" value="child"*
|
||||
**self**
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
Child
|
||||
child
|
||||
```
|
||||
|
||||
## 10.8 下一步
|
||||
|
||||
你已经会面向对象编程了。接下来学习[第 11 章:模块与导入](./11-模块与导入.md),组织大型项目。
|
||||
@@ -0,0 +1,175 @@
|
||||
# 第 11 章:模块与导入
|
||||
|
||||
大型项目需要把代码拆成多个文件。Marqdo 用 **frontmatter 导入**和**点号寻址**组织模块。
|
||||
|
||||
## 11.1 Frontmatter 元信息
|
||||
|
||||
文件开头的成对 `---` 之间是 frontmatter,存放元信息(标题、描述、导入):
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 我的程序
|
||||
description: 描述文字
|
||||
---
|
||||
```
|
||||
|
||||
## 11.2 导入文件:`import 绑定:路径.mq.md`
|
||||
|
||||
```markdown
|
||||
---
|
||||
import text:lib/text.mq.md
|
||||
import time:lib/time.mq.md
|
||||
---
|
||||
```
|
||||
|
||||
- `text` —— 绑定名(本地库名)
|
||||
- `lib/text.mq.md` —— 目标文件路径
|
||||
|
||||
导入后得到一个**库(模块)绑定**,成员**不会**倒进全局。
|
||||
|
||||
中文等价:`导入 文本:lib/文本.mq.md`。
|
||||
|
||||
## 11.3 点号寻址调用:`库.成员`
|
||||
|
||||
导入后用裸点号路径调用库成员:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import json:lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*t = > time.now_unix*
|
||||
*s = > time.format unix=`t` pattern="%Y-%m-%d"*
|
||||
> print text=`s`
|
||||
```
|
||||
|
||||
- `time.now_unix` —— 调用 `time` 库的 `now_unix` 函数
|
||||
- `time.format` —— 调用 `time` 库的 `format` 函数
|
||||
|
||||
**库名不是变量**:路径段是裸标识符,不加反引号。
|
||||
|
||||
## 11.4 三段路径:`库.类型.方法`
|
||||
|
||||
```markdown
|
||||
---
|
||||
import agent:ext/ai/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*助手 = > agent.agent model="gpt-4o-mini"* # 库 → 类型:构造
|
||||
```
|
||||
|
||||
`agent.agent` —— `agent` 库中的 `agent` 类型(构造)。
|
||||
|
||||
## 11.5 短名:`import 绑定:库.成员`
|
||||
|
||||
把库路径成员绑为本地短名:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import time:lib/time.mq.md
|
||||
import fmt:time.format
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*t = > time.now_unix*
|
||||
*s = > fmt unix=`t` pattern="%Y-%m-%d"*
|
||||
```
|
||||
|
||||
`fmt` 现在是 `time.format` 的短名。
|
||||
|
||||
## 11.6 方法调用 vs 库路径(Python 统一命名空间)
|
||||
|
||||
对裸点号 `a.b`,规则是:
|
||||
|
||||
- 若 `a` 是当前作用域的**局部变量** → **方法调用**(`a` 为接收者)
|
||||
- 否则 → **库路径**
|
||||
|
||||
| 写法 | 含义 |
|
||||
|------|------|
|
||||
| `time.parse` | 库路径(裸名,第一段非变量) |
|
||||
| `` > `助手`.step `` | 独立 `>` 调用:实例方法(接收者反引号) |
|
||||
| `*回复 = > 助手.step …*` | `*…*` 段内:`助手` 是变量 → 实例方法;否则 → 库路径 |
|
||||
|
||||
```markdown
|
||||
---
|
||||
import agent:ext/ai/agent.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*助手 = > agent.agent model="gpt-4o-mini"*
|
||||
*out = > 助手.step task="你好"* # 助手是变量 → 方法调用
|
||||
```
|
||||
|
||||
## 11.7 完整示例:多模块程序
|
||||
|
||||
假设项目结构:
|
||||
|
||||
```text
|
||||
project/
|
||||
├── main.mq.md
|
||||
├── lib/
|
||||
│ ├── 数学.mq.md
|
||||
│ └── 问候.mq.md
|
||||
```
|
||||
|
||||
`lib/数学.mq.md`:
|
||||
|
||||
```markdown
|
||||
## 加倍
|
||||
+ `n`
|
||||
|
||||
**n * 2**
|
||||
```
|
||||
|
||||
`lib/问候.mq.md`:
|
||||
|
||||
```markdown
|
||||
## 你好
|
||||
+ `谁`
|
||||
|
||||
> print text=你好,`谁`!
|
||||
```
|
||||
|
||||
`main.mq.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import 数学:lib/数学.mq.md
|
||||
import 问候:lib/问候.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*结果 = > 数学.加倍 n=21*
|
||||
> print text=`结果`
|
||||
|
||||
> 问候.你好 谁=世界
|
||||
```
|
||||
|
||||
输出:
|
||||
|
||||
```text
|
||||
42
|
||||
你好,世界!
|
||||
```
|
||||
|
||||
## 11.8 库路径解析
|
||||
|
||||
`lib/…` 按以下顺序解析:
|
||||
|
||||
1. 环境变量 `MARQDO_LIB`
|
||||
2. 当前目录下的 `lib/`
|
||||
3. `marqdo` 可执行文件旁边的 `lib/`(及几个父目录)
|
||||
|
||||
官方扩展(`ext/`)用 `marqdo ext add llm|agent|web|quantum` 安装,导入仍写 `import llm:ext/llm.mq.md` 等。
|
||||
|
||||
## 11.9 下一步
|
||||
|
||||
你已经能组织大型项目了。接下来学习[第 12 章:标准库](./12-标准库.md),使用官方能力。
|
||||
@@ -0,0 +1,172 @@
|
||||
# 第 12 章:标准库
|
||||
|
||||
Marqdo 内置函数无需导入即可使用;更丰富的能力通过导入 `lib/` 模块获得。
|
||||
|
||||
## 12.1 内置函数(无需导入)
|
||||
|
||||
| 英文 | 中文 | 作用 |
|
||||
|------|------|------|
|
||||
| `print` | `打印` | 写标准输出(参数 `text` ≡ `内容`) |
|
||||
| `input` | `输入` | 读一行(参数 `prompt` ≡ `提示`) |
|
||||
| `len` | `长度` | 文本 / 集合长度(参数 `value` ≡ `值`) |
|
||||
| `str` | `文本` | 转为显示文本(参数 `value` ≡ `值`) |
|
||||
| `int` | `整数` | 转为整数(参数 `value` ≡ `值`) |
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> print text=Hello
|
||||
|
||||
*s = "Marqdo"*
|
||||
*n = > len value=`s`*
|
||||
> print text=长度:`n`
|
||||
```
|
||||
|
||||
## 12.2 标准库模块
|
||||
|
||||
导入一个 `lib/` 文件,使用**该文件**的函数名:
|
||||
|
||||
| 英文导入 | 中文导入 | 典型功能 |
|
||||
|----------|----------|----------|
|
||||
| `lib/text.mq.md` | `lib/文本.mq.md` | 文本处理(去空白、拆分、拼接) |
|
||||
| `lib/table.mq.md` | `lib/表.mq.md` | 列表 / 字典元素更新 |
|
||||
| `lib/fs.mq.md` | `lib/文件.mq.md` | 文件系统 |
|
||||
| `lib/sys.mq.md` | `lib/系统.mq.md` | 进程 / 当前目录 / 加载环境变量 |
|
||||
| `lib/plugin.mq.md` | `lib/插件.mq.md` | 加载原生 ABI 插件 |
|
||||
| `lib/time.mq.md` | `lib/时间.mq.md` | 时间 / 格式化 |
|
||||
| `lib/net.mq.md` | `lib/网络.mq.md` | HTTP(S) |
|
||||
| `lib/json.mq.md` | — | JSON 解析 / 序列化 |
|
||||
| `lib/math.mq.md` | `lib/数学.mq.md` | 数值、三角函数、随机、公式、绘图 |
|
||||
| `lib/foreign.mq.md` | `lib/外联.mq.md` | 运行异种语言代码块 |
|
||||
|
||||
> **语言一致性**:导入英文库文件,就用其英文 API;导入中文库文件,就用其中文 API。不要混用语言。
|
||||
|
||||
## 12.3 JSON 模块示例
|
||||
|
||||
`json` 模块负责**文本 ↔ 结构化数据**的序列化转换,以及把文本字符串里的 `\n` 等转义还原:
|
||||
|
||||
| 函数 | 作用 |
|
||||
|------|------|
|
||||
| `json.parse` | 解析 JSON 文本 |
|
||||
| `json.stringify` | 序列化为 JSON 文本 |
|
||||
| `json.get` | 取字段(键) |
|
||||
| `json.keys` | 取所有键 |
|
||||
| `json.set` | 设字段 |
|
||||
| `json.append` | 向列表追加 |
|
||||
|
||||
```markdown
|
||||
---
|
||||
import json:lib/json.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*obj = > json.parse text={"a":1}*
|
||||
*out = > json.stringify value=`obj`*
|
||||
> print text=`out` # {"a":1}
|
||||
|
||||
*nl = > json.parse text={"n":"\n"}*
|
||||
> print text=第一行`nl`[^n]第二行 # 换行还原
|
||||
```
|
||||
|
||||
> **字典操作**:本地字典的读取用脚注取元 `变量[^键]`,**不要**用 `json.get`。`json.get` / `json.set` 仅用于跨文本边界的序列化场景(例如与外部 JSON API 交换数据时)。构造字典用 GFM 横表(见[第 9 章](./09-集合.md))。
|
||||
`json` 常用函数:
|
||||
|
||||
| 函数 | 作用 |
|
||||
|------|------|
|
||||
| `json.parse` | 解析 JSON 文本 |
|
||||
| `json.stringify` | 序列化为 JSON 文本 |
|
||||
| `json.get` | 取字段(键) |
|
||||
| `json.keys` | 取所有键 |
|
||||
| `json.set` | 设字段 |
|
||||
| `json.append` | 向列表追加 |
|
||||
|
||||
## 12.4 文本模块示例
|
||||
|
||||
```markdown
|
||||
---
|
||||
import text:lib/text.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*parts = > text.str_split s="a,b,c" sep=","*
|
||||
> print text=`parts`
|
||||
|
||||
*joined = > text.str_join xs=`parts` sep="-"*
|
||||
> print text=`joined` # a-b-c
|
||||
```
|
||||
|
||||
## 12.5 数学模块:公式与绘图
|
||||
|
||||
```markdown
|
||||
---
|
||||
import math:lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*值 = > math.num value=3.5*
|
||||
> print text=`值`
|
||||
```
|
||||
|
||||
公式绑定:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import math:lib/math.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`f` =
|
||||
$$
|
||||
x^2 - 2
|
||||
$$
|
||||
|
||||
*_svg = > math.plot formula=`f` var=x min=-3 max=3*
|
||||
```
|
||||
|
||||
空 RHS 赋值 + 后随 `$$…$$` 绑定一个公式值。
|
||||
|
||||
## 12.6 官方扩展库(`ext/`)
|
||||
|
||||
扩展库不是 stdlib,需安装:
|
||||
|
||||
```bash
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext add web
|
||||
marqdo ext add quantum
|
||||
```
|
||||
|
||||
导入仍写 `import …:ext/….mq.md`:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import llm:ext/llm.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*模型 = > llm.llm model="gpt-4o-mini"*
|
||||
```
|
||||
|
||||
| 扩展 | 功能 |
|
||||
|------|------|
|
||||
| `llm` | 大模型对话 |
|
||||
| `agent` | 文档驱动的智能体框架 |
|
||||
| `web` | Web 应用 |
|
||||
| `quantum` | 量子电路模拟 |
|
||||
|
||||
## 12.7 查看库的精确 API
|
||||
|
||||
打开 `lib/` 或 `ext/` 下对应的 `.mq.md` 文件,即可看到精确的 `##` / `#` 名称和参数。例如 `lib/json.mq.md` 顶层就是 `## parse`、`## stringify` 等。
|
||||
|
||||
## 12.8 下一步
|
||||
|
||||
你已经会使用标准库了。继续学习:
|
||||
|
||||
- [第 13 章:命令行工具](./13-命令行工具.md) —— 运行、调试、扩展管理
|
||||
- [第 14 章:网络与 Web 扩展](./14-网络与Web扩展.md) —— `lib/net` 与 `ext/web` 实战
|
||||
@@ -0,0 +1,111 @@
|
||||
# 第 13 章:命令行工具
|
||||
|
||||
Marqdo 提供一组命令行工具,覆盖运行、浏览、调试、发布全流程。
|
||||
|
||||
## 13.1 命令总览
|
||||
|
||||
```text
|
||||
marqdo --version # 查看版本
|
||||
marqdo run 文件.mq.md # 运行程序
|
||||
marqdo view 路径 # 文档浏览器(默认端口 7429)
|
||||
marqdo debug 路径 # 调试界面(默认端口 7430)
|
||||
marqdo catalog 路径 -o 目录 # 生成 OKF 风格清单
|
||||
marqdo sync 路径 -o 目录 # catalog 的别名
|
||||
marqdo ext list # 列出扩展
|
||||
marqdo ext add llm|agent|web|quantum
|
||||
marqdo ext remove llm|agent|web|quantum
|
||||
```
|
||||
|
||||
## 13.2 运行程序:`run`
|
||||
|
||||
```bash
|
||||
marqdo run hello.mq.md
|
||||
```
|
||||
|
||||
指定后端(树遍历默认 / 字节码):
|
||||
|
||||
```bash
|
||||
marqdo run hello.mq.md --backend bytecode
|
||||
```
|
||||
|
||||
### 错误诊断
|
||||
|
||||
诊断信息格式:`path:line:col: message`(行 / 列从 1 开始)。
|
||||
|
||||
```text
|
||||
error: hello.mq.md:5:1: undefined variable `x`
|
||||
```
|
||||
|
||||
根据 `path:line:col` 定位并修复,再重新运行直到退出码为 0。
|
||||
|
||||
## 13.3 文档浏览器:`view`
|
||||
|
||||
`view` 启动一个本地文档浏览器,把 `.mq.md` 渲染成可浏览的文档站:
|
||||
|
||||
```bash
|
||||
marqdo view public --no-open
|
||||
```
|
||||
|
||||
浏览器打开后可看到:
|
||||
|
||||
- Structure(结构)
|
||||
- 函数大纲 / 搜索
|
||||
- Execution(执行)
|
||||
- Variables(变量浮窗)
|
||||
|
||||
## 13.4 调试器:`debug`
|
||||
|
||||
```bash
|
||||
marqdo debug public --no-open
|
||||
```
|
||||
|
||||
提供独立调试页面,支持:
|
||||
|
||||
- 断点
|
||||
- 单步执行
|
||||
- 局部变量查看
|
||||
|
||||
## 13.5 生成清单:`catalog` / `sync`
|
||||
|
||||
从源码派生 OKF 风格的 YAML / Markdown 知识包:
|
||||
|
||||
```bash
|
||||
marqdo catalog public -o .marqdo
|
||||
# 或
|
||||
marqdo sync public -o .marqdo
|
||||
```
|
||||
|
||||
| 参数 | 默认 | 说明 |
|
||||
|------|------|------|
|
||||
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
|
||||
| `-o` / `--out` | `.marqdo` | 输出目录 |
|
||||
|
||||
产物:`catalog.yaml`、`index.md`、`modules/*.md` 等。
|
||||
|
||||
## 13.6 扩展管理:`ext`
|
||||
|
||||
```bash
|
||||
marqdo ext list
|
||||
marqdo ext add llm
|
||||
marqdo ext add agent
|
||||
marqdo ext remove llm
|
||||
```
|
||||
|
||||
扩展默认安装到 `~/.marqdo/ext`(或 `MARQDO_EXT`)。
|
||||
|
||||
## 13.7 标准库与可执行文件解析
|
||||
|
||||
- **标准库**:内置于二进制;磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。
|
||||
- **库路径解析**:`MARQDO_LIB` → 当前目录 `lib/` → 可执行文件旁 `lib/`。
|
||||
|
||||
## 13.8 下一步
|
||||
|
||||
恭喜!你已经完成了 Marqdo 语法教程。你现在可以:
|
||||
|
||||
- 写出带输入输出、函数、分支、循环的程序
|
||||
- 用表格组织列表、字典、记录
|
||||
- 用对象和方法做面向对象编程
|
||||
- 拆分模块、使用标准库和扩展
|
||||
- 用命令行工具运行、调试、发布
|
||||
|
||||
祝你在「代码即文档」的世界里愉快!
|
||||
@@ -0,0 +1,205 @@
|
||||
# 第 14 章:网络与 Web 扩展
|
||||
|
||||
Marqdo 的网络能力分两层:**标准库 `lib/net`**(HTTP 客户端、cookie / multipart 解析)与**官方扩展 `ext/web`**(网页应用、数据库、表单、登录鉴权、WebSocket)。分层的依据是「代码即文档」的可读性——基础、通用、低依赖的进标准库;领域性强、依赖重、只在 Web 场景才用的进扩展。
|
||||
|
||||
## 14.1 概览
|
||||
|
||||
| 能力 | 位置 | 典型函数 |
|
||||
|------|------|----------|
|
||||
| HTTP(S) 客户端 | `lib/net` | `http_get` / `http_post` / `http_request` |
|
||||
| Cookie 解析 | `lib/net` | `cookie_parse` |
|
||||
| multipart/form-data 解析 | `lib/net` | `multipart_parse` |
|
||||
| 网页应用 / 路由 / 静态 | `ext/web` | `web.page` / `web.app` |
|
||||
| SQLite 数据库 | `ext/web` | `web.db` |
|
||||
| 表单 | `ext/web` | `web.form` |
|
||||
| 登录鉴权(session) | `ext/web` | `web.auth` / `app.auth` |
|
||||
| WebSocket 客户端 / 端点 | `ext/web` | `web.ws` / `app.route_ws` |
|
||||
|
||||
```bash
|
||||
# 运行使用 ext/web 的程序前,先安装扩展
|
||||
marqdo ext add web
|
||||
```
|
||||
|
||||
## 14.2 HTTP 客户端(`lib/net`)
|
||||
|
||||
导入 `lib/net.mq.md`(中文 `lib/网络.mq.md`),用 `http_get` / `http_post` 发请求:
|
||||
|
||||
```markdown
|
||||
---
|
||||
import net:lib/net.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
*resp = > net.http_get url="https://api.example.com/status"*
|
||||
> print text=`resp`[^status]
|
||||
```
|
||||
|
||||
`http_post` 默认以 JSON 提交,可用 `content_type=` / `headers=` 覆盖:
|
||||
|
||||
```markdown
|
||||
*body = > net.http_post url="https://api.example.com/echo" body={"msg":"hi"}*
|
||||
> print text=`body`
|
||||
```
|
||||
|
||||
> **字典操作**:返回值是字典(如 `resp`),直接取元 `resp[^键]`,不要用 `json.get`。
|
||||
|
||||
### Cookie 解析
|
||||
|
||||
`cookie_parse` 把 `Cookie` 请求头或 `Set-Cookie` 响应头解析成列表:
|
||||
|
||||
```markdown
|
||||
*req = > net.cookie_parse text="session=abc123; theme=dark"*
|
||||
> print text=`req`[^1][^name] # session
|
||||
> print text=`req`[^1][^value] # abc123
|
||||
|
||||
*resp = > net.cookie_parse text="id=42; Path=/; HttpOnly; SameSite=Lax" is_response=True*
|
||||
> print text=`resp`[^1][^http_only] # True
|
||||
```
|
||||
|
||||
### multipart 解析
|
||||
|
||||
`multipart_parse` 解析 `multipart/form-data` 正文(给定 `boundary`):
|
||||
|
||||
```markdown
|
||||
*parts = > net.multipart_parse body=`body` boundary="----WebKitFormBoundary"*
|
||||
*field = parts[^1]*
|
||||
> print text=`field`[^name]
|
||||
```
|
||||
|
||||
## 14.3 网页应用(`ext/web`)
|
||||
|
||||
`ext/web` 用类 + 方法装配页面。导入 `web:ext/web/web.mq.md`(中文 `网页:ext/web/网页.mq.md`)。
|
||||
|
||||
### 页面、组件、主体
|
||||
|
||||
```markdown
|
||||
---
|
||||
import web:ext/web/web.mq.md
|
||||
---
|
||||
|
||||
# main
|
||||
|
||||
`首页` =
|
||||
|
||||
| 组件 | 样式 |
|
||||
|------|------|
|
||||
| nav.`导航` | shell.`顶栏` |
|
||||
|
||||
*page = > web.page title="我的站点" intro="<h1>你好</h1>"*
|
||||
*page = > `page`.compose_components components=`首页`*
|
||||
*html = > `page`.render*
|
||||
> print text=`html`
|
||||
```
|
||||
|
||||
### 应用 + 路由 + 监听
|
||||
|
||||
```markdown
|
||||
*app = > web.app page=`page` host=127.0.0.1 port=18081*
|
||||
*app = > `app`.route path="/about" page=`关于`*
|
||||
> web_listen app=`app`
|
||||
```
|
||||
|
||||
`listen` 提供 `/`、路由页、表单端点 `/_form/{id}`、可选静态目录与 `/admin`。
|
||||
|
||||
### 数据库(SQLite)
|
||||
|
||||
```markdown
|
||||
*store = > web.db url="sqlite:site.db"*
|
||||
> `store`.init name=articles fields=`字段表`
|
||||
> `store`.insert table=articles rows=`数据`
|
||||
*rows = > `store`.select table=articles limit=10*
|
||||
- [行](rows)
|
||||
> print text=`行`[^title]
|
||||
```
|
||||
|
||||
## 14.4 登录鉴权(session / cookie)
|
||||
|
||||
给 `/admin*` 加登录门禁:`app.auth` 挂用户表,未登录重定向到 `/admin/login`。
|
||||
|
||||
```markdown
|
||||
`管理员` =
|
||||
|
||||
| 行 | 用户名 | 密码 |
|
||||
|----|--------|------|
|
||||
| 1 | admin | secret |
|
||||
| 2 | 站长 | pw123 |
|
||||
|
||||
*app = > web.app page=`page` admin=True*
|
||||
*app = > `app`.auth users=`管理员` session_ttl=3600*
|
||||
> web_listen app=`app`
|
||||
```
|
||||
|
||||
`session_ttl` 是会话有效期(秒),过期后重新登录。
|
||||
|
||||
**独立鉴权工具** `web.auth`:登录、校验、登出(不依赖页面),返回 `{ok, session_id, username}`:
|
||||
|
||||
```markdown
|
||||
*auth = > web.auth users=`管理员` session_ttl=3600*
|
||||
*login = > `auth`.login username="admin" password="secret"*
|
||||
1. `login`[^ok]
|
||||
> print text=登录成功:`login`[^username]
|
||||
2. *
|
||||
> print text=登录失败
|
||||
|
||||
*sid = login[^session_id]*
|
||||
*check = > `auth`.check session_id=`sid`*
|
||||
> print text=`check`[^username]
|
||||
|
||||
> `auth`.logout session_id=`sid`
|
||||
```
|
||||
|
||||
## 14.5 WebSocket
|
||||
|
||||
`app.route_ws` 注册端点,`web.ws.connect` 单次请求–响应:
|
||||
|
||||
```markdown
|
||||
*app = > `app`.route_ws path="/live" echo=True*
|
||||
> web_listen app=`app`
|
||||
```
|
||||
|
||||
客户端(另开终端):
|
||||
|
||||
```markdown
|
||||
*ws = > web.ws timeout_sec=30*
|
||||
*echo = > `ws`.connect url="ws://127.0.0.1:18081/live" message="hi"*
|
||||
1. `echo`[^ok]
|
||||
> print text=`echo`[^messages]
|
||||
2. *
|
||||
> print text=连接失败:`echo`[^error]
|
||||
```
|
||||
|
||||
## 14.6 字典操作:用表格与取元,不用 `json.get`/`json.set`
|
||||
|
||||
Marqdo 用 **GFM 表格**构造字典、用 **脚注取元 `变量[^键]`** 读取字典——这是语言原生能力,是「代码即文档」的体现。**不要**用 `json.get` / `json.set` 读写本地字典(那只用于文本 ↔ 结构化的序列化,如 `json.parse` / `json.stringify`)。
|
||||
|
||||
构造字典(横表,≥2 列 + 1 行):
|
||||
|
||||
```markdown
|
||||
`配置` =
|
||||
|
||||
| 主机 | 端口 |
|
||||
|------|------|
|
||||
| 127.0.0.1 | 18081 |
|
||||
```
|
||||
|
||||
读取字典(取元):
|
||||
|
||||
```markdown
|
||||
> print text=`配置`[^主机] # 127.0.0.1
|
||||
> print text=`配置`[^端口] # 18081
|
||||
```
|
||||
|
||||
读取函数返回的字典字段,同样直接取元:
|
||||
|
||||
```markdown
|
||||
*login = > `auth`.login username="admin" password="secret"*
|
||||
> print text=`login`[^ok] # 而不是 json.get value=`login` key="ok"
|
||||
```
|
||||
|
||||
## 14.7 下一步
|
||||
|
||||
你已经掌握 Marqdo 的网络与 Web 能力。继续探索:
|
||||
|
||||
- [第 13 章:命令行工具](./13-命令行工具.md) —— `marqdo ext` 管理扩展
|
||||
- 设计文档:[`doc/design/ext-web-net.md`](../design/ext-web-net.md) —— 本波次网络扩展的完整设计与边界判定
|
||||
@@ -0,0 +1,94 @@
|
||||
# Marqdo 语法教程
|
||||
|
||||
> **代码即文档,文档即代码。** Marqdo 把 Markdown 的标记当作编程语法:同一个 `.mq.md` 文件既是给人读的文稿,也是给机器跑的程序。
|
||||
|
||||
本教程面向所有读者——从没写过代码的文档作者,到熟悉 Python 的工程师。每章都配有可直接运行的完整示例。
|
||||
|
||||
## 目录
|
||||
|
||||
### 第一部分 · 入门
|
||||
|
||||
| 章节 | 内容 | 你能学会什么 |
|
||||
|------|------|-------------|
|
||||
| [第 1 章:Marqdo 是什么](./01-入门.md) | 理念、安装、第一个程序、运行 | 写出并运行你的第一个 `.mq.md` 程序 |
|
||||
| [第 2 章:基本语法](./02-基本语法.md) | 文件结构、注释、标识符、字面量 | 看懂 `.mq.md` 里哪些是代码、哪些是注释 |
|
||||
|
||||
### 第二部分 · 变量与数据
|
||||
|
||||
| 章节 | 内容 | 你能学会什么 |
|
||||
|------|------|-------------|
|
||||
| [第 3 章:变量与赋值](./03-变量与赋值.md) | 绑定、变量引用、字符串 | 存取值,拼接文本 |
|
||||
| [第 4 章:输出与输入](./04-输出与输入.md) | `print` / `打印`、`input` / `输入` | 与用户交互 |
|
||||
| [第 5 章:运算符与比较](./05-运算符与比较.md) | 算术、比较、逻辑 | 计算与判断 |
|
||||
|
||||
### 第三部分 · 流程控制
|
||||
|
||||
| 章节 | 内容 | 你能学会什么 |
|
||||
|------|------|-------------|
|
||||
| [第 6 章:函数](./06-函数.md) | 定义、参数、返回值、函数结束 | 封装可复用逻辑 |
|
||||
| [第 7 章:条件分支](./07-条件分支.md) | `1.` `2.` 分支、else | 让程序根据条件走不同路线 |
|
||||
| [第 8 章:循环](./08-循环.md) | `-` 遍历、`-` while | 重复执行 |
|
||||
|
||||
### 第四部分 · 数据集合
|
||||
|
||||
| 章节 | 内容 | 你能学会什么 |
|
||||
|------|------|-------------|
|
||||
| [第 9 章:集合(表格)](./09-集合.md) | 列表、字典、记录、脚注取元 | 用 Markdown 表格组织数据 |
|
||||
|
||||
### 第五部分 · 面向对象与模块
|
||||
|
||||
| 章节 | 内容 | 你能学会什么 |
|
||||
|------|------|-------------|
|
||||
| [第 10 章:对象与方法](./10-对象与方法.md) | `#` 类型、构造、方法、继承 | 面向对象编程 |
|
||||
| [第 11 章:模块与导入](./11-模块与导入.md) | frontmatter、import、库路径、短名 | 组织大型项目 |
|
||||
|
||||
### 第六部分 · 进阶
|
||||
|
||||
| 章节 | 内容 | 你能学会什么 |
|
||||
|------|------|-------------|
|
||||
| [第 12 章:标准库](./12-标准库.md) | 内置函数、`lib/` 模块 | 直接使用官方能力 |
|
||||
| [第 13 章:命令行工具](./13-命令行工具.md) | `run` / `view` / `debug` / `catalog` | 运行、浏览、调试、发布 |
|
||||
| [第 14 章:网络与 Web 扩展](./14-网络与Web扩展.md) | `lib/net`、`ext/web`、鉴权、WebSocket | 构建 HTTP 客户端与网页应用 |
|
||||
|
||||
---
|
||||
|
||||
## 快速示例
|
||||
|
||||
一个完整的 Marqdo 程序长这样:
|
||||
|
||||
```markdown
|
||||
# main
|
||||
|
||||
> 问候 谁=World
|
||||
|
||||
## 问候
|
||||
+ `谁`
|
||||
|
||||
> print text=Hello, `谁`!
|
||||
|
||||
---
|
||||
|
||||
## 加一
|
||||
+ `n`
|
||||
|
||||
**n + 1**
|
||||
```
|
||||
|
||||
- `# main` —— 入口
|
||||
- `> 问候 谁=World` —— 调用函数(具名参数)
|
||||
- `## 问候` + `+ `谁`` —— 定义函数及其参数
|
||||
- `> print text=…` —— 输出(副作用,是普通函数)
|
||||
- `**n + 1**` —— 返回值
|
||||
- 单独一行 `---` —— 结束函数体
|
||||
|
||||
---
|
||||
|
||||
## 运行方式
|
||||
|
||||
```bash
|
||||
marqdo run 文件.mq.md
|
||||
```
|
||||
|
||||
更多运行、浏览、调试、发布方式见 [第 13 章](./13-命令行工具.md)。
|
||||
|
||||
> **提示**:语法宪法与精确定义见 [`doc/design/markdown-mapping.md`](../design/markdown-mapping.md);本教程是它的通俗讲解版。
|
||||
@@ -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)。
|
||||
Loaded 100 of 442 files, more files were not shown because too many files have changed in this diff.
Show more
Reference in new issue
Block a user