Compare commits

...
62 Commits
Author SHA1 Message Date
cflmyandCursor 68c4f8c822 release: v0.3.8 — Mid2 stdlib M7–M10
Ship calendar/URL/TOML/HTML/fs/stats plus GLOBAL_HOST restore;
bump Cargo, README, CHANGELOG, and release workflow highlights.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 10:08:59 +08:00
cflmyandCursor 784d5ec346 feat(stdlib): Mid2 M10 stats and log fields
Add thin mean/median/stdev and optional structured fields on log
lines; close Mid2 M7–M10 (zip skipped).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 09:42:13 +08:00
cflmyandCursor 955834e453 feat(stdlib): Mid2 M9 fs make_dirs, walk, and stat
Thicken lib/fs with recursive mkdir/rmdir-tree, metadata maps, and
depth-first walk; add gold tests and public demos.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 09:27:06 +08:00
cflmyandCursor 435f36b6e9 feat(stdlib): Mid2 M8 toml, html escape, and base32
Add read-only TOML subset parse, HTML escape/unescape, and RFC 4648
base32 on encoding; gold tests and public demos included.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 09:22:00 +08:00
cflmyandCursor 08c48f3acb feat(stdlib): Mid2 M7 datetime and url
Add calendar moments as {unix,zone,iso} maps and URL/query parse
helpers in lib/ with thin host_* forwards; gold and public demos.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 09:14:18 +08:00
cflmyandCursor ff1870cedc docs: Mid2 gap research and M7–M10 design/roadmap
Inventory stdlib gaps after Mid M1–M6 and lock Mid2 waves
(datetime/url, toml/html, fs++, optional stats).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 09:04:29 +08:00
cflmyandCursor 5e51ee1bb2 fix(host): restore GLOBAL_HOST after nested plugin calls
Nested call_registered was clearing the process-wide host pointer to null,
so web_listen lost context for later HTTP invoke rounds after an inner ABI call.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-08 10:40:27 +08:00
cflmyandCursor 55f1a37b3d chore: sync Cargo.lock package versions to 0.3.7
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 22:21:54 +08:00
cflmyandCursor 58dff0a1e9 release: v0.3.7 — Hosting H1–H4 (proxy, invoke, MCP stdio)
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 22:18:43 +08:00
cflmyandCursor fc543f1ca5 feat(web,agent): hosting H1–H4 — proxy, invoke, MCP stdio, cross-module db
Close GAP-01–05 with ext/web streaming reverse proxy and HTTP→## invoke,
transitive object method lookup, corpus_search plugin ensure, and agent MCP
server stdio so downstream apps can drop Python side relays.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 22:14:51 +08:00
cflmyandCursor 2e068e66d4 release: v0.3.6 — Mid stdlib M1–M6
Ship mid-tier libraries through log/uuid, bump Cargo/README/CHANGELOG, and refresh the Release workflow highlights.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 20:55:26 +08:00
cflmyandCursor a4c346d4a2 fix(agent,llm): avoid host_* writeback and tolerate SSE reasoning
Alias writeback as wb so the writeback= param does not shadow lib calls; ignore unknown stream event types so live SSE models keep working.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 20:52:44 +08:00
cflmyandCursor fe14d1f7e3 fix(agent): route writeback through lib instead of host_*
ext/** must not call host_*; use writeback.record / 自写回.写回 so the host-boundary gold passes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 20:40:24 +08:00
cflmyandCursor f4b39dfe80 feat(stdlib): Mid M6 log levels and UUID v4
Close the mid-tier stdlib waves with filtered one-line logs and cryptographic UUID minting in lib/, plus golds and public demos.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 20:37:28 +08:00
cflmyandCursor 7d86ed1d9c feat(stdlib): Mid M5 list algorithms and cli.parse
Thicken table with sort/unique/chunk/zip/flatten and add lib/cli
flag parsing, with golds and public demos.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 20:32:58 +08:00
cflmyandCursor 506de65dae feat(stdlib): Mid M4 csv and thickened text helpers
Add lib/csv parse/stringify and expand lib/text with contains,
replace, case, pad, and related golds plus public demos.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 20:27:19 +08:00
cflmyandCursor 08384c7540 feat(stdlib): Mid M3 hash digests and secure tokens
Add lib/hash and lib/secrets (EN/ZH) with known-vector golds,
getrandom-backed tokens, and public demos.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 20:15:36 +08:00
cflmyandCursor 94ae6713aa feat(stdlib): Mid M2 path algebra and fs copy/move/temp
Add lib/path (EN/ZH) and thicken fs with sandboxed copy_file, move,
and make_temp, with golds and public demos.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 20:10:12 +08:00
cflmyandCursor 838a2b425a feat(stdlib): Mid M1 regex and encoding libraries
Add lib/re and lib/encoding (EN/ZH) backed by host_re_* and
host_encoding_*, with golds, public demos, and design docs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 20:02:43 +08:00
cflmyandCursor 1a5ee57a6f docs(stdlib): plan mid-tier standard library waves M1–M6
Define mid-stdlib admission rules and a phased roadmap so general
primitives land in lib/ instead of ABI plugins.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 19:53:44 +08:00
cflmyandCursor d539e6b96b fix(pages): build linalg plugin for public site CI
public/features/07-linalg needs marqdo_plugin_linalg; pages only built quantum.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 19:35:52 +08:00
cflmyandCursor 3ade036d34 feat(linalg): F3 formula-doc public pages and T_ascii
Ship runnable public how-to pages, T_ascii/转置文本 one-step display,
explicit auto-simplify, and mark formula-doc F1–F3 complete.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 16:13:22 +08:00
cflmyandCursor f3c49e86ae feat(linalg): F2 declare from GFM table and lecture example
Add la.declare for batch MatrixSymbol from @-record tables, ship
examples/linalg-transpose, and mark formula-doc F2 done.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 15:52:46 +08:00
cflmyandCursor b2401b8458 docs(linalg): formula-doc design and F1 display auto-simplify
Lock the run-implies-correct authoring model, default-simplify ascii/latex/show
(with raw= escape), and add linalg-doc-smoke for (AB)^T identity.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 15:50:33 +08:00
cflmyandCursor 51bb8767e3 feat(linalg): matrix infix ops and # matrix methods
Dispatch +/−/* to the linalg plugin for matrix values, retag for EN/ZH
method chains, and expand # matrix with T/simplify/ascii-style methods.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 15:13:47 +08:00
cflmyandCursor c0fbe9b182 feat(linalg): L6 lstsq, norms, complex dtype, draw themes
Add QR/SVD least squares, norm/cond/rank, complex dense Frobenius
baseline, and light/dark/bw draw themes aligned with quantum Q8.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 14:47:30 +08:00
cflmyandCursor 01287d9e7e feat(linalg): L5 examples, public feature pages, and skill docs
Ship SVD / least-squares examples, heatmap-hinton draw paths, coerce
dense factors into MatExpr ops, and document ext/linalg in skill/README.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 14:36:17 +08:00
cflmyandCursor 70fb2fbfb2 feat(linalg): L4 factorize and structure SVG draw
Add LU/QR/SVD/eig/chol dense factorizations, teaching structure SVGs,
LU reuse via solve(factor=), and linalg-factor-smoke gold.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 14:31:44 +08:00
cflmyandCursor b6f116108c feat(linalg): L3 block collapse and lazy Kronecker
Add Block/Kron MatExpr, collapse for Block*Block, R7 flatten,
explicit assembly/kronecker, and linalg-block-kron smoke.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 14:22:08 +08:00
cflmyandCursor 03aca7cdac feat(linalg): L2 dense explicit, det, trace, and solve
Add dense kernels with element limits, from_formula for $$ matrices,
and linalg-basic-smoke covering 2×2 det/trace/solve/explicit.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 14:16:16 +08:00
cflmyandCursor 96da88e168 feat(linalg): L0–L1 formula-first MatExpr plugin
Add plugins/linalg with symbol/mul/transpose/inv simplify (R1–R5),
EN/ZH L1, CATALOG/ext add wiring, release native assets, and smokes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 14:10:54 +08:00
cflmyandCursor b6cceab218 docs(linalg): design formula-first linear algebra extension
Add research, design, and roadmap for ext/linalg; cross-link from
stdlib-math and quantum Q7 so classic MatExpr stays out of lib/math.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-07 10:53:56 +08:00
cflmyandCursor 95b16be714 release: v0.3.5 — prebuilt native plugins for ext add
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 17:08:19 +08:00
cflmyandCursor d31ad79bc0 feat(ext): prebuilt native plugins and ext add download
Ship Release native zips and let ext add fetch L1/native without a local Rust toolchain.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 16:57:43 +08:00
cflmyandCursor 5745805a5d docs: blank line before v0.3.3 in CHANGELOG
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 14:20:31 +08:00
cflmyandCursor 590f7a58fa release: v0.3.4 — ext/web customization C0–C4
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 14:16:41 +08:00
cflmyandCursor 027b19c5db feat(web): C4 conditional nav with when and media columns
Filter nav/sidebar/footer by auth/guest/hide and emit responsive media CSS; stamp _logged_in from session on listen.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 13:54:53 +08:00
cflmyandCursor 7670673a39 feat(web): C3 style cell strict checks and head defer/version
Warn or reject numeric CSS values from bare `/` division; support script defer/async/version and page/app asset_version for cache busting.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 13:43:35 +08:00
cflmyandCursor 824b9bf607 docs(web): mark C1 auth-gates solution as landed
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 12:49:07 +08:00
cflmyandCursor 155183eb30 feat(web): C2 shell_css modes and page layout presets
Split injected shell CSS into vars/layout/widgets with full|minimal|off, add stacked/bare/rail layouts, and stop forcing has-sidebar when authors opt out.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 12:48:50 +08:00
cflmyandCursor b10a84466b feat(web): C1 segment-boundary gates with on_deny and exclude
Make auth/admin gates use path segment prefixes, configurable redirect vs 403, and login_path exclusion so /admin-publish and /desk/login are not mis-matched.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 12:38:44 +08:00
cflmyandCursor 0aa0f47a9d feat(web): C0 release /admin when disabled; configurable admin_prefix
Stop mounting reserved admin routes when admin=False, nest CRUD under a
configurable prefix, and honor login/logout redirects so custom desks need no JS bypass.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 11:50:11 +08:00
cflmyandCursor 5f91be7c21 docs(web): catalog customization limits and C0–C4 fix designs
Capture route/shell/auth/theme pain points from real sites and lock per-item solution docs before plugin work.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 11:38:20 +08:00
cflmyandCursor e3e2cfa9d1 fix(agent): writeback param shadow + Wave B1 dump/harness
step/plan writeback=True shadowed lib/writeback; persist via host_writeback_record. Align ZH context builder, add dump_step_context, lock offline harness.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 11:24:50 +08:00
cflmyandCursor d1b4e62d4d feat(agent): Wave B0 constitution demos + harness
Lock code-as-doc / call_site / OKF as first-class: reorder step
context, ship agent-pong and okf-flywheel examples, offline harness,
and skill/docs refresh. Dev LLM template via .env.example only.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 11:17:25 +08:00
cflmyandCursor ff1b846b73 release: v0.3.3 — browser author-zero-JS routes D/E/F
Ship host effects through media APIs, lib/browser + GFM authoring,
and marqdo-dev skill; bump crate versions and release docs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 10:13:28 +08:00
cflmyandCursor ad47d4a0d2 chore: gitignore browser-media wasm build artifact
Keep the example source and bridge; rebuild wasm via marqdo wasm build.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 10:06:03 +08:00
cflmyandCursor c080b79c5b feat(wasm): route F host media APIs + GFM-first browser authoring
Ship bridge effects for file/canvas/audio/observers/drag-drop with
browser-media demo; add lib/browser and marqdo-dev skill so clients
use tables/helpers instead of json.set glue.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 10:05:46 +08:00
cflmyandCursor f19f614e0d feat(wasm): finish route E gaps — multi-DOM, cookies, app CRUD/net
querySelectorAll patches, add/remove_class, append_html, remove,
clipboard/download, cookie storage; browser-app list delete + fetch_all/ws
panel. Mark E completed; plan F for file/canvas/media.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 09:11:36 +08:00
cflmyandCursor 8fbf617e05 feat(wasm): route E host effects for author-zero-JS frontend
Expand the official bridge with style/focus/list/navigate/storage/ws/
fetch_all/interval effects; relax the design rule to forbid only
author-written JS. Add browser-app demo and L1 list_html/dom_patch keys.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 09:06:21 +08:00
cflmyandCursor a9d30cdf4a feat(wasm): route D zero-author-JS frontend + plan route E
Auto-mount via bridge mount/data-mq and client_embed; expand DOM/form
effects; drop hello loader JS; add web-client-site. Document that C+D
cover mid-size interactivity but not most JS apps—route E covers
routing, storage, lists, WebSocket, and richer DOM/timers.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 08:46:05 +08:00
cflmyandCursor 4c27c8afeb docs(release-skill): note gh auth via git credential fill
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 11:26:21 +08:00
cflmyandCursor 9d591674aa chore: sync Cargo.lock versions for v0.3.2
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 11:18:29 +08:00
cflmyandCursor e40d21760a release: v0.3.2 — browser WASM route C + release skill
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 11:18:13 +08:00
cflmyandCursor 2445c290c9 feat(wasm): finish route C — bridge package, smoke, site embed L1
Canonical marqdo-bridge.js ships with wasm build, Node ABI smoke covers
boot/call, and ext/web gains client_embed for head/static mounting.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 11:05:43 +08:00
cflmyandCursor 04890e0c73 feat(wasm): C5 release-wasm size profile and build reporting
Add opt-level=z/LTO strip profile, print KiB from marqdo wasm build,
optional wasm-opt, and document tree-only browser sessions.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 10:58:42 +08:00
cflmyandCursor ab52db2037 feat(wasm): C4 async fetch/after effects with bridge continuations
Accept ADR 0003: handlers return fetch/after maps; the official bridge
runs Promise/timer work and resumes via mq_call. Add fetch.mq.md demo.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 10:53:11 +08:00
cflmyandCursor aac896b044 feat(wasm): C2/C3 session boot, wire events, and interact demo
Add BrowserSession with shared entry env, mq_boot/mq_call exports,
marqdo wasm build, and a counter page driven only by counter.mq.md.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 10:48:46 +08:00
cflmyandCursor fb037022ba docs(wasm): document raw mq_* ABI for C1 exports
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 10:38:15 +08:00
cflmyandCursor a75b7a1c87 feat(wasm): C0/C1 browser Marqdo interpreter on wasm32
Feature-gate host/CLI deps for wasm-core, add run_source, and ship
crates/marqdo-wasm with a raw mq_run ABI plus examples/browser-hello.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 10:37:44 +08:00
cflmyandCursor f2fd4fb34e docs: lock browser Marqdo WASM plan (ADR 0002, C0–C5)
Accept route C: ship the interpreter/VM on wasm32 with a thin JS host
bridge, not transpile-to-JS. Add design, roadmap, and cross-links.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 10:06:56 +08:00
cflmyandCursor 2079577314 fix(web): admin layout, ext add native, keyframes; document quoted CSS ratios
Widen admin main/table display, ensure marqdo ext add builds/copies the
native plugin before mq install, and emit valid @keyframes from style
tables. Prefer quoted cells like "16/9" for CSS values that contain /.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 09:59:03 +08:00
302 changed files with 31274 additions and 793 deletions

No files matched your search

+144
View File
@@ -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)
+166
View File
@@ -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`.
+307
View File
@@ -0,0 +1,307 @@
# Marqdo release — reference
Companion to [SKILL.md](SKILL.md). Use during a release; keep SKILL short.
## Detect versions (commands)
```bash
# From repo root
python3 .cursor/skills/marqdo-release/scripts/detect_version.py
# or manually:
git fetch --tags origin 2>/dev/null || true
echo "Cargo: $(sed -n 's/^version = \"\(.*\)\"/\1/p' Cargo.toml | head -1)"
echo "wasm: $(sed -n 's/^version = \"\(.*\)\"/\1/p' crates/marqdo-wasm/Cargo.toml | head -1)"
echo "tags: $(git tag -l 'v*' --sort=-v:refname | head -3 | tr '\n' ' ')"
gh release list --limit 3 2>/dev/null || true
```
**SemVer guidance for the ask (do not choose for the user):**
| Kind | When |
|------|------|
| patch `x.y.(z+1)` | Fixes, docs, no public API / MQ surface break |
| minor `x.(y+1).0` | New features (WASM route C, new ext APIs) backward compatible |
| major `(x+1).0.0` | Breaking MQ / CLI / plugin ABI |
## Asset matrix (CI tag `v*`)
Produced by `.github/workflows/release.yml` on **windows-latest**:
| Asset | Role |
|-------|------|
| `marqdo-VER-x86_64-pc-windows-msvc.exe` | CLI (stdlib embedded) |
| `marqdo-VER-x86_64-pc-windows-msvc.zip` | `marqdo.exe` + `lib/` |
| `marqdo-VER-stdlib.zip` | `lib/` only |
| `marqdo-VER-ext.zip` | Official `ext/` L1 |
| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Prebuilt Windows plugins (`native/*.dll`) |
| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Prebuilt Linux plugins (`native/lib*.so`) |
| `marqdo-VER-source.zip` | `git archive` of tagged commit |
| `marqdo-VER.vsix` | VS Code / Cursor (from branch `vscode-extension`) |
| `marqdo-VER-public.zip` | Static user docs (`marqdo view output public`) |
Not CI-uploaded (document in notes): Linux/macOS build from source; WASM via `marqdo wasm build` → `dist/wasm/`.
## Doc sync checklist (Phase 2 detail)
### CHANGELOG.md
1. Ensure `## Unreleased` lists everything shipping.
2. Rename to `## vVER — YYYY-MM-DD` (use release day in Asia/Shanghai unless user says otherwise).
3. Add a short **Highlights** subsection (install snippet + 3–6 bullets).
4. Insert empty:
```markdown
## Unreleased
### Added
### Fixed
### Changed
```
### README.md
Update every user-visible version pin, typically:
- Section title `## 现状(vVER)`
- `### 如何使用最新 Marqdo(vVER)`
- `git checkout vVER`
- Release URL `…/releases/tag/vVER`
Keep install / `ext add` / plugin build instructions accurate for this release.
### `.cursor/skills/marqdo/SKILL.md`
- Sync hard rules / feature bullets that this release changes (e.g. WASM, web).
- Do **not** dump full CHANGELOG into the skill.
- If release-only process changed, point to `.cursor/skills/marqdo-release/`.
### `public/` (author Markdown sources)
User tutorials under `public/` (not generated HTML). Update when:
- New CLI (`marqdo wasm …`, `ext add`, `version`)
- New tutorials (browser hello, web client embed)
- Version badges / “requires vVER” lines
Then regenerate HTML for zip/pages:
```bash
./scripts/build-public.sh
# Windows: powershell -File ./scripts/build-public.ps1
```
HTML under `public/**/*.html` is typically gitignored — zip still ships from CI `marqdo view output public`.
### Workflow stub
Edit `.github/workflows/release.yml` `body:` **Highlights** so the first auto body matches this tag (agent still replaces with full notes via `gh release edit`).
### Roadmaps / ADRs
If this release closes a wave: set status Completed in `doc/roadmap/*`; leave ADRs immutable (link from CHANGELOG).
## Extension checklist (Phase 3 detail)
Branch policy: `doc/design/vscode-extension-commit.md`.
```bash
git fetch origin vscode-extension
git checkout vscode-extension
# edit vscode-extension/package.json version → VER
# npm ci && npm run compile
git add vscode-extension/
git commit -m "$(cat <<'EOF'
vscode-extension: bump to VER for release
EOF
)"
git push origin vscode-extension
git checkout main
```
Local VSIX only (fallback):
```bash
git fetch origin vscode-extension
git checkout origin/vscode-extension -- vscode-extension
(cd vscode-extension && npm ci && npm run compile && npx @vscode/vsce package --no-dependencies -o "../dist/marqdo-VER.vsix")
# cleanup ignored tree if desired
gh release upload "vVER" "dist/marqdo-VER.vsix" --clobber
```
## Defaults (mirror of SKILL)
| Setting | Default |
|---------|---------|
| Sync `vscode-extension` to `VER` | yes |
| Push main + annotated tag immediately | yes |
| Release notes | 中英双语 |
| Skip VSIX / docs-only / deploy pages | no |
Phase 0 asks **only** for the next version unless the user wants overrides.
## Notes template (中英双语 — default)
Save as `/tmp/marqdo-vVER-notes.md` then:
```bash
gh release edit "vVER" --notes-file /tmp/marqdo-vVER-notes.md
```
```markdown
## Marqdo vVER
### 亮点 / Highlights
- **中文** … / **EN** …
- …
### 安装 / Install
```bash
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout vVER
cargo build --release
./target/release/marqdo version
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
marqdo ext add web && marqdo ext add agent && marqdo ext add quantum
# 中文 id:网页 / 智能体 / 量子
```
**浏览器 WASM / Browser WASM**
```bash
marqdo wasm build
# → dist/wasm/marqdo_wasm_bg.wasm + marqdo-bridge.js
# examples: examples/browser-hello/
```
### 破坏性变更 / Breaking changes
- 无 / None
- …
### 下载 / Downloads
| Asset | 内容 / Contents |
|-------|-----------------|
| `marqdo-*-windows-msvc.exe` | CLI(内置 stdlib) |
| `marqdo-*-windows-msvc.zip` | exe + `lib/` |
| `marqdo-*-stdlib.zip` | 仅 `lib/` |
| `marqdo-*-ext.zip` | 官方 `ext/` |
| `marqdo-*-source.zip` | 源码快照 |
| `marqdo-*.vsix` | VS Code / Cursor 扩展 |
| `marqdo-*-public.zip` | 用户文档站 |
扩展源码分支 / Extension branch: **`vscode-extension`** ([policy](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension-commit.md)).
### 链接 / Links
- [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md)
- [README](https://github.com/cflmy/marqdo/blob/main/README.md)
```
## Proxy & auth (network recovery)
Symptoms seen in this project: broken local proxy on `127.0.0.1:7890`, TLS failures, `gh` needing token, Cursor sandbox blocking git/gh.
### Diagnose
```bash
env | grep -iE 'proxy|PROXY' || true
curl -sI https://github.com | head -5
gh auth status
```
### Fix order
1. **Unset bad proxy** if connection refused:
```bash
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy
```
2. **Set a working proxy** only if the user provides one (or known working):
```bash
export HTTPS_PROXY=http://HOST:PORT
export HTTP_PROXY=http://HOST:PORT
```
3. **Agent Shell**: retry `git push` / `gh` with `required_permissions: ["all"]` (and `full_network` if needed).
4. **`gh` auth**: if `gh auth status` fails, ask user to `gh auth login` or set `GH_TOKEN` / `GITHUB_TOKEN` for the session — **never commit tokens**. Fallback used in this repo: load password from `git credential fill` (`protocol=https` / `host=github.com`) into `GH_TOKEN` for the session only, then delete the temp env file.
5. **Git remote**: prefer `https://github.com/cflmy/marqdo.git`; SSH needs keys.
6. **Partial upload**:
```bash
gh release upload "vVER" dist/FILE --clobber
```
7. **Re-run CI** without retagging (if tag already correct):
```bash
gh workflow run Release --ref "vVER" # only if workflow_dispatch exists; else fix + new patch tag
```
Current Release workflow is **tag-push only**. Red CI after tag → fix on `main`, then either new patch tag or **user-approved** delete+recreate tag (dangerous; prefer patch).
## Local Windows fallback
```powershell
powershell -File ./scripts/release-full.ps1 -Tag vVER -Upload
# -SkipVsix / -SkipPublic / -DeployPages as needed
```
Also: `scripts/release-windows.ps1`, `scripts/publish-release.py` if present.
## Commit message style
```text
release: vVER — <highlight>
```
Extension:
```text
vscode-extension: bump to VER for release
```
## Pre-tag test suggestions
Minimum:
```bash
cargo test --test gold structure_hello
./target/release/marqdo version # after cargo build --release
```
Stronger (time permitting):
```bash
cargo test --test gold
cargo test -p marqdo-wasm -- --nocapture # if wasm tests exist
# optional Node: node tests/wasm/smoke.mjs after marqdo wasm build
```
## Ask-user prompt (copy)
```text
版本探测结果:
- Cargo.toml: A.B.C
- crates/marqdo-wasm: …
- 最新 git tag: v…
- 最新 GitHub Release: v…
- CHANGELOG Unreleased: 有 / 无(摘要:…)
请指定下一个版本号(例如 0.3.2)。
默认(无需确认):同步 vscode-extension 同号、立刻 push tag 发版、发布说明中英双语。
若要改默认请一并说明。
```
+76
View File
@@ -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())
+50 -10
View File
@@ -4,10 +4,11 @@ description: >-
Author and edit Marqdo programs (.mq.md): Markdown markers are executable
syntax (functions, calls, statements, returns, control flow). Use when writing
or modifying .mq.md files, teaching Marqdo, generating Marqdo from prose,
importing lib/* or ext/web or ext/quantum, running marqdo CLI, building dynamic
sites with ext/web, quantum circuits with ext/quantum, or when the user
mentions Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, or
quantum/量子 extension.
importing lib/* or ext/web or ext/quantum or ext/linalg, running marqdo CLI,
building dynamic sites with ext/web, quantum circuits with ext/quantum,
formula-first linear algebra with ext/linalg, or when the user mentions
Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, quantum/量子,
or linalg/线性代数 extension.
---
# Marqdo development
@@ -16,6 +17,10 @@ Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation a
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number.
## Hard rules (do not violate)
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
@@ -24,9 +29,12 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are **variables** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed.
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division.
8. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug.
## Markup → meaning (v0.2)
@@ -134,13 +142,27 @@ import clock:lib/time.mq.md
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — document-driven agents: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)); **`ext/web`** — dynamic sites (W0–W7 + P3 complete; see below); **`ext/quantum`** — circuits + Q7 density/viz + Q8 themed SVG (see below).
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum|linalg` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below); **`ext/linalg`** — formula-first linear algebra (see below).
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`).
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
Stdlib map: [reference.md](reference.md).
## Official extension: `ext/agent` (document-driven)
Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --release -p marqdo_plugin_agent`.
**Constitution (do not dilute):**
1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag.
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only.
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import).
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
## Official extension: `ext/web` (dynamic sites)
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin first: `cargo build --release -p marqdo_plugin_web`.
@@ -172,11 +194,11 @@ data/ # sqlite runtime (gitignore)
**Core objects (EN / ZH):** `# page`/`页面`, `# style`/`样式`, `# db`/`数据库`, `# form`/`表单`, `# app`/`应用`, `# auth`/`鉴权`, `# cache`/`缓存`, `# storage`/`存储`.
**Typical flow:** `db.init` → `page.compose_components` + `page.compose_main` → `page.head` / `page.images` / `page.meta` → `app` with `route` / `static` / `icons` / `configure` / `listen`.
**Typical flow:** `db.init` → `page.compose_*` → `app` + `static` / `listen`. Client: `marqdo wasm build -o static` + `web.client_embed source="/static/client.mq.md"` — **no author JS**; bridge may implement rich host effects ([browser-wasm-e.md](../../doc/roadmap/browser-wasm-e.md) · [browser-app](../../examples/browser-app/)).
**Shipped surface (W0–W7 + P3 + W8):** 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`).
**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/).
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).
@@ -204,6 +226,19 @@ Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --relea
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
## Official extension: `ext/linalg` (formula-first LA)
Install: `marqdo ext add linalg` (ZH id: `线性代数`). Build: `cargo build --release -p marqdo_plugin_linalg`, then **`marqdo ext add linalg` again** so view loads the new native lib.
- EN: `import la:ext/linalg/linalg.mq.md`
- ZH: `导入 la:ext/linalg/线性代数.mq.md`
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; prefer top-level `la.symbol` (not `matrix.symbol` without a receiver); quote `kind=` strings; dense `explicit` / factorize obey size guards.
APIs (EN): `symbol` → `# matrix`;中缀 `+`/`-`/`*`;方法 `` `A`.T `` / ``.simplify`` / ``.ascii`` · `from_formula` / `explicit` / `factorize` / `draw` · `lstsq` / `norm` / `cond` / `rank`.
Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../../examples/linalg-least-squares/). Design: [ext-linalg.md](../../doc/design/ext-linalg.md) · formula-doc: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
## AI authoring workflow
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
@@ -225,11 +260,14 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
| Forgetting `---` after nested `##` helper | Add `---` / `***` / `****` |
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
| `json.set` / `json.append` to build maps or lists | GFM tables; sparse `table.put`; named helpers (`browser.*`, `web.*`) |
| `json.set` to build page parts | GFM tables + `page.compose_*` / `web.page` methods |
| Import `json` for every browser handler | `import browser:lib/browser.mq.md` + tables ([marqdo-dev](../marqdo-dev/SKILL.md)) |
| Mix `web.page` and `网页.页面` in one file | One import language per `.mq.md` |
| Call `host_web_*` from `ext/web` | Use `# app` / `# db` methods; plugin ABI only |
| Call `host_*` from `ext/quantum` | Use `# circuit` / `# density` methods; plugin ABI only |
| Bare `kind=hinton` inside `*…*` | `kind="hinton"` — quote text literals |
| Call `host_*` from `ext/linalg` | Use `la.*` L1 wrappers; plugin ABI only |
| Bare `kind=eig` inside `*…*` | `kind="eig"` — quote text literals |
| Bare `theme=dark` inside `*…*` | `theme="dark"` — quote; ZH `主题="dark"` |
| Rebuild plugin but skip `ext add` | `cargo build -p marqdo_plugin_quantum` then `marqdo ext add quantum` (or set `MARQDO_QUANTUM_PLUGIN`) |
@@ -241,6 +279,8 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
- [ ] `# main` exists when the file is an entry program
- [ ] Nested functions ended with `---` / `***` / `****` when needed
- [ ] Imports and call names share the same language file
- [ ] Data shaped as **GFM tables** (or short helpers) — no `json.set` / `json.append` glue
- [ ] Web sites: tables + web classes only (no JSON glue); `data/` gitignored
- [ ] Browser client: `lib/browser` + tables when returning effects
- [ ] Quantum draw: quote `kind=` / `theme=`; rebuild plugin → `ext add quantum` before view
- [ ] `marqdo run` succeeds (or errors addressed)
+87
View File
@@ -78,6 +78,7 @@ Greeting via a nested function:
> print text=`果`
```
## 6b. Map table + footnote get
```markdown
@@ -109,6 +110,31 @@ Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of ma
*名 = 订单[^1][^品名]*
```
## 6c. Browser effects — tables + lib/browser (not json.set)
```markdown
---
import browser:lib/browser.mq.md
---
# main
`wire` =
| @ | 选择器 | 事件 | 调用 |
|---|--------|------|------|
| 1 | "#bump" | click | bump |
**`wire`**
## bump
*`count` = count + 1*
*`label` = > str count*
**> browser.set_text sel="#count" text=label**
```
Do **not** build effect maps with `json.set` chains. See [marqdo-dev](../marqdo-dev/SKILL.md).
## 7. Import text stdlib
```markdown
@@ -123,6 +149,39 @@ import text:lib/text.mq.md
> print text=`parts`
```
## 7b. Mid M1 — regex + encoding (no plugin)
```markdown
---
import re:lib/re.mq.md
import enc:lib/encoding.mq.md
---
# main
*`ok` = > re.is_match text="a@b.c" pattern="@"*
*`b64` = > enc.base64_encode text="hi"*
> print text=`ok`
> print text=`b64`
```
## 7c. Mid M6 — log + uuid
```markdown
---
import log:lib/log.mq.md
import uuid:lib/uuid.mq.md
---
# main
> log.info text="start"
> log.set_level level="debug"
> log.debug text="detail"
*id = > uuid.v4*
> print text=`id`
```
## 8. Comment paragraphs (blank-line rule)
```markdown
@@ -300,3 +359,31 @@ import quantum:ext/quantum/quantum.mq.md
- Full lab: `examples/quantum-entanglement/`. Bell-only: `examples/quantum-bell/`.
- `theme="dark"|"light"|"bw"` (default dark) on `circuit` / `probs` / `bloch`. Quote `kind=` / `theme=`.
- After rebuilding the plugin: `marqdo ext add quantum` so view loads the new native lib.
## 15. Linear algebra (ext/linalg)
```markdown
---
import la:ext/linalg/linalg.mq.md
---
# main
*`A` = > la.symbol name="A" rows=2 cols=2*
*`B` = > la.symbol name="B" rows=2 cols=2*
*`C` = `A` + `B`*
*`P` = `A` * `B`*
*`s` = > `P`.T.simplify* <!-- prefer: *`Pt` = > `P`.T* then simplify -->
```
Prefer:
```markdown
*`env` = > la.declare table=`shapes`*
*`P` = env[^A] * env[^B]*
*`t` = > `P`.T_ascii*
```
- Infix `+` / `-` / `*`;`ascii` / `T_ascii` 默认化简(`raw=True` 可关)。
- Formula-doc design: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
- Examples: `examples/linalg-transpose/`, `examples/linalg-svd/`, `examples/linalg-least-squares/`.
+27 -4
View File
@@ -12,8 +12,8 @@ marqdo view PATH # docs browser, default port 7429
marqdo debug PATH # debugger UI, default port 7430
marqdo catalog PATH -o .marqdo
marqdo ext list
marqdo ext add llm|agent|web|quantum
marqdo ext remove llm|agent|web|quantum
marqdo ext add llm|agent|web|quantum|linalg
marqdo ext remove llm|agent|web|quantum|linalg
```
Diagnostics look like `path:line:col: message` (1-based line/col).
@@ -44,18 +44,29 @@ Import one file; use **that** file’s function names.
|-----------|-----------|-------------------------|
| `lib/text.mq.md` | `lib/文本.mq.md` | text helpers / 去空白·拆分·拼接… |
| `lib/table.mq.md` | `lib/表.mq.md` | `put`/`改` + list/map(见 `doc/design/stdlib-table.md`) |
| `lib/re.mq.md` | `lib/正则.mq.md` | Mid:`is_match`/`find`/`replace`/… |
| `lib/encoding.mq.md` | `lib/编码.mq.md` | Mid:base64/hex |
| `lib/path.mq.md` | `lib/路径.mq.md` | Mid:join/normalize/… |
| `lib/hash.mq.md` | `lib/哈希.mq.md` | Mid:sha256/hmac/… |
| `lib/secrets.mq.md` | `lib/机密.mq.md` | Mid:token_hex/urlsafe |
| `lib/csv.mq.md` | `lib/逗号表.mq.md` | Mid:parse/stringify |
| `lib/cli.mq.md` | `lib/命令行.mq.md` | Mid:`parse` flags |
| `lib/log.mq.md` | `lib/日志.mq.md` | Mid:level-filtered one-line logs |
| `lib/uuid.mq.md` | `lib/标识.mq.md` | Mid:UUID v4 |
| `lib/browser.mq.md` | `lib/浏览器.mq.md` | WASM client effect helpers(GFM + `set_text`/`canvas`/…;见 marqdo-dev) |
| `lib/fs.mq.md` | `lib/文件.mq.md` | filesystem |
| `lib/sys.mq.md` | `lib/系统.mq.md` | process / cwd / load_dotenv |
| `lib/plugin.mq.md` | `lib/插件.mq.md` | load native ABI plugins (`doc/design/ext-abi.md`) |
| `lib/time.mq.md` | `lib/时间.mq.md` | time/format |
| `lib/net.mq.md` | `lib/网络.mq.md` | HTTP(S) helpers (+ optional headers) |
| `lib/json.mq.md` | (see design) | JSON (+ `quote`) |
| `lib/json.mq.md` | (see design) | **parse / stringify / quote only** — not a dict builder |
| `lib/math.mq.md` | `lib/数学.mq.md` | num, trig, random, formula, plot |
| `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks |
| `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods |
| `ext/agent.mq.md` | `ext/智能体.mq.md` | agent **framework** (layout now; LLM orchestration roadmap in `ext-agent.md`) |
| `ext/agent.mq.md` | `ext/智能体.mq.md` | document-driven **step** / **plan** + OKF;示例 `examples/agent-pong` · `agent-okf-flywheel`;Wave B:[agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) |
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | dynamic sites — see **ext/web** section below |
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below |
| `ext/linalg/linalg.mq.md` | `ext/linalg/线性代数.mq.md` | formula MatExpr + factorize/draw — see **ext/linalg** below |
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
@@ -97,6 +108,16 @@ Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p
Examples: `examples/quantum-bell/`, `examples/quantum-entanglement/`. Design: `doc/design/ext-quantum.md` · Q7: `doc/design/ext-quantum-q7.md` · Q8: `doc/design/ext-quantum-viz-style.md`.
## ext/linalg (formula-first linear algebra)
Install: `marqdo ext add linalg` (`线性代数`). Native: `cargo build --release -p marqdo_plugin_linalg`, then re-run `ext add`.
| EN import | ZH import | Notes |
|-----------|-----------|-------|
| `ext/linalg/linalg.mq.md` | `ext/linalg/线性代数.mq.md` | Top-level `symbol`/`mul`/`factorize`/`draw` |
Examples: `examples/linalg-svd/`, `examples/linalg-least-squares/`. Design: `doc/design/ext-linalg.md` · formula-doc: `doc/design/ext-linalg-formula-doc.md` · roadmap: `doc/roadmap/ext-linalg.md`.
## Formula + plot (math)
```markdown
@@ -177,4 +198,6 @@ See `doc/design/call-arguments.md`.
| `doc/design/ext-quantum.md` | `ext/quantum` circuits |
| `doc/design/ext-quantum-q7.md` | Q7 density linear algebra + advanced SVG |
| `doc/design/ext-quantum-viz-style.md` | Q8 themed SVG (`dark`/`light`/`bw`; circuit/probs/bloch) |
| `doc/design/ext-linalg.md` | `ext/linalg` formula MatExpr + factorize/draw |
| `doc/design/ext-linalg-formula-doc.md` | 公式文档面:跑通即正确 · 代数/计算两面 |
| `doc/design/view-debug.md` | view / debug hosts |
+12
View File
@@ -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=
+63 -13
View File
@@ -25,8 +25,10 @@ jobs:
with:
node-version: "20"
- name: Build release
run: cargo build --release
- name: Build release CLI + official plugins
run: |
cargo build --release
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
- name: Checkout extension sources (branch vscode-extension only)
run: git fetch origin vscode-extension && git checkout origin/vscode-extension -- vscode-extension
@@ -55,6 +57,7 @@ jobs:
$vsix = "marqdo-$ver.vsix"
$public = "marqdo-$ver-public.zip"
$extZip = "marqdo-$ver-ext.zip"
$nativeZip = "marqdo-$ver-native-$target.zip"
Copy-Item target/release/marqdo.exe "dist/$exe"
git archive --format=zip -o "dist/$source" HEAD
./target/release/marqdo view output public -o public
@@ -65,11 +68,27 @@ jobs:
Copy-Item ext "$stageExt/ext" -Recurse
if (Test-Path "dist/$extZip") { Remove-Item "dist/$extZip" -Force }
Compress-Archive -Path "$stageExt/*" -DestinationPath "dist/$extZip" -Force
# Prebuilt native plugins (no Rust required for `marqdo ext add`)
$stageNative = "dist/stage-native"
if (Test-Path $stageNative) { Remove-Item $stageNative -Recurse -Force }
New-Item -ItemType Directory -Force -Path "$stageNative/native" | Out-Null
Copy-Item target/release/web.dll "$stageNative/native/web.dll"
Copy-Item target/release/agent.dll "$stageNative/native/agent.dll"
Copy-Item target/release/quantum.dll "$stageNative/native/quantum.dll"
Copy-Item target/release/linalg.dll "$stageNative/native/linalg.dll"
if (Test-Path "dist/$nativeZip") { Remove-Item "dist/$nativeZip" -Force }
Compress-Archive -Path "$stageNative/*" -DestinationPath "dist/$nativeZip" -Force
$stage = "dist/stage-bundle"
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
New-Item -ItemType Directory -Force -Path $stage | Out-Null
Copy-Item target/release/marqdo.exe "$stage/marqdo.exe"
Copy-Item lib "$stage/lib" -Recurse
Copy-Item ext "$stage/ext" -Recurse
New-Item -ItemType Directory -Force -Path "$stage/ext/native" | Out-Null
Copy-Item target/release/web.dll "$stage/ext/native/web.dll"
Copy-Item target/release/agent.dll "$stage/ext/native/agent.dll"
Copy-Item target/release/quantum.dll "$stage/ext/native/quantum.dll"
Copy-Item target/release/linalg.dll "$stage/ext/native/linalg.dll"
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
$stageLib = "dist/stage-stdlib"
@@ -85,6 +104,7 @@ jobs:
echo "SOURCE=$source" >> $env:GITHUB_ENV
echo "PUBLIC=$public" >> $env:GITHUB_ENV
echo "EXT=$extZip" >> $env:GITHUB_ENV
echo "NATIVE=$nativeZip" >> $env:GITHUB_ENV
- name: Upload release assets
uses: softprops/action-gh-release@v2
@@ -92,24 +112,21 @@ jobs:
body: |
## Marqdo ${{ github.ref_name }}
### Highlights — v0.3.1
- **W8**: favicon / head assets / image assembly (`app.icons`, `page.head`, `make_images`)
- Fix: absolute `entry_dir` for relative entry scripts (no nested `tests/ext/tests/ext`)
- **`ext/web`**: W0–W7 + P3 + W8; **`ext/quantum`** Q7/Q8; **`ext/agent`** A1–A4
- Install: `marqdo ext list` / `marqdo ext add llm|agent|web|quantum`
- Native plugins: `cargo build --release -p marqdo_plugin_*` then `ext add`
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [README](https://github.com/cflmy/marqdo/blob/main/README.md)
Also: embedded stdlib, writeback/subtask, Variables modal in `view`, VSIX from branch **`vscode-extension`**.
### 亮点 / Highlights
- **中层标准库 Mid2**:datetime/url · toml/html/base32 · fs++ · stats/log.fields(M7–M10)
- **Mid2 stdlib**: calendar/URL, TOML/HTML/base32, thicker fs, thin stats + log fields
- **修复**:嵌套插件调用后恢复 `GLOBAL_HOST`(listen/invoke)
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [stdlib-mid2.md](https://github.com/cflmy/marqdo/blob/main/doc/roadmap/stdlib-mid2.md)
### Downloads
| Asset | Contents |
|-------|----------|
| `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib |
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` (optional disk override) |
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` + `ext/`(含 native DLL) |
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum` 插件 |
| `marqdo-*-stdlib.zip` | `lib/` only |
| `marqdo-*-ext.zip` | Official `ext/` L1 sources (for `MARQDO_EXT_SOURCE` / local `./ext`) |
| `marqdo-*-ext.zip` | Official `ext/` L1 sources |
| `marqdo-*-source.zip` | Source snapshot (`git archive`) |
| `marqdo-*.vsix` | VS Code / Cursor extension |
| `marqdo-*-public.zip` | Static user docs site |
@@ -120,9 +137,42 @@ jobs:
dist/${{ env.ZIP }}
dist/${{ env.STDLIB }}
dist/${{ env.EXT }}
dist/${{ env.NATIVE }}
dist/${{ env.VSIX }}
dist/${{ env.SOURCE }}
dist/${{ env.PUBLIC }}
fail_on_unmatched_files: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
linux-native:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
- name: Build official plugins (release)
run: cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
- name: Package native zip
run: |
set -euo pipefail
VER="${GITHUB_REF_NAME#v}"
TARGET="x86_64-unknown-linux-gnu"
mkdir -p dist/stage-native/native
cp target/release/libweb.so dist/stage-native/native/libweb.so
cp target/release/libagent.so dist/stage-native/native/libagent.so
cp target/release/libquantum.so dist/stage-native/native/libquantum.so
cp target/release/liblinalg.so dist/stage-native/native/liblinalg.so
(cd dist/stage-native && zip -r "../marqdo-${VER}-native-${TARGET}.zip" .)
echo "NATIVE=marqdo-${VER}-native-${TARGET}.zip" >> "$GITHUB_ENV"
- name: Upload Linux native plugins
uses: softprops/action-gh-release@v2
with:
files: dist/${{ env.NATIVE }}
fail_on_unmatched_files: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+12
View File
@@ -23,6 +23,7 @@
.DS_Store
.marqdo/
**/.marqdo/
.marqdo-ext/
.env
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
@@ -39,6 +40,13 @@ spike/.pytest_cache/
**/__pycache__/
*.pyc
# Built browser WASM (rebuild via crates/marqdo-wasm README)
/examples/browser-hello/marqdo_wasm.wasm
/examples/browser-hello/pkg/
/examples/web-client-site/static/marqdo_wasm.wasm
/examples/browser-app/marqdo_wasm.wasm
/examples/browser-media/marqdo_wasm.wasm
# Local sqlite / scratch
/data/
/tmp/
@@ -55,8 +63,12 @@ plugins/*/tmp/
# Quantum draw/SVG runtime outputs (sources & gold .mq.md stay tracked)
/tests/ext/quantum-*.svg
/tests/ext/linalg-*.svg
/examples/quantum-*/**/*.svg
/examples/quantum-*/*.svg
/examples/linalg-*/**/*.svg
/examples/linalg-*/*.svg
/examples/linalg-*.svg
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
/ext/native/
+188
View File
@@ -2,6 +2,194 @@
## Unreleased
### Added
### Fixed
### Changed
## v0.3.8 — 2026-09-09
### Highlights
**中层标准库 Mid2(M7–M10)收口**:日历/时区、URL、TOML、HTML 转义、base32、实用 fs、薄统计与日志字段——日常脚本与工具配置不再依赖外联或插件。另修复嵌套插件调用后 `GLOBAL_HOST` 被清空导致 `invoke` 失败。
```bash
git checkout v0.3.8
# 或下载 Release 的 exe / zip
marqdo run public/features/14-datetime-url.mq.md
marqdo run public/features/17-stats-log.mq.md
```
### Added
- **中层标准库 Mid2 M10**:`lib/stats` / `统计`(mean/median/stdev)与 `log`/`日志` 可选 `fields=`;金样与 public `17-stats-log`。**Mid2 M7–M10 收口**(zip 跳过)。设计 [stdlib-stats-log.md](doc/design/stdlib-stats-log.md)。
- **中层标准库 Mid2 M9**:`fs.make_dirs` / `remove_tree` / `stat` / `walk`(中英);金样与 public `16-fs-mid2`。设计 [stdlib-fs-mid2.md](doc/design/stdlib-fs-mid2.md)。
- **中层标准库 Mid2 M8**:`lib/toml` / `配置表`(只读子集)、`lib/html` / `超文本`(escape/unescape)、`encoding` base32;金样与 public `15-toml-html-encoding`。设计 [stdlib-toml.md](doc/design/stdlib-toml.md) · [stdlib-html.md](doc/design/stdlib-html.md)。
- **中层标准库 Mid2 M7**:`lib/datetime` / `日期时间`(`{unix,zone,iso}` · parse/format/add/in_zone)与 `lib/url` / `地址`(parse · query_parse/stringify);金样与 public `14-datetime-url`。设计 [stdlib-datetime.md](doc/design/stdlib-datetime.md) · [stdlib-url.md](doc/design/stdlib-url.md)。
- **文档**:中层标准库 Mid 之后缺口盘点与 Mid2(M7–M10)设计/路线——[stdlib-gaps-after-mid.md](doc/research/stdlib-gaps-after-mid.md) · [stdlib-mid2.md](doc/design/stdlib-mid2.md) · [stdlib-mid2.md](doc/roadmap/stdlib-mid2.md)。
### Fixed
- **`host_query` / GLOBAL_HOST**:嵌套 `call_registered` 结束后恢复外层宿主指针,不再清空;`web_listen` 多轮 `invoke`(中间再调插件)不再报 `no active host context`。
### Changed
## v0.3.7 — 2026-09-07
### Highlights
**宿主集成 H1–H4**:浏览器同域 SSE/HTTP 流式中继(`app.proxy`)、HTTP→用户 `##`(`app.invoke`)、跨模块 db 方法分发、`corpus_search` 可发现、MCP Server stdio——下游可去掉 Python 旁路。
```bash
git checkout v0.3.7
# 或下载 Release 的 exe / zip
marqdo ext add web && marqdo ext add agent
# *app*.proxy / *app*.invoke · agent.mcp_server
```
### Added
- **宿主集成 H1–H4**:`ext/web` `app.proxy`(同域 SSE/HTTP 流式中继)与 `app.invoke`(HTTP→`lib.member`);跨模块 `#` 对象方法查找;`agent.corpus_search` 自动加载插件;`agent.mcp_server` stdio。金样 `web-proxy-invoke-smoke` · `web-hosting-live` · `web-db-cross-module-smoke` · `agent-mcp-server-smoke`。设计 [ext-hosting-fill.md](doc/design/ext-hosting-fill.md) · [ext-hosting.md](doc/roadmap/ext-hosting.md)。
- **文档**:宿主集成缺口盘点——[ext-hosting-gaps.md](doc/research/ext-hosting-gaps.md)。
### Fixed
- **方法分发**:`find_object_type` 沿导入树传递查找,跨模块拿到的 `web.db` 等句柄可再调方法。
### Changed
## v0.3.6 — 2026-09-07
### Highlights
**中层标准库 Mid M1–M6 收口**:通用原语沉入 `lib/`(正则、编解码、路径、哈希、机密、CSV、加厚文本/集合、CLI、日志、UUID),写日常脚本与多数扩展库不再需要原生插件。另含 `ext/linalg` 公式文档面与 agent/llm 稳健性修复。
```bash
git checkout v0.3.6
# 或下载 Release 的 exe / zip
marqdo run public/features/13-log-uuid.mq.md
marqdo ext add linalg # 可选:公式文档 / 线性代数
```
### Added
- **中层标准库 M6**:`lib/log` / `日志`(级别过滤的一行日志)与 `lib/uuid` / `标识`(v4);金样与 public `13-log-uuid`。设计 [stdlib-log-uuid.md](doc/design/stdlib-log-uuid.md)。**Mid M1–M6 收口。**
- **中层标准库 M5**:`table`/`表` 加厚(sort/sort_by/unique/chunk/zip/flatten)与 `lib/cli`/`命令行`(parse);金样与 public `12-list-cli`。设计 [stdlib-list-cli.md](doc/design/stdlib-list-cli.md)。
- **中层标准库 M4**:`lib/csv` / `逗号表`(parse/stringify)与 `lib/text` / `文本` 加厚(contains/replace/case/pad/…);金样与 public `11-csv-text`。设计 [stdlib-csv.md](doc/design/stdlib-csv.md) · [stdlib-text-mid.md](doc/design/stdlib-text-mid.md)。
- **中层标准库 M3**:`lib/hash` / `哈希`(sha256/sha1/md5/hmac_sha256)与 `lib/secrets` / `机密`(token_hex/token_urlsafe);金样与 public `10-hash-secrets`。设计 [stdlib-hash.md](doc/design/stdlib-hash.md) · [stdlib-secrets.md](doc/design/stdlib-secrets.md)。
- **中层标准库 M2**:`lib/path` / `lib/路径`(join/split/normalize/…)与 `fs`/`文件` 加厚(`copy_file`/`move`/`make_temp`);金样与 public `09-path-fs`。设计 [stdlib-path.md](doc/design/stdlib-path.md) · [stdlib-fs-mid.md](doc/design/stdlib-fs-mid.md)。
- **中层标准库 M1**:`lib/re` / `lib/正则`(`is_match`/`find`/`find_all`/`replace`/`split`)与 `lib/encoding` / `lib/编码`(base64/hex);host `host_re_*` + `host_encoding_*`;金样与 public `08-re-encoding`。设计 [stdlib-mid.md](doc/design/stdlib-mid.md) · [stdlib-re.md](doc/design/stdlib-re.md) · [stdlib-encoding.md](doc/design/stdlib-encoding.md)。
- **`ext/linalg`**:L0–L6 + 公式文档面 **F1–F3**(中缀、`declare`、展示/`explicit` 默认化简、`T_ascii`、public「如何写公式文档」);示例 `linalg-transpose` · `linalg-svd` · `linalg-least-squares`。设计:[ext-linalg-formula-doc.md](doc/design/ext-linalg-formula-doc.md)。
### Fixed
- **`ext/agent`**:写回改走 `wb.record`(避免 `writeback` 形参遮蔽模块名),不再直调 `host_*`。
- **`ext/llm`**:`stream_result` 忽略未知 SSE 类型(如 `reasoning`),不再因此退出。
### Changed
## v0.3.5 — 2026-09-04
### Highlights
**`marqdo ext add` 无需本机 Rust**:Release 发布预编译 native 插件;CLI 可自动下载 L1(`*-ext.zip`)与 `*-native-*.zip`。Windows 便携包内含 `ext/native/*.dll`。
```bash
git checkout v0.3.5
# 或下载 Release 的 exe / zip
marqdo ext add web
marqdo ext add agent
marqdo ext add quantum
```
### Added
- **预编译原生插件资产**:`marqdo-*-native-x86_64-pc-windows-msvc.zip`、`marqdo-*-native-x86_64-unknown-linux-gnu.zip`;Windows zip 捆绑 `ext/` + native DLL。
- **`ext add` 下载回退**:本地无 `target/` 时从 GitHub Release 拉取;`MARQDO_EXT_NO_DOWNLOAD=1` / `MARQDO_EXT_VERSION` 可配置。
### Changed
- 文档:[ext-cli.md](doc/design/ext-cli.md)、[08-ext-deploy-coupling](doc/design/ext-web-customization/08-ext-deploy-coupling.md)、README 安装步骤以预编译为默认路径。
- Release workflow:Windows 编插件并上传 native zip;新增 Linux native job。
## v0.3.4 — 2026-09-04
### Highlights
**`ext/web` 定制波次 C0–C4 收口**:可配置 admin 前缀与登录回跳、段边界 gates、shell/layout、样式单元格 strict、脚本 defer/version/`asset_version`、条件导航 when/media。附智能体 Wave B0 示例与写回遮蔽修复。
```bash
git checkout v0.3.4
cargo build --release
cargo build --release -p marqdo_plugin_web
marqdo ext add web
# golds: tests/ext/web-c0-admin-prefix … web-c4-nav-when
```
### Added
- **智能体 Wave B0**:宪法优先示例 [agent-pong](examples/agent-pong/)(call_site/源码注入)· [agent-okf-flywheel](examples/agent-okf-flywheel/)(OKF `cache=hit`);调研 [agent-framework-2026-09.md](doc/research/agent-framework-2026-09.md);离线 harness [`scripts/agent-harness.sh`](scripts/agent-harness.sh);金样 `agent-constitution-b0`。
- **`.env.example`**:开发期 OpenAI 兼容网关变量模板(密钥仅本地 `.env`)。
### Fixed
- **`agent.step` / `plan` 写回**:参数名 `writeback` 遮蔽 `lib/writeback` import,导致 `writeback=True` 时 `method receiver must be an object map`;改为 `host_writeback_record`。金样 `agent-writeback-shadow`。
- **`ext/web` C0**:`admin=False` 不再挂载/保留 `/admin*`;可配 `admin_prefix` / `login_redirect` / `logout_redirect`;金样 `web-c0-admin-prefix`。
- **`ext/web` C1**:门禁段边界匹配(不再误伤 `/admin-publish`);`gate` 支持 `match` / `on_deny` / `exclude`;`auth` 默认 `on_deny=redirect` + `login_path`;金样 `web-c1-gates`。
- **`ext/web` C2**:`shell_css=full|minimal|off`;`layout=sidebar|stacked|bare|rail`;full 壳含小屏单列 media;金样 `web-c2-shell-layout`。
- **`ext/web` C3**:样式装配对数字/布尔值单元格告警,`strict`/`strict_css_cells` 硬错误;`page.css` 作 raw CSS;head 表支持 `defer`/`async`/`version`,`asset_version` 统一 `?v=`;金样 `web-c3-style-head`。
- **`ext/web` C4**:导航表 `当`/`when`(`auth`/`guest`/`hide`)与 `媒体`/`media`(响应式显隐);listen 注入 `_logged_in`;金样 `web-c4-nav-when`。
### Changed
- `build_step_context`:call site 提前到 task 之后;开场白强调 code-as-documentation。
- 中文 `构建单步上下文` 委托英文版(含预算 / READ);新增 `dump_step_context`;live 用例改用仓库根 `.env`。
- 文档:[ext-web 定制限制](doc/research/ext-web-customization-limits.md) + [解决设计 C0–C4](doc/design/ext-web-customization/)。
## v0.3.3 — 2026-09-04
### Highlights
**浏览器作者零业务 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
Generated
+316 -7
View File
@@ -317,6 +317,12 @@ version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801"
[[package]]
name = "cfg_aliases"
version = "0.2.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"
[[package]]
name = "chacha20"
version = "0.10.2"
@@ -463,6 +469,12 @@ dependencies = [
"cfg-if",
]
[[package]]
name = "crossbeam-utils"
version = "0.8.21"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
[[package]]
name = "crypto-common"
version = "0.1.7"
@@ -625,6 +637,12 @@ version = "0.3.33"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2cd50c473c80f6d7c3670a752354b8e569b1a7cbfdc0419ec88e5edad85e0dc7"
[[package]]
name = "futures-io"
version = "0.3.34"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed"
[[package]]
name = "futures-macro"
version = "0.3.33"
@@ -655,9 +673,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a77a90a256fce34da66415271e30f94ee91c57b04b8a2c042d9cf3220179deaa"
dependencies = [
"futures-core",
"futures-io",
"futures-macro",
"futures-sink",
"futures-task",
"memchr",
"pin-project-lite",
"slab",
]
@@ -688,8 +708,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"
dependencies = [
"cfg-if",
"js-sys",
"libc",
"wasi 0.11.1+wasi-snapshot-preview1",
"wasm-bindgen",
]
[[package]]
@@ -711,9 +733,11 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"
dependencies = [
"cfg-if",
"js-sys",
"libc",
"r-efi 6.0.0",
"rand_core 0.10.1",
"wasm-bindgen",
]
[[package]]
@@ -842,6 +866,23 @@ dependencies = [
"pin-project-lite",
"smallvec",
"tokio",
"want",
]
[[package]]
name = "hyper-rustls"
version = "0.27.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "33ca68d021ef39cf6463ab54c1d0f5daf03377b70561305bb89a8f83aab66e0f"
dependencies = [
"http",
"hyper",
"hyper-util",
"rustls 0.23.44",
"tokio",
"tokio-rustls",
"tower-service",
"webpki-roots 1.0.9",
]
[[package]]
@@ -850,13 +891,21 @@ version = "0.1.20"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"
dependencies = [
"base64",
"bytes",
"futures-channel",
"futures-util",
"http",
"http-body",
"hyper",
"ipnet",
"libc",
"percent-encoding",
"pin-project-lite",
"socket2 0.6.5",
"tokio",
"tower-service",
"tracing",
]
[[package]]
@@ -933,6 +982,12 @@ dependencies = [
"quote",
]
[[package]]
name = "ipnet"
version = "2.12.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0"
[[package]]
name = "is_terminal_polyfill"
version = "1.70.2"
@@ -1016,28 +1071,49 @@ version = "0.4.33"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "lru-slab"
version = "0.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "112b39cec0b298b6c1999fee3e31427f74f676e4cb9879ed1a121b43661a4154"
[[package]]
name = "marqdo"
version = "0.3.1"
version = "0.3.8"
dependencies = [
"anyhow",
"assert_cmd",
"chrono",
"clap",
"futures-util",
"getrandom 0.2.17",
"hmac 0.12.1",
"idna_adapter",
"include_dir",
"libc",
"libloading",
"md-5 0.10.6",
"predicates",
"pulldown-cmark",
"regex",
"serde_json",
"sha1",
"sha2 0.10.9",
"thiserror 1.0.69",
"tiny_http",
"tokio",
"tokio-tungstenite 0.24.0",
"ureq",
"zeroize",
"zip",
]
[[package]]
name = "marqdo-wasm"
version = "0.3.8"
dependencies = [
"marqdo",
"serde_json",
]
[[package]]
@@ -1055,6 +1131,14 @@ dependencies = [
"serde_json",
]
[[package]]
name = "marqdo_plugin_linalg"
version = "0.1.0"
dependencies = [
"serde",
"serde_json",
]
[[package]]
name = "marqdo_plugin_quantum"
version = "0.1.0"
@@ -1069,6 +1153,7 @@ version = "0.1.0"
dependencies = [
"argon2",
"axum",
"bytes",
"futures-util",
"getrandom 0.2.17",
"hex",
@@ -1076,6 +1161,7 @@ dependencies = [
"postgres",
"pulldown-cmark",
"redis",
"reqwest",
"rusqlite",
"serde",
"serde_json",
@@ -1092,6 +1178,16 @@ version = "0.8.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "47e1ffaa40ddd1f3ed91f717a33c8c0ee23fff369e3aa8772b9605cc1d22f4c3"
[[package]]
name = "md-5"
version = "0.10.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d89e7ee0cfbedfc4da3340218492196241d89eefb6dab27de5df917a6d2e78cf"
dependencies = [
"cfg-if",
"digest 0.10.7",
]
[[package]]
name = "md-5"
version = "0.11.0"
@@ -1322,7 +1418,7 @@ dependencies = [
"bytes",
"fallible-iterator 0.2.0",
"hmac 0.13.0",
"md-5",
"md-5 0.11.0",
"memchr",
"rand 0.10.2",
"sha2 0.11.0",
@@ -1409,6 +1505,62 @@ version = "0.11.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "007d8adb5ddab6f8e3f491ac63566a7d5002cc7ed73901f72057943fa71ae1ae"
[[package]]
name = "quinn"
version = "0.11.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0c1a41e437b6bbd489372cd4971de128e85c855f56c57f283d20ff016cf7c0a8"
dependencies = [
"bytes",
"cfg_aliases",
"pin-project-lite",
"quinn-proto",
"quinn-udp",
"rustc-hash",
"rustls 0.23.44",
"socket2 0.6.5",
"thiserror 2.0.20",
"tokio",
"tracing",
"web-time",
]
[[package]]
name = "quinn-proto"
version = "0.11.17"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "04759210543be93709136e28212294a659ef5001836ff4eab4d663e4529bba83"
dependencies = [
"bytes",
"getrandom 0.4.3",
"lru-slab",
"rand 0.10.2",
"rand_pcg",
"ring",
"rustc-hash",
"rustls 0.23.44",
"rustls-pki-types",
"slab",
"thiserror 2.0.20",
"tinyvec",
"tracing",
"web-time",
]
[[package]]
name = "quinn-udp"
version = "0.5.15"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "35a133f956daabe89a61a685c2649f13d82d5aa4bd5d12d1277e1072a21c0694"
dependencies = [
"cfg_aliases",
"libc",
"once_cell",
"socket2 0.6.5",
"tracing",
"windows-sys 0.61.2",
]
[[package]]
name = "quote"
version = "1.0.47"
@@ -1506,6 +1658,15 @@ version = "0.10.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"
[[package]]
name = "rand_pcg"
version = "0.10.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "caa0f4137e1c0a72f4c651489402276c8e8e1cf081f3b0ba156d2cbeef09e86a"
dependencies = [
"rand_core 0.10.1",
]
[[package]]
name = "redis"
version = "0.27.6"
@@ -1562,6 +1723,47 @@ version = "0.8.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d6f6ff9a378485b298a5286656da665ba74413d36db0979633275d2e708145d4"
[[package]]
name = "reqwest"
version = "0.12.28"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"
dependencies = [
"base64",
"bytes",
"futures-core",
"futures-util",
"http",
"http-body",
"http-body-util",
"hyper",
"hyper-rustls",
"hyper-util",
"js-sys",
"log",
"percent-encoding",
"pin-project-lite",
"quinn",
"rustls 0.23.44",
"rustls-pki-types",
"serde",
"serde_json",
"serde_urlencoded",
"sync_wrapper",
"tokio",
"tokio-rustls",
"tokio-util",
"tower",
"tower-http",
"tower-service",
"url",
"wasm-bindgen",
"wasm-bindgen-futures",
"wasm-streams",
"web-sys",
"webpki-roots 1.0.9",
]
[[package]]
name = "ring"
version = "0.17.14"
@@ -1590,6 +1792,12 @@ dependencies = [
"smallvec",
]
[[package]]
name = "rustc-hash"
version = "2.1.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
[[package]]
name = "rustls"
version = "0.22.4"
@@ -1599,7 +1807,21 @@ dependencies = [
"log",
"ring",
"rustls-pki-types",
"rustls-webpki",
"rustls-webpki 0.102.8",
"subtle",
"zeroize",
]
[[package]]
name = "rustls"
version = "0.23.44"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6725596c3f2c3a0aef021139e145d4eafe314a6623e4680ca83852b2c67ab2ba"
dependencies = [
"once_cell",
"ring",
"rustls-pki-types",
"rustls-webpki 0.103.15",
"subtle",
"zeroize",
]
@@ -1610,6 +1832,7 @@ version = "1.15.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96"
dependencies = [
"web-time",
"zeroize",
]
@@ -1624,6 +1847,17 @@ dependencies = [
"untrusted",
]
[[package]]
name = "rustls-webpki"
version = "0.103.15"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "f3c3cf1d8b1e7d4927e2d154c3fcb02979afb9939629c62cd9048d4f07b60ac2"
dependencies = [
"ring",
"rustls-pki-types",
"untrusted",
]
[[package]]
name = "rustversion"
version = "1.0.23"
@@ -1710,9 +1944,9 @@ dependencies = [
[[package]]
name = "sha1"
version = "0.10.7"
version = "0.10.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "a978451301f4db1d02937a4ab3ccce137717b81826e79b7d49ffe3244a13c3b8"
checksum = "e3bf829a2d51ab4a5ddf1352d8470c140cadc8301b2ae1789db023f01cedd6ba"
dependencies = [
"cfg-if",
"cpufeatures 0.2.17",
@@ -1863,6 +2097,9 @@ name = "sync_wrapper"
version = "1.0.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"
dependencies = [
"futures-core",
]
[[package]]
name = "termtree"
@@ -1990,6 +2227,16 @@ dependencies = [
"whoami",
]
[[package]]
name = "tokio-rustls"
version = "0.26.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "b0c85f2c3ef0b1cd58b36682f4b17aaa995f0e5db534d85692b4903abce21f67"
dependencies = [
"rustls 0.23.44",
"tokio",
]
[[package]]
name = "tokio-tungstenite"
version = "0.24.0"
@@ -2066,9 +2313,11 @@ dependencies = [
"pin-project-lite",
"tokio",
"tokio-util",
"tower",
"tower-layer",
"tower-service",
"tracing",
"url",
]
[[package]]
@@ -2103,6 +2352,12 @@ dependencies = [
"once_cell",
]
[[package]]
name = "try-lock"
version = "0.2.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
[[package]]
name = "tungstenite"
version = "0.24.0"
@@ -2204,9 +2459,9 @@ dependencies = [
"flate2",
"log",
"once_cell",
"rustls",
"rustls 0.22.4",
"rustls-pki-types",
"rustls-webpki",
"rustls-webpki 0.102.8",
"url",
"webpki-roots 0.26.11",
]
@@ -2262,6 +2517,15 @@ dependencies = [
"libc",
]
[[package]]
name = "want"
version = "0.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"
dependencies = [
"try-lock",
]
[[package]]
name = "wasi"
version = "0.11.1+wasi-snapshot-preview1"
@@ -2308,6 +2572,16 @@ dependencies = [
"wasm-bindgen-shared",
]
[[package]]
name = "wasm-bindgen-futures"
version = "0.4.77"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "6b7777d5cc23d0e91404e53ce2d5e8ec7acae3026b16233dba62cd3246457950"
dependencies = [
"js-sys",
"wasm-bindgen",
]
[[package]]
name = "wasm-bindgen-macro"
version = "0.2.127"
@@ -2340,6 +2614,19 @@ dependencies = [
"unicode-ident",
]
[[package]]
name = "wasm-streams"
version = "0.4.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "15053d8d85c7eccdbefef60f06769760a563c7f0a9d6902a13d35c7800b0ad65"
dependencies = [
"futures-util",
"js-sys",
"wasm-bindgen",
"wasm-bindgen-futures",
"web-sys",
]
[[package]]
name = "web-sys"
version = "0.3.104"
@@ -2350,6 +2637,16 @@ dependencies = [
"wasm-bindgen",
]
[[package]]
name = "web-time"
version = "1.1.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb"
dependencies = [
"js-sys",
"wasm-bindgen",
]
[[package]]
name = "webpki-roots"
version = "0.26.11"
@@ -2554,6 +2851,18 @@ version = "1.8.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ced3678a2879b30306d323f4542626697a464a97c0a07c9aebf7ebca65cd4dde"
[[package]]
name = "zip"
version = "0.6.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "760394e246e4c28189f19d488c058bf16f564016aefac5d32bb1f3b51d5e9261"
dependencies = [
"byteorder",
"crc32fast",
"crossbeam-utils",
"flate2",
]
[[package]]
name = "zmij"
version = "1.0.23"
+51 -9
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "0.3.1"
version = "0.3.8"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -10,25 +10,58 @@ repository = "https://github.com/cflmy/marqdo"
[[bin]]
name = "marqdo"
path = "src/main.rs"
required-features = ["cli"]
[features]
default = ["native"]
native = ["cli", "view", "net-host", "plugin-host", "exec-host", "fs-host", "tty"]
cli = ["dep:clap"]
view = ["dep:tiny_http"]
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize", "dep:zip"]
plugin-host = ["dep:libloading"]
exec-host = []
fs-host = []
tty = ["dep:libc"]
wasm-core = []
[dependencies]
anyhow = "1"
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
clap = { version = "=4.4.18", features = ["derive"] }
clap = { version = "=4.4.18", features = ["derive"], optional = true }
pulldown-cmark = "0.12"
serde_json = "1"
thiserror = "1"
tiny_http = "0.12"
tiny_http = { version = "0.12", optional = true }
sha2 = { version = "=0.10.9", default-features = false }
sha1 = { version = "=0.10.6", default-features = false }
md-5 = { version = "=0.10.6", default-features = false }
hmac = { version = "=0.12.1", default-features = false }
getrandom = { version = "=0.2.17", default-features = false, features = ["std"] }
# Mid M1: Unicode regex for lib/re (no backrefs; RE2-like).
regex = { version = "=1.13.1", default-features = false, features = ["std", "unicode"] }
# Pin for Cargo/rustc 1.81 (newer rustls/idna/zeroize need edition2024).
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"] }
idna_adapter = "=1.1.0"
zeroize = "=1.8.1"
libloading = "=0.8.6"
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"], optional = true }
idna_adapter = { version = "=1.1.0", optional = true }
zeroize = { version = "=1.8.1", optional = true }
# Extract GitHub Release ext/native zips (`marqdo ext add` without local Rust).
zip = { version = "=0.6.6", default-features = false, features = ["deflate"], optional = true }
libloading = { version = "=0.8.6", optional = true }
include_dir = "0.7"
libc = "0.2"
libc = { version = "0.2", optional = true }
[target.'cfg(target_arch = "wasm32")'.dependencies]
# No `wasmbind`: keeps cdylib free of wasm-bindgen imports (raw mq_* ABI).
chrono = { version = "0.4", default-features = false, features = ["alloc", "std"] }
[workspace]
members = ["plugins/demo", "plugins/agent", "plugins/web", "plugins/quantum"]
members = [
"plugins/demo",
"plugins/agent",
"plugins/web",
"plugins/quantum",
"plugins/linalg",
"crates/marqdo-wasm",
]
resolver = "2"
[dev-dependencies]
@@ -37,3 +70,12 @@ predicates = "=3.1.0"
tokio = { version = "1", features = ["rt-multi-thread", "macros", "time", "net"] }
tokio-tungstenite = "0.24"
futures-util = "0.3"
# Size-oriented profile for `marqdo-wasm` (C5). Use: cargo build -p marqdo-wasm --profile release-wasm --target wasm32-unknown-unknown
[profile.release-wasm]
inherits = "release"
lto = true
codegen-units = 1
opt-level = "z"
strip = true
panic = "abort"
+22 -14
View File
@@ -99,7 +99,7 @@ marqdo catalog public -o .marqdo
---
## 现状(v0.3.1)
## 现状(v0.3.8)
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
@@ -107,24 +107,26 @@ marqdo catalog public -o .marqdo
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
- **`marqdo version --check`**:与 GitHub 最新 release 对比
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**;**中层 Mid M1–M6** + **Mid2 M7–M10**(datetime/url/toml/html/fs++/stats/log.fields 等,见 [stdlib-mid.md](doc/design/stdlib-mid.md) · [stdlib-mid2.md](doc/design/stdlib-mid2.md))
- **官方扩展库 `ext/`**(**非** stdlib,本版收口):
- **`web`**:W0–W7 + P3 + **W8**(favicon / Head 资源 / 图片装配,见 [web-assets-and-images.md](doc/design/web-assets-and-images.md));示例 [marqdo-blog](examples/marqdo-blog/);生产路径见 [web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)(反向代理 → 嵌入式 `listen`,非 Daphne/Uvicorn)
- **`web`**:W0–W7 + P3 + **W8**;**定制 C0–C4**;**宿主 H1–H2**(`proxy`/`invoke`,见 [ext-hosting.md](doc/roadmap/ext-hosting.md));示例 [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)
- **`linalg`**:L0–L6 + 公式文档面(中缀 / `declare` / 展示化简);示例 [linalg-transpose](examples/linalg-transpose/) · [linalg-svd](examples/linalg-svd/) · [linalg-least-squares](examples/linalg-least-squares/)
- **`agent`**:A1–A4 + **MCP Server stdio**(`mcp_server`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
- **`llm`**:OpenAI 兼容对话
- 安装:`marqdo ext list` / `add …` / `remove`([ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum}`
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum,linalg}`
- **用户静态站**:`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.1)
### 如何使用最新 Marqdo(v0.3.8)
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v0.3.1 # 或留在 main
git checkout v0.3.8 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -137,19 +139,25 @@ marqdo view public --no-open
marqdo debug public --no-open
marqdo catalog public -o .marqdo
# 3) 安装官方扩展(需先编原生插件)
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
marqdo ext add web # 或:网页
# 3) 安装官方扩展(Release 用户:无需本机 Rust)
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native
marqdo ext add agent # 或:智能体
marqdo ext add quantum # 或:量子
marqdo ext add llm # 或:大模型
marqdo ext add linalg # 或:线性代数
marqdo ext add llm # 或:大模型(纯 .mq.md)
# 开发者也可:cargo build --release -p marqdo_plugin_* 后在本机 target/ 安装
# 离线:解压 Windows zip(已含 ext/native)或手动放下 native zip;MARQDO_EXT_NO_DOWNLOAD=1
# 4) 动态站示例(扩展装好后)
marqdo run examples/marqdo-blog/index.mq.md
# 浏览器打开终端打印的 listen 地址;/favicon.ico 与 logo 装配见 W8
# 5) Windows:也可从 GitHub Releases 下载 exe / zip / vsix
# https://github.com/cflmy/marqdo/releases/tag/v0.3.1
# 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.8
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+15
View File
@@ -0,0 +1,15 @@
[package]
name = "marqdo-wasm"
version = "0.3.8"
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"
+21
View File
@@ -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
+201
View File
@@ -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");
}
}
+24 -3
View File
@@ -32,6 +32,17 @@
| [design/stdlib.md](design/stdlib.md) | **标准库:内置 + `lib/` + 错误约定** |
| [design/stdlib-i18n.md](design/stdlib-i18n.md) | **标准库中英命名:靠库文件名区分,无 lang 开关** |
| [design/stdlib-modules.md](design/stdlib-modules.md) | **L1:文件/系统/时间/JSON/网络/数学/外联/插件** |
| [design/stdlib-mid.md](design/stdlib-mid.md) | **中层 Mid M1–M6(已落地)** |
| [design/stdlib-mid2.md](design/stdlib-mid2.md) | **中层 Mid2:datetime / url / toml / html / fs++** |
| [design/stdlib-datetime.md](design/stdlib-datetime.md) | **`lib/datetime`(Mid2 M7)** |
| [design/stdlib-url.md](design/stdlib-url.md) | **`lib/url`(Mid2 M7)** |
| [design/stdlib-toml.md](design/stdlib-toml.md) | **`lib/toml`(Mid2 M8)** |
| [design/stdlib-html.md](design/stdlib-html.md) | **`lib/html`(Mid2 M8)** |
| [design/stdlib-fs-mid2.md](design/stdlib-fs-mid2.md) | **`lib/fs` Mid2 M9 加厚** |
| [design/stdlib-stats-log.md](design/stdlib-stats-log.md) | **`lib/stats` + log.fields(Mid2 M10)** |
| [research/stdlib-gaps-after-mid.md](research/stdlib-gaps-after-mid.md) | **Mid 之后缺口盘点**(对照 Python/Go) |
| [roadmap/stdlib-mid.md](roadmap/stdlib-mid.md) | **Mid M1–M6 路线(done)** |
| [roadmap/stdlib-mid2.md](roadmap/stdlib-mid2.md) | **Mid2 M7–M10 路线(规划)** |
| [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** |
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** |
| [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) |
@@ -40,6 +51,8 @@
| [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) | **调用:具名 + 位置实参** |
@@ -59,12 +72,20 @@
| [roadmap/object-inheritance.md](roadmap/object-inheritance.md) | **对象继承**(`# 子类 = > 父类`;I0–I2 已落地) |
| [roadmap/tables-maps-footnotes.md](roadmap/tables-maps-footnotes.md) | **表格语义**(竖表 / 横表字典 / 脚注取元 / 行向记录 / **单元格表达式 T5**) |
| [design/table-cell-expressions.md](design/table-cell-expressions.md) | **表数据单元格 = 表达式**(同调用实参值语法;Accepted) |
| [roadmap/ext-web.md](roadmap/ext-web.md) | **实现路线:`ext/web`**(W0–W4;设计见 [ext-web.md](../design/ext-web.md)) |
| [roadmap/browser-wasm.md](roadmap/browser-wasm.md) | **浏览器 WASM 路线 C(C0–C5 Completed)** |
| [roadmap/browser-wasm-d.md](roadmap/browser-wasm-d.md) | **路线 D:作者零 JS 前端(Completed)** |
| [roadmap/browser-wasm-e.md](roadmap/browser-wasm-e.md) | **路线 E:前端能力补齐(Completed)** |
| [roadmap/browser-wasm-f.md](roadmap/browser-wasm-f.md) | **路线 F:媒体/文件/Canvas 等(Completed,F1–F5;v0.3.3)** |
| [design/browser-marqdo-wasm.md](design/browser-marqdo-wasm.md) | **浏览器 Marqdo(WASM)设计** |
| [roadmap/ext-quantum.md](roadmap/ext-quantum.md) | **规划:`ext/quantum` 量子模拟**(基础门·电路·ABI·`ext add`) |
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点**(产品化 / 评测 / MCP / resume) |
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` 深入优化 A0–A4**(已完成) |
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** |
| [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** |
| [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus |
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** |
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
+57
View File
@@ -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) |
+48
View File
@@ -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 / 关键字纪律 |
+397
View File
@@ -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` 打印闭环 |
+3
View File
@@ -82,6 +82,9 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
| **clap** | CLI | `marqdo run [path]` |
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`import x:x.mq.md` 仍按**行**抽取(见 Spike) |
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
| **regex** (=1.13.1) | 正则 | Mid M1 `lib/re`;`default-features=false` + `std`/`unicode`;无回溯引用 |
| **sha2** (=0.10.9) / **sha1** (=0.10.6) / **md-5** (=0.10.6) / **hmac** (=0.12.1) | 摘要 | Mid M3 `lib/hash` |
| **getrandom** (=0.2.17) | OS 熵 | Mid M3 `lib/secrets` |
#### 强烈建议
+64 -26
View File
@@ -2,9 +2,9 @@
| | |
|---|---|
| Status | **Accepted (v0.1)** |
| Date | 2026-08-07 |
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) |
| Status | **Accepted (v0.3.5 prep)** — prebuilt native download |
| Date | 2026-09-04 |
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) · [08-ext-deploy-coupling.md](ext-web-customization/08-ext-deploy-coupling.md) |
## Commands
@@ -12,8 +12,8 @@
marqdo ext list
marqdo ext add llm
marqdo ext add agent
marqdo ext add web
marqdo ext remove llm
marqdo ext remove agent
```
## Install root
@@ -23,50 +23,88 @@ marqdo ext remove agent
Imports use paths like `import llm:ext/ai/llm.mq.md` (see [`load.rs`](../../src/load.rs)).
## Source for `add`
## Goal: no local Rust required
End users who install Marqdo from **GitHub Releases** should run:
```bash
marqdo ext add web
```
and get both L1 `.mq.md` **and** the matching native plugin (`.dll` / `.so`) **without** `cargo build`.
### Resolution order (`add` with native crate)
1. Local artifact (`MARQDO_*_PLUGIN`, `target/{debug,release}`, beside `marqdo`, `MARQDO_EXT_SOURCE/native`, …)
2. **Download** `marqdo-{VER}-native-{target}.zip` from the GitHub Release for this CLI version → cache under `~/.marqdo/cache/`
3. If Rust/`cargo` is available → `cargo build -p marqdo_plugin_*` (developers)
4. Else fail with a clear message pointing at the Release assets
L1 sources:
1. `MARQDO_EXT_SOURCE` / repo `./ext` / beside binary
2. Else download `marqdo-{VER}-ext.zip` into `~/.marqdo/cache/ext-src-v{VER}/`
### Env knobs
| Variable | Meaning |
|----------|---------|
| `MARQDO_EXT_VERSION` | Override SemVer used for Release asset names (default: CLI `CARGO_PKG_VERSION`) |
| `MARQDO_EXT_NO_DOWNLOAD=1` | Never hit the network (CI / air-gap); local/cargo only |
| `MARQDO_WEB_PLUGIN` / `MARQDO_AGENT_PLUGIN` / `MARQDO_QUANTUM_PLUGIN` | Explicit native path |
Windows Release **zip** also ships `ext/` + `ext/native/*.dll` next to `marqdo.exe` so a portable unzip works offline after one download.
## Source for `add` (developers)
1. `MARQDO_EXT_SOURCE` — directory containing `ai/llm.mq.md` …
2. Else repo `./ext` near cwd / binary
2. Else repo `./ext` near cwd / binary
3. Else Release `marqdo-*-ext.zip` (see above)
## Layout (`ext/`)
Official extensions live under **`ext/ai/`** (LLM + agent framework only). Do not add flat `.mq.md` files at `ext/` root — keeps the tree from accumulating unrelated modules.
```text
ext/
ai/
llm.mq.md
大模型.mq.md
agent.mq.md
智能体.mq.md
ai/ # llm + agent L1
web/
quantum/
```
Future optional ext domains get their own subdirs (e.g. `ext/web/`, `ext/quantum/`), not mixed into `ai/`.
Installed tree (`~/.marqdo/ext` or `MARQDO_EXT`):
```text
web/web.mq.md
web/网页.mq.md
native/libweb.so # or web.dll / libweb.dylib
web.plugin # absolute path hint
```
## Catalog
| Id | Installs under `MARQDO_EXT` |
|----|-----------------------------|
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **`native/libagent.so`** (or `.dylib`) |
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **`native/libweb.so`** — 见 [ext-web.md](ext-web.md) · [roadmap](../roadmap/ext-web.md) |
| `quantum` | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **`native/libquantum.so`** — 见 [ext-quantum.md](ext-quantum.md) · [roadmap](../roadmap/ext-quantum.md) |
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **native `agent`** |
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **native `web`** |
| `quantum` | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **native `quantum`** |
`add agent` copies the built native plugin into `MARQDO_EXT/native/`. Build it first:
## Release assets (native)
```bash
cargo build -p marqdo_plugin_agent
marqdo ext add agent
```
| Asset | Platform |
|-------|----------|
| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Windows x64 (`native/*.dll`) |
| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Linux x64 (`native/lib*.so`) |
Without install, runtime resolves the plugin via `plugin.native_path name=agent` (see [ext-abi.md](ext-abi.md)): `MARQDO_AGENT_PLUGIN` → `CARGO_TARGET_DIR/{debug,release}/` → cwd `target/…` → beside `marqdo` binary → `MARQDO_EXT/native/`.
macOS: use local `cargo build` until CI adds Darwin natives (same zip naming pattern reserved).
## Tests
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` ([`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md); needs `tests/ext/.env` + built `libagent`).
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_cli_add_web` (local build path; set `MARQDO_EXT_NO_DOWNLOAD=1` in sandboxes if needed).
Unit: `ext_fetch` URL / triple tests.
## Non-goals
- Third-party registry
- Merging into `lib/`
- Bundling domain/task helpers in official ext
- Merging domain helpers into `lib/`
- Guaranteeing plugin **source** ABI stability (author `.mq.md` API is the contract)
+306
View File
@@ -0,0 +1,306 @@
# 设计:宿主集成缺口补齐(`ext/web` · `ext/ai`)
| | |
|---|---|
| 状态 | **Accepted · H1–H4 stdio 已落地**(H4b HTTP 可选) |
| 日期 | 2026-09-07 |
| 缺口盘点 | [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) |
| 路线图 | [ext-hosting.md](../roadmap/ext-hosting.md) |
| 边界 | [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) |
| 目标 | 用**扩展库一等 API**关闭 GAP-01–05,取代下游 Python 旁路 |
---
## 0. 一句话
**服务器中继与「请求→`##`」进 `ext/web`;MCP Server 与 corpus 可发现进 `ext/ai`;标准库只保留已有客户端 SSE。** 作者用 GFM 表声明路由/工具,不写 JS、不启第二语言运行时。
---
## 1. 分层与禁止项
| 层 | 职责 | 落点 |
|----|------|------|
| 作者面 | 声明路径、上游、函数名、工具表 | `ext/web/web.mq.md` · `ext/ai/agent.mq.md`(+ 中文对偶) |
| ABI | axum 流式代理、每请求 interp 调用、MCP 传输 | `plugins/web` · `plugins/agent` |
| 标准库 | 不变:缓冲客户端 SSE / 解析 | `lib/net`(**不**加中继) |
| 核心 host | **禁止**新增 agent/web 领域 `host_*` | 见 Skill 硬规则 9 |
**禁止:**
1. 为中继在浏览器手写业务 JS。
2. `json=` 继续塞「任意 `##`」语义(保持 DB-only;新能力用独立装配名)。
3. MCP Server 把向量库升为权威真相(工具结果可带 `authority=workbook`)。
4. 无白名单的「任意文件系统路径 + 任意 `##`」远程触发。
---
## 2. GAP-01 · `app.proxy` 流式反向代理
### 2.1 作者 API
```markdown
*应用 = > `应用`.proxy path="/v1/chat/completions" upstream=$OPENAI_BASE_URL*
*应用 = > `应用`.proxy path="/llm/stream" upstream="https://api.example.com" strip_prefix="/llm" stream=True*
```
或装配表(一次挂多条):
```markdown
*应用 = > `应用`.configure proxy=`代理表`*
| path | upstream | stream | strip_prefix | headers_from_env |
|------|----------|--------|--------------|------------------|
| /proxy/chat | $OPENAI_BASE_URL | True | | OPENAI_API_KEY=Authorization |
```
| 参数 | 默认 | 含义 |
|------|------|------|
| `path` | 必填 | 浏览器同域路径 |
| `upstream` | 必填 | 上游根或完整 URL;支持 `$ENV` |
| `stream` | `True` | `True`:响应按上游 `Content-Type` 管道转发(含 `text/event-stream`) |
| `strip_prefix` | 空 | 转发前去掉本站前缀 |
| `methods` | `POST` | 允许方法 |
| `headers_from_env` | 空 | `ENV=Header-Name` 注入(密钥不进前端) |
| `timeout_ms` | 插件默认 | 上游超时 |
中文:`## 代理` / `流式=` / `上游=` / `去前缀=`。
### 2.2 ABI / 插件行为
| 步骤 | 行为 |
|------|------|
| 注册 | `web_app_proxy` 写入 `AppState` 路由表 |
| 请求 | 读 body + 过滤危险 hop-by-hop 头;合并 env 注入头 |
| 上游 | `reqwest`/`hyper` 流式客户端(插件内,不进核心) |
| 响应 | 复制状态码与 `content-type`;`body` 为 stream;SSE 不整段缓冲 |
| CORS | 仍走既有 `configure cors=`(同域调用时浏览器不依赖上游 CORS) |
### 2.3 与 `lib/net.http_post_sse` 关系
| API | 角色 |
|-----|------|
| `http_post_sse` | **出站消费者**(CLI/agent 侧收齐 events) |
| `app.proxy` | **入站中继**(浏览器 ← Marqdo ← 上游) |
二者互补,不互相替代。
### 2.4 验收
- 金样:mock 上游发两帧 SSE,浏览器侧(或 `curl -N`)收到两帧且中间无全缓冲延迟门槛。
- 密钥仅出现在服务端 env 注入头。
- 金样名建议:`tests/ext/web-proxy-sse-smoke.mq.md`。
---
## 3. GAP-02 · `app.invoke` / `configure invoke=`(HTTP → `##`)
### 3.1 作者 API
```markdown
*应用 = > `应用`.invoke path="/api/沉淀" method=POST fn="run.沉淀"*
```
表形式:
```markdown
*应用 = > `应用`.configure invoke=`调用表`*
| path | method | fn | body | return |
|------|--------|-----|------|--------|
| /api/note | POST | run.写出 | json | json |
| /api/search | GET | db.recent | query | json |
```
| 列 / 参数 | 含义 |
|-----------|------|
| `path` / `method` | HTTP 路由 |
| `fn` | `库.成员`(入口模块已 `import`)或 `模块路径##标题`(白名单前缀内) |
| `body` | `json` \| `form` \| `query` \| `raw` → 映射到 `##` 形参(同名优先;其余进 `payload` 袋) |
| `return` | `json`(默认)\| `text` \| `status` |
中文:`## 调用` / `函数=` / `正文=` / `返回=`。
### 3.2 安全默认(锁定)
1. **仅**解析入口 workbook 已导入的 `bind` 路径,或 `invoke_allow=` 显式前缀列表。
2. 单请求超时 + 可选并发上限(防 listen 线程饿死)。
3. 默认不启;作者显式 `invoke` / `configure invoke=`。
4. 错误:`{ok:false, error}` + HTTP 4xx/5xx;不把内部路径栈默认回传生产模式。
### 3.3 ABI / 插件行为
| 步骤 | 行为 |
|------|------|
| 注册 | `web_app_invoke` 存 `(path, method, FnRef)` |
| 命中 | 解析 body → Value 袋;`call_lib_path` / 等价「同步调用已加载模块的 `##`」 |
| 返回 | Value → JSON(复用现有 host JSON 通路);侧效(写盘)在同一解释器事务语义内尽最大努力 |
**不**把 `json=` DB 路由改语义;`invoke` 是平行装配。
### 3.4 与 compose 期 `call_lib_path` 关系
| 时机 | API |
|------|-----|
| 装配页 | 现有 compose / `call_lib_path` |
| **每个 HTTP 请求** | 本设计 `invoke` |
### 3.5 验收
- `POST` JSON → 用户 `##` 写入临时文件 + 返回 `{ok:true,…}`。
- 未导入路径 → 4xx,不执行。
- 金样:`tests/ext/web-invoke-smoke.mq.md`。
---
## 4. GAP-03 · MCP Server(`ext/ai`)
### 4.1 作者 API
```markdown
*服务 = > agent.mcp_server name="marqdo-qd"*
*服务 = > `服务`.tool name="qd_search" fn="求道.搜索" description="关键词检索"*
*服务 = > `服务`.tool name="qd_capture" fn="求道.捕捉"*
*服务 = > `服务`.serve transport=stdio*
# 或
*服务 = > `服务`.serve transport=http host=127.0.0.1 port=7433*
```
工具表:
| name | fn | description |
|------|-----|-------------|
| qd_search | 求道.搜索 | … |
| qd_list | 求道.列出 | … |
### 4.2 传输
| transport | 用途 |
|-----------|------|
| `stdio` | Cursor / Claude Desktop 拉起 |
| `http` | Streamable HTTP(与官方 MCP 演进对齐;首版可先 SSE+POST 子集) |
### 4.3 与 A4 fixture 客户端关系
| API | 方向 |
|-----|------|
| `mcp_list_tools` / `mcp_call` | **出站**(Agent 调外部 MCP;现 fixture) |
| `mcp_server` + `serve` | **入站**(外部调 Marqdo) |
客户端「真 MCP」仍见 agent 缺口文;本设计先交 Server,fixture 可保留测客户端。
### 4.4 ABI
- `plugins/agent`:`agent_mcp_server_*`(注册工具、stdio loop、可选 HTTP)。
- 工具实现:复用 GAP-02 同款「调用 `##`」内核(可抽共享 `invoke_fn`),避免两套分发。
- 返回包装:可含 `authority=workbook`。
### 4.5 验收
- 金样:stdio 夹具发 `tools/list` + `tools/call`,断言 JSON-RPC 形结果。
- 可选:`tests/ext/agent-mcp-server-smoke.mq.md`。
---
## 5. GAP-04 · 同寿副端口
### 5.1 关闭策略(优先)
GAP-01 + GAP-02 挂在**同一** `app.listen` → **不实现副端口**,文档宣布 GAP-04 关闭。
### 5.2 备选 API(仅当必须隔离)
```markdown
*应用 = > `应用`.listen host=127.0.0.1 port=18081 also_port=7432 also_routes=`中继表`*
```
`also_routes` 仅允许 `proxy` / `invoke` 已注册子集。实现成本高,**默认不做**。
---
## 6. GAP-05 · 跨模块 `db` 与 corpus 可发现
### 6.1 `db` 句柄(扩展约定 + 运行时)
**作者约定(立即文档化):**
1. 跨模块优先传 **`url` 字符串**,调用方 `*store = > web.db url=…*` 再 `select`。
2. 若传对象:必须保留 `_type` 为插件注册名(与 `web.db` 构造一致)。
**运行时修补(H 波次):**
| 选项 | 做法 | 选用 |
|------|------|------|
| A | 跨模块返回插件对象时规范 `_type` + 全局方法表查找 | **首选**(一次修好所有插件对象) |
| B | `db.open` 只返回 `{url}` 朴素 map,禁止「裸 select」跨文件 | 文档契约;体验较差 |
金样:模块 A `open` → 返回 → 模块 B `select` 成功。
`tests/ext/web-db-cross-module-smoke.mq.md`。
### 6.2 `corpus_search` 可发现
```markdown
## corpus_search
+ `query`
+ `root`=".marqdo/agent-kb"
* > plugin.load name=agent *
** > agent_corpus_search query=`query` root=`root` **
```
或在 `# agent` / `## corpus_search` 入口统一 `ensure_plugin`(与现 `agent` 构造对齐),保证 **纯 `marqdo run` + import agent** 即可用。
**不**把 `agent_corpus_search` 搬进 `src/host/`。
### 6.3 验收
- 无显式手工 ABI 名的情况下,`marqdo run` 金样调用 `agent.corpus_search` 成功。
- 跨模块 `db.select` 金样绿。
---
## 7. 扩展库表面清单(落地时改这些文件)
| 文件 | 增补 |
|------|------|
| `ext/web/web.mq.md` · `网页.mq.md` | `## proxy` / `## invoke`;`configure` 增 `proxy`/`invoke` 列 |
| `plugins/web/src/http.rs` · `middleware.rs` · 新 `proxy.rs` / `invoke.rs` | 路由注册与流式/调用 |
| `ext/ai/agent.mq.md` · `智能体.mq.md` | `# mcp_server` · `## tool` · `## serve`;`corpus_search` ensure_plugin |
| `plugins/agent/` | MCP Server 传输 + 共享 invoke |
| `tests/ext/web-proxy-sse-smoke.mq.md` 等 | 见上 |
| `doc/roadmap/ext-web.md` | 链到 H 波次(不重开 W0–W7) |
| `public/` / Skill | 发版时补「同域 LLM 代理 / HTTP 调用 ##」短节 |
**不**新增 `lib/run` 作为核心依赖:用户业务 `##` 仍在其自己的 `lib/*.mq.md`;Marqdo 只提供 **invoke 管道**。
---
## 8. 迁移:下游旁路 → 扩展 API
| 旁路(下游) | 替换为 |
|--------------|--------|
| `llm_proxy.py` `/proxy/stream` | `app.proxy` / `configure proxy=` |
| `llm_proxy.py` `/store/*` + `marqdo run` | `app.invoke` → 用户 `##` |
| `mq_bridge.py` 仅过滤 | 用户 `##` 内 `table`/`re` 过滤,或修复后的 `corpus_search` |
| `qdagent_mcp.py` | `agent.mcp_server` + `serve` |
| `mq.sh` 双进程 | 单 `marqdo run index.mq.md`(proxy+invoke 同端口) |
---
## 9. 开放点(实现前拍板)
| # | 问题 | 默认倾向 |
|---|------|----------|
| 1 | `invoke` 的 `fn` 是否允许 `path.mq.md##标题` 字面量 | 允许但必须 `invoke_allow` 前缀 |
| 2 | MCP HTTP 首版范围 | stdio 先交;HTTP 跟一波 |
| 3 | 代理是否缓冲「非 SSE」大 body | 非流式可限长缓冲;SSE 禁止整段缓冲 |
| 4 | GAP-05 选项 A vs B | **A** |
---
## 10. 完成定义(整包)
1. 无 Python 旁路即可:浏览器同域 SSE 对话 + HTTP 触发沉淀 `##` +(可选)MCP stdio 暴露同一批 `##`。
2. 金样覆盖 proxy / invoke / cross-db / corpus / mcp-server(stdio)。
3. `doc/research/ext-hosting-gaps.md` 各 GAP 标为关闭或降级为「备选副端口不做」。
4. 发版说明指向 `ext/web` · `ext/ai` 新作者面,不指向 `scripts/*.py`。
+235
View File
@@ -0,0 +1,235 @@
# `ext/linalg` — 公式文档面(跑通即正确)
| | |
|---|---|
| 状态 | **Draft · 锁定作者面哲学与分期** |
| 日期 | 2026-09-07 |
| 父设计 | [ext-linalg.md](ext-linalg.md) |
| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) |
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
| 对照 | [stdlib-math.md](stdlib-math.md)(高中标量公式) |
---
## 0. 一句话
**`.mq.md` 里的线性代数应当读起来像一份可运行的公式讲义**:式子能跑通,就在库承诺的规则与维数下代表正确;`lib/math` 守高中边界,大学符号矩阵与更深层计算由 **`ext/linalg` 正当承担**。
---
## 1. 产品哲学
### 1.1 与 Marqdo 总原则对齐
| Marqdo | 在线性代数上的含义 |
|--------|-------------------|
| 代码即文档 | 矩阵代数段落用数学式书写,而不是 API 调用清单 |
| 标记即语法 | `$$`、中缀、`# matrix` 方法都是可读标记,不是「库胶水」 |
| 跑通可验收 | 金样 / 课堂作业:文件 exit 0 + 断言化简结果 = 式子合法 |
### 1.2 「跑通即正确」的精确定义
**不是**「任意高深定理自动证明」。
**是**在声明的能力边界内,下列任一成立则文档该段视为正确:
1. **形状层**:不相容维数的乘加在构造时硬错误(写不出可运行的坏式)。
2. **恒等式层**:文档断言的规范形(如 `(AB)^\top → B^\top A^\top`)经规则集得到。
3. **数值核对层**(可选):小 `$$` 数值阵 `explicit` 后与手算一致——验算,不是符号证明。
更高深主题(矩阵微积分、表示、特殊函数矩阵等)通过**扩展同一公式面的规则表**分期加入,而不是另起一套函数库叙事。
### 1.3 与 `lib/math` 的边界(再次锁定)
| | `lib/math` | `ext/linalg` |
|--|------------|--------------|
| 教育边界 | 高中标量公式 | 大学经典线性代数及更深(官方 ext) |
| 值类型 | `Value::Formula`(标量 AST) | `_type=matrix` / `矩阵`(MatExpr + 稠密) |
| 作者感觉 | `$$sin(x)+x$$` + `diff` / `plot` | `A*B`、`(AB)^T`、分块、分解图 |
| 是否「数学库」 | 是(stdlib) | **是数学库的官方扩展**,不是旁路工具箱 |
把大学 LA 塞进 `lib/math` ❌;在 `ext/linalg` 做大学符号计算乃至更深 ✅。
---
## 2. 两面模型:代数面 vs 计算面
文档里应能一眼分清「推导」与「动手算」。
### 2.1 代数面(默认;公式文档)
| 意图 | 写法(目标) | 语义 |
|------|--------------|------|
| 引入符号阵 | 见 §3 | 惰性 `MatrixSymbol` |
| 加减乘 | `` `C` = `A` + `B` `` · `` `P` = `A` * `B` `` | 建树 + 形状检查 |
| 转置 / 逆 | `` `At` = > `A`.T `` · `` `Ai` = > `A`.inv `` | 惰性节点 |
| 化简 / 展示 | 见 §4(默认化简策略) | 规则不动点 → ASCII / KaTeX |
| 分块 / Kronecker | 表或 `block` / `kron`(可保留具名,但结果仍是公式) | 惰性 |
**读者感受**:像在抄黑板,而不是在调 `la.mul`。
### 2.2 计算面(显式步骤;可单独成段)
| 意图 | 写法 | 语义 |
|------|------|------|
| 稠密求值 | `` `E` = > `A`.explicit `` / `la.explicit` | 展开数值 |
| 分解 | `` `f` = > la.factorize matrix=`A` kind="svd" `` | `linalg_factor` |
| 求解 / 最小二乘 | `solve` / `lstsq` | 数值解 |
| 度量 | `norm` / `cond` / `rank` / `det`(数值路径) | 标量或条件对象 |
| 作图 | `draw` / `show` | SVG / 公式卡 |
**读者感受**:「于是我们计算 / 画出…」——与纯代数叙述分段书写。
---
## 3. 目标作者语法(公式文档优先)
### 3.1 已落地(v1 中缀 / 方法)
```markdown
*`A` = > la.symbol name="A" rows=2 cols=2*
*`B` = > la.symbol name="B" rows=2 cols=2*
*`C` = `A` + `B`*
*`P` = `A` * `B`*
*`Pt` = > `P`.T*
*`s` = > `Pt`.simplify*
*`t` = > `s`.ascii*
```
数值 `$$` 矩阵可直接参与 `+` / `*`(经插件吸收为稠密叶)。
### 3.2 目标形态(文档感更强;分期实现)
**叙事理想(不必一次做完):**
```markdown
# 正规方程
令 \(A\) 为 \(m\times n\) 设计矩阵,\(b\) 为观测。
*`AtA` = > `A`.T * `A`* # 或未来更紧凑的 postfix / 混合写法
*`xty` = > `A`.T * `b`*
*`xhat` = > `AtA`.solve b=`xty`* # 计算面
```
**符号引入(减少 `la.symbol` 噪音)——候选(F2 选定一种):**
| 候选 | 例 | 利 | 弊 |
|------|----|----|-----|
| A. 构造糖 | `` `A` = > la.matrix name=A rows=m cols=n `` | 已有 `# matrix` | 仍是调用 |
| B. 维数表 | GFM 表声明符号与形状,一行绑定 | 很「文档」 | 需新约定 |
| C. `$$` 符号方言 | `$$A_{m\times n}$$` → MatExpr | 最像讲义 | 解析歧义;勿污染标量 formula |
| D. 保持 `symbol` + 短别名 | `` `A` = > la.A rows=m cols=n `` | 实现便宜 | 文档感一般 |
**锁定倾向:** 短期 **A + 默认化简(F1)**;**F2 采用 B(GFM `@` 表 + `la.declare`)**;受限 C(`$$` 符号方言)仍待评估且不得污染核心 formula。
### 3.3 明确不做(本波语法)
- 把符号 MatExpr 塞进核心 `formula::Expr`
- 发明与 Markdown 列表冲突的行首 `+` 矩阵语法
- 用未定义的 `$$矩阵A$$` 伪方言冒充已实现语义
---
## 4. 默认化简与「写出即规范」
### 4.1 策略
| 操作 | 是否自动 `simplify` | 理由 |
|------|---------------------|------|
| `ascii` / `latex` / `show` | **是(F1 done)** | 展示面应接近讲义规范形;`raw=True` 可关 |
| 中缀 `+` `*` `-` 的构造结果 | **否** | 保留用户书写结构;需要时再化简 |
| `.simplify` | 显式不动点 | 文档断言 / 金样 |
| `explicit` 前 | 可选先 simplify(F1.1) | 减少无效稠密路径 |
### 4.2 验收句式(金样)
```markdown
*`P` = `A` * `B`*
*`Pt` = > `P`.T*
*`t` = > `Pt`.ascii* # F1:无需再 .simplify 即得 B^T*A^T
1. `t` == "B^T*A^T"
> print text=ok
```
「跑通 + 断言」= 这段公式文档正确。
---
## 5. 正确性分层与错误体验
| 层 | 失败时 | 作者应看到 |
|----|--------|------------|
| 形状 | `A*B` 列行不配 | 含双方 shape 的硬错误,指向调用点 |
| 规则 | 无法化到文档期望形 | 金样失败;或 `ascii` 仍为未化简形(需补规则) |
| 插件未加载 | 中缀矩阵运算 | 提示 `ext add linalg` / `ensure_plugin` |
| 超维 | `explicit` / 分解 | 护栏错误,建议保持符号 |
---
## 6. 与实现现状的对照
| 能力 | 状态 |
|------|------|
| MatExpr 惰性树 + R1–R5 / 分块 / kron | done(L1–L3) |
| 稠密 / 分解 / 度量 / draw theme | done(L2–L6) |
| 中缀 `+` `-` `*` + `# matrix` 方法 | done(v1) |
| `ascii`/`latex`/`show` 默认 simplify | **done(F1)** |
| 更少噪音的符号引入 | **done(F2:`declare` + 表)** |
| 更紧凑转置 / 混合公式书写 | **done(F3:`T_ascii`)** |
| `explicit` 前可选 auto-simplify | **done(F3,默认开)** |
| public「如何写公式文档」 | **done(F3)** |
| 矩阵微积分等 | L7+ / 规则表扩展 |
---
## 7. 分期(公式文档面)
| 阶段 | 内容 | 出口 |
|------|------|------|
| **F1** | 展示路径默认 simplify;金样「`.T` + `ascii` → 规范形」;设计本文落地 | **done** |
| **F2** | 符号引入降噪(选定 §3.2 候选);更新 examples 使其读起来像讲义 | **done**(`declare` + `linalg-transpose`) |
| **F3** | 可选 postfix / 链式糖;`explicit` 前可选 auto-simplify;public 短文「如何写公式文档」 | **done** |
| **F4+** | 新规则(伴随、多项式矩阵…);矩阵微积分仅当明确需要 | 规则表可测 |
---
## 8. 示例叙事(目标文档骨架)
````markdown
---
import la:ext/linalg/linalg.mq.md
---
# 转置反序
*`A` = > la.symbol name="A" rows=2 cols=3*
*`B` = > la.symbol name="B" rows=3 cols=2*
*`P` = `A` * `B`*
*`Pt` = > `P`.T*
叙述:\((AB)^\top = B^\top A^\top\)。
*`t` = > `Pt`.ascii*
1. `t` == "B^T*A^T"
> print text=identity-ok
2. *
> print text=identity-fail
````
计算面示例保持 `examples/linalg-least-squares/`(`lstsq` + heatmap),与代数面示例分目录或分章节。
---
## 9. 开放问题
1. **自动 simplify 是否改变 `ascii` 金样**——凡依赖「未化简乘积串」的测试需改期望或改调 `repr_raw`(若提供)。
2. **中文 `_type=矩阵` 与展示**——方法链已 retag;view 是否统一显示英文 kind。
3. **`$$` 符号方言**——若做,必须经 `from_formula` 扩展,禁止改核心高中 formula 语义。
---
## 10. 收束
`ext/linalg` 的北极星不是「功能最多的矩阵库」,而是:
> **让大学线性代数(及更深)以可运行公式文档的形式存在于 Marqdo;跑通即在规则集内正确;计算与作图是显式步骤,不淹没代数叙述。**
+345
View File
@@ -0,0 +1,345 @@
# `ext/linalg` — 公式优先的线性代数扩展
| | |
|---|---|
| 状态 | **Draft · L0–L6 + 中缀 v1 · 公式文档面见专文** |
| 日期 | 2026-09-07 |
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
| **公式文档面** | [ext-linalg-formula-doc.md](ext-linalg-formula-doc.md)(跑通即正确 · 代数面/计算面) |
| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) |
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [view.md](view.md) · [ext-quantum-q7.md](ext-quantum-q7.md) |
| 安装(规划) | `marqdo ext add linalg`(`linalg` / `线性代数`) |
---
## 0. 一句话
**经典线性代数以「矩阵公式」为一等公民**:抽象表达式可化简、可展示、可选求值;稠密数值与分解图走 ABI 插件——**不**并入 `lib/math`,**不**挂在 `ext/quantum` 作者面。
作者面北极星见 **[ext-linalg-formula-doc.md](ext-linalg-formula-doc.md)**:跑通即正确;代数面像讲义,计算面是显式步骤。
---
## 1. 目标与非目标
### 1.1 目标
1. **公式类扩展**:在现有标量 `formula` 之上,引入 **矩阵表达式(MatExpr)**——`MatrixSymbol`、乘加、转置、逆、迹、行列式、分块、Kronecker——默认**不展开**。
2. **大规模优化**:形状检查 + 重写规则 + 惰性求值 + 分解对象复用(见 §5)。
3. **易于展示**:KaTeX 公式卡、结构 SVG(SVD/QR/消元/特征)、数值热力图;CLI 可断言的 ASCII。
4. **文档即实验**:GFM 表声明矩阵 / 步骤;`.mq.md` 可读可跑。
### 1.2 非目标(首版)
| 不做 | 原因 |
|------|------|
| 塞进 `lib/math` | 高中标量范围已锁定;大学 LA 属官方 ext |
| 复用 `quantum.*` 作者 API | 领域混淆;量子 Q7 保持量子语义 |
| 完整 SymPy / Mathematica | 规则表可控子集即可 |
| 稀疏格式 / GPU / 分布式 | 超出文档语言定位 |
| 矩阵微积分闭式(Jacobian 积木) | 记入路线图远期 |
| 在 `ext/**` 调 `host_*` | 硬约束;数值走插件名 |
---
## 2. 分层架构
```text
作者 .mq.md
│ import la:ext/linalg/linalg.mq.md
▼
L1 官方 ext(GFM + ## 包装,中英分文件)
│ plugin.load name=linalg
▼
plugins/linalg(ABI v2)
├── matexpr:符号树构造 / 重写 / latex
├── dense:稠密 f64(可选复数)运算与分解
└── draw:结构 SVG / heatmap
│
▼(可选)
核心 Value::Formula 仅保留「数值矩阵字面量」现状;
符号 MatExpr 以 **map `_type=matrix`(中文构造为 `矩阵`)** 承载,避免撑爆高中 formula AST;遗留标签 `linalg_expr` / `linalg_dense` 仍可解析。
```
### 2.1 为何 MatExpr 不直接塞进 `formula::Expr`
| 方案 | 利 | 弊 | 决策 |
|------|----|----|------|
| 扩展 `formula::Expr` | 与 `$$` 一体 | 核心膨胀;高中/大学边界糊 | ❌ |
| 插件侧表达式 + L1 对象 | 核心干净;可独立发版 | 需稳定 `_type` 与 latex 桥 | ✅ **采用** |
| 仅 list-of-list 数值 | 简单 | 无法公式优化与符号展示 | ❌ 仅作 `explicit` 结果 |
**既有** `formula::Expr::Matrix`(数值 `$$`)继续服务量子门 / 小例子;`ext/linalg` 通过 `la.matrix` / `la.from_formula` 吸收为稠密叶子。
### 2.2 与量子的边界
| | `ext/linalg` | `ext/quantum` Q7 |
|--|--------------|------------------|
| 域 | 经典实/复矩阵 | 态 / 密度 / Pauli |
| Kronecker | 经典 ⊗ | 复合量子系统 |
| 图 | SVD/QR/GE/heatmap | hinton/city/qsphere/… |
| 复用 | 插件**私有**可共享 Jacobi/SVD 代码 | 作者面 API **分离** |
---
## 3. 运行时对象(锁定草案)
全部经插件构造,L1 返回 **map**(`_type` 稳定,金样可断言):
| `_type`(英) | 中文标签 | 字段(最小) | 含义 |
|---------------|----------|--------------|------|
| `linalg_expr` | `线性式` | `repr`(S-expr 或内部 id)、`shape`=`[m,n]` 或符号维、`latex`、`ascii` | 抽象矩阵公式 |
| `linalg_dense` | `稠密阵` | `rows`, `cols`, `data`(行主 list[list])、`dtype`=`real`\|`complex` | 显式数值 |
| `linalg_factor` | `分解` | `kind`=`lu`\|`qr`\|`svd`\|`eig`\|`chol`,因子字段,`latex`,可选 `svg` | 分解结果 |
| `linalg_svg` | — | `kind`, `svg` 文本 | 与 quantum_svg 同构展示约定 |
| `linalg_solve` | `求解` | `x`, `residual`, `method` | 线性系 / 最小二乘 |
形状:`shape` 允许整数或符号维名(字符串 `"n"`);不相容 → 硬错误。
---
## 4. 作者面 API(英文 `ext/linalg/linalg.mq.md`)
中文镜像:`ext/linalg/线性代数.mq.md`(`矩阵` / `化简` / `求值` / `绘图`…)。
### 4.1 构造
```markdown
# matrix
## symbol
+ `name`
+ `rows`
+ `cols`
# → linalg_expr MatrixSymbol
## eye / zeros / ones / diag
+ …
## from_list
+ `data` # list[list] 或 table
## from_formula
+ `formula` # 吸收 Value::Formula Matrix 字面量
## block
+ `blocks` # 表或嵌套 list of expr
```
文档写法偏好:
````markdown
`A` = > la.symbol name=A rows=n cols=n
`b` =
$$
\begin{pmatrix}1\\0\\0\end{pmatrix}
$$
*`b` = > la.from_formula formula=`b` *
````
作者面优先顶层 `la.symbol` / `la.mul`(`la.matrix.symbol` 无接收者会硬错误,见 [module-namespace.md](module-namespace.md) §4.3)。
### 4.2 公式代数(返回 `linalg_expr`,惰性)
| 英文 | 中文 | 语义 |
|------|------|------|
| `mul` / `add` / `sub` | `乘` / `加` / `减` | 形状检查后建树 |
| `transpose` / `T` | `转置` | |
| `inv` | `逆` | 符号逆;不立即求数值 |
| `pow` | `幂` | 整数幂 |
| `trace` / `det` | `迹` / `行列式` | 可得到标量 expr 或数值 |
| `kron` | `克罗内克` | **禁止**默认 expand |
| `simplify` | `化简` | 应用 §5 规则集 |
| `collapse` | `分块化简` | 对标 `block_collapse` |
| `latex` / `ascii` | `乳胶` / `文本` | 展示字符串 |
| `shape` | `形状` | |
链式 / 中缀(v1 已落地):
```markdown
*`C` = `A` + `B`*
*`P` = `A` * `B`*
*`Pt` = > `P`.T*
*`s` = > `Pt`.simplify*
```
运行时对双方为 `matrix` / `矩阵` / 数值 `$$` 矩阵 / 遗留 `linalg_expr` 的 `+` `-` `*` 分派到插件;结果保留左操作数 `_type` 以便中英方法链。
### 4.3 求值与分解(热路径 → 稠密)
| 英文 | 说明 |
|------|------|
| `eval` / `explicit` | 符号树 + 绑定表 → `linalg_dense`;超维硬错误 |
| `factorize` | `kind=lu\|qr\|svd\|eig\|chol` → `linalg_factor` |
| `solve` | `A`,`b`;或 `factor` + `b` |
| `lstsq` | 最小二乘 |
| `rank` / `norm` / `cond` | 数值度量 |
| `matmul` | 稠密乘(已 explicit 时) |
维数上限(草案,可配置):
| 操作 | 默认上限 |
|------|----------|
| `explicit` 稠密元素总数 | \(n\cdot m \le 10^4\)(如 100×100) |
| SVD / eig 方阵边长 | \(\le 64\)(与 quantum 密度同级) |
| 结构 SVG(无元素) | 边长示意可达数百(只画框) |
| KaTeX 完整数字阵 | \(\le 8\times 8\);更大只出摘要 + 结构图 |
### 4.4 展示
| 英文 | `kind` | 说明 |
|------|--------|------|
| `show` | — | 写入 view:优先 `latex` 公式卡 |
| `draw` | `structure` | 形状/分块矩形(drawmatrix 风格) |
| `draw` | `heatmap` / `hinton` | 数值幅度 |
| `draw` | `svd` / `qr` / `ge` / `eig` | 分解结构图(对标 LAFigureSpecs) |
| `draw` | `path`= | 可选落盘 SVG |
`show` 应对符号式**始终可用**(无需 `eval`)。
### 4.5 最小可运行示例(设计验收叙事)
````markdown
---
import la:ext/linalg/linalg.mq.md
import table:lib/table.mq.md
---
# main
*`A` = > la.symbol name=A rows=3 cols=3 *
*`x` = > la.symbol name=x rows=3 cols=1 *
*`b` = > la.mul a=`A` b=`x` *
*`s` = > la.simplify expr=`b` *
> la.show expr=`s`
`M` =
$$
\begin{bmatrix}2&0\\0&3\end{bmatrix}
$$
*`M` = > la.from_list data=[[2,0],[0,3]] *
*`f` = > la.factorize matrix=`M` kind=eig *
> la.draw factor=`f` kind=eig path=eig.svg
````
---
## 5. 公式重写与「大规模优化」(核心)
### 5.1 原则
1. **构造便宜,展开昂贵**——乘加只分配节点。
2. **形状是类型系统**——`(m×k)·(k×n)` 合法;否则错误指向调用点。
3. **化简是规则不动点**——有限规则表,可测、可文档化。
4. **expand 显式开启**——`expand=True` 才对 Kronecker / 多项式矩阵做爆炸性展开。
5. **数值路径旁路符号**——已 `explicit` 的叶子用稠密核,不再走规则。
### 5.2 v1 规则集(最小够用)
| ID | 规则 | 例 |
|----|------|-----|
| R1 | 单位元 | `I*A → A`,`A*I → A`,`A+0 → A` |
| R2 | 双逆 | `(A^{-1})^{-1} → A` |
| R3 | 转置反序 | `(AB)^\top → B^\top A^\top`,`(A^\top)^\top → A` |
| R4 | 逆转置 | `(A^{-1})^\top → (A^\top)^{-1}` |
| R5 | 结合扁平 | `MatMul` 链扁平化 |
| R6 | 分块塌缩 | 对标 `block_collapse`(乘/加在块级分配) |
| R7 | Kronecker 结合 | `(A⊗B)⊗C → A⊗B⊗C`;**不**展开成元素 |
| R8 | 标量提出 | `c*(A+B) → c*A+c*B`(可选;默认关以免树变宽) |
### 5.3 数值侧优化
| 策略 | 说明 |
|------|------|
| `factorize` 一次 | 多 RHS `solve` 复用 |
| 小阵专用核 | 2×2 / 3×3 闭式逆 / det(教学友好、可对照公式) |
| 复杂度护栏 | 超限错误信息建议「保持符号 / 降维 / 分块」 |
| 禁止静默降精度 | 病态 `cond` 可警告(stderr 或结果字段) |
---
## 6. 展示设计(效果)
### 6.1 通道
| 通道 | 符号 MatExpr | 稠密 | 分解 |
|------|--------------|------|------|
| view Structure | KaTeX `latex` 卡 | 小阵 KaTeX;大阵摘要 | 公式 + 可选 SVG |
| view Execution plots | — | heatmap SVG | `kind=svd|…` SVG |
| CLI `print` | `ascii` | `[[…],…]` 或摘要 | `svd(U,S,V)` 摘要 |
| writeback | 可选记录 latex | 可选 | 可选 |
### 6.2 LaTeX 约定
- 符号:`A`,`A^{\top}`,`A^{-1}`,`AB`,`A \otimes B`
- 数值小阵:`\begin{bmatrix}…\end{bmatrix}`
- 分块:`\begin{bmatrix} A & B \\ C & D \end{bmatrix}`
- 喂给既有 view:与 `formula-card` / KaTeX 同源路径(L1 `show` → `host_query("record_plot")` 或扩展「record_math」若已有;无则复用 writeback + plot 列表)
### 6.3 结构 SVG(教学主视觉)
对标 LAFigureSpecs / drawmatrix,**不**依赖 Matplotlib:
| `kind` | 画什么 |
|--------|--------|
| `structure` | 矩形块 + 标签(零块灰色) |
| `svd` | \(U\Sigma V^{\top}\) 块布局 + 秩分隔 |
| `qr` | 瘦/胖 QR 示意 |
| `ge` | 消元后上三角高亮 |
| `eig` | \(A=PDP^{-1}\) 或谱列表 + 对角 |
| `heatmap` | 单元填色(实数蓝红;复数幅值) |
主题:`theme=light|dark|bw`(与 quantum Q8 令牌对齐;默认 `light`)。
---
## 7. L1 / 插件 / CLI 约定
1. **`ext/linalg/**` 禁止 `host_*`**;只调 `plugin.*` 注册名(如 `linalg_simplify`)。
2. **中英分文件**,CATALOG 双 id:`linalg` / `线性代数`。
3. **`marqdo ext add linalg`**:与 web/agent/quantum 相同——优先 Release 预编译 native zip。
4. **金样**:离线、确定性;SVG 断言含关键子串或稳定 hash 前缀。
5. **依赖**:插件内自研稠密核(或慎重引入单一 crate,如 `nalgebra`——**实现期再议**;设计默认「可自研小维 + 可选 crate」)。
---
## 8. 分期(摘要;细节见路线图)
| 阶段 | 交付 |
|------|------|
| **L0** | CATALOG + ping + L1 `ensure_plugin` |
| **L1** | `matrix.symbol` / dense 构造 / `mul`·`T`·`inv` 树 + `simplify` R1–R5 + `latex`/`show` |
| **L2** | `explicit` / 小阵运算 / `solve` / `det`·`trace` 数值 |
| **L3** | 分块 + `collapse`;Kronecker 惰性 |
| **L4** | `factorize` LU/QR/SVD/eig + 结构 SVG |
| **L5** | heatmap/hinton;examples + public 文档 + skill 摘要 |
| **L6+** | 矩阵微积分 / 更大 BLAS(仅当用户明确要求);复数全路径算子 |
---
## 9. 验收标准(设计级)
1. 符号式 `(AB)^\top` 经 `simplify` 得 `B^\top A^\top`,**不**产生稠密数据。
2. 不相容形状在符号 `mul` 即失败。
3. `$$` 数值阵 → `from_formula` → `factorize kind=eig` → view 含 SVG 或 latex。
4. Kronecker 默认不 expand;显式 `expand` 受维数护栏。
5. 中英 L1 金样各至少一条;`ext add linalg` 路径文档化。
6. 与 `ext/quantum` 无作者面符号冲突。
---
## 10. 风险与开放问题
| 项 | 备注 |
|----|------|
| MatExpr 序列化 | 金样 / write:倾向可打印 S-expr 或稳定 latex+shape,避免不透明指针跨进程 |
| 与标量 `formula` 混运算 | v1:标量只作 `c*A` 系数;`det` 结果若符号则另型或降为 `formula` 文本 |
| nalgebra 等依赖 | 实现 L2 时评估二进制体积与 ABI 体积 |
| record_math vs plot | 若仅 SVG/KaTeX 字符串,可先复用 plot/writeback |
---
## 11. 一句话(收束)
**`ext/linalg` 让线性代数公式保持可优化的表达式,用规则与结构图服务文档阅读,用受控稠密核服务验算——公式优先,数值可选,展示分层。**
+1 -1
View File
@@ -210,7 +210,7 @@
- >6 qubit 稠密 ρ 的谱 / Hinton(请用态向量 API)
- Matplotlib / WebGL / 交互拖拽
- 量子线性系统算法(HHL)、QSVT 电路构造
- 把线性代数并入 `lib/math`
- 把线性代数并入 `lib/math`(经典公式优先的 LA 见规划 [ext-linalg.md](ext-linalg.md),作者面与 quantum 分离)
---
@@ -0,0 +1,74 @@
# 解决 1:路由与 `/admin` 前缀可让出
| | |
|---|---|
| 问题 | [研究 §1](../../research/ext-web-customization-limits.md#1-路由与路径被框架强占) |
| 优先级 | **P0** · 波次 **C0** |
| 触点 | `plugins/web/src/lib.rs`(`normalize_route_path`、`web_app_new`、redirect)· `plugins/web/src/http.rs`(admin 路由挂载、login redirect)· `ext/web/web.mq.md` / `网页.mq.md` |
---
## 1. 目标
1. 关闭内置后台后,**整段前缀可被站点路由占用**(含自研 `/admin`)。
2. 开启内置后台时,前缀**可配置**(默认仍 `/admin`),登录成功/登出落地页可配置。
3. `app.route` / `app.redirect` 只禁止**当前生效**的框架保留段,不再永久霸占 `/admin`。
---
## 2. 作者 API(草案)
```markdown
*应用 = > web.app page=`首页` db=`库` admin=False*
# 或:仍用内置 CRUD,但挂到旁路前缀 + 自定义回跳
*应用 = > web.app page=`首页` db=`库` admin=True*
*应用 = > `应用`.auth users=`用户表` admin_prefix="/desk" login_redirect="/desk" logout_redirect="/desk/login"*
```
| 参数 | 默认 | 含义 |
|------|------|------|
| `admin` / `后台` | `False` | `False`:**不注册**任何内置 admin HTTP 路由 |
| `admin_prefix` / `后台前缀` | `"/admin"` | 内置 CRUD + 登录页挂载根;仅 `admin=True` 时生效 |
| `login_redirect` / `登录回跳` | `{admin_prefix}` | 登录成功 303 目标 |
| `logout_redirect` / `登出回跳` | `{admin_prefix}/login` | 登出后目标 |
中文别名与英文一一对应,写进 `网页.mq.md`。
---
## 3. 插件改动点
| 改动 | 说明 |
|------|------|
| `normalize_route_path(app)` | reserved 列表改为:`/_form`、`/_part`、`/static` + **当前** `admin_prefix`(仅当 `admin=True`) |
| `listen` 路由表 | `admin=False` → **不** `.route("/admin…")`;为真则用 `admin_prefix` 拼路径 |
| `admin_login_post` / `admin_logout` | 使用配置的 redirect,禁止写死 `"/admin"` |
| `web_app_redirect` | 校验目标时用同一套动态 reserved,允许指向已让出的 `/admin` |
| disabled 文案路径 | 删除「挂路由但只显示 Admin is disabled」;无路由则 404 或落入站点自定义页 |
---
## 4. 兼容策略
- 缺省参数下:现有 `examples/web-site`、`web-net-site`、`marqdo-blog` 行为不变(仍 `/admin` + 跳 `/admin`)。
- 文档明确:`admin=False` 后若仍要登录能力,用 §3 的通用 `auth`/`gate`,不必再依赖内置 admin 壳。
---
## 5. 验收
| 金样 / 手工 | 期望 |
|-------------|------|
| `admin=False` + `route path="/admin/news"` | 注册成功;GET 渲染站点页,**不是** Admin is disabled |
| `admin_prefix="/desk"` | 内置登录在 `/desk/login`;成功跳 `login_redirect` |
| 默认 `admin=True` 无新参数 | 与现网一致 |
| `redirect` 到已让出的 `/admin` | 允许 |
---
## 6. 过渡期 → 已落地
~~继续用 `/desk` 旁路 + JS 调 `/admin/login`。~~
**C0 已落地(2026-09):** `admin=False` 可直接 `route path="/admin/…"`;或 `admin=True` + `admin_prefix="/desk"` + `login_redirect` / `logout_redirect`。见金样 `tests/ext/web-c0-admin-prefix.mq.md`。
@@ -0,0 +1,72 @@
# 解决 2:`SHELL_CSS` 可关 / 可分层
| | |
|---|---|
| 问题 | [研究 §2](../../research/ext-web-customization-limits.md#2-内置-shell_css-难以彻底覆盖) |
| 优先级 | **P1** · 波次 **C2** |
| 触点 | `plugins/web/src/render.rs`(`SHELL_CSS`、`<style>` 拼接)· page/app 元数据 · `ext/web` 样式装配 |
---
## 1. 目标
1. 站点主题可选择:**不要**框架栅格/卡片默认,或只要 reset 级变量。
2. 壳 CSS 与主题 CSS 的级联顺序**可声明、可文档化**。
3. 默认仍注入完整壳(兼容旧站);新主题显式 `shell_css=off` 即可干净起步。
---
## 2. 作者 API(草案)
```markdown
*应用 = > web.app page=`首页` … shell_css="minimal"*
# 或页面级覆盖
*页 = > `页`.meta …* # 或 page 选项 shell_css=
```
| 值 | 行为 |
|----|------|
| `full`(默认) | 现网 `SHELL_CSS` 全文 |
| `minimal` | 仅 `:root` 变量 + `body` margin/字体;**不含** `has-sidebar` 双列栅格与卡片表单皮肤 |
| `off` / `none` | 不注入框架壳样式;只输出站点 `style` / 外链 CSS |
级联顺序锁定为文档约定:
1. (可选)框架 `SHELL_CSS`
2. 站点全局 style 表 / `site.css`
3. 页面级 style
禁止再出现「主题写在 extra,却被同特异性壳规则在小屏打穿且无媒体查询」而无开关可关的情况。
---
## 3. 插件改动点
| 改动 | 说明 |
|------|------|
| 拆分 `SHELL_CSS` | `SHELL_VARS` / `SHELL_LAYOUT` / `SHELL_WIDGETS` 三段;`full`=`all`,`minimal`=vars(+极简 layout) |
| `render` 读 `app.shell_css` / `page.shell_css` | 页面覆盖应用 |
| 为 `has-sidebar` 布局加基础媒体查询 | 即使 `full`,小屏改为单列(减轻幽灵双列);`minimal`/`off` 不负责响应式 |
---
## 4. 兼容策略
- 默认 `full`:视觉与现网一致。
- Tutorial 增加一节「品牌主题请用 `shell_css=minimal|off`」。
---
## 5. 验收
| 场景 | 期望 |
|------|------|
| `shell_css=off` + 站点只写单列 grid | 响应里**无** `grid-template-columns:14rem` |
| `minimal` | 有 CSS 变量;无 `.content.cards article` 边框默认(或等价皮肤段) |
| 默认示例站 | HTML 仍含完整壳 CSS |
---
## 6. 过渡期 → 已落地
**C2 已落地(2026-09):** `shell_css=full|minimal|off`;页面/应用可设;`full` 含 `@media (max-width:720px)` 单列。金样 `tests/ext/web-c2-shell-layout.mq.md`。
@@ -0,0 +1,72 @@
# 解决 3:鉴权 / 门禁可配置且行为一致
| | |
|---|---|
| 问题 | [研究 §3](../../research/ext-web-customization-limits.md#3-鉴权--门禁模型偏固定) |
| 优先级 | **P0** · 波次 **C1**(依赖 [01](01-routes-and-admin-prefix.md) 的 prefix) |
| 触点 | `plugins/web/src/http.rs`(`rbac_middleware`、`path_matches`、login 表单)· `lib.rs`(`web_app_auth` / `web_app_gate`)· `ext/web` |
---
## 1. 目标
1. **未登录策略一致**:可配置 `redirect`(303 登录)或 `forbid`(403),对任意 gate 路径生效,不再「仅 `/admin*` 会跳登录」。
2. **匹配语义清晰**:支持精确路径、前缀、以及排除列表;`/desk` 默认**不**误伤 `/desk/login`。
3. 默认 admin gate 使用 **路径段边界**(`/admin` 与 `/admin/…`),不匹配 `/admin-publish`。
4. 登录 URL、表单 `action`、成功/失败回跳均可配置(与 C0 对齐)。
---
## 2. 作者 API(草案)
```markdown
*应用 = > `应用`.auth users=`用户表` login_path="/desk/login" login_redirect="/desk"*
*应用 = > `应用`.gate path="/desk" roles="admin" match="prefix" on_deny="redirect" exclude="/desk/login"*
```
| 字段 | 说明 |
|------|------|
| `login_path` | 登录页 URL(GET 表单 + POST 处理);默认 `{admin_prefix}/login` |
| `match` | `exact` \| `prefix`(默认对自定义 gate 建议 `prefix` + `exclude`) |
| `on_deny` | `redirect` \| `forbid`;`redirect` 时跳 `login_path`(可带 `?next=`) |
| `exclude` | 逗号分隔或表列:匹配前缀时放行的路径 |
`auth` 注册默认 gate 时:
- 使用 `{admin_prefix}` + 段边界,**不要** `starts_with("/admin")` 裸前缀。
- 自动把 `login_path` 加入放行列表。
---
## 3. 插件改动点
| 改动 | 说明 |
|------|------|
| `path_matches` | 增加 `exact`;`prefix` 要求下一字符为 `/` 或结尾;可选 exclude |
| `rbac_middleware` | 按 gate 的 `on_deny` 分支;通用放行 `login_path`,不写死 `/admin/login` |
| 登录 HTML | `action={login_path}`;hidden `next` 可选 |
| Session/CSRF | 短期仍用框架实现;文档标明字段名;中期再开放 `login_form` 自定义字段映射(非本波次必做) |
---
## 4. 兼容策略
- 未传新字段:行为对齐现网(`/admin*` → redirect 登录;其它自定义 gate → 403)。
- 新增金样:`/desk` gate + `/desk/login` 可匿名打开。
---
## 5. 验收
| 场景 | 期望 |
|------|------|
| visitor 访问 `/desk`(`on_deny=redirect`) | 303 → `/desk/login`,不是 403 |
| visitor 访问 `/desk/login`(exclude) | 200 登录页 |
| `/admin-publish` 无显式 gate | **不**被默认 admin gate 拦住 |
| 旧站仅 `app.auth` | 仍保护 `/admin*` |
---
## 6. 过渡期 → 已落地
**C1 已落地(2026-09):** `auth` 默认段边界 prefix + `on_deny=redirect` + 排除 `login_path`;自定义 `gate` 可设 `match` / `on_deny` / `exclude`。金样 `tests/ext/web-c1-gates.mq.md`;单元测试 `http::gate_tests`。
@@ -0,0 +1,69 @@
# 解决 4:样式表作者体验
| | |
|---|---|
| 问题 | [研究 §4](../../research/ext-web-customization-limits.md#4-样式作者体验受限) |
| 优先级 | **P2** · 波次 **C3** |
| 触点 | 表单元格表达式(T5)· `ext/web` style 装配 · 教程 / Skill · 可选校验 |
---
## 1. 目标
1. 含 `/`、`,`、括号的 CSS 值**不易被静默算坏**。
2. 复杂选择器 / `@keyframes` / 多层 media 有**官方推荐写法**(表内 vs 外链 vs raw 块)。
3. 与壳 CSS 的层叠关系在文档中一句话写清(并链到 [02](02-shell-css.md))。
---
## 2. 作者 API / 约定(草案)
### 2.1 立即固化的文档约定(可不改代码)
| 规则 | 说明 |
|------|------|
| 含 `/` 的值必须引号 | `"1 / 5"`、`"image/png"`(已有;Skill/教程加醒目反例) |
| 复杂皮肤优先外链 | `static/theme.css` + `page.head` / `app.icons` 同类资源表 |
| `@keyframes` / 长 media | 放外链 CSS,不塞进 GFM 单元格 |
| 调试 | `shell_css=off` 后只看主题文件,避免同页双源 |
### 2.2 产品增强(C3)
| 能力 | 说明 |
|------|------|
| `style` 装配时对可疑单元格告警 | 未加引号且含 `/` → listen/assemble 警告或硬错误(可开关) |
| 可选 `##` raw CSS 块绑定 | 例如页面附属 ````css` 具名块,**不经**表表达式求值 |
| 文档示例 | `min-width` + `max-width` 外链表;引用 [table-cell-expressions.md](../table-cell-expressions.md) |
---
## 3. 插件 / 核心改动点
| 改动 | 说明 |
|------|------|
| web style 编译 | 可选 `strict_css_cells=True`:裸 `/` 报错 |
| (可选)`web_page_css_raw` | 把文本 CSS 追加到页面,跳过 T5 |
| Skill `marqdo` / tutorial 14 | 增加「样式踩坑」小节 |
---
## 4. 兼容策略
- 默认不硬错误(避免打碎旧表);新 scaffold 默认 `strict_css_cells` 或文档强制引号。
- 不把完整 CSS 语法塞进表格方言——复杂内容走文件。
---
## 5. 验收
| 场景 | 期望 |
|------|------|
| 文档反例 `grid-column` 裸 `1 / 5` | 在 strict 模式下失败或警告 |
| 外链 `theme.css` + `shell_css=off` | 无壳栅格串扰 |
| 现有 web 示例 | 默认模式仍绿 |
---
## 6. 过渡期 workaround
全部敏感值加引号;响应式与 keyframes 只写在 `static/*.css`;小屏问题优先关壳([02](02-shell-css.md))再调主题。
@@ -0,0 +1,85 @@
# 解决 5:页面壳与插槽松绑
| | |
|---|---|
| 问题 | [研究 §5](../../research/ext-web-customization-limits.md#5-页面壳与插槽约定僵硬) |
| 优先级 | **P1** · 波次 **C2/C4** |
| 触点 | `plugins/web/src/render.rs`(body class、四区 HTML)· page 槽位装配 · nav 组件表 |
---
## 1. 目标
1. 作者可选**非侧栏栅格**布局,而不必用 CSS 硬怼掉 `has-sidebar`。
2. 侧栏存在 ≠ 强制桌面双列;提供 stacked / bare 等预设。
3. 为「条件导航」留扩展点(先文档 + 简单 hook,完整运行时条件可后置)。
---
## 2. 作者 API(草案)
```markdown
*首页 = > web.page … layout="stacked"*
*应用 = > web.app page=`首页` … layout="bare"*
```
| `layout` | DOM / class | 说明 |
|----------|-------------|------|
| `sidebar`(默认,有 side 槽时) | `body.has-sidebar` | 现网行为 |
| `stacked` | `body.layout-stacked`;side 在 main 上或折叠区 | 单列流式,适合杂志/营销 |
| `bare` | 无 top/side/foot 强制栅格;只渲染 `main`(+ 显式槽) | 登录页、落地页 |
| `rail`(可选) | 保留站点已有 `has-rail` 约定并文档化 | 避免「只有首页有 class」 |
规则:**有 side 组件但 `layout=stacked|bare` 时,不自动加 `has-sidebar`。**
---
## 3. 插件改动点
| 改动 | 说明 |
|------|------|
| `render` 读 `page.layout` / `app.layout` | 决定 body class 与 HTML 骨架 |
| `SHELL_LAYOUT`(见 [02](02-shell-css.md)) | 为 `layout-stacked` / `layout-bare` 提供最小样式;`shell_css=off` 时不注入 |
| Nav 表 | 短期保持声明式;文档说明「条件项用两套 nav 组件 + 媒体查询隐藏」 |
| 中期 hook(非阻断) | `navigate` 已有字段可扩展 `when`/`media` 列(单独 RFC) |
---
## 4. 兼容策略
- 未设 `layout`:有 side → 与现网 `has-sidebar` 相同。
- 金样增加 `layout=bare` 登录页(可与 C0 自研 `/desk/login` 共用)。
---
## 5. 验收
| 场景 | 期望 |
|------|------|
| 有 side + `layout=stacked` | body **无** `has-sidebar`;无 `14rem` 双列(在 full 壳下用 stacked 规则) |
| `layout=bare` | 输出不含 `<aside class="side">`(或 empty 不占栅格) |
| 默认站 | 不变 |
---
## 6. 过渡期 → 已落地
**C2 已落地(2026-09):** `layout=sidebar|stacked|bare|rail`;有 side 时 `stacked`/`bare` 不再强制 `has-sidebar`。金样 `web-c2-shell-layout`。
**C4 已落地(2026-09):** 导航 / 侧栏 / 页脚绑定表可选列:
| 列 | 说明 |
|----|------|
| `媒体` / `media` | CSS media;不匹配时 `display:none`(生成 `nav-mq-*` + `@media not …`) |
| `当` / `when` | `hide` 省略;`auth` / `guest` 按登录态过滤;空 = 总是显示 |
```markdown
| 属性 | 值 | 样式 | 媒体 | 当 |
|------|-----|------|------|-----|
| Home | / | | | |
| Menu | /m | | (max-width: 720px) | |
| Admin | /admin | | | auth |
| Login | /login | | | guest |
```
Listen 渲染时写入 `_logged_in` / `_nav_user`(来自 session)。离线 `page.render` 可自行 `table.put` `_logged_in`。金样 `web-c4-nav-when`。
@@ -0,0 +1,67 @@
# 解决 6:后台 CRUD 与表单能力边界
| | |
|---|---|
| 问题 | [研究 §6](../../research/ext-web-customization-limits.md#6-后台-crud-与表单能力边界) |
| 优先级 | **P3** · 随 C0 文档化;增强可选 |
| 触点 | `plugins/web/src/http.rs` / `form.rs`(内置 admin)· 站点自研页 + `db.*` · `/_form` |
---
## 1. 目标
1. **产品叙事澄清**:内置 `/admin`(或可配置前缀)= 通用表浏览器,**不是** CMS;关则彻底让路(见 [01](01-routes-and-admin-prefix.md))。
2. 自研后台的推荐路径写清楚:`page` + `form` + `db` + gate,而不是改插件壳。
3. 对「链接前缀 / new / edit」给出约定或薄辅助,减少前端状态机拼装。
---
## 2. 作者 API / 文档(草案)
### 2.1 推荐架构(文档为主)
| 需求 | 做法 |
|------|------|
| 产品级编辑器、专栏联动 | 自研 `# page` + 组件;写库用 `db.insert`/`update`;鉴权用 `gate` |
| 简单表维护 | 开 `admin=True`(可换前缀) |
| 关内置仍要 CRUD | 自研列表/编辑页;**不要**依赖 disabled 壳 |
### 2.2 可选薄增强(非 CMS)
| 能力 | 说明 |
|------|------|
| `form` 支持 `mode=new\|edit` 查询参数约定 | 文档 + 示例;必要时 `web.form` 读 `id`/`new` |
| `list` 组件 `link_prefix` | 已有则补示例;缺失则加一列「详情路径模板」 |
| Markdown 字段 | 继续「存库 + 前台渲染」;分栏编辑器保持外挂 JS(明确不做进 ABI) |
---
## 3. 插件改动点
| 改动 | 优先级 |
|------|--------|
| C0:disabled 不占路径 | 必需(属 [01](01-routes-and-admin-prefix.md)) |
| 示例 `examples/web-custom-desk/` | 展示自研列表/编辑,零内置 admin |
| form 查询参数助手 | 可选 |
---
## 4. 兼容策略
- 不扩展内置 admin 成 CMS(避免范围爆炸)。
- Tutorial 增加「何时用内置 admin / 何时自研」。
---
## 5. 验收
| 场景 | 期望 |
|------|------|
| 文档 + 示例 desk | 无 `/admin` 也能完成一文增删改 |
| 内置 admin 金样 | 仍绿 |
---
## 6. 过渡期 workaround
自研 `/desk` + 调用 `/_form` 或直接 DB API;复杂编辑器继续外挂 JS。
@@ -0,0 +1,71 @@
# 解决 7:静态资源与脚本生命周期
| | |
|---|---|
| 问题 | [研究 §7](../../research/ext-web-customization-limits.md#7-静态资源与脚本生命周期) |
| 优先级 | **P2** · 波次 **C3** |
| 触点 | `web_page_head` / `web_head` · `render.rs` head 输出 · static 挂载 · [web-assets-and-images.md](../web-assets-and-images.md) |
---
## 1. 目标
1. 默认脚本加载方式**不假设**作者手写 IIFE 抢在 DOM 前执行成功;提供 `defer` / `module` 一等约定。
2. 静态资源变更可发现:文档化 `?v=`,并提供可选自动指纹或 listen 时 mtime 查询参数。
---
## 2. 作者 API(草案)
Head 资源表扩展列(向后兼容):
| 列 | 说明 |
|----|------|
| `rel` / `关系` | 已有;`script` / `module` |
| `defer` / `推迟` | `真` → `<script defer>`(**建议默认对 script 为真**) |
| `async` / `异步` | 可选 |
| `version` / `版本` | 非空则自动追加 `?v=` |
```markdown
`头` =
| 关系 | 地址 | 推迟 | 版本 |
|------|------|------|------|
| script | /static/theme.js | 真 | 2026-09-04 |
| module | /static/desk.js | 真 | 3 |
```
全局:`app.asset_version="2026-09-04"` 为所有 static 链接统一 bump(可选)。
---
## 3. 插件改动点
| 改动 | 说明 |
|------|------|
| head 渲染 | 尊重 defer/async;`module` → `type="module"`(已有则核对) |
| 默认 | 新建 scaffold 的 script 行带 `defer` |
| (可选)`asset_version` | listen 时重写 head / 页面内 static URL |
| 文档 | 「禁止在同步 head 脚本里直接 `getElementById` 主节点;用 defer 或 `DOMContentLoaded`」 |
---
## 4. 兼容策略
- 旧表无 `defer` 列:保持现网同步行为(或仅对 scaffold/新文档默认 defer,避免静默改变旧站时序)。
- 更安全:缺省仍同步;**Skill 与 scaffold 默认写 defer=真**。
---
## 5. 验收
| 场景 | 期望 |
|------|------|
| defer 脚本读 DOM | 登录跳转逻辑在 DOM 就绪后执行 |
| `version` 列 | HTML 中出现 `theme.js?v=…` |
| 旧示例无新列 | 仍通过 |
---
## 6. 过渡期 workaround
脚本改 `type=module` 或放 body 末;手动 `?v=` bump;登录逻辑用 `DOMContentLoaded`。
@@ -0,0 +1,68 @@
# 解决 8:扩展与部署耦合
| | |
|---|---|
| 问题 | [研究 §8](../../research/ext-web-customization-limits.md#8-扩展与部署耦合) |
| 优先级 | **P3** · 文档 + 发布流程 |
| 触点 | `marqdo ext add web` · ABI 版本 · Docker/发布说明 · [ext-cli.md](../ext-cli.md) · [marqdo-release](../../../.cursor/skills/marqdo-release/SKILL.md) |
---
## 1. 目标
1. 站点作者**不必 fork 插件**才能完成 P0/P1 定制(把能力收进官方参数,见 01–05)。
2. 版本耦合可预期:changelog / 扩展清单标明「web 插件需 ≥ x.y.z」。
3. 升级路径文档化:二进制、`.marqdo-ext`、Docker 镜像三者对齐检查。
---
## 2. 作者 / 运维约定(草案)
| 约定 | 说明 |
|------|------|
| 定制优先走 `.mq.md` 开关 | `admin_prefix`、`shell_css`、`layout`、`gate`… 进官方 API 后,禁止文档再教「改 plugins/web」 |
| 兼容性矩阵 | 在 [web-net-capabilities.md](../web-net-capabilities.md) 或本目录维护「Marqdo ↔ libweb 最低版本」表 |
| `marqdo ext add web` | 安装后打印当前插件路径与版本;与 CLI 版本不符时警告 |
| Docker | 示例 Dockerfile 注释:升级需同时换 `marqdo` 与 `ext add` 产物 |
| 样式引号等行为变更 | 写入 CHANGELOG **Breaking / migration** 小节(如 0.3.2 T5) |
---
## 3. 工程改动点
| 改动 | 说明 |
|------|------|
| 插件/Crate 版本可见 | `web_listen` 或 `ext list` 显示 web ABI/包版本 |
| CI | 金样使用仓库内 `plugins/web`;发布技能检查 VSIX/CLI/插件三件套 |
| 研究→设计→路线图 | C0–C4 进 [ext-web roadmap](../../roadmap/ext-web.md),避免只活在私有 fork |
---
## 4. 兼容策略
- 不承诺插件源码级稳定 API;承诺 **`.mq.md` 作者 API** 在小版本尽量兼容,破坏性变更进 CHANGELOG。
- Fork 插件仅作为「官方尚未交付」的临时手段,并在 issue/路线图留归还项。
---
## 5. 验收
| 场景 | 期望 |
|------|------|
| 升级说明文档 | 运维按清单升级后 web 金样通过 |
| C0–C2 落地 | 自研后台场景**无需**改 `plugins/web` 源码 |
| `ext list` / 文档 | 能核对版本 |
---
## 6. 过渡期 → 预编译路径(进行中)
**目标:** 用户 `marqdo ext add web` **不必**本机 Rust。
| 交付 | 说明 |
|------|------|
| Release `marqdo-*-native-*.zip` | Windows / Linux 预编译 `web`/`agent`/`quantum` |
| Windows portable zip | 内含 `ext/` + `ext/native/*.dll` |
| `ext add` 下载回退 | 本地无 `.so`/`.dll` 时从 GitHub Release 拉取(`MARQDO_EXT_NO_DOWNLOAD=1` 可关) |
仍保留开发者 `cargo build -p marqdo_plugin_*` 路径。详见 [ext-cli.md](../ext-cli.md)。
@@ -0,0 +1,50 @@
# `ext/web` 定制修复:解决文档索引
| | |
|---|---|
| 状态 | **C0–C4 done** |
| 日期 | 2026-09-04 |
| 问题盘点 | [../../research/ext-web-customization-limits.md](../../research/ext-web-customization-limits.md) |
| 相关 | [../ext-web.md](../ext-web.md) · [../ext-web-net.md](../ext-web-net.md) · [../../roadmap/ext-web.md](../../roadmap/ext-web.md) |
对应研究文 §1–§8,每项一份解决文档:**目标 → 作者 API → 插件改动点 → 兼容策略 → 验收**。
实现时优先 **不破坏现有金样**(`tests/ext/web-*`、`examples/web-*`);新能力用显式 opt-in 参数打开。
---
## 文档一览
| # | 主题 | 文档 | 建议优先级 |
|---|------|------|------------|
| 1 | 路由与 `/admin` 前缀可让出 | [01-routes-and-admin-prefix.md](01-routes-and-admin-prefix.md) | P0 |
| 2 | `SHELL_CSS` 可关 / 可层 | [02-shell-css.md](02-shell-css.md) | P1 |
| 3 | 鉴权门禁可配置且行为一致 | [03-auth-gates.md](03-auth-gates.md) | P0 |
| 4 | 样式表作者体验 | [04-stylesheet-authoring.md](04-stylesheet-authoring.md) | P2 |
| 5 | 页面壳与插槽松绑 | [05-page-shell-slots.md](05-page-shell-slots.md) | P1 |
| 6 | 后台 CRUD / 表单边界 | [06-admin-crud-forms.md](06-admin-crud-forms.md) | P3 |
| 7 | 静态资源与脚本生命周期 | [07-assets-script-lifecycle.md](07-assets-script-lifecycle.md) | P2 |
| 8 | 扩展与部署耦合 | [08-ext-deploy-coupling.md](08-ext-deploy-coupling.md) | P3 |
---
## 波次建议(实现用)
| 波次 | 内容 | 依赖 |
|------|------|------|
| **C0** | 可配置 `admin_prefix`;`admin=False` 时不挂内置路由;`login_redirect` / `logout_redirect` | — |
| **C1** | gate:统一未登录策略;精确/前缀匹配;登录页自动放行;默认 gate 不再误伤 `/admin-*` | C0 |
| **C2** | `shell_css=off\|minimal\|full`;主题在壳前或隔离层;可选 `layout=bare` | — |
| **C3** | 样式:校验警告 / `strict`;`page.css` raw;脚本 `defer`/`async`/`version` + `asset_version` | **done** |
| **C4** | 壳:`layout` 预设(C2);条件导航 `when` / `media` | **done** |
路线图入口可在 [ext-web.md](../../roadmap/ext-web.md) 增补「定制波次 C0–C4」行,落地后再改状态。
---
## 产品原则(解法共同约束)
1. **`.mq.md` 仍是真相源** — 能声明的不进隐藏默认;新开关写在 `app` / `page` / `listen` 参数表。
2. **内置 admin 是可选产品**,不是不可替换的内核路由命名空间。
3. **默认行为保持兼容** — 现有 tutorial / 示例零改动仍能跑;新站显式打开定制。
4. **禁止**为单站需求永久硬编码第二套旁路(如永远推荐 `/desk` + JS fetch 登录)。
+1 -1
View File
@@ -268,7 +268,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
| **首列表头 `@` / `行` / `row`** | **行向** `List` of `Map`(标记列不进入字段;任意数据行数) |
| 重复表头 | 诊断错误 |
**数据单元格是表达式**(与调用实参值语法相同:裸词、数字、`` `var` ``、算术、引号串;URL / `gpt-4o-mini` 等按路径·连字符折叠为文本)。表头仍是键名文本。细则:[table-cell-expressions.md](table-cell-expressions.md)。
**数据单元格是表达式**(与调用实参值语法相同:裸词、数字、`` `var` ``、算术、引号串;URL / `gpt-4o-mini` 等按路径·连字符折叠为文本;含 `/` 的 CSS 比率等请用引号 `"1/5"`,裸 `1/5` 为除法)。表头仍是键名文本。细则:[table-cell-expressions.md](table-cell-expressions.md)。
```markdown
*`k` = secret *
+29
View File
@@ -0,0 +1,29 @@
# `lib/csv` — 逗号表(Mid M4)
| | |
|---|---|
| 状态 | **已落地(M4)** |
| 日期 | 2026-09-07 |
| 相关 | [stdlib-text-mid.md](stdlib-text-mid.md) · [stdlib-mid.md](stdlib-mid.md) |
| 导入 | `lib/csv.mq.md` · `lib/逗号表.mq.md` |
| Host | `host_csv_*`(RFC4180 最小集,无第三方 crate) |
---
## 1. API
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `parse` | `解析` | `text` | **list of maps**:首行为表头 |
| `stringify` | `序列化` | `rows` | CSV 文本(表头 = 首行 map 的键顺序) |
## 2. 方言(v1)
- 分隔符 `,`;引号 `"`;`""` 转义。
- 换行 `\n` / `\r\n`;忽略末尾空行。
- 字段内可含逗号与换行(须加引号)。
- **不**支持自定义分隔符 / 无表头模式(可后续加)。
## 3. 刻意不做
流式大文件、类型推断、Excel 方言。
+40
View File
@@ -0,0 +1,40 @@
# 设计:`lib/datetime` / `lib/日期时间`(Mid2 M7)
| | |
|---|---|
| 状态 | **已落地** |
| 日期 | 2026-09-09 |
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §2.1 |
| 宿主 | `src/host/datetime.rs` · `host_datetime_*` |
---
## 1. 时刻形状
每次返回 **map**:
| 键 | 含义 |
|----|------|
| `unix` | 秒级 Unix 戳(int) |
| `zone` | 固定偏移文本,如 `+08:00` / `+00:00` |
| `iso` | RFC3339(秒精度) |
`to_unix` 也接受裸 int 或 ISO 文本。
## 2. API
| EN | ZH | 说明 |
|----|-----|------|
| `now` | `现在` | UTC 此刻(wasm 无时钟桥则失败) |
| `from_unix` | `自戳` | `unix` + 可选 `zone` |
| `to_unix` | `成戳` | |
| `parse` | `解析` | 默认 RFC3339 / `YYYY-MM-DD[ HH:MM:SS]`;`pattern=` |
| `format` | `格式化` | `rfc3339`/`date`/`time` 或 strftime |
| `add` | `加` | `days`/`hours`/`minutes`/`seconds` |
| `in_zone` | `时区` | 同瞬间换区 |
**区名**:`+HH:MM` / `UTC` / `Z`,以及少量固定偏移别名(如 `Asia/Shanghai`)。**不做**完整 tzdb / DST。
## 3. 与 `lib/time`
`lib/time` 保留极简 unix/format/parse/sleep。日历语义用本库。
+32
View File
@@ -0,0 +1,32 @@
# `lib/encoding` — 编解码(Mid M1)
| | |
|---|---|
| 状态 | **已落地(M1)** |
| 日期 | 2026-09-07 |
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [stdlib-re.md](stdlib-re.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
| 导入 | `lib/encoding.mq.md` · `lib/编码.mq.md` |
| Host | `host_encoding_*`(无第三方 crate:标准 Base64 / hex) |
---
## 1. API
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `base64_encode` | `基64编码` | `text` | 文本(UTF-8 字节 → 标准 Base64,含 `=` 填充) |
| `base64_decode` | `基64解码` | `text` | 文本(解码后须为合法 UTF-8) |
| `hex_encode` | `十六进制编码` | `text` | 小写 hex |
| `hex_decode` | `十六进制解码` | `text` | 文本(偶数字节;合法 UTF-8) |
## 2. 与 `net.url_encode` 的边界
| 能力 | 归属 |
|------|------|
| `application/x-www-form-urlencoded` 风格 | `net.url_encode` |
| Base64 / hex | **本库** |
| 百分号编解码通用版 | 可日后加 `encoding.percent_*`;本波不做 |
## 3. 刻意不做(v1)
URL-safe Base64 变体开关、忽略空白的宽松解码、二进制 `bytes` 类型(仍经 UTF-8 文本往返)。
+24
View File
@@ -0,0 +1,24 @@
# `lib/fs` 加厚 — 复制 / 移动 / 临时文件(Mid M2)
| | |
|---|---|
| 状态 | **已落地(M2)** |
| 日期 | 2026-09-07 |
| 相关 | [stdlib-path.md](stdlib-path.md) · [stdlib-mid.md](stdlib-mid.md) |
| 边界 | **文本与普通文件**;不引入 `bytes` 类型(`read_bytes` 延后) |
---
## 1. 新增 API
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `copy_file` | `复制文件` | `src`, `dest` | `None`(覆盖已存在的目标文件) |
| `move` | `移动` | `src`, `dest` | `None`(rename;跨设备失败则报错) |
| `make_temp` | `建临时` | 可选 `prefix` | 相对 `cwd`/`fs_root` 的新空文件路径文本 |
均走现有 `resolve_path` 沙箱;写操作受 `fs_write` 策略约束。
## 2. 刻意不做
目录树 `copy_tree`、原子替换、`read_bytes`、权限 chmod。
+25
View File
@@ -0,0 +1,25 @@
# 设计:`lib/fs` Mid2 加厚(M9)
| | |
|---|---|
| 状态 | **已落地** |
| 日期 | 2026-09-09 |
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §4 · [stdlib-fs-mid.md](stdlib-fs-mid.md)(M2) |
| 宿主 | `src/host/fs.rs` · `host_make_dirs` / `host_remove_tree` / `host_stat` / `host_walk` |
---
## API
| EN | ZH | 行为 |
|----|-----|------|
| `make_dirs` | `建目录树` | 递归创建(与既有 `make_dir` 同为 `create_dir_all`;显式命名) |
| `remove_tree` | `删目录树` | 仅删目录树;路径为文件则报错 |
| `stat` | `状态` | `{size, mtime_unix, is_file, is_dir}` |
| `walk` | `遍历` | **深度优先**;相对路径列表(正斜杠);含目录项;同级按名排序 |
既有 `remove` 对目录仍递归删除;`remove_tree` 拒绝文件,语义更窄。
## 刻意不做
ACL、watch、硬链接、`copy_tree`、惰性迭代器协议。
+26
View File
@@ -0,0 +1,26 @@
# `lib/hash` — 摘要与 HMAC(Mid M3)
| | |
|---|---|
| 状态 | **已落地(M3)** |
| 日期 | 2026-09-07 |
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [stdlib-secrets.md](stdlib-secrets.md) |
| 导入 | `lib/hash.mq.md` · `lib/哈希.mq.md` |
| Host | `host_hash_*`(`sha2` / `sha1` / `md-5` / `hmac`) |
---
## 1. API
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `sha256` | `哈希256` | `text` | 小写 hex |
| `sha1` | `哈希1` | `text` | 小写 hex |
| `md5` | `md5` | `text` | 小写 hex |
| `hmac_sha256` | `密钥哈希256` | `key`, `text` | 小写 hex |
输入按 **UTF-8 字节**摘要。文档标明:用于完整性标识 / 缓存键,**不是**密码存储(无 Argon2/bcrypt)。
## 2. 刻意不做
密码哈希、流式大文件哈希 API、非 UTF-8 二进制类型。
+19
View File
@@ -0,0 +1,19 @@
# 设计:`lib/html` / `lib/超文本`(Mid2 M8)
| | |
|---|---|
| 状态 | **已落地** |
| 日期 | 2026-09-09 |
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §3.2 |
| 宿主 | `src/host/html_ops.rs` · `host_html_escape` / `host_html_unescape` |
---
## API
| EN | ZH | 行为 |
|----|-----|------|
| `escape` | `转义` | `& < > " '` → 实体(`'` → `&#x27;`) |
| `unescape` | `还原` | 上述实体(含 `&#39;` / `&apos;`) |
**不做** DOM / 模板引擎。
+36
View File
@@ -0,0 +1,36 @@
# `lib/table` 集合加厚 + `lib/cli`(Mid M5)
| | |
|---|---|
| 状态 | **已落地(M5)** |
| 日期 | 2026-09-07 |
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
| 集合 | 加厚现有 `lib/table` / `lib/表`(不另开 `listx`) |
| CLI | `lib/cli.mq.md` / `lib/命令行.mq.md` |
---
## 1. 集合新增
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `sort` | `排序` | `list` | 升序列表(int/num/text 优先;其它按显示文本) |
| `sort_by` | `按键排序` | `list`, `key` | 对 **map 列表**按键值排序 |
| `unique` | `去重` | `list` | 保序去重 |
| `chunk` | `分块` | `list`, `size` | 列表的列表 |
| `zip` | `拉链` | `a`, `b` | `[[a0,b0], …]`(取较短长度) |
| `flatten` | `展平` | `list` | 一层展平 |
`reverse` 已有。
## 2. CLI
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `parse` | `解析` | 可选 `args` | map:`--k v` / `--k=v` → 文本;裸 `--flag` → `True`;位置参 → 键 `_` 列表 |
`args` 缺省时用 `sys.args`(经宿主 `argv`)。
## 3. 刻意不做
稳定自定义比较器、惰性迭代器、完整 argparse 互斥组。
+30
View File
@@ -0,0 +1,30 @@
# `lib/log` + `lib/uuid`(Mid M6)
| | |
|---|---|
| 状态 | **已落地** |
| 日期 | 2026-09-07 |
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
---
## 1. 日志 `lib/log` / `lib/日志`
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `set_level` | `设级别` | `level`(`debug`/`info`/`warn`/`error`) | `None` |
| `debug` / `info` / `warn` / `error` | `调试` / `信息` / `警告` / `错误` | `text` | 达级别则 `print` 一行 `LEVEL message`;否则无输出 |
默认级别:`info`(隐藏 `debug`)。中文级别别名:`调试`/`信息`/`警告`/`错误`。
实现:宿主记最小级别;`host_log_line` 返回待打印文本或 `None`;L1 再 `print`(接入现有 stdout / capture)。
## 2. UUID `lib/uuid` / `lib/标识`
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `v4` | `版本4` | (无) | 标准 8-4-4-4-12 小写 hex(`getrandom`) |
## 3. 刻意不做
结构化 JSON 日志、远程 sink、UUID v1/v7、yaml。
+3 -2
View File
@@ -4,7 +4,7 @@
|---|---|
| 状态 | **已实现(M1–M4)** |
| 日期 | 2026-08-05 |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [view.md](view.md) · 大学线性代数见规划 [ext-linalg.md](ext-linalg.md) |
| 导入 | `lib/math.mq.md`(英)· `lib/数学.mq.md`(中) |
| 范围 | **高中数学**(初等函数、导数、圆锥曲线、简单方程);非大学 CAS |
@@ -92,7 +92,7 @@ $$
| 代入求值 | `subs` → `num` 或公式 |
| 求解 | 一元一次 / 二次闭式;其它用数值求根并标明 |
**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、矩阵、复数完备、任意证明。
**不做(本波):** 多元方程组、极限 ε-δ、级数、积分保证、**大学线性代数**(符号矩阵表达式 / 分解 —— 见 [ext-linalg.md](ext-linalg.md))、复数完备、任意证明。数值小矩阵字面量可在 `$$` 中解析为 `formula::Matrix`,但符号 MatExpr 与分解不在 `lib/math`。
### 3.2 作图(P)
@@ -210,6 +210,7 @@ Interpreter.plots: Vec<Stringimport math:lib/math.mq.md · lib/数学.mq.md
- `$$:name` 模块级具名绑定(已废除)。
- 无名 `$$` 自动进运行时。
- 大学级数 / 完备积分 / 定理证明。
- **大学线性代数扩展**(见 [ext-linalg.md](ext-linalg.md);不在本库做符号 MatExpr)。
- 通用隐函数作图引擎。
- 3D、交互式图表库。
+172
View File
@@ -0,0 +1,172 @@
# 中层标准库(Mid Stdlib)
| | |
|---|---|
| 状态 | **M1–M6 已落地** |
| 日期 | 2026-09-07 |
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-abi.md](ext-abi.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) · **后续** [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) |
| 目标 | 在接下来数个发版周期内,把「通用编程」能力沉到 **L0.5 宿主 + L1 `.mq.md`**,减少「凡是稍有能力就必须 ABI 插件」的路径依赖 |
---
## 1. 为什么现在做
现状分层(已落地):
```text
L0 内置 print / len / split / …
L0.5 宿主原语 src/host/*(供 L1 包装,作者原则上不直调)
L1 官方库 lib/*.mq.md(嵌入二进制 / 可覆盖)
ext 官方扩展 .mq.md + 可选 cdylib(web / agent / quantum / linalg)
```
痛点:
1. **通用语言能力缺口**:`lib/text` 几乎只是 `trim/split/join`;无正则、无编解码、无哈希、无路径代数、无 CSV……日常脚本要么外联 Python,要么新开插件。
2. **插件路径过重**:ABI 插件适合**领域热路径**(量子核、公式矩阵、HTTP 服务+SQLite),不适合「再来一个 base64」。每加一个插件都要:crate、Release 资产、`ext add`、CI、WASM 缺口。
3. **扩展作者被逼进插件**:`ext/**` 禁止 `host_*`。若 L1 没有正则 / 哈希 / 路径,扩展只能 `plugin.load`,导致「库」与「原生模块」边界模糊。
4. **对照成熟语言**:Go 的 `strings` / `regexp` / `encoding/*` / `crypto` / `path/filepath`、Python 的「难写对才进 stdlib」标准——都把**通用原语**留在语言自带层,把**领域产品**留给第三方。Marqdo 的「通用」应对齐前者;`ext/` 对齐后者。
中层标准库 = **在现有 L1 之上、在官方 ext 之下**,专门补「写通用程序必备、又不该做成插件」的那一档。
---
## 2. 分层命名(本波约定)
| 名称 | 位置 | 用户导入 | 实现形态 |
|------|------|----------|----------|
| **核心 L1** | 已有 `lib/{fs,sys,time,json,net,math,…}` | 是 | 薄包装 → 已有 `host_*` |
| **中层 L1(Mid)** | 新增 / 加厚 `lib/{re,encoding,hash,path,…}` | 是(仍属 `lib/` / `std/`) | **优先**薄 `host_*` + L1;能纯 `.mq.md` 则纯库 |
| **官方 ext** | `ext/{web,agent,quantum,linalg,ai}` | 显式 `ext/` | `.mq.md`;**仅**领域热路径允许 ABI 插件 |
| **catalog / 用户库** | 发版外收录 | 各自约定 | 应能主要靠 Mid + 核心 L1 写成,**默认无插件** |
> **不**新开第三棵目录树。中层仍落在 `lib/`,用文档与路线图分期交付,避免 `lib/` vs `lib-mid/` 分裂。
---
## 3. 准入 / 不准入(宪法)
### 3.1 进入中层的条件(须同时满足多数)
| # | 条件 | 说明 |
|---|------|------|
| 1 | **跨领域高频** | 脚本、站点、智能体、教学示例都会用到 |
| 2 | **难写对或不可移植** | 正则、Unicode、密码学、路径跨平台——纯 Marqdo 成本过高 |
| 3 | **解锁「无插件写库」** | 有了它,更多 `ext/` / catalog 可用纯 `.mq.md` |
| 4 | **宿主面积极小** | 一个或少数 `host_*` + 稳定 crate;不把巨型框架链进主二进制 |
| 5 | **API 可长期冻住** | 宁可窄接口,也不提前做成第二个 Requests |
参考(外部):
- Python:[stdlib 准入](https://devguide.python.org/developer-workflow/stdlib/) 与 [Language Summit:stdlib 何用](https://blog.python.org/2023/05/the-python-language-summit-2023-what-is.html)——偏「启动器 / 新手脚本 / 难写对的协议」,而非「万物入 std」。
- Go:日常几乎离不开的 `strings`、`regexp`、`encoding/*`、`crypto`、`path/filepath`、`slices`——对标我们的 Mid 候选,而非 `database/sql` 驱动全家桶。
- 反面:PEP 594「死电池」——过窄协议、过时格式、与生态脱节的模块不要进 Mid。
### 3.2 明确不准入(继续走 ext + 可选插件)
| 领域 | 原因 |
|------|------|
| HTTP **服务端** / ASGI / 路由框架 | 产品面;已有 `ext/web` |
| SQLite / ORM / 管理后台 | 同上 |
| LLM / 智能体编排 / OKF | `ext/ai` · `ext/agent` |
| 量子线路 / 密度矩阵核 | `ext/quantum` |
| 大学线性代数 CAS / 分解可视化 | `ext/linalg`(公式文档面) |
| 完整图像 / 音视频 / ML | 体积与依赖爆炸 |
| 任意第三方云 SDK | 不属于语言 |
### 3.3 插件仍保留的边界
ABI 插件 **不废除**。规则收紧为:
```text
若能力可用「少量 host_* + lib/*.mq.md」表达 → 必须走中层,禁止新开官方插件。
若能力是领域数值核 / 长生命周期服务 / 可选重依赖 → 才允许官方插件。
```
`lib/plugin` 继续服务:本地实验、第三方原生、官方领域包。
---
## 4. 实现分工(怎么长)
```text
用户 / catalog / 官方 ext(纯 mq 优先)
│ import re:lib/re.mq.md
▼
中层 L1(.mq.md,中英分文件,除 json 类共用外)
│ **> host_re_find …**
▼
L0.5 宿主(Rust:regex / sha2 / …)
│
▼
OS / 算法库(精选 crate,默认 features 最小化)
```
| 规则 | 说明 |
|------|------|
| `ext/**` 仍禁止 `host_*` | 中层补齐后,ext 经 `lib/re` 等调用 |
| 每个新 `host_*` | 必须有 L1 包装 + 金样 + 中英对称(见 [stdlib-i18n.md](stdlib-i18n.md)) |
| 能纯 mq 的 | 例如在 `table` 上的 `sort_by` 若性能可接受,可先纯库;热路径再下沉 host |
| WASM | 新 host 须标注是否进浏览器构建;不能 WASM 的在文档标 `host-only` |
| 依赖 | 新增 crate 写进 [dependencies.md](dependencies.md) 动机;禁止「顺手」拉大型框架 |
---
## 5. 模块候选总表(按优先级波次)
完整排期与验收见 [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md)。摘要:
| 波次 | 模块(英 / 中) | 典型能力 | 主要形态 |
|------|-----------------|----------|----------|
| **M1** | `re` / `正则` · `encoding` / `编码` | match / find / replace;base64 / hex | **done** |
| **M2** | `path` / `路径` · `fs` 加厚 | join / normalize;copy / move / temp | **done** |
| **M3** | `hash` / `哈希` · `secrets` / `机密` | sha256 / hmac;token | **done** |
| **M4** | `csv` / `逗号表` · `text` 加厚 | parse / stringify;contains / replace | **done** |
| **M5** | `table` 加厚 · `cli` / `命令行` | sort / zip;flags | **done** |
| **M6** | `log` / `日志` · `uuid` / `标识` | level 日志;v4 | **done** |
| **可选(Mid1)** | `yaml` | 默认 **不做** | 见 Mid2:优先 TOML |
**Mid1 刻意延后、现已升格到 Mid2:** 日历/时区、URL 解析 —— 见 [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md)。
**仍不准入 Mid:** 连接池、异步 runtime、模板引擎、完整 `collections` 类型系统、HTTP 服务端 / SQLite(`ext/`)。
---
## 6. 与现有库的关系
| 现有 | 中层策略 |
|------|----------|
| `lib/text` | **加厚**,不另起 `strings` 英文名(保持 Marqdo 习惯);中文 `文本` |
| `lib/table` | Mid 集合算法优先挂这里或薄 `listx`;避免与 GFM 表语义打架 |
| `lib/net` | HTTP 客户端保留;编解码类能力与 `encoding` 边界写清(url 组件归谁) |
| `lib/math` | 保持**高中**;哈希 / 安全随机不进 math |
| `lib/json` | 仍只 parse/stringify/quote;CSV/YAML 另库 |
| `lib/plugin` | 不变;文档写明「通用能力请先查 Mid」 |
| `ext/*` | 逐步**改写依赖**:能改用 `lib/re` 的路由/校验,去掉不必要的原生 |
---
## 7. 文档与工程节奏
每个 Mid 波次固定流水线(与现有发版习惯对齐):
1. 本设计不变的前提下,在 roadmap 勾选该波次工作项。
2. `doc/design/stdlib-<module>.md`(可短)→ `host_*` → `lib/` 中英 → `tests/lib/*` 金样 → `public/features` 短文。
3. 更新 [stdlib-modules.md](stdlib-modules.md) 模块表。
4. **不**为 Mid 单开 SemVer 故事;随正常产品发版收进 CHANGELOG「标准库」小节。
5. 发版技能 / Release 资产:仅当新增 **必须** 随 CLI 分发的东西时改 release 脚本——Mid 默认已嵌入 stdlib,**无** native zip。
---
## 8. 成功标准(数个版本后)
1. 用 Mid + 核心 L1 **不加载任何插件**,能写:日志采集脚本、CSV 清洗、带正则的文本管线、带哈希校验的下载器、简单 CLI 工具。
2. 新的官方 **非领域** 能力默认进 `lib/`,评审时问:「能否不做成插件?」
3. `ext/web` / `ext/agent` 等仍可有插件,但依赖面写进文档:哪些能力已改走 Mid。
4. 主二进制体积与依赖可解释;WASM 可用性有清单。
---
## 9. 一句话
**中层标准库把「通用原语」沉回语言自带层,让插件专属于真正的领域引擎——这样 Marqdo 才像一门通用语言,而不是「Markdown + 一堆 .so」。**
+139
View File
@@ -0,0 +1,139 @@
# 设计:中层标准库第二波(Mid2 · M7–M10)
| | |
|---|---|
| 状态 | **Accepted · M7–M10 已落地(zip 跳过)** |
| 日期 | 2026-09-09 |
| 缺口盘点 | [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) |
| 路线图 | [stdlib-mid2.md](../roadmap/stdlib-mid2.md) |
| 宪法 | [stdlib-mid.md](stdlib-mid.md) §3(准入 / 不准入 **不变**) |
| 目标 | 在 M1–M6 之上补「日历 · URL · 配置 · HTML 安全 · fs 再厚」,仍保持宿主面积极小 |
---
## 0. 一句话
**Mid2 = 第二档通用原语,不是第二套 stdlib。** 仍落在 `lib/` + 薄 `host_*`;禁止借机引入 YAML 全家桶、HTTP 服务端、数据库。
---
## 1. 分层与禁止
| 允许 | 禁止 |
|------|------|
| 新 `lib/*.mq.md` 中英对偶 | 新开 `lib-mid2/` 目录树 |
| 少数 `host_datetime_*` / `host_url_*` / `host_toml_parse` | 为 Mid 新增 ABI 插件 |
| 加厚既有 `fs` / `encoding` / `net` / `text` | 把 `ext/web` 能力下沉进 `lib/net` 服务端 |
| TOML **只读** | 完整 YAML 1.2、任意对象反序列化 |
| HTML **转义** | 模板引擎 / CSS 选择器引擎 |
---
## 2. M7 — `datetime` + `url`
### 2.1 `lib/datetime.mq.md` / `lib/日期时间.mq.md`
| 函数(英) | 中文建议 | 行为 |
|------------|----------|------|
| `now` | `现在` | 返回结构化时刻(见下)或 ISO 文本(二选一,实现时锁定) |
| `from_unix` / `to_unix` | `自戳` / `成戳` | 秒级;可选 `ms` |
| `parse` | `解析` | 支持 RFC3339 / 常见 `YYYY-MM-DD[ HH:MM:SS]` |
| `format` | `格式化` | strftime 子集或命名样式 `rfc3339`/`date`/`time` |
| `add` | `加` | `days`/`hours`/`minutes`/`seconds` 具名 |
| `in_zone` | `时区` | IANA 名或 `+08:00`;失败 → 诊断 |
**结构化时刻(建议 map)**:`{unix, zone, iso}` 或宿主不透明柄 + `_type=datetime`。优先 **map + 稳定字段**,便于 GFM/table 协作。
**刻意不做**:农历、营业日、完整 tzdb 热更新 UI、闰秒政治。
### 2.2 `lib/url.mq.md` / `lib/地址.mq.md`(或并入 `net`)
| 函数 | 行为 |
|------|------|
| `parse` | → `{scheme, userinfo, host, port, path, query, fragment}` |
| `query_parse` | `a=1&b=2` → map(多值用列表) |
| `query_stringify` | map → query |
| `join` | base + relative(可选,可二期) |
既有 `net.url_encode` **保留**;文档写清:编码单段用 `net`/`encoding`,解析整 URL 用 `url`。
**验收**:金样解析带 query 的 HTTPS URL;往返 query。
---
## 3. M8 — `toml` + `html` + `encoding` 加厚
### 3.1 `lib/toml.mq.md` / `lib/Toml.mq.md`(或 `配置表`)
| 函数 | 行为 |
|------|------|
| `parse` | TOML 文本 → Marqdo map/list(只读) |
**不做** `stringify`(首版);需要写出时继续用 JSON。动机对齐 PEP 680:配置引导,而非通用文档格式战争。
### 3.2 HTML 转义
二选一(实现时定一):
- A:`lib/html.mq.md` · `escape` / `unescape`
- B:`text.html_escape` / `text.html_unescape`
推荐 **A**(安全语义独立可见)。
### 3.3 `encoding` 加厚
| 函数 | 行为 |
|------|------|
| `base32_encode` / `base32_decode` | RFC 4648 |
| (可选)`percent_decode` | 与 `url` 协作 |
---
## 4. M9 — `fs` 加厚
| 函数 | 行为 |
|------|------|
| `make_dirs` | 递归创建 |
| `remove_tree` | 递归删除(目录) |
| `stat` | `{size, mtime_unix, is_file, is_dir}` |
| `walk` | 返回路径列表(深度优先或广度;文档锁定) |
**不做**:权限 ACL、watch/inotify、硬链接全家桶。
---
## 5. M10 — 收口糖(可选)
| 项 | 说明 |
|----|------|
| `lib/stats` 或 `math.mean`/`median`/`stdev` | 极薄;非 pandas |
| `log` 结构化字段 | 可选 `fields=` map;非完整 slog 生态 |
| `zip` 读写 | **默认跳过**;有明确 Release 需求再开 |
---
## 6. 宿主与 WASM
| Host | WASM |
|------|------|
| `datetime` / `url` / `toml` / `html` / `fs.stat` | 尽量可进;IANA tz 数据体积需评估(可 host-only + 文档标注) |
| `fs.walk` / `remove_tree` | host-only 可接受 |
新 crate 写进 [dependencies.md](dependencies.md);禁止顺手拉大型框架。
---
## 7. 作者面风格
- 中英分文件;形参表声明全部可选并转发 `host_*`。
- 数据优先 GFM / `table`;`json` 仍只 parse/stringify/quote。
- 每波:设计短文 → host → lib → `tests/lib/*` → `public/features` 短页。
---
## 8. 完成定义(Mid2 整包)
1. 作者可用 `datetime` + `url` + `toml.parse` + `html.escape` 写配置驱动脚本,无需 foreign。
2. `fs.stat` / `make_dirs` 金样绿。
3. 研究文高优先级缺口标 closed;YAML/模板/sqlite 仍标明 won't。
4. [stdlib-modules.md](stdlib-modules.md) 总表更新;`stdlib.md` 状态改为 Mid2 进行中/完成。
+28 -9
View File
@@ -2,10 +2,10 @@
| | |
|---|---|
| 状态 | **已落地**:text/table/fs/sys/time/json/net/math/foreign/**plugin** |
| 日期 | 2026-08-07 |
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精 |
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
| 状态 | **核心已落地**;**Mid M1–M6 已落地**;**Mid2 规划中** · [stdlib-mid2.md](stdlib-mid2.md) / [roadmap/stdlib-mid2.md](../roadmap/stdlib-mid2.md) |
| 日期 | 2026-09-08 |
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精;**通用能力优先 Mid,插件留给领域核** |
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-mid.md](stdlib-mid.md) · [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
---
@@ -15,12 +15,27 @@
| 模块族 | 英文库 | 中文库 | 状态 |
|--------|--------|--------|------|
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有(`put`/`改` + list/map;见 [stdlib-table.md](stdlib-table.md)) |
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 |
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 + **Mid M4** 加厚 |
| **正则** | `lib/re.mq.md` | `lib/正则.mq.md` | **Mid M1** |
| **编解码** | `lib/encoding.mq.md` | `lib/编码.mq.md` | **Mid M1** + Mid2 M8 base32 |
| **路径** | `lib/path.mq.md` | `lib/路径.mq.md` | **Mid M2** |
| **哈希** | `lib/hash.mq.md` | `lib/哈希.mq.md` | **Mid M3** |
| **机密** | `lib/secrets.mq.md` | `lib/机密.mq.md` | **Mid M3** |
| **逗号表** | `lib/csv.mq.md` | `lib/逗号表.mq.md` | **Mid M4** |
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有 + Mid M4/M5:`sort`/`unique`/`zip`/… |
| **命令行** | `lib/cli.mq.md` | `lib/命令行.mq.md` | **Mid M5** |
| **日志** | `lib/log.mq.md` | `lib/日志.mq.md` | **Mid M6** + Mid2 M10 `fields=` |
| **标识** | `lib/uuid.mq.md` | `lib/标识.mq.md` | **Mid M6** |
| **日期时间** | `lib/datetime.mq.md` | `lib/日期时间.mq.md` | **Mid2 M7** |
| **地址** | `lib/url.mq.md` | `lib/地址.mq.md` | **Mid2 M7** |
| **配置表** | `lib/toml.mq.md` | `lib/配置表.mq.md` | **Mid2 M8** |
| **超文本** | `lib/html.mq.md` | `lib/超文本.mq.md` | **Mid2 M8** |
| **统计** | `lib/stats.mq.md` | `lib/统计.mq.md` | **Mid2 M10** |
| 浏览器效应 | `lib/browser.mq.md` | `lib/浏览器.mq.md` | WASM 客户端效应助手(GFM + helpers;勿用 `json.set` 链) |
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 + Mid M2 + **Mid2 M9**:`make_dirs` / `remove_tree` / `stat` / `walk` |
| 系统 | `lib/sys.mq.md` | `lib/系统.mq.md` | 已有(含 `load_dotenv`) |
| 时间 | `lib/time.mq.md` | `lib/时间.mq.md` | 已有 |
| JSON | `lib/json.mq.md` | **同文件** | 已有(含 `quote`) |
| JSON | `lib/json.mq.md` | **同文件** | **仅** parse / stringify / quote;集合请用 table / GFM |
| 网络 | `lib/net.mq.md` | `lib/网络.mq.md` | 已有(HTTPS + headers) |
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | 已有 |
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | 已有 |
@@ -28,7 +43,11 @@
| **自写回** | `lib/writeback.mq.md` | `lib/自写回.mq.md` | **已有**(Jupyter 式输出写回) |
| **子任务** | `lib/subtask.mq.md` | `lib/子任务.mq.md` | **已有**(OS 子进程 + KillOnDrop) |
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` — 见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
官方可选扩展(**非** stdlib):`ext/llm` · `ext/agent` · `ext/web` · `ext/quantum` · `ext/linalg` — 见各 `ext-*.md`。
**中层已落地:** M1–M6(含 log / uuid)— 见 [stdlib-mid.md](stdlib-mid.md) · [stdlib-log-uuid.md](stdlib-log-uuid.md)。
**Mid2:** **M7–M10 done**(datetime / url / toml / html / base32 / fs++ / stats / log.fields;zip 跳过)— [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-stats-log.md](stdlib-stats-log.md)。
设计细节:[stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md)。
+33
View File
@@ -0,0 +1,33 @@
# `lib/path` — 路径代数(Mid M2)
| | |
|---|---|
| 状态 | **已落地(M2)** |
| 日期 | 2026-09-07 |
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
| 导入 | `lib/path.mq.md` · `lib/路径.mq.md` |
| Host | `host_path_*`(`std::path`;无 I/O、不经 `fs_root`) |
---
## 1. API
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `join` | `拼接` | `a`, `b` | 文本路径 |
| `split` | `拆分` | `path` | 组件文本列表(去空段) |
| `file_name` | `文件名` | `path` | 最后一段;根路径可为空文本 |
| `parent` | `父目录` | `path` | 父路径文本;无父则 `"."` |
| `extension` | `扩展名` | `path` | 不含点;无扩展名为 `""` |
| `normalize` | `规范化` | `path` | 清理 `.` / `..`(纯字符串,不访问磁盘) |
| `is_absolute` | `是绝对` | `path` | 布尔 |
## 2. 语义
- 分隔符与绝对路径判定跟随 **宿主 OS**(Linux CI 为 `/`)。
- **不做** I/O;逃逸检查仍由 `lib/fs` 在读写时执行。
- `join`:若 `b` 为绝对路径,结果为 `b`(同 `Path::join`)。
## 3. 刻意不做(v1)
`glob`、符号链接解析、`relative_to`、Windows UNC 专项文档。
+33
View File
@@ -0,0 +1,33 @@
# `lib/re` — 正则(Mid M1)
| | |
|---|---|
| 状态 | **已落地(M1)** |
| 日期 | 2026-09-07 |
| 相关 | [stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
| 导入 | `lib/re.mq.md` · `lib/正则.mq.md` |
| Host | `host_re_*`(`regex` crate,默认 Unicode) |
---
## 1. API
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `is_match` | `匹配` | `text`, `pattern` | 布尔 |
| `find` | `查找` | `text`, `pattern` | 首个匹配文本,或 `None` |
| `find_all` | `查找全部` | `text`, `pattern` | 文本列表 |
| `replace` | `替换` | `text`, `pattern`, `with`, 可选 `count` | 文本(`count` 缺省 = 全部) |
| `split` | `拆分` | `text`, `pattern` | 文本列表 |
非法 pattern → 诊断失败(含 crate 错误信息)。
## 2. 语义
- 引擎:Rust [`regex`](https://docs.rs/regex)(无回溯引用;与 RE2 同族限制)。
- 按 **UTF-8 文本**匹配,不做字节模式。
- `find` / `find_all` 返回整段匹配(不含捕获组拆分;捕获组 v1 不做)。
## 3. 刻意不做(v1)
命名捕获、替换回调、`Regex` 对象缓存 API、字节模式。
+24
View File
@@ -0,0 +1,24 @@
# `lib/secrets` — 安全随机令牌(Mid M3)
| | |
|---|---|
| 状态 | **已落地(M3)** |
| 日期 | 2026-09-07 |
| 相关 | [stdlib-hash.md](stdlib-hash.md) · [stdlib-mid.md](stdlib-mid.md) |
| 导入 | `lib/secrets.mq.md` · `lib/机密.mq.md` |
| Host | `host_secrets_*`(`getrandom`) |
---
## 1. API
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `token_hex` | `十六进制令牌` | 可选 `n`(字节数,默认 16) | 小写 hex,长度 `2*n` |
| `token_urlsafe` | `网址安全令牌` | 可选 `n`(字节数,默认 16) | URL-safe Base64(无填充) |
**不要**用 `math.random` / `math.seed` 生成令牌。
## 2. 刻意不做
密钥派生、加密/解密、密码哈希。
+30
View File
@@ -0,0 +1,30 @@
# 设计:`lib/stats` / `lib/统计` 与 `log.fields`(Mid2 M10)
| | |
|---|---|
| 状态 | **已落地** |
| 日期 | 2026-09-09 |
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §5 |
| 宿主 | `src/host/stats.rs` · `host_stats_*`;`log::line` 可选 `fields` |
---
## 1. `lib/stats`
| EN | ZH | 行为 |
|----|-----|------|
| `mean` | `均值` | 算术平均 → Num |
| `median` | `中位数` | 排序后中位;偶数取两中点平均 |
| `stdev` | `标准差` | **样本**标准差(n≥2) |
**不做** dataframe、分位数全家桶、加权统计。
## 2. `log` `fields=`
各级别函数可选 `fields`(map)。宿主拼到行尾:`INFO msg key=val …`(map 插入序)。
**不做** 远程 sink、结构化 JSON 日志协议。
## 3. zip
按路线图 **默认跳过**。
+30
View File
@@ -0,0 +1,30 @@
# `lib/text` 加厚(Mid M4)
| | |
|---|---|
| 状态 | **已落地(M4)** |
| 日期 | 2026-09-07 |
| 相关 | [stdlib-csv.md](stdlib-csv.md) · [stdlib-mid.md](stdlib-mid.md) |
| 导入 | `lib/text.mq.md` · `lib/文本.mq.md` |
| Host | `host_text_*`(Unicode 大小写 / 子串;非正则替换) |
---
## 1. 新增 API
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `contains` | `包含` | `text`, `sub` | 布尔 |
| `starts_with` | `开头是` | `text`, `prefix` | 布尔 |
| `ends_with` | `结尾是` | `text`, `suffix` | 布尔 |
| `replace` | `替换` | `text`, `old`, `new`, 可选 `count` | 文本(字面替换,非正则) |
| `to_upper` | `大写` | `text` | 文本(Unicode) |
| `to_lower` | `小写` | `text` | 文本 |
| `repeat` | `重复` | `text`, `n` | 文本 |
| `pad` | `填充` | `text`, `width`, 可选 `fill`=`" "`,可选 `align`=`left`/`right`/`center` | 文本 |
保留原有 `str_trim` / `str_split` / `str_join`(及中文去空白/拆分/拼接)。
## 2. 刻意不做
正则替换(用 `lib/re`)、完整 `format` 模板引擎。
+24
View File
@@ -0,0 +1,24 @@
# 设计:`lib/toml` / `lib/配置表`(Mid2 M8)
| | |
|---|---|
| 状态 | **已落地** |
| 日期 | 2026-09-09 |
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §3.1 |
| 宿主 | `src/host/toml_ops.rs` · `host_toml_parse`(手写子集,无 `toml` crate) |
---
## 1. API
| EN | ZH | 行为 |
|----|-----|------|
| `parse` | `解析` | TOML 文本 → map/list |
**不做** `stringify`;写出继续用 JSON。
## 2. 子集
支持:`#` 注释、基本/字面字符串、int/float/bool、标量数组、`[table]` 与 dotted key。
**不支持:** `[[array of tables]]`、内联表、TOML datetime、多行字符串。
+24
View File
@@ -0,0 +1,24 @@
# 设计:`lib/url` / `lib/地址`(Mid2 M7)
| | |
|---|---|
| 状态 | **已落地** |
| 日期 | 2026-09-09 |
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §2.2 |
| 宿主 | `src/host/url_ops.rs` · `host_url_*`(手写子集,无 `url` crate) |
---
## 1. 与 `net.url_encode`
| API | 用途 |
|-----|------|
| `net.url_encode` | **单段** form 编码(空格→`+`) |
| `url.parse` | 整 URL → `{scheme,userinfo,host,port,path,query,fragment}` |
| `url.query_parse` / `query_stringify` | 查询串 ↔ map(重复键→列表;空格→`%20`) |
## 2. 解析子集
`scheme://[userinfo@]host[:port]/path[?query][#fragment]`,含 IPv6 `[addr]`。缺 path 时规范为 `/`。
**不做**:相对 URL join、完整 WHATWG 边角、IDNA 规范化(host 原样保留)。
+10 -6
View File
@@ -2,12 +2,14 @@
| | |
|---|---|
| 状态 | **S0–S3 + L1 全模块落地** |
| 日期 | 2026-08-07 |
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) |
| 状态 | **S0–S3 + 核心 L1 + Mid M1–M6 + Mid2 M7–M10 已落地** |
| 日期 | 2026-09-09 |
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [**stdlib-mid.md**](stdlib-mid.md) · [**stdlib-mid2.md**](stdlib-mid2.md) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) |
> **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。
> **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。
> **中层标准库 Mid(M1–M6)**:已落地——[stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md)。
> **中层第二波 Mid2(M7–M10)**:已落地——[stdlib-mid2.md](stdlib-mid2.md) · [roadmap/stdlib-mid2.md](../roadmap/stdlib-mid2.md) · 缺口 [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md)。
> **`ext/` 不是 stdlib**:官方可选扩展见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
---
@@ -17,9 +19,11 @@
| 层 | 内容 |
|----|------|
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at`(`type` 可含 `map`) |
| **L1 官方库** | 仓库根目录 [`lib/`](../../lib/)(`.mq.md`);可用 `lib/…` 或别名 `std/…` 导入 |
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1 |
| **L2** | catalog / 用户站收录(随发版) |
| **L1 核心** | 已有 [`lib/`](../../lib/):fs/sys/time/json/net/math/foreign/plugin/table/text/… |
| **L1 中层(Mid)** | **已落地** re / encoding / path / hash / secrets / csv / text++ / table++ / cli / log / uuid — [stdlib-mid.md](stdlib-mid.md) |
| **L1 Mid2** | **已落地** datetime / url / toml / html / fs++ / stats / log.fields — [stdlib-mid2.md](stdlib-mid2.md) |
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1;插件仅领域热路径 |
| **L2** | catalog / 用户站收录(随发版);应主要靠核心+中层、默认无插件 |
---
+6 -3
View File
@@ -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 同步 |
+1 -1
View File
@@ -34,7 +34,7 @@
| 中 | 静态类型 / 可维护 AST | 长期改解释器不疼 |
| 中 | CLI 与打包 | 单二进制或 `npx`/等价体验 |
| 低 | 极致性能 | v0 样例很小 |
| 低 | 浏览器内运行 | 可后置 |
| 低 | 浏览器内运行 | **已后置落地规划**:见 [ADR 0002](../adr/0002-browser-marqdo-wasm.md)(WASM 解释器) |
非准则:跟风、先写再选、与「生成 OKF」强绑某一云厂商。
+5 -2
View File
@@ -121,13 +121,16 @@ url = /favicon.ico
| `媒体` | `media` | CSS media |
| `作为` | `as` | preload `as` |
| `跨域` | `crossorigin` | 空 / `anonymous` / `use-credentials` |
| `推迟` | `defer` | 经典 `script` 为真时输出 `defer`(缺省同步,兼容旧站) |
| `异步` | `async` | 为真时输出 `async` |
| `版本` | `version` / `v` | 非空则自动追加 `?v=`;否则用页面/应用 `asset_version` |
**渲染规则**
| `rel` | 输出 |
|-------|------|
| `script` | `<script src="…"></script>`(`type` 非空则写出) |
| `module` | `<script type="module" src="…"></script>` |
| `script` | `<script … src="…"></script>`(可选 `defer`/`async`;`type` 非空则写出) |
| `module` | `<script type="module" src="…"></script>`(浏览器默认 defer 语义) |
| 其他 | `<link rel="…" href="…" …>`(按列附加 `type`/`sizes`/`media`/`as`/`crossorigin`) |
空 `地址` 的行跳过。
+2
View File
@@ -13,6 +13,8 @@
**`ext/web` + `plugins/web` 已完成 W0–W7 + P3 路线图**:中间件/JSON API、数据层(连接池/事务/分页/FTS/迁移/外键/审计时间戳)、安全硬化(argon2/CSRF/会话持久化/限速/RBAC)、内容站点标配(SEO/RSS/Markdown/分页 UI)、上传下载/相册/ETag、sitemap/robots/错误页/重定向、WebSocket 广播与访问日志。足以在 Marqdo 上实现博客/CMS/中小型 API 站点;**未内置**的仅剩标签页模板(D6,可用路由+`db.count` 自建)与应用层反垃圾。边界不变:**纯解析进 `lib/net`,HTTP 服务器与领域能力进 `plugins/web` + `ext/web` 作者面**。
**宿主集成下一刀**(同域 LLM SSE 中继、HTTP→用户 `##`、与 MCP Server 协作)不在本 W 表内,见 [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) · [ext-hosting-fill.md](ext-hosting-fill.md) · [ext-hosting.md](../roadmap/ext-hosting.md)。
---
+54
View File
@@ -0,0 +1,54 @@
# 调研刷新:2026-09 智能体框架与 Marqdo「代码即文档」
| | |
|---|---|
| 状态 | **Wave B1 Active**(B0/B0.5 已完成;宪法优先) |
| 日期 | 2026-09-04 |
| 前置 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) |
| 路线 | [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) |
## 0. 结论
业界框架(LangGraph / Microsoft Agent Framework / CrewAI / OpenAI Agents SDK)在编排、工具、检查点、MCP、评测上继续收敛;**权威真相仍默认在对象图 + transcript + 外置 Store**。
Marqdo 的差异化不是「再做一个 loop」,而是:
1. **代码即文档** — 编排 `.mq.md` = 提示词工作面
2. **调用位置可见** — `agent_call_site`(路径 / 函数 / 行)是一等上下文
3. **文档即知识库(OKF)** — 写回 → promote / solidify → 二次命中 / `llm_free`
Wave B 的目标函数:**证明并硬化上述三点**;产品化示例与评测必须服务差异化,禁止做成无源码上下文的 chatbot demo。
## 1. 业界快照(2026)
| 模式 | 代表 | 状态记忆 | 对 Marqdo |
|------|------|----------|-----------|
| 图 + checkpointer | LangGraph | typed state 持久化 | 续跑应对齐**文件化工作簿**,不造 Python 图 DSL |
| Agent vs Workflow | Microsoft AF | 自主 + 确定性流 | 已有 step / plan,强化即可 |
| 角色班组 | CrewAI | Task 管道 | 多 Agent 低优先;父 CALL + 多工作簿 |
| Handoff + Guardrails | OpenAI Agents SDK | 显式交接 | 可借鉴语义;权威仍在 `.mq.md` |
## 2. 深远影响(开发硬约束)
| 约束 | 含义 |
|------|------|
| 提示不黑盒 | standing / 工具 / 任务写在文件;拼装可审查 |
| 位置感知 | 每次推理注入 call_site;示例与评测可断言 |
| 源码工作面 | `source_brief` + `READ:source\|skill`;禁止藏整份 Skill 进不可见提示 |
| 写回即记忆 | ok/error 槽 + view;非默认向量库 |
| OKF 飞轮 | promote / solidify / hit / llm_free |
| 外置工具 | corpus / MCP 仅证据,`authority=workbook` |
## 3. Wave B 范围
| 波次 | 主题 |
|------|------|
| **B0** | 宪法可见示例 + 上下文管道可读性 + Skill/文档 |
| **B0.5** | 本机 live(`.env` → cflmy)验证「模型用上了文档」 |
| **B1** | 评测锁住 call_site / OKF / 写回 / 预算 |
暂缓:真 MCP、resume/HITL view、kb stats、并行、A2A。
## 4. 开发期 LLM
仓库根目录 `.env`(gitignore):`OPENAI_*` 或 `MARQDO_LLM_*`。模板见 `.env.example`。
@@ -70,6 +70,7 @@
| **高** | 官方端到端示例 + 文档新鲜度 | 无独立 `examples/agent-*`;Skill/参考里仍有「layout / roadmap」陈旧表述;外人难「照抄即跑通 plan→固化→二次命中」 | `examples/agent-pong`(或同类)+ README;Skill 专节与 A0–A4 对齐 |
| **高** | Agent 评测 / 回归 harness | 有离线金样,缺成本·恢复·命中率·补丁质量的系统评测;业界强调 evaluation 先于上线 | `tests/` 或脚本:命中率、llm_free 占比、失败恢复、可选 live 预算 |
| **高** | 真 MCP(HTTP/SSE)与凭证 | A4 仅 JSON fixture;缺 streamable HTTP、鉴权、resources/prompts | 金样打 mock MCP server;返回仍带 `authority=workbook` |
| **高** | **MCP Server 宿主**(stdio / HTTP) | Agent 只能当客户端 fixture;IDE 无法把 `.mq.md` `##` 暴露为 MCP 工具 | 见 [ext-hosting-gaps.md](ext-hosting-gaps.md) GAP-03 · [ext-hosting-fill.md](../design/ext-hosting-fill.md) |
| **中** | Plan 断点续跑 | 工作簿在盘上,缺显式 checkpoint / resume(对标 LangGraph checkpointer) | `plan resume=` 从第 N 轮 DECISION 继续;进程崩溃可恢复 |
| **中** | 人机协同(HITL)加深 | 仅有 `confirm=True` 建簿即停;缺审批卡、拒绝重开、view 一键继续 | view 审批控件 + 金样 |
| **中** | 飞轮可观测指标 | `hits` / `improve_every` / `llm_free` 有字段,缺汇总与 CLI/view 报表 | `agent_kb_stats` 或 view 面板:命中率、探索浪费 |
+156
View File
@@ -0,0 +1,156 @@
# 调研:宿主集成缺口(浏览器中继 · HTTP→`##` · MCP Server · 同寿副端口 · 跨模块 DB/检索)
| | |
|---|---|
| 状态 | **调研笔记 · 缺口盘点(H1–H4 stdio 已落地;H4b HTTP 可选)** |
| 日期 | 2026-09-07 |
| 触发 | 下游应用(对话站 / 求道类 Agent)在真实集成中被迫旁路 Python 脚本 |
| 基线版本 | **v0.3.6+**(宿主波次 H1–H4 见 [ext-hosting.md](../roadmap/ext-hosting.md)) |
| 相关设计 | [ext-web.md](../design/ext-web.md) · [ext-web-net.md](../design/ext-web-net.md) · [web-net-capabilities.md](../design/web-net-capabilities.md) · [ext-agent.md](../design/ext-agent.md) · [ext-abi.md](../design/ext-abi.md) |
| 邻近缺口 | [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md)(真 MCP **客户端**) |
| 补齐设计 | [ext-hosting-fill.md](../design/ext-hosting-fill.md) |
| 实现路线 | [ext-hosting.md](../roadmap/ext-hosting.md) |
---
## 0. 一句话结论
`ext/web` 已能做**内容站 / CRUD / JSON-DB API / WS**;`ext/ai` 已能做**工作簿 Agent + 客户端 SSE 消费**。下游要把「浏览器同域流式 LLM」「请求触发任意 `##`」「MCP Server 被 IDE 拉起」合进**单一 Marqdo 进程**时,现有扩展**没有一等装配**——只能外挂缓冲代理 / CLI 子进程。缺口集中在 **扩展库作者面 + `plugins/web|agent` ABI**,不是语法层,也不是再开一套标准库。
**原则:** 旁路脚本只证明需求;关闭缺口必须把能力沉进 `ext/*` + `plugins/*`(可选极薄 `lib/` 编排),禁止把领域逻辑塞进 `src/host/`。
---
## 1. 已有基线(不是缺口)
| 能力 | 现状 | 文档 / 金样 |
|------|------|-------------|
| CORS / 安全头 / gzip / body limit | `app.configure` | `tests/ext/web-middleware-smoke.mq.md` |
| JSON **DB select** 路由 | `configure json=` | `plugins/web/src/middleware.rs` |
| `/_form/*` SQL CRUD | `mount_form` | `plugins/web/src/form.rs` |
| 客户端缓冲 SSE | `lib/net.http_post_sse` → `ext/llm.complete stream=` | `tests/lib/net-openai-sse.mq.md` |
| 执行过程 SSE(非 LLM 中继) | `marqdo view` `/api/run` | [view.md](../design/view.md) §5 |
| Agent 证据工具(fixture MCP) | `corpus_search` / `mcp_list_tools` / `mcp_call` | A4;[agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) |
| 同模块 `# db` CRUD | `ext/web` `# db` | `examples/web-site/db/` |
---
## 2. 缺口总表
| ID | 缺口 | 需要 | Marqdo 现状 | 典型旁路 | 解除条件 |
|----|------|------|-------------|----------|----------|
| **GAP-01** | 浏览器 → 上游 LLM **同域流式中继** | 绕过对方 CORS;**SSE 原样转发** | **`app.proxy` / `configure proxy=`**(H1) | ~~`llm_proxy.py`~~ | ✅ 已关闭 |
| **GAP-02** | HTTP 处理函数可调用用户 `##` | 请求内执行用户 `##`,返回 JSON | **`app.invoke` / `configure invoke=`**(H2) | ~~外挂 `marqdo run`~~ | ✅ 已关闭 |
| **GAP-03** | **MCP Server** 宿主 | IDE 拉起暴露工具 | **`agent.mcp_server` + `serve` stdio**(H4);HTTP=H4b | ~~`qdagent_mcp.py`~~ | ✅ stdio;HTTP 可选 |
| **GAP-04** | 同寿「第二监听端口」 | 与 `listen` 同寿中继 | 并入主端口(H1+H2) | ~~`mq.sh` 双进程~~ | ✅ won't |
| **GAP-05** | 跨模块 `db`;纯 run 用 corpus | 跨文件 `select`;CLI 检索 | 传递归查找 + `corpus_search` ensure_plugin(H3) | ~~db/index 导出~~ | ✅ 已关闭 |
旁路脚本名来自下游集成仓库;**本仓库 `scripts/` 不含这些文件**——它们是需求证据,不是上游实现。
---
## 3. 分项说明
### 3.1 GAP-01 · 同域 SSE 中继
**问题**
浏览器页面跑在 `ext/web` 源上时,直连 OpenAI 兼容上游会撞 CORS;`lib/net.http_post_sse` 只在 **CLI/宿主侧缓冲整段流**,不能把字节边收边推回浏览器。
**现状边界**
| 已有 | 缺什么 |
|------|--------|
| `app.configure cors=` | 解决的是**本站对外** CORS,不是替上游开 CORS |
| `http_post_sse` → `{status, events}` | **客户端消费**,非服务器中继 |
| `app.download` 对象流 | 存储下载,非上游 SSE |
| view `/api/run` SSE | Marqdo **执行事件**,非 LLM token 流 |
**解除形态(产品)**
作者声明:`path` + `upstream`(或 env)+ 可选 header 白名单;监听端对浏览器返回 `Content-Type: text/event-stream`,chunk 原样或按 OpenAI SSE 帧转发。
### 3.2 GAP-02 · 路由 → `##`
**问题**
对话沉淀、表单后写 `data/runs/*.mq.md`、触发 `lib/run.沉淀` 等,需要**同进程**执行用户函数。今天只有:
1. 页面装配期 `call_lib_path`(compose,非每请求);
2. `/_form` / `json=` 的 **DB 专用** handler。
**解除形态(产品)**
声明式:`path` · `method` · `fn=lib.member` 或 `file=… ## name` · body→形参映射 · 返回值序列化为 JSON(错误码约定)。安全默认:仅允许入口模块已导入路径;禁止任意路径注入。
### 3.3 GAP-03 · MCP Server
**问题**
A4 解决的是 Agent **调用** MCP 工具(且仍是 fixture)。下游要把 Marqdo 工作簿 **暴露为** MCP Server(stdio / Streamable HTTP),IDE 拉起后调 `qd_*`。
与 [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md)「真 MCP 客户端」正交:本缺口是 **Server 宿主**。
**解除形态(产品)**
`ext/ai`(或 `ext/mcp`)提供:`server tools=` 表(name → `.mq.md`/`##`);`serve stdio=` / `serve http port=`;工具结果仍可带 `authority=workbook`。
### 3.4 GAP-04 · 同寿副端口
**问题**
在 GAP-01/02 未并入主端口前,下游用第二端口跑代理。`app.listen` 同步阻塞,无「同进程再绑一个 TcpListener」的作者 API;只能 shell 并起另一运行时。
**解除形态(产品)**
优先:GAP-01/02 挂在同一 `listen` → **本缺口关闭**。备选:`app.attach` / `listen also=` 同 tokio 运行时附加服务(仅当必须隔离路径树)。
### 3.5 GAP-05 · 跨模块 DB 句柄与 corpus 可发现性
**问题**
1. **类型分发:** 插件对象依赖 `_type` / 方法表;跨模块传回的 store 若丢类型或未注册方法,报 `unknown object type db`。同文件 `db/index.mq.md` 内 `## recent` 再导出 JSON 是现行绕过。
2. **`agent_corpus_search`:** 注册在 `plugins/agent`;普通 `marqdo run` 未 `plugin.load` / 未构造 `# agent` 时不可用。导入 `ext/ai/agent.mq.md` 文本本身不保证原生插件已加载。
**解除形态(产品)**
句柄:跨模块返回值保留 `_type=db` 且方法分发查全局/插件表(修运行时或约定「只返回 url,调用方再 `web.db`」二选一,见补齐设计)。corpus:`plugin.load` 自动路径,或 `ext/ai` 导出独立 `## corpus_search` 并在调用前 `ensure_plugin`。
---
## 4. 归属判定(标准库 vs 扩展)
沿用 [ext-web-net.md](../design/ext-web-net.md) / [web-net-capabilities.md](../design/web-net-capabilities.md) 边界:
| 能力 | 归属 | 理由 |
|------|------|------|
| SSE **中继**路由、HTTP→`##`、副端口 | **`plugins/web` + `ext/web`** | 服务器结构 / 网站领域;axum 已在依赖链 |
| MCP **Server**、corpus 可发现 | **`plugins/agent` + `ext/ai`** | Agent/工具宿主;禁止塞 `src/host/` |
| 缓冲 SSE 客户端、解析 | 已有 **`lib/net`** | 不新增中继到 stdlib |
| 任意路径 shell 出去跑 `marqdo` | **刻意不做进核心** | 旁路脚本可留在下游;上游给一等 API 后废弃 |
---
## 5. 优先级建议
| 优先级 | ID | 理由 |
|--------|-----|------|
| **高** | GAP-01 + GAP-02 | 去掉 Python 中继的主路径;浏览器站 + 沉淀闭环 |
| **高** | GAP-03 | IDE 生态入口;与「真 MCP 客户端」可并行设计、分波交付 |
| **中** | GAP-05 | 减少 `db/index` 与 bridge 胶水;影响面偏语言/插件加载 |
| **低(可随 01/02 关闭)** | GAP-04 | 并入主端口后自然消失 |
---
## 6. 明确「不是缺口」
| 项 | 说明 |
|----|------|
| 内容站 W0–W7+P3 | 已完结;本清单不重开上传/RSS/RBAC |
| Mid M1–M6 | 通用原语已够;本清单不是再开 `lib/re` 一类 |
| 隐藏 JSON TOOL 主循环 | 与 Agent 宪法冲突 |
| Dense embedding 默认化 | 仍见 [okf-near-match.md](../roadmap/okf-near-match.md) |
| 浏览器手写业务 JS 代理 | 与 WASM 路线「作者零 JS」冲突;中继应在服务端 `ext/web` |
---
## 7. 与其它文档
| 文档 | 关系 |
|------|------|
| [ext-hosting-fill.md](../design/ext-hosting-fill.md) | **补齐设计(作者 API + ABI)** |
| [ext-hosting.md](../roadmap/ext-hosting.md) | 实现波次 H0–H4 |
| [ext-web.md](../roadmap/ext-web.md) | 站点主线完结;本缺口为后续宿主波次 |
| [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) | 客户端真 MCP;与 GAP-03 Server 互补 |
| [web-asgi-servers-and-marqdo.md](../design/web-asgi-servers-and-marqdo.md) | 反代模型;中继仍在 Marqdo `listen` 内 |
+113
View File
@@ -0,0 +1,113 @@
# 调研:线性代数 × 公式类 × 展示
| | |
|---|---|
| 状态 | 调研纪要(为 [ext-linalg](../design/ext-linalg.md) 供输入) |
| 日期 | 2026-09-07 |
| 相关 | [stdlib-math.md](../design/stdlib-math.md) · [ext-quantum-q7.md](../design/ext-quantum-q7.md) · SymPy MatrixExpr · Symbolics.jl · LAFigureSpecs |
---
## 1. 问题陈述
Marqdo 已有:
- `Value::Formula` + `` `f` = `` + `$$…$$`(高中标量符号)
- `formula::Expr::Matrix`:**数值**稠密矩阵字面量(`[[…]]` / `\begin{pmatrix}`),供量子门核对与 view KaTeX
- `ext/quantum` Q7:**量子语境**下的密度矩阵 / Kronecker / 谱 / SVD 风格图(ABI)
缺口:一门**经典线性代数**扩展——作者用**公式级矩阵表达式**写 \(A^\top A\)、\((X^\top X)^{-1}X^\top y\)、分块、Kronecker,在**不立刻展开成巨大稠密矩阵**的前提下做重写与化简,并在文档 / view 中**好看地呈现**分解与结构。
---
## 2. 业界对照
### 2.1 符号矩阵表达式(大规模优化的关键)
| 系统 | 模型 | 对 Marqdo 的启示 |
|------|------|------------------|
| **SymPy `MatrixExpr`** | `MatrixSymbol(name, n, m)` + `MatMul` / `MatAdd` / `Inverse` / `Transpose` / `Trace` / `Determinant` / `BlockMatrix` / `KroneckerProduct`;`as_explicit()` 才展开 | **默认保持抽象**;形状元数据传播;显式求值是可选动作 |
| SymPy `block_collapse` | 分块表达式在块级化简,避免整块稠密展开 | 分块是教学与优化的第一公民 |
| SymPy Kronecker | `KroneckerProduct` 惰性 + `combine_kronecker` 规则 | Kronecker **绝不能**默认 `expand`(维数爆炸) |
| SymPy 矩阵求导 | 经 array expr 再收回 MatrixExpr;闭式导数 | v1 **不做**;记入远期 |
| **Symbolics.jl** | 「数组的符号」vs「符号数组」:后者 O(1) 表示整阵,保留 `A*B` 不展开 | 与 MatrixExpr 同构;强调 **shape / eltype 元数据** |
| NumPy / Eigen / nalgebra | 数值热路径,无公式树 | 对应 Marqdo **插件数值层**,不是文档作者主路径 |
**结论:** 「公式类线性代数」= **抽象表达式 DAG + 形状检查 + 重写规则**;稠密数值是 `eval` / `as_explicit` 的终点,不是默认形态。
### 2.2 教学与展示(效果最好的做法)
| 做法 | 来源 | 效果 | Marqdo 映射 |
|------|------|------|-------------|
| KaTeX / MathJax 渲染 `bmatrix` / `pmatrix` | SymPy `latex()` + Jupyter `init_printing` | 公式即排版;多式用 `display` 并列 | 既有 view `formula-card` + KaTeX |
| 标签化等式 `A = UΣV^\top` | 教材 / Qiita display+Math | 步骤可读 | `show` / writeback 多卡片 |
| **结构图**(SVD / QR / 消元轨) | [LAFigureSpecs](https://github.com/ea42gh/LAFigureSpecs) + matrixlayout;TeX `drawmatrix` | 比数字表更能讲「秩 / 零空间 / 对角结构」 | SVG `kind=svd|qr|ge|eig` |
| 热力图 / Hinton | Qiskit / QuTiP / 既有 quantum | 稠密数值矩阵的幅度/符号 | `kind=heatmap|hinton`(经典实/复) |
| 分块着色矩形 | CTAN `drawmatrix` | 零块 / 三角 / 带状一目了然 | `kind=structure`(形状示意图,可无元素值) |
| 仅打印 ASCII | CLI 默认 | 金样可断言 | `str` / `print` → 规范 ASCII / LaTeX 源 |
**展示优先级(锁定建议):**
1. **符号式**:始终可 `latex` → view KaTeX(不依赖数值)
2. **结构式 SVG**:分解 / 分块 / 秩示意(教学主图)
3. **数值热力图**:仅在 `eval` 后、维数可控时
4. CLI:短 ASCII;大矩阵默认摘要 `m×n …` + 可选 `preview=`
### 2.3 一门「够用」的线性代数库需要什么
按大学一学期 + 数据科学入门,能力桶:
| 桶 | 内容 | 符号层 | 数值层 |
|----|------|--------|--------|
| A 构造 | 符号阵、常数阵、单位/零/对角、从 `$$` / 表 / list | ✅ | ✅ |
| B 代数 | 加减乘、转置、逆、伴随、幂、Kronecker、分块 | ✅ 重写 | ✅ |
| C 分解 | LU / QR / 特征 / SVD / Cholesky(对称) | 结果对象 + 结构图 | ✅ |
| D 系统 | `Ax=b`、最小二乘、伪逆 | 公式写法 + 数值解 | ✅ |
| E 度量 | 行列式、迹、秩、范数、条件数 | 部分可符号 | ✅ |
| F 展示 | latex / ASCII / SVG 结构 / heatmap | ✅ | ✅ |
| G 微积分 | 矩阵导数、Jacobian 积木 | 远期 | — |
**不做(首版):** 稀疏专用格式、GPU、分布式、完整 CAS 证明、通用张量网络、与 `lib/math` 高中标量混成一个巨模块。
---
## 3. 与现有 Marqdo 的衔接点
| 已有 | 用法 | 扩展时注意 |
|------|------|------------|
| `$$` + Matrix 数值字面量 | 小门矩阵、手算核对 | 保留;符号阵用 `MatrixSymbol` 或 `matrix.symbol`,勿与数值 Matrix 混为一谈 |
| `lib/math` formula | 标量 simplify/diff/plot | **不**把大学线性代数塞进 `lib/math`(与 Q7 结论一致) |
| view KaTeX | formula-card | 符号 MatExpr 的 `latex` 字符串直接喂 KaTeX |
| `ext/quantum` Q7 linop | 量子密度 / 纠缠 | **经典 API 不复用 quantum 命名空间**;共享算法可在插件内私有复用,作者面分离 |
| `plugins/*` ABI | 重数值 / SVG | 稠密分解与大图走 `plugins/linalg` |
| GFM 表 | 数据即代码 | 矩阵输入:表或 `$$`;分解步骤:`@` 记录表 |
---
## 4. 「大规模优化」具体指什么
在公式类语境下,优化 ≠ BLAS 微内核,而是:
1. **惰性**:`A*B*C` 保持乘积树,直到 `eval` / `explicit`
2. **形状短路**:不相容维数在符号阶段报错,不跑数值
3. **代数恒等**:`(A^{-1})^{-1}→A`,`(AB)^\top→B^\top A^\top`,`I*A→A`,分块 `block_collapse`
4. **禁止爆炸展开**:Kronecker / 高维符号积默认不 `expand`
5. **数值批处理**:同形状多 RHS、分解一次多用(`factorize` 对象)
6. **展示成本**:大矩阵不默认内嵌完整 KaTeX 数字阵;结构图 + 摘要
---
## 5. 推荐产品叙事(一句)
**线性代数文档用公式写变换,用规则做化简,用结构图讲分解,用可控数值做验算——公式是一等公民,稠密矩阵是可选终点。**
---
## 6. 参考链接
- SymPy Matrix Expressions: https://docs.sympy.org/latest/modules/matrices/expressions.html
- SymPy Matrix derivatives (远期): https://docs.sympy.org/dev/explanation/modules/matrices/matrixderivatives.html
- Symbolics.jl Symbolic Arrays: https://docs.sciml.ai/Symbolics/v6.54/manual/arrays/
- LAFigureSpecs(教学结构图): https://github.com/ea42gh/LAFigureSpecs
- CTAN drawmatrix: 矩阵形状示意
- 既有:`doc/design/stdlib-math.md` · `doc/design/ext-quantum-q7.md`
@@ -0,0 +1,154 @@
# `ext/web` 定制限制:开发者不易定制的问题盘点
| | |
|---|---|
| 状态 | **调研锁定(踩坑整理)** |
| 日期 | 2026-09-04 |
| 相关 | [ext-web.md](../design/ext-web.md) · [ext-web-net.md](../design/ext-web-net.md) · [web-net-capabilities.md](../design/web-net-capabilities.md) |
| 解决索引 | [../design/ext-web-customization/](../design/ext-web-customization/) |
结合自研后台、样式迁移与响应式改造中的实际踩坑,整理当前 `plugins/web` + `ext/web` 对站点作者的**强占与难定制点**。本文只陈述问题与证据;逐项解法见解决索引。
---
## 0. 一句话
内置 `/admin` 壳、固定鉴权路径、注入式 `SHELL_CSS` 与四区栅格,让「只写 `.mq.md`」的产品路径在**自研后台 / 品牌主题 / 移动端**上反复撞墙;作者被迫旁路前缀 + `!important` + 前端 JS 兜底。
---
## 1. 路由与路径被框架强占
**现象**
- `/admin` 及 `/admin/*` 整段保留,无法 `app.route` 注册自定义页(错误:`route path … is reserved`)。
- `app.重定向` / `redirect` 目标若落在 reserved 前缀,同样被校验拒绝。
- `后台=False`(`admin=False`)后,访问 `/admin/news` 等仍进内置壳,只显示 *Admin is disabled*,**不能**换成自研页。
- 登录/登出硬绑 `/admin/login`、`/admin/logout`;登录成功硬编码 `Redirect::to("/admin")`,无法配置回跳到 `/desk`。
**代码证据**
| 位置 | 行为 |
|------|------|
| `plugins/web/src/lib.rs` → `normalize_route_path` | `/admin`、`/_form`、`/_part`、`/static` 一律 reserved |
| `plugins/web/src/http.rs` | 始终挂 `/admin…` 路由;disabled 时仍 `admin_shell` + 文案 |
| 同文件 `admin_login_post` | 成功跳转写死 `/admin` |
**结果**
自研后台只能用 `/desk` 等旁路前缀;入口与鉴权路径分裂,还要靠前端 JS(`fetch('/admin/login')` 再 `replace('/desk')`)做跳转兜底。
→ 解决:[01-routes-and-admin-prefix.md](../design/ext-web-customization/01-routes-and-admin-prefix.md)
---
## 2. 内置 `SHELL_CSS` 难以彻底覆盖
**现象**
- 每个页面都会注入框架壳样式,例如 `body.has-sidebar { grid-template-columns:14rem 1fr; … }`、默认卡片/表单/侧栏色。
- 规则**无媒体查询**、选择器优先级不低;站点主题选择器不够强时,小屏双列、侧栏占位等「幽灵布局」反复出现。
- 首页有额外 class(如 `has-rail`)时碰巧盖住,其他页没有同类 class 就暴露——表现为「只修了首页」。
- 实务上经常要 `!important` + 更高选择器,与「干净主题层」冲突。
**代码证据**
| 位置 | 行为 |
|------|------|
| `plugins/web/src/render.rs` → `SHELL_CSS` | 常量内联进每个 HTML |
| 同文件壳渲染 | `<style>{SHELL_CSS}{extra}</style>`,主题只能接在后面 |
→ 解决:[02-shell-css.md](../design/ext-web-customization/02-shell-css.md)
---
## 3. 鉴权 / 门禁模型偏固定
**现象**
- 未登录访问受保护路径:对 `/admin*` 会 **303 → 登录页**;对 `/desk` 等自定义路径往往是 **403 HTML**,行为不一致。
- 门禁匹配偏宽:`path.starts_with` / `path_matches` 使 `/desk` 匹配 `/desk/login`,公开登录页易被误伤。
- 默认鉴权挂上 `/admin*` → `admin`;`/admin-publish` 这类名字也会被当成 admin 域(`starts_with("/admin")`)。
- 会话 cookie、CSRF、登录表单字段均固定在框架实现;难换登录 UI 或改成功落地页。
**代码证据**
| 位置 | 行为 |
|------|------|
| `http.rs` → `rbac_middleware` | visitor + `/admin*` → redirect;其它 gate → 403 |
| `http.rs` → `path_matches` | 前缀匹配,无「精确路径 + 子路径排除」DSL |
| `lib.rs` → `web_app_auth` | 默认塞入 `/admin*` gate |
→ 解决:[03-auth-gates.md](../design/ext-web-customization/03-auth-gates.md)
---
## 4. 样式作者体验受限
**现象**
- 样式表是 GFM 表格;含 `/` 的值必须加引号(如 `"1 / 5"`),否则单元格表达式把 `/` 当除法(曾出现 `grid-column` 变成 `0`)。
- `@keyframes`、复杂选择器、多层媒体查询(`min-width` and `max-width`)表达能力有限,装配顺序要小心。
- 主题 CSS 与 `SHELL_CSS` 同页串联,级联顺序不透明,调试成本高。
- 响应式不能指望框架;壳层几乎不提供移动端抽屉/折叠。
→ 解决:[04-stylesheet-authoring.md](../design/ext-web-customization/04-stylesheet-authoring.md)
---
## 5. 页面壳与插槽约定僵硬
**现象**
- 壳结构固定为 `topnav` / `side` / `main` / `foot` 栅格命名区。
- 侧栏一旦装配,`body` 即 `has-sidebar`,套上框架双列;杂志风单列、抽屉必须自己拆布局。
- 组件表驱动导航,难做运行时条件导航(小屏合并顶栏+侧栏),通常再补 `theme.js`。
→ 解决:[05-page-shell-slots.md](../design/ext-web-customization/05-page-shell-slots.md)
---
## 6. 后台 CRUD 与表单能力边界
**现象**
- 内置 admin 是通用表管理,不是产品级 CMS;**关了又占着 `/admin` 路径**(与 §1 叠加)。
- 表单以声明式字段表为主;Markdown 分栏、专栏元数据联动等只能外挂 JS。
- 列表「链接前缀」等约定简单;编辑/新建状态机常靠前端拼(`?id=`、`?new=1`)。
→ 解决:[06-admin-crud-forms.md](../design/ext-web-customization/06-admin-crud-forms.md)
---
## 7. 静态资源与脚本生命周期
**现象**
- 头资源脚本常在 `<head>` **同步**加载;若脚本假设 DOM 已就绪会直接失败(登录页曾因此不跳转)。
- 缓存靠 `?v=` 手动 bump;无构建管线时易出现「改了 JS 浏览器仍用旧文件」。
→ 解决:[07-assets-script-lifecycle.md](../design/ext-web-customization/07-assets-script-lifecycle.md)
---
## 8. 扩展与部署耦合
**现象**
- 能力依赖 web 插件 ABI / Marqdo 版本(如 0.3.2 起的样式引号约定);升级要同步 Docker / 本机二进制。
- 定制若依赖改插件源码(放宽 `/admin` reserved、可配置 login redirect),就脱离「只写 `.mq.md`」的产品路径,维护成本陡增。
→ 解决:[08-ext-deploy-coupling.md](../design/ext-web-customization/08-ext-deploy-coupling.md)
---
## 9. 优先级建议(给实现排期)
| 优先级 | 项 | 理由 |
|--------|-----|------|
| P0 | §1 路由/前缀 + §3 鉴权一致 | 阻塞自研后台产品路径 |
| P1 | §2 SHELL_CSS + §5 壳布局 | 阻塞品牌主题与响应式 |
| P2 | §4 样式作者体验 + §7 脚本生命周期 | 降低日常踩坑,不改架构也能缓解 |
| P3 | §6 CRUD 边界 + §8 部署耦合 | 文档/约定/可选增强为主 |
详细验收与实现切片见解决索引 README。
+144
View File
@@ -0,0 +1,144 @@
# 调研:Mid M1–M6 之后标准库还缺什么
| | |
|---|---|
| 状态 | **调研笔记 · 缺口盘点(M1–M6 闭环之后)** |
| 日期 | 2026-09-08 |
| 基线 | **v0.3.7+** · Mid M1–M6 **done** |
| 已落地设计 | [stdlib-mid.md](../design/stdlib-mid.md) · [stdlib-modules.md](../design/stdlib-modules.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
| 补齐设计 | [stdlib-mid2.md](../design/stdlib-mid2.md) |
| 实现路线 | [stdlib-mid2.md](../roadmap/stdlib-mid2.md) |
| 外部对照 | Python stdlib([use-case 索引](https://www.socratopia.app/library/python-programming-ai-era-en/chapter-15) · [PEP 680 tomllib](https://peps.python.org/pep-0680/))· Go `strings`/`regexp`/`encoding/*`/`crypto`/`path`/`time`/`net/url` · Node 内置 vs userland |
---
## 0. 一句话结论
**M1–M6 已把「写日常脚本 / 多数扩展库不再事事插件」的硬缺口补齐。** 相对 Python / Go 的「通用原语层」,Marqdo **不再缺** 正则、编解码、路径、哈希、CSV、集合糖、CLI、日志、UUID。
仍缺的是 **第二档通用能力**:日历与时区、URL/查询串、配置格式(优先 TOML)、HTML 安全转义、文件系统再厚一点(`mkdir -p` / 元数据 / 递归删除)、轻量统计。这些**值得开 Mid2(M7+)**,但**不应**再开一轮「事事插件」;也**不要**把 YAML 全家桶、HTTP 服务端、SQLite、图像/ML 塞进 `lib/`。
---
## 1. 已有基线(不是缺口)
| 族 | Marqdo | 对标 |
|----|--------|------|
| 文本 / 正则 | `text`++ · `re` | Python `str`/`re` · Go `strings`/`regexp` |
| 编解码 | `encoding`(base64/hex)· `net.url_encode` | Go `encoding/base64`/`hex` · Python `base64`/`binascii` |
| 路径 / 文件 | `path` · `fs`(含 copy/move/temp) | Go `path/filepath` · Python `pathlib`(子集) |
| 完整性 / 机密 | `hash` · `secrets` | Go `crypto` 子集 · Python `hashlib`/`secrets` |
| 表数据 | `csv` · `table`++ · `json` | Go `encoding/csv`/`json` · Python `csv`/`json` |
| CLI / 可观测 | `cli` · `log` · `uuid` | Python `argparse`/`logging`/`uuid`(窄) |
| 时间(极简) | `time`:unix/ms · format · parse · sleep | **远薄于** Python `datetime`/`zoneinfo` · Go `time` |
| 网络客户端 | `net`:HTTP/SSE/cookie/multipart/markdown | Go `net/http` **客户端**侧;服务端在 `ext/web` |
| 数学 | `math`(含公式/作图) | Python `math` + 教学向扩展 |
准入宪法仍见 [stdlib-mid.md](../design/stdlib-mid.md) §3:跨领域、难写对、解锁无插件写库、宿主面积极小。
---
## 2. 对照总表(按「脚本作者是否还要 foreign / 自造轮子」)
| 能力 | Python / Go 常态 | Marqdo 现状 | 缺口级别 | Mid2 建议 |
|------|------------------|-------------|----------|-----------|
| 日历日期 / 时区 / timedelta | `datetime`+`zoneinfo` · `time` | 仅 unix 戳 + 简单 format/parse | **高** | **M7** `datetime` |
| URL 解析 / 查询串 | `urllib.parse` · `net/url` | 仅 `url_encode` | **高** | **M7** `url`(或并入 `net`) |
| 配置 TOML 只读 | `tomllib`(PEP 680) | 无 | **中高** | **M8** `toml`(只读优先) |
| 配置 YAML | 第三方;**故意不进** CPython | 无 | **低 / 慎入** | 默认 **不做**;与 Python 同理(复杂度/安全) |
| HTML / XML 转义 | `html` · `html/template` 转义 | 无(`markdown_parse` ≠ 转义) | **中** | **M8** `html` 或 `text.html_escape` |
| `mkdir -p` / 递归删 / stat | `pathlib`/`shutil` | `make_dir`/`remove` 偏浅 | **中** | **M9** `fs` 加厚 |
| 文件元数据(size/mtime) | `os.stat` · `Path.stat` | 无一等 API | **中** | **M9** |
| base32 / percent 完整 | `base64.b32*` · `url` | 无 base32 | **低–中** | **M8** `encoding` 加厚 |
| 轻量统计 | `statistics` | `math` 无 mean/median | **低–中** | **M10** `stats` 或 `math` 薄加 |
| 计数 / 默认字典 / deque | `collections` | `table` 可凑 | **低** | 优先用 `table`;必要时 M10 `collections` 极薄 |
| 组合迭代 | `itertools` | 无 | **低** | 多数可用 `table`;**延后** |
| 模板引擎 | Jinja / Go `text/template` | 无 | **不准入 Mid** | 应用层 / 未来 ext |
| SQLite 客户端 | `sqlite3` · `database/sql` | **`ext/web` `# db`** | **不准入** | 保持扩展 |
| HTTP 服务端 | — | **`ext/web`** | **不准入** | 已关闭(宿主波次另文) |
| 密码哈希 Argon2 | 第三方 / 框架 | `ext/web` 已有 | **不准入 Mid** | 安全产品面 |
| 完整 TLS/证书 API | `ssl` · `crypto/tls` | 客户端 HTTPS 由 ureq | **不准入** | 宿主实现细节即可 |
| 压缩 zip/tar | `zipfile` · `archive/zip` | 无 | **低** | 可选 M10;体积敏感 |
| 环境 `.env` | 第三方;Go 常自写 | **`sys.load_dotenv` 已有** | 无 | — |
---
## 3. 分项说明(高优先级)
### 3.1 日历 / 时区(M7 候选之首)
**问题**
脚本与站点大量需要「今天」「本地日界」「RFC3339」「时区换算」。现有 `time.parse`/`format` 够演示,不够「难写对」的日历语义(闰秒除外,但 DST / offset 已够劝退字符串拼接)。
**对照**
Python 强调 **aware datetime + zoneinfo**;Go `time.Location` 是日常依赖。Mid 原文已把「完整 datetime 时区库」标为刻意延后——M1–M6 完成后应升格。
**建议窄 API(设计文锁定)**
`now` / `parse` / `format` / `add`(天/时)/ `to_unix` / `from_unix` / 可选 `in_zone`(IANA 或固定 offset)。**不做**完整历法 UI、农历、业务假期库。
### 3.2 URL 与查询串
**问题**
`url_encode` 只解决「编码一段」;解析 `https://a/b?x=1&y=2#frag`、合并 query、取 path 仍靠 `re` 自造。浏览器代理 / `invoke` / webhook 场景高频。
**建议**
`url.parse` → `{scheme,host,path,query,fragment}`;`url.query_parse` / `query_stringify`;与 `url_encode` 边界写进 `net` vs 新 `lib/url`。
### 3.3 TOML vs YAML
**外部事实**
Python 因 **打包引导**(`pyproject.toml`)接受只读 `tomllib`([PEP 680](https://peps.python.org/pep-0680/));YAML 多次被拒:规范复杂、实现难维护、安全面大。
**对 Marqdo**
catalog / 工具配置若走向 TOML,只读 `toml.parse` 性价比高。YAML:**默认不准入 Mid**;若 public 强需求,单独 ADR,且优先「JSON 超集子集」而非完整 1.2。
### 3.4 HTML 转义
**问题**
`ext/web` 与浏览器 WASM 拼 HTML 时,缺 `escape` 易 XSS。这是「难写对 / 安全相关」的经典 stdlib 项(Python `html.escape`)。
**建议**
极薄:`html.escape` / `unescape`(或挂 `text`)。**不做** DOM / 模板语言。
### 3.5 文件系统再厚
**问题**
`make_dir` 是否递归、`remove` 是否递归、无 `stat`(size/mtime)、无 `walk`——脚本仍会 `foreign` 或脆弱字符串。
**建议**
`fs.make_dirs` · `fs.remove_tree` · `fs.stat` · 可选 `fs.walk`(返回路径列表,非惰性迭代器协议)。
---
## 4. 明确「不是缺口」
| 项 | 说明 |
|----|------|
| Mid M1–M6 清单本身 | 已收口;不要用本表重开 base64/re |
| HTTP 服务 / DB / Agent | `ext/*`;见 [ext-hosting](ext-hosting-gaps.md) |
| Dense embedding / 向量库默认化 | OKF 路线不变 |
| 完整 `collections` / `itertools` 类型系统 | 语言没有泛型迭代协议;用 `table` |
| 「对齐 Python 模块个数」 | 反模式;对齐**用例与难写对** |
---
## 5. 优先级建议(转入 Mid2)
| 优先级 | 波次草案 | 内容 |
|--------|----------|------|
| **高** | **M7** | `datetime` + `url` — **done** |
| **高** | **M8** | `toml` 只读 + `html.escape` + `encoding` base32 — **done** |
| **中** | **M9** | `fs` 加厚(dirs/stat/walk) — **done** |
| **低** | **M10** | `stats` 薄 · log 字段 · (zip 默认跳过) — **done**(zip 仍跳过) |
| **won't** | — | 完整 YAML · 模板引擎 · sqlite 进 `lib/` |
---
## 6. 与其它文档
| 文档 | 关系 |
|------|------|
| [stdlib-mid2.md](../design/stdlib-mid2.md) | **补齐设计(作者 API + 边界)** |
| [stdlib-mid2.md](../roadmap/stdlib-mid2.md) | 实现波次 M7–M10 |
| [stdlib-mid.md](../design/stdlib-mid.md) | Mid1 宪法;本调研不改准入原则 |
| [web-net-capabilities.md](../design/web-net-capabilities.md) | 网络服务端能力在 ext,不进 Mid2 |
+35
View File
@@ -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` 效应可演示
+32
View File
@@ -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`
+26
View File
@@ -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`。
+40
View File
@@ -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 |
+23 -12
View File
@@ -2,9 +2,9 @@
| | |
|---|---|
| 状态 | **A0–A4 完成**(调研驱动优化闭环;A4:corpus/MCP 证据工具,权威仍是 `.mq.md`) |
| 日期 | 2026-08-28 |
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · **缺口盘点** [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) |
| 状态 | **A0–A4 完成**;**Wave B Active**(宪法优先:代码即文档 / call_site / OKF) |
| 日期 | 2026-09-04 |
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) · **[agent-framework-2026-09.md](../research/agent-framework-2026-09.md)** |
| 设计 | [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md) · [okf.md](../design/okf.md) |
| 邻近 | [agent-streaming.md](agent-streaming.md) · [okf-near-match.md](okf-near-match.md) |
@@ -13,21 +13,32 @@
## 1. 优化原则(来自调研)
1. **强化差异化,不向 LangChain 薄循环回退**(禁止隐藏 TOOL: 主路径、禁止整文件 LLM 重写工作簿)。
2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视**。
2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视、源码/调用位置注入**。
3. 外部 RAG/MCP 只作**工具**,不升为权威真相源。
自评四问见调研 §9。A0–A4 之后的缺口与建议分期 **B0–B5** 见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md)。
自评四问见调研 §9。A0–A4 之后的缺口见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md)。**2026-09 Wave B** 锁定见 [agent-framework-2026-09.md](../research/agent-framework-2026-09.md)。
---
## 2. 建议分期(摘要)
## 2. A0–A4(已完成)
| 波次 | 主题 | 验收线索 |
|------|------|----------|
| **A0** | 工作簿补丁 / 固化可靠性 | **done** — 整文件 FIND 护栏;`soft` 仅 miss;decompose `n` 检查;`workbook_solidify` 单测;金样 `agent-workbook-patch-a0`(双 CONTINUE + solidify) |
| **A1** | OKF 复用飞轮(lookup / near / soft_match UX) | **done** — `list_tasks` 含 description/aliases/status/llm_free/hits;`plan` 命中路径暴露 `match`/`score`;soft_match 策展行含 meta;view plan 卡显示 match;金样 `agent-kb-plan-hit`(exact hit + near soft-hit) |
| **A2** | 过程可见(stream + view 过程卡) | **done** — `plan_append_*` / `plan_finish_stream` 始终写入 `events`(SSE 仍仅 `stream=True`);OKF REUSE 记 `decision`;view `plan-card` 渲染过程时间线(跳过 delta);金样断言 `events-ok`;对齐 [agent-streaming.md](agent-streaming.md) |
| **A3** | 上下文预算(源码/Skill 渐进披露) | **done** — `source_brief` / 加深 `skill_brief`;`build_step_context` 默认预算 + `READ:source|skill`;`step max_reads`;父 `READ:skill`;金样 `agent-context-budget-a3` |
| **A4** | 可选:RAG/MCP 工具适配器 | **done** — `corpus_search`(本地语料关键词);`mcp_list_tools` / `mcp_call`(JSON fixture);`authority=workbook`;金样 `agent-tools-rag-a4` |
| **A0** | 工作簿补丁 / 固化可靠性 | **done** — 金样 `agent-workbook-patch-a0` |
| **A1** | OKF 复用飞轮 | **done** — 金样 `agent-kb-plan-hit` |
| **A2** | 过程可见 | **done** — events + view plan 卡 |
| **A3** | 上下文预算 | **done** — `source_brief` / `READ:`;金样 `agent-context-budget-a3` |
| **A4** | RAG/MCP 证据工具 | **done** — 金样 `agent-tools-rag-a4` |
细节与行业对照以调研正文为准;本文件只跟踪 **A0–A4** 实现分期。后续产品化 / 评测 / live MCP 等见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) §5(草案 B0–B5)。
---
## 3. Wave B(Active — 宪法优先)
| 波次 | 主题 | 状态 |
|------|------|------|
| **B0** | 官方示例演示 call_site/源码/OKF;Skill/文档;上下文管道可读 | **done** |
| **B0.5** | 本机 live(`.env` → 开发模型)验证「模型用上了文档」 | **done**(`AGENT_LIVE` / `AGENT_HARNESS_LIVE`) |
| **B1** | 评测 harness 锁差异化指标(constitution / dump / writeback 遮蔽) | **Active** |
| **B2–B5** | 真 MCP / resume+HITL / stats / 并行 | 暂缓 |
示例:`examples/agent-pong/` · `examples/agent-okf-flywheel/`。
+102
View File
@@ -0,0 +1,102 @@
# 路线图:宿主集成补齐(H0–H4)
| | |
|---|---|
| 状态 | **Active · 规划** |
| 日期 | 2026-09-07 |
| 缺口 | [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) |
| 设计 | [ext-hosting-fill.md](../design/ext-hosting-fill.md) |
| 相关 | [ext-web.md](ext-web.md)(W/C 完结)· [ext-agent-optimize.md](ext-agent-optimize.md) · [agent-streaming.md](agent-streaming.md) |
| 基线 | v0.3.6+ |
本文只跟踪**实现波次**。作者 API、ABI 边界、禁止项以设计文为准。
---
## 0. 目标回顾
让 `ext/web` + `ext/ai` 具备:同域 SSE 中继、HTTP→用户 `##`、MCP Server(至少 stdio)、跨模块 db/corpus 可发现——从而下游无需 Python 旁路进程。
---
## 1. 波次总表
| 波次 | 内容 | 关闭缺口 | 状态 |
|------|------|----------|------|
| **H0** | 文档契约:跨模块 `db` 传 `url`;`corpus_search` 调用前 `ensure_plugin` 说明;缺口索引进 `doc/README` | GAP-05 文档侧 | **done** |
| **H1** | `app.proxy` / `configure proxy=`:上游 SSE/HTTP **流式**转发 | GAP-01 | **done** |
| **H2** | `app.invoke` / `configure invoke=`:请求 → 白名单 `##` → JSON | GAP-02 | **done** |
| **H3** | 跨模块插件对象 `_type` 分发修补 + `corpus_search` 自动 `ensure_plugin` | GAP-05 运行时 | **done** |
| **H4** | `agent.mcp_server` + `serve transport=stdio`(HTTP 可选 H4b) | GAP-03 | **done**(stdio) |
| **H4b** | MCP Streamable HTTP | GAP-03 余量 | **todo**(可选) |
| **—** | 副端口 API | GAP-04 | **won't**:H1+H2 同端口关闭 |
建议顺序:**H1 → H2 → H3 → H4**(H2 的 invoke 内核可被 H4 工具复用,故 H2 不宜晚于 H4)。
---
## 2. 分波工作项
### H1 — 流式代理
1. `plugins/web`:`proxy.rs` + `web_app_proxy`;listen 挂流式 handler。
2. `ext/web`:`## proxy` + `configure proxy=` 表。
3. 金样 `web-proxy-sse-smoke`(mock 上游)。
4. 教程/public 短节:「浏览器同域调 LLM」。
**完成定义:** `curl -N` 同域 path 收到多帧 SSE;密钥仅 env 注入。
### H2 — HTTP invoke
1. 共享或插件内 `invoke_fn`(解析 `库.成员`、映射 body)。
2. `web_app_invoke` + 白名单。
3. 金样:临时 `##` 写文件 + JSON 响应;拒绝未允许路径。
4. 迁移说明:替换 `/store/*` + 外挂 `marqdo run`。
**完成定义:** 单进程 `listen` 下表单/fetch 可触发用户 `##`。
### H3 — db / corpus
1. 复现并修跨模块 `unknown object type db`(设计选项 A)。
2. `ext/ai` `corpus_search` 路径 `ensure_plugin`。
3. 金样 `web-db-cross-module-smoke` + corpus CLI run 金样。
### H4 — MCP Server
1. `plugins/agent` stdio JSON-RPC 最小子集:`initialize` / `tools/list` / `tools/call`。
2. `ext/ai` `# mcp_server` · `## tool` · `## serve`。
3. 工具调用复用 H2 `invoke_fn`。
4. 金样夹具;文档对接 Cursor `mcp.json` 示例。
**H4b:** Streamable HTTP 与鉴权;不阻塞 H4 stdio 发版。
---
## 3. 刻意不做
| 项 | 原因 |
|----|------|
| 默认开启任意 `##` 远程执行 | 安全 |
| 中继进 `lib/net` / `src/host` | 边界 |
| 重开 W0–W7 内容站清单 | 已完结 |
| 以副端口为推荐架构 | H1+H2 同端口即可 |
| Dense embedding 默认 | OKF 路线不变 |
---
## 4. 与发版
- 每波可随小版本发布;H1+H2 建议同一版本对外宣传「可去掉 llm_proxy」。
- H4 可标 `ext/ai` 能力点,与「真 MCP 客户端」分列 Release notes。
---
## 5. 进度勾选(落地时改)
- [x] H0 缺口 + 补齐文档
- [x] H1 proxy SSE
- [x] H2 invoke
- [x] H3 db/corpus
- [x] H4 mcp_server stdio
- [ ] H4b mcp http(可选)
- [x] 研究文 GAP 状态改为 closed(H4b 除外)
+126
View File
@@ -0,0 +1,126 @@
# 官方扩展:`ext/linalg` 实现路线图
| | |
|---|---|
| 状态 | **L0–L6 + 公式文档面 F1–F3 已落地 · L7+ 远期** |
| 日期 | 2026-09-07 |
| **锁定设计** | [design/ext-linalg.md](../design/ext-linalg.md) · [design/ext-linalg-formula-doc.md](../design/ext-linalg-formula-doc.md) |
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [view.md](../design/view.md) · [ext-quantum-q7.md](../design/ext-quantum-q7.md) |
| 安装(规划) | `marqdo ext add linalg`(`linalg` / `线性代数`) |
本文只跟踪**实现阶段**。作者面、公式规则、展示以设计文为准。
---
## 1. 目标回顾(一句)
**可运行的线性代数公式文档**:矩阵公式可化简、可 KaTeX 展示;跑通即在规则集内正确;需要时再稠密求值与分解,并内嵌结构 SVG。
---
## 2. 落地阶段
| 阶段 | 内容 | 状态 |
|------|------|------|
| **L0** | CATALOG + `plugins/linalg` ping + L1 `ensure_plugin`;`ext add` 条目 | **done** |
| **L1** | MatExpr:`symbol` / 稠密叶子 / `mul`·`add`·`T`·`inv`;`simplify` R1–R5;`latex`·`ascii`·`show` | **done** |
| **L2** | `explicit` / 小阵 gemm·解系·`det`·`trace`;维数护栏;金样 `linalg-basic-smoke` | **done** |
| **L3** | `block` + `collapse`;`kron` 惰性 + R7;金样 `linalg-block-kron` | **done** |
| **L4** | `factorize` LU/QR/SVD/eig(+ 可选 chol);结构 SVG `svd|qr|ge|eig`;金样 `linalg-factor-smoke` | **done** |
| **L5** | `heatmap`/`hinton`;examples(最小二乘 / SVD 示意);public + skill 摘要 | **done** |
| **L6** | 复数 dtype;`lstsq`;`norm`/`cond`;主题令牌对齐 | **done** |
| **F1** | 展示路径默认 simplify;公式文档金样 | **done** |
| **F2** | 符号引入降噪;examples 讲义化 | **done** |
| **F3** | 紧凑糖 + public「如何写公式文档」 | **done** |
| **L7+** | 矩阵微积分 / 更大 BLAS 依赖(仅当用户明确要求) | **deferred** |
验收金样(规划路径):`tests/ext/linalg-*-smoke.mq.md`;示例:`examples/linalg-least-squares/`、`examples/linalg-svd/`。
---
## 3. 每阶段出口检查
### L0
- [x] `ext/linalg` CATALOG 含 `linalg`
- [x] 插件 `ping` → ok
- [x] 文档:`marqdo ext add linalg`
### L1
- [x] `(AB)^\top` → `simplify` → `B^T*A^T`(无 dense)
- [x] 形状错误含行列信息
- [x] CLI `ascii` / `show` SVG 通道
- [x] 中英 L1 各一 smoke
### L2
- [x] `from_formula` 吸收 `$$` 数值阵
- [x] `solve` 与手算 2×2 一致
- [x] 超维 `explicit` 硬错误(单元测护栏)
### L3
- [x] 分块乘 `collapse` 后块级正确
- [x] Kronecker 默认不膨胀元素个数(惰性 `A⊗B`)
### L4
- [x] SVD/特征结果对象字段稳定
- [x] SVG 含可断言标记(如 `data-linalg="eig"`)
- [x] `factorize` + 二次 `solve` 复用(LU)
### L5
- [x] 至少 1 个 examples 可 `marqdo run`
- [x] public/features 或 tutorial 短页
- [x] skill / CHANGELOG Unreleased 条目
### L6
- [x] `lstsq` / `norm` / `cond` / `rank` 金样
- [x] `dtype=complex` 基线(Frobenius;分解仍为实数)
- [x] `draw theme=light|dark|bw` 与 quantum Q8 令牌对齐(`data-theme`)
### F1
- [x] `ascii` / `latex` / `show` 默认 simplify
- [x] 金样:`.T` 后直接 `ascii` 得 `B^T*A^T`(无需显式 simplify)
- [x] 设计文 [ext-linalg-formula-doc.md](../design/ext-linalg-formula-doc.md) 落地
### F2
- [x] 符号引入降噪(选定候选) — GFM `@` 表 + `la.declare`
- [x] 至少 1 个 example 以代数面为主叙述 — `examples/linalg-transpose/`
### F3
- [x] `T_ascii` / `转置文本` 一步展示糖
- [x] `explicit` 默认先 simplify(`raw=` 可关)
- [x] public `07-linalg` / `07-线性代数`「如何写公式文档」
---
## 4. 依赖与并行
| 依赖 | 说明 |
|------|------|
| ABI v2 + ext CLI | 已有 |
| view KaTeX / plot | 已有;L1 `show` 接现成通道 |
| Release native zip | 随首次含 `plugins/linalg` 的发版接入 |
| quantum 数值核 | **可选**私有复用;不阻塞 L1–L2 |
不阻塞项:浏览器 WASM 上的 linalg(默认 host/native;WASM 另议)。
---
## 5. 建议开发顺序(下一手)
1. **L7+** 仅当用户明确要求更深符号(微积分等)。公式文档面 F1–F3 已收口。
---
## 6. 一句话
**代数面像讲义、计算面是步骤;跑通即在规则集内正确;每阶段都有可跑金样。**
+13
View File
@@ -35,6 +35,18 @@
| **W7** | Cache-Control / 404·500 / 重定向 / sitemap·robots / init 唯一·索引 / HTTPS 反代说明 | **done** |
| **P3** | 审计时间戳 / 外键 / RBAC / 相册 / ETag | **done** |
### 定制波次(规划中)
自研后台 / 主题 / 响应式踩坑见 [ext-web-customization-limits.md](../research/ext-web-customization-limits.md);解法索引 [ext-web-customization/](../design/ext-web-customization/)。
| 波次 | 内容 | 状态 |
|------|------|------|
| **C0** | `admin` 关则不占路径;`admin_prefix` / 登录回跳可配 | **done** |
| **C1** | gate 匹配与未登录策略一致;段边界默认 admin gate | **done** |
| **C2** | `shell_css` + `layout` 松绑 | **done** |
| **C3** | 样式 strict / 脚本 defer·version | **done** |
| **C4** | 条件导航 when/media(layout 见 C2) | **done** |
验收金样:`tests/ext/web-smoke.mq.md`、`tests/ext/web-security-smoke.mq.md`、`tests/ext/web-drivers-smoke.mq.md`、`tests/ext/web-upload-smoke.mq.md`、`tests/ext/web-db-w6-smoke.mq.md`、`tests/ext/web-w7-finish-smoke.mq.md`、`tests/ext/web-p3-smoke.mq.md`、`ext_cli_add_web`。
---
@@ -57,3 +69,4 @@
| [design/ext-web.md](../design/ext-web.md) | **真理** |
| [user-site.md](../design/user-site.md) | 静态站互补 |
| [ext-quantum.md](ext-quantum.md) | 同属官方 ext + ABI + `ext add` |
| [ext-hosting.md](ext-hosting.md) · [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) | **W/C 之后**:同域 SSE 中继、HTTP→`##`(不重开本表 W0–W7) |
+2 -1
View File
@@ -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)
---
+2 -2
View File
@@ -18,7 +18,7 @@
| **诊断** | 语句级 `path:line:col: message`;字节码指令带 `spans`;errors 金样例双后端断言位置 | **P0 完成** |
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
| **标准库** | 核心 L1 + Mid M1–M6 + Mid2 M7–M10 已完成([stdlib-modules.md](../design/stdlib-modules.md) · [stdlib-mid2.md](../design/stdlib-mid2.md)) | **P2 + Mid1 + Mid2 完成** |
| **模块** | [module-namespace.md](../design/module-namespace.md):**M1+M2 已落地**(库名绑定、`库.成员` / `use`;无扁平合并) | — |
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
@@ -174,7 +174,7 @@ flowchart LR
### 风险与边界
- 静态 `gh-pages` **无法**真断点(无常驻 VM);调试仅 **live view**(或未来 WASM 解释器)。
- 静态 `gh-pages` **无法**真断点(无常驻 VM);调试仅 **live view**(或 [浏览器 WASM 解释器](browser-wasm.md) C5)。
- 字节码调试可晚于树遍历一个迭代。
---
+200
View File
@@ -0,0 +1,200 @@
# 路线图:中层标准库(数个版本)
| | |
|---|---|
| 状态 | **M1–M6 已落地**(收口) |
| 日期 | 2026-09-07 |
| 设计 | [stdlib-mid.md](../design/stdlib-mid.md) |
| 后续 | [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) |
| 相关 | [stdlib-modules.md](../design/stdlib-modules.md) · [next-phase.md](next-phase.md) · [ext-cli.md](../design/ext-cli.md) |
> **不预标 SemVer。** 每一波随当时产品发版合入;下文用 **M1…M6** 波次名。每波须可单独演示、可回滚。
---
## 0. 总序
```text
M1 文本与编解码地基 re + encoding ← 最先解锁「无插件写库」
M2 路径与文件中层 path + fs 加厚
M3 完整性与机密 hash + secrets
M4 表格数据与文本加厚 csv + text++
M5 集合与 CLI 糖 table/listx + cli
M6 可观测与标识 log + uuid(+ 可选 yaml)
```
原则:
1. **先原语、后糖**:正则 / 编解码 / 路径先于 CLI 糖与日志格式。
2. **每波必须有金样 + public 短页**;无文档不算完成。
3. **并行约束**:不阻塞 `ext/linalg` 等已定领域工作;但新官方能力评审优先问 Mid。
4. **插件冻结规则**:自 M1 起,官方新增「通用」ABI 插件默认 **拒绝**,除非设计文档论证无法用 host+L1。
---
## 1. 现状缺口(开工依据)
| 能力 | 现状 | 后果 |
|------|------|------|
| 正则 | 无 | 校验、替换、简单解析只能 foreign 或插件 |
| base64 / hex | 无(仅有 `url_encode`) | 令牌、摘要、嵌二进制文本困难 |
| 路径代数 | `fs` 只做 I/O | 拼接靠字符串,跨平台易错 |
| 哈希 / HMAC | 无 | 校验、缓存键、签名只能外联 |
| CSV | 无 | 数据脚本推向外联 Python |
| `lib/text` | 3 个包装函数 | 「有 text 库」名不副实 |
| 安全随机 | 仅 `math.random` | 易误用于 token |
| 结构化日志 / flags | 无 | 每个脚本自造 |
对照:Go 日常高频包(`regexp`、`encoding/*`、`crypto`、`path/filepath`、`slices`)与 Python「难写对才进 stdlib」——正是 M1–M5 的选型来源;**不**把 HTTP 服务端、数据库驱动塞进 Mid(见设计文 §3.2)。
---
## 2. 波次明细
### M1 — 正则与编解码(最高优先) — **done**
| 交付 | 说明 |
|------|------|
| `lib/re.mq.md` / `lib/正则.mq.md` | `is_match` / `find` / `find_all` / `replace` / `split` |
| `lib/encoding.mq.md` / `lib/编码.mq.md` | `base64_*` / `hex_*` |
| Host | `host_re_*`(`regex`)、`host_encoding_*`(无第三方编解码 crate) |
| 金样 | `tests/lib/re-smoke` · `正则-烟测` · `encoding-smoke` · `编码-烟测` |
| 文档 | [stdlib-re.md](../design/stdlib-re.md) · [stdlib-encoding.md](../design/stdlib-encoding.md) · public `08-re-encoding` |
| 验收 | 无插件:邮箱式校验 + base64/hex 往返 |
**刻意不做:** 回溯引用极致兼容、替换回调、完整 PCRE 方言文档化——先 RE2/ Rust `regex` 语义并写清。
---
### M2 — 路径与文件中层 — **done**
| 交付 | 说明 |
|------|------|
| `lib/path.mq.md` / `lib/路径.mq.md` | `join` / `split` / `file_name` / `parent` / `extension` / `normalize` / `is_absolute` |
| `lib/fs` 加厚 | `copy_file` / `move` / `make_temp`(文本边界;无 `read_bytes`) |
| Host | `host_path_*`、`host_copy_file` / `host_move` / `host_make_temp` |
| 金样 | `path-smoke` · `路径-烟测` · `fs-copy-move` · `文件-复制` |
| 文档 | [stdlib-path.md](../design/stdlib-path.md) · [stdlib-fs-mid.md](../design/stdlib-fs-mid.md) · public `09-path-fs` |
| 验收 | 规范化 + 沙箱内复制/移动 |
**刻意不做:** 完整 `shutil`、监视 `inotify`、权限 ACL 全家桶。
---
### M3 — 哈希与机密 — **done**
| 交付 | 说明 |
|------|------|
| `lib/hash.mq.md` / `lib/哈希.mq.md` | `sha256` / `sha1` / `md5` / `hmac_sha256` |
| `lib/secrets.mq.md` / `lib/机密.mq.md` | `token_hex` / `token_urlsafe` |
| Host | `host_hash_*`、`host_secrets_*`(`sha2`/`sha1`/`md-5`/`hmac`/`getrandom`) |
| 金样 | `hash-smoke` · `哈希-烟测` · `secrets-smoke` · `机密-烟测` |
| 文档 | [stdlib-hash.md](../design/stdlib-hash.md) · [stdlib-secrets.md](../design/stdlib-secrets.md) · public `10-hash-secrets` |
| 验收 | 已知向量 + 令牌长度 |
**刻意不做:** 密码哈希(Argon2/bcrypt)、完整 TLS、证书管理——仍属服务端/安全产品。
---
### M4 — CSV 与文本加厚 — **done**
| 交付 | 说明 |
|------|------|
| `lib/csv.mq.md` / `lib/逗号表.mq.md` | `parse` / `stringify`(首行表头 → list of maps) |
| `lib/text` / `文本` 加厚 | `contains` / `starts_with` / `ends_with` / `replace` / `to_upper`/`to_lower` / `repeat` / `pad` |
| Host | `host_csv_*`、`host_text_*` |
| 金样 | `csv-smoke` · `逗号表-烟测` · `text-mid-smoke` · `文本-加厚-烟测` |
| 文档 | [stdlib-csv.md](../design/stdlib-csv.md) · [stdlib-text-mid.md](../design/stdlib-text-mid.md) · public `11-csv-text` |
| 验收 | CSV 往返 + 文本清洗小例 |
**可选同波:** 极简 `format`(`{name}` 替换),若与引用语法冲突则延后。
---
### M5 — 集合算法与 CLI — **done**
| 交付 | 说明 |
|------|------|
| `lib/table` / `表` 加厚 | `sort` / `sort_by` / `unique` / `chunk` / `zip` / `flatten`(`reverse` 已有) |
| `lib/cli.mq.md` / `lib/命令行.mq.md` | `parse`(`--k v` / `--k=v` / `--flag`;位置参 `_`) |
| Host | `host_list_sort*` / `unique` / `chunk` / `zip` / `flatten`、`host_cli_parse` |
| 金样 | `table-list-mid` · `cli-sort-smoke` · `表-命令行-烟测` |
| 文档 | [stdlib-list-cli.md](../design/stdlib-list-cli.md) · public `12-list-cli` |
| 验收 | CSV 按键排序 + 参数解析 |
**刻意不做:** 泛型迭代器协议、惰性流、完整 argparse 互斥组。
---
### M6 — 日志、UUID、收口 — **done**
| 交付 | 说明 |
|------|------|
| `lib/log.mq.md` / `lib/日志.mq.md` | `debug`/`info`/`warn`/`error`;level 过滤;一行文本 |
| `lib/uuid.mq.md` / `lib/标识.mq.md` | `v4` |
| Host | `host_log_set_level` / `host_log_line`、`host_uuid_v4` |
| 金样 | `log-uuid-smoke` · `日志-标识-烟测` |
| 文档 | [stdlib-log-uuid.md](../design/stdlib-log-uuid.md) · public `13-log-uuid` |
| 文档收口 | `stdlib-modules.md` 总表;设计文状态 → **M1–M6 已落地** |
| 可选未做 | `yaml` 只读子集(默认不做) |
---
## 3. 跨波次工程清单
每波共用:
- [ ] 中英 L1 对称([stdlib-i18n.md](../design/stdlib-i18n.md))
- [ ] `host_*` 形参在 L1 **全量转发**([stdlib-modules.md](../design/stdlib-modules.md) §2.1)
- [ ] 双后端金样(tree + bytecode,若该 host 已接线)
- [ ] WASM:标注 `host-only` 或实现 stub
- [ ] CHANGELOG「标准库」条目
- [ ] skill `examples.md` 增加 Mid 惯用写法(GFM 优先)
宿主膨胀守卫:
- 新增 crate 须在 PR/设计中写清:**为何不能纯 mq**、**features 如何裁剪**、**许可证**。
- 禁止借 Mid 把 `ext/web` 的服务端栈链进主二进制。
---
## 4. 与官方扩展的互动(减插件)
| 扩展 | Mid 落地后可做的减负 |
|------|----------------------|
| `ext/web` | 路由/校验用 `re`;ETag/缓存键用 `hash`;静态路径用 `path` |
| `ext/agent` | 工具参数校验、密钥材料用 `secrets`/`hash`(领域核仍插件) |
| `ext/ai/llm` | 头/体编解码走 `encoding` |
| `ext/linalg` / `quantum` | **不**迁入 Mid;继续插件;仅共用 `path`/`hash` 等通用面 |
跟踪方式:某波完成后,开短 issue/清单「ext X 可删除的原生辅助」,不强迫同波大改。
---
## 5. 建议人力切分(示意)
| 波次 | 大致体量 | 可演示产物 |
|------|----------|------------|
| M1 | 中 | 「正则替换 + base64 往返」用户页 |
| M2 | 中 | 「安全拼接路径写文件」 |
| M3 | 小–中 | 「下载内容 sha256 校验」 |
| M4 | 中 | 「CSV → 表 → 打印」 |
| M5 | 小–中 | 「零插件数据 CLI」 |
| M6 | 小 | 「带 log level 的脚本」 |
若只能开一条线:**M1 → M3 → M2 → M4 → M5 → M6**(完整性校验常比路径代数更刚需时,M3 可紧贴 M1)。
---
## 6. 完成定义(整条 Mid 叙事)
当 M1–M6 完成时,对外可宣称:
> Marqdo 自带中层标准库:正则、编解码、路径、哈希、CSV、加厚文本与集合/CLI 糖,以及日志与 UUID;**写通用脚本与多数扩展库不再需要原生插件。**
> 插件保留给 web 运行时、智能体、量子与线性代数等**领域引擎**。
---
## 7. 一句话
**按 M1→M6 把通用原语沉进 `lib/`,用数个发版周期换掉「事事插件」——领域 `ext/` 继续尖,语言本体变宽。**
+91
View File
@@ -0,0 +1,91 @@
# 路线图:中层标准库第二波(M7–M10)
| | |
|---|---|
| 状态 | **Completed · M7–M10 已落地(zip 跳过)** |
| 日期 | 2026-09-09 |
| 设计 | [stdlib-mid2.md](../design/stdlib-mid2.md) |
| 缺口 | [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) |
| 前序 | [stdlib-mid.md](stdlib-mid.md)(**M1–M6 done**) |
| 基线 | v0.3.7+ |
> **不预标 SemVer。** 波次名 **M7…M10**;每波可单独演示、可回滚。
---
## 0. 总序
```text
M7 时间与地址 datetime + url
M8 配置与安全字面 toml(只读) + html.escape + encoding/base32
M9 文件再厚 fs make_dirs / remove_tree / stat / walk
M10 收口糖(可选) stats 薄 · log 字段 · (zip 默认跳过)
```
原则:
1. 继承 Mid1 宪法:通用、难写对、小宿主、可冻 API。
2. **TOML 优先于 YAML**(对齐 PEP 680 教训)。
3. 不阻塞宿主 / ext 产品线;但新「通用」ABI 插件默认拒绝。
---
## 1. 波次明细
### M7 — datetime + url — **done**
| 交付 | 说明 |
|------|------|
| `lib/datetime` · `日期时间` | now/parse/format/add/unix/zone 子集 |
| `lib/url` · `地址` | parse · query_parse/stringify(手写;无 `url` crate) |
| Host | `host_datetime_*` · `host_url_*` |
| 金样 | `tests/lib/datetime-smoke` · `url-smoke`(中英) |
| public | `14-datetime-url` · `14-日期时间地址` |
| 设计 | [stdlib-datetime.md](../design/stdlib-datetime.md) · [stdlib-url.md](../design/stdlib-url.md) |
### M8 — toml + html + encoding — **done**
| 交付 | 说明 |
|------|------|
| `lib/toml` · `配置表` | 只读子集 `parse` |
| `lib/html` · `超文本` | `escape` / `unescape` |
| `encoding` base32 | RFC 4648 |
| 金样 | `toml-html-encoding-smoke`(中英) |
| public | `15-toml-html-encoding` · `15-配置表超文本编码` |
| 设计 | [stdlib-toml.md](../design/stdlib-toml.md) · [stdlib-html.md](../design/stdlib-html.md) |
### M9 — fs 加厚 — **done**
| 交付 | 说明 |
|------|------|
| `make_dirs` / `remove_tree` / `stat` / `walk` | 见 [stdlib-fs-mid2.md](../design/stdlib-fs-mid2.md) |
| 金样 | `fs-mid2-smoke`(中英) |
| public | `16-fs-mid2` · `16-文件mid2` |
### M10 — 可选收口 — **done**(zip 跳过)
| 交付 | 说明 |
|------|------|
| `lib/stats` · `统计` | mean / median / sample stdev |
| `log` `fields=` | 行尾 `key=val` |
| zip | **跳过** |
| 金样 | `stats-log-smoke`(中英) |
| public | `17-stats-log` · `17-统计日志` |
| 设计 | [stdlib-stats-log.md](../design/stdlib-stats-log.md) |
---
## 2. 进度勾选
- [x] M7 datetime + url
- [x] M8 toml + html + base32
- [x] M9 fs 加厚
- [x] M10 可选(zip 跳过)
- [x] 研究文高优先级缺口 → closed(M7–M9;M10 为收口糖)
- [x] `stdlib-modules.md` / `stdlib.md` 状态同步
---
## 3. 成功标准
对外可宣称:在 Mid1(文本/路径/哈希/CSV/CLI/日志)之上,**日历、URL、TOML 配置、HTML 转义、实用 fs** 无需外联即可完成常见脚本与 catalog 工具——领域能力仍在 `ext/`。
+13
View File
@@ -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)。
+60
View File
@@ -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
+16
View File
@@ -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)。
+89
View File
@@ -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
+21
View File
@@ -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)。
+283
View File
@@ -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**
+96
View File
@@ -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
+21
View File
@@ -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)。
+27
View File
@@ -0,0 +1,27 @@
---
title: browser counter (C3)
description: wire table + browser.set_text — no json glue
import browser:lib/browser.mq.md
---
# main
*`count` = 0*
`wire` =
| @ | 选择器 | 事件 | 调用 |
|---|--------|------|------|
| 1 | "#bump" | click | bump |
| 2 | "#reset" | click | reset |
**`wire`**
## bump
*`count` = count + 1*
*`label` = > str count*
**> browser.set_text sel="#count" text=label**
## reset
*`count` = 0*
**> browser.set_text sel="#count" text="0"**
+86
View File
@@ -0,0 +1,86 @@
<!DOCTYPE html>
<html lang="zh-Hans">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Marqdo · fetch / after (C4)</title>
<style>
:root {
--ink: #1a1f1c;
--paper: #e8efe6;
--accent: #2f6f4e;
--muted: #5a6b60;
}
* { box-sizing: border-box; }
body {
margin: 0;
min-height: 100vh;
font-family: "IBM Plex Sans", "Noto Sans SC", sans-serif;
color: var(--ink);
background:
radial-gradient(800px 420px at 0% 100%, #d5e4d8 0%, transparent 55%),
linear-gradient(165deg, #f3f7f2, var(--paper));
padding: 2rem clamp(1rem, 4vw, 3rem);
}
h1 {
font-family: "IBM Plex Serif", "Noto Serif SC", serif;
font-weight: 600;
font-size: clamp(1.6rem, 3vw, 2.2rem);
margin: 0 0 0.35rem;
}
.lead { color: var(--muted); margin: 0 0 1.25rem; max-width: 38rem; }
#status {
font-family: "IBM Plex Mono", ui-monospace, monospace;
font-size: 0.95rem;
line-height: 1.45;
white-space: pre-wrap;
word-break: break-all;
min-height: 4rem;
margin: 1rem 0 1.25rem;
padding: 0.85rem 1rem;
background: rgba(255,255,255,0.55);
border: 1px solid #b7c7bb;
}
button {
margin-right: 0.5rem;
margin-bottom: 0.4rem;
padding: 0.55rem 1.1rem;
border: 0;
background: var(--accent);
color: #f5faf6;
font: inherit;
cursor: pointer;
}
button.secondary { background: #3a4740; }
button:disabled { opacity: 0.5; cursor: wait; }
pre {
margin-top: 1.5rem;
width: min(42rem, 100%);
padding: 0.9rem 1rem;
background: #122018;
color: #d7eadc;
overflow: auto;
font-size: 0.8rem;
line-height: 1.4;
}
.err { color: #ffb4a8; }
a { color: var(--accent); }
</style>
</head>
<body>
<h1>Marqdo</h1>
<p class="lead">C4/D:返回 <code>fetch</code> / <code>after</code> 效应;bridge 自启(ADR 0003)。业务只在 <code>fetch.mq.md</code>。<a href="./interact.html">计数器</a> · <a href="./form.html">表单</a> · <a href="./">打印</a></p>
<div id="status">idle</div>
<button id="load" type="button" disabled>请求 UUID</button>
<button id="ping" class="secondary" type="button" disabled>延迟 pong</button>
<pre id="log">loading…</pre>
<script
type="module"
src="./marqdo-bridge.js"
data-mq-wasm="./marqdo_wasm.wasm"
data-mq-source-url="./fetch.mq.md"
data-mq-ready="#log"
data-mq-enable="#load,#ping"
></script>
</body>
</html>
+42
View File
@@ -0,0 +1,42 @@
---
title: browser fetch (C4)
description: fetch/after effects via lib/browser — no json glue
import browser:lib/browser.mq.md
---
# main
`wire` =
| @ | 选择器 | 事件 | 调用 |
|---|--------|------|------|
| 1 | "#load" | click | load |
| 2 | "#ping" | click | ping |
**`wire`**
## load
*`msg` = > browser.set_text sel="#status" text="loading…"*
*`req` = > browser.fetch url="https://httpbin.org/uuid" then="on_uuid"*
**> browser.merge a=msg b=req**
## on_uuid
+ `ok`
+ `status`
+ `body`=""
+ `error`=""
1. ok
**> browser.set_text sel="#status" text=body**
2. *
**> browser.set_text sel="#status" text="fetch failed"**
## ping
*`msg` = > browser.set_text sel="#status" text="wait 600ms…"*
*`t` = > browser.after ms=600 then="on_ping"*
**> browser.merge a=msg b=t**
## on_ping
+ `ok`=True
**> browser.set_text sel="#status" text="pong"**
+76
View File
@@ -0,0 +1,76 @@
<!DOCTYPE html>
<html lang="zh-Hans">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Marqdo · 表单 (D3)</title>
<style>
:root {
--ink: #1a1f1c;
--paper: #e8efe6;
--accent: #2f6f4e;
--muted: #5a6b60;
}
* { box-sizing: border-box; }
body {
margin: 0;
min-height: 100vh;
font-family: "IBM Plex Sans", "Noto Sans SC", sans-serif;
color: var(--ink);
background:
radial-gradient(700px 400px at 100% 20%, #d0e0d4 0%, transparent 50%),
linear-gradient(165deg, #f3f7f2, var(--paper));
padding: 2rem clamp(1rem, 4vw, 3rem);
}
h1 {
font-family: "IBM Plex Serif", "Noto Serif SC", serif;
font-weight: 600;
font-size: clamp(1.6rem, 3vw, 2.2rem);
margin: 0 0 0.35rem;
}
.lead { color: var(--muted); margin: 0 0 1.25rem; max-width: 38rem; }
label { display: block; font-size: 0.85rem; color: var(--muted); margin: 0.75rem 0 0.35rem; }
input[type="text"] {
width: min(24rem, 100%);
padding: 0.5rem 0.75rem;
border: 1px solid #b7c7bb;
background: rgba(255,255,255,0.75);
font: inherit;
}
#echo {
margin-top: 1rem;
font-size: 1.25rem;
min-height: 1.5em;
}
#echo.hi { color: var(--accent); font-weight: 600; }
pre {
margin-top: 1.5rem;
width: min(42rem, 100%);
padding: 0.9rem 1rem;
background: #122018;
color: #d7eadc;
overflow: auto;
font-size: 0.8rem;
line-height: 1.4;
}
.err { color: #ffb4a8; }
a { color: var(--accent); }
</style>
</head>
<body>
<h1>Marqdo</h1>
<p class="lead">D3:<code>input</code> 事件把 <code>value</code> 传入 Marqdo;<code>set_value</code> / <code>set_class</code> / <code>set_attr</code> 回写 DOM。业务只在 <code>form.mq.md</code>。<a href="./interact.html">计数器</a> · <a href="./">打印</a></p>
<label for="name">名字</label>
<input id="name" type="text" placeholder="输入…" disabled />
<div id="echo">(等待输入)</div>
<pre id="log">loading…</pre>
<script
type="module"
src="./marqdo-bridge.js"
data-mq-wasm="./marqdo_wasm.wasm"
data-mq-source-url="./form.mq.md"
data-mq-ready="#log"
data-mq-enable="#name"
></script>
</body>
</html>
+33
View File
@@ -0,0 +1,33 @@
---
title: browser form (D3)
description: input wire passes value; effects via lib/browser
import browser:lib/browser.mq.md
import table:lib/table.mq.md
---
# main
`wire` =
| @ | 选择器 | 事件 | 调用 |
|---|--------|------|------|
| 1 | "#name" | input | on_input |
**`wire`**
## on_input
+ `value`=""
+ `event`=""
1. `value` != ""
*`label` = "你好," + value*
*`ret` = > browser.set_text sel="#echo" text=label*
*`cls` = > browser.set_class sel="#echo" class="hi"*
*`ret` = > browser.merge a=ret b=cls*
*`attrs` = > table.put in=None at="data-name" value=value*
*`attr` = > browser.set_attr sel="#echo" attrs=attrs*
**> browser.merge a=ret b=attr**
2. *
*`ret` = > browser.set_text sel="#echo" text="(等待输入)"*
*`cls` = > browser.set_class sel="#echo" class=""*
**> browser.merge a=ret b=cls**
+88
View File
@@ -0,0 +1,88 @@
<!DOCTYPE html>
<html lang="zh-Hans">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Marqdo browser hello (WASM C1)</title>
<style>
:root {
--ink: #1a1f1c;
--paper: #e8efe6;
--accent: #2f6f4e;
--muted: #5a6b60;
}
* { box-sizing: border-box; }
body {
margin: 0;
min-height: 100vh;
font-family: "IBM Plex Sans", "Noto Sans SC", sans-serif;
color: var(--ink);
background:
radial-gradient(1200px 600px at 10% -10%, #c5dcc8 0%, transparent 55%),
linear-gradient(165deg, #f3f7f2, var(--paper));
padding: 2rem clamp(1rem, 4vw, 3rem);
}
h1 {
font-family: "IBM Plex Serif", "Noto Serif SC", serif;
font-weight: 600;
font-size: clamp(1.6rem, 3vw, 2.2rem);
margin: 0 0 0.35rem;
letter-spacing: -0.02em;
}
.lead { color: var(--muted); margin: 0 0 1.5rem; max-width: 36rem; }
label { display: block; font-size: 0.85rem; color: var(--muted); margin-bottom: 0.35rem; }
textarea {
width: min(40rem, 100%);
min-height: 10rem;
padding: 0.75rem 0.9rem;
border: 1px solid #b7c7bb;
border-radius: 2px;
background: rgba(255,255,255,0.7);
font-family: "IBM Plex Mono", ui-monospace, monospace;
font-size: 0.9rem;
line-height: 1.45;
}
button {
margin-top: 0.85rem;
padding: 0.55rem 1.1rem;
border: 0;
background: var(--accent);
color: #f5faf6;
font: inherit;
cursor: pointer;
}
button:disabled { opacity: 0.5; cursor: wait; }
pre {
margin-top: 1.25rem;
width: min(40rem, 100%);
padding: 0.9rem 1rem;
background: #122018;
color: #d7eadc;
overflow: auto;
font-size: 0.85rem;
line-height: 1.4;
}
.err { color: #ffb4a8; }
</style>
</head>
<body>
<h1>Marqdo</h1>
<p class="lead">浏览器内 WASM(路线 C/D):源码是 <code>.mq.md</code>,官方 bridge 自启 playground,无作者业务 JS。<a href="./interact.html">交互</a> · <a href="./fetch.html">fetch</a> · <a href="./form.html">表单</a></p>
<label for="src">程序</label>
<textarea id="src"># main
> print text=Hello from browser WASM!
</textarea>
<div>
<button id="run" disabled>运行</button>
</div>
<pre id="out">loading wasm…</pre>
<script
type="module"
src="./marqdo-bridge.js"
data-mq-wasm="./marqdo_wasm.wasm"
data-mq-playground="#src,#run,#out"
data-mq-ready="#out"
></script>
</body>
</html>
+79
View File
@@ -0,0 +1,79 @@
<!DOCTYPE html>
<html lang="zh-Hans">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Marqdo · 交互装配 (C3)</title>
<style>
:root {
--ink: #1a1f1c;
--paper: #e8efe6;
--accent: #2f6f4e;
--muted: #5a6b60;
}
* { box-sizing: border-box; }
body {
margin: 0;
min-height: 100vh;
font-family: "IBM Plex Sans", "Noto Sans SC", sans-serif;
color: var(--ink);
background:
radial-gradient(900px 500px at 90% 0%, #cfe0d2 0%, transparent 50%),
linear-gradient(165deg, #f3f7f2, var(--paper));
padding: 2rem clamp(1rem, 4vw, 3rem);
}
h1 {
font-family: "IBM Plex Serif", "Noto Serif SC", serif;
font-weight: 600;
font-size: clamp(1.6rem, 3vw, 2.2rem);
margin: 0 0 0.35rem;
}
.lead { color: var(--muted); margin: 0 0 1.5rem; max-width: 36rem; }
#count {
font-family: "IBM Plex Serif", serif;
font-size: 4rem;
line-height: 1;
margin: 1rem 0 1.25rem;
letter-spacing: -0.04em;
}
button {
margin-right: 0.5rem;
padding: 0.55rem 1.1rem;
border: 0;
background: var(--accent);
color: #f5faf6;
font: inherit;
cursor: pointer;
}
button.secondary { background: #3a4740; }
pre {
margin-top: 1.5rem;
width: min(40rem, 100%);
padding: 0.9rem 1rem;
background: #122018;
color: #d7eadc;
overflow: auto;
font-size: 0.8rem;
line-height: 1.4;
}
.err { color: #ffb4a8; }
a { color: var(--accent); }
</style>
</head>
<body>
<h1>Marqdo</h1>
<p class="lead">C3/D:GFM 交互表装配事件;官方 <code>mount</code> 自启,业务只在 <code>counter.mq.md</code>。<a href="./fetch.html">fetch</a> · <a href="./form.html">表单</a> · <a href="./">打印</a></p>
<div id="count">0</div>
<button id="bump" type="button" disabled>加一</button>
<button id="reset" class="secondary" type="button" disabled>清零</button>
<pre id="log">loading…</pre>
<script
type="module"
src="./marqdo-bridge.js"
data-mq-wasm="./marqdo_wasm.wasm"
data-mq-source-url="./counter.mq.md"
data-mq-ready="#log"
data-mq-enable="#bump,#reset"
></script>
</body>
</html>
File diff suppressed because it is too large. Load diff
+20
View File
@@ -0,0 +1,20 @@
# browser-media(路线 F)
作者**零业务 JS**;`.mq.md` 用 **GFM 表格 + `lib/browser`**(禁止 `json.set` 链)。
| 能力 | 演示 |
|------|------|
| read_file | 文本 / DataURL |
| canvas | `@` 指令表 |
| audio | beep(Web Audio) |
| observe | Intersection + Resize |
| drag/drop | `data-drag` → `drop_text` |
```bash
cargo build -p marqdo --release
./target/release/marqdo wasm build -o examples/browser-media
cd examples/browser-media && python3 -m http.server 8767
```
写法约定见 [.cursor/skills/marqdo-dev/SKILL.md](../../.cursor/skills/marqdo-dev/SKILL.md)。
路线图:[browser-wasm-f.md](../../doc/roadmap/browser-wasm-f.md)。
+98
View File
@@ -0,0 +1,98 @@
<!DOCTYPE html>
<html lang="zh-Hans">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Marqdo · browser-media (route F)</title>
<style>
:root { --ink: #1a1f1c; --paper: #e8efe6; --accent: #2f6f4e; --muted: #5a6b60; }
* { box-sizing: border-box; }
body {
margin: 0; min-height: 100vh; font-family: "IBM Plex Sans", "Noto Sans SC", sans-serif;
color: var(--ink);
background: linear-gradient(165deg, #f3f7f2, var(--paper));
padding: 2rem clamp(1rem, 4vw, 3rem);
}
h1 { font-family: "IBM Plex Serif", "Noto Serif SC", serif; margin: 0 0 0.35rem; }
.lead { color: var(--muted); max-width: 42rem; }
section { margin: 1.5rem 0; padding: 1rem 0; border-top: 1px solid #c5d4c9; }
button {
padding: 0.45rem 0.9rem; border: 0; background: var(--accent); color: #f5faf6;
font: inherit; cursor: pointer; margin: 0.2rem 0.35rem 0.2rem 0;
}
button.secondary { background: #3a4740; }
#pad {
display: block; background: #fff; border: 1px solid #b7c7bb;
margin-top: 0.75rem;
}
#chips { display: flex; gap: 0.5rem; flex-wrap: wrap; margin: 0.75rem 0; }
#chips span {
padding: 0.45rem 0.75rem; background: rgba(255,255,255,0.75);
border: 1px dashed #2f6f4e; cursor: grab; user-select: none;
}
#dropzone {
min-height: 3.5rem; padding: 0.85rem; border: 2px dashed #7a9584;
background: rgba(255,255,255,0.45); color: var(--muted);
}
#beacon {
margin-top: 8rem; padding: 2rem; background: #2f6f4e; color: #f5faf6;
text-align: center;
}
#preview { margin-top: 0.5rem; min-height: 1rem; }
pre {
margin-top: 1rem; padding: 0.85rem 1rem; background: #122018; color: #d7eadc;
font-size: 0.8rem; overflow: auto; max-width: 42rem;
}
.err { color: #ffb4a8; }
</style>
</head>
<body>
<h1>Marqdo browser-media</h1>
<p class="lead">路线 F:文件 / Canvas / Audio / Observer / 拖放 — <strong>无作者业务 JS</strong>。</p>
<section>
<h2>F1 文件</h2>
<input id="file" type="file" accept="image/*,text/*,.txt,.md" disabled />
<button id="read-text" type="button" disabled>读文本</button>
<button id="read-dataurl" type="button" disabled>读 DataURL</button>
<div id="preview"></div>
</section>
<section>
<h2>F2 Canvas · F3 Audio</h2>
<button id="draw" type="button" disabled>绘制</button>
<button id="play" type="button" disabled>蜂鸣</button>
<canvas id="pad" width="280" height="120"></canvas>
</section>
<section>
<h2>F4 Observer</h2>
<button id="watch" type="button" disabled>开始观察</button>
<button id="unwatch" class="secondary" type="button" disabled>停止</button>
<p id="obs">idle</p>
<p>向下滚动可触发 Intersection;改窗口大小触发 Resize。</p>
</section>
<section>
<h2>F5 拖放</h2>
<div id="chips">
<span draggable="true" data-drag="alpha">alpha</span>
<span draggable="true" data-drag="beta">beta</span>
<span draggable="true" data-drag="gamma">gamma</span>
</div>
<div id="dropzone">拖到这里</div>
</section>
<div id="beacon">beacon(滚到可见)</div>
<pre id="log">loading…</pre>
<script
type="module"
src="./marqdo-bridge.js"
data-mq-wasm="./marqdo_wasm.wasm"
data-mq-source-url="./media.mq.md"
data-mq-ready="#log"
data-mq-enable="#file,#read-text,#read-dataurl,#draw,#play,#watch,#unwatch"
></script>
</body>
</html>
Loaded 100 of 302 files, more files were not shown because too many files have changed in this diff. Show more