Compare commits

...
85 Commits
Author SHA1 Message Date
cflmyandCursor 00a77181ef docs(skill): note Go libweb default for v0.4.0
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-13 15:10:00 +08:00
cflmyandCursor e13468dc43 release: v0.4.0 — Go libweb default and anlian-mq
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-13 15:09:45 +08:00
cflmyandCursor d3b137c919 feat(anlian-mq): align site with Django anlian browse UX
Port original CSS/JS/assets, rebuild home as four sections with feed
fragments, expand schema (boards/notices/rooms/topics), and add
page.chrome HTML overrides plus invoke html returns so Marqdo can
render Django-class chrome without json glue.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 22:46:55 +08:00
cflmyandCursor e292c8a7c7 feat(anlian-mq): port pink-glass theme, hero motion, and brand assets
Replace the warm-paper placeholder shell with GFM style tables that
mirror Django anlian (fixed bg, frosted nav, pulse logo, hero float,
glass cards). Ship original static assets and tighten smoke for visuals.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 21:32:46 +08:00
cflmyandCursor ce195998c1 feat(web): W-G14 anlian-mq acceptance and auth/session listen fixes
Add a GFM-first anlian rewrite under examples/anlian-mq to exercise Go
libweb (lists, detail, gates, login, WS). Wire RBAC/login into listen,
page query/order/detail ABIs, and stop issuing Max-Age=0 CSRF cookies so
browser login sessions stick.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 21:20:11 +08:00
cflmyandCursor e20cf8b386 feat(web): serve upload, WS, proxy, and gallery on Go listen
Mount media/ws/proxy/invoke routes in httpx, force gold onto Go via
MARQDO_WEB_PLUGIN, and case-fold middleware header checks so all seven
web live golds pass against libweb.so.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 20:52:29 +08:00
cflmyandCursor c4a726397d feat(web): W-G13 default to Go libweb in CLI, gold, and release
Switch ext add / gold / release builds to scripts/build-web-plugin.sh,
drop the Rust archive from the Cargo workspace, and resolve libweb from
plugins/web/build (and target copies) without MARQDO_WEB_PLUGIN.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 20:18:41 +08:00
cflmyandCursor 7fab85b389 fix(web): expose web_db_table_info for admin schema forms
Wire existing db.TableInfo through the C ABI so offline admin smoke
can introspect columns before form_from_schema.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 20:12:32 +08:00
cflmyandCursor 12d2c7be69 feat(web): Go W-G12 rooms, Redis session, and API keys
Add mode=room with room_key hub APIs, optional redis:// session
backend, and web_api_key_check (sha256 pepper:key) for anlian primitives.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 20:10:43 +08:00
cflmyandCursor 26955f4f36 feat(web): Go W-G11 render head links for C2–C4
Emit page.head scripts/styles with defer and asset versioning so
shell/layout, style/head, and nav when/media offline smokes pass.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 20:07:04 +08:00
cflmyandCursor 56df0736fa feat(web): Go W-G10 proxy and invoke route bags
Register web_app_proxy/invoke and merge configure tables into
proxy_routes/invoke_routes so offline proxy-invoke smoke passes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 20:02:46 +08:00
cflmyandCursor 695939ac74 feat(web): Go W-G9 memory/Redis cache drivers
Wire web_cache_* ABIs with an in-process memory backend and go-redis
ops so drivers smoke covers cache, file storage, postgres URL, and s3 open.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 19:41:10 +08:00
cflmyandCursor 4c06851e0e feat(web): Go W-G8 WebSocket routes and access_log
Register route_ws/ws_connect ABIs with an in-process broadcast hub
so offline WS broadcast and access_log smokes pass on libweb.so.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 19:31:03 +08:00
cflmyandCursor 23e4bc406e feat(web): Go W-G7 RSS, sitemap, redirect, and SEO bags
Add paginate/meta wiring, RSS and sitemap builders, and app
redirect/error/sitemap/robots route bags so content and W7 offline
smokes pass on libweb.so.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 17:51:50 +08:00
cflmyandCursor fe18c4d1d6 docs(web): mark W-G6 complete in rewrite plan
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 17:41:59 +08:00
cflmyandCursor e6fdeb0b31 feat(web): Go W-G6 storage, upload, gallery, and assets
Add file: storage, media validate/save, app upload/download/gallery
route bags, and head/images/icons assembly so offline upload, assets,
and P3 smokes pass on libweb.so.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 17:41:59 +08:00
cflmyandCursor 5ec4b3c17d docs(web): mark W-G5 complete in rewrite plan
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 17:31:07 +08:00
cflmyandCursor 6e94d0a179 feat(web): Go W-G5 session, auth, password, and RBAC gates
Wire password hash, session CRUD, auth login/check/logout, and
app.auth/gate ABIs so security and C0/C1 offline smokes pass on libweb.so.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 17:31:07 +08:00
cflmyandCursor 4357045904 docs(web): mark W-G4 complete in rewrite plan
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 16:50:30 +08:00
cflmyandCursor 1ef71d7492 feat(web): Go W-G4 listen, static, middleware, and JSON routes
Add app.static / configure middleware bags and blocking httpx.Listen
(home, routes, _part, static, forms, JSON API, CORS/gzip layers).
Pass route/static/middleware/part offline smokes against libweb.so.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 16:41:59 +08:00
cflmyandCursor 1fc985db7e docs(web): mark W-G2/W-G3 complete in rewrite plan
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 16:03:53 +08:00
cflmyandCursor 364428ca1e feat(web): Go W-G2 txn/migrate/FTS and W-G3 form ABI
Wire begin/commit/rollback, migrations, FTS search, and form
rules/validate/render/submit/from_schema plus mount_form; pass
web-db-w2, web-db-w6, and web-form-smoke against libweb.so.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 16:01:17 +08:00
cflmyandCursor 09b549a862 docs(web): note W-G2 CRUD/where progress after select-smoke
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 15:34:42 +08:00
cflmyandCursor 2d238a8c36 feat(web): Go SQLite update/delete/query/count + where filters
Complete core CRUD beyond smoke: typed where (map + filter ops),
register web_db_update/delete/query/count, and pass web-select-smoke.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 15:34:15 +08:00
cflmyandCursor 7a0309284a feat(web): Go plugin W-G1 assemble/render + SQLite smoke path
Port table/compose/style/render/db/form/app bags, register ABI symbols,
prefer MARQDO_WEB_PLUGIN over ~/.marqdo, and pass web-smoke + web-zh-smoke.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 15:27:12 +08:00
cflmyandCursor fd3f1724e6 chore: ignore Go web plugin build/ artifacts
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 14:48:07 +08:00
cflmyandCursor ca40c698a2 refactor(web): start Go ABI rewrite of plugins/web (W-G0)
Archive the Rust web plugin and add a Go c-shared skeleton with ABI v2
bridge, build script, design doc/ADR, and smoke test so multi-language
plugins and full web parity can proceed wave by wave.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-10 14:47:43 +08:00
cflmyandCursor fb6254e501 fix: GAP-11 form slot mount and GAP-12 MARQDO_EXT import hint
compose_form/表单装配 can inject into intro via target/表单插槽; unresolved
ext/ imports hint to set MARQDO_EXT when unset.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 16:52:41 +08:00
cflmyandCursor cf9d96477b fix(release): avoid env http_proxy when git uses HK jump -c
Match the proven push path: clear env proxies and set only git -c http.proxy.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 16:15:23 +08:00
cflmyandCursor 493d0ad91a fix(release): use Basic auth in HK jump git push
GIT_ASKPASS hung under agent/no-TTY; prefer http.extraHeader from credential store.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 15:52:33 +08:00
cflmyandCursor a0e88919a6 docs(release): add HK Paramiko jump for GitHub push recovery
Document the proven hk.cflmy.de CONNECT path and ship push-via-hk-jump.py so flaky Clash/reverse-proxy no longer blocks releases.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 15:44:17 +08:00
cflmyandCursor 237962c3be release: v0.3.9 — GAP-06–10 parser, invoke, exec, SSE
Ship business-integration fixes: star/JSON body recovery, invoke Null,
sys.exec capture, and proxy anti-buffer headers.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 14:12:43 +08:00
cflmyandCursor 1637acce6e fix: GAP-06–10 parser, invoke Null, exec capture, SSE headers
Recover ## bodies after bad *…* terminators; bracket-aware call args;
invoke Null is 500 not fake ok; sys.exec capture={code,stdout,stderr};
proxy stream sets anti-buffer headers.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 13:58:02 +08:00
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
457 changed files with 54941 additions and 2852 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)
+7 -5
View File
@@ -6,8 +6,9 @@ description: >-
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.
failures via proxy or HK SSH jump (scripts/push-via-hk-jump.py). Use when the
user asks to release, cut a version, publish vX.Y.Z, ship a GitHub release,
发版, 发布新版本, or tag marqdo.
---
# Marqdo release
@@ -22,7 +23,7 @@ Canonical release playbook for **cflmy/marqdo**. Read this skill **before** tagg
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.
7. After network errors: apply [reference.md § Proxy](reference.md); retry; do not silently skip uploads. If GitHub stays unreachable but **HK jump** (`hk.cflmy.de`) works, use `scripts/push-via-hk-jump.py` (Paramiko CONNECT) — see reference § **HK SSH jump**.
## Defaults (after version is confirmed)
@@ -105,7 +106,7 @@ release: vVER — <one-line highlight>
EOF
```
Push `main`: `git push origin main` (with proxy/`all` perms if needed).
Push `main`: `git push origin main` (with proxy/`all` perms if needed; on persistent GitHub failure use [reference § HK SSH jump](reference.md)).
## Phase 3 — VS Code / Cursor extension
@@ -152,7 +153,8 @@ Local Windows fallback: `scripts/release-full.ps1 -Tag TAG -Upload` (see script
| Failure | Action |
|---------|--------|
| `gh` / git TLS or proxy `7890` refused | Unset bad proxy; use working `HTTP(S)_PROXY` or `required_permissions: ["all"]`; see reference |
| `gh` / git TLS or Clash `7890` refused | Unset bad proxy; `required_permissions: ["all"]`; see [reference § Proxy](reference.md) |
| GitHub blocked / `proxy.cflmy.top` push timeout | **HK SSH jump**: `scripts/push-via-hk-jump.py` (ask user for HK password/key; never commit). See reference § **HK SSH jump** |
| Tag exists | Stop; ask user to bump or delete tag (no force on shared tags without explicit order) |
| CI red | Fix on main, move tag only if user explicitly allows delete+re-push tag |
| VSIX missing | Fetch `vscode-extension`, build locally, `gh release upload TAG dist/*.vsix` |
+50 -6
View File
@@ -33,6 +33,8 @@ Produced by `.github/workflows/release.yml` on **windows-latest**:
| `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`) |
@@ -164,7 +166,7 @@ git checkout vVER
cargo build --release
./target/release/marqdo version
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
marqdo ext add web && marqdo ext add agent && marqdo ext add quantum
# 中文 id:网页 / 智能体 / 量子
```
@@ -204,14 +206,16 @@ marqdo wasm build
## Proxy & auth (network recovery)
Symptoms seen in this project: broken local proxy on `127.0.0.1:7890`, TLS failures, `gh` needing token, Cursor sandbox blocking git/gh.
Symptoms seen in this project: broken local Clash on `127.0.0.1:7890`, flaky `proxy.cflmy.top` HTTPS (short GET OK, long `git push` / connect timeouts), TLS failures, `gh` needing token, Cursor agent sandbox with only `lo`.
### Diagnose
```bash
env | grep -iE 'proxy|PROXY' || true
curl -sI https://github.com | head -5
curl -sI --max-time 15 https://github.com | head -5
curl -sS --max-time 15 -o /dev/null -w 'proxy=%{http_code}\n' https://proxy.cflmy.top/ || true
gh auth status
ip -br addr | head -5 # agent may lack enp*; use required_permissions: ["all"]
```
### Fix order
@@ -220,6 +224,7 @@ gh auth status
```bash
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy
# also clear for one git call: git -c http.proxy= -c https.proxy= …
```
2. **Set a working proxy** only if the user provides one (or known working):
@@ -231,17 +236,19 @@ 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**.
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**:
6. **HK SSH jump (preferred when GitHub is blocked but HK is reachable)** — see next subsection.
7. **Partial upload**:
```bash
gh release upload "vVER" dist/FILE --clobber
```
7. **Re-run CI** without retagging (if tag already correct):
8. **Re-run CI** without retagging (if tag already correct):
```bash
gh workflow run Release --ref "vVER" # only if workflow_dispatch exists; else fix + new patch tag
@@ -249,6 +256,43 @@ gh workflow run Release --ref "vVER" # only if workflow_dispatch exists; else f
Current Release workflow is **tag-push only**. Red CI after tag → fix on `main`, then either new patch tag or **user-approved** delete+recreate tag (dangerous; prefer patch).
### HK SSH jump (Paramiko CONNECT)
**When to use:** local → GitHub fails (timeout / TLS / Clash flaky / reverse-proxy `proxy.cflmy.top` connect drops), but this host can reach an overseas box that has stable GitHub (default `hk.cflmy.de`). Proven path for v0.3.9 push/tag/`gh`.
**Do not** rely on OpenSSH + `sshpass` here — password auth has hung; use **Paramiko** (`python3-paramiko`).
**Never** commit the HK root password or tokens. Ask the user for the password (or a key), put it in env / a `600` temp file, scrub after.
```bash
# one-shot password file (example — use the secret the user gave this session)
printf '%s' "$HK_PASSWORD_FROM_USER" > /tmp/.hk_ssh_pw && chmod 600 /tmp/.hk_ssh_pw
export HK_SSH_HOST=hk.cflmy.de # or 83.229.126.119
export HK_SSH_USER=root
export HK_SSH_PASSWORD_FILE=/tmp/.hk_ssh_pw
# optional: HK_JUMP_PORT=18081
SCRIPT=.cursor/skills/marqdo-release/scripts/push-via-hk-jump.py
# push / tag / extension (git gets CONNECT proxy + github.com askpass)
python3 "$SCRIPT" -- git push origin main
python3 "$SCRIPT" -- git push origin vscode-extension
python3 "$SCRIPT" -- git push origin vVER
# gh (sets GH_TOKEN from git credential fill if unset)
python3 "$SCRIPT" -- gh release edit vVER --notes-file /tmp/notes.md
python3 "$SCRIPT" -- gh run list --workflow=Release --limit 3
# leave proxy up for manual commands
python3 "$SCRIPT" --serve # then: export https_proxy=http://127.0.0.1:18081
rm -f /tmp/.hk_ssh_pw
```
Script behavior: SSH to HK → local `http://127.0.0.1:$HK_JUMP_PORT` HTTP CONNECT via `direct-tcpip` → run `git`/`gh`/`curl` with that proxy. Git auth uses local `git credential` via `http.extraHeader` (Basic) — **not** `GIT_ASKPASS` (askpass has hung under agent/no TTY). Tokens never go to the jump host disk.
Optional path reverse-proxy (`https://proxy.cflmy.top/github.com/…` `insteadOf`) may work for short GETs; treat long `git push` failures as a signal to use the HK jump instead of retrying Clash forever.
## Local Windows fallback
```powershell
+284
View File
@@ -0,0 +1,284 @@
#!/usr/bin/env python3
"""Push / run git|gh through an HK SSH jump host (Paramiko HTTP CONNECT).
When this machine cannot reach GitHub reliably but can SSH to a host that can
(e.g. hk.cflmy.de), open a local HTTP CONNECT proxy over Paramiko and run the
remaining command with http(s).proxy pointed at it.
Why Paramiko: OpenSSH/`sshpass` has hung on password auth in this environment;
Paramiko password + direct-tcpip works.
Credentials (never commit):
HK_SSH_PASSWORD password string
HK_SSH_PASSWORD_FILE file containing password (mode 600 recommended)
or SSH key via Paramiko agent/keys if password unset and key works
Optional env:
HK_SSH_HOST default hk.cflmy.de
HK_SSH_USER default root
HK_JUMP_PORT default 18081 (local CONNECT listen)
Usage:
HK_SSH_PASSWORD_FILE=/tmp/hk.pw \\
python3 .cursor/skills/marqdo-release/scripts/push-via-hk-jump.py -- \\
git push origin main
# keep proxy only (Ctrl+C to stop)
... push-via-hk-jump.py --serve
# wrap gh
... push-via-hk-jump.py -- gh release view v0.3.9
"""
from __future__ import annotations
import os
import select
import socket
import socketserver
import subprocess
import sys
import threading
import time
from pathlib import Path
try:
import paramiko
except ImportError as e: # pragma: no cover
raise SystemExit(
"paramiko required: apt install python3-paramiko (or pip install paramiko)"
) from e
ROOT = Path(__file__).resolve().parents[4]
class _Server(socketserver.ThreadingMixIn, socketserver.TCPServer):
allow_reuse_address = True
daemon_threads = True
def load_password() -> str | None:
path = os.environ.get("HK_SSH_PASSWORD_FILE")
if path:
return Path(path).read_text(encoding="utf-8").strip()
pw = os.environ.get("HK_SSH_PASSWORD")
return pw.strip() if pw else None
def connect_hk() -> paramiko.SSHClient:
host = os.environ.get("HK_SSH_HOST", "hk.cflmy.de")
user = os.environ.get("HK_SSH_USER", "root")
pw = load_password()
client = paramiko.SSHClient()
client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
kwargs: dict = {
"hostname": host,
"username": user,
"timeout": 20,
"auth_timeout": 25,
"banner_timeout": 25,
}
if pw:
kwargs.update(password=pw, allow_agent=False, look_for_keys=False)
else:
kwargs.update(allow_agent=True, look_for_keys=True)
print(f"== HK jump {user}@{host} ==", flush=True)
client.connect(**kwargs)
_, stdout, stderr = client.exec_command(
"hostname; curl -sS --max-time 20 -o /dev/null -w gh=%{http_code} https://github.com/; echo"
)
out = stdout.read().decode()
err = stderr.read().decode()
print(out, end="" if out.endswith("\n") else "\n", flush=True)
if err.strip():
print(err, file=sys.stderr, flush=True)
return client
def make_proxy(transport: paramiko.Transport, port: int) -> _Server:
class Handler(socketserver.StreamRequestHandler):
def handle(self) -> None:
try:
first = self.rfile.readline(65536)
if not first:
return
parts = first.decode("latin1", "replace").split()
if len(parts) < 2 or parts[0].upper() != "CONNECT":
self.wfile.write(b"HTTP/1.1 405 Method Not Allowed\r\n\r\n")
return
while True:
line = self.rfile.readline(65536)
if line in (b"\r\n", b"\n", b""):
break
host, _, port_s = parts[1].partition(":")
chan = transport.open_channel(
"direct-tcpip",
(host, int(port_s or "443")),
self.connection.getpeername(),
)
self.wfile.write(b"HTTP/1.1 200 Connection Established\r\n\r\n")
sock = self.connection
sock.setblocking(False)
chan.setblocking(False)
try:
while True:
r, _, x = select.select([sock, chan], [], [sock, chan], 120)
if x:
break
if sock in r:
data = sock.recv(65536)
if not data:
break
chan.sendall(data)
if chan in r:
data = chan.recv(65536)
if not data:
break
sock.sendall(data)
finally:
try:
chan.close()
except Exception:
pass
except Exception:
pass
return _Server(("127.0.0.1", port), Handler)
def github_basic_auth_header() -> str:
"""Authorization: Basic … from local git credential store (no askpass; askpass can hang)."""
import base64
out = subprocess.check_output(
["git", "credential", "fill"],
input=b"protocol=https\nhost=github.com\n\n",
).decode()
data = dict(line.split("=", 1) for line in out.splitlines() if "=" in line)
user = data.get("username") or "x-access-token"
password = data.get("password") or ""
if not password:
raise SystemExit("no github.com credential in git credential store")
token = base64.b64encode(f"{user}:{password}".encode()).decode()
return f"Authorization: Basic {token}"
def github_token() -> str | None:
out = subprocess.check_output(
["git", "credential", "fill"],
input=b"protocol=https\nhost=github.com\n\n",
).decode()
data = dict(line.split("=", 1) for line in out.splitlines() if "=" in line)
return data.get("password") or None
def run_with_proxy(proxy: str, argv: list[str]) -> int:
env = os.environ.copy()
for k in (
"http_proxy",
"https_proxy",
"HTTP_PROXY",
"HTTPS_PROXY",
"ALL_PROXY",
"all_proxy",
):
env.pop(k, None)
cmd = list(argv)
if cmd and cmd[0] == "git":
# Prefer http.extraHeader over GIT_ASKPASS (askpass has hung under agent/no TTY).
# Do not also set env http_proxy for git — only -c (avoids double-proxy quirks).
auth = github_basic_auth_header()
cmd = [
"git",
"-c",
f"http.proxy={proxy}",
"-c",
f"https.proxy={proxy}",
"-c",
"credential.helper=",
"-c",
f"http.extraHeader={auth}",
"-c",
"http.version=HTTP/1.1",
"-c",
"http.postBuffer=524288000",
*cmd[1:],
]
print(
"+",
" ".join(
c if not str(c).startswith("http.extraHeader=") else "http.extraHeader=<redacted>"
for c in cmd
),
flush=True,
)
return subprocess.call(cmd, cwd=ROOT, env=env)
env["http_proxy"] = proxy
env["https_proxy"] = proxy
env["HTTP_PROXY"] = proxy
env["HTTPS_PROXY"] = proxy
if cmd and cmd[0] == "gh" and not env.get("GH_TOKEN"):
tok = github_token()
if tok:
env["GH_TOKEN"] = tok
print("+", " ".join(cmd), flush=True)
return subprocess.call(cmd, cwd=ROOT, env=env)
def main(argv: list[str]) -> int:
args = argv[1:]
if not args or args[0] in ("-h", "--help"):
print(__doc__)
return 0 if args else 1
serve_only = args == ["--serve"]
if args[0] == "--":
args = args[1:]
if not serve_only and not args:
print("missing command after --", file=sys.stderr)
return 2
port = int(os.environ.get("HK_JUMP_PORT", "18081"))
client = connect_hk()
transport = client.get_transport()
assert transport is not None
server = make_proxy(transport, port)
threading.Thread(target=server.serve_forever, daemon=True).start()
proxy = f"http://127.0.0.1:{port}"
print(f"== CONNECT proxy {proxy} ==", flush=True)
# smoke
subprocess.call(
[
"curl",
"-sS",
"--connect-timeout",
"10",
"--max-time",
"25",
"--proxy",
proxy,
"-o",
"/dev/null",
"-w",
"github=%{http_code}\\n",
"https://github.com/",
]
)
try:
if serve_only:
print("serving; Ctrl+C to stop", flush=True)
while transport.is_active():
time.sleep(5)
return 1
return run_with_proxy(proxy, args)
finally:
server.shutdown()
client.close()
if __name__ == "__main__":
raise SystemExit(main(sys.argv))
+48 -11
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,8 @@ 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)
@@ -29,7 +32,9 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
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):** client logic is Marqdo on WASM ([ADR 0002](../../../doc/adr/0002-browser-marqdo-wasm.md)); async I/O via return effects `fetch`/`after` ([ADR 0003](../../../doc/adr/0003-browser-async-effects.md)); official bridge is host glue only.
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)
@@ -137,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`.
@@ -158,7 +177,7 @@ Import **one language file** — never mix EN/ZH API names in the same `.mq.md`:
- Authors use **GFM tables + `#` classes** — no `json.parse` / `json.set` glue, no hand-built part JSON.
- Table cells stay **literal strings**; path text like `` `posts`.`title` `` is resolved by web classes.
- **Quote path/MIME cells** that contain `/` (T5 cell expressions treat bare `/` as division): `"/static/logo.svg"`, `"image/png"`.
- **`ext/**` never calls `host_*`** — hot path is native `plugins/web` ABI.
- **`ext/**` never calls `host_*`** — hot path is native `plugins/web` ABI (default **Go `libweb`**, build via `scripts/build-web-plugin.sh`).
- HTTPS: terminate at reverse proxy; set `cookie_secure=True` on auth (no in-process TLS).
**Typical layout:**
@@ -175,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).
@@ -207,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`).
@@ -228,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`) |
@@ -244,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=
+81 -13
View File
@@ -20,13 +20,26 @@ jobs:
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
- name: Install Go (web plugin)
uses: actions/setup-go@v5
with:
go-version: "1.23.x"
- name: Install Node (VS Code extension)
uses: actions/setup-node@v4
with:
node-version: "20"
- name: Build release
run: cargo build --release
- name: Install MinGW for cgo (web.dll)
run: choco install mingw -y
- name: Build release CLI + official plugins
shell: bash
run: |
export PATH="/c/ProgramData/mingw64/mingw64/bin:/c/ProgramData/chocolatey/lib/mingw/tools/install/mingw64/bin:$PATH"
cargo build --release
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
bash ./scripts/build-web-plugin.sh
- name: Checkout extension sources (branch vscode-extension only)
run: git fetch origin vscode-extension && git checkout origin/vscode-extension -- vscode-extension
@@ -55,6 +68,7 @@ jobs:
$vsix = "marqdo-$ver.vsix"
$public = "marqdo-$ver-public.zip"
$extZip = "marqdo-$ver-ext.zip"
$nativeZip = "marqdo-$ver-native-$target.zip"
Copy-Item target/release/marqdo.exe "dist/$exe"
git archive --format=zip -o "dist/$source" HEAD
./target/release/marqdo view output public -o public
@@ -65,11 +79,27 @@ jobs:
Copy-Item ext "$stageExt/ext" -Recurse
if (Test-Path "dist/$extZip") { Remove-Item "dist/$extZip" -Force }
Compress-Archive -Path "$stageExt/*" -DestinationPath "dist/$extZip" -Force
# Prebuilt native plugins (no Rust required for `marqdo ext add`)
$stageNative = "dist/stage-native"
if (Test-Path $stageNative) { Remove-Item $stageNative -Recurse -Force }
New-Item -ItemType Directory -Force -Path "$stageNative/native" | Out-Null
Copy-Item target/release/web.dll "$stageNative/native/web.dll"
Copy-Item target/release/agent.dll "$stageNative/native/agent.dll"
Copy-Item target/release/quantum.dll "$stageNative/native/quantum.dll"
Copy-Item target/release/linalg.dll "$stageNative/native/linalg.dll"
if (Test-Path "dist/$nativeZip") { Remove-Item "dist/$nativeZip" -Force }
Compress-Archive -Path "$stageNative/*" -DestinationPath "dist/$nativeZip" -Force
$stage = "dist/stage-bundle"
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
New-Item -ItemType Directory -Force -Path $stage | Out-Null
Copy-Item target/release/marqdo.exe "$stage/marqdo.exe"
Copy-Item lib "$stage/lib" -Recurse
Copy-Item ext "$stage/ext" -Recurse
New-Item -ItemType Directory -Force -Path "$stage/ext/native" | Out-Null
Copy-Item target/release/web.dll "$stage/ext/native/web.dll"
Copy-Item target/release/agent.dll "$stage/ext/native/agent.dll"
Copy-Item target/release/quantum.dll "$stage/ext/native/quantum.dll"
Copy-Item target/release/linalg.dll "$stage/ext/native/linalg.dll"
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
$stageLib = "dist/stage-stdlib"
@@ -85,6 +115,7 @@ jobs:
echo "SOURCE=$source" >> $env:GITHUB_ENV
echo "PUBLIC=$public" >> $env:GITHUB_ENV
echo "EXT=$extZip" >> $env:GITHUB_ENV
echo "NATIVE=$nativeZip" >> $env:GITHUB_ENV
- name: Upload release assets
uses: softprops/action-gh-release@v2
@@ -92,24 +123,21 @@ jobs:
body: |
## Marqdo ${{ github.ref_name }}
### 亮点 / Highlights — v0.3.2
- **浏览器 Marqdo(路线 C)**:`marqdo wasm build`、官方 bridge、会话 ABI、`fetch`/`after` 效应;示例 `examples/browser-hello/`
- **Browser Marqdo (route C)**: WASM build, official bridge, session ABI, async effects; see CHANGELOG
- Fix: Admin 长内容布局 · `ext add` 原生插件预检 · `@keyframes` / 样式表比率引号约定
- 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
- **Go libweb 默认(W-G0–W-G14)**:网页原生插件 Go 重写;anlian-mq 验收;Release 含预编译 web.dll/libweb.so
- **Go libweb default (W-G0–W-G14)**: web plugin rewritten in Go; anlian-mq acceptance; prebuilt natives in Release
- **GAP-11/12**:表单插槽 · `MARQDO_EXT` 导入提示
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [ADR 0004](https://github.com/cflmy/marqdo/blob/main/doc/adr/0004-web-plugin-go.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 +148,49 @@ 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: Install Go (web plugin)
uses: actions/setup-go@v5
with:
go-version: "1.23.x"
- name: Build official plugins (release)
run: |
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
bash ./scripts/build-web-plugin.sh
- 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)
@@ -42,6 +43,9 @@ spike/.pytest_cache/
# 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/
@@ -56,11 +60,19 @@ plugins/*/tmp/
/examples/web-net-site/data/
/examples/web-net-site-zh/data/
/examples/marqdo-blog/data/
/examples/anlian-mq/data/
# Quantum draw/SVG runtime outputs (sources & gold .mq.md stay tracked)
/tests/ext/quantum-*.svg
/tests/ext/linalg-*.svg
/examples/quantum-*/**/*.svg
/examples/quantum-*/*.svg
/examples/linalg-*/**/*.svg
/examples/linalg-*/*.svg
/examples/linalg-*.svg
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
/ext/native/
# Go web plugin c-shared build output (./scripts/build-web-plugin.sh)
/plugins/web/build/
+200
View File
@@ -8,6 +8,206 @@
### Changed
## v0.4.0 — 2026-09-13
### Highlights
**Go `libweb` 默认落地(W-G0–W-G14)**:官方网页原生插件改为 Go C ABI;CLI / gold / Release 走 `scripts/build-web-plugin.sh`;Rust 源码归档。另附 **anlian-mq** 验收站与表单插槽 / `MARQDO_EXT` 提示修复。
```bash
git checkout v0.4.0
# 构建 web 原生插件(需 Go + cgo):
bash ./scripts/build-web-plugin.sh
marqdo ext add web
marqdo run examples/anlian-mq/index.mq.md
```
### Added
- **`plugins/web` Go 全量重写(W-G0–W-G13)**:C ABI 对等装配/DB/表单/listen/鉴权/上传/SEO/WS/驱动/proxy·invoke/定制壳;`scripts/build-web-plugin.sh` → `libweb.so` / `web.dll`;ADR [0004](doc/adr/0004-web-plugin-go.md) · 施工 [ext-web-go-rewrite.md](doc/design/ext-web-go-rewrite.md)。
- **W-G14 验收**:`examples/anlian-mq/`(暗恋见君风格论坛:路由/登录/粉玻璃主题/片段 API;SQLite 本地可跑)。
- **GAP-11**:`compose_form` / `表单装配` 支持 `target` / `表单插槽`(如 `#id`),把表单注入引言 HTML 内的挂载点。
### Fixed
- **GAP-12**:`ext/…` import 解析失败且未设置 `MARQDO_EXT` 时,错误附带 `hint: set MARQDO_EXT to the directory that contains web/`。
- **listen 会话 / CSRF**:登录后 `IssueCookie` 不再误设 `Max-Age=0`;页面 ABIs(`query`/`order`/`link_prefix`/`css`/`detail`)与 `web_page_chrome`、`invoke return=html` 对齐 anlian 需求。
### Changed
- **默认 `libweb` 为 Go**:Release / gold / `ext add web` 不再构建 Rust `marqdo_plugin_web`;旧 Rust 树移至 `plugins/web-rust-archive/`(非 workspace 成员)。作者面 `ext/web` ABI 名保持兼容。
## v0.3.9 — 2026-09-09
### Highlights
**业务联调缺口 GAP-06–10**:解析器不再吞掉嵌套反引号/`text=[…]` 后的函数体;`invoke` 的 `Null` 不再伪装成功;`sys.exec capture=` 可取 stdout;流式 proxy 反缓冲头。
```bash
git checkout v0.3.9
```
### Added
- **`sys.exec` / `系统.执行`**:可选 `capture=` / `捕获=`;为真时返回 `{code, stdout, stderr}`(GAP-09)。
### Fixed
- **GAP-06/07**:`*…*` 分类对反引号/字符串内的 `*` 不再误判;错误收尾的赋值行不再吞掉后续 `##` 体(`>` / 合法 `*…*` 可脱出注释段);命名参数边界尊重 `[…]`/`{…}`。
- **GAP-08**:`app.invoke` 对 `Null`/`None` 返回不再伪装成 `{"ok":true}`,改为 500 + `{"ok":false,"error":"null result"}`。
- **GAP-10**:`app.proxy` `stream=true` 响应补齐 `Cache-Control: no-cache, no-transform` 与 `X-Accel-Buffering: no`。
### Changed
## v0.3.8 — 2026-09-09
### Highlights
**中层标准库 Mid2(M7–M10)收口**:日历/时区、URL、TOML、HTML 转义、base32、实用 fs、薄统计与日志字段——日常脚本与工具配置不再依赖外联或插件。另修复嵌套插件调用后 `GLOBAL_HOST` 被清空导致 `invoke` 失败。
```bash
git checkout v0.3.8
# 或下载 Release 的 exe / zip
marqdo run public/features/14-datetime-url.mq.md
marqdo run public/features/17-stats-log.mq.md
```
### Added
- **中层标准库 Mid2 M10**:`lib/stats` / `统计`(mean/median/stdev)与 `log`/`日志` 可选 `fields=`;金样与 public `17-stats-log`。**Mid2 M7–M10 收口**(zip 跳过)。设计 [stdlib-stats-log.md](doc/design/stdlib-stats-log.md)。
- **中层标准库 Mid2 M9**:`fs.make_dirs` / `remove_tree` / `stat` / `walk`(中英);金样与 public `16-fs-mid2`。设计 [stdlib-fs-mid2.md](doc/design/stdlib-fs-mid2.md)。
- **中层标准库 Mid2 M8**:`lib/toml` / `配置表`(只读子集)、`lib/html` / `超文本`(escape/unescape)、`encoding` base32;金样与 public `15-toml-html-encoding`。设计 [stdlib-toml.md](doc/design/stdlib-toml.md) · [stdlib-html.md](doc/design/stdlib-html.md)。
- **中层标准库 Mid2 M7**:`lib/datetime` / `日期时间`(`{unix,zone,iso}` · parse/format/add/in_zone)与 `lib/url` / `地址`(parse · query_parse/stringify);金样与 public `14-datetime-url`。设计 [stdlib-datetime.md](doc/design/stdlib-datetime.md) · [stdlib-url.md](doc/design/stdlib-url.md)。
- **文档**:中层标准库 Mid 之后缺口盘点与 Mid2(M7–M10)设计/路线——[stdlib-gaps-after-mid.md](doc/research/stdlib-gaps-after-mid.md) · [stdlib-mid2.md](doc/design/stdlib-mid2.md) · [stdlib-mid2.md](doc/roadmap/stdlib-mid2.md)。
### Fixed
- **`host_query` / GLOBAL_HOST**:嵌套 `call_registered` 结束后恢复外层宿主指针,不再清空;`web_listen` 多轮 `invoke`(中间再调插件)不再报 `no active host context`。
### Changed
## v0.3.7 — 2026-09-07
### Highlights
**宿主集成 H1–H4**:浏览器同域 SSE/HTTP 流式中继(`app.proxy`)、HTTP→用户 `##`(`app.invoke`)、跨模块 db 方法分发、`corpus_search` 可发现、MCP Server stdio——下游可去掉 Python 旁路。
```bash
git checkout v0.3.7
# 或下载 Release 的 exe / zip
marqdo ext add web && marqdo ext add agent
# *app*.proxy / *app*.invoke · agent.mcp_server
```
### Added
- **宿主集成 H1–H4**:`ext/web` `app.proxy`(同域 SSE/HTTP 流式中继)与 `app.invoke`(HTTP→`lib.member`);跨模块 `#` 对象方法查找;`agent.corpus_search` 自动加载插件;`agent.mcp_server` stdio。金样 `web-proxy-invoke-smoke` · `web-hosting-live` · `web-db-cross-module-smoke` · `agent-mcp-server-smoke`。设计 [ext-hosting-fill.md](doc/design/ext-hosting-fill.md) · [ext-hosting.md](doc/roadmap/ext-hosting.md)。
- **文档**:宿主集成缺口盘点——[ext-hosting-gaps.md](doc/research/ext-hosting-gaps.md)。
### Fixed
- **方法分发**:`find_object_type` 沿导入树传递查找,跨模块拿到的 `web.db` 等句柄可再调方法。
### Changed
## v0.3.6 — 2026-09-07
### Highlights
**中层标准库 Mid M1–M6 收口**:通用原语沉入 `lib/`(正则、编解码、路径、哈希、机密、CSV、加厚文本/集合、CLI、日志、UUID),写日常脚本与多数扩展库不再需要原生插件。另含 `ext/linalg` 公式文档面与 agent/llm 稳健性修复。
```bash
git checkout v0.3.6
# 或下载 Release 的 exe / zip
marqdo run public/features/13-log-uuid.mq.md
marqdo ext add linalg # 可选:公式文档 / 线性代数
```
### Added
- **中层标准库 M6**:`lib/log` / `日志`(级别过滤的一行日志)与 `lib/uuid` / `标识`(v4);金样与 public `13-log-uuid`。设计 [stdlib-log-uuid.md](doc/design/stdlib-log-uuid.md)。**Mid M1–M6 收口。**
- **中层标准库 M5**:`table`/`表` 加厚(sort/sort_by/unique/chunk/zip/flatten)与 `lib/cli`/`命令行`(parse);金样与 public `12-list-cli`。设计 [stdlib-list-cli.md](doc/design/stdlib-list-cli.md)。
- **中层标准库 M4**:`lib/csv` / `逗号表`(parse/stringify)与 `lib/text` / `文本` 加厚(contains/replace/case/pad/…);金样与 public `11-csv-text`。设计 [stdlib-csv.md](doc/design/stdlib-csv.md) · [stdlib-text-mid.md](doc/design/stdlib-text-mid.md)。
- **中层标准库 M3**:`lib/hash` / `哈希`(sha256/sha1/md5/hmac_sha256)与 `lib/secrets` / `机密`(token_hex/token_urlsafe);金样与 public `10-hash-secrets`。设计 [stdlib-hash.md](doc/design/stdlib-hash.md) · [stdlib-secrets.md](doc/design/stdlib-secrets.md)。
- **中层标准库 M2**:`lib/path` / `lib/路径`(join/split/normalize/…)与 `fs`/`文件` 加厚(`copy_file`/`move`/`make_temp`);金样与 public `09-path-fs`。设计 [stdlib-path.md](doc/design/stdlib-path.md) · [stdlib-fs-mid.md](doc/design/stdlib-fs-mid.md)。
- **中层标准库 M1**:`lib/re` / `lib/正则`(`is_match`/`find`/`find_all`/`replace`/`split`)与 `lib/encoding` / `lib/编码`(base64/hex);host `host_re_*` + `host_encoding_*`;金样与 public `08-re-encoding`。设计 [stdlib-mid.md](doc/design/stdlib-mid.md) · [stdlib-re.md](doc/design/stdlib-re.md) · [stdlib-encoding.md](doc/design/stdlib-encoding.md)。
- **`ext/linalg`**:L0–L6 + 公式文档面 **F1–F3**(中缀、`declare`、展示/`explicit` 默认化简、`T_ascii`、public「如何写公式文档」);示例 `linalg-transpose` · `linalg-svd` · `linalg-least-squares`。设计:[ext-linalg-formula-doc.md](doc/design/ext-linalg-formula-doc.md)。
### Fixed
- **`ext/agent`**:写回改走 `wb.record`(避免 `writeback` 形参遮蔽模块名),不再直调 `host_*`。
- **`ext/llm`**:`stream_result` 忽略未知 SSE 类型(如 `reasoning`),不再因此退出。
### Changed
## v0.3.5 — 2026-09-04
### Highlights
**`marqdo ext add` 无需本机 Rust**:Release 发布预编译 native 插件;CLI 可自动下载 L1(`*-ext.zip`)与 `*-native-*.zip`。Windows 便携包内含 `ext/native/*.dll`。
```bash
git checkout v0.3.5
# 或下载 Release 的 exe / zip
marqdo ext add web
marqdo ext add agent
marqdo ext add quantum
```
### Added
- **预编译原生插件资产**:`marqdo-*-native-x86_64-pc-windows-msvc.zip`、`marqdo-*-native-x86_64-unknown-linux-gnu.zip`;Windows zip 捆绑 `ext/` + native DLL。
- **`ext add` 下载回退**:本地无 `target/` 时从 GitHub Release 拉取;`MARQDO_EXT_NO_DOWNLOAD=1` / `MARQDO_EXT_VERSION` 可配置。
### Changed
- 文档:[ext-cli.md](doc/design/ext-cli.md)、[08-ext-deploy-coupling](doc/design/ext-web-customization/08-ext-deploy-coupling.md)、README 安装步骤以预编译为默认路径。
- Release workflow:Windows 编插件并上传 native zip;新增 Linux native job。
## v0.3.4 — 2026-09-04
### Highlights
**`ext/web` 定制波次 C0–C4 收口**:可配置 admin 前缀与登录回跳、段边界 gates、shell/layout、样式单元格 strict、脚本 defer/version/`asset_version`、条件导航 when/media。附智能体 Wave B0 示例与写回遮蔽修复。
```bash
git checkout v0.3.4
cargo build --release
cargo build --release -p marqdo_plugin_web
marqdo ext add web
# golds: tests/ext/web-c0-admin-prefix … web-c4-nav-when
```
### Added
- **智能体 Wave B0**:宪法优先示例 [agent-pong](examples/agent-pong/)(call_site/源码注入)· [agent-okf-flywheel](examples/agent-okf-flywheel/)(OKF `cache=hit`);调研 [agent-framework-2026-09.md](doc/research/agent-framework-2026-09.md);离线 harness [`scripts/agent-harness.sh`](scripts/agent-harness.sh);金样 `agent-constitution-b0`。
- **`.env.example`**:开发期 OpenAI 兼容网关变量模板(密钥仅本地 `.env`)。
### Fixed
- **`agent.step` / `plan` 写回**:参数名 `writeback` 遮蔽 `lib/writeback` import,导致 `writeback=True` 时 `method receiver must be an object map`;改为 `host_writeback_record`。金样 `agent-writeback-shadow`。
- **`ext/web` C0**:`admin=False` 不再挂载/保留 `/admin*`;可配 `admin_prefix` / `login_redirect` / `logout_redirect`;金样 `web-c0-admin-prefix`。
- **`ext/web` C1**:门禁段边界匹配(不再误伤 `/admin-publish`);`gate` 支持 `match` / `on_deny` / `exclude`;`auth` 默认 `on_deny=redirect` + `login_path`;金样 `web-c1-gates`。
- **`ext/web` C2**:`shell_css=full|minimal|off`;`layout=sidebar|stacked|bare|rail`;full 壳含小屏单列 media;金样 `web-c2-shell-layout`。
- **`ext/web` C3**:样式装配对数字/布尔值单元格告警,`strict`/`strict_css_cells` 硬错误;`page.css` 作 raw CSS;head 表支持 `defer`/`async`/`version`,`asset_version` 统一 `?v=`;金样 `web-c3-style-head`。
- **`ext/web` C4**:导航表 `当`/`when`(`auth`/`guest`/`hide`)与 `媒体`/`media`(响应式显隐);listen 注入 `_logged_in`;金样 `web-c4-nav-when`。
### Changed
- `build_step_context`:call site 提前到 task 之后;开场白强调 code-as-documentation。
- 中文 `构建单步上下文` 委托英文版(含预算 / READ);新增 `dump_step_context`;live 用例改用仓库根 `.env`。
- 文档:[ext-web 定制限制](doc/research/ext-web-customization-limits.md) + [解决设计 C0–C4](doc/design/ext-web-customization/)。
## v0.3.3 — 2026-09-04
### Highlights
**浏览器作者零业务 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
Generated
+61 -1115
View File
File diff suppressed because it is too large. Load diff
+14 -3
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "0.3.2"
version = "0.4.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -17,7 +17,7 @@ default = ["native"]
native = ["cli", "view", "net-host", "plugin-host", "exec-host", "fs-host", "tty"]
cli = ["dep:clap"]
view = ["dep:tiny_http"]
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize"]
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize", "dep:zip"]
plugin-host = ["dep:libloading"]
exec-host = []
fs-host = []
@@ -32,10 +32,19 @@ pulldown-cmark = "0.12"
serde_json = "1"
thiserror = "1"
tiny_http = { version = "0.12", optional = true }
sha2 = { version = "=0.10.9", default-features = false }
sha1 = { version = "=0.10.6", default-features = false }
md-5 = { version = "=0.10.6", default-features = false }
hmac = { version = "=0.12.1", default-features = false }
getrandom = { version = "=0.2.17", default-features = false, features = ["std"] }
# Mid M1: Unicode regex for lib/re (no backrefs; RE2-like).
regex = { version = "=1.13.1", default-features = false, features = ["std", "unicode"] }
# Pin for Cargo/rustc 1.81 (newer rustls/idna/zeroize need edition2024).
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"], optional = true }
idna_adapter = { version = "=1.1.0", optional = true }
zeroize = { version = "=1.8.1", optional = true }
# Extract GitHub Release ext/native zips (`marqdo ext add` without local Rust).
zip = { version = "=0.6.6", default-features = false, features = ["deflate"], optional = true }
libloading = { version = "=0.8.6", optional = true }
include_dir = "0.7"
libc = { version = "0.2", optional = true }
@@ -48,10 +57,12 @@ chrono = { version = "0.4", default-features = false, features = ["alloc", "std"
members = [
"plugins/demo",
"plugins/agent",
"plugins/web",
"plugins/quantum",
"plugins/linalg",
"crates/marqdo-wasm",
]
# Official web plugin is Go (`plugins/web/`); Rust sources kept as
# `plugins/web-rust-archive/` for reference (not a workspace member).
resolver = "2"
[dev-dependencies]
+18 -13
View File
@@ -99,7 +99,7 @@ marqdo catalog public -o .marqdo
---
## 现状(v0.3.2)
## 现状(v0.4.0)
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
@@ -107,25 +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));原生层默认 **Go `libweb`**([ADR 0004](doc/adr/0004-web-plugin-go.md),`scripts/build-web-plugin.sh`);示例 [marqdo-blog](examples/marqdo-blog/) · [anlian-mq](examples/anlian-mq/);生产路径见 [web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)
- **`quantum`**:Q0–Q7 + Q8a/b 主题 SVG;示例 [quantum-entanglement](examples/quantum-entanglement/)
- **`agent`**:A1–A4(OKF 复用、过程事件、上下文预算、RAG/MCP fixture);下一波缺口 [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
- **`linalg`**:L0–L6 + 公式文档面(中缀 / `declare` / 展示化简);示例 [linalg-transpose](examples/linalg-transpose/) · [linalg-svd](examples/linalg-svd/) · [linalg-least-squares](examples/linalg-least-squares/)
- **`agent`**:A1–A4 + **MCP Server stdio**(`mcp_server`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
- **`llm`**:OpenAI 兼容对话
- 安装:`marqdo ext list` / `add …` / `remove`([ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum}`
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum,linalg}`(`web` 为 Go;其余为 Rust)
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge;示例 [browser-hello](examples/browser-hello/);站点挂载 `web.client_embed` / `网页.客户端挂载`([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [ADR 0003](doc/adr/0003-browser-async-effects.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.2)
### 如何使用最新 Marqdo(v0.4.0)
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v0.3.2 # 或留在 main
git checkout v0.4.0 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -138,15 +139,19 @@ marqdo view public --no-open
marqdo debug public --no-open
marqdo catalog public -o .marqdo
# 3) 安装官方扩展(需先编原生插件)
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
marqdo ext add web # 或:网页
# 3) 安装官方扩展(Release 用户:无需本机 Rust/Go)
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native(Go libweb)
marqdo ext add agent # 或:智能体
marqdo ext add quantum # 或:量子
marqdo ext add llm # 或:大模型
marqdo ext add linalg # 或:线性代数
marqdo ext add llm # 或:大模型(纯 .mq.md)
# 开发者:cargo build --release -p marqdo_plugin_{agent,quantum,linalg}
# bash ./scripts/build-web-plugin.sh # 需 Go + cgo → libweb
# 离线:解压 Windows zip(已含 ext/native)或手动放下 native zip;MARQDO_EXT_NO_DOWNLOAD=1
# 4) 动态站示例(扩展装好后)
marqdo run examples/marqdo-blog/index.mq.md
marqdo run examples/anlian-mq/index.mq.md # W-G14 验收站
# 浏览器打开终端打印的 listen 地址;/favicon.ico 与 logo 装配见 W8
# 5) 浏览器 WASM(可选)
@@ -154,7 +159,7 @@ marqdo wasm build
# → dist/wasm/ … 见 examples/browser-hello/
# 6) Windows:也可从 GitHub Releases 下载 exe / zip / vsix
# https://github.com/cflmy/marqdo/releases/tag/v0.3.2
# https://github.com/cflmy/marqdo/releases/tag/v0.4.0
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo-wasm"
version = "0.3.2"
version = "0.4.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
File diff suppressed because it is too large. Load diff
+26 -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,10 @@
| [design/ext-agent-plan.md](design/ext-agent-plan.md) | **`## 多步` / `## plan` 锁定设计**(工作簿文件、subtask 执行、修订循环、`step` 默认写回) |
| [design/ext-cli.md](design/ext-cli.md) | **`marqdo ext list/add/remove` 官方扩展安装器** |
| [design/ext-web.md](design/ext-web.md) | **官方扩展 `ext/web`(页面/库表/绑定/后台;ABI + CLI;设计锁定)** |
| [design/ext-web-go-rewrite.md](design/ext-web-go-rewrite.md) | **`plugins/web` Go 全量重写**(多语言 ABI · 网页制备完备 · anlian 验收) |
| [adr/0004-web-plugin-go.md](adr/0004-web-plugin-go.md) | **Accepted:web 原生插件实现语言为 Go** |
| [research/ext-web-customization-limits.md](research/ext-web-customization-limits.md) | **`ext/web` 定制限制踩坑盘点**(路由/壳 CSS/鉴权/样式/部署) |
| [design/ext-web-customization/](design/ext-web-customization/) | **对应解决设计**(C0–C4:前缀可让出、shell_css、gate、布局…) |
| [design/web-assets-and-images.md](design/web-assets-and-images.md) | **W8:favicon / Head 资源表 / 图片装配**(一次补齐) |
| [design/web-asgi-servers-and-marqdo.md](design/web-asgi-servers-and-marqdo.md) | **Daphne/Uvicorn 等 vs Marqdo**:不能直接托管;反代 + axum `listen` |
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
@@ -59,12 +74,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/)。
+28
View File
@@ -0,0 +1,28 @@
# ADR 0004:网络拓展库原生实现改为 Go
| | |
|---|---|
| Status | **Accepted** |
| Date | 2026-09-10 |
| Related | [ext-web-go-rewrite.md](../design/ext-web-go-rewrite.md) · [ext-abi.md](../design/ext-abi.md) · [0001-implementation-language.md](0001-implementation-language.md) |
## Context
- Marqdo **宿主/解释器**仍为 Rust(ADR 0001 不变)。
- 官方插件契约是稳定 **C ABI**(`include/marqdo_abi.h`),不绑定 Rust ABI。
- `plugins/web`(Rust/axum)已具备 W0–W8 等能力,但迭代成本高;且需验证多语言插件生态。
- 产品目标:网络拓展库支撑完整网页制备,并以暗恋见君(外接 PostgreSQL + Redis)验收;应用层前后端均为 Marqdo 脚本。
## Decision
1. **重写** `plugins/web` 为 **Go** 共享库(`-buildmode=c-shared`),产物名仍为 `libweb.so` / `web.dll` / `libweb.dylib`。
2. **ABI 全量兼容**(函数名、参数、语义);`ext/web` 作者面默认不动。
3. 施工图:[ext-web-go-rewrite.md](../design/ext-web-go-rewrite.md)。禁止在旧 Rust 插件上继续打补丁演进(ext-web C5)。
4. 其它官方插件(agent / quantum / linalg)**暂不**强制改语言;Go web 作为多语言样板。
## Consequences
- 构建与发版需安装 Go;CI/`marqdo ext add web` 增加 `go build` 回退。
- 根 Cargo workspace 不再包含 `plugins/web` Rust crate(切换完成后)。
- cgo/共享库生命周期与 `shutdown` 需严格测试。
- 金样例 `tests/ext/web-*` 为门禁。
+87
View File
@@ -299,6 +299,93 @@ marqdo wasm build -o static # marqdo_wasm.wasm + marqdo-bridge.js
---
## 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. 决策摘要
| 问题 | 答案 |
+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` |
#### 强烈建议
+1 -1
View File
@@ -85,7 +85,7 @@ cargo build -p marqdo_plugin_agent
- Demo (ABI v1): `demo_add`, `demo_echo` — [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md).
- Agent (ABI v2): … **OKF agent-kb** …
- Web (ABI v2): HTTP listen + SQLite + page render (`web_listen`, `web_render`, `web_db_*`) — [`plugins/web`](../../plugins/web); used by [`ext/web/web.mq.md`](../../ext/web/web.mq.md). Lookup: `plugin.native_path name=web` / `MARQDO_WEB_PLUGIN` / `marqdo ext add web`.
- Web (ABI v2): HTTP listen + SQLite/Postgres + page render (`web_listen`, `web_render`, `web_db_*`, …) — [`plugins/web`](../../plugins/web)(**Go 全量重写**,见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md) · [ADR 0004](../adr/0004-web-plugin-go.md));作者面 [`ext/web/web.mq.md`](../../ext/web/web.mq.md)。Lookup: `plugin.native_path name=web` / `MARQDO_WEB_PLUGIN` / `marqdo ext add web`.
## Layering
+66 -33
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,57 +23,90 @@ marqdo ext remove agent
Imports use paths like `import llm:ext/ai/llm.mq.md` (see [`load.rs`](../../src/load.rs)).
## Source for `add`
## Goal: no local Rust required
End users who install Marqdo from **GitHub Releases** should run:
```bash
marqdo ext add web
```
and get both L1 `.mq.md` **and** the matching native plugin (`.dll` / `.so`) **without** `cargo build`.
### Resolution order (`add` with native crate)
1. Local artifact (`MARQDO_*_PLUGIN`, `plugins/web/build` for **web**, `target/{debug,release}`, beside `marqdo`, `MARQDO_EXT_SOURCE/native`, …)
2. **Download** `marqdo-{VER}-native-{target}.zip` from the GitHub Release for this CLI version → cache under `~/.marqdo/cache/`
3. Local rebuild fallback:
- **web** → `./scripts/build-web-plugin.sh` (Go c-shared `libweb`; requires Go 1.22+ / cgo)
- other plugins → `cargo build -p marqdo_plugin_*` when Rust/`cargo` is available
4. Else fail with a clear message pointing at the Release assets
L1 sources:
1. `MARQDO_EXT_SOURCE` / repo `./ext` / beside binary
2. Else download `marqdo-{VER}-ext.zip` into `~/.marqdo/cache/ext-src-v{VER}/`
### Env knobs
| Variable | Meaning |
|----------|---------|
| `MARQDO_EXT_VERSION` | Override SemVer used for Release asset names (default: CLI `CARGO_PKG_VERSION`) |
| `MARQDO_EXT_NO_DOWNLOAD=1` | Never hit the network (CI / air-gap); local/cargo only |
| `MARQDO_WEB_PLUGIN` / `MARQDO_AGENT_PLUGIN` / `MARQDO_QUANTUM_PLUGIN` | Explicit native path |
Windows Release **zip** also ships `ext/` + `ext/native/*.dll` next to `marqdo.exe` so a portable unzip works offline after one download.
## Source for `add` (developers)
1. `MARQDO_EXT_SOURCE` — directory containing `ai/llm.mq.md` …
2. Else repo `./ext` near cwd / binary
2. Else repo `./ext` near cwd / binary
3. Else Release `marqdo-*-ext.zip` (see above)
## Layout (`ext/`)
Official extensions live under **`ext/ai/`** (LLM + agent framework only). Do not add flat `.mq.md` files at `ext/` root — keeps the tree from accumulating unrelated modules.
```text
ext/
ai/
llm.mq.md
大模型.mq.md
agent.mq.md
智能体.mq.md
ai/ # llm + agent L1
web/
quantum/
```
Future optional ext domains get their own subdirs (e.g. `ext/web/`, `ext/quantum/`), not mixed into `ai/`.
Installed tree (`~/.marqdo/ext` or `MARQDO_EXT`):
```text
web/web.mq.md
web/网页.mq.md
native/libweb.so # or web.dll / libweb.dylib
web.plugin # absolute path hint
```
## Catalog
| Id | Installs under `MARQDO_EXT` |
|----|-----------------------------|
| `llm` | `ai/llm.mq.md`, `ai/大模型.mq.md` |
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **`native/libagent.so`** (or `.dylib`) |
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **`native/libweb.so`** — 见 [ext-web.md](ext-web.md) · [roadmap](../roadmap/ext-web.md) |
| `quantum` | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **`native/libquantum.so`** — 见 [ext-quantum.md](ext-quantum.md) · [roadmap](../roadmap/ext-quantum.md) |
| `agent` | `ai/agent.mq.md`, `ai/智能体.mq.md`, **native `agent`** |
| `web` | `web/web.mq.md`, `web/网页.mq.md`, **native `web`** |
| `quantum` | `quantum/quantum.mq.md`, `quantum/量子.mq.md`, **native `quantum`** |
`add agent` / `add web` / `add quantum` **先定位原生插件**,再复制 `.mq.md`:
## Release assets (native)
1. 在 `CARGO_TARGET_DIR`、`target/{debug,release}`、源码 `ext` 旁的 `target/`、可执行文件旁等路径查找 `lib{name}.so`(或 `.dll` / `.dylib`)
2. 找不到则自动执行 `cargo build -p marqdo_plugin_{name}`,再安装到 `MARQDO_EXT/native/`
3. 写入 `{name}.plugin` 绝对路径提示,供 `plugin.native_path` 解析
| Asset | Platform |
|-------|----------|
| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Windows x64 (`native/*.dll`) |
| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Linux x64 (`native/lib*.so`) |
这样不会出现「只装了 `.mq.md`、运行时报 native plugin not found」的半安装状态。
```bash
# 推荐:在仓库根目录
marqdo ext add web
# 等价于找到或编好 libweb.so 后拷入 ~/.marqdo/ext/native/
```
Without a prior install, runtime still resolves via `plugin.native_path name=web` (see [ext-abi.md](ext-abi.md)): `MARQDO_WEB_PLUGIN` → `CARGO_TARGET_DIR/{debug,release}/` → cwd `target/…` → beside `marqdo` binary → `MARQDO_EXT/native/`.
macOS: use local `cargo build` until CI adds Darwin natives (same zip naming pattern reserved).
## Tests
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` ([`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md); needs `tests/ext/.env` + built `libagent`).
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_cli_add_web` (local build path; set `MARQDO_EXT_NO_DOWNLOAD=1` in sandboxes if needed).
Unit: `ext_fetch` URL / triple tests.
## Non-goals
- Third-party registry
- Merging into `lib/`
- Bundling domain/task helpers in official ext
- Merging domain helpers into `lib/`
- Guaranteeing plugin **source** ABI stability (author `.mq.md` API is the contract)
+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 登录)。
+454
View File
@@ -0,0 +1,454 @@
# `plugins/web` Go 全量重写(多语言 ABI 生态 · 网页制备完备)
| | |
|---|---|
| 状态 | **Completed(W-G0…W-G14 · v0.4.0)** |
| 日期 | 2026-09-10 |
| 相关 | [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) · [web-net-capabilities.md](web-net-capabilities.md) · [ext-web-drivers.md](ext-web-drivers.md) · [web-assets-and-images.md](web-assets-and-images.md) · [ext-hosting-fill.md](ext-hosting-fill.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [web-asgi-servers-and-marqdo.md](web-asgi-servers-and-marqdo.md) |
| 实现目录 | `plugins/web/`(**Go module**;产物仍为 `libweb.so` / `web.dll` / `libweb.dylib`) |
| 作者面 | `ext/web/web.mq.md` · `ext/web/网页.mq.md`(**ABI 名与方法面保持兼容**;非另起一套 API) |
| 验收应用 | 工作区 `anlian`(暗恋见君):用 Marqdo 前后端脚本完整重写;**PostgreSQL + Redis 外接** |
---
## 0. 一句话
用 **Go** 重写官方网络拓展库原生层(`plugins/web`),在 **C ABI v2 全量兼容** 前提下提供「网页制备」所需的全部服务端能力;`ext/web` 继续用 GFM 表 + `#` 类做作者面;应用(含暗恋见君)的前后端脚本全部用 Marqdo 书写。此举同时验证 **多语言 ABI 插件生态**(首个非 Rust 官方插件)。
**不是**最小 hello 插件;**不是**在旧 Rust 代码上打补丁(对齐 [ext-web.md](ext-web.md) **C5**)。
---
## 1. 动机与目标
### 1.1 为何重写
| 动机 | 说明 |
|------|------|
| 开发/编译节奏 | Rust 插件迭代慢,网络域能力长期「半成品感」来自堆叠依赖与慢反馈,而非语言绝对性能 |
| 多语言生态 | ABI 已是稳定 C 契约;需要第一个 **Go** 官方插件证明「宿主 Rust ≠ 插件必须 Rust」 |
| 网页制备完备 | 目标是支持 **完整动态站点制备**(装配、CRUD、鉴权、实时、上传、SEO、代理、驱动…),并以真实论坛项目验收 |
| 性能与拉起 | Go `net/http` 生态成熟、单二进制友好;论坛级 IO 密集负载下足够「极致可用」 |
### 1.2 成功标准(全部满足才算完成)
1. **ABI 全量对等**:下文 §5 列出的每一个已注册 `web_*` 符号,参数 CSV、JSON 形、语义与现网 gold 一致(中英参数别名保留)。
2. **作者面可用**:现有 `ext/web` 示例与 `tests/ext/web-*`(含 live-server)在换 Go `.so` 后通过;无需作者改业务脚本(除非文档标明的 **G 增强**)。
3. **网页制备完备**:单站点可完成页面装配、样式/头/图、库表、表单、路由、中间件、鉴权/RBAC、上传下载、SEO/RSS/sitemap、WS、缓存、对象存储、反代、invoke——即 W0–W8 + P3 + C0–C4 + H1/H2 能力面。
4. **驱动外接**:`postgres://`、`redis://`、`s3://` 为正式一等能力(与 [ext-web-drivers.md](ext-web-drivers.md) 一致);SQLite / memory / file 仍支持本地与测试。
5. **暗恋见君可写完**:用 Marqdo 后端脚本 + 浏览器 WASM 前端脚本重写 anlian 核心模块(见 §8);运行时仅依赖 `marqdo` + `libweb` + **外接 PostgreSQL + Redis**(可选 S3/RustFS)。
6. **安装路径不变**:`marqdo ext add web`、`plugin.native_path name=web`、`MARQDO_WEB_PLUGIN`、产物文件名 `libweb.so` 等与 [ext-cli.md](ext-cli.md) 兼容。
### 1.3 非目标
| 非目标 | 说明 |
|--------|------|
| 改 Marqdo 核心语法 | 仍遵守 ext-web **C1** |
| 把服务器搬进浏览器 WASM | 仍遵守 ADR 0002 |
| 进程内 TLS | HTTPS 由反代;`cookie_secure` 保留 |
| 第三方插件市场 | 仍无 registry |
| 把论坛业务写进 Go 插件 | 帖子/新闻/聊天室规则在 `.mq.md`;插件只提供原语 |
| 强制嵌入式替代 PG/Redis | 本项目明确 **允许并依赖外接** PG/Redis |
---
## 2. 分层架构(锁定)
```text
┌──────────────────────────────────────────────────────────────────┐
│ 应用(anlian / 任意站点) │
│ · 后端 .mq.md:路由、业务、装配、invoke 处理函数 │
│ · 前端 .mq.md:WASM + lib/browser(作者零业务 JS) │
└────────────────────────────┬─────────────────────────────────────┘
│ import web / 网页
┌────────────────────────────▼─────────────────────────────────────┐
│ ext/web(L1 · Marqdo) │
│ # page # db # app # form # auth # cache # storage # media # ws │
│ make_style / make_head / make_images / client_embed … │
└────────────────────────────┬─────────────────────────────────────┘
│ lib/plugin → dlopen
┌────────────────────────────▼─────────────────────────────────────┐
│ plugins/web(L0 · Go · C ABI v2) ← 本文件重写对象 │
│ net/http + 驱动适配 + HTML 装配 + WS hub + 中间件 … │
└──────────┬─────────────────┬─────────────────┬───────────────────┘
│ │ │
PostgreSQL Redis S3/MinIO/RustFS
(外接) (外接) (可选外接)
```
| 层 | 语言 | 职责 |
|----|------|------|
| 应用脚本 | Marqdo | 前后端业务、页面表、领域模型 |
| `ext/web` | Marqdo | 双语作者 API;禁止直接 `host_*` |
| `plugins/web` | **Go** | 全部 `web_*` ABI;高性能网络与驱动 |
| `lib/net` | Marqdo + Rust host | **仅**客户端 HTTP / cookie / multipart / markdown **解析**;不进本重写范围(边界不变) |
| 宿主 | Rust | `dlopen`、JSON Value、`host_query`(`entry_dir` / `call_lib_path` …) |
---
## 3. 硬约束(继承 + 本重写追加)
### 3.1 继承 ext-web C1–C7
| ID | 约束 |
|----|------|
| C1 | 不为 web 改核心语法 |
| C2 | 作者面禁止 json 袋胶水拼装页面 |
| C3 | 中英 API 分文件;禁止混排 |
| C4 | 首页 `index.mq.md`;组件可拆 |
| C5 | **禁止在旧 Rust 插件上打补丁演进**;清空/替换后用 Go 重写 |
| C6 | `# db` 完整 CRUD;`select`/`查询`;admin 与表单共用写库 API |
| C7 | 表单字段+规则;**写库前服务端校验** |
### 3.2 本重写追加(G 系列)
| ID | 约束 |
|----|------|
| **G1** | 产物仍为 C ABI v2;`MARQDO_ABI_VERSION = 2`;导出符号名与 [include/marqdo_abi.h](../../include/marqdo_abi.h) 一致 |
| **G2** | **ABI 函数名与参数名向后兼容**:§5 清单中每个 `web_*` 必须注册;参数 CSV 与现 Rust 插件一致(含中文别名) |
| **G3** | Go 使用 `-buildmode=c-shared`;**禁止**把 Go runtime 假设成唯一线程——跨 FFI 调用必须可重入或明确串行化文档 |
| **G4** | `marqdo_plugin_shutdown` 必须停止 HTTP/WS、关闭 DB/Redis 连接、释放 hub |
| **G5** | 字符串跨界:成功时 `*out_json` / 失败时 `*err_msg` 必须用 **host `alloc`** 分配(与现插件相同),由宿主 `free` |
| **G6** | 相对路径(sqlite 文件、静态目录、上传根)一律相对 `host_query("entry_dir")` |
| **G7** | 多语言样板:仓库内保留可复用的 Go ABI 脚手架注释/包结构,供后续其它语言插件参考 |
| **G8** | 金样例不过 = 未完成;切换默认 `libweb` 到 Go 后,既有 `tests/ext/web-*` 必须绿 |
---
## 4. 技术选型(Go)
| 能力 | 选型 | 备注 |
|------|------|------|
| HTTP 服务器 | 标准库 `net/http` | 路由可用轻量自研 mux 或 `chi`/`http.ServeMux`(Go 1.22+ 模式) |
| 中间件 | 自研链式 `func(http.Handler) http.Handler` | 对等 CORS / 安全头 / gzip / body limit / access_log / cache-control |
| WebSocket | `gorilla/websocket` 或 `coder/websocket` | 对等 echo / broadcast / drain;**G 增强**:命名房间(§7) |
| SQLite | `modernc.org/sqlite`(纯 Go)或 `mattn/go-sqlite3`(cgo) | 优先纯 Go 以便交叉编译;FTS5/migrate 行为对齐 |
| PostgreSQL | `jackc/pgx/v5` | `postgres://` / `postgresql://` |
| Redis | `redis/go-redis/v9` | `# cache`;**G 增强**:可选 session/WS 后端 |
| S3 | `aws-sdk-go-v2` 或 MinIO SDK | `s3://`;兼容 RustFS |
| 密码 | `golang.org/x/crypto/argon2` | argon2id 参数对齐现实现 |
| Markdown | `goldmark`(GFM 扩展) | 对等 `pulldown-cmark` 用途(正文 HTML) |
| JSON | `encoding/json` | ABI 边界 |
| 构建 | `go build -buildmode=c-shared -o libweb.so` | 见 §9 |
**不引入**完整 Web 框架(Gin/Echo 业务层)以免作者面旁路;框架能力用 Marqdo `# app` 表达。
---
## 5. ABI 全量清单(必须注册 · 兼容)
> 参数列为注册时 `params` CSV(英;实现须同时接受设计中已有的中文键别名,与现 `lib.rs` 一致)。
> 状态列:`P0` = 首波必须与 gold 对齐;实现顺序见 §10。
### 5.1 Page / compose / assets / render
| ABI | params(摘要) | 域 |
|-----|----------------|-----|
| `web_page_new` | (空或 title 等,对齐现实现) | page |
| `web_compose_components` | page, components, … | compose |
| `web_compose_main` | page, main, … | compose |
| `web_page_query` | page, query | page |
| `web_page_order` | page, order | page |
| `web_page_link_prefix` | page, prefix | page |
| `web_page_css` | page, css | page |
| `web_page_detail` | page, … | page |
| `web_page_meta` | page, meta | SEO |
| `web_page_head` | page, head | W8 |
| `web_page_images` | page, images | W8 |
| `web_page_paginate` | page, … | content |
| `web_head` | table / … | W8 |
| `web_images` | table / … | W8 |
| `web_app_icons` | app, icons | W8 |
| `web_style` | table, strict? | CSS |
| `web_compose_form` | page, form, target? | form embed |
| `web_render` | page | HTML |
### 5.2 SEO / ops routes
| ABI | 域 |
|-----|-----|
| `web_rss_build` | RSS |
| `web_app_route_rss` | app |
| `web_app_redirect` | app |
| `web_app_error_page` | app |
| `web_app_sitemap` | app |
| `web_app_robots` | app |
| `web_sitemap_build` | sitemap |
### 5.3 Upload / media
| ABI | 域 |
|-----|-----|
| `web_app_upload` | app |
| `web_app_download` | app |
| `web_upload_validate` | media |
| `web_upload_save` | media |
| `web_media_new` | media |
| `web_app_gallery` | app |
### 5.4 Database
| ABI | 备注 |
|-----|------|
| `web_db_new` | `sqlite:` / `postgres://` |
| `web_db_init` | unique / index / fk / 审计时间戳 |
| `web_db_insert` / `select` / `get` / `update` / `delete` / `exec` | CRUD |
| `web_db_query` / `count` | 原生 / 计数 |
| `web_db_migrate` | **SQLite only**(对等) |
| `web_db_fts_create` / `web_db_search` | **SQLite only** |
| `web_db_begin` / `commit` / `rollback` | 事务句柄 |
| `web_db_list_tables` / `web_db_table_info` | admin 内部 |
Where 语义:等值 map、filter 表、OR / IN / BETWEEN、分页 offset/limit——行为对齐现 `db.rs` / `db_pg.rs`。
### 5.5 Cache / storage
| ABI | URL |
|-----|-----|
| `web_cache_new` / `get` / `set` / `del` / `exists` / `ttl` | `memory:` / `redis://` |
| `web_storage_new` / `put` / `get` / `delete` / `list` | `file:` / `s3://` |
### 5.6 App / HTTP / hosting
| ABI | 域 |
|-----|-----|
| `web_app_new` | app |
| `web_app_route` | 动态 `{param}` + `/_part` |
| `web_app_mount_form` | `/_form` |
| `web_app_static` | 静态目录 |
| `web_app_middleware` | `configure`:CORS、安全头、gzip、body_limit、JSON API、access_log、cache_control |
| `web_app_proxy` | 流式反代 / SSE(H1) |
| `web_app_invoke` | HTTP → `lib.member`(H2;经 `host_query call_lib_path`) |
| `web_listen` | 阻塞监听;组装全部路由 |
| `web_app_route_ws` | WS 端点 |
| `web_ws_connect` | 客户端单次请求-响应式 |
| `web_app_auth` | `/admin` 门禁 |
| `web_app_gate` | RBAC 段前缀 |
### 5.7 Form
| ABI |
|-----|
| `web_form_new` / `fields` / `rules` / `validate` / `render` / `submit` / `from_schema` |
规则:`required`、`min:N`、`max:N`、`email`、`url`、`match:field`、`in:a,b,c`。
### 5.8 Session / auth
| ABI |
|-----|
| `web_session_new` / `set` / `get` / `del` / `destroy` |
| `web_auth_new` / `login` / `check` / `logout` |
| `web_password_hash` |
安全对等:argon2id、CSRF、登录限速、CSPRNG session id、cookie Secure(配置)、滑动 TTL、持久化会话(默认 SQLite 会话表;见 §7 Redis 可选)。
### 5.9 HTTP 挂载面(`web_listen` 必须复现)
- `GET /`,`GET /_part/{id}`,`GET|POST /_form/{id}`
- 可选 admin:`{prefix}/`、`/login`、`/logout`、`/{table}`、`/new`、`/{id}/edit`、`/{id}/delete`(C0:`admin=False` 让出 `/admin`)
- 作者 `route` 页 + `{path}/_part/{id}`;动态路径参数
- WS;RSS;upload POST;download GET;gallery;sitemap;`/robots.txt`
- 301/307 重定向;自定义 404/500;proxy;invoke
- 静态与 icons;约定 `/favicon.ico`
- 保留名:`/_form`、`/_part`、静态挂载冲突检测
### 5.10 `host_query` 依赖
| name | 用途 |
|------|------|
| `entry_dir` | 路径沙箱根 |
| `call_lib_path` | invoke / 嵌套 lib 调用(含 `args`) |
| (其它已允许项) | 与 ABI v2 allowlist 一致;不得扩展任意 HostFn |
---
## 6. 作者面(保持 · 不另起炉灶)
英文 `ext/web/web.mq.md` / 中文 `ext/web/网页.mq.md` 现有 `#` 类与 `##` 方法 **保持**:
| 类 | 职责 |
|----|------|
| `# page` / `# 页面` | 装配、meta、head、images、paginate、render |
| `# db` / `# 数据库` + `# txn` | CRUD、事务、migrate/FTS(SQLite) |
| `# form` / `# 表单` | 字段、规则、校验、渲染、提交 |
| `# app` / `# 应用` | route、configure、listen、auth、gate、upload… |
| `# auth` / `# 鉴权` | login/check/logout/hash |
| `# cache` / `# 缓存` | memory/redis |
| `# storage` / `# 存储` | file/s3 |
| `# media` / `# 媒体` | validate/save |
| `# ws` / `# 实时` | connect |
| 模块函数 | `ensure_plugin`、`make_style`、`make_head`、`make_images`、`client_embed`、`text_patch`、`dom_patch`、`list_html` |
**重写默认策略**:先 **只换原生 `.so`**,L1 不动;仅当 §7 G 增强需要新方法时,再 **追加**(不破坏旧方法)。
---
## 7. G 增强(完备网页制备 + anlian;兼容之上增量)
> 以下为 **新增能力**,不替代 §5。作者面用新方法/新 configure 键;旧脚本不受影响。
| ID | 能力 | 动机 | 作者面草案 |
|----|------|------|------------|
| **G-WS1** | **命名房间** WS:`join`/`leave`/`publish`;组名 ASCII(如 `chat.room.{id}`) | anlian 公聊/私聊 | `app.route_ws` 增 `mode=room` + `room_key`;或 `ws.room_*` ABI |
| **G-WS2** | 房间消息钩子:先 `invoke`/落库再广播 | 「先写 PG 再推送」 | configure 或 route 表 `on_message=lib.member` |
| **G-SESS1** | Session 后端可选 `redis://` | 多进程/多实例 | `web_session_new` url 或 auth 配置 `session=redis://` |
| **G-CACHE1** | Redis pub/sub 可选作 WS 扇出后端 | 多进程 WS | `configure ws_backend=redis` |
| **G-API1** | Bearer API Key 校验原语(hash+pepper+scopes) | anlian `apikeys` | `web_api_key_check` + `# auth` 或独立小类;**业务 scopes 仍在 .mq.md** |
| **G-MAIL0** | (可选后续)SMTP 发送原语 | 邮箱验证码 | 不阻塞首版对等;列入 anlian 二期 |
**明确仍属应用层(不进插件)**:反垃圾策略、草稿定时发布约定、好友关系、专题 `topic_bundles` 静态交互内容(静态挂载 + 前端 Marqdo/既有 JS 资产)。
---
## 8. 暗恋见君验收矩阵(检测「能不能写完」)
外部依赖(允许):**PostgreSQL**、**Redis**;可选对象存储。
| 模块 | Marqdo 后端 | Marqdo 前端 | 插件依赖 | 验收 |
|------|-------------|-------------|----------|------|
| 站点壳 / 首页 | `# page` + db | 局部刷新可选 WASM | listen、static、cache | 首页可开 |
| posts 帖子/评论/板块 | route + form + db | 发帖表单 WASM 可选 | CRUD、CSRF、upload | CRUD+列表详情 |
| news | 同上 | 同上 | 同上 | 列表详情 |
| accounts | auth + session +(二期 mail) | 登录表单 | argon2、session、gate | 注册登录 |
| profiles | db + storage | 头像上传 | storage/upload | 资料页 |
| search | db.search 或 PG 查询 + cache | — | db/cache | 关键词搜索 |
| chat | route_ws + G-WS1/2 + db | WS 客户端脚本 | Redis + WS rooms | 公聊+私聊实时 |
| apikeys | G-API1 + db | 管理页 | — | Bearer 调 API |
| webmaster | sitemap/robots | — | 已有 ABI | `/sitemap.xml` |
| topics | `app.static` → bundles | 既有静态交互 | static | 专题可访问 |
**「写完」定义**:上述模块在 Marqdo 仓库或 `anlian` 旁路目录有可运行 `.mq.md` 站点;gold/手工脚本能走通主路径;不依赖 Django/Channels/Daphne/gunicorn。
---
## 9. 仓库布局与构建
### 9.1 目录(目标)
```text
plugins/web/ # Go module(替换原 Rust crate)
go.mod
go.sum
README.md
abi/
marqdo_abi.h # 从 include/ 拷贝或 cgo 引用
bridge.go # //export marqdo_plugin_* ;register;alloc/free
internal/
page/ compose/ render/ form/
db/ # sqlite + postgres driver
cache/ storage/ upload/
session/ auth/ password/ ratelimit/
httpx/ # listen、router、middleware、admin、proxy、invoke
ws/ # hub、rooms、client connect
assets/ rss/ sitemap/ markdown/
table/ # GFM 表 JSON 形态辅助
cmd/ # 可选:非 c-shared 的本地自测
scripts/build-web-plugin.sh # go build -buildmode=c-shared -o …/libweb.so
```
原 Rust 源码:`plugins/web-rust-archive/`(**已移出 Cargo workspace**;参考用,默认不构建)。
### 9.2 产物与解析
| 平台 | 文件名 |
|------|--------|
| Linux | `libweb.so` |
| macOS | `libweb.dylib` |
| Windows | `web.dll` |
解析顺序仍走 `installed_native_path` / `MARQDO_WEB_PLUGIN`;`find_native_plugin` 增加查找:
- `plugins/web/build/libweb.so`(Go 构建输出)
- `target/{debug,release}/libweb.so`(兼容旧路径,可选 copy)
### 9.3 宿主 / CI 变更要点
| 组件 | 变更 |
|------|------|
| 根 `Cargo.toml` workspace | 移除 `plugins/web` / `web-rust-archive` Rust member |
| `tests/gold.rs` | `ensure_web_plugin_built()` → `scripts/build-web-plugin.sh` |
| `marqdo ext add web` | 构建回退:`scripts/build-web-plugin.sh`(Go);Release 仍下发预编译 native zip |
| Release 脚本 | Go:`scripts/build-web-plugin.sh`;其它插件仍 `cargo build -p …` |
| [ext-cli.md](ext-cli.md) / [ext-abi.md](ext-abi.md) | 注明 web 插件实现语言为 Go |
### 9.4 cgo / runtime 注意
- `marqdo_plugin_init` 内 `register_fn` 注册全部符号;保存 host `alloc`/`free`/`host_query`。
- 长时间 `web_listen`:在独立 goroutine 跑 `http.Server`,ABI 调用阻塞至 shutdown 或按现语义阻塞(**对齐现 Rust:listen 阻塞当前插件调用**)。
- 禁止在 FFI 回调里长时间持有阻碍 GC 的错误模式;JSON 尽快拷贝到 Go string。
- Windows 导出需 `.def` 或 `//export` 完整三个符号。
---
## 10. 实现波次(按文档开发顺序)
| 波次 | 内容 | 退出条件 |
|------|------|----------|
| **W-G0** | 文档(本文)+ ADR + 目录骨架 + ABI bridge 能 `plugin.load` + `demo` 注册探测 | ✅ `tests/ext/web-go-abi-smoke.mq.md`;`web_go_ready` + `web_page_new`;`scripts/build-web-plugin.sh` → `libweb.so` |
| **W-G1** | table 辅助 + `web_style` + page new/compose/render(无 listen) | ✅ `web-smoke` / `web-zh-smoke`(含 compose_form / app_new / app_route 袋) |
| **W-G2** | SQLite db CRUD + where + txn + init | ✅ `web-db-w2-smoke` / `web-db-w6-smoke`(txn·migrate·FTS) |
| **W-G3** | form + mount_form + CSRF 基础 | ✅ `web-form-smoke`(validate/submit/render;CSRF 字段已接,listen 侧硬化见 W-G4/G5) |
| **W-G4** | `web_listen` + route + static + part + middleware + JSON API | ✅ offline:`web-route` / `web-static` / `web-middleware` / `web-part`;`web_listen` 已接线(live 随 W-G5+ hardening) |
| **W-G5** | session/auth/password/rate limit/gate/admin | ✅ offline:`web-security` / `web-c0` / `web-c1`;login rate limit 包已就位(HTTP 接线随 listen hardening) |
| **W-G6** | upload/download/gallery/ETag + assets W8 | ✅ `web-upload` / `web-assets` / `web-p3` |
| **W-G7** | SEO RSS sitemap robots redirect error paginate markdown | ✅ `web-content` / `web-w7-*` |
| **W-G8** | WS echo/broadcast + access_log | ✅ `web-ws-broadcast-*` |
| **W-G9** | Postgres + Redis cache + file/S3 storage | ✅ `web-drivers-smoke` |
| **W-G10** | proxy + invoke + nested plugin | ✅ `web-proxy-invoke` / hosting live |
| **W-G11** | 定制 C2–C4 shell/layout/style/nav | ✅ `web-c2`–`c4` |
| **W-G12** | G 增强 WS rooms + Redis session/pubsub + API key 原语 | ✅ 单测 + `web-g12-api-key-smoke` |
| **W-G13** | 默认切换 Go `libweb`;归档 Rust;更新发版与 ext CLI | ✅ 离线+live gold(7 个 `*_live`)对 Go 全绿;`ext add`/`gold`/`release` 走 `scripts/build-web-plugin.sh`;Rust 移出 workspace;gold 强制 `MARQDO_WEB_PLUGIN` 避免 `~/.marqdo` 旧 so |
| **W-G14** | anlian Marqdo 重写主路径(可分仓或 `examples/anlian-mq/`) | ✅ `examples/anlian-mq/`(本地 SQLite + 粉玻璃主题 + 主路由/登录/片段;外接 PG/Redis 仍为增强路径) |
每波次:**先补 Go 实现 → 跑对应 gold → 再进入下一波**。禁止跨波次留下「注册了但返回 stub 错误」的 ABI(除 W-G0 明确的未实现探测)。
---
## 11. 测试策略
| 类型 | 做法 |
|------|------|
| 单元 | Go `go test ./internal/...`(db where、form rules、middleware) |
| 金样例 | 现有 `tests/ext/web-*.mq.md`;构建脚本产出 `libweb.so` 后跑 |
| Live | 现有 `*-live-server.mq.md` + curl |
| 回归门禁 | CI:安装 Go → `scripts/build-web-plugin.sh` → `cargo test` 相关 web 项 |
| anlian | 独立 smoke:登录、发帖、WS 发言、API key |
---
## 12. 风险与缓解
| 风险 | 缓解 |
|------|------|
| cgo/共享库与宿主线程 | 文档化;listen 独立 goroutine;shutdown 明确 |
| JSON ABI 开销 | 热路径减少往返;装配结果缓存;不在此用「换语言」幻想消除 |
| 行为微差异(HTML/Markdown) | 用同一批 gold HTML 片段断言;差异列 changelog |
| 交叉编译 | 优先 `modernc.org/sqlite`;Release 矩阵 Linux/Windows 先 |
| 双实现并存混乱 | W-G13 前用 `MARQDO_WEB_PLUGIN` 显式指向;文档写清默认 |
---
## 13. 文档与索引更新清单
实现推进时同步:
- [x] 本文状态行随波次更新
- [x] [ext-abi.md](ext-abi.md) Demo/Web 节:实现语言 Go
- [x] [ext-cli.md](ext-cli.md):构建回退含 `go build` / `scripts/build-web-plugin.sh`
- [x] [ext-web.md](ext-web.md):链到本文;C5 落实说明
- [ ] [web-asgi-servers-and-marqdo.md](web-asgi-servers-and-marqdo.md):axum → Go `net/http`
- [ ] [doc/README.md](../README.md) 索引行(若尚未链到本文)
- [x] ADR:`doc/adr/0004-web-plugin-go.md`(Accepted)
- [x] `plugins/web/README.md` 开发者构建说明
---
## 14. 决议摘要
1. **全量重写** `plugins/web` 为 Go,**不是**最小闭环。
2. **既有网络拓展能力(§5)重写后必须仍可用**;作者面默认兼容。
3. **PostgreSQL / Redis 外接** 为一等公民;Marqdo 承担应用前后端脚本。
4. **暗恋见君** 为完备性验收,不是缩小插件范围的借口。
5. **多语言 ABI 生态** 以本插件为样板(G7)。
6. 开发严格按 **§10 波次** 推进;本文件为唯一施工图。
+2 -2
View File
@@ -45,7 +45,7 @@
| C2 | 作者面**禁止** `json.parse` / `json.set` 袋胶水、手写 part JSON、手写 assemble 袋 |
| C3 | 能力以 **`#` 类 + `##` 方法** 暴露;**英文库文件只用英文名,中文库文件只用中文名**(见 [stdlib-i18n.md](stdlib-i18n.md));同一 `.mq.md` 内禁止中英 API 混排 |
| C4 | 首页在 **`index.mq.md`**:页面表在此;可复用片段进 `components/`;主体可就地写 |
| C5 | **旧有网络扩展库全部废弃**:`plugins/web`、`ext/web/**`(含现网示例/gold 中依赖旧 API 者)评审通过后**删除或清空后重写**;禁止在旧代码上打补丁演进 |
| C5 | **旧有网络扩展库全部废弃**:`plugins/web`、`ext/web/**`(含现网示例/gold 中依赖旧 API 者)评审通过后**删除或清空后重写**;禁止在旧代码上打补丁演进。**落实**:原生层 Go 全量重写见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md);作者面 ABI 名保持兼容 |
| C6 | `# db` / `# 数据库` 必须提供完整**增删改查**;列表查询英文方法名为 **`select`**(中文 **`查询`**);后台 `/admin` 与表单提交走同一套写库 API |
| C7 | 用户输入经 `# form` / `# 表单`:字段表 + 校验表;**服务端校验必须在写库前执行**(见 §5.5) |
@@ -541,7 +541,7 @@ submit → action=insert → db.insert;action=update → db.update
|----|----|------|
| Marqdo 核心 | 表→Value、类/方法、import | 不识别 web 路径语法 |
| `ext/web/*.mq.md` | 作者 API、中英面、委托插件 | 不直接 `host_*` |
| `plugins/web` | 路径解析辅助、装配结果、listen、SQL、渲染 | 不要求作者写袋 |
| `plugins/web` | **Go** `libweb`(HTTP / SQL / HTML 壳;见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md)) | 不要求作者写袋 |
**实现要点(评审通过后再做):**
+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 / 用户站收录(随发版);应主要靠核心+中层、默认无插件 |
---
+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`。
+1 -1
View File
@@ -2,7 +2,7 @@
| | |
|---|---|
| 状态 | **Completed**(路线 C 首版功能完备) |
| 状态 | **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) |
+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) |
+1 -1
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 是两条路径。
+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
+45
View File
@@ -0,0 +1,45 @@
# 暗恋见君 · Marqdo 重写
用 **Marqdo + `ext/web`(Go `libweb`)** 对齐 Django [anlian](../../../anlian/) 的主浏览路径与视觉:原站 CSS/JS、首页四段、列表/详情、发帖门禁、聊天室、专题、搜索入口、API 指南。
默认 **SQLite**(`data/anlian-mq.db`);生产可换 `postgres://` + Redis。
## 设计约定
| 做 | 不做 |
|----|------|
| GFM 表装配库表/种子/表单/门禁/头资源 | `json.set` 链拼页面 |
| 原站 `public/css|js|img` + DOM class 对齐 | 另起一套模板糊弄验收 |
| `页面.壳HTML` 挂 Django 级导航/页脚 | 业务写进 Go 插件 |
| 缺能力时改 `ext/web` / `libweb` | 在应用层堆不可读胶水 |
## 路径(对齐原站)
| 路径 | 能力 |
|------|------|
| `/` | Hero + 公告 + 新闻时间线 + 论坛板块栏/卡片 |
| `/post`、`/post/{slug}` | 帖子列表 / 详情 |
| `/news`、`/news/{slug}` | 新闻列表 / 详情 |
| `/post/public` | 发帖(需登录) |
| `/post/ten`、`/news/five` | 首页 AJAX 片段 |
| `/chat`、`/chat/lobby`、`/chat/casual` | 房间列表 + 公聊 WS |
| `/topics` | 专题书架 |
| `/search` | 搜索入口 |
| `/guide/automation-api` | API 指南 |
| `/accounts/login` | 粉玻璃登录 |
| `/sitemap.xml`、`/robots.txt` | 站长 |
## 运行
```bash
export PATH="$HOME/.local/go/bin:$PATH"
./scripts/build-web-plugin.sh
export MARQDO_WEB_PLUGIN=$PWD/plugins/web/build/libweb.so
rm -f examples/anlian-mq/data/anlian-mq.db* # 首次或改 schema 后
./target/debug/marqdo run examples/anlian-mq/index.mq.md
# → http://127.0.0.1:18180/
bash examples/anlian-mq/smoke.sh
```
默认账号:`admin` / `anlian`。
@@ -0,0 +1,50 @@
---
title: components/chrome
description: 暗恋见君壳层 — head 资源表、导航 HTML、页脚 HTML(对齐 Django base / site_footer)。
---
## 头资源
首页与浏览页共用的 CSS / JS 链接表(挂到 `页面.头装配`)。路径对齐 `public/` 静态树。
`头` =
| 关系 | 地址 | 推迟 |
|------|------|------|
| stylesheet | "/static/vendor/bootstrap-anlian.min.css" | |
| stylesheet | "/static/css/base.css" | |
| stylesheet | "/static/css/navbar_search.css" | |
| stylesheet | "/static/css/footer.css" | |
| stylesheet | "/static/css/icons.css" | |
| stylesheet | "/static/css/feed_common.css" | |
| stylesheet | "/static/css/feed_list.css" | |
| stylesheet | "/static/css/index.css" | |
| stylesheet | "/static/css/index/hero.css" | |
| stylesheet | "/static/css/index/notice.css" | |
| stylesheet | "/static/css/index/home_news_timeline.css" | |
| stylesheet | "/static/css/index/home_posts.css" | |
| stylesheet | "/static/css/anlian_forms.css" | |
| stylesheet | "/static/css/login.css" | |
| stylesheet | "/static/css/rich_content.css" | |
| stylesheet | "/static/css/detail_reading.css" | |
| stylesheet | "/static/css/search.css" | |
| stylesheet | "/static/css/chat.css" | |
| stylesheet | "/static/css/topic_index.css" | |
| script | "/static/vendor/bootstrap.bundle.min.js" | 真 |
| script | "/static/js/anlian_partial.js" | 真 |
| script | "/static/js/feed_board.js" | 真 |
| script | "/static/js/index.js" | 真 |
**`头`**
## 导航HTML
对齐 Django `front/base.html` 顶栏:品牌「暗恋见君论坛」、主导航、搜索、登录/退出(`nav-when-guest` / `nav-when-auth` 由 CSS/JS 切换)。
**"<nav class=\"navbar navbar-expand-lg navbar-dark bg-dark\"><div class=\"container-fluid navbar-shell\"><div class=\"navbar-start\"><div class=\"navbar-logo\"><img src=\"/static/img/logo.svg\" alt=\"logo\" width=\"30\" height=\"30\" decoding=\"async\"></div><a class=\"navbar-brand\" href=\"/\">暗恋见君论坛</a></div><button class=\"navbar-toggler\" type=\"button\" data-bs-toggle=\"collapse\" data-bs-target=\"#navbarNav\" aria-controls=\"navbarNav\" aria-expanded=\"false\" aria-label=\"Toggle navigation\"><span class=\"navbar-toggler-icon\"></span></button><div class=\"collapse navbar-collapse\" id=\"navbarNav\"><ul class=\"navbar-nav navbar-nav-main\"><li class=\"nav-item\"><a class=\"nav-link\" href=\"/\">首页</a></li><li class=\"nav-item\"><a class=\"nav-link\" href=\"/post\">帖子</a></li><li class=\"nav-item\"><a class=\"nav-link\" href=\"/news\">新闻</a></li><li class=\"nav-item\"><a class=\"nav-link\" href=\"/topics\">专题</a></li><li class=\"nav-item\"><a class=\"nav-link\" href=\"/chat\">聊天</a></li><li class=\"nav-item\"><a class=\"nav-link\" href=\"/post/public\">发帖</a></li></ul><div class=\"navbar-end\"><form class=\"navbar-search d-flex\" action=\"/search\" method=\"get\" role=\"search\"><input class=\"form-control\" type=\"search\" name=\"q\" placeholder=\"搜索帖子、新闻、用户\" aria-label=\"搜索\" maxlength=\"100\" autocomplete=\"off\"><button class=\"btn btn-search-submit\" type=\"submit\">搜索</button></form><ul class=\"navbar-nav navbar-auth\"><li class=\"nav-item nav-when-guest\"><a class=\"nav-link nav-link-auth\" href=\"/accounts/login\">登录</a></li><li class=\"nav-item nav-when-auth\"><a class=\"nav-link nav-link-btn\" href=\"/admin/logout\">退出</a></li></ul></div></div></div></nav>"**
## 页脚HTML
对齐 `site_footer`:站点列 + 作者列;标语、版权、API 指南、作者 cflmy。
**"<footer class=\"site-footer\"><div class=\"site-footer-inner\"><div class=\"footer-col footer-col-site\"><img src=\"/static/img/logo.svg\" alt=\"\" class=\"footer-site-logo\" width=\"40\" height=\"40\" loading=\"lazy\"><p class=\"footer-site-name\">暗恋见君论坛</p><p class=\"footer-site-tagline\">期待人们能够继续相信爱情</p><p class=\"footer-copy\">&copy; 2026 暗恋见君论坛</p><p class=\"footer-meta-sm footer-api-guide\"><a href=\"/guide/automation-api\" class=\"footer-guide-btn\" title=\"面向开发者的 API Key 与自动化对接说明\"><span class=\"anlian-icon anlian-icon--book\" aria-hidden=\"true\"><svg viewBox=\"0 0 24 24\" xmlns=\"http://www.w3.org/2000/svg\" focusable=\"false\" aria-hidden=\"true\"><path d=\"M6 2a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V4a2 2 0 0 0-2-2H6Zm0 2h5v7.5L8.5 10 6 11.5V4Zm7 0h5v16h-5V4Z\"/></svg></span> API 自动化指南</a></p></div><div class=\"footer-col footer-col-author\"><img src=\"/static/img/author_avatar-144.webp\" alt=\"\" class=\"footer-author-avatar\" width=\"72\" height=\"72\" loading=\"lazy\"><div class=\"footer-author-info\"><p class=\"footer-author-name\">cflmy</p><p class=\"footer-author-title\">站长</p></div></div></div></footer>"**
+97
View File
@@ -0,0 +1,97 @@
---
title: components/feed
description: 帖子列表 / 新闻时间线 / 板块栏 HTML 片段(对齐 Django feed 与 home 局部模板)。
import table:lib/table.mq.md
import text:lib/text.mq.md
---
## 帖子列表HTML
+ `行`
给定帖子行记录列表,输出 `ul.home-posts-list` 标记(首页与列表页共用)。
*段 = None*
- [帖](行)
*板 = 帖[^board]*
*题 = 帖[^title]*
*链 = 帖[^slug]*
*作 = 帖[^author]*
*评 = 帖[^comments_count]*
*时 = 帖[^created_at]*
1. not 作
*作 = "匿名"*
2. *
1. not 评
*评 = 0*
2. *
1. not 时
*时 = ""*
2. *
*一项 = "<li><article class=\"home-post-card feed-post-card\"><a href=\"/post/" + 链 + "\" class=\"home-post-card-link feed-post-card-link\"><span class=\"home-post-board feed-post-board\">" + 板 + "</span><div class=\"home-post-body feed-post-body\"><h3 class=\"home-post-title feed-post-title\">" + 题 + "</h3><div class=\"home-post-meta feed-post-meta\"><span class=\"home-post-meta-item feed-post-meta-item\"><span class=\"anlian-icon anlian-icon--user\" aria-hidden=\"true\"></span> " + 作 + "</span><span class=\"home-post-meta-item feed-post-meta-item\"><span class=\"anlian-icon anlian-icon--comment\" aria-hidden=\"true\"></span> " + 评 + "</span><time>" + 时 + "</time></div></div><span class=\"home-post-arrow feed-post-arrow\" aria-hidden=\"true\"><span class=\"anlian-icon anlian-icon--chevron-right\"></span></span></a></article></li>"*
*段 = > table.append list=段 item=一项*
1. 段
*内 = > text.str_join xs=段 sep=""*
**"<ul class=\"home-posts-list feed-posts-list\">" + 内 + "</ul>"**
2. *
**"<ul class=\"home-posts-list feed-posts-list\"><li class=\"home-posts-empty feed-empty\">暂无帖子,<a href=\"/post/public\">去发帖</a></li></ul>"**
## 新闻时间线HTML
+ `行`
给定新闻行记录列表,输出 `.news-timeline` 标记。
*段 = None*
- [讯](行)
*题 = 讯[^title]*
*链 = 讯[^slug]*
*板 = 讯[^board]*
*时 = 讯[^created_at]*
1. not 板
*板 = ""*
2. *
1. not 时
*时 = ""*
2. *
*一项 = "<li class=\"news-timeline-item\"><span class=\"news-timeline-node\" aria-hidden=\"true\"></span><article class=\"news-timeline-card\"><div class=\"news-timeline-meta\"><time class=\"news-timeline-date\">" + 时 + "</time><span class=\"news-timeline-board\">" + 板 + "</span></div><h3 class=\"news-timeline-title\"><a href=\"/news/" + 链 + "\" class=\"news-timeline-link\">" + 题 + "</a></h3></article></li>"*
*段 = > table.append list=段 item=一项*
1. 段
*内 = > text.str_join xs=段 sep=""*
**"<div class=\"news-timeline\"><div class=\"news-timeline-rail\" aria-hidden=\"true\"><span class=\"news-timeline-line\"></span><span class=\"news-timeline-arrow\" aria-hidden=\"true\"><span class=\"anlian-icon anlian-icon--chevron-right news-timeline-arrow-icon--right\"></span><span class=\"anlian-icon anlian-icon--chevron-down news-timeline-arrow-icon--down\"></span></span></div><ol class=\"news-timeline-items\">" + 内 + "</ol></div>"**
2. *
**"<div class=\"news-timeline\"><div class=\"news-timeline-rail\" aria-hidden=\"true\"><span class=\"news-timeline-line\"></span><span class=\"news-timeline-arrow\" aria-hidden=\"true\"></span></div><ol class=\"news-timeline-items\"><li class=\"news-timeline-item news-timeline-item-empty\"><article class=\"news-timeline-card\"><p class=\"news-timeline-empty\">暂无新闻</p></article></li></ol></div>"**
## 板块栏HTML
+ `板块`
+ `前缀`
+ `查询键`
+ `全部类`
板块 Tab 栏。`前缀` 如 `/post/ten/`;`查询键` 为 `board_id` 或 `news_board_id`;`全部类` 为 Tab 共用 class(含 js hook)。
*数据属 = "data-board"*
*全标签 = "全部"*
1. 查询键 == "news_board_id"
*数据属 = "data-news-board"*
*全标签 = "所有板块"*
2. *
*段 = None*
*全链 = 前缀 + "?" + 查询键 + "=0"*
*全项 = "<a href=\"" + 全链 + "\" class=\"" + 全部类 + " active\" " + 数据属 + "=\"0\">" + 全标签 + "</a>"*
*段 = > table.append list=段 item=全项*
- [板](板块)
*名 = 板[^name]*
*号 = 板[^id]*
*链 = 前缀 + "?" + 查询键 + "=" + 号*
*项 = "<a href=\"" + 链 + "\" class=\"" + 全部类 + "\" " + 数据属 + "=\"" + 号 + "\">" + 名 + "</a>"*
*段 = > table.append list=段 item=项*
1. 查询键 == "news_board_id"
*更多 = "<a href=\"/news\" class=\"home-posts-tab home-posts-tab-more\">全部新闻</a>"*
*段 = > table.append list=段 item=更多*
2. *
*内 = > text.str_join xs=段 sep=""*
*栏类 = "home-posts-board-bar"*
1. 查询键 == "news_board_id"
*栏类 = "home-posts-board-bar home-news-board-bar"*
2. *
**"<div class=\"" + 栏类 + "\" data-feed-board><button type=\"button\" class=\"home-posts-scroll home-posts-scroll-left\" aria-label=\"向左滚动\"><span class=\"anlian-icon anlian-icon--chevron-left\"></span></button><div class=\"home-posts-segment-outer\"><div class=\"home-posts-segment\"><div class=\"home-posts-spotlight\" aria-hidden=\"true\"></div><div class=\"home-posts-tabs-scroll\"><div class=\"home-posts-tabs\" role=\"tablist\">" + 内 + "</div></div></div></div><button type=\"button\" class=\"home-posts-scroll home-posts-scroll-right\" aria-label=\"向右滚动\"><span class=\"anlian-icon anlian-icon--chevron-right\"></span></button></div>"**
+15
View File
@@ -0,0 +1,15 @@
## 页脚
站点信息与站长链接(毛玻璃底由壳样式绘制)。
`页脚` =
| 属性 | 值 |
|------|-----|
| 暗恋见君 · 期待人们能够继续相信爱情 | / |
| 帖子 | /posts |
| 新闻 | /news |
| 公聊 | /chat |
| sitemap | /sitemap.xml |
**`页脚`**
@@ -0,0 +1,21 @@
---
title: components/fragments
description: AJAX 片段 — /post/ten、/news/five。
导入 网页:ext/web/网页.mq.md
import db:../db/index.mq.md
import feed:feed.mq.md
---
## 帖子十
+ `board_id`="0"
*store = > db.打开*
*行 = > store.查询 表="posts" 上限=10 排序="-created_at"*
**> feed.帖子列表HTML 行=`行`**
## 新闻五
+ `news_board_id`="0"
*store = > db.打开*
*行 = > store.查询 表="news" 上限=5 排序="-created_at"*
**> feed.新闻时间线HTML 行=`行`**
+5
View File
@@ -0,0 +1,5 @@
## 首页引言
英雄区 HTML(品牌标语 + CTA + 漂浮主图)。样式在 `styles/shell` 的 Hero / 动效表。
**"<section class=\"hero\" aria-label=\"暗恋见君\"><div class=\"hero-content\"><div class=\"hero-left\"><p class=\"hero-brand\"><img class=\"hero-logo\" src=\"/static/logo.svg\" alt=\"\" width=\"30\" height=\"30\"><span>暗恋<span class=\"hero-pink\">见君</span></span></p><h1 class=\"main-text\">期待人们能够继续相信<span class=\"hero-pink\">爱情</span></h1><p class=\"sub-text\">粉玻璃、呼吸 Logo、漂浮主图——用 Marqdo 表格装配的社区站点,验收「代码即文档」能否撑起真实前端。</p><p class=\"hero-cta\"><a class=\"hero-btn\" href=\"/posts\">浏览帖子</a><a class=\"hero-btn ghost\" href=\"/news\">新闻</a><a class=\"hero-btn ghost\" href=\"/chat\">公聊</a></p></div><div class=\"hero-right\"><img class=\"hero-art\" src=\"/static/bg-hero-640.webp\" alt=\"暗恋见君\"></div></div></section><div class=\"home-feed-head\"><h2>最新帖子</h2><p>来自粉玻璃卡片流</p></div>"**
@@ -0,0 +1,47 @@
---
title: components/home_body
description: 首页主体 HTML — hero + 公告 + 新闻时间线 + 论坛帖子(对齐 Django home.html,无外层导航)。
导入 网页:ext/web/网页.mq.md
import table:lib/table.mq.md
import text:lib/text.mq.md
import feed:feed.mq.md
---
## 装配
+ `库`
查询 notices / boards / news_boards / news(5) / posts(10),拼装首页四段 HTML(不含导航与页脚)。调用方传入已打开的 store。
*公告行 = > 库.查询 表="notices" 上限=20 排序="-created_at"*
*板块行 = > 库.查询 表="boards" 上限=50*
*新闻板块行 = > 库.查询 表="news_boards" 上限=50*
*新闻行 = > 库.查询 表="news" 上限=5 排序="-created_at"*
*帖子行 = > 库.查询 表="posts" 上限=10 排序="-created_at"*
*公告段 = None*
- [告](公告行)
*文 = 告[^content]*
*时 = 告[^created_at]*
*一项 = "<div class=\"notice-item\"><article class=\"notice-content\">" + 文 + "</article><p class=\"notice-create-time\">" + 时 + "</p></div>"*
*公告段 = > table.append list=公告段 item=一项*
1. 公告段
*公告内 = > text.str_join xs=公告段 sep=""*
2. *
*公告内 = "<p class=\"text-muted\">暂无公告</p>"*
*新闻栏 = > feed.板块栏HTML 板块=新闻板块行 前缀="/news/five" 查询键="news_board_id" 全部类="home-posts-tab js-home-news-tab"*
*新闻板 = > feed.新闻时间线HTML 行=新闻行*
*帖子栏 = > feed.板块栏HTML 板块=板块行 前缀="/post/ten" 查询键="board_id" 全部类="home-posts-tab js-home-post-tab"*
*帖子表 = > feed.帖子列表HTML 行=帖子行*
*段 = None*
*英雄 = "<section class=\"hero\"><div class=\"section-wrap\"><header><img src=\"/static/img/logo.svg\" alt=\"logo\" width=\"30\" height=\"30\" decoding=\"async\"><a class=\"head-logo\" href=\"/\"><span>暗恋</span>见君</a></header><div class=\"hero-content\"><div class=\"left\"><h1 class=\"main-text\">期待人们能够继续相信<span style=\"color:#ffd0d0\">爱情</span></h1><h2 class=\"sub-text\">粉玻璃社区 · 匿名与实名同在</h2></div><div class=\"right\"><img src=\"/static/img/bg-hero-640.webp\" alt=\"首页展示图\" width=\"640\" height=\"482\" fetchpriority=\"high\" decoding=\"async\"></div></div><div class=\"social\"></div></div></section>"*
*段 = > table.append list=段 item=英雄*
*公告区 = "<section class=\"notice\"><div class=\"section-wrap\"><h2 class=\"notice-title\">公告信息</h2><div class=\"notice-content-container\"><div class=\"notice-list\">" + 公告内 + "</div></div></div></section>"*
*段 = > table.append list=段 item=公告区*
*新闻区 = "<section class=\"news home-news\" id=\"news\"><div class=\"section-wrap home-news-stage\"><h2 class=\"news-title\">新闻动态</h2>" + 新闻栏 + "<div class=\"news-timeline-wrap\"><div id=\"homeNewsPanel\" class=\"news-timeline-panel home-panel-swap\">" + 新闻板 + "</div></div></div></section>"*
*段 = > table.append list=段 item=新闻区*
*更多 = "<a href=\"/post\" class=\"home-posts-more-link\">查看更多帖子</a>"*
*帖子区 = "<section class=\"home-posts\" id=\"post\"><div class=\"section-wrap home-posts-stage\"><h2 class=\"home-posts-title\">论坛交流</h2>" + 帖子栏 + "<div id=\"tenPostContainer\" class=\"home-posts-panel home-panel-swap\">" + 帖子表 + 更多 + "</div></div></section>"*
*段 = > table.append list=段 item=帖子区*
**> text.str_join xs=段 sep=""**
+18
View File
@@ -0,0 +1,18 @@
## 导航
顶栏:首页、帖子、新闻、搜索、聊天、发帖(登录后)、后台。
`导航` =
| 属性 | 值 | 样式 | 媒体 | 当 |
|------|-----|------|------|-----|
| 暗恋见君 | / | | | |
| 帖子 | /posts | | | |
| 新闻 | /news | | | |
| 搜索 | /search | | | |
| 聊天 | /chat | | | |
| 发帖 | /write | | | auth |
| 登录 | /admin/login | | | guest |
| 后台 | /admin | | | auth |
**`导航`**
+18
View File
@@ -0,0 +1,18 @@
---
title: components/page
description: 用原站 chrome 包一层完整 HTML 引言(bare 布局)。
import text:lib/text.mq.md
import chrome:chrome.mq.md
---
## 包装
+ `正文`
+ `体类`=""
导航 + 正文 + 页脚;体类如 `page-home`。
*顶 = > chrome.导航HTML*
*底 = > chrome.页脚HTML*
*鉴权脚本 = "<script>(function(){var c=document.cookie.indexOf('marqdo_sid=')>=0;document.querySelectorAll('.nav-when-guest').forEach(function(el){el.style.display=c?'none':'';});document.querySelectorAll('.nav-when-auth').forEach(function(el){el.style.display=c?'':'none';});})();</script>"*
*鉴权样式 = "<style>.nav-when-auth{display:none}</style>"*
**鉴权样式 + 顶 + "<main class=\"anlian-main " + 体类 + "\">" + 正文 + "</main>" + 底 + 鉴权脚本**
+63
View File
@@ -0,0 +1,63 @@
---
title: db/index
description: 打开库、建全表、幂等种子、帖子全文索引。
导入 网页:ext/web/网页.mq.md
import schema:schema.mq.md
import seed:seed.mq.md
---
## 打开
打开 sqlite:data/anlian-mq.db,初始化全部表;帖子建 FTS;若 posts 为空则写入种子。返回 store。
*store = > 网页.数据库 地址="sqlite:data/anlian-mq.db"*
*帖子字段 = > schema.posts*
*新闻字段 = > schema.news*
*板块字段 = > schema.boards*
*新闻板块字段 = > schema.news_boards*
*公告字段 = > schema.notices*
*评论字段 = > schema.comments*
*房间字段 = > schema.chat_rooms*
*专题字段 = > schema.topics*
*密钥字段 = > schema.api_keys*
> `store`.初始化 名=posts 字段=`帖子字段`
> `store`.初始化 名=news 字段=`新闻字段`
> `store`.初始化 名=boards 字段=`板块字段`
> `store`.初始化 名=news_boards 字段=`新闻板块字段`
> `store`.初始化 名=notices 字段=`公告字段`
> `store`.初始化 名=comments 字段=`评论字段`
> `store`.初始化 名=chat_rooms 字段=`房间字段`
> `store`.初始化 名=topics 字段=`专题字段`
> `store`.初始化 名=api_keys 字段=`密钥字段`
`全文列` =
| 列 |
|----|
| title |
| summary |
| body |
> `store`.全文 表=posts 列=`全文列` 名=posts_fts
*已有 = > store.查询 表="posts" 上限=1*
1. `已有`
**store**
2. *
*板块 = > seed.boards*
*新闻板块 = > seed.news_boards*
*帖子 = > seed.posts*
*新闻 = > seed.news*
*公告 = > seed.notices*
*评论 = > seed.comments*
*房间 = > seed.chat_rooms*
*专题 = > seed.topics*
> `store`.插入 表=boards 行=`板块`
> `store`.插入 表=news_boards 行=`新闻板块`
> `store`.插入 表=posts 行=`帖子`
> `store`.插入 表=news 行=`新闻`
> `store`.插入 表=notices 行=`公告`
> `store`.插入 表=comments 行=`评论`
> `store`.插入 表=chat_rooms 行=`房间`
> `store`.插入 表=topics 行=`专题`
**store**
+146
View File
@@ -0,0 +1,146 @@
## posts
帖子主表。`slug` 用于详情路径;`board` 为板块显示名,`board_id` 关联 `boards`。
`posts` =
| 字段 | 类型 | 可空 | 索引 |
|------|------|------|------|
| id | integer | false | |
| title | text | false | |
| slug | text | false | 是 |
| summary | text | true | |
| body | text | true | |
| board | text | true | |
| board_id | integer | true | |
| author | text | true | |
| comments_count | integer | true | |
| views | integer | true | |
| created_at | timestamp | true | |
| updated_at | timestamp | true | |
**`posts`**
## news
新闻主表。`board_id` 关联 `news_boards`;`board` 为板块显示名。
`news` =
| 字段 | 类型 | 可空 | 索引 |
|------|------|------|------|
| id | integer | false | |
| title | text | false | |
| slug | text | false | 是 |
| summary | text | true | |
| body | text | true | |
| board | text | true | |
| board_id | integer | true | |
| created_at | timestamp | true | |
| updated_at | timestamp | true | |
**`news`**
## boards
帖子板块。
`boards` =
| 字段 | 类型 | 可空 | 索引 |
|------|------|------|------|
| id | integer | false | |
| name | text | false | |
| slug | text | false | 是 |
**`boards`**
## news_boards
新闻板块。
`news_boards` =
| 字段 | 类型 | 可空 | 索引 |
|------|------|------|------|
| id | integer | false | |
| name | text | false | |
| slug | text | false | 是 |
**`news_boards`**
## notices
首页公告。
`notices` =
| 字段 | 类型 | 可空 |
|------|------|------|
| id | integer | false |
| content | text | false |
| created_at | timestamp | true |
**`notices`**
## comments
评论(按目标类型 + slug 挂接)。
`comments` =
| 字段 | 类型 | 可空 |
|------|------|------|
| id | integer | false |
| target_type | text | false |
| target_slug | text | false |
| body | text | false |
| author | text | true |
| created_at | timestamp | true |
**`comments`**
## chat_rooms
公聊房间。
`chat_rooms` =
| 字段 | 类型 | 可空 | 索引 |
|------|------|------|------|
| id | integer | false | |
| slug | text | false | 是 |
| name | text | false | |
| summary | text | true | |
**`chat_rooms`**
## topics
专题占位。
`topics` =
| 字段 | 类型 | 可空 | 索引 |
|------|------|------|------|
| id | integer | false | |
| slug | text | false | 是 |
| title | text | false | |
| summary | text | true | |
**`topics`**
## api_keys
API Key 校验用哈希表(应用层 scopes)。
`api_keys` =
| 字段 | 类型 | 可空 |
|------|------|------|
| id | integer | false |
| name | text | false |
| hash | text | false |
| scopes | text | true |
**`api_keys`**
+106
View File
@@ -0,0 +1,106 @@
## boards
帖子板块:日常 / 开发 / 聊天。
`boards` =
| @ | name | slug |
|---|------|------|
| 1 | 日常 | daily |
| 2 | 开发 | develop |
| 3 | 聊天 | chat |
**`boards`**
## news_boards
新闻板块:站务 / 技术。
`news_boards` =
| @ | name | slug |
|---|------|------|
| 1 | 站务 | site |
| 2 | 技术 | tech |
**`news_boards`**
## posts
种子帖子(标题/短链与原 anlian-mq 一致)。
`posts` =
| @ | title | slug | summary | body | board | board_id | author | comments_count | views |
|---|-------|------|---------|------|-------|----------|--------|----------------|-------|
| 1 | 欢迎来到暗恋见君 | welcome | 期待人们能够继续相信爱情。 | 这是用 Marqdo 重写的验收站点。页面、库表与门禁都用 GFM 表格装配——代码即文档。 | 日常 | 1 | 站务 | 2 | 42 |
| 2 | 如何用表格写论坛 | tables-for-forums | 导航、表单、种子数据都是可读表格。 | 若某功能逼你写一长串 json.set,请先审视 ext/web 是否缺命名方法。 | 开发 | 2 | 站务 | 0 | 18 |
| 3 | 公聊室已开放 | chat-open | WebSocket 广播房间。 | 打开 /chat,连上 /chat/ws,消息会扇出给同房间所有人。 | 聊天 | 3 | 站务 | 0 | 9 |
**`posts`**
## news
种子新闻。
`news` =
| @ | title | slug | summary | body | board | board_id |
|---|-------|------|---------|------|-------|----------|
| 1 | 站点迁往 Marqdo | migrate-to-marqdo | 原生层换 Go libweb,作者面保持表格。 | 暗恋见君的验收目标:登录、发帖、列表详情、聊天与站长工具都能用 .mq.md 写完。 | 站务 | 1 |
| 2 | 外接 PostgreSQL / Redis | pg-redis | 生产可用外接驱动。 | 本示例默认 sqlite:;把数据库地址换成 postgres:// 即可。 | 技术 | 2 |
**`news`**
## notices
首页公告(2–3 条)。
`notices` =
| @ | content | created_at |
|---|---------|------------|
| 1 | 欢迎来到暗恋见君论坛。本站支持匿名与实名交流,请友善发言。 | 2026-09-01 10:00:00 |
| 2 | 站点正用 Marqdo 表格重写验收:导航、首页四段、列表与公聊对齐原站 DOM。 | 2026-09-08 14:30:00 |
| 3 | 发帖与评论请遵守社区规范;站务公告将在此置顶。 | 2026-09-10 09:00:00 |
**`notices`**
## comments
欢迎帖下的评论。
`comments` =
| @ | target_type | target_slug | body | author | created_at |
|---|-------------|-------------|------|--------|------------|
| 1 | post | welcome | 终于等到用表格写论坛的一天。 | 路人甲 | 2026-09-10 11:00:00 |
| 2 | post | welcome | 期待人们能够继续相信爱情。 | 见君 | 2026-09-10 12:15:00 |
**`comments`**
## chat_rooms
公聊:大厅 + 闲聊。
`chat_rooms` =
| @ | slug | name | summary |
|---|------|------|---------|
| 1 | lobby | 大厅 | 全站公共聊天室。 |
| 2 | casual | 闲聊 | 轻松闲聊,勿刷屏。 |
**`chat_rooms`**
## topics
专题占位条目。
`topics` =
| @ | slug | title | summary |
|---|------|-------|---------|
| 1 | glass-ui | 粉玻璃界面 | 首页与列表的毛玻璃视觉专题(占位)。 |
| 2 | tables-as-code | 表格即代码 | Marqdo GFM 表装配专题(占位)。 |
**`topics`**
+210
View File
@@ -0,0 +1,210 @@
---
title: 暗恋见君 · Marqdo
description: 对齐 Django 暗恋见君:原站 CSS/DOM、首页四段、列表详情、发帖门禁、聊天室、专题、搜索、API 指南。
导入 网页:ext/web/网页.mq.md
import table:lib/table.mq.md
import text:lib/text.mq.md
import chrome:components/chrome.mq.md
import page:components/page.mq.md
import home:components/home_body.mq.md
import feed:components/feed.mq.md
import fragments:components/fragments.mq.md
import db:db/index.mq.md
---
# main
路径对齐原站:`/post`、`/news`、`/post/public`、`/chat`、`/topics`、`/search`、`/accounts/login`。
`用户表` =
| 行 | 用户名 | 密码 | 角色 |
|----|--------|------|------|
| 1 | admin | anlian | admin |
`发帖字段` =
| 字段 | 标签 | 类型 | 必填 |
|------|------|------|------|
| title | 标题 | text | true |
| slug | 短链 | text | true |
| summary | 摘要 | text | false |
| body | 正文 | textarea | true |
| board | 板块 | text | false |
| board_id | 板块ID | number | false |
| author | 署名 | text | false |
`发帖规则` =
| 字段 | 规则 | 消息 |
|------|------|------|
| title | required | 标题不能为空 |
| slug | required | 需要短链 |
| body | required | 正文不能为空 |
`帖子详情` =
| 属性 | 值 | 样式 |
|------|-----|------|
| title | posts.title | |
| meta | posts.author | |
| body | posts.body | |
`新闻详情` =
| 属性 | 值 | 样式 |
|------|-----|------|
| title | news.title | |
| body | news.body | |
`帖子条件` =
| 字段 | 操作 | 值 |
|------|------|-----|
| slug | = | {slug} |
`新闻条件` =
| 字段 | 操作 | 值 |
|------|------|-----|
| slug | = | {slug} |
`地图项` =
| loc | 更新 |
|-----|------|
| / | 2026-09-10 |
| /post | 2026-09-10 |
| /news | 2026-09-10 |
| /chat | 2026-09-10 |
| /topics | 2026-09-10 |
| /search | 2026-09-10 |
| /guide/automation-api | 2026-09-10 |
`图标` =
| 路径 | 关系 | 类型 | 尺寸 | 地址 |
|------|------|------|------|------|
| "public/img/favicon-32.png" | icon | "image/png" | 32x32 | "/favicon.ico" |
*store = > db.打开*
*头 = > chrome.头资源*
*顶 = > chrome.导航HTML*
*底 = > chrome.页脚HTML*
*鉴权补丁 = "<style>.nav-when-auth{display:none}</style><script>(function(){var c=document.cookie.indexOf('marqdo_sid=')>=0;document.querySelectorAll('.nav-when-guest').forEach(function(el){el.style.display=c?'none':'';});document.querySelectorAll('.nav-when-auth').forEach(function(el){el.style.display=c?'':'none';});})();</script>"*
*主页体 = > home.装配 库=`store`*
*主页文 = > page.包装 正文=`主页体` 体类="page-home"*
*首页 = > 网页.页面 标题="暗恋见君论坛" 引言=`主页文` 壳样式="off" 布局="bare"*
*首页 = > 首页.头装配 表=`头`*
*板块行 = > store.查询 表="boards" 上限=50*
*帖子行 = > store.查询 表="posts" 上限=50 排序="-created_at"*
*帖子栏 = > feed.板块栏HTML 板块=板块行 前缀="/post" 查询键="board_id" 全部类="feed-tab"*
*帖子表 = > feed.帖子列表HTML 行=帖子行*
*帖子列表体 = "<section class=\"feed-list-page\"><div class=\"section-wrap\"><h1 class=\"feed-list-title\">论坛交流</h1>" + 帖子栏 + 帖子表 + "<p style=\"margin-top:1rem\"><a href=\"/post/public\">发布帖子</a></p></div></section>"*
*帖子列表文 = > page.包装 正文=`帖子列表体` 体类="page-post-list"*
*帖子列表 = > 网页.页面 标题="帖子 · 暗恋见君" 引言=`帖子列表文` 壳样式="off" 布局="bare"*
*帖子列表 = > 帖子列表.头装配 表=`头`*
*新闻板块行 = > store.查询 表="news_boards" 上限=50*
*新闻行 = > store.查询 表="news" 上限=50 排序="-created_at"*
*新闻栏 = > feed.板块栏HTML 板块=新闻板块行 前缀="/news" 查询键="news_board_id" 全部类="feed-tab"*
*新闻表 = > feed.新闻时间线HTML 行=新闻行*
*新闻列表体 = "<section class=\"feed-list-page home-news\"><div class=\"section-wrap\"><h1 class=\"feed-list-title\">新闻动态</h1>" + 新闻栏 + 新闻表 + "</div></section>"*
*新闻列表文 = > page.包装 正文=`新闻列表体` 体类="page-news-list"*
*新闻列表 = > 网页.页面 标题="新闻 · 暗恋见君" 引言=`新闻列表文` 壳样式="off" 布局="bare"*
*新闻列表 = > 新闻列表.头装配 表=`头`*
*帖子页 = > 网页.页面 标题="帖子详情" 引言=`鉴权补丁` 壳样式="off" 布局="stacked"*
*帖子页 = > 帖子页.头装配 表=`头`*
*帖子页 = > 帖子页.壳HTML 导航=`顶` 页脚=`底` 体类="page-post-detail"*
*帖子页 = > 帖子页.主体装配 主体=`帖子详情`*
*帖子页 = > 帖子页.查询条件 条件=`帖子条件`*
*帖子页 = > 帖子页.详情 详情=True*
*新闻页 = > 网页.页面 标题="新闻详情" 引言=`鉴权补丁` 壳样式="off" 布局="stacked"*
*新闻页 = > 新闻页.头装配 表=`头`*
*新闻页 = > 新闻页.壳HTML 导航=`顶` 页脚=`底` 体类="page-news-detail"*
*新闻页 = > 新闻页.主体装配 主体=`新闻详情`*
*新闻页 = > 新闻页.查询条件 条件=`新闻条件`*
*新闻页 = > 新闻页.详情 详情=True*
*发帖表 = > 网页.表单 表="posts" 动作="插入"*
*发帖表 = > 发帖表.字段 字段=`发帖字段`*
*发帖表 = > 发帖表.规则 规则=`发帖规则`*
*发帖引言 = > page.包装 正文="<section class=\"feed-list-page\"><div class=\"section-wrap\"><h1>发布帖子</h1><p>需登录(admin / anlian)</p></div></section>" 体类="page-post-public"*
*发帖页 = > 网页.页面 标题="发帖 · 暗恋见君" 引言=`发帖引言` 壳样式="off" 布局="bare"*
*发帖页 = > 发帖页.头装配 表=`头`*
*发帖页 = > 发帖页.表单装配 id="post" 表单=`发帖表`*
*房间行 = > store.查询 表="chat_rooms" 上限=50*
*房间段 = None*
- [房](房间行)
*名 = 房[^name]*
*链 = 房[^slug]*
*摘 = 房[^summary]*
*项 = "<article class=\"chat-room-card\"><h3><a href=\"/chat/" + 链 + "\">" + 名 + "</a></h3><p>" + 摘 + "</p></article>"*
*房间段 = > table.append list=房间段 item=项*
*房间内 = > text.str_join xs=房间段 sep=""*
*聊天列表体 = "<section class=\"feed-list-page\"><div class=\"section-wrap\"><h1>聊天室</h1><div class=\"chat-room-grid\">" + 房间内 + "</div></div></section>"*
*聊天列表文 = > page.包装 正文=`聊天列表体` 体类="page-chat"*
*聊天列表 = > 网页.页面 标题="聊天 · 暗恋见君" 引言=`聊天列表文` 壳样式="off" 布局="bare"*
*聊天列表 = > 聊天列表.头装配 表=`头`*
*大厅体 = "<section class=\"feed-list-page\"><div class=\"section-wrap\"><h1>大厅</h1><div class=\"chat-box\"><div id=\"chat-log\" class=\"chat-log\"></div><p class=\"search-bar\"><input id=\"chat-msg\" placeholder=\"说点什么…\" aria-label=\"消息\"><button id=\"chat-send\" type=\"button\">发送</button></p></div><script src=\"/static/chat.js\"></script></div></section>"*
*大厅文 = > page.包装 正文=`大厅体` 体类="page-chat-room"*
*大厅页 = > 网页.页面 标题="大厅 · 暗恋见君" 引言=`大厅文` 壳样式="off" 布局="bare"*
*大厅页 = > 大厅页.头装配 表=`头`*
*闲聊体 = "<section class=\"feed-list-page\"><div class=\"section-wrap\"><h1>闲聊</h1><div class=\"chat-box\"><div id=\"chat-log\" class=\"chat-log\"></div><p class=\"search-bar\"><input id=\"chat-msg\" placeholder=\"说点什么…\" aria-label=\"消息\"><button id=\"chat-send\" type=\"button\">发送</button></p></div><script src=\"/static/chat.js\"></script></div></section>"*
*闲聊文 = > page.包装 正文=`闲聊体` 体类="page-chat-room"*
*闲聊页 = > 网页.页面 标题="闲聊 · 暗恋见君" 引言=`闲聊文` 壳样式="off" 布局="bare"*
*闲聊页 = > 闲聊页.头装配 表=`头`*
*专题行 = > store.查询 表="topics" 上限=50*
*专题段 = None*
- [题](专题行)
*题名 = 题[^title]*
*链 = 题[^slug]*
*摘 = 题[^summary]*
*项 = "<article class=\"topic-card\"><h3>" + 题名 + "</h3><p>" + 摘 + "</p><p class=\"text-muted\">slug: " + 链 + "</p></article>"*
*专题段 = > table.append list=专题段 item=项*
*专题内 = > text.str_join xs=专题段 sep=""*
*专题体 = "<section class=\"feed-list-page\"><div class=\"section-wrap\"><h1>专题书架</h1><div class=\"topic-shelf\">" + 专题内 + "</div></div></section>"*
*专题文 = > page.包装 正文=`专题体` 体类="page-topics"*
*专题页 = > 网页.页面 标题="专题 · 暗恋见君" 引言=`专题文` 壳样式="off" 布局="bare"*
*专题页 = > 专题页.头装配 表=`头`*
*搜索体 = "<section class=\"feed-list-page\"><div class=\"section-wrap\"><h1>搜索</h1><form class=\"search-bar\" method=\"get\" action=\"/search\"><input name=\"q\" placeholder=\"关键词\" aria-label=\"关键词\"><button type=\"submit\">搜</button></form><p class=\"text-muted\">全文检索走 SQLite FTS(posts_fts);结果面板后续可按 q 扩展。</p></div></section>"*
*搜索文 = > page.包装 正文=`搜索体` 体类="page-search"*
*搜索页 = > 网页.页面 标题="搜索 · 暗恋见君" 引言=`搜索文` 壳样式="off" 布局="bare"*
*搜索页 = > 搜索页.头装配 表=`头`*
*指南体 = "<section class=\"feed-list-page\"><div class=\"section-wrap\"><h1>API 自动化指南</h1><p>使用 Bearer / X-Api-Key 调用自动化接口。本验收切片提供 <code>api_keys</code> 表与 <code>web_api_key_check</code> 原语;业务 scopes 写在 .mq.md。</p><pre>Authorization: Bearer &lt;token&gt;</pre></div></section>"*
*指南文 = > page.包装 正文=`指南体` 体类="page-guide"*
*指南页 = > 网页.页面 标题="API 指南 · 暗恋见君" 引言=`指南文` 壳样式="off" 布局="bare"*
*指南页 = > 指南页.头装配 表=`头`*
*应用 = > 网页.应用 页面=`首页` 数据库=`store` 后台=True 主机="127.0.0.1" 端口=18180*
*应用 = > 应用.路由 路径="/post" 页面=`帖子列表`*
*应用 = > 应用.路由 路径="/post/public" 页面=`发帖页`*
*应用 = > 应用.路由 路径="/post/{slug}" 页面=`帖子页`*
*应用 = > 应用.路由 路径="/news" 页面=`新闻列表`*
*应用 = > 应用.路由 路径="/news/{slug}" 页面=`新闻页`*
*应用 = > 应用.路由 路径="/chat" 页面=`聊天列表`*
*应用 = > 应用.路由 路径="/chat/lobby" 页面=`大厅页`*
*应用 = > 应用.路由 路径="/chat/casual" 页面=`闲聊页`*
*应用 = > 应用.路由 路径="/topics" 页面=`专题页`*
*应用 = > 应用.路由 路径="/search" 页面=`搜索页`*
*应用 = > 应用.路由 路径="/guide/automation-api" 页面=`指南页`*
*应用 = > 应用.静态 目录="public" 挂载="/static"*
*应用 = > 应用.图标 表=`图标`*
*应用 = > 应用.鉴权 用户表=`用户表` 会话时长=7200 登录路径="/accounts/login" 登录回跳="/post/public" 登出回跳="/"*
*应用 = > 应用.门禁 路径="/post/public" 角色="admin" 匹配="prefix" 拒绝="redirect" 排除="/accounts/login"*
*应用 = > 应用.路由实时 路径="/chat/ws" 模式="broadcast"*
*应用 = > 应用.调用 路径="/post/ten" 方法="GET" 函数="fragments.帖子十" 正文="query" 返回="html"*
*应用 = > 应用.调用 路径="/news/five" 方法="GET" 函数="fragments.新闻五" 正文="query" 返回="html"*
*应用 = > 应用.站点地图 路径="/sitemap.xml" 基址="http://127.0.0.1:18180" 条目=`地图项`*
*应用 = > 应用.爬虫协议 站点地图="http://127.0.0.1:18180/sitemap.xml"*
> `应用`.监听
+72
View File
@@ -0,0 +1,72 @@
---
title: anlian-mq offline smoke
description: 不 listen:装配库表/页面/门禁/WS 路由袋,验证可读路径可构造。
导入 网页:ext/web/网页.mq.md
import shell:styles/shell.mq.md
import nav:components/nav.mq.md
import foot:components/foot.mq.md
import db:db/index.mq.md
import sys:lib/sys.mq.md
---
# main
`壳` =
| 组件 | 样式 |
|------|------|
| nav.`导航` | |
| foot.`页脚` | |
`帖子卡片` =
| 属性 | 值 |
|------|-----|
| title | posts.title |
| body | posts.summary |
| href | posts.slug |
`用户表` =
| 行 | 用户名 | 密码 | 角色 |
|----|--------|------|------|
| 1 | admin | anlian | admin |
*store = > db.打开*
*壳CSS = > shell.全局*
*首页 = > 网页.页面 标题="暗恋见君" 引言="<h1>ok</h1>"*
*首页 = > 首页.组件装配 组件=`壳`*
*首页 = > 首页.主体装配 主体=`帖子卡片`*
*首页 = > 首页.样式 样式=`壳CSS`*
*应用 = > 网页.应用 页面=`首页` 数据库=`store` 后台=True 主机="127.0.0.1" 端口=18180*
*应用 = > 应用.鉴权 用户表=`用户表`*
*应用 = > 应用.门禁 路径="/write" 角色="admin" 匹配="prefix" 拒绝="redirect"*
*应用 = > 应用.路由实时 路径="/chat/ws" 模式="broadcast"*
*gates = 应用[^gates]*
*n = > len value=`gates`*
1. `n` >= 2
> print text=gates-ok
2. *
> print text=gates-fail
> sys.exit code=1
*ws = 应用[^ws_routes]*
*room = ws[^/chat/ws]*
*mode = room[^mode]*
1. `mode` == "broadcast"
> print text=ws-ok
2. *
> print text=ws-fail
> sys.exit code=1
*list = > store.查询 表="posts" 上限=10*
*nr = > len value=`list`*
1. `nr` >= 1
> print text=seed-ok
2. *
> print text=seed-fail
> sys.exit code=1
> print text=anlian-offline-ok
Binary file not shown.

After

Width:  |  Height:  |  Size: 76 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 45 KiB

+37
View File
@@ -0,0 +1,37 @@
/* 公聊客户端:保持极薄;业务配置仍在 .mq.md 表格里。 */
(function () {
var log = document.getElementById("chat-log");
var input = document.getElementById("chat-msg");
var send = document.getElementById("chat-send");
if (!log || !input || !send) return;
var proto = location.protocol === "https:" ? "wss:" : "ws:";
var ws = new WebSocket(proto + "//" + location.host + "/chat/ws");
function line(text) {
log.textContent += text + "\n";
log.scrollTop = log.scrollHeight;
}
ws.onopen = function () {
line("[已连接公聊室]");
};
ws.onclose = function () {
line("[连接关闭]");
};
ws.onmessage = function (ev) {
line(String(ev.data));
};
function publish() {
var t = (input.value || "").trim();
if (!t || ws.readyState !== 1) return;
ws.send(t);
input.value = "";
}
send.addEventListener("click", publish);
input.addEventListener("keydown", function (e) {
if (e.key === "Enter") publish();
});
})();
@@ -0,0 +1,454 @@
/**
* 暗恋见君 — 登录/注册/发帖/评论 共用表单样式(粉色毛玻璃主题)
*/
:root {
--anlian-accent: #fdbbdb;
--anlian-accent-deep: #f0a8c4;
--anlian-accent-text: #a85878;
--anlian-accent-muted: #c97a96;
--anlian-glass-bg: rgba(255, 255, 255, 0.38);
--anlian-glass-border: rgba(255, 255, 255, 0.52);
--anlian-text: #222;
--anlian-text-muted: #666;
--anlian-radius: 14px;
--anlian-radius-pill: 999px;
--anlian-transition: 0.2s ease;
}
/* ---------- 页面布局 ---------- */
.anlian-page {
display: flex;
flex-direction: column;
align-items: center;
width: 100%;
max-width: 520px;
margin: 0 auto;
padding: 1.5rem 1rem 2.5rem;
box-sizing: border-box;
}
.anlian-page-wide {
max-width: 800px;
}
.anlian-page-title {
margin: 0 0 1.25rem;
font-size: 1.75rem;
font-weight: 700;
color: var(--anlian-text);
text-align: center;
}
.anlian-page-lead {
margin: -0.5rem 0 1.25rem;
font-size: 0.9rem;
color: var(--anlian-text-muted);
text-align: center;
line-height: 1.5;
}
/* ---------- 表单卡片 ---------- */
.anlian-form-card {
width: 100%;
padding: 2rem 1.75rem;
border-radius: 24px;
background: var(--anlian-glass-bg);
backdrop-filter: blur(18px);
-webkit-backdrop-filter: blur(18px);
border: 1px solid var(--anlian-glass-border);
box-shadow: 0 12px 40px rgba(253, 189, 219, 0.15);
box-sizing: border-box;
}
.anlian-form-card .form-group,
.anlian-form-card .anlian-field {
margin-bottom: 1.25rem;
}
.anlian-form-card .anlian-field:last-child,
.anlian-form-card .form-group:last-of-type {
margin-bottom: 0;
}
/* ---------- 标签与输入框 ---------- */
.anlian-field-label,
.anlian-form-card label:not(.anlian-pill-label):not(.anlian-switch) {
display: block;
margin-bottom: 0.45rem;
font-size: 0.875rem;
font-weight: 600;
color: var(--anlian-accent-text);
}
.anlian-form-card input[type="text"],
.anlian-form-card input[type="email"],
.anlian-form-card input[type="password"],
.anlian-form-card input[type="search"],
.anlian-form-card input[type="number"],
.anlian-form-card input.anlian-input,
.anlian-form-card .form-control,
.anlian-form-card textarea,
.anlian-form-card select {
display: block;
width: 100%;
box-sizing: border-box;
padding: 0.7rem 0.95rem;
font-size: 1rem;
line-height: 1.4;
color: var(--anlian-text);
background: rgba(255, 255, 255, 0.55);
border: 1px solid rgba(253, 189, 219, 0.35);
border-radius: 12px;
transition: border-color var(--anlian-transition), box-shadow var(--anlian-transition),
background var(--anlian-transition);
}
.anlian-form-card input::placeholder,
.anlian-form-card textarea::placeholder {
color: #999;
}
.anlian-form-card input:focus,
.anlian-form-card textarea:focus,
.anlian-form-card select:focus {
outline: none;
border-color: var(--anlian-accent-deep);
background: rgba(255, 255, 255, 0.72);
box-shadow: 0 0 0 3px rgba(253, 189, 219, 0.28);
}
.anlian-form-card select {
cursor: pointer;
appearance: none;
background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='8' viewBox='0 0 12 8'%3E%3Cpath fill='%23a85878' d='M6 8 0 0h12z'/%3E%3C/svg%3E");
background-repeat: no-repeat;
background-position: right 0.95rem center;
padding-right: 2.25rem;
}
.anlian-form-card textarea {
min-height: 100px;
resize: vertical;
}
/* ---------- 记住我(自定义勾选,替代原生 checkbox) ---------- */
.anlian-field-remember {
margin-bottom: 1.25rem;
}
.anlian-switch {
display: inline-flex;
align-items: center;
gap: 0.65rem;
cursor: pointer;
user-select: none;
}
.anlian-switch-input {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border: 0;
}
.anlian-switch-box {
position: relative;
flex-shrink: 0;
width: 1.35rem;
height: 1.35rem;
border-radius: 8px;
background: rgba(255, 255, 255, 0.5);
border: 1px solid rgba(253, 189, 219, 0.5);
box-shadow: inset 0 1px 2px rgba(255, 255, 255, 0.4);
transition: background var(--anlian-transition), border-color var(--anlian-transition),
box-shadow var(--anlian-transition);
}
.anlian-switch-box::after {
content: '';
position: absolute;
left: 50%;
top: 45%;
width: 0.3rem;
height: 0.55rem;
margin-left: -0.2rem;
margin-top: -0.38rem;
border: solid #fff;
border-width: 0 2px 2px 0;
transform: rotate(45deg) scale(0);
opacity: 0;
transition: transform 0.15s ease, opacity 0.15s ease;
}
.anlian-switch-input:checked + .anlian-switch-box {
background: linear-gradient(135deg, rgba(253, 189, 219, 0.85), rgba(240, 168, 196, 0.9));
border-color: rgba(240, 168, 196, 0.85);
box-shadow: 0 2px 8px rgba(253, 189, 219, 0.35);
}
.anlian-switch-input:checked + .anlian-switch-box::after {
transform: rotate(45deg) scale(1);
opacity: 1;
}
.anlian-switch-input:focus-visible + .anlian-switch-box {
outline: none;
box-shadow: 0 0 0 3px rgba(253, 189, 219, 0.35);
}
.anlian-switch-text {
font-size: 0.875rem;
font-weight: 500;
color: var(--anlian-accent-text);
line-height: 1.3;
}
.anlian-switch:hover .anlian-switch-box {
border-color: var(--anlian-accent-deep);
background: rgba(255, 255, 255, 0.62);
}
.anlian-switch:hover .anlian-switch-input:checked + .anlian-switch-box {
background: linear-gradient(135deg, rgba(253, 189, 219, 0.95), rgba(240, 168, 196, 0.95));
}
/* ---------- 匿名:分段切换 ---------- */
.anlian-field-anon {
margin-top: 0.25rem;
}
.anlian-pill-toggle {
position: relative;
}
.anlian-pill-input {
position: absolute;
width: 1px;
height: 1px;
padding: 0;
margin: -1px;
overflow: hidden;
clip: rect(0, 0, 0, 0);
white-space: nowrap;
border: 0;
}
.anlian-pill-label {
position: relative;
display: grid;
grid-template-columns: 1fr 1fr;
align-items: center;
min-height: 2.5rem;
padding: 4px;
border-radius: var(--anlian-radius-pill);
background: rgba(255, 255, 255, 0.32);
border: 1px solid rgba(253, 189, 219, 0.45);
cursor: pointer;
user-select: none;
overflow: hidden;
}
.anlian-pill-thumb {
position: absolute;
top: 4px;
left: 4px;
width: calc(50% - 4px);
height: calc(100% - 8px);
border-radius: var(--anlian-radius-pill);
background: linear-gradient(135deg, rgba(253, 189, 219, 0.65), rgba(240, 168, 196, 0.75));
box-shadow: 0 2px 10px rgba(253, 189, 219, 0.25);
transition: transform 0.28s cubic-bezier(0.34, 1.2, 0.64, 1);
pointer-events: none;
}
.anlian-pill-input:checked + .anlian-pill-label .anlian-pill-thumb {
transform: translateX(100%);
}
.anlian-pill-option {
position: relative;
z-index: 1;
text-align: center;
font-size: 0.8125rem;
font-weight: 600;
color: var(--anlian-text-muted);
padding: 0.35rem 0.5rem;
transition: color var(--anlian-transition);
}
.anlian-pill-input:not(:checked) + .anlian-pill-label .anlian-pill-option:first-child,
.anlian-pill-input:checked + .anlian-pill-label .anlian-pill-option:last-child {
color: var(--anlian-accent-text);
}
.anlian-field-hint {
margin: 0.4rem 0 0;
font-size: 0.75rem;
color: var(--anlian-text-muted);
line-height: 1.4;
}
/* ---------- 验证码行 ---------- */
.anlian-code-row {
display: flex;
gap: 0.5rem;
align-items: stretch;
}
.anlian-code-row input {
flex: 1;
min-width: 0;
}
.anlian-btn-send-code {
flex-shrink: 0;
align-self: stretch;
padding: 0 1rem;
border: 1px solid rgba(253, 189, 219, 0.5);
border-radius: 12px;
background: rgba(253, 189, 219, 0.32);
color: var(--anlian-accent-text);
font-size: 0.8125rem;
font-weight: 600;
cursor: pointer;
white-space: nowrap;
transition: background var(--anlian-transition), transform var(--anlian-transition);
}
.anlian-btn-send-code:hover:not(:disabled) {
background: rgba(253, 189, 219, 0.48);
}
.anlian-btn-send-code:disabled {
opacity: 0.55;
cursor: not-allowed;
}
/* ---------- 主按钮 ---------- */
.anlian-btn-primary,
.anlian-form-card .anlian-btn-submit,
.anlian-form-card #login-btn,
.anlian-form-card #submit-btn,
.anlian-form-card #submit-comment-btn {
display: block;
width: 100%;
margin-top: 1.25rem;
padding: 0.75rem 1.25rem;
font-size: 1rem;
font-weight: 600;
color: var(--anlian-accent-text);
background: linear-gradient(135deg, rgba(253, 189, 219, 0.55), rgba(240, 168, 196, 0.65));
border: 1px solid rgba(240, 168, 196, 0.75);
border-radius: var(--anlian-radius-pill);
cursor: pointer;
transition: transform var(--anlian-transition), box-shadow var(--anlian-transition),
background var(--anlian-transition);
box-shadow: 0 4px 16px rgba(253, 189, 219, 0.22);
}
.anlian-btn-primary:hover,
.anlian-form-card .anlian-btn-submit:hover,
.anlian-form-card #login-btn:hover,
.anlian-form-card #submit-btn:hover,
.anlian-form-card #submit-comment-btn:hover {
background: linear-gradient(135deg, rgba(253, 189, 219, 0.68), rgba(240, 168, 196, 0.78));
box-shadow: 0 6px 22px rgba(253, 189, 219, 0.32);
transform: translateY(-1px);
}
/* ---------- 提示与链接 ---------- */
.anlian-alert {
padding: 0.85rem 1rem;
margin-bottom: 1rem;
border-radius: 12px;
font-size: 0.875rem;
line-height: 1.45;
}
.anlian-alert-danger {
background: rgba(220, 80, 100, 0.12);
border: 1px solid rgba(220, 80, 100, 0.28);
color: #9e3a4a;
}
.anlian-alert p {
margin: 0;
}
.anlian-field-error {
display: block;
margin-top: 0.35rem;
font-size: 0.8125rem;
color: #b33a4d;
}
.anlian-form-links {
display: flex;
justify-content: center;
gap: 1rem;
margin-top: 1.25rem;
flex-wrap: wrap;
}
.anlian-form-links a {
font-size: 0.875rem;
font-weight: 500;
color: var(--anlian-accent-text);
text-decoration: none;
}
.anlian-form-links a:hover {
text-decoration: underline;
}
/* ---------- 富文本编辑器 ---------- */
.anlian-editor-wrap {
border-radius: 12px;
overflow: hidden;
border: 1px solid rgba(253, 189, 219, 0.35);
background: rgba(255, 255, 255, 0.45);
}
.anlian-editor-wrap #editor {
min-height: 360px;
}
.anlian-editor-wrap .w-e-toolbar {
background: rgba(255, 255, 255, 0.65) !important;
border-bottom: 1px solid rgba(253, 189, 219, 0.3) !important;
}
.anlian-editor-wrap .w-e-text-container {
background: rgba(255, 255, 255, 0.35) !important;
}
/* ---------- 评论表单区块 ---------- */
.anlian-comment-form.anlian-form-card {
margin-bottom: 2rem;
}
@media (max-width: 576px) {
.anlian-form-card {
padding: 1.35rem 1.15rem;
border-radius: 18px;
}
.anlian-page-title {
font-size: 1.5rem;
}
.anlian-code-row {
flex-direction: column;
}
.anlian-btn-send-code {
width: 100%;
padding: 0.65rem;
}
}
+199
View File
@@ -0,0 +1,199 @@
/* API 自动化指南页 */
.api-guide-page {
max-width: 52rem;
align-items: stretch;
text-align: left;
padding-bottom: 3rem;
}
.api-guide-hero {
margin-bottom: 1.25rem;
}
.api-guide-hero .api-guide-title {
margin-top: 0;
text-align: left;
}
.api-guide-hero .anlian-page-lead {
margin-bottom: 0;
text-align: left;
max-width: none;
}
.api-guide-toc {
margin-bottom: 1.25rem;
}
.api-guide-toc-title {
margin: 0 0 0.65rem;
font-size: 0.875rem;
font-weight: 700;
color: var(--anlian-text-muted);
text-transform: uppercase;
letter-spacing: 0.04em;
}
.api-guide-toc ol {
margin: 0;
padding-left: 1.25rem;
line-height: 1.85;
}
.api-guide-toc a {
color: var(--anlian-accent-text);
text-decoration: none;
font-weight: 500;
}
.api-guide-toc a:hover {
text-decoration: underline;
}
.api-guide-section {
margin-bottom: 1.25rem;
}
.api-guide-section h2 {
margin: 0 0 0.85rem;
font-size: 1.25rem;
font-weight: 700;
color: var(--anlian-text);
border-bottom: 1px solid rgba(253, 189, 219, 0.45);
padding-bottom: 0.4rem;
}
.api-guide-section h3 {
margin: 1.1rem 0 0.5rem;
font-size: 1rem;
font-weight: 600;
color: var(--anlian-text);
}
.api-guide-section p,
.api-guide-section li {
font-size: 0.9375rem;
line-height: 1.65;
color: var(--anlian-text);
}
.api-guide-steps {
margin: 0 0 1rem;
padding-left: 1.35rem;
}
.api-guide-steps li {
margin-bottom: 0.35rem;
}
.api-guide-list {
margin: 0;
padding-left: 1.25rem;
}
.api-guide-list li {
margin-bottom: 0.4rem;
}
.api-guide-note {
margin: 0.75rem 0 0;
padding: 0.65rem 0.85rem;
font-size: 0.8125rem;
color: var(--anlian-text-muted);
background: rgba(255, 255, 255, 0.35);
border-radius: 10px;
border-left: 3px solid var(--anlian-accent);
}
.api-guide-warn {
margin: 0.75rem 0 0;
font-size: 0.875rem;
color: #a85858;
font-weight: 500;
}
.api-guide-code {
margin: 0.5rem 0 1rem;
padding: 0.85rem 1rem;
overflow-x: auto;
font-size: 0.8125rem;
line-height: 1.55;
background: rgba(30, 30, 40, 0.06);
border: 1px solid rgba(0, 0, 0, 0.06);
border-radius: 10px;
}
.api-guide-code code {
font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
color: #333;
white-space: pre;
}
.api-guide-table {
width: 100%;
margin: 0.75rem 0 1rem;
border-collapse: collapse;
font-size: 0.8125rem;
}
.api-guide-table th,
.api-guide-table td {
padding: 0.5rem 0.65rem;
border: 1px solid rgba(0, 0, 0, 0.08);
text-align: left;
vertical-align: top;
}
.api-guide-table th {
background: rgba(253, 189, 219, 0.2);
font-weight: 600;
}
.api-guide-table code {
font-size: 0.75rem;
word-break: break-all;
}
.api-guide-section a:not(.api-guide-btn) {
color: var(--anlian-accent-text);
font-weight: 500;
}
.api-guide-btn {
display: inline-block;
margin-top: 0.75rem;
padding: 0.45rem 1rem;
font-size: 0.875rem;
font-weight: 600;
color: #fff !important;
text-decoration: none !important;
background: var(--anlian-accent-text);
border-radius: var(--anlian-radius-pill);
}
.api-guide-btn:hover {
opacity: 0.9;
}
.api-guide-back {
margin: 0.5rem 0 0;
text-align: center;
font-size: 0.875rem;
}
.api-guide-back a {
color: var(--anlian-text-muted);
text-decoration: none;
}
.api-guide-back a:hover {
color: var(--anlian-accent-text);
text-decoration: underline;
}
@media (max-width: 575.98px) {
.api-guide-table {
display: block;
overflow-x: auto;
}
}
Loaded 100 of 457 files, more files were not shown because too many files have changed in this diff. Show more