Compare commits

...
126 Commits
Author SHA1 Message Date
cflmyandCursor 3eb8e732ea release: v1.0.1 — fix Go libweb dynamic-route query, Markdown, CSS false positives
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-15 14:48:47 +08:00
cflmyandCursor 761b92afce docs(public): keep narrative emphasis from executing as v0.3 code
Unbold code-shaped prose and give log.fields a map so pages and
`view output` stay green under markup v0.3.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 16:15:47 +08:00
cflmyandCursor b5f43ee993 release: v1.0.0 — markup v0.3 as the 1.0 language surface
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 16:05:29 +08:00
cflmyandCursor 76da97f090 ci(release): require Linux native+CLI zips; document proxy.cflmy.top
Pages was failing on leading-backtick narrative (already fixed on main).
Linux job now waits for the Windows release, then uploads .so plugins and a
Linux CLI bundle. Release skill treats those assets as mandatory.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 16:03:02 +08:00
cflmyandCursor 7554e45f60 feat(debug): dump v0.3 prose bits, inferred params, and dead binds
--dump-lines tags [decl]/[bold]/[italic]; --dump-ast prints `inferred` params
and `dead=[…]`. Migrate leftover italic-assign unit fixtures to bold/return.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 15:33:45 +08:00
cflmyandCursor 6994acb91d fix(prose): mid-line italic emphasis is not a return
Skip *very important* / *foo.bar* / *code-as-docs* so narrative emphasis cannot end a function; keep whole-line *n* and 返回*n*.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 15:25:26 +08:00
cflmyandCursor bccfec86ba feat(parse): bold infix expressions are ExprStmt, not calls
`` **n + 1** `` evaluates and discards (design §6.2); keep assign-first and
bare-call fallback. Explicit `` **> …** `` uses standalone bare=text rules.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 15:12:00 +08:00
cflmyandCursor 114fd53cd1 fix(prose): Decl names are identifiers; skip non-decl tick spans
Reject `` `n+1` `` as Decl, and when skipping non-decl `` `…` `` advance past the closing tick so inner `*` cannot open italic (fixes `` `OPENAI_*` `` in ext/ai/llm).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 14:50:01 +08:00
cflmyandCursor c8f41164c5 fix(parse): keep GAP recovery for unclosed bold
Hard-erroring code-shaped `` **… `` broke tests/structure/gap-star-json-body.mq.md; unclosed bold stays Comment so later statements still run.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 14:41:51 +08:00
cflmyandCursor 6f303ff957 fix(parse): diagnose unclosed code-shaped bold
Treat `` **x = 1 `` as Code and error with a clear unclosed-`**` diagnostic instead of silently skipping it as a comment.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 14:39:58 +08:00
cflmyandCursor 95a49697f7 fix(lex): glued ` name=default …prose ` is Decl, not assign
Trailing text after a glued default (same terminators as prose Decl) keeps the line narrative so `` `礼貌`=False 时… `` no longer binds a mangled text value.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 14:31:12 +08:00
cflmyandCursor 8846f5f070 fix(lex): treat leading backtick decl lines as narrative
Only `` `name` = … `` binds stay Code; lines like `` `捕获=True` 时… `` are Comment Decl prose so they no longer raise unrecognized statement.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 14:22:19 +08:00
cflmyandCursor 4f09e515ee feat(view): mark prose-inferred params in Structure
Show inferred function parameters with a dashed chip and outline annotation so view surfaces v0.3 param elevation without changing the redundant call surfaces.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 14:04:45 +08:00
cflmyandCursor 551f4ff322 feat(view): preserve bracket-marked calls without modifiers
Track CallExpr.bracket_marked from `[callee]` parse so Structure display keeps `[fn] …` instead of falling back to `> fn …` when there are no pre-modifiers.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 13:39:12 +08:00
cflmyandCursor d5a9301c7f docs(public): finish stdlib bracket-call demos and fix import returns
Prefer [lib.fn] in remaining public/stdlib samples, correct italic returns in structure import modules, and keep lib/系统 narration from starting with backticks.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 13:32:17 +08:00
cflmyandCursor 34915e3b16 docs: align remaining tutorial chapters with markup v0.3
Teach bold-as-code, italic-as-return, link-index, and bracket-marked calls across chapters 1–8/10–14 and Skill reference so teaching matches the runtime.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 13:18:28 +08:00
cflmyandCursor c55aad775e docs: teach link-index and v0.3 markers in tutorial and Skill
Rewrite chapter 9 and Skill examples around [key](coll), bracket-marked
calls, and ** code / * return; keep footnote get as a transitional note.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 13:08:53 +08:00
cflmyandCursor ac3f0633cd refactor(tests): prefer link-index in structure collection golds
Move collection-* structure fixtures to [key](base), and modernize
public/stdlib table/fs/time demos with bracket-marked library calls.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 13:03:03 +08:00
cflmyandCursor d55567a634 chore: stop tracking ephemeral tests/ext/:memory:
Remove the accidental sqlite artifact from the tree and ignore it.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 12:54:51 +08:00
cflmyandCursor abcb141737 refactor: prefer link-index get across examples and tests
Migrate remaining footnote-style collection access in examples,
public/structure, and ext/lib smokes to [key](base); teach link-index in
structure pages and use bracket calls in the cafe journal example.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 12:54:38 +08:00
cflmyandCursor 8d97adc1dc docs(ext): narrate quantum/linalg and link-index public features
Add module intros and missing purpose lines for EN/ZH quantum and linalg
extensions; migrate remaining public/features footnote gets to [key](base).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 12:45:57 +08:00
cflmyandCursor 5c37d54070 refactor(ext): prefer link-index get in web and ai modules
Migrate footnote-style collection access to [key](base) (including nested
chains) in ext/web and ext/ai EN/ZH sources.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 11:55:09 +08:00
cflmyandCursor fecaacd5be docs(lib): narrate remaining stdlib modules (M2)
Add module intros and per-function purpose lines across EN/ZH libs, with
callable examples on the smaller modules; keep + params and host bodies intact.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 11:47:35 +08:00
cflmyandCursor 53bc3538da docs(lib): narrate table/text/json as code-as-docs pilot
Add purpose lines and bracket-call examples in EN/ZH libs and public/stdlib
demos; keep explicit + params so function-body prose cannot be mistaken for
link-index or bold code.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 11:38:24 +08:00
cflmyandCursor 0e0655b316 feat(markup): bracket-marked calls with pre_modifiers
Stabilize `mod… [callee] args` (modifiers → name=True) alongside link-index
disambiguation; expand in interp/bytecode, show in view, and document lib/view
code-as-docs waves before stdlib rewrite.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 11:33:11 +08:00
cflmyandCursor 5058f5ddcf docs(examples): make code-as-docs read as a cafe journal
Drop syntax-teaching asides, rename the tip helper to 印章加一, and keep
return phrasing that the italic heuristic recognizes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 10:52:30 +08:00
cflmyandCursor 4a1c9c48a2 feat(markup): prefer [key](collection) for map and list access
Add GFM link-shaped index as the primary get surface, keep footnote
index as transitional compatibility, and align the coffee example.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 10:44:18 +08:00
cflmyandCursor 5e74ff39f2 feat(markup): code-as-docs narration surface (G1–G4) and drop --- body end
Treat --- as Markdown HR everywhere, end side-effect helpers with empty returns,
and accept soft emphasis, float literals, and dynamic footnote keys so LLM-friendly
.mq.md stays runnable. Ship the weekend coffee example plus gold fixtures.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-14 10:16:48 +08:00
cflmyandCursor b5c07385e9 feat(markup): finish v0.3 stock migration and green gold
Migrate remaining .mq.md (tests/ext/public/examples), stop elevating local assigns to params, inject form_target in Go libweb, and skip live LLM gold without a real key.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-13 23:43:44 +08:00
cflmyandCursor bfb10d172b feat(markup): adopt v0.3 as sole mapping (** code, * return)
Make prose-unified Markup the only runtime: bold segments are executable,
italic is return, params can be inferred from body/prose, with no v0.2 dual
mode. Migrate lib and structure/keywords golds; gate on tests/markup-v03.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-13 20:38:53 +08:00
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
cflmyandCursor 9d591674aa chore: sync Cargo.lock versions for v0.3.2
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 11:18:29 +08:00
cflmyandCursor e40d21760a release: v0.3.2 — browser WASM route C + release skill
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 11:18:13 +08:00
cflmyandCursor 2445c290c9 feat(wasm): finish route C — bridge package, smoke, site embed L1
Canonical marqdo-bridge.js ships with wasm build, Node ABI smoke covers
boot/call, and ext/web gains client_embed for head/static mounting.

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

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

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

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

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

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

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-01 09:59:03 +08:00
cflmyandCursor 416914a346 release: v0.3.1 — W8 favicon/head/images + entry_dir fix
Ship site icons, head asset tables, and image assembly; absolutize
entry_dir for relative entry scripts so sqlite paths no longer nest.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-29 11:47:22 +08:00
797 changed files with 68816 additions and 6704 deletions

No files matched your search

+152
View File
@@ -0,0 +1,152 @@
---
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.
6. **Calls in narrative:** prefer `**结果 = 某函数 名=`x`**` (no `>` on the RHS). Bracket form `礼貌 [问候] "x"` / `**出 = [put] …**` is fine when modifiers help. Use `> …` for standalone step lists. See `examples/code-as-docs/`.
7. **Do not use `##` inside `# main` for document sectioning** — those become nested functions. Use paragraphs / `---` breaks instead.
8. **Index:** prefer `[键](集合)` / `` [`名`](集合) `` over footnote `` m[^k] ``.
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/*`)
Canonical thin-template + waves: [lib-code-as-docs.md](../../doc/design/lib-code-as-docs.md) · [roadmap/lib-ext-code-as-docs.md](../../doc/roadmap/lib-ext-code-as-docs.md).
### 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`).
- Collection get: **`[key](coll)`** (no new footnote indexes). Calls in examples may use `修饰 [fn] …` or classic `>` / bold.
### Library checklist
- [ ] Purpose sentence + prose params + one example + short body
- [ ] Public examples use **tables + helpers**, not json glue
- [ ] Index with `[k](c)`; foreach `- [item](coll)`
- [ ] 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)
+184
View File
@@ -0,0 +1,184 @@
---
name: marqdo-release
description: >-
Run a full Marqdo product release: detect latest version and ask the user for
the next tag, update CHANGELOG/README/skills/public docs, bump Cargo versions,
sync VS Code extension on branch vscode-extension when needed, build or
trigger install assets (Windows CLI + **required Linux native/CLI zips**,
stdlib, ext, public zip, VSIX), push via origin or
https://proxy.cflmy.top/github.com/cflmy/marqdo.git, publish GitHub Release
with detailed notes, and recover from network failures via that proxy or HK
SSH jump (scripts/push-via-hk-jump.py). Use when the user asks to release,
cut a version, publish vX.Y.Z, ship a GitHub release, 发版, 发布新版本, or tag
marqdo.
---
# Marqdo release
Canonical release playbook for **cflmy/marqdo**. Read this skill **before** tagging or uploading assets. Details: [reference.md](reference.md).
## Hard rules
1. **Never invent the next version.** Detect current versions → **stop and ask the user** for the next SemVer (`X.Y.Z`). Do not proceed until they confirm.
2. **Never force-push** `main` / tags. **Never** `--no-verify` unless the user explicitly orders it.
3. **Never commit `vscode-extension/` on `main`** (gitignored). Extension source lives only on branch **`vscode-extension`**. See `doc/design/vscode-extension-commit.md`.
4. **Do not release from a dirty tree** (except intentional release commits you create in this flow).
5. **Tag format** is always `vX.Y.Z` matching root `Cargo.toml` `version = "X.Y.Z"`.
6. Prefer **tag push → GitHub Actions** (`.github/workflows/release.yml`) for **both** Windows and **Linux** install assets. Local packaging is fallback / verification.
7. After network errors: apply [reference.md § Proxy](reference.md). **First try** `https://proxy.cflmy.top/github.com/cflmy/marqdo.git` (this clone’s usual `origin`). Retry; do not silently skip uploads. If the reverse-proxy still drops long pushes, use **HK jump** (`hk.cflmy.de`) via `scripts/push-via-hk-jump.py` — see reference § **Proxy** / **HK SSH jump**.
8. **Do not ship a GitHub Release without the Linux extension/native zip.** Job `linux` must attach `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` (and the Linux CLI bundle). Missing Linux packages = release incomplete.
## Defaults (after version is confirmed)
Unless the user overrides, apply these automatically — **do not re-ask**:
| Setting | Default |
|---------|---------|
| Sync / bump `vscode-extension` to same `VER` | **yes** |
| Push `main`, create annotated tag, push tag immediately (trigger CI) | **yes** |
| Release notes language | **中英双语** (Chinese first, then English section, or paired ZH/EN under each heading) |
| Skip VSIX | **no** |
| Docs-only release | **no** (full asset pipeline via CI) |
| Deploy gh-pages after release | **no** (only if user asks) |
Phase 0 asks **only** for the next version (and optional overrides). Example ask:
> 当前最新是 **vA.B.C**。请指定下一个版本号(如 `0.3.2`)。其余按默认:同步扩展、立刻打 tag 发布、中英双语说明。
## Phase 0 — Detect versions (mandatory stop)
Run in repo root (parallel OK):
```bash
python3 .cursor/skills/marqdo-release/scripts/detect_version.py
# or: rg / git tag / gh release list — see reference.md
```
Report briefly, then **ask only for the next SemVer** (defaults above). Wait for confirmation. Normalize to `VER=X.Y.Z` and `TAG=vX.Y.Z`.
## Phase 1 — Preflight
Copy and track:
```
Release progress:
- [ ] Phase 0: version confirmed by user (TAG=…)
- [ ] Phase 1: preflight green
- [ ] Phase 2: docs + version bumps committed
- [ ] Phase 3: extension branch (if needed)
- [ ] Phase 4: main pushed; tag created & pushed
- [ ] Phase 5: CI / assets / release notes verified
- [ ] Phase 6: post-release checks
```
Checks:
1. `git status` clean or only release WIP you control.
2. `git checkout main && git pull --ff-only origin main`.
3. Quick gate: `cargo test --test gold structure_hello` (and any release-critical tests the user named). Full gold suite if time allows.
4. `CHANGELOG.md` has meaningful **Unreleased** notes; if empty, draft from `git log vLAST..HEAD --oneline` and confirm with user.
5. Confirm no secrets in the commit (`*.env`, credentials).
## Phase 2 — Docs & version bumps (main)
Bump **in lockstep**:
| File | Change |
|------|--------|
| `Cargo.toml` | `version = "VER"` |
| `crates/marqdo-wasm/Cargo.toml` | same `VER` |
| `CHANGELOG.md` | Move `## Unreleased` → `## vVER — YYYY-MM-DD`; leave fresh empty `## Unreleased` |
| `README.md` | 「现状 / 如何使用最新」version strings, checkout tag, release URL |
| `.cursor/skills/marqdo/SKILL.md` | Version-sensitive bullets if any (WASM/web status); keep rules accurate |
| `public/**` | User-facing tutorials if features shipped (welcome, features/*, extensions). Prefer small factual updates over rewrites |
| `doc/roadmap/*.md` | Mark shipped waves done if this release closes them |
| `.github/workflows/release.yml` | Update **Highlights** body template to this release (CI still uses hardcoded blurb—keep in sync) |
Public HTML: regenerate before packaging / pages deploy:
```bash
./scripts/build-public.sh
# outputs under public/ (gitignored HTML); used by release zip / gh-pages
```
Commit on `main` (HEREDOC message), e.g.:
```text
release: vVER — <one-line highlight>
EOF
```
Push `main` (this repo’s `origin` is usually the reverse proxy):
```bash
# origin typically: https://proxy.cflmy.top/github.com/cflmy/marqdo.git
git push origin main
# one-shot if origin still points at github.com:
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git HEAD:main
```
If that times out: [reference § HK SSH jump](reference.md).
## Phase 3 — VS Code / Cursor extension
**Default: always** bump extension to `VER` on branch `vscode-extension` (skip only if user said so).
1. `git fetch origin vscode-extension`
2. Work on `vscode-extension` branch (not main):
- Bump `vscode-extension/package.json` `version` to `VER`.
- Update `engines` / CLI version hints in extension README if present.
- `npm ci && npm run compile`
3. Commit & `git push origin vscode-extension`.
4. Return to `main`. **Do not** add `vscode-extension/` to main.
## Phase 4 — Tag & trigger CI
```bash
git tag -a "TAG" -m "TAG"
git push origin "TAG"
```
This runs `.github/workflows/release.yml`:
- **windows** — CLI exe/zip, stdlib zip, ext zip, source zip, public zip, VSIX, Windows native zip
- **linux** (`needs: windows`) — **required** Linux native plugins zip + Linux CLI bundle (`ext/` + `native/*.so`)
If tag push fails: [reference.md § Proxy](reference.md) (`proxy.cflmy.top` first), retry once; then HK jump.
## Phase 5 — Release notes & assets
1. Wait for Actions success: `gh run list --workflow=Release --limit 3` / open the run URL. **Both** `windows` and `linux` jobs must be green.
2. Ensure GitHub Release for `TAG` exists with assets (workflow uses `softprops/action-gh-release`).
3. Confirm Linux assets exist: `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` and `marqdo-VER-x86_64-unknown-linux-gnu.zip`. If missing, do **not** call the release done — re-run / upload.
4. **Rewrite release body** (workflow body is a stub) with **中英双语** — see [reference.md § Notes template](reference.md). `gh release edit TAG --notes-file …`.
4. Include: Highlights, Breaking, Install (`ext add`, plugins build), Downloads table, WASM (`marqdo wasm build`), links to CHANGELOG/README, extension branch note.
5. Optional Linux local extras (not required if CI green): `marqdo wasm build` smoke; document in notes that wasm is built from source via CLI.
Local Windows fallback: `scripts/release-full.ps1 -Tag TAG -Upload` (see script header).
## Phase 6 — Post-release
1. `gh release view TAG` — confirm assets + notes.
2. `git status` clean; `main` synced.
3. Tell user: release URL `https://github.com/cflmy/marqdo/releases/tag/TAG`.
4. Optional: `./scripts/deploy-public.ps1` / pages workflow if user wants user-site refresh.
5. Open fresh `## Unreleased` already done in Phase 2.
## Failure matrix (short)
| Failure | Action |
|---------|--------|
| `gh` / git TLS or Clash `7890` refused | Unset bad proxy; `required_permissions: ["all"]`; see [reference § Proxy](reference.md) |
| GitHub blocked | **`origin` via proxy.cflmy.top** (see below), then HK jump |
| Tag exists | Stop; ask user to bump or delete tag (no force on shared tags without explicit order) |
| CI red | Fix on main, move tag only if user explicitly allows delete+re-push tag |
| VSIX missing | Fetch `vscode-extension`, build locally, `gh release upload TAG dist/*.vsix` |
| Linux native/CLI zip missing | Incomplete release — fix `linux` job or `gh release upload`; do not skip |
## Do not
- Ship without user-confirmed version.
- Hardcode release highlights only in Actions YAML and forget CHANGELOG.
- Commit `target/`, `dist/`, `*.wasm`, or `public/**/*.html` unless project policy changes.
- Merge extension tree into `main`.
+379
View File
@@ -0,0 +1,379 @@
# Marqdo release — reference
Companion to [SKILL.md](SKILL.md). Use during a release; keep SKILL short.
## Detect versions (commands)
```bash
# From repo root
python3 .cursor/skills/marqdo-release/scripts/detect_version.py
# or manually:
git fetch --tags origin 2>/dev/null || true
echo "Cargo: $(sed -n 's/^version = \"\(.*\)\"/\1/p' Cargo.toml | head -1)"
echo "wasm: $(sed -n 's/^version = \"\(.*\)\"/\1/p' crates/marqdo-wasm/Cargo.toml | head -1)"
echo "tags: $(git tag -l 'v*' --sort=-v:refname | head -3 | tr '\n' ' ')"
gh release list --limit 3 2>/dev/null || true
```
**SemVer guidance for the ask (do not choose for the user):**
| Kind | When |
|------|------|
| patch `x.y.(z+1)` | Fixes, docs, no public API / MQ surface break |
| minor `x.(y+1).0` | New features (WASM route C, new ext APIs) backward compatible |
| major `(x+1).0.0` | Breaking MQ / CLI / plugin ABI |
## Asset matrix (CI tag `v*`)
Produced by `.github/workflows/release.yml` on **windows-latest** (`windows` job) and **ubuntu-latest** (`linux` job, **required**, `needs: windows`):
| Asset | Role | Job |
|-------|------|-----|
| `marqdo-VER-x86_64-pc-windows-msvc.exe` | CLI (stdlib embedded) | windows |
| `marqdo-VER-x86_64-pc-windows-msvc.zip` | `marqdo.exe` + `lib/` + `ext/` + native DLL | windows |
| `marqdo-VER-stdlib.zip` | `lib/` only | windows |
| `marqdo-VER-ext.zip` | Official `ext/` L1 | windows |
| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Prebuilt Windows plugins (`native/*.dll`) | windows |
| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Prebuilt Linux plugins (`native/lib*.so`) — **must ship** | linux |
| `marqdo-VER-x86_64-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + native `.so` — **must ship** | linux |
| `marqdo-VER-source.zip` | `git archive` of tagged commit | windows |
| `marqdo-VER.vsix` | VS Code / Cursor (from branch `vscode-extension`) | windows |
| `marqdo-VER-public.zip` | Static user docs (`marqdo view output public`) | windows |
Not CI-uploaded (document in notes): macOS build from source; WASM via `marqdo wasm build` → `dist/wasm/`.
A release **without** the Linux native zip is incomplete (`marqdo ext add` on Linux cannot download prebuilts).
## Doc sync checklist (Phase 2 detail)
### CHANGELOG.md
1. Ensure `## Unreleased` lists everything shipping.
2. Rename to `## vVER — YYYY-MM-DD` (use release day in Asia/Shanghai unless user says otherwise).
3. Add a short **Highlights** subsection (install snippet + 3–6 bullets).
4. Insert empty:
```markdown
## Unreleased
### Added
### Fixed
### Changed
```
### README.md
Update every user-visible version pin, typically:
- Section title `## 现状(vVER)`
- `### 如何使用最新 Marqdo(vVER)`
- `git checkout vVER`
- Release URL `…/releases/tag/vVER`
Keep install / `ext add` / plugin build instructions accurate for this release.
### `.cursor/skills/marqdo/SKILL.md`
- Sync hard rules / feature bullets that this release changes (e.g. WASM, web).
- Do **not** dump full CHANGELOG into the skill.
- If release-only process changed, point to `.cursor/skills/marqdo-release/`.
### `public/` (author Markdown sources)
User tutorials under `public/` (not generated HTML). Update when:
- New CLI (`marqdo wasm …`, `ext add`, `version`)
- New tutorials (browser hello, web client embed)
- Version badges / “requires vVER” lines
Then regenerate HTML for zip/pages:
```bash
./scripts/build-public.sh
# Windows: powershell -File ./scripts/build-public.ps1
```
HTML under `public/**/*.html` is typically gitignored — zip still ships from CI `marqdo view output public`.
### Workflow stub
Edit `.github/workflows/release.yml` `body:` **Highlights** so the first auto body matches this tag (agent still replaces with full notes via `gh release edit`).
### Roadmaps / ADRs
If this release closes a wave: set status Completed in `doc/roadmap/*`; leave ADRs immutable (link from CHANGELOG).
## Extension checklist (Phase 3 detail)
Branch policy: `doc/design/vscode-extension-commit.md`.
```bash
git fetch origin vscode-extension
git checkout vscode-extension
# edit vscode-extension/package.json version → VER
# npm ci && npm run compile
git add vscode-extension/
git commit -m "$(cat <<'EOF'
vscode-extension: bump to VER for release
EOF
)"
git push origin vscode-extension
git checkout main
```
Local VSIX only (fallback):
```bash
git fetch origin vscode-extension
git checkout origin/vscode-extension -- vscode-extension
(cd vscode-extension && npm ci && npm run compile && npx @vscode/vsce package --no-dependencies -o "../dist/marqdo-VER.vsix")
# cleanup ignored tree if desired
gh release upload "vVER" "dist/marqdo-VER.vsix" --clobber
```
## Defaults (mirror of SKILL)
| Setting | Default |
|---------|---------|
| Sync `vscode-extension` to `VER` | yes |
| Push main + annotated tag immediately | yes |
| Release notes | 中英双语 |
| Skip VSIX / docs-only / deploy pages | no |
Phase 0 asks **only** for the next version unless the user wants overrides.
## Notes template (中英双语 — default)
Save as `/tmp/marqdo-vVER-notes.md` then:
```bash
gh release edit "vVER" --notes-file /tmp/marqdo-vVER-notes.md
```
```markdown
## Marqdo vVER
### 亮点 / Highlights
- **中文** … / **EN** …
- …
### 安装 / Install
```bash
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout vVER
cargo build --release
./target/release/marqdo version
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
marqdo ext add web && marqdo ext add agent && marqdo ext add quantum
# 中文 id:网页 / 智能体 / 量子
```
**浏览器 WASM / Browser WASM**
```bash
marqdo wasm build
# → dist/wasm/marqdo_wasm_bg.wasm + marqdo-bridge.js
# examples: examples/browser-hello/
```
### 破坏性变更 / Breaking changes
- 无 / None
- …
### 下载 / Downloads
| Asset | 内容 / Contents |
|-------|-----------------|
| `marqdo-*-windows-msvc.exe` | CLI(内置 stdlib) |
| `marqdo-*-windows-msvc.zip` | exe + `lib/` + `ext/`(含 native) |
| `marqdo-*-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + `.so` |
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`(Win + **Linux 必出**) |
| `marqdo-*-stdlib.zip` | 仅 `lib/` |
| `marqdo-*-ext.zip` | 官方 `ext/` |
| `marqdo-*-source.zip` | 源码快照 |
| `marqdo-*.vsix` | VS Code / Cursor 扩展 |
| `marqdo-*-public.zip` | 用户文档站 |
扩展源码分支 / Extension branch: **`vscode-extension`** ([policy](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension-commit.md)).
### 链接 / Links
- [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md)
- [README](https://github.com/cflmy/marqdo/blob/main/README.md)
```
## Proxy & auth (network recovery)
Symptoms seen in this project: broken local Clash on `127.0.0.1:7890`, flaky GitHub TLS, `gh` needing token, Cursor agent sandbox with only `lo`.
### `proxy.cflmy.top` (try this first)
This machine’s `origin` is typically:
```
https://proxy.cflmy.top/github.com/cflmy/marqdo.git
```
Push / fetch / tag through that remote (HTTPS reverse proxy to GitHub):
```bash
git remote -v # confirm origin uses proxy.cflmy.top
git push origin main
git push origin vVER
git push origin vscode-extension
# one-shot if origin still points at github.com:
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git HEAD:main
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git vVER
```
Short GETs via the proxy often work; **long `git push` may still time out**. If push hangs or drops, skip Clash retries and go to **HK SSH jump** below.
`gh` against `api.github.com` may still need a direct path or HK jump (the reverse proxy is for `github.com` git, not always the API).
### Diagnose
```bash
env | grep -iE 'proxy|PROXY' || true
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
1. **Unset bad proxy** if connection refused:
```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):
```bash
export HTTPS_PROXY=http://HOST:PORT
export HTTP_PROXY=http://HOST:PORT
```
3. **Agent Shell**: retry `git push` / `gh` with `required_permissions: ["all"]` (and `full_network` if needed).
4. **`gh` auth**: if `gh auth status` fails, ask user to `gh auth login` or set `GH_TOKEN` / `GITHUB_TOKEN` for the session — **never commit tokens**. Fallback used in this repo: load password from `git credential fill` (`protocol=https` / `host=github.com`) into `GH_TOKEN` for the session only, then delete the temp env file.
5. **Git remote**: prefer `https://github.com/cflmy/marqdo.git`; SSH needs keys.
6. **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
```
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
```
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
powershell -File ./scripts/release-full.ps1 -Tag vVER -Upload
# -SkipVsix / -SkipPublic / -DeployPages as needed
```
Also: `scripts/release-windows.ps1`, `scripts/publish-release.py` if present.
## Commit message style
```text
release: vVER — <highlight>
```
Extension:
```text
vscode-extension: bump to VER for release
```
## Pre-tag test suggestions
Minimum:
```bash
cargo test --test gold structure_hello
./target/release/marqdo version # after cargo build --release
```
Stronger (time permitting):
```bash
cargo test --test gold
cargo test -p marqdo-wasm -- --nocapture # if wasm tests exist
# optional Node: node tests/wasm/smoke.mjs after marqdo wasm build
```
## Ask-user prompt (copy)
```text
版本探测结果:
- Cargo.toml: A.B.C
- crates/marqdo-wasm: …
- 最新 git tag: v…
- 最新 GitHub Release: v…
- CHANGELOG Unreleased: 有 / 无(摘要:…)
请指定下一个版本号(例如 0.3.2)。
默认(无需确认):同步 vscode-extension 同号、立刻 push tag 发版、发布说明中英双语。
若要改默认请一并说明。
```
+76
View File
@@ -0,0 +1,76 @@
#!/usr/bin/env python3
"""Detect Marqdo version sources for release Phase 0. Never invent next SemVer."""
from __future__ import annotations
import re
import subprocess
import sys
from pathlib import Path
# …/marqdo/.cursor/skills/marqdo-release/scripts/this.py → parents[4] = repo root
ROOT = Path(__file__).resolve().parents[4]
def cargo_version(path: Path) -> str | None:
if not path.is_file():
return None
m = re.search(r'^version\s*=\s*"([^"]+)"', path.read_text(encoding="utf-8"), re.M)
return m.group(1) if m else None
def run(cmd: list[str]) -> str:
try:
out = subprocess.check_output(cmd, cwd=ROOT, stderr=subprocess.DEVNULL, text=True)
return out.strip()
except (subprocess.CalledProcessError, FileNotFoundError):
return ""
def main() -> int:
cargo = cargo_version(ROOT / "Cargo.toml")
wasm = cargo_version(ROOT / "crates" / "marqdo-wasm" / "Cargo.toml")
tags = run(["git", "tag", "-l", "v*", "--sort=-v:refname"])
latest_tag = tags.splitlines()[0] if tags else "(none)"
gh_list = run(["gh", "release", "list", "--limit", "3"])
latest_gh = "(gh unavailable)"
if gh_list:
# first column is tag name for `gh release list`
latest_gh = gh_list.splitlines()[0].split("\t")[0].strip()
changelog = ROOT / "CHANGELOG.md"
unreleased = False
unreleased_preview = ""
if changelog.is_file():
text = changelog.read_text(encoding="utf-8")
m = re.search(r"^## Unreleased\s*\n(.*?)(?=^## |\Z)", text, re.M | re.S)
if m:
body = m.group(1).strip()
# nonempty if any bullet or non-heading content beyond empty section headers
content_lines = [
ln
for ln in body.splitlines()
if ln.strip() and not re.match(r"^###\s+", ln.strip())
]
unreleased = bool(content_lines)
unreleased_preview = " | ".join(content_lines[:3])[:200]
print("=== Marqdo version detect (do NOT invent next; ask the user) ===")
print(f"repo: {ROOT}")
print(f"Cargo.toml: {cargo or '(missing)'}")
print(f"marqdo-wasm: {wasm or '(missing)'}")
print(f"latest git tag: {latest_tag}")
print(f"latest gh release: {latest_gh}")
print(f"Unreleased notes: {'YES' if unreleased else 'NO/empty'}")
if unreleased_preview:
print(f"Unreleased peek: {unreleased_preview}")
if cargo and latest_tag.lstrip("v") != cargo:
print("WARN: Cargo version != latest tag (expected during pre-bump or lag)")
if cargo and wasm and cargo != wasm:
print("WARN: root Cargo.toml and marqdo-wasm versions differ — sync before release")
print()
print("ASK USER: next SemVer X.Y.Z (tag will be vX.Y.Z)")
return 0
if __name__ == "__main__":
sys.exit(main())
+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))
+79 -34
View File
@@ -4,31 +4,39 @@ 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
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
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).
Canonical design (repo): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-mapping-v0.3.md) (**v0.3 · runtime**), `doc/design/keywords.md`. Legacy v0.2 notes: `doc/design/markdown-mapping.md` (historical). Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number.
## Hard rules (do not violate)
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are **variables** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed.
8. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
2. **`**…**` = code** (assign / call). **`*…*` = return value**. Output is **not** either marker — use `> print text=…` / `**print text="…"**` / `> 打印 内容=…`.
3. **Prose:** unmarked narrative may contain `` `名` `` (declare/ref), inline `**code**`, and `*return*`. Soft Markdown emphasis that is **not** code-shaped (`**说明**`, mid-line `*only*`) is ignored — see [code-as-docs-gaps.md](../../doc/design/code-as-docs-gaps.md). Dead `` `名` `` (never read) is OK and does not become a param.
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**. Params: prefer prose `` `名` `` / `` `名`=默认 `` (inferred); `` + `名` `` still accepted.
5. **Identifiers:** `` `名` `` in prose; inside `*…*` / `**…**`, bare ids are **variables**. **Text literals must be quoted** in bold/italic: `**print text="hi"**`. Standalone `>` calls: bare words = text; vars need ticks: `` > str `n` ``.
6. **Structure lines** (`#` `>` `+` `-` `|` `1.`) need not be wrapped in bold.
7. **Paths:** In bare expressions `/` is division. In call args / defaults / table cells, unspaced `a/b` and quoted paths are text.
8. Prefer ending side-effect-only bodies with `*None*` / `*无*` / whole-line `**` / `****` when the next lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped everywhere), not function end.
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug.
12. **Bracket-marked calls:** Function name may be marked with `[函数名]`; bare words before `[` are boolean modifiers (`礼貌 [问候] x` → `礼貌=True`). `]` immediately followed by `(` is **index** `[key](coll)`, not a call. Prefer `[k](c)` over footnote index in new code. See [bracket-call-modifiers.md](../../doc/design/bracket-call-modifiers.md).
## Markup → meaning (v0.2)
## Markup → meaning (v0.3)
| Marker | Meaning |
|--------|---------|
@@ -39,15 +47,17 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
| Line `N. *` | Else arm |
| `> fn args` | Call (named `k=v` or positional) |
| `修饰 [fn] args` | Bracket-marked call; leading words → `名=True` |
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
| `****` or `**` + spaces + `**` | Return `None` and end function body |
| Lone `---` / `***` in function body | End function body (no value) |
| GFM table after empty RHS bind | Collection (1-col list / ≥2-col map / `@`·`行`·`row` → list of maps); `` `x`[^1] `` / `` `m`[^key] `` |
| `**…**` | **Code** (assign / call) — closing `**` touches last token; bare ids are variables; quote text literals |
| `*…*` | **Return value** — closing `*` touches last token; bare ids are variables |
| `****` / whole-line `**` / `*None*` | Return `None` and end function body |
| Lone `---` / `***` | Markdown thematic break (skip; not function end) |
| GFM table after empty RHS bind | Collection; get with `[key](coll)` (preferred) or legacy `` `m`[^key] `` |
| `- [item](coll)` | Foreach (unchanged) |
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
| Unmarked prose | Comment |
@@ -82,27 +92,28 @@ Chinese builtins (same functions, no import):
> print text=Hello, `who`!
---
*None*
```
- Call: `> name key=value` or `> name value`.
- Nested helpers use deeper `#` (`##`, `###`, …).
- After a helper with only side effects, end with `---` / `***`.
- After a helper with only side effects, end with `*None*` / whole-line `**` / `****` when later lines must stay in the outer function. Lone `---` is only a thematic break (skipped).
- In bold assigns, prefer bare calls: `**摘要 = 结账摘要 …**` (omit `>`).
## Statements, returns, branches
```markdown
*x = 1*
*y = x + 2*
**x = 1**
**y = x + 2**
## add_one
+ `n`
**n + 1**
*n + 1*
```
```markdown
*n = 0*
**n = 0**
1. `n` > 0
> print text=positive
@@ -125,22 +136,36 @@ import clock:lib/time.mq.md
# main
*xs = > text.split value="a,b,c" sep=","*
**xs = > text.str_split s="a,b,c" sep=","**
> print text=`xs`
*t = > clock.now_unix*
**t = > clock.now_unix**
```
- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages).
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (see `doc/design/ext-cli.md`). `ext/llm` — chat; `ext/agent` — document-driven agents: **step** (default writeback) / **plan** workbook ([ext-agent.md](../../doc/design/ext-agent.md), [ext-agent-plan.md](../../doc/design/ext-agent-plan.md)); **`ext/web`** — dynamic sites (W0–W7 + P3 complete; see below); **`ext/quantum`** — circuits + Q7 density/viz + Q8 themed SVG (see below).
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum|linalg` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below); **`ext/linalg`** — formula-first linear algebra (see below).
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`).
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
Stdlib map: [reference.md](reference.md).
## Official extension: `ext/agent` (document-driven)
Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --release -p marqdo_plugin_agent`.
**Constitution (do not dilute):**
1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag.
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only.
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import).
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
## Official extension: `ext/web` (dynamic sites)
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin first: `cargo build --release -p marqdo_plugin_web`.
@@ -154,7 +179,8 @@ 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.
- **`ext/**` never calls `host_*`** — hot path is native `plugins/web` ABI.
- **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 (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:**
@@ -164,17 +190,18 @@ index.mq.md # entry + home page table + listen
pages/ # sub-pages
components/ # reusable |属性|值|样式| tables
styles/ # CSS modules
public/ # static + favicon.ico|png|svg
db/ # schema + open/init
data/ # sqlite runtime (gitignore)
```
**Core objects (EN / ZH):** `# page`/`页面`, `# style`/`样式`, `# db`/`数据库`, `# form`/`表单`, `# app`/`应用`, `# auth`/`鉴权`, `# cache`/`缓存`, `# storage`/`存储`.
**Typical flow:** `db.init` → `page.compose_components` + `page.compose_main` → `page.render` → `app` with `route` / `static` / `configure` / `listen`.
**Typical flow:** `db.init` → `page.compose_*` → `app` + `static` / `listen`. Client: `marqdo wasm build -o static` + `web.client_embed source="/static/client.mq.md"` — **no author JS**; bridge may implement rich host effects ([browser-wasm-e.md](../../doc/roadmap/browser-wasm-e.md) · [browser-app](../../examples/browser-app/)).
**Shipped surface (W0–W7 + P3):** middleware + JSON API (`app.configure`); transactions, pagination, FTS search (`db.migrate`, `db.fts`, `db.search`); security (argon2, CSRF, SQLite sessions, login rate limit); SEO / RSS / Markdown (`page.meta`, `route_rss`, `lib/net.markdown_parse`); upload / download / gallery; sitemap / robots / error pages / redirects; RBAC (`app.gate`, user `role`); audit timestamps + FK in `db.init`; ETag on downloads.
**Shipped surface (W0–W7 + P3 + W8 + route D mount):** middleware + JSON API (`app.configure`); transactions, pagination, FTS search (`db.migrate`, `db.fts`, `db.search`); security (argon2, CSRF, SQLite sessions, login rate limit); SEO / RSS / Markdown (`page.meta`, `route_rss`, `lib/net.markdown_parse`); upload / download / gallery; sitemap / robots / error pages / redirects; RBAC (`app.gate`, user `role`); audit timestamps + FK in `db.init`; ETag on downloads; **W8** site icons (`app.icons` → `/favicon.ico`), head resource tables (`page.head`), image assembly (`make_images` / `page.images`); **D** `client_embed` auto-mount + DOM effect helpers (`text_patch` / `dom_patch`).
Design: [ext-web.md](../../doc/design/ext-web.md) · capability matrix: [web-net-capabilities.md](../../doc/design/web-net-capabilities.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
Design: [ext-web.md](../../doc/design/ext-web.md) · assets: [web-assets-and-images.md](../../doc/design/web-assets-and-images.md) · capability matrix: [web-net-capabilities.md](../../doc/design/web-net-capabilities.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/) · client: [examples/web-client-site/](../../examples/web-client-site/).
Web patterns: [examples.md](examples.md) §13 · API index: [reference.md](reference.md).
@@ -202,6 +229,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`).
@@ -220,14 +260,17 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
| `* > print text=hi *` | `> print text=hi` |
| `` *`a` = 1 * `` (trailing space + backticks) | `*a = 1*` — bare bind, no trailing space before `*` / `**` |
| `*xs = > text.split value=a,b sep=,*` (bare text args) | `*xs = > text.split value="a,b" sep=","*` — quote text literals; bare words are variables |
| Forgetting `---` after nested `##` helper | Add `---` / `***` / `****` |
| Forgetting empty return after nested `##` helper when outer continues | Add `*None*` / `**` / `****` (not `---`) |
| 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`) |
@@ -237,8 +280,10 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
- [ ] Print via `print` / `打印`, not bold
- [ ] Blank lines separate comment paragraphs from code
- [ ] `# main` exists when the file is an entry program
- [ ] Nested functions ended with `---` / `***` / `****` when needed
- [ ] Nested side-effect helpers ended with `*None*` / `**` / `****` when the outer function continues
- [ ] 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)
+163 -46
View File
@@ -1,5 +1,7 @@
# Marqdo examples (AI)
v0.3: `**…**` = code (assign / call); `*…*` = return. Prefer `[key](coll)` over footnote get. Bracket calls: `礼貌 [问候] x`.
## 1. Hello (English)
```markdown
@@ -16,7 +18,7 @@
> 打印 内容=你好,世界!
```
## 3. Function + named call + body end
## 3. Function + named call + empty return
```markdown
# main
@@ -30,22 +32,24 @@ Greeting via a nested function:
> print text=Hello, `who`!
---
*None*
```
Or end with a whole-line empty bold return: `**` / `****`. Lone `---` is a thematic break (skipped), not function end.
## 4. Bindings and return
```markdown
# main
*a = 2*
*b = > add_one n=`a`*
> print text=`b`
**a = 2**
**b = add_one n=`a`**
**打印 内容=`b`**
## add_one
+ `n`
**n + 1**
*n + 1*
```
## 5. Branch with else
@@ -53,7 +57,7 @@ Greeting via a nested function:
```markdown
# main
*n = 0*
**n = 0**
1. `n` > 0
> print text=positive
@@ -78,7 +82,7 @@ Greeting via a nested function:
> print text=`果`
```
## 6b. Map table + footnote get
## 6b. Map table + link-index get
```markdown
# main
@@ -89,13 +93,20 @@ Greeting via a nested function:
|------|------|
| 水果 | 蔬菜 |
*种 = 分类[^苹果]*
> print text=`种`
**种 = [苹果](分类)**
**打印 内容=`种`**
*第一 = 篮子[^1]*
`篮子` =
| 果 |
|----|
| 苹果 |
**第一 = [1](篮子)**
**打印 内容=`第一`**
```
One column → list; ≥2 columns + one data row → map; ≥2 columns + many rows → map of lists. Data cells are expressions (same as call-arg values): bare words, numbers, `` `var` ``, quoted strings; URLs and `gpt-4o-mini` stay text via path/hyphen folding. Footnotes: lists use 1-based digit indices; maps use key text (including digit keys like `[^00]`). Foreach on a map walks **keys**.
One column → list; ≥2 columns + one data row → map; ≥2 columns + many rows → map of lists. Prefer `[key](coll)` (lists are 1-based). Legacy `` coll[^key] `` still parses. Foreach on a map walks **keys**.
Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of maps (marker column excluded):
@@ -106,9 +117,51 @@ Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of ma
|----|------|------|
| 1 | 苹果 | 2 |
*名 = 订单[^1][^品名]*
**名 = [品名]([1](订单))**
```
## 6c. Bracket-marked call + modifiers
```markdown
# main
**打印 内容=(礼貌 [问候] "Marqdo")**
## 问候
+ `谁`
+ `礼貌`=False
**出 = `礼貌` + ", " + `谁` + "!"**
*出*
```
`礼貌 [问候] …` → `礼貌=True`. `]` immediately followed by `(` is index, not a call.
## 6d. 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
@@ -119,8 +172,41 @@ import text:lib/text.mq.md
# main
*parts = > split value=a,b,c sep=,*
> print text=`parts`
**parts = [text.str_split] s="a,b,c" sep=","**
**打印 内容=`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"**
**打印 内容=`ok`**
**打印 内容=`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]**
**打印 内容=`id`**
```
## 8. Comment paragraphs (blank-line rule)
@@ -129,7 +215,7 @@ import text:lib/text.mq.md
# main
This whole paragraph is a comment, including lines that look like code:
*not_executed = 1*
**not_executed = 1**
> print text=also still comment
After a blank line, code runs:
@@ -147,13 +233,13 @@ import math:lib/math.mq.md
# main
*t = > num value=3.5*
> print text=`t`
**t = > num value=3.5**
**打印 内容=`t`**
```
## 10. Object handle + method
See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` constructs a map with `_type`; methods use `` > `obj`.method `` and read `self` / `自`.
See `tests/structure/object-handle.mq.md` and `ext/ai/llm.mq.md`: `# Type` constructs a map with `_type`; methods use `` > `obj`.method `` and read `self` / `自`.
## 10b. Object inheritance
@@ -163,16 +249,16 @@ See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` construc
## hello
+ `who`
*msg = "Hello, `who`!"*
**msg**
**msg = "Hello, `who`!"**
*msg*
# Loud = > Greeter
## hello
+ `who`
*msg = "HELLO, `who`!"*
**msg**
**msg = "HELLO, `who`!"**
*msg*
```
`_type` stays the most specific name (`Loud`). Methods walk the base chain; same-name `##` on the child overrides. **No implicit super** — if the child needs parent fields, call the parent explicitly:
@@ -181,9 +267,9 @@ See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` construc
# Child = > Parent
+ `name`
*self = > Parent name=`name`*
*self = > json.set map=`self` key=extra value=1*
**self**
**self = > Parent name=`name`**
**self = [table.put] in=`self` at="extra" value=1**
*self*
```
## 11. Agent layout (ABI)
@@ -197,9 +283,9 @@ import agent:ext/agent.mq.md
> load_native
*ws = > agent*
*n = > `ws`.ensure_layout*
> print text=`n`
**ws = > agent**
**n = > `ws`.ensure_layout**
**打印 内容=`n`**
```
Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see `doc/design/ext-agent.md`).
@@ -207,14 +293,14 @@ Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see
## 12. What not to emit
```markdown
# BAD — bold is return, not print
# BAD — bare bold that is not code-shaped (decorative OK); do not use bold/italic as print
**Hello**
# BAD — Python control keywords
if x > 0:
print(x)
# BAD — wrapping a call in italics
# BAD — wrapping a call in italics as if it were a statement
*> print text=hi*
# BAD — old branch syntax (removed)
@@ -231,6 +317,10 @@ if x > 0:
> print text=y-pos
2. *
> print text=y-other
# GOOD — print / return
**打印 内容="hi"**
*n + 1*
```
## 13. Dynamic site (ext/web, minimal)
@@ -257,14 +347,14 @@ import db:db/index.mq.md
| title | posts.title | |
| body | posts.summary | |
*store = > db.open*
*css = "body{font-family:sans-serif}"*
*page = > web.page title="Hello"*
*page = > page.compose_components components=`shell`*
*page = > page.compose_main main=`main`*
*page = > page.css css=`css`*
*app = > web.app page=`page` port=8080*
*app = > app.static prefix="/static" dir="static"*
**store = > db.open**
**css = "body{font-family:sans-serif}"**
**page = > web.page title="Hello"**
**page = > page.compose_components components=`shell`**
**page = > page.compose_main main=`main`**
**page = > page.css css=`css`**
**app = > web.app page=`page` port=8080**
**app = > app.static prefix="/static" dir="static"**
> listen app=`app`
```
@@ -288,15 +378,42 @@ import quantum:ext/quantum/quantum.mq.md
| 1 | H | 0 |
| 2 | CX | 0,1 |
*qc = > quantum.circuit qubits=2 steps=`steps`*
*rho = > `qc`.density*
*red = > `rho`.partial_trace keep=0*
*sch = > `qc`.schmidt cut=1*
*_ = > `qc`.draw kind="circuit" theme="dark"*
*_ = > `qc`.draw kind="hinton"*
> print text=`red`
**qc = > quantum.circuit qubits=2 steps=`steps`**
**rho = > `qc`.density**
**red = > `rho`.partial_trace keep=0**
**sch = > `qc`.schmidt cut=1**
**_ = > `qc`.draw kind="circuit" theme="dark"**
**_ = > `qc`.draw kind="hinton"**
**打印 内容=`red`**
```
- Full lab: `examples/quantum-entanglement/`. Bell-only: `examples/quantum-bell/`.
- `theme="dark"|"light"|"bw"` (default dark) on `circuit` / `probs` / `bloch`. Quote `kind=` / `theme=`.
- After rebuilding the plugin: `marqdo ext add quantum` so view loads the new native lib.
## 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`**
```
Prefer:
```markdown
**`env` = > la.declare table=`shapes`**
**`P` = [A](env) * [B](env)**
**`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/`.
+30 -6
View File
@@ -12,13 +12,13 @@ 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).
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * `` (same-indent restart at `1.` = **new** branch statement); loops `` - [item](coll) `` or `` - [`item`](`coll`) ``; identifiers in backticks (foreach header may omit ticks). See `doc/design/markdown-mapping.md`.
**v0.3 surface:** `**…**` = code; `*…*` = return; parameters `` + `name` `` (or prose-inferred); branches `` 1. `cond` `` / `` 2. * `` (same-indent restart at `1.` = **new** branch statement); loops `` - [item](coll) ``; get `` [key](coll) ``; bracket calls `` mod [fn] args ``. See `doc/design/markdown-mapping-v0.3.md`.
Stdlib search order for `lib/…` imports: `MARQDO_LIB`, `./lib`, directory of the `marqdo` executable (and a few parents). Prefer the **bundle zip** (`marqdo.exe` + `lib/`) over a bare exe.
@@ -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
@@ -162,7 +183,8 @@ See `doc/design/call-arguments.md`.
| Doc | Topic |
|-----|--------|
| `doc/design/markdown-mapping.md` | Syntax constitution |
| `doc/design/markdown-mapping-v0.3.md` | Syntax constitution (runtime) |
| `doc/design/markdown-mapping.md` | Legacy v0.2 notes |
| `doc/design/objects.md` | `#` objects / `##` methods |
| `doc/design/keywords.md` | Builtins / keywords |
| `doc/design/return-hr-and-code-surface.md` | Function end / surfaces |
@@ -177,4 +199,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=
+109 -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,23 @@ jobs:
body: |
## Marqdo ${{ github.ref_name }}
### Highlights — v0.3
- **`ext/web`**: W0–W7 + P3 complete (sessions, cache, upload, WebSocket, style assembly); see marqdo-blog
- **`ext/quantum`**: Q7 linalg + Q8 themed SVG viz
- **`ext/agent`**: A1–A4 (OKF reuse, events, context budget, RAG/MCP fixtures)
- Install: `marqdo ext list` / `marqdo ext add llm|agent|web|quantum`
- Native plugins: `cargo build --release -p marqdo_plugin_*` then `ext add`
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [README](https://github.com/cflmy/marqdo/blob/main/README.md)
Also: embedded stdlib, writeback/subtask, Variables modal in `view`, VSIX from branch **`vscode-extension`**.
### 亮点 / Highlights
- **v1.0.1**:修复 Go `libweb` 动态路由 `{param}` 查询代入、详情 Markdown、CSS 数字误报、`/static/` ServeMux 冲突
- **v1.0.1**: fix Go `libweb` dynamic-route `{param}` query resolve, article Markdown, CSS numeric false positives, `/static/` ServeMux conflict
- **v1.0.0**:Markdown 语法映射 v0.3 为唯一运行时(`**` 代码 / `*` 返回 / 叙述 `` `名` ``)
- **Linux 包必出**:`*-native-x86_64-unknown-linux-gnu.zip` + Linux CLI bundle
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [mapping v0.3](https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping-v0.3.md)
### 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`/`linalg`(Windows DLL + **Linux .so 必出**) |
| `marqdo-*-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + native `.so` |
| `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 +150,75 @@ 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:
runs-on: ubuntu-latest
# Wait until Windows has created the GitHub Release, then attach Linux zips
# (required: native plugins for `marqdo ext add` on Linux + CLI bundle).
needs: windows
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: Install zip + cgo toolchain
run: sudo apt-get update && sudo apt-get install -y zip gcc libc6-dev
- name: Build Linux CLI + official plugins
run: |
set -euo pipefail
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: Package Linux native zip + CLI bundle
run: |
set -euo pipefail
VER="${GITHUB_REF_NAME#v}"
TARGET="x86_64-unknown-linux-gnu"
mkdir -p dist/stage-native/native
for lib in libweb.so libagent.so libquantum.so liblinalg.so; do
src="target/release/${lib}"
if [[ ! -f "$src" && "$lib" == libweb.so ]]; then
src="plugins/web/build/libweb.so"
fi
test -f "$src" || { echo "missing $src" >&2; exit 1; }
cp "$src" "dist/stage-native/native/${lib}"
done
(cd dist/stage-native && zip -r "../marqdo-${VER}-native-${TARGET}.zip" .)
echo "NATIVE=marqdo-${VER}-native-${TARGET}.zip" >> "$GITHUB_ENV"
stage="dist/stage-linux"
rm -rf "$stage"
mkdir -p "$stage/ext/native" "$stage/lib"
cp target/release/marqdo "$stage/marqdo"
chmod +x "$stage/marqdo"
cp -a lib/. "$stage/lib/"
cp -a ext/. "$stage/ext/"
cp dist/stage-native/native/*.so "$stage/ext/native/"
linux_zip="marqdo-${VER}-${TARGET}.zip"
(cd "$stage" && zip -r "../${linux_zip}" .)
echo "LINUX_ZIP=${linux_zip}" >> "$GITHUB_ENV"
- name: Upload Linux packages
uses: softprops/action-gh-release@v2
with:
files: |
dist/${{ env.NATIVE }}
dist/${{ env.LINUX_ZIP }}
fail_on_unmatched_files: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+19
View File
@@ -23,6 +23,7 @@
.DS_Store
.marqdo/
**/.marqdo/
.marqdo-ext/
.env
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
@@ -39,6 +40,13 @@ spike/.pytest_cache/
**/__pycache__/
*.pyc
# Built browser WASM (rebuild via crates/marqdo-wasm README)
/examples/browser-hello/marqdo_wasm.wasm
/examples/browser-hello/pkg/
/examples/web-client-site/static/marqdo_wasm.wasm
/examples/browser-app/marqdo_wasm.wasm
/examples/browser-media/marqdo_wasm.wasm
# Local sqlite / scratch
/data/
/tmp/
@@ -52,11 +60,22 @@ 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/
# ephemeral sqlite / test artifacts
tests/ext/:memory:
+303
View File
@@ -2,6 +2,309 @@
## Unreleased
### Added
### Fixed
### Changed
## v1.0.1 — 2026-09-15
### Highlights
**ext/web(Go libweb)回归修复**:动态路由查询条件恢复 `{param}` 代入;详情 SSR + Markdown;样式表数字不再误报。
```bash
git checkout v1.0.1
cargo build --release
bash ./scripts/build-web-plugin.sh
# 或:解压 Release 的 marqdo-1.0.1-*-native-*.zip / Linux CLI zip
marqdo run examples/marqdo-blog/index.mq.md
```
### Added
- Go web plugin:详情页正文 Markdown(goldmark GFM),对齐 Rust `pulldown-cmark` 路径。
### Fixed
- **动态路由 `{param}` 未代入查询条件**(`ext/web` Go):`selectPageData` 递归展开 `query` 全部字符串叶子;`data-slot-src` / `_route` 同步替换。`examples/marqdo-blog` `/post/{slug}` 详情 SSR 恢复。
- **样式表数字单元格误报「可疑 `/` 除法」**:`cssValueSuspicious` 不再把合法 `z-index`/`opacity` 等 number 当警告。
- Go 1.22+ ServeMux:`/static/` 与 `/static/favicon.svg` 的 GET/HEAD 注册冲突导致博客启动 panic。
- Rust archive 同步:`resolve_placeholders` 递归 + CSS number 误报收窄(非默认构建路径)。
## v1.0.0 — 2026-09-14
### Highlights
**Markdown 语法映射 v0.3 成为 1.0 宪法**:`**粗体**` = 代码,`*斜体*` = 返回,叙述里的 `` `名` `` 声明并推断形参。这是相对 v0.4 / 旧 `*语句*`/`**返回**` 的破坏性对调。Linux 预编译拓展包与 CLI bundle 为 Release 必出资产。
```bash
git checkout v1.0.0
cargo build --release
# Linux:也可直接解压 Release 的 marqdo-1.0.0-x86_64-unknown-linux-gnu.zip
marqdo run tests/markup-v03/inc-prose.mq.md
```
### Added
- **Markup v0.3 运行时闭环**:粗体=`代码`、斜体=`返回`、叙述 `` `名` `` 声明与形参推断为唯一映射;金样 `tests/markup-v03/`。
- **方括号标记调用**与前置修饰语:`礼貌 [问候] x`;取元主语法 `[键](集合)`(脚注取元过渡保留)。
- **代码即文档叙述面 G1–G4**:模块级 `---` 跳过、装饰性强调、浮点面量、动态键。
- **粗体表达式语句** `**n + 1**`;`--dump-lines` 标注 `[decl]/[bold]/[italic]`;`--dump-ast` 显示 inferred 形参与死绑定。
- **Release Linux 包必出**:`linux` job 上传 `*-native-x86_64-unknown-linux-gnu.zip` 与 Linux CLI bundle。
### Fixed
- 行首 `` `名`… `` 叙述不再当语句(修复 pages CI:`public/features/16-fs-mid2.mq.md`)。
- 句中斜体强调(`*very important*` / `*foo.bar*`)不再误收束函数;Decl 名须为标识符;残缺粗体保持 GAP 恢复。
- 胶合 `` `名`=default …prose `` 为 Decl 而非赋值。
### Changed
- 教程 / Skill / `lib` / `ext` / `public` 对齐 v0.3 标记;view 推断形参 `chip inferred`。
## 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
**浏览器 Marqdo(路线 C)首版完备**:`wasm-core`、`marqdo wasm build`、会话 ABI、DOM/`fetch`/`after` 效应、官方 bridge、体积与冒烟;并修 Admin 长内容布局、`ext add` 原生插件预检、`@keyframes` 与样式表 `/` 比率约定。
```bash
git checkout v0.3.2
cargo build --release
marqdo wasm build
marqdo ext add web # 改插件后请重新 add
```
### Added
- **浏览器 Marqdo(路线 C)**: [ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [design](doc/design/browser-marqdo-wasm.md) · [roadmap C0–C5](doc/roadmap/browser-wasm.md)。
- **C0/C1**:`wasm-core` feature 门控;`run_source`;crate `crates/marqdo-wasm`(`mq_run` ABI);示例 [examples/browser-hello](examples/browser-hello/)。
- **C2/C3**:`marqdo wasm build`;会话 `mq_boot`/`mq_call`;GFM wire 表 + `set_text` DOM 回写;[interact.html](examples/browser-hello/interact.html) 计数器示例。
- **C4**:[ADR 0003](doc/adr/0003-browser-async-effects.md) 效应表(`fetch` / `after`)+ bridge 续体;[fetch.html](examples/browser-hello/fetch.html)。
- **C5**:`release-wasm` 体积配置;`marqdo wasm build` 报告 KiB 并可选 `wasm-opt`;`run_source` bytecode 单测;会话仍为 tree。
- **WASM 收口**:规范 `crates/marqdo-wasm/js/marqdo-bridge.js`;`wasm build` 同时拷贝 bridge;Node 冒烟 `tests/wasm`;`web.client_embed` / `网页.客户端挂载`;路线图标 Completed。
- **发版 Skill**:`.cursor/skills/marqdo-release/`(探测版本 → 用户确认 → 文档/资产/扩展/Release 说明)。
### Fixed
- **Admin UI**:主区取消 `max-width:56rem` 限制,表格外包可横向滚动的 `.table-wrap`,单元格完整展示并自动换行;表单加宽且 textarea 可随内容增高。
- **`marqdo ext add`**:安装含原生插件的扩展时**先**定位/自动 `cargo build` 再拷贝 `.mq.md`,避免只装上文稿、运行时报 `native plugin not found`;扩大 `.so` 搜索路径。
- **`web_style` / 样式装配**:正确输出 `@keyframes` 块(停点为嵌套规则,不再写成 `0%: opacity: 0`)。
- **样式表含 `/` 的值**:文档明确**引号优先**(`"16/9"`、`"1/5"`);不引入靠空格消歧的表单元格比率折叠。
## v0.3.1 — 2026-08-29
### Highlights
**W8 站点资源**:favicon / Head 资源表 / 图片装配一次补齐;并修复相对入口路径下 `entry_dir` 双重拼接导致的嵌套目录问题。
```bash
git checkout v0.3.1
cargo build --release
marqdo ext add web # 改插件后请重新 add
```
### Added
- **`ext/web` W8(站点图标 / Head / 图片装配)** ([web-assets-and-images.md](doc/design/web-assets-and-images.md)):`app.icons` / `应用.图标` 挂 `GET /favicon.ico`;`page.head` / `头装配`;`make_images` / `图片装配`;`meta` 认 `icon`/`favicon`/`apple-touch-icon`;`static` 约定 `favicon.*`;金样 `web-assets-smoke` / `web-assets-live`;[marqdo-blog](examples/marqdo-blog/) 接入。
### Fixed
- **`host_query("entry_dir")`**:相对入口脚本(如 `tests/ext/….mq.md`)时对进程 cwd 绝对化,避免与 `for_run` 已设的脚本目录 cwd 再次拼接成 `tests/ext/tests/ext/…`。
## v0.3.0 — 2026-08-29
### Highlights
Generated
+68 -1114
View File
File diff suppressed because it is too large. Load diff
+52 -9
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "0.3.0"
version = "1.0.1"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -10,25 +10,59 @@ repository = "https://github.com/cflmy/marqdo"
[[bin]]
name = "marqdo"
path = "src/main.rs"
required-features = ["cli"]
[features]
default = ["native"]
native = ["cli", "view", "net-host", "plugin-host", "exec-host", "fs-host", "tty"]
cli = ["dep:clap"]
view = ["dep:tiny_http"]
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize", "dep:zip"]
plugin-host = ["dep:libloading"]
exec-host = []
fs-host = []
tty = ["dep:libc"]
wasm-core = []
[dependencies]
anyhow = "1"
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
clap = { version = "=4.4.18", features = ["derive"] }
clap = { version = "=4.4.18", features = ["derive"], optional = true }
pulldown-cmark = "0.12"
serde_json = "1"
thiserror = "1"
tiny_http = "0.12"
tiny_http = { version = "0.12", optional = true }
sha2 = { version = "=0.10.9", default-features = false }
sha1 = { version = "=0.10.6", default-features = false }
md-5 = { version = "=0.10.6", default-features = false }
hmac = { version = "=0.12.1", default-features = false }
getrandom = { version = "=0.2.17", default-features = false, features = ["std"] }
# Mid M1: Unicode regex for lib/re (no backrefs; RE2-like).
regex = { version = "=1.13.1", default-features = false, features = ["std", "unicode"] }
# Pin for Cargo/rustc 1.81 (newer rustls/idna/zeroize need edition2024).
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"] }
idna_adapter = "=1.1.0"
zeroize = "=1.8.1"
libloading = "=0.8.6"
ureq = { version = "=2.9.7", default-features = false, features = ["tls", "gzip"], optional = true }
idna_adapter = { version = "=1.1.0", optional = true }
zeroize = { version = "=1.8.1", optional = true }
# Extract GitHub Release ext/native zips (`marqdo ext add` without local Rust).
zip = { version = "=0.6.6", default-features = false, features = ["deflate"], optional = true }
libloading = { version = "=0.8.6", optional = true }
include_dir = "0.7"
libc = "0.2"
libc = { version = "0.2", optional = true }
[target.'cfg(target_arch = "wasm32")'.dependencies]
# No `wasmbind`: keeps cdylib free of wasm-bindgen imports (raw mq_* ABI).
chrono = { version = "0.4", default-features = false, features = ["alloc", "std"] }
[workspace]
members = ["plugins/demo", "plugins/agent", "plugins/web", "plugins/quantum"]
members = [
"plugins/demo",
"plugins/agent",
"plugins/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]
@@ -37,3 +71,12 @@ predicates = "=3.1.0"
tokio = { version = "1", features = ["rt-multi-thread", "macros", "time", "net"] }
tokio-tungstenite = "0.24"
futures-util = "0.3"
# Size-oriented profile for `marqdo-wasm` (C5). Use: cargo build -p marqdo-wasm --profile release-wasm --target wasm32-unknown-unknown
[profile.release-wasm]
inherits = "release"
lto = true
codegen-units = 1
opt-level = "z"
strip = true
panic = "abort"
+41 -32
View File
@@ -23,23 +23,23 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
---
## 语法速览(v0.2)
## 语法速览(v0.3)
| 标记 | 含义 |
|------|------|
| 无标记行 | 注释(空行分段) |
| `*…*` | 程序语句 |
| `**…**` | **返回值**(架构) |
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
| 无标记行 | 叙述(注释);行内 `` `名` `` 可声明 |
| `**…**` | **代码**(赋值 / 调用 / 表达式) |
| `*…*` | **返回值**(整行、`返回*n*`、或表达式形) |
| `****` / 整行 `**` / `*None*` | **空返回**(`None`),并结束本函数体 |
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
| `##` … | 函数 / 方法(按标题深度嵌套) |
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
| `+` / `1.` … | 函数头下 `` + `名` `` = 形参;体内 `1.` `2.` … = 分支(`N. *` = else) |
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) `` / `` - [`项`](`集合`) ``) |
| 表格 | 集合 |
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
| 叙述 `` `名` `` / `` `名`=默认 `` | 形参由体推断(`` + `名` `` 仍可用) |
| `1.` … | 体内 `1.` `2.` … = 分支(`N. *` = else) |
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) ``) |
| 表格 | 集合;取元优先 `[键](集合)` |
| 单独一行 `---` / `***` | **叙述分隔**(跳过;不是函数收束) |
```markdown
# main
@@ -47,19 +47,18 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
> 问候 谁=World
## 问候
+ `谁`
> print text=Hello `谁`!
向`谁`问好。
---
**print text="Hello " + 谁**
*None*
## 加一
+ `n`
**`n` + 1**
对于输入变量`n`,执行**n=n+1**接着返回*n*。
```
完整约定:[markdown-mapping.md](doc/design/markdown-mapping.md)。
完整约定:[markdown-mapping-v0.3.md](doc/design/markdown-mapping-v0.3.md)。
---
@@ -99,32 +98,34 @@ marqdo catalog public -o .marqdo
---
## 现状(v0.3.0)
## 现状(v1.0.1)
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
- 映射与解释器:**v0.3 语法宪法**(`**` 代码 / `*` 返回 / 叙述声明);Phase I 树遍历 + 字节码后端;金样例在 `tests/` 与 `tests/markup-v03/`
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
- **`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 完结(会话 / 缓存 / 上传 / WebSocket / 样式装配等);示例 [marqdo-blog](examples/marqdo-blog/);生产路径见 [web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)(反向代理 → 嵌入式 `listen`,非 Daphne/Uvicorn)
- **`web`**:W0–W7 + P3 + **W8**;**定制 C0–C4**;**宿主 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`
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
### 如何使用最新 Marqdo(v0.3.0)
### 如何使用最新 Marqdo(v1.0.1)
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v0.3.0 # 或留在 main
git checkout v1.0.1 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -137,19 +138,27 @@ 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
# 浏览器打开终端打印的 listen 地址
marqdo run examples/anlian-mq/index.mq.md # W-G14 验收站
# 浏览器打开终端打印的 listen 地址;/favicon.ico 与 logo 装配见 W8
# 5) Windows:也可从 GitHub Releases 下载 exe / zip / vsix
# https://github.com/cflmy/marqdo/releases/tag/v0.3.0
# 5) 浏览器 WASM(可选)
marqdo wasm build
# → dist/wasm/ … 见 examples/browser-hello/
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
# https://github.com/cflmy/marqdo/releases/tag/v1.0.1
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+15
View File
@@ -0,0 +1,15 @@
[package]
name = "marqdo-wasm"
version = "1.0.1"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
repository = "https://github.com/cflmy/marqdo"
publish = false
[lib]
crate-type = ["cdylib", "rlib"]
[dependencies]
marqdo = { path = "../..", default-features = false, features = ["wasm-core"] }
serde_json = "1"
+21
View File
@@ -0,0 +1,21 @@
# Marqdo browser WASM (route C)
Raw `cdylib` exports — no `wasm-bindgen` CLI required.
| Export | Role |
|--------|------|
| `mq_alloc` / `mq_dealloc` | linear memory |
| `mq_run` | one-shot `# main` (C1) |
| `mq_boot` / `mq_call` | session + handlers (C3) |
| `mq_version` | version C string |
```bash
# from repo root (C5 size profile)
marqdo wasm build -o examples/browser-hello
# or:
cargo build -p marqdo-wasm --target wasm32-unknown-unknown --profile release-wasm
```
Prints size in KiB; runs `wasm-opt -Oz` when Binaryen is on `PATH`.
See [doc/design/browser-marqdo-wasm.md](../../doc/design/browser-marqdo-wasm.md).
File diff suppressed because it is too large. Load diff
+201
View File
@@ -0,0 +1,201 @@
//! Browser export surface for Marqdo (ADR 0002 / C1–C3).
//!
//! Raw `cdylib` ABI (no wasm-bindgen CLI):
//! - `mq_alloc` / `mq_dealloc`
//! - `mq_run` — one-shot `# main` (C1)
//! - `mq_boot` — start session; return value often a `wire` table (C3)
//! - `mq_call` — `(name_ptr, name_len, args_ptr, args_len) ->` JSON result (C3)
//! - `mq_version`
//!
//! Packed results: little-endian `u32` length + UTF-8 JSON
//! `{ ok, stdout, error, value }`.
use std::alloc::{alloc, dealloc, Layout};
use std::cell::RefCell;
use std::ptr;
use std::slice;
use marqdo::{run_source, value_as_json, BrowserSession, RunOptions};
use serde_json::json;
thread_local! {
static SESSION: RefCell<Option<BrowserSession>> = const { RefCell::new(None) };
}
/// Allocate `size` bytes in WASM linear memory (alignment 1).
#[no_mangle]
pub extern "C" fn mq_alloc(size: usize) -> *mut u8 {
if size == 0 {
return ptr::null_mut();
}
let layout = match Layout::from_size_align(size, 1) {
Ok(l) => l,
Err(_) => return ptr::null_mut(),
};
unsafe { alloc(layout) }
}
/// Free a buffer previously returned by [`mq_alloc`], [`mq_run`], [`mq_boot`], or [`mq_call`].
#[no_mangle]
pub extern "C" fn mq_dealloc(ptr: *mut u8, size: usize) {
if ptr.is_null() || size == 0 {
return;
}
let layout = match Layout::from_size_align(size, 1) {
Ok(l) => l,
Err(_) => return,
};
unsafe { dealloc(ptr, layout) }
}
/// One-shot run (C1). Does not keep a session.
#[no_mangle]
pub extern "C" fn mq_run(ptr: *const u8, len: usize) -> *mut u8 {
let source = match read_utf8(ptr, len) {
Ok(s) => s,
Err(e) => return pack_json(&err_json(&e)),
};
pack_json(&run_to_json(&source))
}
/// Boot a session: run `# main`, keep entry env. Replaces any prior session.
#[no_mangle]
pub extern "C" fn mq_boot(ptr: *const u8, len: usize) -> *mut u8 {
let source = match read_utf8(ptr, len) {
Ok(s) => s,
Err(e) => return pack_json(&err_json(&e)),
};
match BrowserSession::boot(&source) {
Ok((sess, value)) => {
let stdout = String::new();
let value_json = match value_as_json(&value) {
Ok(j) => j,
Err(e) => return pack_json(&err_json(&e)),
};
SESSION.with(|s| *s.borrow_mut() = Some(sess));
pack_json(&json!({
"ok": true,
"stdout": stdout,
"error": null,
"value": value_json,
}))
}
Err(e) => {
SESSION.with(|s| *s.borrow_mut() = None);
pack_json(&err_json(&format!("{e:#}")))
}
}
}
/// Call a function in the current session.
/// `args` is UTF-8 JSON object of named arguments (may be `{}`).
#[no_mangle]
pub extern "C" fn mq_call(
name_ptr: *const u8,
name_len: usize,
args_ptr: *const u8,
args_len: usize,
) -> *mut u8 {
let name = match read_utf8(name_ptr, name_len) {
Ok(s) => s,
Err(e) => return pack_json(&err_json(&e)),
};
let args = match read_utf8(args_ptr, args_len) {
Ok(s) => s,
Err(e) => return pack_json(&err_json(&e)),
};
SESSION.with(|cell| {
let mut guard = cell.borrow_mut();
let Some(sess) = guard.as_mut() else {
return pack_json(&err_json("no session — call mq_boot first"));
};
match sess.call(&name, &args) {
Ok(value) => {
let stdout = sess.take_stdout();
let value_json = match value_as_json(&value) {
Ok(j) => j,
Err(e) => return pack_json(&err_json(&e)),
};
pack_json(&json!({
"ok": true,
"stdout": stdout,
"error": null,
"value": value_json,
}))
}
Err(e) => pack_json(&err_json(&format!("{e:#}"))),
}
})
}
/// Package version (NUL-terminated C string in static memory — do not free).
#[no_mangle]
pub extern "C" fn mq_version() -> *const u8 {
concat!(env!("CARGO_PKG_VERSION"), "\0").as_ptr()
}
fn read_utf8(ptr: *const u8, len: usize) -> Result<String, String> {
if ptr.is_null() || len == 0 {
return Ok(String::new());
}
let bytes = unsafe { slice::from_raw_parts(ptr, len) };
String::from_utf8(bytes.to_vec()).map_err(|e| format!("not utf-8: {e}"))
}
fn run_to_json(source: &str) -> serde_json::Value {
let mut opts = RunOptions::default();
opts.allow_fs_write = false;
opts.allow_exec = false;
opts.allow_net = false;
opts.sleep_limit_ms = Some(0);
match run_source(source, &opts) {
Ok(cap) => match value_as_json(&cap.value) {
Ok(value) => json!({
"ok": true,
"stdout": cap.stdout,
"error": null,
"value": value,
}),
Err(e) => err_json(&e),
},
Err(e) => err_json(&format!("{e:#}")),
}
}
fn err_json(msg: &str) -> serde_json::Value {
json!({
"ok": false,
"stdout": "",
"error": msg,
"value": null,
})
}
fn pack_json(v: &serde_json::Value) -> *mut u8 {
let s = v.to_string();
let bytes = s.as_bytes();
let total = 4 + bytes.len();
let out = mq_alloc(total);
if out.is_null() {
return ptr::null_mut();
}
unsafe {
let len = bytes.len() as u32;
ptr::copy_nonoverlapping(len.to_le_bytes().as_ptr(), out, 4);
ptr::copy_nonoverlapping(bytes.as_ptr(), out.add(4), bytes.len());
}
out
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn run_hello_json() {
let v = run_to_json("# main\n\n> print text=Hello World!\n");
assert_eq!(v["ok"], true);
assert_eq!(v["stdout"], "Hello World!\n");
}
}
+31 -4
View File
@@ -15,7 +15,10 @@
| 文档 | 摘要 |
|------|------|
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.1 语法宪法** |
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.2 语法宪法(现行运行时)** |
| [design/markdown-mapping-v0.3.md](design/markdown-mapping-v0.3.md) | **v0.3 草案:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断** |
| [adr/0005-prose-unified-markup.md](adr/0005-prose-unified-markup.md) | **Proposed:采纳 mapping v0.3** |
| [roadmap/markup-v0.3.md](roadmap/markup-v0.3.md) | **Markup v0.3 实现路线(M0–M5)** |
| [design/objects.md](design/objects.md) | **`#` 对象 / `##` 函数与方法** |
| [design/ai-skill.md](design/ai-skill.md) | **AI 接入 Skill**([`skills/marqdo/`](../skills/marqdo/)) |
| [design/code-vs-comment.md](design/code-vs-comment.md) | 叙述 / 可执行 / 外联 |
@@ -32,6 +35,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 +54,11 @@
| [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) | **调用:具名 + 位置实参** |
| [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** |
@@ -58,12 +77,20 @@
| [roadmap/object-inheritance.md](roadmap/object-inheritance.md) | **对象继承**(`# 子类 = > 父类`;I0–I2 已落地) |
| [roadmap/tables-maps-footnotes.md](roadmap/tables-maps-footnotes.md) | **表格语义**(竖表 / 横表字典 / 脚注取元 / 行向记录 / **单元格表达式 T5**) |
| [design/table-cell-expressions.md](design/table-cell-expressions.md) | **表数据单元格 = 表达式**(同调用实参值语法;Accepted) |
| [roadmap/ext-web.md](roadmap/ext-web.md) | **实现路线:`ext/web`**(W0–W4;设计见 [ext-web.md](../design/ext-web.md)) |
| [roadmap/browser-wasm.md](roadmap/browser-wasm.md) | **浏览器 WASM 路线 C(C0–C5 Completed)** |
| [roadmap/browser-wasm-d.md](roadmap/browser-wasm-d.md) | **路线 D:作者零 JS 前端(Completed)** |
| [roadmap/browser-wasm-e.md](roadmap/browser-wasm-e.md) | **路线 E:前端能力补齐(Completed)** |
| [roadmap/browser-wasm-f.md](roadmap/browser-wasm-f.md) | **路线 F:媒体/文件/Canvas 等(Completed,F1–F5;v0.3.3)** |
| [design/browser-marqdo-wasm.md](design/browser-marqdo-wasm.md) | **浏览器 Marqdo(WASM)设计** |
| [roadmap/ext-quantum.md](roadmap/ext-quantum.md) | **规划:`ext/quantum` 量子模拟**(基础门·电路·ABI·`ext add`) |
| [research/okf-and-marqdo.md](research/okf-and-marqdo.md) | OKF 调研 |
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点**(产品化 / 评测 / MCP / resume) |
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` 深入优化 A0–A4**(已完成) |
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** |
| [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** |
| [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus |
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** |
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
+57
View File
@@ -0,0 +1,57 @@
# ADR 0002:浏览器内 Marqdo = WASM 解释器(路线 C)
| | |
|---|---|
| 状态 | **Accepted** |
| 日期 | 2026-09-01 |
| 决策者 | chaungming + 协作 |
| 相关 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [roadmap/browser-wasm.md](../roadmap/browser-wasm.md) · [interpreter.md](../roadmap/interpreter.md) · [0001](0001-implementation-language.md) |
---
## 背景
`ext/web` 已把站点装配成「源码以 `.mq.md` 为主、服务端 Rust 解释执行」。作者面仍缺**浏览器内**的同一语言:事件、局部状态、客户端 fetch/WS 回调今天要么手写 JS,要么完全不做。
候选路线:
| 代号 | 做法 |
|------|------|
| **A** | 服务端驱动 + 极薄固定增强(类 HTMX) |
| **B** | 把 Marqdo **编译/翻译成 JavaScript** |
| **C** | 把 **Rust 解释器/字节码 VM 编成 WASM**,浏览器跑同一套语义 |
产品叙事目标:**网络项目源码树可以只有 `.mq.md`**(JS/WASM 为生成或发行物,不是第二作者语言)。
---
## 决策
1. **选定路线 C**:浏览器内运行 **与主机同构的 Marqdo 语义**(parse → tree 和/或 bytecode VM),制品为 `marqdo.wasm` + 极薄 JS 宿主桥。
2. **不选定 B 作为主路径**:翻译到 JS 易语义漂移,长期要维护两套后端;B 至多作实验,不替代 C。
3. **A 不对立**:内容站 / SSR / 表单 POST 仍以服务端 `ext/web` 为主;C 负责「必须在客户端执行的 Marqdo」。
4. **同一内核、两套宿主**:`server`(今日 CLI + axum 插件)与 `browser`(DOM / `fetch` / 定时器 / storage);**不是**把 axum、`plugins/web`、SQLite 服务端塞进浏览器。
5. **另开设计与路线图**(见相关链接);实现按 **C0→C5** 切片,金样对齐主机行为。
6. **与「编译 mq.md → WASM 机器码」区分**:本 ADR 是 **解释器/VM 上 WASM**;把 `.mq.md` 直接编译成独立 wasm 模块仍属 `interpreter.md` Phase III 可选项,**另案**,不替代本决策。
---
## 后果
- 核心库必须可 **feature-gate** 掉 `libloading` / `ureq` / `tiny_http` / TTY `libc` 等,以便 `wasm32-unknown-unknown` 链接。
- 新增公共 API:`run_source`(内存源码 + 可选导入图),供 WASM 与测试共用。
- 浏览器侧宿主 API 以表驱动「交互装配」暴露(对称于 `样式装配`);`ext/**` 仍不直接调 `host_*`。
- 发行物可包含 `.wasm` / 生成的 loader;**作者仓库可不提交手写业务 JS**。
- view 断点 / 静态文档站调试可复用同一 WASM 解释器(与 `next-phase.md` 所述一致)。
---
## 否决 / 非目标(本 ADR)
| 方案 / 目标 | 原因 |
|-------------|------|
| 以 B(编译到 JS)为主交付 | 语义双轨;与「一种语言」冲突 |
| 浏览器内完整复刻 `plugins/web` 服务器 | 协议与权限模型不同;服务端仍 axum |
| 浏览器 `dlopen` 原生插件 | WASM 无 POSIX 动态库模型 |
| v1 消灭一切 JS 字节 | 胶水与发行 loader 允许存在;禁止的是**业务手写 JS** |
| 用 Daphne/ASGI 托管 Marqdo | 已否决,见 [web-asgi-servers-and-marqdo.md](../design/web-asgi-servers-and-marqdo.md) |
+48
View File
@@ -0,0 +1,48 @@
# ADR 0003:浏览器异步 I/O(fetch / 定时)— 效应表 + 续体回调
| | |
|---|---|
| 状态 | **Accepted** |
| 日期 | 2026-09-01 |
| 决策者 | chaungming + 协作 |
| 相关 | [0002-browser-marqdo-wasm.md](0002-browser-marqdo-wasm.md) · [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [roadmap/browser-wasm.md](../roadmap/browser-wasm.md) |
---
## 背景
Marqdo 调用面今日以**同步**为主。浏览器 `fetch` / `setTimeout` 是异步的;若在 WASM 里阻塞等待,会卡死 UI,且 `wasm32-unknown-unknown` 无真实阻塞 HTTP。
C3 已有:`mq_call` 返回 Map(如 `set_text`)由官方 bridge 执行。C4 在同一通道上扩展异步效应。
---
## 决策
1. **不**在语言内核引入 async/await 关键字或假同步 `fetch`。
2. 处理器返回值可含**效应字段**(与 `set_text` 并列),由 **JS bridge** 执行:
- `fetch`: `{ url, method?, then, headers?, body? }`
- `after`: `{ ms, then }`(定时续体)
3. 异步完成后 bridge 调用 `mq_call(then, payload)`:
- fetch 成功/失败:`{ ok, status, body, error? }`
- after:`{ ok: true }`
4. 能力默认关网络语义仍由**返回效应**显式开启(站点作者主动返回 `fetch`);CORS / 鉴权仍是浏览器与服务端责任。
5. 服务端 `lib/net` / `plugins/web` **不变**;本 ADR 仅浏览器 WASM 宿主。
---
## 后果
- 作者用表格/Map 声明「请求谁、完成后调谁」,无手写业务 JS。
- Bridge 必须串行处理效应(先 `set_text`,再调度 `fetch`/`after`)。
- 深层 Promise 链靠多次 `then` 回调;不在 C4 做通用 async 运行时。
---
## 否决
| 方案 | 原因 |
|------|------|
| WASM 内同步阻塞 `fetch` | 卡死主线程;平台不支持 |
| 编译期把 Marqdo 译成 async JS | 回到路线 B |
| 在核心加 `await` 关键字 | 违反 Markup-as-Syntax / 关键字纪律 |
+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-*` 为门禁。
+53
View File
@@ -0,0 +1,53 @@
# ADR 0005:叙述统一的 Markup 映射(粗体即代码 · 斜体即返回 · 形参体推断)
| | |
|---|---|
| Status | **Accepted** |
| Date | 2026-09-13 |
| Related | [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) · [markdown-mapping.md](../design/markdown-mapping.md) · [return-hr-and-code-surface.md](../design/return-hr-and-code-surface.md) · [roadmap/markup-v0.3.md](../roadmap/markup-v0.3.md) |
## Context
- Marqdo 的产品承诺是「代码即文档 / 文档即代码」:`.mq.md` 打开是文章,运行是程序。
- v0.2([markdown-mapping.md](../design/markdown-mapping.md))为消歧做了硬隔离:无标记 = 注释;`*…*` = 语句;`**…**` = 返回;调用必须 `>`;形参必须 `` + `名` ``。
- 该隔离使叙述与程序**视觉割裂**;且与 AI/Markdown 习惯相反(模型偏好用 `**` 强调「要做的事」)。
- 产品方重新审视后,希望合法化如下写法:
```markdown
## 加一函数
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
# main
> 加一函数 37
或者可以直接这么调用**加一函数 37**
```
## Decision
1. 采纳 **Markup 映射 v0.3** 为下一版语言宪法草案,全文见 [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md)。
2. **角色对调**:`**…**` = 代码段(含可省略 `>` 的调用);`*…*` = 返回值。
3. **叙述中的** `` `名` ``:**首次未赋值 = 声明变量**;未使用不报错;**仅当可执行面读取时升为形参**(见设计 §4.4 · §8.2)。不设「提及性」专用语法。
4. **形参默认由函数体/叙述推断**(升参);`` + `名` `` 仅作迁移兼容。
5. **`>` 调用面保留**(可选)。
6. **空返回**用标记而非关键字:推荐 `---` / `***`;显式 `*None*` / `*无*`;整行 `**`;兼容 `****`(设计 §7.2)。
7. **不做 v0.2 双模式兼容**(摸索阶段允许破坏性变更);旧 `.mq.md` 须改写。
8. 金样例门禁:`tests/markup-v03/`;存量 suite 随后迁移。
## Consequences
### Positive
- 叙述与代码共用 Markdown 习惯,文档可读性上升。
- 更贴合 AI 生成粗体「操作」的偏好,降低错用标记。
- 去掉形参表仪式,函数更像「带名字的说明段落」。
### Negative / Risks
- **破坏性**:与 v0.2 金样例、Skill、教程、大量 `lib/`/`ext/` 源码不兼容,必须分波迁移或双模式。
- 段内扫描与形参推断增加解析/语义复杂度——空返回与升参规则已在设计 §7.2 / §8.2 钉死;其余 §12 项用金样例收口。
- view/catalog/LSP 高亮规则需同步。
### Neutral
- `#` / `##` 对象体系、标准库、插件 ABI、关键字最小集不变。
- 输出仍是 `print` / `打印`,不是粗体/斜体。
+54
View File
@@ -0,0 +1,54 @@
# 方括号标记调用与前置修饰语
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-09-14 |
| 相关 | [call-arguments.md](call-arguments.md) · [collection-access-link.md](collection-access-link.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) |
---
## 1. 动机
无标记时,修饰语+函数名与函数名+实参都是词列,**无法消歧**。消歧标记必须来自 Marqdo 语法,**不能**依赖任一自然语言词法(「的」、形容词位置等)。
## 2. 形状
```text
修饰语… [函数名] 实参…
```
| 例子 | 含义 |
|------|------|
| `[问候] marqdo` | 调用 `问候`,位置实参 |
| `礼貌 [问候] marqdo` | 另加 `礼貌=True` |
| `正式 礼貌 [问候] marqdo` | `正式=True` `礼貌=True` |
| `[结账摘要] 品名="拿铁" 杯数=2` | 仅具名实参 |
| `[问候] ([格式化] `名字`)` | 嵌套:内层整段用 `()` |
旧形保留:`> 问候 …`、`**问候 …**`、`礼貌=True` 显式具名。
## 3. 与取元 / foreach
| 形状 | 语义 |
|------|------|
| `[X](Y)`(`]` 后**紧邻** `(`) | 取元 |
| `[X]`(`]` 后不是 `(`) | 函数名标记 |
| `- [X](Y)` | foreach |
## 4. 修饰语绑定
- `[` 前按空白切开;每段为标识(可 `` `名` ``)。
- 降为 `Named(名, Bool(true))`,再与 `]` 后实参合并。
- 与显式同名具名冲突 → 诊断。
- **核心不剥语言词缀**;形参叫 `礼貌` 则写 `礼貌 [问候]`。
## 5. AST
`CallExpr.pre_modifiers: Vec<String>`;求值/字节码在绑参前展开。
## 6. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿并落地 |
+397
View File
@@ -0,0 +1,397 @@
# 浏览器 Marqdo(WASM 解释器)设计
| | |
|---|---|
| 状态 | **Accepted(设计锁定)** · 实现见路线图 C0–C5 |
| 日期 | 2026-09-01 |
| ADR | [0002-browser-marqdo-wasm.md](../adr/0002-browser-marqdo-wasm.md) |
| 路线图 | [roadmap/browser-wasm.md](../roadmap/browser-wasm.md) |
| 相关 | [ext-web.md](ext-web.md) · [bytecode.md](bytecode.md) · [web-assets-and-images.md](web-assets-and-images.md) · [table-cell-expressions.md](table-cell-expressions.md) |
---
## 0. 一句话
**源码只有 `.mq.md`;浏览器跑与 CLI 同构的 Marqdo VM(WASM);JS 只做宿主桥与加载器,不做业务语言。**
---
## 1. 目标与非目标
### 1.1 目标
| # | 目标 |
|---|------|
| G1 | 浏览器内执行合法 `.mq.md`(至少 `# main` + 打印/绑定/分支/循环/表/调用) |
| G2 | 与主机 **tree**(及后续 **bytecode**)金样在共享子集上 stdout/返回值一致 |
| G3 | 作者用 GFM 表声明交互(选择器 / 事件 / 调用),对称于 `样式装配` |
| G4 | 仓库源码树可不含业务 `.js`;允许提交或由工具生成 `marqdo.wasm` + 官方 loader |
| G5 | `import lib/…` 在浏览器可用(嵌入式 `lib/` 或打包进 wasm) |
### 1.2 非目标(本波 / C0–C3)
| # | 非目标 |
|---|--------|
| N1 | 在浏览器复刻 axum、`web_listen`、SQLite 服务端、admin UI |
| N2 | `plugin.load` 加载原生 `.so` / 浏览器内 dlopen |
| N3 | 把整站 `plugins/web` ABI 原样搬进 WASM |
| N4 | 把 `.mq.md` 编译成独立机器码 WASM(异于「解释器上 WASM」) |
| N5 | 强制内容站必须加载 WASM(纯 SSR 站可继续零客户端逻辑) |
---
## 2. 架构
```
┌─────────────────────────────────────────────────────────┐
│ Page (HTML shell from ext/web SSR or static) │
│ ┌──────────────┐ ┌─────────────────────────────────┐ │
│ │ DOM / CSS │ │ Official JS loader (thin) │ │
│ └──────▲───────┘ │ - WebAssembly.instantiate │ │
│ │ bridge │ - marqdo_run_source / on_event │ │
│ │ └──────────────┬──────────────────┘ │
│ │ │ │
│ │ ┌──────────▼──────────┐ │
│ │ │ marqdo.wasm │ │
│ │ │ parse → load → │ │
│ └──────────────│ Interpreter | Vm │ │
│ host_dom_* │ HostContext(browser)│ │
│ host_fetch_* │ embedded lib/ │ │
│ └─────────────────────┘ │
└─────────────────────────────────────────────────────────┘
Server (unchanged):
marqdo run / plugins/web (axum) — SSR, DB, auth, full site
```
**原则:** 一套语言语义;**HostContext 分型**(`native` vs `browser`),不是两套语法。
---
## 3. 与现有流水线对齐
主机今日(见 `src/lib.rs`):
```
path → fs::read → load_module → Interpreter|Vm → HostContext(native)
```
浏览器目标:
```
source: &str (+ optional import map)
→ load_module_from_memory
→ Interpreter|Vm (capture stdout)
→ HostContext(browser caps)
→ { ok, stdout, value_json, error }
```
公共库 API(C0/C1 必须落地):
| API | 职责 |
|-----|------|
| `run_source(source, opts) -> Result<RunCapture>` | 无路径入口;cwd/fs_root 虚拟 |
| `RunOptions` 浏览器默认 | `allow_fs_write=false`, `allow_exec=false`, `allow_net=false`(net 经显式 bridge 再开) |
| `load` 导入 | `lib/**` → `embedded_lib`;用户模块 → JS 注入的 `HashMap<path, source>` |
后端优先级:
1. **C1:tree**(与默认 CLI 一致,调试简单)
2. **C2+:bytecode** 可选(体积/性能;金样双后端)
---
## 4. Cargo / 制品布局
### 4.1 Feature 门(核心 crate `marqdo`)
| Feature | 默认(native) | `wasm-core` | 作用 |
|---------|----------------|-------------|------|
| `cli` | on | off | `main` / clap 仅 bin |
| `view` | on | off | `tiny_http` 文档浏览器 |
| `net-host` | on | off | `ureq` HTTP 客户端 |
| `plugin-host` | on | off | `libloading` 原生插件 |
| `exec-host` | on | off | `std::process` / foreign |
| `fs-host` | on | off | 真实磁盘读写(可读可后续经 VFS 桥) |
| `wasm-core` | off | on | 浏览器子集编译开关 |
`wasm32-unknown-unknown` 构建:**不得**链接 `libloading`、`ureq`、`tiny_http`、TTY `libc`。
### 4.2 包
| 路径 | 角色 |
|------|------|
| `marqdo`(根) | 核心;feature-gate |
| `crates/marqdo-wasm` | `cdylib`:`mq_*` ABI + `js/marqdo-bridge.js` |
| `ext/web` 或 `web/browser` | L1:`浏览器.运行` / `交互装配`(C3+) |
| `examples/browser-hello/` | 静态页 + wasm 冒烟 |
| `tests/browser/` 或金样脚本 | Node/wasmtime 跑 `run_source` 对齐 |
发行:`marqdo wasm build`(C2 CLI 糖)或 `wasm-pack build crates/marqdo-wasm`。
---
## 5. 宿主能力矩阵
| 能力 | Native | Browser C1 | Browser C3+ |
|------|--------|------------|-------------|
| `print` / 捕获 stdout | ✓ | ✓ → 可镜像 `console` | ✓ |
| `input` | stdin / preset | **仅 preset / JS 喂入** | 可选 prompt 桥 |
| builtins / 表 / 算术 | ✓ | ✓ | ✓ |
| `lib/math` `lib/json` `lib/collection` | ✓ | ✓(embedded) | ✓ |
| `lib/fs` 真磁盘 | ✓ | ✗ 明确报错 | 可选 OPFS/VFS 桥 |
| `lib/net` ureq | ✓ | ✗ | `fetch` 桥(异步模型见 §7) |
| `plugin.load` | ✓ | ✗ | ✗(改 L1 浏览器专用) |
| `exec` / foreign | ✓ | ✗ | ✗ |
| DOM / 事件 | ✗ | stub | **交互装配** |
| `sleep` | thread | 0 或 JS timer(异步) | timer |
错误策略:**显式失败**(诊断字符串含 `unavailable in browser wasm`),禁止静默空成功。
---
## 6. 交互装配(C3,对称样式装配)
### 6.1 作者面(示例)
```markdown
---
import json:lib/json.mq.md
---
# main
*`count` = 0*
`wire` =
| @ | 选择器 | 事件 | 调用 |
|---|--------|------|------|
| 1 | "#bump" | click | bump |
**`wire`**
## bump
*`count` = count + 1*
*`label` = > str count*
*`patch` = > json.set map=None key="#count" value=label*
**> json.set map=None key="set_text" value=patch**
```
`# main` 的返回值是 **wire 表**(`@` 行向记录列表)。Loader 调用 `mq_boot`,再 `wireEvents`。
### 6.2 桥约定
| 步骤 | API |
|------|-----|
| 启动 | `mq_boot(source)` → `{ ok, value }`;`value` = wire 列表或 `{ wire: [...] }` |
| 事件 | Loader `addEventListener` → `mq_call(fn, {"event":"click"})` |
| 回写 | 返回 Map 可含 `set_text`: `{ "#sel": "text" }`(仅 `textContent`) |
行键名认:`选择器`/`selector`、`事件`/`event`、`调用`/`call`。
含 `/` 的 CSS 等单元格仍 **引号优先**(见 [table-cell-expressions.md](table-cell-expressions.md))。
L1 `浏览器.交互装配`(ext)可后置;C3 以 bridge + 返回 wire 表即可验收。
---
## 7. 异步模型(C4)
锁定:[ADR 0003](../adr/0003-browser-async-effects.md)。
处理器返回 Map 可含(与 `set_text` 并列):
| 字段 | 含义 | 完成后 `mq_call` 实参 |
|------|------|----------------------|
| `fetch` | `{ url, method?, then, headers?, body? }` | `{ ok, status, body, error? }` |
| `after` | `{ ms, then }` | `{ ok: true }` |
Bridge:`applyEffects(exports, value)` — 先 DOM,再调度异步;**不**在 WASM 内阻塞。
示例见 `examples/browser-hello/fetch.mq.md`。
---
## 8. 安全
| 项 | 规则 |
|----|------|
| 默认能力 | 无磁盘写、无 exec、无任意 net |
| 源码来源 | 同源或构建时嵌入;不默认 `eval` 远程不可信脚本除非站点显式开启 |
| DOM | 仅经装配表/白名单 API;不暴露任意 `innerHTML` 字符串执行第三方脚本 |
| CSRF / Cookie | 浏览器 Marqdo **不替代**服务端鉴权;cookie 仍走 HTTP |
---
## 9. 与 `ext/web` 分工
| 层 | 负责 |
|----|------|
| 服务端 `plugins/web` | 路由、DB、会话、SSR HTML、样式/头/图装配 |
| 页面壳 | `头装配` 挂 `module` → `marqdo-bridge.js`;`static` 提供 `.wasm` |
| 浏览器 L1 | `客户端挂载` / `client_embed`;效应约定见 ADR 0003 |
| 核心 / crate | `run_source`、`BrowserSession`、`marqdo-wasm` ABI |
挂载示例:
```markdown
`头` =
| 关系 | 地址 |
|------|------|
| module | /static/marqdo-bridge.js |
*p = > page.头装配 表=头*
```
```bash
marqdo wasm build -o static # marqdo_wasm.wasm + marqdo-bridge.js
# app.static dir=static
```
业务页再 `boot` 自己的 `.mq.md`(见 `examples/browser-hello/`)。
---
## 10. 测试与验收
| 级 | 内容 |
|----|------|
| 单元 | `run_source("…# main\n> print…")` native 与 wasm 同测 |
| 金样子集 | `tests/structure/hello.mq.md` 等无 fs/net/plugin 的样例 |
| 浏览器冒烟 | `examples/browser-hello`:按钮点击 → Marqdo 函数 → 改 DOM 文本 |
| 回归 | CI:`cargo test` native;另 job `wasm-pack build` / `cargo check --target wasm32-unknown-unknown --no-default-features --features wasm-core` |
---
## 11. 文档与技能同步
- ADR 0002、本文、路线图 C0–C5。
- `.cursor/skills/marqdo/SKILL.md`:补充「浏览器 WASM / 交互装配 / 引号 CSS」。
- `CHANGELOG`:Unreleased 记录设计锁定与各 C 完成项。
---
## 12. 风险
| 风险 | 缓解 |
|------|------|
| wasm 体积过大 | `release-wasm` profile(`opt-level=z` + LTO + strip);`marqdo wasm build` 打印 KiB,有则跑 `wasm-opt -Oz` |
| 异步拖垮语言 | ADR 0003 效应表;不阻塞 WASM |
| Feature-gate 伤 native | 默认 features = 今日行为;CI 全绿再合 |
| 作者误以浏览器替代服务器安全 | 文档强调鉴权在服务端 |
| 会话要 bytecode | **未做**:`BrowserSession` 固定 tree(缺 entry-env invoke);`run_source` 已支持 bytecode |
---
## 14. C5 硬化(已落地)
| 项 | 状态 |
|----|------|
| `profile.release-wasm` + `marqdo wasm build` 体积报告 | done(~0.9 MiB) |
| 可选 `wasm-opt` | done |
| `run_source` bytecode 金样 | done |
| 规范 bridge + 构建拷贝 | done(`crates/marqdo-wasm/js/`) |
| Node ABI 冒烟 | done(`tests/wasm`) |
| 站点 `头装配` / L1 `client_embed` | done |
| 会话 bytecode / view 断点复用 | **非本版目标** |
---
## 16. 路线 D — 作者零 JS(Active)
路线图:[browser-wasm-d.md](../roadmap/browser-wasm-d.md)。
**原则:** 业务与交互 100% `.mq.md`;`marqdo-bridge.js` 仅宿主胶。作者仓库可不含自写 `.js`。
### 16.1 一键挂载
| API | 含义 |
|-----|------|
| `mount({ wasmUrl, source \| sourceUrl, … })` | `loadWasm` → `boot` → `wireEvents` → 初始效应 |
| `script[data-mq-source-url]` / `data-mq-wasm` | 模块脚本属性自启 |
| `#marqdo-boot` | `application/json` 配置块 |
| `data-mq-playground` | 官方 playground(`#src,#run,#out`),仍非业务 JS |
`ext/web`:`client_embed` / `客户端挂载` 参数 `bridge`、`wasm`、`source`、`boot`(默认 true)。
```bash
marqdo wasm build -o static # marqdo_wasm.wasm + marqdo-bridge.js
# app.static dir=static
# intro 或主区嵌入 > web.client_embed source="/static/client.mq.md"
```
### 16.2 DOM / 表单效应(D3)
与 `set_text` / `fetch` / `after` 并列(白名单;**默认无**任意脚本注入):
| 字段 | 作用 |
|------|------|
| `set_text` | `textContent` |
| `set_value` | input/textarea/select 的 `value` |
| `set_attr` | 属性;值为 `null`/`false` 则 `removeAttribute` |
| `set_class` | `className` 字符串 |
| `toggle_class` | `{ "#sel": "cls" }` 切换 class |
| `set_html` | **仅**键前缀 `#trusted` 的选择器才写 `innerHTML`;其它键忽略 |
Wire 行可选 `值选择器` / `value_from`:事件触发时把该节点内容写入实参 `value`。
事件实参默认含:`event`、`value`、`checked`、`id`(来自 event.target);`submit` 另含 `fields` 表单字典。
L1:`web.dom_patch` / `网页.DOM补丁` 合并效应键;`web.text_patch` / `网页.文本补丁` 快捷 `set_text`。
### 16.3 非目标(D)
| # | 非目标 |
|---|--------|
| D-N1 | 用 Marqdo 重写 bridge 自身 |
| D-N2 | 作者手写业务 JS / TS(官方桥内机制允许) |
| D-N3 | ~~开放无前缀的 set_html~~(E 已允许任意选择器;内容由 MQ 产出) |
---
## 17. 路线 E — 前端能力补齐(Active)
路线图:[browser-wasm-e.md](../roadmap/browser-wasm-e.md)。
**原则:** 唯一硬禁是**作者手写业务 JS**。官方 bridge 可实现列表装配、路由、storage、WebSocket、内部模板/轻量 VDOM 等;作者只写 `.mq.md` + 效应表。
| 波 | 要点 |
|----|------|
| E1 | `set_style` / `focus` / `blur` / `scroll_into`;wire `委托`;键盘事件 |
| E2 | `set_html` / `replace_children` / `render_list` |
| E3 | `navigate` + `popstate`(选择器 `window`) |
| E4 | `storage` `{ op, key, value?, scope?, then? }` |
| E5 | `ws` `{ op: open\|send\|close, … }` |
| E6 | `fetch_all` / `interval` / `clear_interval` / fetch `fields` |
### 17.1 效应速查(E)
| 字段 | 含义 |
|------|------|
| `set_style` | `{ "#sel": { color: "red" } }` 或 `{ "#sel": "color:red" }` |
| `focus` / `blur` | `"#sel"` 或选择器数组 |
| `scroll_into` | `"#sel"` |
| `set_html` / `append_html` / `replace_children` | 写/追加 HTML(MQ 产出;XSS 自负) |
| `render_list` | `{ "#sel": { tag, items } }` |
| `remove` | 选择器或数组,删除节点 |
| `add_class` / `remove_class` | classList |
| `navigate` | `{ url, replace?: bool }` |
| `storage` | `{ op, key, value?, scope?: local\|session\|cookie, days?, then? }` |
| `ws` | `{ op: open\|send\|close, … }` |
| `fetch_all` | `{ requests: []\|map, then }` |
| `interval` / `clear_interval` | 定时 |
| `clipboard` / `download` | 剪贴板 / 触发下载 |
| `fetch.fields` | → FormData |
Wire 列:`委托` / `delegate` = 在容器上监听,目标须 `closest(delegate)`;选择器 `window` 绑 `window`。
## 15. 决策摘要
| 问题 | 答案 |
|------|------|
| 路线? | **C**:解释器/VM → WASM |
| 作者语言? | 仅 `.mq.md` |
| JS 角色? | Loader + 宿主桥 |
| 服务端? | 保留;不塞进浏览器 |
| 第一步实现? | C0 门控可编译 + C1 `run_source` 打印闭环 |
+17 -10
View File
@@ -2,9 +2,9 @@
| | |
|---|---|
| 状态 | 已定(v0.1 增补) |
| 状态 | 已定(v0.1 增补;2026-09-14:方括号标记调用) |
| 日期 | 2026-08-07 |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md) |
---
@@ -16,20 +16,26 @@
|------|------|------|
| **具名**(保留) | `> 问候 谁=Marqdo` | `名=值`;值可含空格(至下一 `名=`) |
| **位置**(新增) | `> 问候 Marqdo` | 按形参声明顺序绑定 |
| **方括号标记**(增补) | `礼貌 [问候] Marqdo` | `[函数名]` 消歧;`[` 前裸词 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md) |
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。具名不可绑定同一形参两次;位置实参不得出现在「已出现具名实参」之后(对齐常见「位置在前、关键字在后」习惯)。
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。具名不可绑定同一形参两次;位置实参不得出现在「已出现具名实参」之后(对齐常见「位置在前、关键字在后」习惯)。前置修饰语与显式同名具名冲突则报错。
---
## 2. 文法(调用尾部)
```
call_tail ::= callee arg*
call_tail ::= bracket_call | classic_call
bracket_call ::= modifier* '[' callee ']' arg*
classic_call ::= callee arg*
arg ::= named | positional
named ::= ident '=' value
positional ::= value_token
positional ::= value_token | '(' call_tail ')'
modifier ::= ident # 展开为 ident=True;核心不剥语言词缀
```
- `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记(见 [collection-access-link.md](collection-access-link.md))。
- 嵌套调用:把内层整段放进 `()`,例如 `[问候] ([格式化] "x")`。
- `value`(具名右侧):可含空格与 `` `var` `` 插值,直到下一个 `ident=` 边界。
- `value_token`(位置):空白分隔的一个词法单元——数字、`` `名` ``、标识/文本词;**不含空格**。多词字符串请用具名,例如 `> print text=Hello World!`。
- 实参值中 `` `变量` `` 后**紧跟** `[^…]` 时按**脚注取元**解析(可链式),而非文本:`> print text=苹果单价:`水果价格`[^苹果]`、`> print text=`订单`[^2][^品名]`。
@@ -44,13 +50,14 @@ positional ::= value_token
## 3. 绑定算法
1. 收集具名 → 映射;冲突则报错。
2. 按函数形参表顺序:若具名已提供则用之,否则取下一个位置实参。
3. 位置实参有余、或必填形参仍缺 → 报错(内置 `input` 的 `prompt` 可缺省)。
4. 用户函数:额外具名键仍写入调用环境(便于扩展);位置实参不可超过形参数目。
1. 将前置修饰语展开为 `名=True` 具名(与显式具名冲突则报错)。
2. 收集具名 → 映射;冲突则报错。
3. 按函数形参表顺序:若具名已提供则用之,否则取下一个位置实参。
4. 位置实参有余、或必填形参仍缺 → 报错(内置 `input` 的 `prompt` 可缺省)。
5. 用户函数:额外具名键仍写入调用环境(便于扩展);位置实参不可超过形参数目。
---
## 4. 金样例
见 `tests/structure/positional-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。
见 `tests/structure/positional-call.mq.md`、`tests/structure/bracket-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。
+119
View File
@@ -0,0 +1,119 @@
# 代码即文档 · 叙述面摩擦(v0.3 实测)
| | |
|---|---|
| 状态 | **Done** |
| 日期 | 2026-09-14 |
| 触发 | `examples/code-as-docs/index.mq.md` 试跑 |
| 宪法 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) |
| 路线 | [code-as-docs-gaps.md](../roadmap/code-as-docs-gaps.md) |
---
## 0. 原则
修复必须同时服务:
1. **代码即文档**:人读 Markdown 时自然段落、分隔线、强调不应被误伤。
2. **适配 LLM 输出**:模型习惯写 `---` 分段、`**加粗强调**`、`0.85` 小数、`` map[^`key`] `` 动态键——运行时应尽量「写出来就能跑」。
3. **可执行标记仍清晰**:真正的赋值 / 调用 / 返回不被误判成装饰。
---
## 1. 四个问题(实测)
### G1 — 模块级 `---` 被当成结构错误
| | |
|---|---|
| 现象 | 文件标题段落后写 Markdown 分隔线 `---`,报 `expected heading … got: ---` |
| 根因 | 词法上整行 `-`/`*` 为 Code;旧实现把函数体内 `---` 当收束,模块顶却当非法。现统一为叙述跳过 |
| 人/LLM 期望 | 任意处 `---` = GFM thematic break = **叙述噪音** |
| 决议 | **处处** frame 行 skip;副作用收束用 `*None*` / `**` / `****`(返回即结束函数体解析) |
### G2 — 叙述里的 `**强调**` / `*斜体强调*` 被当成代码/返回
| | |
|---|---|
| 现象 | 「本文件既是**说明**也是**程序**」→ 粗体 `说明` 不是赋值/调用,解析失败;`*only*` 类英文强调升成返回/`only` 变量 |
| 根因 | v0.3 叙述扫描凡 `**…**` / `*…*` 一律可执行([prose.rs](../../src/parse/prose.rs));Skill 曾禁止强调,但与 LLM/Markdown 习惯冲突 |
| 人/LLM 期望 | 装饰性强调可出现;**像代码的**粗体/斜体仍执行 |
| 决议 | **形状启发式**(见 §2):像代码则执行,否则当作叙述装饰(不产生 Stmt,不升参) |
### G3 — 小数面量 `0.85` 不可用
| | |
|---|---|
| 现象 | `**x = 0.85**` → `trailing input: ".85"`;`28 * 0.85` 解析错乱;即便进到求值,`*` 仍只接受 int |
| 根因 | 表达式主词只吃整数字面量(`Literal` 无 `Num`);运行时已有 `Value::Num`,二元运算未接浮点 |
| 人/LLM 期望 | `0.85`、`3.14`、`折扣=0.85` 可写可算 |
| 决议 | 解析 `数字.数字` → `Literal::Num`;`*` `/` `+` `-` 及比较在 `Int`/`Num` 间提升(与已有 `cmp_ord` 一致) |
### G4 — 动态脚注键 `` 菜单[^`名`] ``
| | |
|---|---|
| 现象 | `` 菜单[^`名`] `` → `missing map key ``名`` `(把字面 `` `名` `` 当键,或解析失败) |
| 根因 | `[^label]` 的 label 仅为**静态字符串**;AST `Expr::Index { label: String }` 无变量槽 |
| 人/LLM 期望 | 表/映射按变量取键:`` `菜单`[^`品名`] `` 或 `菜单[^`品名`]` |
| 决议 | 支持 `` [^`ident`] `` → 运行时用变量值作键(文本化后走现有 footnote get);静态 `[^拿铁]` 不变 |
---
## 2. 粗体/斜体「像代码」启发式
### 粗体 `**inner**` → 可执行,当且仅当
满足任一:
- 含 `=`(赋值 / 命名参数调用);或
- 以 `>` 开头(显式调用);或
- 含运算符 / 索引 / 调用形:`+ - * / ( ) [ ]`;或
- 空白分词 ≥2 段,且其后段含数字面量、引号串、或 `=`(如 `**加一 37**`、`**print text="hi"**`)
否则(如 `**说明**`、`**代码即文档**`)→ **装饰,忽略**。
### 斜体 `*inner*` → 返回,当且仅当
满足任一:
- 空 / `None` / `无` / `空` / bool 字面;或
- 以 `>` 开头;或
- 含 `=` 或运算符 / 索引;或
- **整行**仅为 `*…*`(含缩进)——整行返回 `*总额*` / `*n*`;或
- 行内且前方紧邻「返回」二字(叙述「接着返回*n*」)
否则行内简单词(如 `*only*`、`*named*`)→ **装饰,忽略**。
> 整行 `*n*` 仍是返回;行内「返回*n*。」仍是返回。英文强调词在句中被忽略。
---
## 3. 非目标
- 不恢复 v0.2 双模式
- 不引入 `if`/`return` 关键字
- 不把任意 `**任意自然语言句子**` 都当代码(必须过 §2)
- 动态键第一期只做 `` [^`ident`] ``,不做完整表达式 `[^a+b]`
---
## 4. 验收
| 用例 | 期望 |
|------|------|
| 顶层段落之间的 `---` | 可解析、可运行 |
| 「既是**说明**也是**程序**」 | 可解析;无 Stmt |
| `**应付 = 原价 * 0.85**` / `折扣`=0.85 | 数值正确(浮点) |
| `` **价 = 菜单[^`名`]** ``(`名` 已绑定) | 取到对应价 |
| `examples/code-as-docs/index.mq.md` | 用回浮点折扣与动态键后仍绿 |
| 既有 `tests/markup-v03/*` 与 gold | 不回归 |
---
## 5. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿:四缝 + 启发式 + 验收 |
| 2026-09-14 | 落地:G1–G4 实现 + 金样;顶层 Comment 引言 skip |
+16 -13
View File
@@ -2,8 +2,12 @@
| | |
|---|---|
| 状态 | 与 mapping v0.1 / keywords 对齐(成段注释) |
| 日期 | 2026-08-04 |
| 状态 | 与 mapping **v0.3** 对齐(现行运行时) |
| 日期 | 2026-09-14 |
| 取代 | 本文曾按 v0.2(`*语句*` / `**返回**`)叙述;旧对照见 [markdown-mapping.md](markdown-mapping.md) |
| 相关 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) §4 |
「Markup」在此仓库 = Marqdo **把 Markdown 标记映射成语法** 的那一层,不是另一个语言。
---
@@ -11,19 +15,18 @@
| 层 | 形态 | 角色 |
|----|------|------|
| **叙述面** | 成段注释(空行分段) | 注释;段内任意标记无语义 |
| **Marqdo 可执行面** | 结构标记 + `*语句*` + `**返回**` | 本语言程序 |
| **叙述面** | 普通段落 | 注释;行内 `` `名` `` 可声明/引用;装饰性 `**强调**` / `*斜体*` 不执行 |
| **Marqdo 可执行面** | 结构标记 + **`**代码**`** + **`*返回*`** | 本语言程序 |
| **外联面** | ` ```lang ` | 其它语言(FFI) |
输出属于可执行面里的**函数调用**(`> print …`),见 [keywords.md](keywords.md)。
输出属于可执行面里的**函数调用**(`> print …` / `**print …**`),见 [keywords.md](keywords.md)。
### 成段注释
- 以**空行**划分段落。
- 段首行:首字符非标记 → 注释。
- 段内续行:一律注释(即使以 `` ` `` / `-` / `**` 等开头)。
- **例外**:整行仅为 `**expr**`(或 `****`)→ Marqdo **返回**;`**强调**` 后还有文字 → 仍是叙述注释。
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
- 段首行:首字符非标记 → 注释段;段内续行一律叙述(即使以 `` ` `` / `-` 开头)。
- 段内仍扫描行内可执行位:`` `名` ``、代码形 `**…**`、返回形 `*…*`。
- 叙述段与独立结构行(`>` `#`)之间**建议空一行**,否则 `> print` 可能被吞进注释段。
---
@@ -31,8 +34,8 @@
| 标记/形式 | 角色 | 是否架构级 |
|-----------|------|------------|
| `*…*` | 程序语句 | 是 |
| `**…**` | 返回值 | 是 |
| `****` / 空粗体 | 空返回 + 结束函数体 | 是 |
| `**…**` | 代码(赋值 / 调用 / 表达式语句) | 是 |
| `*…*` | 返回值(整行、`返回*n*`、或表达式形) | 是 |
| `****` / 整行 `**` / `*None*` | 空返回 + 结束函数体 | 是 |
| `> print …` | 打印副作用 | 否(内置函数) |
| 函数体 `---` / `***` | 结束函数体 | 是(边界) |
| 函数体 `---` / `***` | 叙述分隔(跳过,**不**结束函数体) | 否 |
+64
View File
@@ -0,0 +1,64 @@
# 集合取元:GFM 链接形
| | |
|---|---|
| 状态 | **Active(运行时)** |
| 日期 | 2026-09-14 |
| 相关 | [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
---
## 1. 决议
表达式取元的**主语法**为 Markdown 链接外形,与 foreach 同构:
| 角色 | 写法 |
|------|------|
| **取元(表达式)** | `[键](集合)` |
| **遍历(语句)** | `- [项](集合)`(不变) |
| **脚注取元(过渡)** | `` 集合[^键] `` 仍解析,新代码勿写 |
心智:**方括号 = 取出的名字,圆括号 = 从哪取。**
```markdown
**价 = [拿铁](菜单)**
**价 = [`名`](菜单)**
**第一 = [1](篮子)**
- [行](今日订单)
**名 = [品名](行)**
```
## 2. 细则
| 写法 | 语义 |
|------|------|
| `[拿铁](菜单)` | 静态键;`菜单` 为变量(粗体/斜体内) |
| `` [`名`](菜单) `` | 动态键(求值 `名` 再作键) |
| `[1](篮子)` | List **1-based** 下标(同脚注约定) |
| `[1]([苹果](货架))` | 嵌套链式 |
与 `- [项](集合)` 消歧:仅 **表达式位置** 的 `[…](…)` 为取元;`-` 行头仍为 foreach。
## 3. 迁移
`` `菜单`[^拿铁] `` / `菜单[^拿铁]` → `[拿铁](菜单)`(**基与键左右对调**)。
| 区域 | 约定 |
|------|------|
| 新代码 / examples / public | **只用**链接形 |
| `tests/structure/footnote*` · `interp-footnote*` | 脚注兼容门禁(保留) |
| 其余 structure / ext / lib 金样 | 已迁链接形 |
脚注路径保留至另行决定移除之日;Skill / 教程 / 新示例只用链接形。
## 4. 非目标
- 点号 map 访问、`在`、箭头取元、`(键)[集合]`
- 循环语法糖(`←` / `in` / 自然语言)
## 5. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿并落地主语法 |
+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` |
#### 强烈建议
+9 -18
View File
@@ -16,27 +16,17 @@
tests/
README.md
gold.rs # 集成测试入口
structure/ # 代码基础结构(Markup 架构)
hello.mq.md
nested-call.mq.md
positional-call.mq.md
branch.mq.md
loop.mq.md
collection.mq.md
import/
main.mq.md
utils.mq.md
ns/
helpers.mq.md
path3.mq.md
use.mq.md
structure/ # 代码基础结构(Markup 架构 · v0.2)
…
keywords/ # 关键字与内置名
print.mq.md
bool-logic.mq.md
…
markup-v03/ # Markup 映射 v0.3 草案金样例(实现前 ignore)
README.md
inc-prose.mq.md
…
ext/
agent-run-live.mq.md
…
errors/ # 期望失败(诊断文案稳定后再加金样例)
ns-instance-method.mq.md
…
```
@@ -51,6 +41,7 @@ tests/
|------|--------|----------|
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、点号路径 / `use`、位置/具名实参 | 关键字边角 |
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
| **markup-v03** | v0.3:叙述声明、粗体代码、斜体返回、升参、空返回、双调用面(见 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)) | 在 `--markup v0.3` 落地前 `#[ignore]` |
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
未单独建夹、但应覆盖的其它测试(`src/**` 单测或日后 `tests/runtime/`):
+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 -26
View File
@@ -2,9 +2,9 @@
| | |
|---|---|
| Status | **Accepted (v0.1)** |
| Date | 2026-08-07 |
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) |
| Status | **Accepted (v0.3.5 prep)** — prebuilt native download |
| Date | 2026-09-04 |
| Related | [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) · [08-ext-deploy-coupling.md](ext-web-customization/08-ext-deploy-coupling.md) |
## Commands
@@ -12,8 +12,8 @@
marqdo ext list
marqdo ext add llm
marqdo ext add agent
marqdo ext add web
marqdo ext remove llm
marqdo ext remove agent
```
## Install root
@@ -23,50 +23,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` copies the built native plugin into `MARQDO_EXT/native/`. Build it first:
## Release assets (native)
```bash
cargo build -p marqdo_plugin_agent
marqdo ext add agent
```
| Asset | Platform |
|-------|----------|
| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Windows x64 (`native/*.dll`) |
| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Linux x64 (`native/lib*.so`) |
Without install, runtime resolves the plugin via `plugin.native_path name=agent` (see [ext-abi.md](ext-abi.md)): `MARQDO_AGENT_PLUGIN` → `CARGO_TARGET_DIR/{debug,release}/` → cwd `target/…` → beside `marqdo` binary → `MARQDO_EXT/native/`.
macOS: use local `cargo build` until CI adds Darwin natives (same zip naming pattern reserved).
## Tests
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_agent_framework_smoke`, `ext_agent_run_live` ([`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md); needs `tests/ext/.env` + built `libagent`).
`tests/gold.rs`: `ext_cli_add_list_remove_llm`, `ext_cli_add_agent`, `ext_cli_add_web` (local build path; set `MARQDO_EXT_NO_DOWNLOAD=1` in sandboxes if needed).
Unit: `ext_fetch` URL / triple tests.
## Non-goals
- Third-party registry
- Merging into `lib/`
- Bundling domain/task helpers in official ext
- Merging domain helpers into `lib/`
- Guaranteeing plugin **source** ABI stability (author `.mq.md` API is the contract)
+306
View File
@@ -0,0 +1,306 @@
# 设计:宿主集成缺口补齐(`ext/web` · `ext/ai`)
| | |
|---|---|
| 状态 | **Accepted · H1–H4 stdio 已落地**(H4b HTTP 可选) |
| 日期 | 2026-09-07 |
| 缺口盘点 | [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) |
| 路线图 | [ext-hosting.md](../roadmap/ext-hosting.md) |
| 边界 | [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) |
| 目标 | 用**扩展库一等 API**关闭 GAP-01–05,取代下游 Python 旁路 |
---
## 0. 一句话
**服务器中继与「请求→`##`」进 `ext/web`;MCP Server 与 corpus 可发现进 `ext/ai`;标准库只保留已有客户端 SSE。** 作者用 GFM 表声明路由/工具,不写 JS、不启第二语言运行时。
---
## 1. 分层与禁止项
| 层 | 职责 | 落点 |
|----|------|------|
| 作者面 | 声明路径、上游、函数名、工具表 | `ext/web/web.mq.md` · `ext/ai/agent.mq.md`(+ 中文对偶) |
| ABI | axum 流式代理、每请求 interp 调用、MCP 传输 | `plugins/web` · `plugins/agent` |
| 标准库 | 不变:缓冲客户端 SSE / 解析 | `lib/net`(**不**加中继) |
| 核心 host | **禁止**新增 agent/web 领域 `host_*` | 见 Skill 硬规则 9 |
**禁止:**
1. 为中继在浏览器手写业务 JS。
2. `json=` 继续塞「任意 `##`」语义(保持 DB-only;新能力用独立装配名)。
3. MCP Server 把向量库升为权威真相(工具结果可带 `authority=workbook`)。
4. 无白名单的「任意文件系统路径 + 任意 `##`」远程触发。
---
## 2. GAP-01 · `app.proxy` 流式反向代理
### 2.1 作者 API
```markdown
*应用 = > `应用`.proxy path="/v1/chat/completions" upstream=$OPENAI_BASE_URL*
*应用 = > `应用`.proxy path="/llm/stream" upstream="https://api.example.com" strip_prefix="/llm" stream=True*
```
或装配表(一次挂多条):
```markdown
*应用 = > `应用`.configure proxy=`代理表`*
| path | upstream | stream | strip_prefix | headers_from_env |
|------|----------|--------|--------------|------------------|
| /proxy/chat | $OPENAI_BASE_URL | True | | OPENAI_API_KEY=Authorization |
```
| 参数 | 默认 | 含义 |
|------|------|------|
| `path` | 必填 | 浏览器同域路径 |
| `upstream` | 必填 | 上游根或完整 URL;支持 `$ENV` |
| `stream` | `True` | `True`:响应按上游 `Content-Type` 管道转发(含 `text/event-stream`) |
| `strip_prefix` | 空 | 转发前去掉本站前缀 |
| `methods` | `POST` | 允许方法 |
| `headers_from_env` | 空 | `ENV=Header-Name` 注入(密钥不进前端) |
| `timeout_ms` | 插件默认 | 上游超时 |
中文:`## 代理` / `流式=` / `上游=` / `去前缀=`。
### 2.2 ABI / 插件行为
| 步骤 | 行为 |
|------|------|
| 注册 | `web_app_proxy` 写入 `AppState` 路由表 |
| 请求 | 读 body + 过滤危险 hop-by-hop 头;合并 env 注入头 |
| 上游 | `reqwest`/`hyper` 流式客户端(插件内,不进核心) |
| 响应 | 复制状态码与 `content-type`;`body` 为 stream;SSE 不整段缓冲 |
| CORS | 仍走既有 `configure cors=`(同域调用时浏览器不依赖上游 CORS) |
### 2.3 与 `lib/net.http_post_sse` 关系
| API | 角色 |
|-----|------|
| `http_post_sse` | **出站消费者**(CLI/agent 侧收齐 events) |
| `app.proxy` | **入站中继**(浏览器 ← Marqdo ← 上游) |
二者互补,不互相替代。
### 2.4 验收
- 金样:mock 上游发两帧 SSE,浏览器侧(或 `curl -N`)收到两帧且中间无全缓冲延迟门槛。
- 密钥仅出现在服务端 env 注入头。
- 金样名建议:`tests/ext/web-proxy-sse-smoke.mq.md`。
---
## 3. GAP-02 · `app.invoke` / `configure invoke=`(HTTP → `##`)
### 3.1 作者 API
```markdown
*应用 = > `应用`.invoke path="/api/沉淀" method=POST fn="run.沉淀"*
```
表形式:
```markdown
*应用 = > `应用`.configure invoke=`调用表`*
| path | method | fn | body | return |
|------|--------|-----|------|--------|
| /api/note | POST | run.写出 | json | json |
| /api/search | GET | db.recent | query | json |
```
| 列 / 参数 | 含义 |
|-----------|------|
| `path` / `method` | HTTP 路由 |
| `fn` | `库.成员`(入口模块已 `import`)或 `模块路径##标题`(白名单前缀内) |
| `body` | `json` \| `form` \| `query` \| `raw` → 映射到 `##` 形参(同名优先;其余进 `payload` 袋) |
| `return` | `json`(默认)\| `text` \| `status` |
中文:`## 调用` / `函数=` / `正文=` / `返回=`。
### 3.2 安全默认(锁定)
1. **仅**解析入口 workbook 已导入的 `bind` 路径,或 `invoke_allow=` 显式前缀列表。
2. 单请求超时 + 可选并发上限(防 listen 线程饿死)。
3. 默认不启;作者显式 `invoke` / `configure invoke=`。
4. 错误:`{ok:false, error}` + HTTP 4xx/5xx;不把内部路径栈默认回传生产模式。
### 3.3 ABI / 插件行为
| 步骤 | 行为 |
|------|------|
| 注册 | `web_app_invoke` 存 `(path, method, FnRef)` |
| 命中 | 解析 body → Value 袋;`call_lib_path` / 等价「同步调用已加载模块的 `##`」 |
| 返回 | Value → JSON(复用现有 host JSON 通路);侧效(写盘)在同一解释器事务语义内尽最大努力 |
**不**把 `json=` DB 路由改语义;`invoke` 是平行装配。
### 3.4 与 compose 期 `call_lib_path` 关系
| 时机 | API |
|------|-----|
| 装配页 | 现有 compose / `call_lib_path` |
| **每个 HTTP 请求** | 本设计 `invoke` |
### 3.5 验收
- `POST` JSON → 用户 `##` 写入临时文件 + 返回 `{ok:true,…}`。
- 未导入路径 → 4xx,不执行。
- 金样:`tests/ext/web-invoke-smoke.mq.md`。
---
## 4. GAP-03 · MCP Server(`ext/ai`)
### 4.1 作者 API
```markdown
*服务 = > agent.mcp_server name="marqdo-qd"*
*服务 = > `服务`.tool name="qd_search" fn="求道.搜索" description="关键词检索"*
*服务 = > `服务`.tool name="qd_capture" fn="求道.捕捉"*
*服务 = > `服务`.serve transport=stdio*
# 或
*服务 = > `服务`.serve transport=http host=127.0.0.1 port=7433*
```
工具表:
| name | fn | description |
|------|-----|-------------|
| qd_search | 求道.搜索 | … |
| qd_list | 求道.列出 | … |
### 4.2 传输
| transport | 用途 |
|-----------|------|
| `stdio` | Cursor / Claude Desktop 拉起 |
| `http` | Streamable HTTP(与官方 MCP 演进对齐;首版可先 SSE+POST 子集) |
### 4.3 与 A4 fixture 客户端关系
| API | 方向 |
|-----|------|
| `mcp_list_tools` / `mcp_call` | **出站**(Agent 调外部 MCP;现 fixture) |
| `mcp_server` + `serve` | **入站**(外部调 Marqdo) |
客户端「真 MCP」仍见 agent 缺口文;本设计先交 Server,fixture 可保留测客户端。
### 4.4 ABI
- `plugins/agent`:`agent_mcp_server_*`(注册工具、stdio loop、可选 HTTP)。
- 工具实现:复用 GAP-02 同款「调用 `##`」内核(可抽共享 `invoke_fn`),避免两套分发。
- 返回包装:可含 `authority=workbook`。
### 4.5 验收
- 金样:stdio 夹具发 `tools/list` + `tools/call`,断言 JSON-RPC 形结果。
- 可选:`tests/ext/agent-mcp-server-smoke.mq.md`。
---
## 5. GAP-04 · 同寿副端口
### 5.1 关闭策略(优先)
GAP-01 + GAP-02 挂在**同一** `app.listen` → **不实现副端口**,文档宣布 GAP-04 关闭。
### 5.2 备选 API(仅当必须隔离)
```markdown
*应用 = > `应用`.listen host=127.0.0.1 port=18081 also_port=7432 also_routes=`中继表`*
```
`also_routes` 仅允许 `proxy` / `invoke` 已注册子集。实现成本高,**默认不做**。
---
## 6. GAP-05 · 跨模块 `db` 与 corpus 可发现
### 6.1 `db` 句柄(扩展约定 + 运行时)
**作者约定(立即文档化):**
1. 跨模块优先传 **`url` 字符串**,调用方 `*store = > web.db url=…*` 再 `select`。
2. 若传对象:必须保留 `_type` 为插件注册名(与 `web.db` 构造一致)。
**运行时修补(H 波次):**
| 选项 | 做法 | 选用 |
|------|------|------|
| A | 跨模块返回插件对象时规范 `_type` + 全局方法表查找 | **首选**(一次修好所有插件对象) |
| B | `db.open` 只返回 `{url}` 朴素 map,禁止「裸 select」跨文件 | 文档契约;体验较差 |
金样:模块 A `open` → 返回 → 模块 B `select` 成功。
`tests/ext/web-db-cross-module-smoke.mq.md`。
### 6.2 `corpus_search` 可发现
```markdown
## corpus_search
+ `query`
+ `root`=".marqdo/agent-kb"
* > plugin.load name=agent *
** > agent_corpus_search query=`query` root=`root` **
```
或在 `# agent` / `## corpus_search` 入口统一 `ensure_plugin`(与现 `agent` 构造对齐),保证 **纯 `marqdo run` + import agent** 即可用。
**不**把 `agent_corpus_search` 搬进 `src/host/`。
### 6.3 验收
- 无显式手工 ABI 名的情况下,`marqdo run` 金样调用 `agent.corpus_search` 成功。
- 跨模块 `db.select` 金样绿。
---
## 7. 扩展库表面清单(落地时改这些文件)
| 文件 | 增补 |
|------|------|
| `ext/web/web.mq.md` · `网页.mq.md` | `## proxy` / `## invoke`;`configure` 增 `proxy`/`invoke` 列 |
| `plugins/web/src/http.rs` · `middleware.rs` · 新 `proxy.rs` / `invoke.rs` | 路由注册与流式/调用 |
| `ext/ai/agent.mq.md` · `智能体.mq.md` | `# mcp_server` · `## tool` · `## serve`;`corpus_search` ensure_plugin |
| `plugins/agent/` | MCP Server 传输 + 共享 invoke |
| `tests/ext/web-proxy-sse-smoke.mq.md` 等 | 见上 |
| `doc/roadmap/ext-web.md` | 链到 H 波次(不重开 W0–W7) |
| `public/` / Skill | 发版时补「同域 LLM 代理 / HTTP 调用 ##」短节 |
**不**新增 `lib/run` 作为核心依赖:用户业务 `##` 仍在其自己的 `lib/*.mq.md`;Marqdo 只提供 **invoke 管道**。
---
## 8. 迁移:下游旁路 → 扩展 API
| 旁路(下游) | 替换为 |
|--------------|--------|
| `llm_proxy.py` `/proxy/stream` | `app.proxy` / `configure proxy=` |
| `llm_proxy.py` `/store/*` + `marqdo run` | `app.invoke` → 用户 `##` |
| `mq_bridge.py` 仅过滤 | 用户 `##` 内 `table`/`re` 过滤,或修复后的 `corpus_search` |
| `qdagent_mcp.py` | `agent.mcp_server` + `serve` |
| `mq.sh` 双进程 | 单 `marqdo run index.mq.md`(proxy+invoke 同端口) |
---
## 9. 开放点(实现前拍板)
| # | 问题 | 默认倾向 |
|---|------|----------|
| 1 | `invoke` 的 `fn` 是否允许 `path.mq.md##标题` 字面量 | 允许但必须 `invoke_allow` 前缀 |
| 2 | MCP HTTP 首版范围 | stdio 先交;HTTP 跟一波 |
| 3 | 代理是否缓冲「非 SSE」大 body | 非流式可限长缓冲;SSE 禁止整段缓冲 |
| 4 | GAP-05 选项 A vs B | **A** |
---
## 10. 完成定义(整包)
1. 无 Python 旁路即可:浏览器同域 SSE 对话 + HTTP 触发沉淀 `##` +(可选)MCP stdio 暴露同一批 `##`。
2. 金样覆盖 proxy / invoke / cross-db / corpus / mcp-server(stdio)。
3. `doc/research/ext-hosting-gaps.md` 各 GAP 标为关闭或降级为「备选副端口不做」。
4. 发版说明指向 `ext/web` · `ext/ai` 新作者面,不指向 `scripts/*.py`。
+235
View File
@@ -0,0 +1,235 @@
# `ext/linalg` — 公式文档面(跑通即正确)
| | |
|---|---|
| 状态 | **Draft · 锁定作者面哲学与分期** |
| 日期 | 2026-09-07 |
| 父设计 | [ext-linalg.md](ext-linalg.md) |
| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) |
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
| 对照 | [stdlib-math.md](stdlib-math.md)(高中标量公式) |
---
## 0. 一句话
**`.mq.md` 里的线性代数应当读起来像一份可运行的公式讲义**:式子能跑通,就在库承诺的规则与维数下代表正确;`lib/math` 守高中边界,大学符号矩阵与更深层计算由 **`ext/linalg` 正当承担**。
---
## 1. 产品哲学
### 1.1 与 Marqdo 总原则对齐
| Marqdo | 在线性代数上的含义 |
|--------|-------------------|
| 代码即文档 | 矩阵代数段落用数学式书写,而不是 API 调用清单 |
| 标记即语法 | `$$`、中缀、`# matrix` 方法都是可读标记,不是「库胶水」 |
| 跑通可验收 | 金样 / 课堂作业:文件 exit 0 + 断言化简结果 = 式子合法 |
### 1.2 「跑通即正确」的精确定义
**不是**「任意高深定理自动证明」。
**是**在声明的能力边界内,下列任一成立则文档该段视为正确:
1. **形状层**:不相容维数的乘加在构造时硬错误(写不出可运行的坏式)。
2. **恒等式层**:文档断言的规范形(如 `(AB)^\top → B^\top A^\top`)经规则集得到。
3. **数值核对层**(可选):小 `$$` 数值阵 `explicit` 后与手算一致——验算,不是符号证明。
更高深主题(矩阵微积分、表示、特殊函数矩阵等)通过**扩展同一公式面的规则表**分期加入,而不是另起一套函数库叙事。
### 1.3 与 `lib/math` 的边界(再次锁定)
| | `lib/math` | `ext/linalg` |
|--|------------|--------------|
| 教育边界 | 高中标量公式 | 大学经典线性代数及更深(官方 ext) |
| 值类型 | `Value::Formula`(标量 AST) | `_type=matrix` / `矩阵`(MatExpr + 稠密) |
| 作者感觉 | `$$sin(x)+x$$` + `diff` / `plot` | `A*B`、`(AB)^T`、分块、分解图 |
| 是否「数学库」 | 是(stdlib) | **是数学库的官方扩展**,不是旁路工具箱 |
把大学 LA 塞进 `lib/math` ❌;在 `ext/linalg` 做大学符号计算乃至更深 ✅。
---
## 2. 两面模型:代数面 vs 计算面
文档里应能一眼分清「推导」与「动手算」。
### 2.1 代数面(默认;公式文档)
| 意图 | 写法(目标) | 语义 |
|------|--------------|------|
| 引入符号阵 | 见 §3 | 惰性 `MatrixSymbol` |
| 加减乘 | `` `C` = `A` + `B` `` · `` `P` = `A` * `B` `` | 建树 + 形状检查 |
| 转置 / 逆 | `` `At` = > `A`.T `` · `` `Ai` = > `A`.inv `` | 惰性节点 |
| 化简 / 展示 | 见 §4(默认化简策略) | 规则不动点 → ASCII / KaTeX |
| 分块 / Kronecker | 表或 `block` / `kron`(可保留具名,但结果仍是公式) | 惰性 |
**读者感受**:像在抄黑板,而不是在调 `la.mul`。
### 2.2 计算面(显式步骤;可单独成段)
| 意图 | 写法 | 语义 |
|------|------|------|
| 稠密求值 | `` `E` = > `A`.explicit `` / `la.explicit` | 展开数值 |
| 分解 | `` `f` = > la.factorize matrix=`A` kind="svd" `` | `linalg_factor` |
| 求解 / 最小二乘 | `solve` / `lstsq` | 数值解 |
| 度量 | `norm` / `cond` / `rank` / `det`(数值路径) | 标量或条件对象 |
| 作图 | `draw` / `show` | SVG / 公式卡 |
**读者感受**:「于是我们计算 / 画出…」——与纯代数叙述分段书写。
---
## 3. 目标作者语法(公式文档优先)
### 3.1 已落地(v1 中缀 / 方法)
```markdown
*`A` = > la.symbol name="A" rows=2 cols=2*
*`B` = > la.symbol name="B" rows=2 cols=2*
*`C` = `A` + `B`*
*`P` = `A` * `B`*
*`Pt` = > `P`.T*
*`s` = > `Pt`.simplify*
*`t` = > `s`.ascii*
```
数值 `$$` 矩阵可直接参与 `+` / `*`(经插件吸收为稠密叶)。
### 3.2 目标形态(文档感更强;分期实现)
**叙事理想(不必一次做完):**
```markdown
# 正规方程
令 \(A\) 为 \(m\times n\) 设计矩阵,\(b\) 为观测。
*`AtA` = > `A`.T * `A`* # 或未来更紧凑的 postfix / 混合写法
*`xty` = > `A`.T * `b`*
*`xhat` = > `AtA`.solve b=`xty`* # 计算面
```
**符号引入(减少 `la.symbol` 噪音)——候选(F2 选定一种):**
| 候选 | 例 | 利 | 弊 |
|------|----|----|-----|
| A. 构造糖 | `` `A` = > la.matrix name=A rows=m cols=n `` | 已有 `# matrix` | 仍是调用 |
| B. 维数表 | GFM 表声明符号与形状,一行绑定 | 很「文档」 | 需新约定 |
| C. `$$` 符号方言 | `$$A_{m\times n}$$` → MatExpr | 最像讲义 | 解析歧义;勿污染标量 formula |
| D. 保持 `symbol` + 短别名 | `` `A` = > la.A rows=m cols=n `` | 实现便宜 | 文档感一般 |
**锁定倾向:** 短期 **A + 默认化简(F1)**;**F2 采用 B(GFM `@` 表 + `la.declare`)**;受限 C(`$$` 符号方言)仍待评估且不得污染核心 formula。
### 3.3 明确不做(本波语法)
- 把符号 MatExpr 塞进核心 `formula::Expr`
- 发明与 Markdown 列表冲突的行首 `+` 矩阵语法
- 用未定义的 `$$矩阵A$$` 伪方言冒充已实现语义
---
## 4. 默认化简与「写出即规范」
### 4.1 策略
| 操作 | 是否自动 `simplify` | 理由 |
|------|---------------------|------|
| `ascii` / `latex` / `show` | **是(F1 done)** | 展示面应接近讲义规范形;`raw=True` 可关 |
| 中缀 `+` `*` `-` 的构造结果 | **否** | 保留用户书写结构;需要时再化简 |
| `.simplify` | 显式不动点 | 文档断言 / 金样 |
| `explicit` 前 | 可选先 simplify(F1.1) | 减少无效稠密路径 |
### 4.2 验收句式(金样)
```markdown
*`P` = `A` * `B`*
*`Pt` = > `P`.T*
*`t` = > `Pt`.ascii* # F1:无需再 .simplify 即得 B^T*A^T
1. `t` == "B^T*A^T"
> print text=ok
```
「跑通 + 断言」= 这段公式文档正确。
---
## 5. 正确性分层与错误体验
| 层 | 失败时 | 作者应看到 |
|----|--------|------------|
| 形状 | `A*B` 列行不配 | 含双方 shape 的硬错误,指向调用点 |
| 规则 | 无法化到文档期望形 | 金样失败;或 `ascii` 仍为未化简形(需补规则) |
| 插件未加载 | 中缀矩阵运算 | 提示 `ext add linalg` / `ensure_plugin` |
| 超维 | `explicit` / 分解 | 护栏错误,建议保持符号 |
---
## 6. 与实现现状的对照
| 能力 | 状态 |
|------|------|
| MatExpr 惰性树 + R1–R5 / 分块 / kron | done(L1–L3) |
| 稠密 / 分解 / 度量 / draw theme | done(L2–L6) |
| 中缀 `+` `-` `*` + `# matrix` 方法 | done(v1) |
| `ascii`/`latex`/`show` 默认 simplify | **done(F1)** |
| 更少噪音的符号引入 | **done(F2:`declare` + 表)** |
| 更紧凑转置 / 混合公式书写 | **done(F3:`T_ascii`)** |
| `explicit` 前可选 auto-simplify | **done(F3,默认开)** |
| public「如何写公式文档」 | **done(F3)** |
| 矩阵微积分等 | L7+ / 规则表扩展 |
---
## 7. 分期(公式文档面)
| 阶段 | 内容 | 出口 |
|------|------|------|
| **F1** | 展示路径默认 simplify;金样「`.T` + `ascii` → 规范形」;设计本文落地 | **done** |
| **F2** | 符号引入降噪(选定 §3.2 候选);更新 examples 使其读起来像讲义 | **done**(`declare` + `linalg-transpose`) |
| **F3** | 可选 postfix / 链式糖;`explicit` 前可选 auto-simplify;public 短文「如何写公式文档」 | **done** |
| **F4+** | 新规则(伴随、多项式矩阵…);矩阵微积分仅当明确需要 | 规则表可测 |
---
## 8. 示例叙事(目标文档骨架)
````markdown
---
import la:ext/linalg/linalg.mq.md
---
# 转置反序
*`A` = > la.symbol name="A" rows=2 cols=3*
*`B` = > la.symbol name="B" rows=3 cols=2*
*`P` = `A` * `B`*
*`Pt` = > `P`.T*
叙述:\((AB)^\top = B^\top A^\top\)。
*`t` = > `Pt`.ascii*
1. `t` == "B^T*A^T"
> print text=identity-ok
2. *
> print text=identity-fail
````
计算面示例保持 `examples/linalg-least-squares/`(`lstsq` + heatmap),与代数面示例分目录或分章节。
---
## 9. 开放问题
1. **自动 simplify 是否改变 `ascii` 金样**——凡依赖「未化简乘积串」的测试需改期望或改调 `repr_raw`(若提供)。
2. **中文 `_type=矩阵` 与展示**——方法链已 retag;view 是否统一显示英文 kind。
3. **`$$` 符号方言**——若做,必须经 `from_formula` 扩展,禁止改核心高中 formula 语义。
---
## 10. 收束
`ext/linalg` 的北极星不是「功能最多的矩阵库」,而是:
> **让大学线性代数(及更深)以可运行公式文档的形式存在于 Marqdo;跑通即在规则集内正确;计算与作图是显式步骤,不淹没代数叙述。**
+345
View File
@@ -0,0 +1,345 @@
# `ext/linalg` — 公式优先的线性代数扩展
| | |
|---|---|
| 状态 | **Draft · L0–L6 + 中缀 v1 · 公式文档面见专文** |
| 日期 | 2026-09-07 |
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
| **公式文档面** | [ext-linalg-formula-doc.md](ext-linalg-formula-doc.md)(跑通即正确 · 代数面/计算面) |
| 路线图 | [roadmap/ext-linalg.md](../roadmap/ext-linalg.md) |
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [view.md](view.md) · [ext-quantum-q7.md](ext-quantum-q7.md) |
| 安装(规划) | `marqdo ext add linalg`(`linalg` / `线性代数`) |
---
## 0. 一句话
**经典线性代数以「矩阵公式」为一等公民**:抽象表达式可化简、可展示、可选求值;稠密数值与分解图走 ABI 插件——**不**并入 `lib/math`,**不**挂在 `ext/quantum` 作者面。
作者面北极星见 **[ext-linalg-formula-doc.md](ext-linalg-formula-doc.md)**:跑通即正确;代数面像讲义,计算面是显式步骤。
---
## 1. 目标与非目标
### 1.1 目标
1. **公式类扩展**:在现有标量 `formula` 之上,引入 **矩阵表达式(MatExpr)**——`MatrixSymbol`、乘加、转置、逆、迹、行列式、分块、Kronecker——默认**不展开**。
2. **大规模优化**:形状检查 + 重写规则 + 惰性求值 + 分解对象复用(见 §5)。
3. **易于展示**:KaTeX 公式卡、结构 SVG(SVD/QR/消元/特征)、数值热力图;CLI 可断言的 ASCII。
4. **文档即实验**:GFM 表声明矩阵 / 步骤;`.mq.md` 可读可跑。
### 1.2 非目标(首版)
| 不做 | 原因 |
|------|------|
| 塞进 `lib/math` | 高中标量范围已锁定;大学 LA 属官方 ext |
| 复用 `quantum.*` 作者 API | 领域混淆;量子 Q7 保持量子语义 |
| 完整 SymPy / Mathematica | 规则表可控子集即可 |
| 稀疏格式 / GPU / 分布式 | 超出文档语言定位 |
| 矩阵微积分闭式(Jacobian 积木) | 记入路线图远期 |
| 在 `ext/**` 调 `host_*` | 硬约束;数值走插件名 |
---
## 2. 分层架构
```text
作者 .mq.md
│ import la:ext/linalg/linalg.mq.md
▼
L1 官方 ext(GFM + ## 包装,中英分文件)
│ plugin.load name=linalg
▼
plugins/linalg(ABI v2)
├── matexpr:符号树构造 / 重写 / latex
├── dense:稠密 f64(可选复数)运算与分解
└── draw:结构 SVG / heatmap
│
▼(可选)
核心 Value::Formula 仅保留「数值矩阵字面量」现状;
符号 MatExpr 以 **map `_type=matrix`(中文构造为 `矩阵`)** 承载,避免撑爆高中 formula AST;遗留标签 `linalg_expr` / `linalg_dense` 仍可解析。
```
### 2.1 为何 MatExpr 不直接塞进 `formula::Expr`
| 方案 | 利 | 弊 | 决策 |
|------|----|----|------|
| 扩展 `formula::Expr` | 与 `$$` 一体 | 核心膨胀;高中/大学边界糊 | ❌ |
| 插件侧表达式 + L1 对象 | 核心干净;可独立发版 | 需稳定 `_type` 与 latex 桥 | ✅ **采用** |
| 仅 list-of-list 数值 | 简单 | 无法公式优化与符号展示 | ❌ 仅作 `explicit` 结果 |
**既有** `formula::Expr::Matrix`(数值 `$$`)继续服务量子门 / 小例子;`ext/linalg` 通过 `la.matrix` / `la.from_formula` 吸收为稠密叶子。
### 2.2 与量子的边界
| | `ext/linalg` | `ext/quantum` Q7 |
|--|--------------|------------------|
| 域 | 经典实/复矩阵 | 态 / 密度 / Pauli |
| Kronecker | 经典 ⊗ | 复合量子系统 |
| 图 | SVD/QR/GE/heatmap | hinton/city/qsphere/… |
| 复用 | 插件**私有**可共享 Jacobi/SVD 代码 | 作者面 API **分离** |
---
## 3. 运行时对象(锁定草案)
全部经插件构造,L1 返回 **map**(`_type` 稳定,金样可断言):
| `_type`(英) | 中文标签 | 字段(最小) | 含义 |
|---------------|----------|--------------|------|
| `linalg_expr` | `线性式` | `repr`(S-expr 或内部 id)、`shape`=`[m,n]` 或符号维、`latex`、`ascii` | 抽象矩阵公式 |
| `linalg_dense` | `稠密阵` | `rows`, `cols`, `data`(行主 list[list])、`dtype`=`real`\|`complex` | 显式数值 |
| `linalg_factor` | `分解` | `kind`=`lu`\|`qr`\|`svd`\|`eig`\|`chol`,因子字段,`latex`,可选 `svg` | 分解结果 |
| `linalg_svg` | — | `kind`, `svg` 文本 | 与 quantum_svg 同构展示约定 |
| `linalg_solve` | `求解` | `x`, `residual`, `method` | 线性系 / 最小二乘 |
形状:`shape` 允许整数或符号维名(字符串 `"n"`);不相容 → 硬错误。
---
## 4. 作者面 API(英文 `ext/linalg/linalg.mq.md`)
中文镜像:`ext/linalg/线性代数.mq.md`(`矩阵` / `化简` / `求值` / `绘图`…)。
### 4.1 构造
```markdown
# matrix
## symbol
+ `name`
+ `rows`
+ `cols`
# → linalg_expr MatrixSymbol
## eye / zeros / ones / diag
+ …
## from_list
+ `data` # list[list] 或 table
## from_formula
+ `formula` # 吸收 Value::Formula Matrix 字面量
## block
+ `blocks` # 表或嵌套 list of expr
```
文档写法偏好:
````markdown
`A` = > la.symbol name=A rows=n cols=n
`b` =
$$
\begin{pmatrix}1\\0\\0\end{pmatrix}
$$
*`b` = > la.from_formula formula=`b` *
````
作者面优先顶层 `la.symbol` / `la.mul`(`la.matrix.symbol` 无接收者会硬错误,见 [module-namespace.md](module-namespace.md) §4.3)。
### 4.2 公式代数(返回 `linalg_expr`,惰性)
| 英文 | 中文 | 语义 |
|------|------|------|
| `mul` / `add` / `sub` | `乘` / `加` / `减` | 形状检查后建树 |
| `transpose` / `T` | `转置` | |
| `inv` | `逆` | 符号逆;不立即求数值 |
| `pow` | `幂` | 整数幂 |
| `trace` / `det` | `迹` / `行列式` | 可得到标量 expr 或数值 |
| `kron` | `克罗内克` | **禁止**默认 expand |
| `simplify` | `化简` | 应用 §5 规则集 |
| `collapse` | `分块化简` | 对标 `block_collapse` |
| `latex` / `ascii` | `乳胶` / `文本` | 展示字符串 |
| `shape` | `形状` | |
链式 / 中缀(v1 已落地):
```markdown
*`C` = `A` + `B`*
*`P` = `A` * `B`*
*`Pt` = > `P`.T*
*`s` = > `Pt`.simplify*
```
运行时对双方为 `matrix` / `矩阵` / 数值 `$$` 矩阵 / 遗留 `linalg_expr` 的 `+` `-` `*` 分派到插件;结果保留左操作数 `_type` 以便中英方法链。
### 4.3 求值与分解(热路径 → 稠密)
| 英文 | 说明 |
|------|------|
| `eval` / `explicit` | 符号树 + 绑定表 → `linalg_dense`;超维硬错误 |
| `factorize` | `kind=lu\|qr\|svd\|eig\|chol` → `linalg_factor` |
| `solve` | `A`,`b`;或 `factor` + `b` |
| `lstsq` | 最小二乘 |
| `rank` / `norm` / `cond` | 数值度量 |
| `matmul` | 稠密乘(已 explicit 时) |
维数上限(草案,可配置):
| 操作 | 默认上限 |
|------|----------|
| `explicit` 稠密元素总数 | \(n\cdot m \le 10^4\)(如 100×100) |
| SVD / eig 方阵边长 | \(\le 64\)(与 quantum 密度同级) |
| 结构 SVG(无元素) | 边长示意可达数百(只画框) |
| KaTeX 完整数字阵 | \(\le 8\times 8\);更大只出摘要 + 结构图 |
### 4.4 展示
| 英文 | `kind` | 说明 |
|------|--------|------|
| `show` | — | 写入 view:优先 `latex` 公式卡 |
| `draw` | `structure` | 形状/分块矩形(drawmatrix 风格) |
| `draw` | `heatmap` / `hinton` | 数值幅度 |
| `draw` | `svd` / `qr` / `ge` / `eig` | 分解结构图(对标 LAFigureSpecs) |
| `draw` | `path`= | 可选落盘 SVG |
`show` 应对符号式**始终可用**(无需 `eval`)。
### 4.5 最小可运行示例(设计验收叙事)
````markdown
---
import la:ext/linalg/linalg.mq.md
import table:lib/table.mq.md
---
# main
*`A` = > la.symbol name=A rows=3 cols=3 *
*`x` = > la.symbol name=x rows=3 cols=1 *
*`b` = > la.mul a=`A` b=`x` *
*`s` = > la.simplify expr=`b` *
> la.show expr=`s`
`M` =
$$
\begin{bmatrix}2&0\\0&3\end{bmatrix}
$$
*`M` = > la.from_list data=[[2,0],[0,3]] *
*`f` = > la.factorize matrix=`M` kind=eig *
> la.draw factor=`f` kind=eig path=eig.svg
````
---
## 5. 公式重写与「大规模优化」(核心)
### 5.1 原则
1. **构造便宜,展开昂贵**——乘加只分配节点。
2. **形状是类型系统**——`(m×k)·(k×n)` 合法;否则错误指向调用点。
3. **化简是规则不动点**——有限规则表,可测、可文档化。
4. **expand 显式开启**——`expand=True` 才对 Kronecker / 多项式矩阵做爆炸性展开。
5. **数值路径旁路符号**——已 `explicit` 的叶子用稠密核,不再走规则。
### 5.2 v1 规则集(最小够用)
| ID | 规则 | 例 |
|----|------|-----|
| R1 | 单位元 | `I*A → A`,`A*I → A`,`A+0 → A` |
| R2 | 双逆 | `(A^{-1})^{-1} → A` |
| R3 | 转置反序 | `(AB)^\top → B^\top A^\top`,`(A^\top)^\top → A` |
| R4 | 逆转置 | `(A^{-1})^\top → (A^\top)^{-1}` |
| R5 | 结合扁平 | `MatMul` 链扁平化 |
| R6 | 分块塌缩 | 对标 `block_collapse`(乘/加在块级分配) |
| R7 | Kronecker 结合 | `(A⊗B)⊗C → A⊗B⊗C`;**不**展开成元素 |
| R8 | 标量提出 | `c*(A+B) → c*A+c*B`(可选;默认关以免树变宽) |
### 5.3 数值侧优化
| 策略 | 说明 |
|------|------|
| `factorize` 一次 | 多 RHS `solve` 复用 |
| 小阵专用核 | 2×2 / 3×3 闭式逆 / det(教学友好、可对照公式) |
| 复杂度护栏 | 超限错误信息建议「保持符号 / 降维 / 分块」 |
| 禁止静默降精度 | 病态 `cond` 可警告(stderr 或结果字段) |
---
## 6. 展示设计(效果)
### 6.1 通道
| 通道 | 符号 MatExpr | 稠密 | 分解 |
|------|--------------|------|------|
| view Structure | KaTeX `latex` 卡 | 小阵 KaTeX;大阵摘要 | 公式 + 可选 SVG |
| view Execution plots | — | heatmap SVG | `kind=svd|…` SVG |
| CLI `print` | `ascii` | `[[…],…]` 或摘要 | `svd(U,S,V)` 摘要 |
| writeback | 可选记录 latex | 可选 | 可选 |
### 6.2 LaTeX 约定
- 符号:`A`,`A^{\top}`,`A^{-1}`,`AB`,`A \otimes B`
- 数值小阵:`\begin{bmatrix}…\end{bmatrix}`
- 分块:`\begin{bmatrix} A & B \\ C & D \end{bmatrix}`
- 喂给既有 view:与 `formula-card` / KaTeX 同源路径(L1 `show` → `host_query("record_plot")` 或扩展「record_math」若已有;无则复用 writeback + plot 列表)
### 6.3 结构 SVG(教学主视觉)
对标 LAFigureSpecs / drawmatrix,**不**依赖 Matplotlib:
| `kind` | 画什么 |
|--------|--------|
| `structure` | 矩形块 + 标签(零块灰色) |
| `svd` | \(U\Sigma V^{\top}\) 块布局 + 秩分隔 |
| `qr` | 瘦/胖 QR 示意 |
| `ge` | 消元后上三角高亮 |
| `eig` | \(A=PDP^{-1}\) 或谱列表 + 对角 |
| `heatmap` | 单元填色(实数蓝红;复数幅值) |
主题:`theme=light|dark|bw`(与 quantum Q8 令牌对齐;默认 `light`)。
---
## 7. L1 / 插件 / CLI 约定
1. **`ext/linalg/**` 禁止 `host_*`**;只调 `plugin.*` 注册名(如 `linalg_simplify`)。
2. **中英分文件**,CATALOG 双 id:`linalg` / `线性代数`。
3. **`marqdo ext add linalg`**:与 web/agent/quantum 相同——优先 Release 预编译 native zip。
4. **金样**:离线、确定性;SVG 断言含关键子串或稳定 hash 前缀。
5. **依赖**:插件内自研稠密核(或慎重引入单一 crate,如 `nalgebra`——**实现期再议**;设计默认「可自研小维 + 可选 crate」)。
---
## 8. 分期(摘要;细节见路线图)
| 阶段 | 交付 |
|------|------|
| **L0** | CATALOG + ping + L1 `ensure_plugin` |
| **L1** | `matrix.symbol` / dense 构造 / `mul`·`T`·`inv` 树 + `simplify` R1–R5 + `latex`/`show` |
| **L2** | `explicit` / 小阵运算 / `solve` / `det`·`trace` 数值 |
| **L3** | 分块 + `collapse`;Kronecker 惰性 |
| **L4** | `factorize` LU/QR/SVD/eig + 结构 SVG |
| **L5** | heatmap/hinton;examples + public 文档 + skill 摘要 |
| **L6+** | 矩阵微积分 / 更大 BLAS(仅当用户明确要求);复数全路径算子 |
---
## 9. 验收标准(设计级)
1. 符号式 `(AB)^\top` 经 `simplify` 得 `B^\top A^\top`,**不**产生稠密数据。
2. 不相容形状在符号 `mul` 即失败。
3. `$$` 数值阵 → `from_formula` → `factorize kind=eig` → view 含 SVG 或 latex。
4. Kronecker 默认不 expand;显式 `expand` 受维数护栏。
5. 中英 L1 金样各至少一条;`ext add linalg` 路径文档化。
6. 与 `ext/quantum` 无作者面符号冲突。
---
## 10. 风险与开放问题
| 项 | 备注 |
|----|------|
| MatExpr 序列化 | 金样 / write:倾向可打印 S-expr 或稳定 latex+shape,避免不透明指针跨进程 |
| 与标量 `formula` 混运算 | v1:标量只作 `c*A` 系数;`det` 结果若符号则另型或降为 `formula` 文本 |
| nalgebra 等依赖 | 实现 L2 时评估二进制体积与 ABI 体积 |
| record_math vs plot | 若仅 SVG/KaTeX 字符串,可先复用 plot/writeback |
---
## 11. 一句话(收束)
**`ext/linalg` 让线性代数公式保持可优化的表达式,用规则与结构图服务文档阅读,用受控稠密核服务验算——公式优先,数值可选,展示分层。**
+1 -1
View File
@@ -210,7 +210,7 @@
- >6 qubit 稠密 ρ 的谱 / Hinton(请用态向量 API)
- Matplotlib / WebGL / 交互拖拽
- 量子线性系统算法(HHL)、QSVT 电路构造
- 把线性代数并入 `lib/math`
- 把线性代数并入 `lib/math`(经典公式优先的 LA 见规划 [ext-linalg.md](ext-linalg.md),作者面与 quantum 分离)
---
@@ -0,0 +1,74 @@
# 解决 1:路由与 `/admin` 前缀可让出
| | |
|---|---|
| 问题 | [研究 §1](../../research/ext-web-customization-limits.md#1-路由与路径被框架强占) |
| 优先级 | **P0** · 波次 **C0** |
| 触点 | `plugins/web/src/lib.rs`(`normalize_route_path`、`web_app_new`、redirect)· `plugins/web/src/http.rs`(admin 路由挂载、login redirect)· `ext/web/web.mq.md` / `网页.mq.md` |
---
## 1. 目标
1. 关闭内置后台后,**整段前缀可被站点路由占用**(含自研 `/admin`)。
2. 开启内置后台时,前缀**可配置**(默认仍 `/admin`),登录成功/登出落地页可配置。
3. `app.route` / `app.redirect` 只禁止**当前生效**的框架保留段,不再永久霸占 `/admin`。
---
## 2. 作者 API(草案)
```markdown
*应用 = > web.app page=`首页` db=`库` admin=False*
# 或:仍用内置 CRUD,但挂到旁路前缀 + 自定义回跳
*应用 = > web.app page=`首页` db=`库` admin=True*
*应用 = > `应用`.auth users=`用户表` admin_prefix="/desk" login_redirect="/desk" logout_redirect="/desk/login"*
```
| 参数 | 默认 | 含义 |
|------|------|------|
| `admin` / `后台` | `False` | `False`:**不注册**任何内置 admin HTTP 路由 |
| `admin_prefix` / `后台前缀` | `"/admin"` | 内置 CRUD + 登录页挂载根;仅 `admin=True` 时生效 |
| `login_redirect` / `登录回跳` | `{admin_prefix}` | 登录成功 303 目标 |
| `logout_redirect` / `登出回跳` | `{admin_prefix}/login` | 登出后目标 |
中文别名与英文一一对应,写进 `网页.mq.md`。
---
## 3. 插件改动点
| 改动 | 说明 |
|------|------|
| `normalize_route_path(app)` | reserved 列表改为:`/_form`、`/_part`、`/static` + **当前** `admin_prefix`(仅当 `admin=True`) |
| `listen` 路由表 | `admin=False` → **不** `.route("/admin…")`;为真则用 `admin_prefix` 拼路径 |
| `admin_login_post` / `admin_logout` | 使用配置的 redirect,禁止写死 `"/admin"` |
| `web_app_redirect` | 校验目标时用同一套动态 reserved,允许指向已让出的 `/admin` |
| disabled 文案路径 | 删除「挂路由但只显示 Admin is disabled」;无路由则 404 或落入站点自定义页 |
---
## 4. 兼容策略
- 缺省参数下:现有 `examples/web-site`、`web-net-site`、`marqdo-blog` 行为不变(仍 `/admin` + 跳 `/admin`)。
- 文档明确:`admin=False` 后若仍要登录能力,用 §3 的通用 `auth`/`gate`,不必再依赖内置 admin 壳。
---
## 5. 验收
| 金样 / 手工 | 期望 |
|-------------|------|
| `admin=False` + `route path="/admin/news"` | 注册成功;GET 渲染站点页,**不是** Admin is disabled |
| `admin_prefix="/desk"` | 内置登录在 `/desk/login`;成功跳 `login_redirect` |
| 默认 `admin=True` 无新参数 | 与现网一致 |
| `redirect` 到已让出的 `/admin` | 允许 |
---
## 6. 过渡期 → 已落地
~~继续用 `/desk` 旁路 + JS 调 `/admin/login`。~~
**C0 已落地(2026-09):** `admin=False` 可直接 `route path="/admin/…"`;或 `admin=True` + `admin_prefix="/desk"` + `login_redirect` / `logout_redirect`。见金样 `tests/ext/web-c0-admin-prefix.mq.md`。
@@ -0,0 +1,72 @@
# 解决 2:`SHELL_CSS` 可关 / 可分层
| | |
|---|---|
| 问题 | [研究 §2](../../research/ext-web-customization-limits.md#2-内置-shell_css-难以彻底覆盖) |
| 优先级 | **P1** · 波次 **C2** |
| 触点 | `plugins/web/src/render.rs`(`SHELL_CSS`、`<style>` 拼接)· page/app 元数据 · `ext/web` 样式装配 |
---
## 1. 目标
1. 站点主题可选择:**不要**框架栅格/卡片默认,或只要 reset 级变量。
2. 壳 CSS 与主题 CSS 的级联顺序**可声明、可文档化**。
3. 默认仍注入完整壳(兼容旧站);新主题显式 `shell_css=off` 即可干净起步。
---
## 2. 作者 API(草案)
```markdown
*应用 = > web.app page=`首页` … shell_css="minimal"*
# 或页面级覆盖
*页 = > `页`.meta …* # 或 page 选项 shell_css=
```
| 值 | 行为 |
|----|------|
| `full`(默认) | 现网 `SHELL_CSS` 全文 |
| `minimal` | 仅 `:root` 变量 + `body` margin/字体;**不含** `has-sidebar` 双列栅格与卡片表单皮肤 |
| `off` / `none` | 不注入框架壳样式;只输出站点 `style` / 外链 CSS |
级联顺序锁定为文档约定:
1. (可选)框架 `SHELL_CSS`
2. 站点全局 style 表 / `site.css`
3. 页面级 style
禁止再出现「主题写在 extra,却被同特异性壳规则在小屏打穿且无媒体查询」而无开关可关的情况。
---
## 3. 插件改动点
| 改动 | 说明 |
|------|------|
| 拆分 `SHELL_CSS` | `SHELL_VARS` / `SHELL_LAYOUT` / `SHELL_WIDGETS` 三段;`full`=`all`,`minimal`=vars(+极简 layout) |
| `render` 读 `app.shell_css` / `page.shell_css` | 页面覆盖应用 |
| 为 `has-sidebar` 布局加基础媒体查询 | 即使 `full`,小屏改为单列(减轻幽灵双列);`minimal`/`off` 不负责响应式 |
---
## 4. 兼容策略
- 默认 `full`:视觉与现网一致。
- Tutorial 增加一节「品牌主题请用 `shell_css=minimal|off`」。
---
## 5. 验收
| 场景 | 期望 |
|------|------|
| `shell_css=off` + 站点只写单列 grid | 响应里**无** `grid-template-columns:14rem` |
| `minimal` | 有 CSS 变量;无 `.content.cards article` 边框默认(或等价皮肤段) |
| 默认示例站 | HTML 仍含完整壳 CSS |
---
## 6. 过渡期 → 已落地
**C2 已落地(2026-09):** `shell_css=full|minimal|off`;页面/应用可设;`full` 含 `@media (max-width:720px)` 单列。金样 `tests/ext/web-c2-shell-layout.mq.md`。
@@ -0,0 +1,72 @@
# 解决 3:鉴权 / 门禁可配置且行为一致
| | |
|---|---|
| 问题 | [研究 §3](../../research/ext-web-customization-limits.md#3-鉴权--门禁模型偏固定) |
| 优先级 | **P0** · 波次 **C1**(依赖 [01](01-routes-and-admin-prefix.md) 的 prefix) |
| 触点 | `plugins/web/src/http.rs`(`rbac_middleware`、`path_matches`、login 表单)· `lib.rs`(`web_app_auth` / `web_app_gate`)· `ext/web` |
---
## 1. 目标
1. **未登录策略一致**:可配置 `redirect`(303 登录)或 `forbid`(403),对任意 gate 路径生效,不再「仅 `/admin*` 会跳登录」。
2. **匹配语义清晰**:支持精确路径、前缀、以及排除列表;`/desk` 默认**不**误伤 `/desk/login`。
3. 默认 admin gate 使用 **路径段边界**(`/admin` 与 `/admin/…`),不匹配 `/admin-publish`。
4. 登录 URL、表单 `action`、成功/失败回跳均可配置(与 C0 对齐)。
---
## 2. 作者 API(草案)
```markdown
*应用 = > `应用`.auth users=`用户表` login_path="/desk/login" login_redirect="/desk"*
*应用 = > `应用`.gate path="/desk" roles="admin" match="prefix" on_deny="redirect" exclude="/desk/login"*
```
| 字段 | 说明 |
|------|------|
| `login_path` | 登录页 URL(GET 表单 + POST 处理);默认 `{admin_prefix}/login` |
| `match` | `exact` \| `prefix`(默认对自定义 gate 建议 `prefix` + `exclude`) |
| `on_deny` | `redirect` \| `forbid`;`redirect` 时跳 `login_path`(可带 `?next=`) |
| `exclude` | 逗号分隔或表列:匹配前缀时放行的路径 |
`auth` 注册默认 gate 时:
- 使用 `{admin_prefix}` + 段边界,**不要** `starts_with("/admin")` 裸前缀。
- 自动把 `login_path` 加入放行列表。
---
## 3. 插件改动点
| 改动 | 说明 |
|------|------|
| `path_matches` | 增加 `exact`;`prefix` 要求下一字符为 `/` 或结尾;可选 exclude |
| `rbac_middleware` | 按 gate 的 `on_deny` 分支;通用放行 `login_path`,不写死 `/admin/login` |
| 登录 HTML | `action={login_path}`;hidden `next` 可选 |
| Session/CSRF | 短期仍用框架实现;文档标明字段名;中期再开放 `login_form` 自定义字段映射(非本波次必做) |
---
## 4. 兼容策略
- 未传新字段:行为对齐现网(`/admin*` → redirect 登录;其它自定义 gate → 403)。
- 新增金样:`/desk` gate + `/desk/login` 可匿名打开。
---
## 5. 验收
| 场景 | 期望 |
|------|------|
| visitor 访问 `/desk`(`on_deny=redirect`) | 303 → `/desk/login`,不是 403 |
| visitor 访问 `/desk/login`(exclude) | 200 登录页 |
| `/admin-publish` 无显式 gate | **不**被默认 admin gate 拦住 |
| 旧站仅 `app.auth` | 仍保护 `/admin*` |
---
## 6. 过渡期 → 已落地
**C1 已落地(2026-09):** `auth` 默认段边界 prefix + `on_deny=redirect` + 排除 `login_path`;自定义 `gate` 可设 `match` / `on_deny` / `exclude`。金样 `tests/ext/web-c1-gates.mq.md`;单元测试 `http::gate_tests`。
@@ -0,0 +1,69 @@
# 解决 4:样式表作者体验
| | |
|---|---|
| 问题 | [研究 §4](../../research/ext-web-customization-limits.md#4-样式作者体验受限) |
| 优先级 | **P2** · 波次 **C3** |
| 触点 | 表单元格表达式(T5)· `ext/web` style 装配 · 教程 / Skill · 可选校验 |
---
## 1. 目标
1. 含 `/`、`,`、括号的 CSS 值**不易被静默算坏**。
2. 复杂选择器 / `@keyframes` / 多层 media 有**官方推荐写法**(表内 vs 外链 vs raw 块)。
3. 与壳 CSS 的层叠关系在文档中一句话写清(并链到 [02](02-shell-css.md))。
---
## 2. 作者 API / 约定(草案)
### 2.1 立即固化的文档约定(可不改代码)
| 规则 | 说明 |
|------|------|
| 含 `/` 的值必须引号 | `"1 / 5"`、`"image/png"`(已有;Skill/教程加醒目反例) |
| 复杂皮肤优先外链 | `static/theme.css` + `page.head` / `app.icons` 同类资源表 |
| `@keyframes` / 长 media | 放外链 CSS,不塞进 GFM 单元格 |
| 调试 | `shell_css=off` 后只看主题文件,避免同页双源 |
### 2.2 产品增强(C3)
| 能力 | 说明 |
|------|------|
| `style` 装配时对可疑单元格告警 | 未加引号且含 `/` → listen/assemble 警告或硬错误(可开关) |
| 可选 `##` raw CSS 块绑定 | 例如页面附属 ````css` 具名块,**不经**表表达式求值 |
| 文档示例 | `min-width` + `max-width` 外链表;引用 [table-cell-expressions.md](../table-cell-expressions.md) |
---
## 3. 插件 / 核心改动点
| 改动 | 说明 |
|------|------|
| web style 编译 | 可选 `strict_css_cells=True`:裸 `/` 报错 |
| (可选)`web_page_css_raw` | 把文本 CSS 追加到页面,跳过 T5 |
| Skill `marqdo` / tutorial 14 | 增加「样式踩坑」小节 |
---
## 4. 兼容策略
- 默认不硬错误(避免打碎旧表);新 scaffold 默认 `strict_css_cells` 或文档强制引号。
- 不把完整 CSS 语法塞进表格方言——复杂内容走文件。
---
## 5. 验收
| 场景 | 期望 |
|------|------|
| 文档反例 `grid-column` 裸 `1 / 5` | 在 strict 模式下失败或警告 |
| 外链 `theme.css` + `shell_css=off` | 无壳栅格串扰 |
| 现有 web 示例 | 默认模式仍绿 |
---
## 6. 过渡期 workaround
全部敏感值加引号;响应式与 keyframes 只写在 `static/*.css`;小屏问题优先关壳([02](02-shell-css.md))再调主题。
@@ -0,0 +1,85 @@
# 解决 5:页面壳与插槽松绑
| | |
|---|---|
| 问题 | [研究 §5](../../research/ext-web-customization-limits.md#5-页面壳与插槽约定僵硬) |
| 优先级 | **P1** · 波次 **C2/C4** |
| 触点 | `plugins/web/src/render.rs`(body class、四区 HTML)· page 槽位装配 · nav 组件表 |
---
## 1. 目标
1. 作者可选**非侧栏栅格**布局,而不必用 CSS 硬怼掉 `has-sidebar`。
2. 侧栏存在 ≠ 强制桌面双列;提供 stacked / bare 等预设。
3. 为「条件导航」留扩展点(先文档 + 简单 hook,完整运行时条件可后置)。
---
## 2. 作者 API(草案)
```markdown
*首页 = > web.page … layout="stacked"*
*应用 = > web.app page=`首页` … layout="bare"*
```
| `layout` | DOM / class | 说明 |
|----------|-------------|------|
| `sidebar`(默认,有 side 槽时) | `body.has-sidebar` | 现网行为 |
| `stacked` | `body.layout-stacked`;side 在 main 上或折叠区 | 单列流式,适合杂志/营销 |
| `bare` | 无 top/side/foot 强制栅格;只渲染 `main`(+ 显式槽) | 登录页、落地页 |
| `rail`(可选) | 保留站点已有 `has-rail` 约定并文档化 | 避免「只有首页有 class」 |
规则:**有 side 组件但 `layout=stacked|bare` 时,不自动加 `has-sidebar`。**
---
## 3. 插件改动点
| 改动 | 说明 |
|------|------|
| `render` 读 `page.layout` / `app.layout` | 决定 body class 与 HTML 骨架 |
| `SHELL_LAYOUT`(见 [02](02-shell-css.md)) | 为 `layout-stacked` / `layout-bare` 提供最小样式;`shell_css=off` 时不注入 |
| Nav 表 | 短期保持声明式;文档说明「条件项用两套 nav 组件 + 媒体查询隐藏」 |
| 中期 hook(非阻断) | `navigate` 已有字段可扩展 `when`/`media` 列(单独 RFC) |
---
## 4. 兼容策略
- 未设 `layout`:有 side → 与现网 `has-sidebar` 相同。
- 金样增加 `layout=bare` 登录页(可与 C0 自研 `/desk/login` 共用)。
---
## 5. 验收
| 场景 | 期望 |
|------|------|
| 有 side + `layout=stacked` | body **无** `has-sidebar`;无 `14rem` 双列(在 full 壳下用 stacked 规则) |
| `layout=bare` | 输出不含 `<aside class="side">`(或 empty 不占栅格) |
| 默认站 | 不变 |
---
## 6. 过渡期 → 已落地
**C2 已落地(2026-09):** `layout=sidebar|stacked|bare|rail`;有 side 时 `stacked`/`bare` 不再强制 `has-sidebar`。金样 `web-c2-shell-layout`。
**C4 已落地(2026-09):** 导航 / 侧栏 / 页脚绑定表可选列:
| 列 | 说明 |
|----|------|
| `媒体` / `media` | CSS media;不匹配时 `display:none`(生成 `nav-mq-*` + `@media not …`) |
| `当` / `when` | `hide` 省略;`auth` / `guest` 按登录态过滤;空 = 总是显示 |
```markdown
| 属性 | 值 | 样式 | 媒体 | 当 |
|------|-----|------|------|-----|
| Home | / | | | |
| Menu | /m | | (max-width: 720px) | |
| Admin | /admin | | | auth |
| Login | /login | | | guest |
```
Listen 渲染时写入 `_logged_in` / `_nav_user`(来自 session)。离线 `page.render` 可自行 `table.put` `_logged_in`。金样 `web-c4-nav-when`。
@@ -0,0 +1,67 @@
# 解决 6:后台 CRUD 与表单能力边界
| | |
|---|---|
| 问题 | [研究 §6](../../research/ext-web-customization-limits.md#6-后台-crud-与表单能力边界) |
| 优先级 | **P3** · 随 C0 文档化;增强可选 |
| 触点 | `plugins/web/src/http.rs` / `form.rs`(内置 admin)· 站点自研页 + `db.*` · `/_form` |
---
## 1. 目标
1. **产品叙事澄清**:内置 `/admin`(或可配置前缀)= 通用表浏览器,**不是** CMS;关则彻底让路(见 [01](01-routes-and-admin-prefix.md))。
2. 自研后台的推荐路径写清楚:`page` + `form` + `db` + gate,而不是改插件壳。
3. 对「链接前缀 / new / edit」给出约定或薄辅助,减少前端状态机拼装。
---
## 2. 作者 API / 文档(草案)
### 2.1 推荐架构(文档为主)
| 需求 | 做法 |
|------|------|
| 产品级编辑器、专栏联动 | 自研 `# page` + 组件;写库用 `db.insert`/`update`;鉴权用 `gate` |
| 简单表维护 | 开 `admin=True`(可换前缀) |
| 关内置仍要 CRUD | 自研列表/编辑页;**不要**依赖 disabled 壳 |
### 2.2 可选薄增强(非 CMS)
| 能力 | 说明 |
|------|------|
| `form` 支持 `mode=new\|edit` 查询参数约定 | 文档 + 示例;必要时 `web.form` 读 `id`/`new` |
| `list` 组件 `link_prefix` | 已有则补示例;缺失则加一列「详情路径模板」 |
| Markdown 字段 | 继续「存库 + 前台渲染」;分栏编辑器保持外挂 JS(明确不做进 ABI) |
---
## 3. 插件改动点
| 改动 | 优先级 |
|------|--------|
| C0:disabled 不占路径 | 必需(属 [01](01-routes-and-admin-prefix.md)) |
| 示例 `examples/web-custom-desk/` | 展示自研列表/编辑,零内置 admin |
| form 查询参数助手 | 可选 |
---
## 4. 兼容策略
- 不扩展内置 admin 成 CMS(避免范围爆炸)。
- Tutorial 增加「何时用内置 admin / 何时自研」。
---
## 5. 验收
| 场景 | 期望 |
|------|------|
| 文档 + 示例 desk | 无 `/admin` 也能完成一文增删改 |
| 内置 admin 金样 | 仍绿 |
---
## 6. 过渡期 workaround
自研 `/desk` + 调用 `/_form` 或直接 DB API;复杂编辑器继续外挂 JS。
@@ -0,0 +1,71 @@
# 解决 7:静态资源与脚本生命周期
| | |
|---|---|
| 问题 | [研究 §7](../../research/ext-web-customization-limits.md#7-静态资源与脚本生命周期) |
| 优先级 | **P2** · 波次 **C3** |
| 触点 | `web_page_head` / `web_head` · `render.rs` head 输出 · static 挂载 · [web-assets-and-images.md](../web-assets-and-images.md) |
---
## 1. 目标
1. 默认脚本加载方式**不假设**作者手写 IIFE 抢在 DOM 前执行成功;提供 `defer` / `module` 一等约定。
2. 静态资源变更可发现:文档化 `?v=`,并提供可选自动指纹或 listen 时 mtime 查询参数。
---
## 2. 作者 API(草案)
Head 资源表扩展列(向后兼容):
| 列 | 说明 |
|----|------|
| `rel` / `关系` | 已有;`script` / `module` |
| `defer` / `推迟` | `真` → `<script defer>`(**建议默认对 script 为真**) |
| `async` / `异步` | 可选 |
| `version` / `版本` | 非空则自动追加 `?v=` |
```markdown
`头` =
| 关系 | 地址 | 推迟 | 版本 |
|------|------|------|------|
| script | /static/theme.js | 真 | 2026-09-04 |
| module | /static/desk.js | 真 | 3 |
```
全局:`app.asset_version="2026-09-04"` 为所有 static 链接统一 bump(可选)。
---
## 3. 插件改动点
| 改动 | 说明 |
|------|------|
| head 渲染 | 尊重 defer/async;`module` → `type="module"`(已有则核对) |
| 默认 | 新建 scaffold 的 script 行带 `defer` |
| (可选)`asset_version` | listen 时重写 head / 页面内 static URL |
| 文档 | 「禁止在同步 head 脚本里直接 `getElementById` 主节点;用 defer 或 `DOMContentLoaded`」 |
---
## 4. 兼容策略
- 旧表无 `defer` 列:保持现网同步行为(或仅对 scaffold/新文档默认 defer,避免静默改变旧站时序)。
- 更安全:缺省仍同步;**Skill 与 scaffold 默认写 defer=真**。
---
## 5. 验收
| 场景 | 期望 |
|------|------|
| defer 脚本读 DOM | 登录跳转逻辑在 DOM 就绪后执行 |
| `version` 列 | HTML 中出现 `theme.js?v=…` |
| 旧示例无新列 | 仍通过 |
---
## 6. 过渡期 workaround
脚本改 `type=module` 或放 body 末;手动 `?v=` bump;登录逻辑用 `DOMContentLoaded`。
@@ -0,0 +1,68 @@
# 解决 8:扩展与部署耦合
| | |
|---|---|
| 问题 | [研究 §8](../../research/ext-web-customization-limits.md#8-扩展与部署耦合) |
| 优先级 | **P3** · 文档 + 发布流程 |
| 触点 | `marqdo ext add web` · ABI 版本 · Docker/发布说明 · [ext-cli.md](../ext-cli.md) · [marqdo-release](../../../.cursor/skills/marqdo-release/SKILL.md) |
---
## 1. 目标
1. 站点作者**不必 fork 插件**才能完成 P0/P1 定制(把能力收进官方参数,见 01–05)。
2. 版本耦合可预期:changelog / 扩展清单标明「web 插件需 ≥ x.y.z」。
3. 升级路径文档化:二进制、`.marqdo-ext`、Docker 镜像三者对齐检查。
---
## 2. 作者 / 运维约定(草案)
| 约定 | 说明 |
|------|------|
| 定制优先走 `.mq.md` 开关 | `admin_prefix`、`shell_css`、`layout`、`gate`… 进官方 API 后,禁止文档再教「改 plugins/web」 |
| 兼容性矩阵 | 在 [web-net-capabilities.md](../web-net-capabilities.md) 或本目录维护「Marqdo ↔ libweb 最低版本」表 |
| `marqdo ext add web` | 安装后打印当前插件路径与版本;与 CLI 版本不符时警告 |
| Docker | 示例 Dockerfile 注释:升级需同时换 `marqdo` 与 `ext add` 产物 |
| 样式引号等行为变更 | 写入 CHANGELOG **Breaking / migration** 小节(如 0.3.2 T5) |
---
## 3. 工程改动点
| 改动 | 说明 |
|------|------|
| 插件/Crate 版本可见 | `web_listen` 或 `ext list` 显示 web ABI/包版本 |
| CI | 金样使用仓库内 `plugins/web`;发布技能检查 VSIX/CLI/插件三件套 |
| 研究→设计→路线图 | C0–C4 进 [ext-web roadmap](../../roadmap/ext-web.md),避免只活在私有 fork |
---
## 4. 兼容策略
- 不承诺插件源码级稳定 API;承诺 **`.mq.md` 作者 API** 在小版本尽量兼容,破坏性变更进 CHANGELOG。
- Fork 插件仅作为「官方尚未交付」的临时手段,并在 issue/路线图留归还项。
---
## 5. 验收
| 场景 | 期望 |
|------|------|
| 升级说明文档 | 运维按清单升级后 web 金样通过 |
| C0–C2 落地 | 自研后台场景**无需**改 `plugins/web` 源码 |
| `ext list` / 文档 | 能核对版本 |
---
## 6. 过渡期 → 预编译路径(进行中)
**目标:** 用户 `marqdo ext add web` **不必**本机 Rust。
| 交付 | 说明 |
|------|------|
| Release `marqdo-*-native-*.zip` | Windows / Linux 预编译 `web`/`agent`/`quantum` |
| Windows portable zip | 内含 `ext/` + `ext/native/*.dll` |
| `ext add` 下载回退 | 本地无 `.so`/`.dll` 时从 GitHub Release 拉取(`MARQDO_EXT_NO_DOWNLOAD=1` 可关) |
仍保留开发者 `cargo build -p marqdo_plugin_*` 路径。详见 [ext-cli.md](../ext-cli.md)。
@@ -0,0 +1,50 @@
# `ext/web` 定制修复:解决文档索引
| | |
|---|---|
| 状态 | **C0–C4 done** |
| 日期 | 2026-09-04 |
| 问题盘点 | [../../research/ext-web-customization-limits.md](../../research/ext-web-customization-limits.md) |
| 相关 | [../ext-web.md](../ext-web.md) · [../ext-web-net.md](../ext-web-net.md) · [../../roadmap/ext-web.md](../../roadmap/ext-web.md) |
对应研究文 §1–§8,每项一份解决文档:**目标 → 作者 API → 插件改动点 → 兼容策略 → 验收**。
实现时优先 **不破坏现有金样**(`tests/ext/web-*`、`examples/web-*`);新能力用显式 opt-in 参数打开。
---
## 文档一览
| # | 主题 | 文档 | 建议优先级 |
|---|------|------|------------|
| 1 | 路由与 `/admin` 前缀可让出 | [01-routes-and-admin-prefix.md](01-routes-and-admin-prefix.md) | P0 |
| 2 | `SHELL_CSS` 可关 / 可层 | [02-shell-css.md](02-shell-css.md) | P1 |
| 3 | 鉴权门禁可配置且行为一致 | [03-auth-gates.md](03-auth-gates.md) | P0 |
| 4 | 样式表作者体验 | [04-stylesheet-authoring.md](04-stylesheet-authoring.md) | P2 |
| 5 | 页面壳与插槽松绑 | [05-page-shell-slots.md](05-page-shell-slots.md) | P1 |
| 6 | 后台 CRUD / 表单边界 | [06-admin-crud-forms.md](06-admin-crud-forms.md) | P3 |
| 7 | 静态资源与脚本生命周期 | [07-assets-script-lifecycle.md](07-assets-script-lifecycle.md) | P2 |
| 8 | 扩展与部署耦合 | [08-ext-deploy-coupling.md](08-ext-deploy-coupling.md) | P3 |
---
## 波次建议(实现用)
| 波次 | 内容 | 依赖 |
|------|------|------|
| **C0** | 可配置 `admin_prefix`;`admin=False` 时不挂内置路由;`login_redirect` / `logout_redirect` | — |
| **C1** | gate:统一未登录策略;精确/前缀匹配;登录页自动放行;默认 gate 不再误伤 `/admin-*` | C0 |
| **C2** | `shell_css=off\|minimal\|full`;主题在壳前或隔离层;可选 `layout=bare` | — |
| **C3** | 样式:校验警告 / `strict`;`page.css` raw;脚本 `defer`/`async`/`version` + `asset_version` | **done** |
| **C4** | 壳:`layout` 预设(C2);条件导航 `when` / `media` | **done** |
路线图入口可在 [ext-web.md](../../roadmap/ext-web.md) 增补「定制波次 C0–C4」行,落地后再改状态。
---
## 产品原则(解法共同约束)
1. **`.mq.md` 仍是真相源** — 能声明的不进隐藏默认;新开关写在 `app` / `page` / `listen` 参数表。
2. **内置 admin 是可选产品**,不是不可替换的内核路由命名空间。
3. **默认行为保持兼容** — 现有 tutorial / 示例零改动仍能跑;新站显式打开定制。
4. **禁止**为单站需求永久硬编码第二套旁路(如永远推荐 `/desk` + JS fetch 登录)。
+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 波次** 推进;本文件为唯一施工图。
+5 -5
View File
@@ -2,9 +2,9 @@
| | |
|---|---|
| 状态 | **Accepted · W0–W7 + P3 完结**(SQLite/Postgres 作者面:页面装配 / db CRUD+`where` / form / 嵌入主区 / `app.route` / 路由 `/_part` / admin UI / RBAC / 上传相册 / SEO·RSS·sitemap;Postgres 等见 §9) |
| 日期 | 2026-08-11 |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [stdlib-i18n.md](stdlib-i18n.md) |
| 状态 | **Accepted · W0–W7 + P3 + W8(站点图标/Head/图片装配)完结**(SQLite/Postgres 作者面:页面装配 / db CRUD+`where` / form / 嵌入主区 / `app.route` / 路由 `/_part` / admin UI / RBAC / 上传相册 / SEO·RSS·sitemap / **favicon·头资源·图片装配**;Postgres 等见 §9) |
| 日期 | 2026-08-11(W8:2026-08-29) |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [stdlib-i18n.md](stdlib-i18n.md) · [web-assets-and-images.md](web-assets-and-images.md) |
| 安装(目标) | `marqdo ext add web`(中英:`web` / `网页`) |
| 本文目的 | 锁定**作者面**与**类 API**;指导实现 |
@@ -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)) | 不要求作者写袋 |
**实现要点(评审通过后再做):**
+55
View File
@@ -0,0 +1,55 @@
# 标准库 / 扩展库:代码即文档
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-09-14 |
| 相关 | [code-as-docs-gaps.md](code-as-docs-gaps.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md) · [collection-access-link.md](collection-access-link.md) · [stdlib.md](stdlib.md) · [marqdo-dev skill](../../.cursor/skills/marqdo-dev/SKILL.md) · [roadmap](../roadmap/lib-ext-code-as-docs.md) |
---
## 1. 目标
`lib/*` 与 `ext/*` 的 `.mq.md` 应**可当说明书读、可当程序跑**。薄库不写长文;厚领域库(web / quantum / …)仍用叙述承载意图,但数据与调用面与用户程序同一套标记。
## 2. 薄库模板(默认)
每个导出函数 / 方法尽量按此骨架(中英分文件锁步):
1. **目的句**(一句人话,无标记即可)。
2. **叙述形参**:正文里出现 `` `名` `` / `` `名`=默认 ``(推断签名);过渡期可保留 `` + `名` ``。
3. **一例**:粗体或 `>` 调用;优先可读表面。
4. **实现**:短;取元用 `[键](集合)`,**禁止新增**脚注取元 `` `m`[^k] ``(旧解析仍可用)。
调用示例(三种等价,试点期任选;新叙述优先括号标记或粗体):
```markdown
**出 = [put] 入=`表` 键="a" 值=1**
**出 = put 入=`表` 键="a" 值=1**
> put 入=`表` 键="a" 值=1
```
带布尔开关时可用前置修饰:`严格 [parse] text=`源`` → `严格=True`(形参名与修饰语字面一致;核心不剥「的」等词缀)。
## 3. 硬约束
| 要 | 不要 |
|----|------|
| GFM 表作数据;`table.put` / 具名助手 | `json.set` 链当字典构造器 |
| 作者程序用 `[k](c)` 取元;`- [项](集合)` foreach | 新代码写 `` m[^k] `` |
| 中英 API 对称(见 [stdlib-i18n.md](stdlib-i18n.md)) | 只改一侧 |
| 一例跑通即文档(public/stdlib 或 examples) | 另开第二套「文档站」手写说明 |
**库函数体内的叙述坑:** 函数体里的链接形 `[k](c)`、以及单独的 `**强调**` 会被当成可执行代码。库内说明用「链接取元 / link-index」等字面描述;可执行示例放在 `public/stdlib` 或 `examples/`,不要写在 `##` 体内当叙述。
## 4. 波次
见 [roadmap/lib-ext-code-as-docs.md](../roadmap/lib-ext-code-as-docs.md):先稳定调用表面,再 M1 试点 table/text/json,其后批次 lib → ext。
## 5. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿(随括号调用落地) |
+618
View File
@@ -0,0 +1,618 @@
# Marqdo 语法映射 v0.3(叙述统一 · 粗体即代码)
| | |
|---|---|
| 状态 | **Accepted · 现行运行时目标(实现中)** |
| 日期 | 2026-09-13 |
| 取代 | [markdown-mapping.md](markdown-mapping.md) **v0.2(已废止为运行时宪法)** |
| ADR | [0005-prose-unified-markup.md](../adr/0005-prose-unified-markup.md) |
| 路线 | [markup-v0.3.md](../roadmap/markup-v0.3.md) |
| 相关 | [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) · [call-arguments.md](call-arguments.md) · [objects.md](objects.md) · [keywords.md](keywords.md) |
> **名词:** 本文「Markup」指 Marqdo **如何把 Markdown 标记映射成语法**(`**` 代码、`*` 返回、`` `名` `` 声明),不是另一个语言。产品仍是 Marqdo。
> **v0.3 为唯一映射。** 不做 v0.2 双模式 / `--markup` 版本身份。摸索阶段允许破坏性变更;旧 `.mq.md`(`*语句*` / `**返回**`)须改写。金样例见 `tests/markup-v03/`。
---
## 0. 一句话
让 **Markdown 叙述本身成为程序的一部分**:普通文字里用 `` `名` `` 出现变量(首次未赋值 = 声明);用 **`**…**` 粗体** 包裹可执行代码(含调用,不必再写 `>`);用 **`*…*` 斜体** 表示返回值。函数形参**不再手写 `+` 列表**,由函数体内的声明/赋值自行推断。
---
## 1. 动机(为何推翻 v0.2 的部分定论)
v0.2 为了「标记即语法」的清晰边界,做了这些硬隔离:
| v0.2 | 代价 |
|------|------|
| 无标记行 = 纯注释;变量只能写在 `*…*` / 结构行里 | 叙述与代码割裂,「文档即代码」读起来像两套语言叠在一起 |
| `*…*` = 语句,`**…**` = 返回 | 与常见 Markdown/AI 习惯相反:模型更爱用 `**` 强调「要执行的东西」,读者也更易看见粗体 |
| 调用必须 `>` | 行间调用要另起结构行,叙述中夹调用不自然 |
| 形参必须 `` + `名` `` | 仪式感强;函数头像「另一套签名语言」,与正文脱节 |
古早示例(当时不能跑,正是本文要合法化的目标面):
```markdown
## 加一函数
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
# main
我要调用加一函数可以采用这样的办法:
> 加一函数 37
或者可以直接这么调用**加一函数 37**
```
目标:上述文件在 v0.3 下应能解析、求值,且**读起来仍是一篇正常中文说明**。
---
## 2. 哲学(设计原则)
### P1 — 叙述统一(Prose-unified)
- Marqdo 注释采用 **Markdown 叙述**(段落、列表中的说明文字),不是第二种注释语法。
- **变量可以出现在正常文字之间**:用 Markdown 行内代码 `` `n` `` 标识标识符。
- **第一次出现且未赋值 = 声明变量**;之后的出现 = 引用。赋值发生在粗体代码段内(或兼容的结构赋值形)。
- **未使用的变量无害**(不报错、不升参);真正的输入由「可执行面读取」升为形参(§8)。
- 这样「说明文字」与「程序名字」共用同一套 Markdown 视觉习惯,整体更和谐。
### P2 — 粗体即代码(Bold-as-code)
- **`**…**` = 代码段**(可执行):赋值、表达式、函数/方法调用、可内联的短语句。
- 选择粗体的原因:
1. **AI 输出偏好**:模型天然爱用 `**` 强调「重要操作」;把粗体定为可执行,降低「模型写了强调却被当成返回」的错配。
2. **行间显眼**:在长段落里,粗体比斜体更容易被扫到。
- 粗体代码段内的调用 **允许不写 `>`**:`**加一函数 37**` 与 `> 加一函数 37` 语义等价(见 §6)。
- **`>` 保留为可选调用面**(blockquote 风格、独立行、兼容 v0.2 迁移与 AI 已学会的形态)。
### P3 — 斜体即返回(Italic-as-return)
- **`*…*` = 返回值**(架构级),与粗体代码形成对立、易读的一对:
- 做了什么 → 粗体
- 结果是什么 → 斜体
- **空返回 / 无值收束**(已决议,见 §7.2):推荐 `*None*` / `*无*`;整行 `**`;兼容 `****`。`---` / `***` 仅为叙述分隔(跳过),**不再**结束函数体。
- **输出仍不是返回**:打印继续用内置 `print` / `打印`(副作用函数),不把粗体或斜体当成「打印到终端」的语法。
### P4 — 形参由体推断(Body-inferred params)
- **不再要求**作者手写 `` + `名` `` 形参表(v0.3 默认关闭;过渡期可兼容,见 §8)。
- 函数体内:
- **只声明、未赋默认** → **必选形参**(调用时必须提供)。
- **声明同时赋值**(含默认值字面量)→ **可选形参**(带默认值)。
- 推断顺序与绑定规则见 §8;与位置/具名实参规则对齐 [call-arguments.md](call-arguments.md) 的精神(可修订附录)。
### P5 — 标记仍承载控制流(不变)
- **不引入** `if` / `else` / `while` / `for` / `def` / `return` 关键字。
- `#` = 对象/类型,`##`+ = 函数/方法([objects.md](objects.md) 不变)。
- 分支仍用 `1.` `2.` …;循环仍用 `-`;结构行不必再包粗体(见 §5)。
### P6 — 其它「代码即文档」补强(本版一并采纳)
| 思路 | 说明 |
|------|------|
| **渐进披露** | 读者可只读叙述;运行时只执行标记与推断出的声明。同一文件服务人与机器。 |
| **最小仪式** | 能从正文看出的签名,就不在函数头重复写一遍。 |
| **双调用面** | 独立行 `>` 适合「步骤清单」;行间 `**f …**` 适合「嵌在句子里的动作」。 |
| **标识符视觉统一** | 叙述、代码、形参一律优先 `` `名` ``;粗体/斜体内部允许裸名(与 v0.2 斜体/粗体内规则同类)。 |
| **段落仍可整段注释** | 不含任何可执行标记、且无「声明性 `` `名` ``」义务的纯说明段,行为与注释相同(见 §4 消歧)。 |
| **迁移可观测** | `--dump-lines` / `--dump-ast` 必须能区分「叙述中的声明」与「粗体代码」与「斜体返回」。 |
---
## 3. 与 v0.2 对照(角色对调摘要)
| 概念 | v0.2 | v0.3 |
|------|------|------|
| 程序语句 / 代码段 | `*…*` | `**…**` |
| 返回值 | `**…**` | `*…*` |
| 独立调用 | 必须 `>` | `>` **或** `**callee …**` |
| 形参 | 标题下 `` + `名` `` | **体推断**(`+` 过渡兼容) |
| 叙述中的变量 | 一般为注释,不可声明 | `` `名` `` 可声明/引用 |
| 无标记纯文字 | 成段注释 | 仍为叙述;**若含声明性反引号则参与绑定图**(见 §4) |
这是一次 **架构级标记对调**,不是局部糖。金样例、教程、Skill、扩展库需按路线图分波迁移。
---
## 4. 叙述、声明与注释
### 4.1 三层模型(修订)
| 层 | 形态 | 角色 |
|----|------|------|
| **叙述面** | 普通 Markdown 段落、列表说明 | 给人读;其中的 `` `名` `` 可进入**绑定图** |
| **可执行面** | 结构标记(`#` `>` `+` `-` `1.` 表…)+ **`**代码**`** + **`*返回*`** | 求值 |
| **外联面** | ` ```lang ` | FFI(不变) |
### 4.2 变量在叙述中的出现
语法:Markdown **行内代码** `` `标识符` ``。
| 出现形态 | 语义 |
|----------|------|
| 全文(当前函数/对象作用域)**首次**出现 `` `n` ``,且此前/同句无对 `n` 的赋值 | **声明变量**(进入绑定图;是否升为形参见 §8) |
| 已声明之后再次 `` `n` `` | **引用**(不生成新绑定) |
| 粗体内 `**n = …**` / `**n=n+1**` | **赋值**(若首次赋值且未见声明,则声明+赋值一并发生) |
| 叙述中 `` `n`=1 ``(反引号名紧贴 `=`,无粗体) | **带初值的声明**(形参默认或局部初值;见 §8) |
推荐作者写法(与动机示例一致):
```markdown
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
```
- `` `n` `` → 声明变量;因随后在代码中**读取**未先由局部独力定义 → 升为必选形参(§8)
- `**n=n+1**` → 代码段(赋值)
- `*n*` → 返回
### 4.3 何为「纯注释」
满足下列**全部**条件的段落,不产生绑定、不求值:
1. 不含结构标记行;
2. 不含 `**…**` / 作为返回的 `*…*`(见 §7);
3. 不含任何 `` `标识符` ``。
仍建议:**叙述段与独立结构代码行之间空一行**,降低人读与差分时的视觉粘连(解析器在 v0.3 下不再依赖「空行分段注释升级」作为唯一边界,但空行仍是作者卫生习惯)。
### 4.4 提及性反引号:一律视作变量(已决议)
**不另设「仅提及、不声明」语法。** 叙述里凡出现合法标识符 code span `` `名` ``,一律按 **变量** 处理(首次 = 声明,其后 = 引用)。
| 情况 | 处理 |
|------|------|
| 谈到某名但可执行代码**从未读写**它 | 仍是绑定图中的变量;**对求值无影响**(死绑定) |
| 与其它语言对照 | 类似 Python 写了未用局部、JS 未用 `let`——默认可忽略;实现可对「从未读写」发**可选 lint**,**不得**因此报错或拒绝运行 |
| 是否变成函数形参 | **否**(仅声明、从未在可执行面被读取)——见 §8.2「升参条件」 |
| 是否需要 `` 提及`n` `` 等前缀 | **不需要**;避免第二套反引号方言 |
例(合法、无副作用):
```markdown
## 说明性函数
本文顺便提到`Markdown`与`GFM`,但真正的输入只有`题干`。
**print text=题干**
---
```
- `` `Markdown` `` / `` `GFM` `` → 变量声明,未使用 → 不进形参表、不改行为
- `` `题干` `` → 声明且在粗体中读取 → 必选形参
**否决**:为「提及」单独做转义/前缀(曾列于开放点);若将来作者强烈需要「叙述中的等宽字但不进绑定图」,另开增强案,不阻塞 v0.3 核心。
### 4.5 成段规则相对 v0.2 的变化
v0.2:「段首无标记 → 整段注释,续行永不升级」。
v0.3:
- 叙述段落**可以**内含可执行粗体/斜体返回;解析器做**段内扫描**,抽出 `` `名` ``、`**…**`、`*…*`。
- 独立结构行(行首 `#` `>` `-` `1.` `|` 等)仍整行分类为代码。
- **否决维持**:「整行无标记 = 默认可执行代码」。无标记且无反引号声明的文字永不单独变成语句。
---
## 5. 映射总表(v0.3)
| 标记 | 语义 |
|------|------|
| `#` … `######` | `#` = 对象/类型;`##`+ = 函数/方法(同 [objects.md](objects.md)) |
| 叙述中 `` `名` `` | 声明或引用(§4) |
| `**…**` | **代码段**(赋值、表达式、调用) |
| `*…*` | **返回值**(含显式空值,见 §7.2) |
| `>` 行 | **调用**(可选面,与粗体内调用等价) |
| `` + `名` `` | **过渡兼容**:显式形参;新代码不推荐 |
| 体内 `1.` `2.` … | 分支 |
| 体内 `-` | 循环 |
| `N. *` | else 臂(此处 `*` 仍是「空条件」标记,**不是**返回值;见 §7.3) |
| GFM 表格 | 集合(不变) |
| 表达式 `[键](集合)` | **取元**(与 foreach 同形;见 [collection-access-link.md](collection-access-link.md)) |
| `修饰… [函数名] 实参…` | **方括号标记调用**(前置修饰 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md)) |
| `` 集合[^键] `` | **过渡**:旧脚注取元(仍可用) |
| ` ```lang ` | 外联(不变) |
| 单独一行 `---` / `***` | **叙述分隔**(跳过;模块顶与函数体内相同) |
| 整行恰 `**` 或 `****` / `*None*` / `*无*` | **空返回**并结束本函数体(见 §7.2) |
### 结构行与粗体
行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包 `**…**`。
粗体用于:**嵌在叙述中的代码**,以及「我想把这一小段标成可执行」的行间片段。
---
## 6. 调用
### 6.1 调用表面
```markdown
> 加一函数 37
**加一函数 37**
礼貌 [问候] marqdo
```
前两种解析为对 `加一函数` 的调用;第三种为**方括号标记调用**(`[` `]` 标出函数名,前置裸词展开为 `名=True`)。实参位置或具名绑定;详见 [call-arguments.md](call-arguments.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md)。
| 形式 | 典型用途 |
|------|----------|
| `> …` | 步骤列表、独立可执行行、与 v0.2/AI 习惯兼容 |
| `**…**` | 嵌在句子中:「或者可以直接这么调用**加一函数 37**」 |
| `**x = 加一 37**` | 粗体赋值右侧为调用时**可省略 `>`**(代码即文档首选;`> 加一 37` 仍合法) |
| `修饰… [函数] 实参…` | 叙述里需要「形容词 + 动词」时消歧;与 `[键](集合)` 取元靠 `]` 后是否紧邻 `(` 区分 |
### 6.2 粗体内调用的判别
粗体内容在去掉外层 `**` 后,按下列优先级分类:
1. 含 `=` 且左侧为可赋值目标(标识符 / 脚注左值等)→ **赋值语句**(可含右侧调用)。
2. 否则,若首词为已知函数/方法/内置/导入成员(Pass 名表可见)→ **调用**。
3. 否则 → **表达式语句**(求值后丢弃,或在语句位置非法则诊断)。
示例:
| 粗体内容 | 分类 |
|----------|------|
| `n=n+1` | 赋值 |
| `加一函数 37` | 调用 |
| `加一函数 n=37` | 调用(具名) |
| `n + 1` | 表达式(单独出现时;作返回应写 `*n + 1*`) |
| `print text=hi` / `打印 内容=你好` | 调用(内置) |
### 6.3 方法调用
- 独立行:`` > `对象`.方法 … ``(兼容)或 `> 对象.方法 …`(若接收者规则允许)。
- 粗体内:`**对象.方法 …**` / `**p = page.主体装配 组件=home**`。
- 粗体/斜体内裸名 = 变量(延续 v0.2「段内统一命名空间」精神)。
### 6.4 实参
具名 + 位置混用规则继承 [call-arguments.md](call-arguments.md);v0.3 仅把「形参列表来源」从 `+` 行改为**推断签名**(§8)。独立 `>` 行上裸词仍为文本字面量;粗体内调用的裸词为变量(与 v0.2「段内调用」一致)。
---
## 7. 返回
### 7.1 斜体返回
```markdown
*n*
*n + 1*
*"ok"*
```
斜体内部值语法与 v0.2 粗体返回内部相同(裸词 = 变量;文本须引号)。
### 7.2 空返回与收束(已决议)
Marqdo **不引入** `return` 关键字;「无值结束」用标记表达。对照常见语言:
| 语言 | 无值 / 空返回 | Marqdo v0.3 对应 |
|------|----------------|------------------|
| Python | `return` / `return None` | 显式 `*None*`·`*无*` |
| Go | 无结果函数里的 `return` | `*None*` / 整行 `**` / `****` |
| Rust | `()` 或函数末尾隐式 unit | 同上;或下一标题 / EOF 自然结束 |
| JavaScript | `return;` → `undefined` | 同上 → 运行时 `None` |
| Marqdo 历史 | `---` 收束;`****` | `---` 已改为叙述跳过;`****` 仍兼容 |
#### 形式层级(推荐自上而下)
| 优先级 | 形式 | 语义 | 说明 |
|--------|------|------|------|
| **1. 显式空值** | `*None*` 或 `*无*`(整段或行内返回位) | 返回 `None` **并结束本函数体解析** | 对齐 Python `return None`;副作用函数首选;外层续写依赖此收束 |
| **2. 空斜体标记** | **整行** trim 后恰为两个星号:`**` | 同上 | 词法钉死:`^\s*\*\*\s*$` → **空斜体返回**,**不得**当成粗体开闭 |
| **3. 兼容** | 整行 `****`(四个星号) | 同空返回 | 迁移期识别 |
| **(非收束)** | 整行 `---` / `***` | **仅叙述分隔**,跳过 | 不再结束函数;见 [code-as-docs-gaps.md](code-as-docs-gaps.md) |
```markdown
## 只打印
**print text=hi**
*None*
## 空斜体行
**print text=hi**
**
## 分割线不收束(下一标题才结束)
**print text=hi**
---
```
#### 词法消歧(空斜体 vs 粗体)
1. **整行恰好 `**`(两个 `*`)** → 空返回(规则 2),不是未闭合粗体。
2. **粗体代码**至少包住一个非空内容:`**x**`、`**n=1**`;不允许「空粗体代码段」作为语句。
3. **四个星号整行 `****`** → 兼容空返回(规则 3),不解释为「空粗体代码」。
4. 行内出现的 `**…**`(两侧还有叙述文字)按正常粗体代码扫描,不走「整行空返回」。
#### 与「有返回值」的关系
- 需要把值交回调用方 → 用非空斜体:`*n*`、`*n + 1*`(返回即结束本函数体解析)。
- 只做副作用、不要值 → 优先 `*None*` / `*无*` / 整行 `**`。
- 下一标题或 EOF 也可结束体;**不要**再靠 `---` 收束。
### 7.3 与 else 臂 `N. *` 的消歧
有序列表臂头 `2. *` 中的 `*` 表示 **else**,不是返回。判别:行匹配 `^\s*\d+\.\s+\*\s*$`(可带尾注)→ 分支 else;不进入返回扫描。
### 7.4 输出
```markdown
**print text=Hello**
> print text=Hello
```
打印是调用,不是返回。禁止把 `*Hello*` / `**Hello**` 解释为「打印 Hello」(延续 v0.2 决议精神,仅对调标记)。
---
## 8. 形参推断
### 8.1 目标签名
对每个 `## 函数`(及方法),在 Pass1 收集体之后得到:
```text
params: Vec<{ name, default: Option<Expr>, span }>
```
### 8.2 收集规则(函数作用域)
扫描该函数标题之下、下一同级/更高级标题之前的所有节点,维护**绑定图**与**形参表**(二者分离):
#### A. 绑定图(所有变量)
1. **声明事件**:叙述或代码中的首次 `` `名` ``,或粗体内首次对 `名` 的赋值左值。
2. **默认/初值事件**:叙述 `` `名`=默认表达式 ``;或符合 §8.3 的「形参默认」赋值。
3. **排除出绑定图**(不建变量):
- 循环变量 `` - [项](集合) `` 中的 `项`(循环自有绑定);
- `self` / `自`(方法自动注入)。
凡进入绑定图的名字都是**变量**——包括「只在叙述里出现、可执行代码从未读写」的名字(§4.4)。未使用 → **不报错**。
#### B. 升为形参的条件(升参)
名字已在绑定图中,且满足下列之一,才进入 `params`:
| 升参种类 | 条件 |
|----------|------|
| **必选形参** | 在可执行面(`**…**` / `*…*` / `>` / 结构语句)中存在对 `名` 的**读取**,且该读取无法单靠「不依赖外部输入的局部赋值」满足——典型:先声明、后 `n=n+1` / `*n*` / `**print text=n**` 等读到未先行赋成纯局部常量 |
| **可选形参** | 有默认/初值事件(`` `名`=… `` 或 §8.3 默认赋值),供调用方覆盖 |
**不升参**:仅叙述声明、可执行面零读取(死绑定)→ 留在绑定图,**不进** `params`,调用签名不变。
**顺序**:按升参名字的**首次声明事件**在源码中的出现序。
**仍排除**:分支/块内纯局部(金样例钉启发式);显式 `+` 合并见 §8.4。
### 8.3 「形参默认」与「函数体赋值」的区分
```markdown
## 问候
对`谁`打招呼,默认`礼貌`=False。
**print text=谁**
```
- `` `谁` `` → 必选
- `` `礼貌`=False `` → 可选,默认 `False`
- 体里的 `**print …**` 不是给 `谁` 赋默认值
```markdown
## 加一函数
输入`n`。**n=n+1**返回*n*。
```
- `` `n` `` 先声明 → 必选
- `**n=n+1**` 是**体语句**(对已声明形参赋值),**不是**默认值
判别启发式(实现契约):
- 若赋值右值**依赖同名左值**(如 `n=n+1`)→ 体语句。
- 若赋值出现在「该名被当作输入读取」之前,且右值不依赖未绑定的同名 → 可作为默认值候选。
- 叙述形 `` `名`=字面量 `` 优先视为默认值声明。
### 8.4 显式 `+` 形参(过渡)
- 若函数标题下仍有 `` + `名` `` 行:与推断结果**合并**;冲突时 **显式 `+` 胜出**并诊断警告。
- 迁移完成后(路线图 M4)可改为:存在 `+` 则关闭推断,或直接废弃 `+`。
### 8.5 调用绑定
与现有一致:具名优先,位置按「尚未绑定的形参」从左到右填充。缺必选形参 → 语义错误。
---
## 9. 完整示例(规范金样意向)
### 9.1 加一(动机例)
```markdown
## 加一函数
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
# main
我要调用加一函数可以采用这样的办法:
> 加一函数 37
或者可以直接这么调用**加一函数 37**
```
期望:
- 签名:`加一函数(n)`
- `# main` 两次调用均返回 `38`(第二次若未绑定到打印,至少 AST/求值结果为 38;可用 `**print text=…**` 观测)。
### 9.2 带默认值
```markdown
## 问候
向`谁`问好;`礼貌`=False 时用短句。
1. 礼貌
**print text=您好,**
**print text=谁**
2. *
**print text=嗨,**
**print text=谁**
---
# main
**问候 谁=Marqdo 礼貌=True**
> 问候 Marqdo
```
### 9.3 对象方法(不变骨架)
```markdown
# 计数器
## 加
将`self`的`值`增加`delta`(`delta`=1)。
**值 = 值 + delta**
*self*
# main
*c = > 计数器*
**c.加 3**
```
(方法形参推断含 `delta`;`self` 自动。)
---
## 10. AST / 管线变更要点(设计约束)
详细里程碑见 [markup-v0.3.md](../roadmap/markup-v0.3.md)。此处只钉**语义 → 树**的约束,供实现对照:
### 10.1 行分类(lex / line-class)
新增或调整类别:
| 类别 | 说明 |
|------|------|
| `Prose` | 叙述行;需**内联扫描** |
| `BoldCode` | 整行或片段 `**…**` |
| `ItalicReturn` | 整行或片段 `*…*`(非 else 臂) |
| `CallLine` | `>` 调用(保留) |
| … | 原有 Heading / List / Table / Fence / Hr |
**内联扫描**产出 `InlineBit`:`Text` | `IdentDecl/Ref` | `BoldCode` | `ItalicReturn`。
### 10.2 AST 节点调整(建议)
```text
Param { name, default?, inferred: bool, span } // inferred=true 表示来自体推断
Stmt::
Assign { … } // 多由 BoldCode 解析
Call { … } // CallLine 或 BoldCode 判别为调用
Return { value } // 由 ItalicReturn 解析(原由 Bold)
ExprStmt { … } // 可选:纯表达式粗体
Prose { bits } // 可选:保留叙述结构供 view/catalog;求值阶段只消费 Decl
FnDef.params:
由 InferParams(body + prose bits) 填充,再合并显式 +
```
`Stmt::Return` 的**语法来源**从粗体改为斜体;dump 文本应写 `return←italic`。
### 10.3 Pass1 / Pass2
- Pass1:收集 `#`/`##` 结构;建绑定图;跑 **ParamInfer(升参)**;登记名表。
- Pass2:粗体内调用名解析;叙述 Decl 不重复建参。
- 诊断:**必选缺失**、`+` 与推断冲突、空返回词法歧义(非整行 `**` 的残缺粗体)。
- Lint(可选、默认关或降级为 hint):绑定图中「从未读写」的死变量——**不得**当错误。
### 10.4 双后端
树遍历与字节码均消费同一 AST;字节码发射仅跟随 `Stmt`/`Expr` 变化,不感知 Markdown 标记。
---
## 11. 破坏性切换(无双模式)
**产品决定(2026-09-13):** 直接以 v0.3 为唯一运行时映射;**不**保留 `--markup v0.2` / 双 edition。旧语法金样例与库文件在迁移完成前可能失败——可接受。
| 阶段 | 行为 |
|------|------|
| 现在 | 解析器切到 v0.3;`tests/markup-v03/` 为门禁 |
| 随后 | 批量改写 `tests/structure|keywords`、`lib/`、`ext/`、Skill、`public/` |
| 文档 | `markdown-mapping.md` 改为指向本文;ADR 0005 → Accepted |
**机械改写:**
- 语句 `*a = 1*` → `**a = 1**`
- 返回 `**x**` → `*x*`
- 粗体内文本字面量须引号:`**print text="hi"**`(裸词 = 变量)
- 调用可保留 `>` 或改为粗体
- `` + `n` `` 可删,改为叙述 `` `n` `` + 升参
---
## 12. 开放问题 / 已决议
| # | 议题 | 状态 | 决议摘要 |
|---|------|------|----------|
| 1 | 空返回词法 | **已决议** | §7.2:推荐 `*None*`/`*无*`;整行 `**`;兼容 `****`;`---` 仅叙述跳过 |
| 2 | 提及性反引号 | **已决议** | §4.4:一律视作变量;未使用不报错、不升参;不设提及前缀 |
| 3 | 粗体内调用 vs 赋值 | **已落地** | §6.2:可赋值左值 → 赋值;否则表达式优先、再裸调用;`**n + 1**` = ExprStmt |
| 4 | `` `n`+1 `` 误声明 | **已落地** | Decl 名须为标识符;`` `n+1` `` 不升 Decl |
| 5 | 叙述强调斜体 vs 返回 | **已落地** | 整行 / `返回*…*` / 表达式形才当返回;`*only*` `*very important*` `*foo.bar*` 为叙述 |
| 6 | 一行多 `**…**` | **已落地** | 允许,按出现序执行(`tests/markup-v03/multi-bold.mq.md`) |
| 7 | view 展示 prose Decl | **已落地** | Structure / Functions 大纲:`inferred` 形参标注(`chip inferred`) |
---
## 13. 非目标
- 不把整篇无标记 Markdown 变成可执行程序。
- 不引入 `def` / `return` 关键字(空返回用标记,见 §7.2)。
- 不改变 `#` / `##` 对象体系与 ext 插件 ABI。
- 不在本文阶段修改解释器代码(见路线图)。
- 不为「提及」另发明一套反引号方言(§4.4)。
---
## 14. 验收标准(设计完成 ≠ 实现完成)
设计稿验收:
- [x] 哲学 P1–P6 成文
- [x] 与 v0.2 对照表
- [x] 形参推断规则可实现(含升参 vs 死绑定)
- [x] 动机示例在语义上闭合
- [x] AST/管线约束与路线图挂接
- [x] ADR 记录决策意向
- [x] **空返回**对照其它语言并钉死词法
- [x] **提及/未使用变量**政策钉死
实现验收:
- [x] 金样例夹具 `tests/markup-v03/`(`gold.rs` `markup_v03_*`)
- [x] 动机示例金样例通过(`inc-prose.mq.md`)
- [x] `--dump-ast` 可见 inferred params 与死绑定;`--dump-lines` 标注 `[decl]` / `[bold]` / `[italic]`
- [x] 空返回四种形式金样例通过
- [x] 无 v0.2 双模式(默认即 v0.3)
---
## 15. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-13 | 初稿:叙述统一、粗体代码、斜体返回、形参体推断;Proposed |
| 2026-09-13 | 决议空返回(§7.2)与提及性反引号(§4.4);形参改为「升参」与绑定图分离(§8.2) |
| 2026-09-14 | §7.2:`---` 不再收束;返回语句结束函数体解析;空返回首选 `*None*` |
| 2026-09-14 | 取元主语法改为 `[键](集合)`;脚注取元过渡保留 |
+3 -2
View File
@@ -2,9 +2,10 @@
| | |
|---|---|
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、同级再 `1.` 为新分支、标识符反引号、`-` 专用于循环) |
| 状态 | **历史文档(v0.2 · 已废止为运行时)** — 现行见 **[markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)** |
| 日期 | 2026-08-07 |
| 取代 | v0.1 中「函数头 `-` 形参 / 裸名形参与遍历变量 / `+` 分支」 |
| 被取代 | **[markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)**(粗体即代码 · 斜体即返回 · 无双模式兼容) |
| 相关 | [objects.md](objects.md) · [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) · [module-namespace.md](module-namespace.md) |
Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。
@@ -268,7 +269,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
| **首列表头 `@` / `行` / `row`** | **行向** `List` of `Map`(标记列不进入字段;任意数据行数) |
| 重复表头 | 诊断错误 |
**数据单元格是表达式**(与调用实参值语法相同:裸词、数字、`` `var` ``、算术、引号串;URL / `gpt-4o-mini` 等按路径·连字符折叠为文本)。表头仍是键名文本。细则:[table-cell-expressions.md](table-cell-expressions.md)。
**数据单元格是表达式**(与调用实参值语法相同:裸词、数字、`` `var` ``、算术、引号串;URL / `gpt-4o-mini` 等按路径·连字符折叠为文本;含 `/` 的 CSS 比率等请用引号 `"1/5"`,裸 `1/5` 为除法)。表头仍是键名文本。细则:[table-cell-expressions.md](table-cell-expressions.md)。
```markdown
*`k` = secret *
+2 -2
View File
@@ -23,9 +23,9 @@ marqdo dump FILE --stage lines|tokens|ast|sema|all
| 标志 | 阶段 | 输出内容 |
|------|------|----------|
| `--dump-lines` | 行分类 | 每行:`LINE kind=Comment\|Code\|Blank` + 原文预览 |
| `--dump-lines` | 行分类 | 每行:`kind=Comment\|Code\|Blank` + 原文;v0.3 行内位 `[decl n]` / `[bold …]` / `[italic …]` |
| `--dump-tokens` | 词法 | Token 流:`type lexeme line:col` |
| `--dump-ast` | 语法 | S 表达式或缩进树(模块/函数/语句) |
| `--dump-ast` | 语法 | 模块/函数/语句;形参带 `inferred`;叙述死绑定 `dead=[…]` |
| `--dump-sema` | 语义 | 作用域、导入图、提升后的符号表 |
| `--trace-eval` | 求值 | **JSON 行**(stderr):语句级事件,含 `path` / `span`(`line:col`) |
| `--dump-bytecode` | 字节码 | 反汇编 `Program`(指令旁带 `@line:col`;见 [bytecode.md](bytecode.md)) |
+21 -3
View File
@@ -2,18 +2,36 @@
| | |
|---|---|
| 状态 | 已决议(并入 mapping v0.1 + keywords;2026-08-04 修订函数收束) |
| 状态 | **v0.2 已决议**(现行实现);**v0.3 拟对调 `*` / `**` 角色**(见下) |
| 日期 | 2026-08-04 |
| 修订 | 2026-09-13:挂接 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) |
---
## 决议
## 决议(v0.2 · 现行)
1. **`*…*` = 程序语句**。
2. **`**…**` = 返回值**(架构级);空粗体 `****` / `** **` = 空返回(`None`)并结束函数体。
3. **输出**用内置函数 **`print`**(英文),不是粗体,不是中文名。
4. **`---` / `***`(函数体顶层)**:结束本函数体(无返回值函数收束);**不是**分支/循环装饰框。
4. **`---` / `***`**:Markdown 叙述分隔(跳过);**不再**结束函数体。无值收束用 `*None*` / 整行 `**` / `****`(见 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) §7.2)。
5. **成段注释**:空行分段;段内续行不因首字符升级为代码。
6. **否决**:无标记行 = 默认代码。
详见 [keywords.md](keywords.md)、[markdown-mapping.md](markdown-mapping.md)、[code-vs-comment.md](code-vs-comment.md)。
---
## v0.3 意向(Proposed · 未实现)
产品方重新审视后,拟在 [ADR 0005](../adr/0005-prose-unified-markup.md) 下**对调**架构标记,并放宽叙述面:
| 概念 | v0.2 | v0.3 草案 |
|------|------|-----------|
| 代码段 / 语句 | `*…*` | `**…**` |
| 返回值 | `**…**` | `*…*` |
| 空返回 | `****` / 空粗体;或 `---` | **推荐 `*None*`/`*无*`**;整行 `**`;兼容 `****`;`---` 仅叙述 |
| 输出 | 仍为 `print` / `打印` | 不变 |
| 无标记 = 默认代码 | 否决 | **仍否决** |
| 叙述中 `` `名` `` | 通常无绑定义 | 一律变量;未使用 OK;升参需可执行面读取 |
完整规则与迁移见 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)。**v0.3 已为运行时;本文件历史决议中「`---` 收束」已废止。**
+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
按路线图 **默认跳过**。
+5 -4
View File
@@ -11,9 +11,9 @@
| 读 | 写 |
|----|----|
| 脚注 `` `xs`[^1] `` / `` `m`[^key] `` / 嵌套 `` `m`[^a][^1] `` | **`table.put` / `表.改`** |
| 链接取元 `[key](xs)` / `[key](m)` / 嵌套 `[1]([a](m))`(脚注 `` `m`[^k] `` 仍兼容) | **`table.put` / `表.改`** |
`put` / `改` 的 `at=`(`于=`)与脚注同构:文本键、**1-based** 整数下标,或键/下标组成的路径列表。
`put` / `改` 的 `at=`(`于=`)与取元同构:文本键、**1-based** 整数下标,或键/下标组成的路径列表。
```markdown
---
@@ -22,7 +22,7 @@ import table:lib/table.mq.md
# main
*`h` = > table.put in=None at=Authorization value=Bearer-x*
**`h` = [table.put] in=None at="Authorization" value="Bearer-x"**
`xs` =
@@ -31,7 +31,8 @@ import table:lib/table.mq.md
| a |
| b |
*`xs` = > table.put in=`xs` at=1 value=A*
**`xs` = [table.put] in=`xs` at=1 value="A"**
**打印 内容=[Authorization](h)**
```
`in=None` 且 `at=` 为单个文本键 → 新建单键字典。值一律不可变更新(返回新集合)。
+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 原样保留)。
+11 -6
View File
@@ -2,12 +2,15 @@
| | |
|---|---|
| 状态 | **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) · [lib-code-as-docs.md](lib-code-as-docs.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) |
> **库写法(代码即文档)**:[lib-code-as-docs.md](lib-code-as-docs.md) · [roadmap/lib-ext-code-as-docs.md](../roadmap/lib-ext-code-as-docs.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 +20,11 @@
| 层 | 内容 |
|----|------|
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at`(`type` 可含 `map`) |
| **L1 官方库** | 仓库根目录 [`lib/`](../../lib/)(`.mq.md`);可用 `lib/…` 或别名 `std/…` 导入 |
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1 |
| **L2** | catalog / 用户站收录(随发版) |
| **L1 核心** | 已有 [`lib/`](../../lib/):fs/sys/time/json/net/math/foreign/plugin/table/text/… |
| **L1 中层(Mid)** | **已落地** re / encoding / path / hash / secrets / csv / text++ / table++ / cli / log / uuid — [stdlib-mid.md](stdlib-mid.md) |
| **L1 Mid2** | **已落地** datetime / url / toml / html / fs++ / stats / log.fields — [stdlib-mid2.md](stdlib-mid2.md) |
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1;插件仅领域热路径 |
| **L2** | catalog / 用户站收录(随发版);应主要靠核心+中层、默认无插件 |
---
+6 -3
View File
@@ -44,10 +44,11 @@ v1 把 GFM 数据单元格一律收成 **字面量**(`Int` / `Text`)。结
| `` `api_key` `` | 变量引用 |
| `` `a` + `b` `` | 普通表达式 |
| `True` / `假` / `None` | 布尔 / 空 |
| `"https://…"` / `".marqdo/x"` | 引号字符串(可含 `/`、插值) |
| `"https://…"` / `".marqdo/x"` / `"1/5"` / `"16/9"` | 引号字符串(可含 `/`、插值;**CSS 比率等含 `/` 的值请用引号**,勿依赖空格消歧) |
| `https://api.openai.com/v1` | **路径折叠**:无空格的 `Text/Text/…` 除法链收成整段文本(同调用实参) |
| `gpt-4o-mini` | **连字符散文**:不拆成减法(同调用实参) |
| `` /about ``、`` /chat/completions `` | 以 `/` 开头的路径散文 → 整段文本 |
| `1/5` | **整数除法**(同表达式 / 调用实参;今日整除得 `0`)——要文本请写 `"1/5"` |
| 空单元格 | 空文本 `""` |
### 2.2 表头仍是键名文本
@@ -111,9 +112,10 @@ v1 把 GFM 数据单元格一律收成 **字面量**(`Int` / `Text`)。结
|--------|------|
| 纯中文/英文词、整数 | **不变** |
| `gpt-4o-mini`、URL、`/path` | **不变**(折叠规则与调用实参一致) |
| 真正要做除法 / 减法 | 用空格或括号:`` `n` / 2 ``、`` `a` - 1 ``;或先在表外算再 `` `x` `` 填入 |
| 真正要做除法 / 减法 | 裸写 `1/5` 或空格/括号:`` `n` / 2 ``、`` `a` - 1 ``;或先在表外算再 `` `x` `` 填入 |
| CSS / 含 `/` 的散文值 | **引号优先**:`"1/5"`、`"16/9"`、`"image/png"`(不靠空格把算术「关掉」) |
破坏性:几乎无。唯一需注意的是「想在单元格里写算术且两侧是裸词」——与调用实参同一套消歧。
破坏性:几乎无。唯一需注意的是「想在单元格里写算术且两侧是裸词」——与调用实参同一套消歧;含 `/` 的**文本**一律用引号。
---
@@ -132,6 +134,7 @@ v1 把 GFM 数据单元格一律收成 **字面量**(`Int` / `Text`)。结
|----|------|
| 金样 | 横表单元格 `` `var` `` 读环境;竖表旧金样全绿 |
| 路径 | `https://…`、`/chat/completions`、`gpt-4o-mini` 仍为文本 |
| 含 `/` 文本 | 表单元格用引号:`"1/5"`、`"16/9"`;裸 `1/5` 为除法 |
| 扩展 | `ext/ai/llm` 构造可用表写入运行时字段,去掉无必要的 `json.set` 链 |
| 文档 | 本页 + roadmap T5 + markdown-mapping §9 同步 |
+1 -1
View File
@@ -34,7 +34,7 @@
| 中 | 静态类型 / 可维护 AST | 长期改解释器不疼 |
| 中 | CLI 与打包 | 单二进制或 `npx`/等价体验 |
| 低 | 极致性能 | v0 样例很小 |
| 低 | 浏览器内运行 | 可后置 |
| 低 | 浏览器内运行 | **已后置落地规划**:见 [ADR 0002](../adr/0002-browser-marqdo-wasm.md)(WASM 解释器) |
非准则:跟风、先写再选、与「生成 OKF」强绑某一云厂商。
+35
View File
@@ -0,0 +1,35 @@
# View:Markup 表面保真
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-09-14 |
| 相关 | [view.md](view.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md) · [collection-access-link.md](collection-access-link.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) |
---
## 1. 目标
`marqdo view` 的 Structure / 表达式展示应**贴近作者写出的 Markup**,而不是内部 AST 的旧拼法。读者从 view 抄回源文件时,应仍是合法、推荐的表面。
## 2. 表面对照
| AST / 概念 | View 优先显示 | 备注 |
|------------|---------------|------|
| `Expr::Index` | `[键](基)` | 嵌套 `[k2]([k1](base))` |
| `InterpPart::Index` | 同上嵌套链接形 | 不再默认 `` `base`[^k] `` |
| `CallExpr` + `bracket_marked` / `pre_modifiers` | `修饰 [callee] 实参…` 或 `[callee] 实参…` | 仅经典 `>` 解析时仍显示 `> callee …` |
| 赋值 / 返回 | 粗体 / 斜体语义即可 | 不强制还原整句叙述 |
| foreach | `- [项](集合)` | 不变 |
## 3. 非目标
- 不把 view 做成第二语法;解析真相仍在 mapping / call-arguments。
- 不删除对脚注取元、旧 `>` 调用的兼容显示需求时,可用次要提示,但默认推荐面优先。
## 4. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿;Index 链接形 + 括号调用修饰表面 |
| 2026-09-14 | `bracket_marked`:无修饰的 `[callee]` 也保真显示 |
+1 -1
View File
@@ -4,7 +4,7 @@
|---|---|
| 状态 | 已定(v0.0.2 方向) |
| 日期 | 2026-08-04 |
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [view-markup-surface.md](view-markup-surface.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
---
+328
View File
@@ -0,0 +1,328 @@
# `ext/web` — 站点图标、Head 资源与图片装配
| | |
|---|---|
| 状态 | **Accepted · W8 已落地** |
| 日期 | 2026-08-29 |
| 父设计 | [ext-web.md](ext-web.md) · [web-net-capabilities.md](web-net-capabilities.md) |
| 相关 | [web-asgi-servers-and-marqdo.md](web-asgi-servers-and-marqdo.md)(静态仍由嵌入式 `listen` 提供) |
| 硬约束 | `ext/**` 不调 `host_*`;作者面禁止袋胶水;中英库文件分文件 |
---
## 0. 一句话
把 **浏览器默认图标(`/favicon.ico`)**、**`<head>` 里的 link/script**、**正文/品牌图片** 都做成与 `样式装配` 同构的能力:**GFM 表即数据,装配即函数**;由 `plugins/web` ABI 渲染/挂路由,`ext/web` 只做 L1 包装。
---
## 1. 动机与现状缺口
### 1.1 已有
| 能力 | 说明 |
|------|------|
| `app.static` / `应用.静态` | 目录挂到 `/static`(或自定义 mount) |
| `page.meta` / `页面.元数据` | `title` / `description` / `canonical` / `og:*` → `<head>` |
| `app.upload` + `gallery` | **运行时**用户上传媒体,不是站点品牌资源 |
### 1.2 缺口(本设计一次补齐)
| # | 缺口 | 影响 |
|---|------|------|
| G1 | 浏览器默认请求 **`GET /favicon.ico`**,静态挂在 `/static` 时根路径 404 | 标签页无图标 |
| G2 | `page.meta` 未知键一律变成 `<meta name="…">`,**不能**正确写出 `<link rel="icon">` | 作者写 `icon` 无效 |
| G3 | 无 **Head 资源表**(stylesheet / preload / script / manifest / apple-touch-icon) | 只能手写进 `intro` 或改插件 |
| G4 | 无 **图片装配**(表 → `<figure>`/`<img>`),与样式装配不对齐 | logo / 头图 / 插图只能拼 HTML 字符串 |
| G5 | 无 **站点级图标表 → 根路径文件服务 + 默认 head 注入** | 多页站点要在每页重复声明 |
---
## 2. 设计原则
1. **配置即数据、装配即函数** — 与 `web_style` / `应用.装配` 同构。
2. **应用层管「可达性」**(磁盘文件 → HTTP 路径);**页面层管「声明」**(`<head>` / 正文 HTML)。
3. **站点图标可自动注入所有页面**,页面仍可用 `头装配` / `元数据` 覆盖或追加。
4. **约定优于配置**:若已 `静态` 且目录内存在 `favicon.ico`(或 `favicon.png` / `favicon.svg`),未显式配置时仍挂 `GET /favicon.ico`(及对应静态 URL 由作者自选)。
5. **中英分文件**:`web.mq.md` ↔ `网页.mq.md`,禁止混排。
---
## 3. 作者面 API(一次交付全集)
### 3.1 模块级装配(返回字符串,可与主题拼装)
| EN | ZH | FFI | 输入 | 输出 |
|----|----|-----|------|------|
| `make_style`(已有) | `样式装配` | `web_style` | 样式表 | CSS 文本 |
| **`make_images`** | **`图片装配`** | **`web_images`** | 图片表 | HTML 片段 |
| **`make_head`** | **`头资源装配`** | **`web_head`** | Head 表 | 供调试/预览的 HTML 片段(可选;页面方法主路径不强制调用) |
### 3.2 `# page` / `# 页面`
| EN | ZH | FFI | 作用 |
|----|----|-----|------|
| `meta`(增强) | `元数据` | `web_page_meta` | 认 `icon` / `favicon` / `apple-touch-icon` → `<link>`,不再误写成 `<meta name>` |
| **`head`** | **`头装配`** | **`web_page_head`** | 挂 Head 资源表到 `page.head`,渲染时写入 `<head>` |
| **`images`** | **`图片装配`**(方法) | **`web_page_images`** | 图片表 → HTML,写入 `page.images_html`,渲染进主区 |
### 3.3 `# app` / `# 应用`
| EN | ZH | FFI | 作用 |
|----|----|-----|------|
| **`icons`** | **`图标`** | **`web_app_icons`** | 站点图标表:根路径文件服务 + 默认 head 链接注入全站 |
| `static`(增强) | `静态`(增强) | `web_app_static` | 约定:目录内 `favicon.ico|png|svg` → 自动注册 `/favicon.ico`(可被 `icons` 显式行覆盖) |
---
## 4. 表形约定
单元格仍为**字面量**;列名中英等价(任选一套,勿混列名语义)。
### 4.1 站点图标表(`app.icons` / `应用.图标`)
| 列(ZH) | 列(EN) | 必填 | 说明 |
|----------|----------|------|------|
| `路径` | `path` | ✅* | 磁盘路径(相对进程 cwd 或入口目录解析规则与 `static` 一致) |
| `关系` | `rel` | | 默认 `icon`;常用 `icon` / `apple-touch-icon` / `mask-icon` |
| `类型` | `type` | | 缺省按扩展名推断 |
| `尺寸` | `sizes` | | 如 `16x16`、`180x180`、`any` |
| `地址` | `url` / `href` | | 对外 URL。缺省:首个 `rel=icon` 且扩展名为 `.ico` → `/favicon.ico`;否则 `/icons/{文件名}` |
\* 若仅提供 `地址` 指向已由 `静态` 提供的 URL、不落盘服务,则 `路径` 可空(只注入 head,不挂新路由)。
**Listen 行为**
1. 规范化为数组 `{path, rel, type, sizes, url}`。
2. 对每个非空 `path`:注册 **`GET {url}`**,读文件返回,`Content-Type` = `type` 或推断;`Cache-Control` 可用 `public, max-age=86400`。
3. 若存在至少一个 `rel` 含 `icon` 的行,保证浏览器默认路径:若没有任何 `url=/favicon.ico`,则把**第一行 icon** 额外挂到 `/favicon.ico`(同一文件,可选)。
4. 将图标行转为默认 head 链接列表,存入 `app.site_head`,listen 时写入 `AppState`,渲染任意页面前 **merge**(页面自有 `head` / meta 图标 **追加且可同 href 去重**)。
**`static` 约定自动图标**
在 `listen` 解析完 `static_dir` 后:若 `app.icons` 为空,且 `{static_dir}/favicon.ico` 或 `.png` / `.svg` 存在,则等价注册:
```text
path = {static_dir}/favicon.{ico|png|svg}
rel = icon
url = /favicon.ico
```
(文件仍可通过 `/static/favicon.*` 访问;根路径额外可达。)
### 4.2 Head 资源表(`page.head` / `页面.头装配`)
| 列(ZH) | 列(EN) | 说明 |
|----------|----------|------|
| `关系` | `rel` | `icon` / `apple-touch-icon` / `stylesheet` / `preload` / `modulepreload` / `manifest` / `canonical` / **`script`** / **`module`** |
| `地址` | `href` / `src` / `url` | 资源 URL |
| `类型` | `type` | MIME 或 `module` |
| `尺寸` | `sizes` | icons |
| `媒体` | `media` | CSS media |
| `作为` | `as` | preload `as` |
| `跨域` | `crossorigin` | 空 / `anonymous` / `use-credentials` |
| `推迟` | `defer` | 经典 `script` 为真时输出 `defer`(缺省同步,兼容旧站) |
| `异步` | `async` | 为真时输出 `async` |
| `版本` | `version` / `v` | 非空则自动追加 `?v=`;否则用页面/应用 `asset_version` |
**渲染规则**
| `rel` | 输出 |
|-------|------|
| `script` | `<script … src="…"></script>`(可选 `defer`/`async`;`type` 非空则写出) |
| `module` | `<script type="module" src="…"></script>`(浏览器默认 defer 语义) |
| 其他 | `<link rel="…" href="…" …>`(按列附加 `type`/`sizes`/`media`/`as`/`crossorigin`) |
空 `地址` 的行跳过。
### 4.3 元数据表增强(`page.meta`)
| 键 | 行为 |
|----|------|
| `title` / `description` / `canonical` / `og:*` | **不变** |
| **`icon`** / **`favicon`** | `<link rel="icon" href="{值}"/>`(可选若值含空格后 MIME:本切片仅 href) |
| **`apple-touch-icon`** | `<link rel="apple-touch-icon" href="{值}"/>` |
| 其他 | 仍为 `<meta name="…" content="…"/>` |
### 4.4 图片表(`make_images` / `page.images`)
| 列(ZH) | 列(EN) | 说明 |
|----------|----------|------|
| `源` | `src` | 必填,图片 URL |
| `替代` | `alt` | `alt` 文本,默认空 |
| `标题` | `title` | `title` 属性 |
| `类` | `class` | 加在 `<figure>`(无 figure 时加在 `<img>`) |
| `链接` | `href` / `link` | 非空则用 `<a>` 包裹 `<img>` |
| `宽度` | `width` | 像素,可选 |
| `高度` | `height` | 像素,可选 |
| `加载` | `loading` | `lazy` / `eager`;默认 `lazy`(首行可写 `eager`) |
| `图注` | `caption` | 非空则 `<figcaption>` |
| `槽` | `slot` | 预留:`main`(默认)。本切片只支持主区 |
**输出 HTML(多行)**
```html
<div class="mq-images" data-slot="main">
<figure class="mq-img …">…</figure>
…
</div>
```
单行且无图注/类时仍包在 `div.mq-images` 内,保证主题可统一选中。
**`page.images`**:调用 `web_images` 逻辑,结果写入 `page.images_html`。
**渲染位置**:`render_page` 主区中,在 `intro` **之前**插入 `images_html`(品牌图/头图常见需求);`render_fragment` 的 main 槽同样插入。
路径与 MIME 单元格若含 `/`,须写成引号字面量(T5 单元格表达式会把裸 `/` 当除法):`"/favicon.ico"`、`"image/png"`。
---
## 5. 插件 / 状态形状
### 5.1 页面对象新增字段
```json
{
"meta": { "title": "…", "icon": "/favicon.ico" },
"head": [
{ "rel": "stylesheet", "href": "/static/print.css", "media": "print" }
],
"images_html": "<div class=\"mq-images\">…</div>"
}
```
### 5.2 应用对象新增字段
```json
{
"static_dir": "public",
"static_mount": "/static",
"icons": [
{
"path": "public/favicon.ico",
"rel": "icon",
"type": "image/x-icon",
"sizes": "32x32",
"url": "/favicon.ico"
}
],
"site_head": [
{ "rel": "icon", "href": "/favicon.ico", "type": "image/x-icon", "sizes": "32x32" }
]
}
```
`site_head` 由 `web_app_icons`(及 static 约定)生成,作者不必手写。
### 5.3 `AppState` / `listen` 签名
新增:
- `icon_routes: Vec<IconRoute { url, path, content_type }>`
- `site_head: Vec<HeadLink>`
在 `home` / 动态与静态 `route` 渲染前:`merge_site_head(&mut page, &state.site_head)`。
---
## 6. MIME 推断
| 扩展名 | Content-Type |
|--------|----------------|
| `.ico` | `image/x-icon` |
| `.png` | `image/png` |
| `.svg` | `image/svg+xml` |
| `.webp` | `image/webp` |
| `.jpg` / `.jpeg` | `image/jpeg` |
| `.gif` | `image/gif` |
| `.webmanifest` / `.json` | `application/manifest+json` |
| 其他 | `application/octet-stream` |
---
## 7. 作者示例(中文)
```markdown
## 站点图标
|路径|关系|类型|尺寸|地址|
|---|---|---|---|---|
|public/favicon.ico|icon|image/x-icon|32x32|/favicon.ico|
|public/apple-touch-icon.png|apple-touch-icon|image/png|180x180|/static/apple-touch-icon.png|
## 头资源
|关系|地址|类型|媒体|
|---|---|---|---|
|icon|/favicon.ico|image/x-icon|
|stylesheet|/static/print.css|text/css|print|
|script|/static/live.js||
## 品牌图
|源|替代|类|链接|宽度|加载|
|---|---|---|---|---|---|
|/static/logo.svg|Marqdo|brand-logo|/|48|eager|
# main
*page = > 网页.页面 标题="博客"*
*page = > page.头装配 表=`头资源`*
*page = > page.图片装配 表=`品牌图`*
*page = > page.元数据 元数据=`seo表`*
*app = > 网页.应用 页面=`page` …*
*app = > app.静态 目录="public" 挂载="/static"*
*app = > app.图标 表=`站点图标`*
> app.监听
```
英文对称:`web.page` / `head` / `images` / `meta`;`web.app` / `static` / `icons`;模块 `web.make_images`。
---
## 8. 实现清单(本切片必须全部完成)
| # | 项 | 归属 |
|---|----|------|
| I1 | `assets.rs`:表解析、MIME、`web_images` HTML、`web_head` HTML、图标规范化 | `plugins/web` |
| I2 | `web_page_head` / `web_page_images` / `web_images` / `web_head` / `web_app_icons` FFI + 注册 | `plugins/web` |
| I3 | `head_html`:meta 图标键 + `page.head` + 合并 `site_head` | `render.rs` |
| I4 | `images_html` 插入主区;fragment main 同理 | `render.rs` |
| I5 | `listen`:图标文件路由 + static 约定 favicon + `AppState` 注入 | `http.rs` / `lib.rs` |
| I6 | `ext/web/web.mq.md` + `网页.mq.md` L1 方法与叙述 | `ext/web` |
| I7 | 金样:离线装配 + live `GET /favicon.ico` + HTML 含 link/img | `tests/ext/` |
| I8 | `examples/marqdo-blog`:真实 favicon + logo 装配 + README | `examples/` |
| I9 | 更新 [web-net-capabilities.md](web-net-capabilities.md)、[ext-web.md](ext-web.md)、[doc/README.md](../README.md)、CHANGELOG Unreleased;Skill 专节一句 | 文档 |
**非目标(本切片不做)**
- 服务端图片缩放 / WebP 转码
- CDN 签名 URL
- 把上传相册(`gallery`)与品牌图混为一谈
- 进程内 TLS(仍见反代文档)
---
## 9. 验收标准
1. `marqdo run tests/ext/web-assets-smoke.mq.md` 离线:icons/head/images 字段与 HTML 片段断言通过。
2. Live:`GET /favicon.ico` → 200 + 正确 Content-Type;首页 HTML 含 `rel="icon"` 与 `mq-images`。
3. `examples/marqdo-blog`:`curl /favicon.ico` 与页面源码可见图标与 logo。
4. 旧金样(`web-static-smoke`、`web-content-smoke` 等)不回归。
5. `ext/**` 无 `host_*`。
---
## 10. 与能力矩阵的关系
在 [web-net-capabilities.md](web-net-capabilities.md) **类 D** 增补:
| # | 能力 | 状态 |
|---|------|------|
| **D10** | 站点图标 / `/favicon.ico` / apple-touch-icon | ✅ 本设计 |
| **D11** | Head 资源表(link / script / preload / manifest) | ✅ 本设计 |
| **D12** | 图片装配(GFM → figure/img)+ 主区注入 | ✅ 本设计 |
波次标签:**W8(站点资源与图片装配)** — 在 W7+P3 完结之上的内容站体验补齐,不推翻既有边界。
+6
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)。
---
@@ -166,6 +168,9 @@
| D7 | **评论系统**(表单 + 审核 + 反垃圾) | ✅ 约定:表+表单+where(W6);反垃圾属应用层 | `ext/web` | P2 ✅ |
| D8 | **草稿/发布/定时**(状态字段 + 过滤查询) | ✅ 约定:`status` + where(W6) | `ext/web` + db where | P2 ✅ |
| D9 | **图片/附件库**(依赖 A5 上传 + 相册页) | ✅ **已实现(P3)**:`app.gallery` HTML 相册 + A5 上传/下载 | `ext/web` + `plugins/web` | P3 ✅ |
| **D10** | **站点图标 / favicon**(`/favicon.ico` + apple-touch-icon) | ✅ **已实现(W8)**:`app.icons` / `应用.图标`;`static` 约定 `favicon.*`;设计 [web-assets-and-images.md](web-assets-and-images.md) | `plugins/web` + `ext/web` | W8 ✅ |
| **D11** | **Head 资源表**(link / script / preload / manifest) | ✅ **已实现(W8)**:`page.head` / `页面.头装配`;`meta` 认 `icon`/`favicon` | `plugins/web` + `ext/web` | W8 ✅ |
| **D12** | **图片装配**(GFM → figure/img + 主区注入) | ✅ **已实现(W8)**:`make_images` / `网页.图片装配`;`page.images` | `plugins/web` + `ext/web` | W8 ✅ |
---
@@ -184,6 +189,7 @@
| **W6** | 进阶 | 全文搜索(FTS5) + 迁移机制 + 评论系统 + 草稿/发布 + WS 广播 | B6 B9 ✅;WS 广播 + access_log ✅;D7/D8 用表+where ✅ |
| **W7** | 完结打磨 | Cache-Control、自定义 404/500、301 重定向、sitemap/robots、init 唯一/索引、HTTPS 反代文档 | A6 A7 A9 A10 B7 D2 ✅ |
| **P3** | 真·网络扩展补齐 | 审计时间戳、外键、RBAC 门禁、媒体相册、下载 ETag | B10 C8 D9 + ETag/FK ✅ |
| **W8** | 站点资源与图片装配 | favicon 根路由、Head 资源表、图片装配、meta 图标键 | D10 D11 D12 ✅ |
### 4.2 边界判定要点(严格遵守既有约束)
+54
View File
@@ -0,0 +1,54 @@
# 调研刷新:2026-09 智能体框架与 Marqdo「代码即文档」
| | |
|---|---|
| 状态 | **Wave B1 Active**(B0/B0.5 已完成;宪法优先) |
| 日期 | 2026-09-04 |
| 前置 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) |
| 路线 | [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) |
## 0. 结论
业界框架(LangGraph / Microsoft Agent Framework / CrewAI / OpenAI Agents SDK)在编排、工具、检查点、MCP、评测上继续收敛;**权威真相仍默认在对象图 + transcript + 外置 Store**。
Marqdo 的差异化不是「再做一个 loop」,而是:
1. **代码即文档** — 编排 `.mq.md` = 提示词工作面
2. **调用位置可见** — `agent_call_site`(路径 / 函数 / 行)是一等上下文
3. **文档即知识库(OKF)** — 写回 → promote / solidify → 二次命中 / `llm_free`
Wave B 的目标函数:**证明并硬化上述三点**;产品化示例与评测必须服务差异化,禁止做成无源码上下文的 chatbot demo。
## 1. 业界快照(2026)
| 模式 | 代表 | 状态记忆 | 对 Marqdo |
|------|------|----------|-----------|
| 图 + checkpointer | LangGraph | typed state 持久化 | 续跑应对齐**文件化工作簿**,不造 Python 图 DSL |
| Agent vs Workflow | Microsoft AF | 自主 + 确定性流 | 已有 step / plan,强化即可 |
| 角色班组 | CrewAI | Task 管道 | 多 Agent 低优先;父 CALL + 多工作簿 |
| Handoff + Guardrails | OpenAI Agents SDK | 显式交接 | 可借鉴语义;权威仍在 `.mq.md` |
## 2. 深远影响(开发硬约束)
| 约束 | 含义 |
|------|------|
| 提示不黑盒 | standing / 工具 / 任务写在文件;拼装可审查 |
| 位置感知 | 每次推理注入 call_site;示例与评测可断言 |
| 源码工作面 | `source_brief` + `READ:source\|skill`;禁止藏整份 Skill 进不可见提示 |
| 写回即记忆 | ok/error 槽 + view;非默认向量库 |
| OKF 飞轮 | promote / solidify / hit / llm_free |
| 外置工具 | corpus / MCP 仅证据,`authority=workbook` |
## 3. Wave B 范围
| 波次 | 主题 |
|------|------|
| **B0** | 宪法可见示例 + 上下文管道可读性 + Skill/文档 |
| **B0.5** | 本机 live(`.env` → cflmy)验证「模型用上了文档」 |
| **B1** | 评测锁住 call_site / OKF / 写回 / 预算 |
暂缓:真 MCP、resume/HITL view、kb stats、并行、A2A。
## 4. 开发期 LLM
仓库根目录 `.env`(gitignore):`OPENAI_*` 或 `MARQDO_LLM_*`。模板见 `.env.example`。
@@ -70,6 +70,7 @@
| **高** | 官方端到端示例 + 文档新鲜度 | 无独立 `examples/agent-*`;Skill/参考里仍有「layout / roadmap」陈旧表述;外人难「照抄即跑通 plan→固化→二次命中」 | `examples/agent-pong`(或同类)+ README;Skill 专节与 A0–A4 对齐 |
| **高** | Agent 评测 / 回归 harness | 有离线金样,缺成本·恢复·命中率·补丁质量的系统评测;业界强调 evaluation 先于上线 | `tests/` 或脚本:命中率、llm_free 占比、失败恢复、可选 live 预算 |
| **高** | 真 MCP(HTTP/SSE)与凭证 | A4 仅 JSON fixture;缺 streamable HTTP、鉴权、resources/prompts | 金样打 mock MCP server;返回仍带 `authority=workbook` |
| **高** | **MCP Server 宿主**(stdio / HTTP) | Agent 只能当客户端 fixture;IDE 无法把 `.mq.md` `##` 暴露为 MCP 工具 | 见 [ext-hosting-gaps.md](ext-hosting-gaps.md) GAP-03 · [ext-hosting-fill.md](../design/ext-hosting-fill.md) |
| **中** | Plan 断点续跑 | 工作簿在盘上,缺显式 checkpoint / resume(对标 LangGraph checkpointer) | `plan resume=` 从第 N 轮 DECISION 继续;进程崩溃可恢复 |
| **中** | 人机协同(HITL)加深 | 仅有 `confirm=True` 建簿即停;缺审批卡、拒绝重开、view 一键继续 | view 审批控件 + 金样 |
| **中** | 飞轮可观测指标 | `hits` / `improve_every` / `llm_free` 有字段,缺汇总与 CLI/view 报表 | `agent_kb_stats` 或 view 面板:命中率、探索浪费 |
+156
View File
@@ -0,0 +1,156 @@
# 调研:宿主集成缺口(浏览器中继 · HTTP→`##` · MCP Server · 同寿副端口 · 跨模块 DB/检索)
| | |
|---|---|
| 状态 | **调研笔记 · 缺口盘点(H1–H4 stdio 已落地;H4b HTTP 可选)** |
| 日期 | 2026-09-07 |
| 触发 | 下游应用(对话站 / 求道类 Agent)在真实集成中被迫旁路 Python 脚本 |
| 基线版本 | **v0.3.6+**(宿主波次 H1–H4 见 [ext-hosting.md](../roadmap/ext-hosting.md)) |
| 相关设计 | [ext-web.md](../design/ext-web.md) · [ext-web-net.md](../design/ext-web-net.md) · [web-net-capabilities.md](../design/web-net-capabilities.md) · [ext-agent.md](../design/ext-agent.md) · [ext-abi.md](../design/ext-abi.md) |
| 邻近缺口 | [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md)(真 MCP **客户端**) |
| 补齐设计 | [ext-hosting-fill.md](../design/ext-hosting-fill.md) |
| 实现路线 | [ext-hosting.md](../roadmap/ext-hosting.md) |
---
## 0. 一句话结论
`ext/web` 已能做**内容站 / CRUD / JSON-DB API / WS**;`ext/ai` 已能做**工作簿 Agent + 客户端 SSE 消费**。下游要把「浏览器同域流式 LLM」「请求触发任意 `##`」「MCP Server 被 IDE 拉起」合进**单一 Marqdo 进程**时,现有扩展**没有一等装配**——只能外挂缓冲代理 / CLI 子进程。缺口集中在 **扩展库作者面 + `plugins/web|agent` ABI**,不是语法层,也不是再开一套标准库。
**原则:** 旁路脚本只证明需求;关闭缺口必须把能力沉进 `ext/*` + `plugins/*`(可选极薄 `lib/` 编排),禁止把领域逻辑塞进 `src/host/`。
---
## 1. 已有基线(不是缺口)
| 能力 | 现状 | 文档 / 金样 |
|------|------|-------------|
| CORS / 安全头 / gzip / body limit | `app.configure` | `tests/ext/web-middleware-smoke.mq.md` |
| JSON **DB select** 路由 | `configure json=` | `plugins/web/src/middleware.rs` |
| `/_form/*` SQL CRUD | `mount_form` | `plugins/web/src/form.rs` |
| 客户端缓冲 SSE | `lib/net.http_post_sse` → `ext/llm.complete stream=` | `tests/lib/net-openai-sse.mq.md` |
| 执行过程 SSE(非 LLM 中继) | `marqdo view` `/api/run` | [view.md](../design/view.md) §5 |
| Agent 证据工具(fixture MCP) | `corpus_search` / `mcp_list_tools` / `mcp_call` | A4;[agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) |
| 同模块 `# db` CRUD | `ext/web` `# db` | `examples/web-site/db/` |
---
## 2. 缺口总表
| ID | 缺口 | 需要 | Marqdo 现状 | 典型旁路 | 解除条件 |
|----|------|------|-------------|----------|----------|
| **GAP-01** | 浏览器 → 上游 LLM **同域流式中继** | 绕过对方 CORS;**SSE 原样转发** | **`app.proxy` / `configure proxy=`**(H1) | ~~`llm_proxy.py`~~ | ✅ 已关闭 |
| **GAP-02** | HTTP 处理函数可调用用户 `##` | 请求内执行用户 `##`,返回 JSON | **`app.invoke` / `configure invoke=`**(H2) | ~~外挂 `marqdo run`~~ | ✅ 已关闭 |
| **GAP-03** | **MCP Server** 宿主 | IDE 拉起暴露工具 | **`agent.mcp_server` + `serve` stdio**(H4);HTTP=H4b | ~~`qdagent_mcp.py`~~ | ✅ stdio;HTTP 可选 |
| **GAP-04** | 同寿「第二监听端口」 | 与 `listen` 同寿中继 | 并入主端口(H1+H2) | ~~`mq.sh` 双进程~~ | ✅ won't |
| **GAP-05** | 跨模块 `db`;纯 run 用 corpus | 跨文件 `select`;CLI 检索 | 传递归查找 + `corpus_search` ensure_plugin(H3) | ~~db/index 导出~~ | ✅ 已关闭 |
旁路脚本名来自下游集成仓库;**本仓库 `scripts/` 不含这些文件**——它们是需求证据,不是上游实现。
---
## 3. 分项说明
### 3.1 GAP-01 · 同域 SSE 中继
**问题**
浏览器页面跑在 `ext/web` 源上时,直连 OpenAI 兼容上游会撞 CORS;`lib/net.http_post_sse` 只在 **CLI/宿主侧缓冲整段流**,不能把字节边收边推回浏览器。
**现状边界**
| 已有 | 缺什么 |
|------|--------|
| `app.configure cors=` | 解决的是**本站对外** CORS,不是替上游开 CORS |
| `http_post_sse` → `{status, events}` | **客户端消费**,非服务器中继 |
| `app.download` 对象流 | 存储下载,非上游 SSE |
| view `/api/run` SSE | Marqdo **执行事件**,非 LLM token 流 |
**解除形态(产品)**
作者声明:`path` + `upstream`(或 env)+ 可选 header 白名单;监听端对浏览器返回 `Content-Type: text/event-stream`,chunk 原样或按 OpenAI SSE 帧转发。
### 3.2 GAP-02 · 路由 → `##`
**问题**
对话沉淀、表单后写 `data/runs/*.mq.md`、触发 `lib/run.沉淀` 等,需要**同进程**执行用户函数。今天只有:
1. 页面装配期 `call_lib_path`(compose,非每请求);
2. `/_form` / `json=` 的 **DB 专用** handler。
**解除形态(产品)**
声明式:`path` · `method` · `fn=lib.member` 或 `file=… ## name` · body→形参映射 · 返回值序列化为 JSON(错误码约定)。安全默认:仅允许入口模块已导入路径;禁止任意路径注入。
### 3.3 GAP-03 · MCP Server
**问题**
A4 解决的是 Agent **调用** MCP 工具(且仍是 fixture)。下游要把 Marqdo 工作簿 **暴露为** MCP Server(stdio / Streamable HTTP),IDE 拉起后调 `qd_*`。
与 [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md)「真 MCP 客户端」正交:本缺口是 **Server 宿主**。
**解除形态(产品)**
`ext/ai`(或 `ext/mcp`)提供:`server tools=` 表(name → `.mq.md`/`##`);`serve stdio=` / `serve http port=`;工具结果仍可带 `authority=workbook`。
### 3.4 GAP-04 · 同寿副端口
**问题**
在 GAP-01/02 未并入主端口前,下游用第二端口跑代理。`app.listen` 同步阻塞,无「同进程再绑一个 TcpListener」的作者 API;只能 shell 并起另一运行时。
**解除形态(产品)**
优先:GAP-01/02 挂在同一 `listen` → **本缺口关闭**。备选:`app.attach` / `listen also=` 同 tokio 运行时附加服务(仅当必须隔离路径树)。
### 3.5 GAP-05 · 跨模块 DB 句柄与 corpus 可发现性
**问题**
1. **类型分发:** 插件对象依赖 `_type` / 方法表;跨模块传回的 store 若丢类型或未注册方法,报 `unknown object type db`。同文件 `db/index.mq.md` 内 `## recent` 再导出 JSON 是现行绕过。
2. **`agent_corpus_search`:** 注册在 `plugins/agent`;普通 `marqdo run` 未 `plugin.load` / 未构造 `# agent` 时不可用。导入 `ext/ai/agent.mq.md` 文本本身不保证原生插件已加载。
**解除形态(产品)**
句柄:跨模块返回值保留 `_type=db` 且方法分发查全局/插件表(修运行时或约定「只返回 url,调用方再 `web.db`」二选一,见补齐设计)。corpus:`plugin.load` 自动路径,或 `ext/ai` 导出独立 `## corpus_search` 并在调用前 `ensure_plugin`。
---
## 4. 归属判定(标准库 vs 扩展)
沿用 [ext-web-net.md](../design/ext-web-net.md) / [web-net-capabilities.md](../design/web-net-capabilities.md) 边界:
| 能力 | 归属 | 理由 |
|------|------|------|
| SSE **中继**路由、HTTP→`##`、副端口 | **`plugins/web` + `ext/web`** | 服务器结构 / 网站领域;axum 已在依赖链 |
| MCP **Server**、corpus 可发现 | **`plugins/agent` + `ext/ai`** | Agent/工具宿主;禁止塞 `src/host/` |
| 缓冲 SSE 客户端、解析 | 已有 **`lib/net`** | 不新增中继到 stdlib |
| 任意路径 shell 出去跑 `marqdo` | **刻意不做进核心** | 旁路脚本可留在下游;上游给一等 API 后废弃 |
---
## 5. 优先级建议
| 优先级 | ID | 理由 |
|--------|-----|------|
| **高** | GAP-01 + GAP-02 | 去掉 Python 中继的主路径;浏览器站 + 沉淀闭环 |
| **高** | GAP-03 | IDE 生态入口;与「真 MCP 客户端」可并行设计、分波交付 |
| **中** | GAP-05 | 减少 `db/index` 与 bridge 胶水;影响面偏语言/插件加载 |
| **低(可随 01/02 关闭)** | GAP-04 | 并入主端口后自然消失 |
---
## 6. 明确「不是缺口」
| 项 | 说明 |
|----|------|
| 内容站 W0–W7+P3 | 已完结;本清单不重开上传/RSS/RBAC |
| Mid M1–M6 | 通用原语已够;本清单不是再开 `lib/re` 一类 |
| 隐藏 JSON TOOL 主循环 | 与 Agent 宪法冲突 |
| Dense embedding 默认化 | 仍见 [okf-near-match.md](../roadmap/okf-near-match.md) |
| 浏览器手写业务 JS 代理 | 与 WASM 路线「作者零 JS」冲突;中继应在服务端 `ext/web` |
---
## 7. 与其它文档
| 文档 | 关系 |
|------|------|
| [ext-hosting-fill.md](../design/ext-hosting-fill.md) | **补齐设计(作者 API + ABI)** |
| [ext-hosting.md](../roadmap/ext-hosting.md) | 实现波次 H0–H4 |
| [ext-web.md](../roadmap/ext-web.md) | 站点主线完结;本缺口为后续宿主波次 |
| [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) | 客户端真 MCP;与 GAP-03 Server 互补 |
| [web-asgi-servers-and-marqdo.md](../design/web-asgi-servers-and-marqdo.md) | 反代模型;中继仍在 Marqdo `listen` 内 |
+113
View File
@@ -0,0 +1,113 @@
# 调研:线性代数 × 公式类 × 展示
| | |
|---|---|
| 状态 | 调研纪要(为 [ext-linalg](../design/ext-linalg.md) 供输入) |
| 日期 | 2026-09-07 |
| 相关 | [stdlib-math.md](../design/stdlib-math.md) · [ext-quantum-q7.md](../design/ext-quantum-q7.md) · SymPy MatrixExpr · Symbolics.jl · LAFigureSpecs |
---
## 1. 问题陈述
Marqdo 已有:
- `Value::Formula` + `` `f` = `` + `$$…$$`(高中标量符号)
- `formula::Expr::Matrix`:**数值**稠密矩阵字面量(`[[…]]` / `\begin{pmatrix}`),供量子门核对与 view KaTeX
- `ext/quantum` Q7:**量子语境**下的密度矩阵 / Kronecker / 谱 / SVD 风格图(ABI)
缺口:一门**经典线性代数**扩展——作者用**公式级矩阵表达式**写 \(A^\top A\)、\((X^\top X)^{-1}X^\top y\)、分块、Kronecker,在**不立刻展开成巨大稠密矩阵**的前提下做重写与化简,并在文档 / view 中**好看地呈现**分解与结构。
---
## 2. 业界对照
### 2.1 符号矩阵表达式(大规模优化的关键)
| 系统 | 模型 | 对 Marqdo 的启示 |
|------|------|------------------|
| **SymPy `MatrixExpr`** | `MatrixSymbol(name, n, m)` + `MatMul` / `MatAdd` / `Inverse` / `Transpose` / `Trace` / `Determinant` / `BlockMatrix` / `KroneckerProduct`;`as_explicit()` 才展开 | **默认保持抽象**;形状元数据传播;显式求值是可选动作 |
| SymPy `block_collapse` | 分块表达式在块级化简,避免整块稠密展开 | 分块是教学与优化的第一公民 |
| SymPy Kronecker | `KroneckerProduct` 惰性 + `combine_kronecker` 规则 | Kronecker **绝不能**默认 `expand`(维数爆炸) |
| SymPy 矩阵求导 | 经 array expr 再收回 MatrixExpr;闭式导数 | v1 **不做**;记入远期 |
| **Symbolics.jl** | 「数组的符号」vs「符号数组」:后者 O(1) 表示整阵,保留 `A*B` 不展开 | 与 MatrixExpr 同构;强调 **shape / eltype 元数据** |
| NumPy / Eigen / nalgebra | 数值热路径,无公式树 | 对应 Marqdo **插件数值层**,不是文档作者主路径 |
**结论:** 「公式类线性代数」= **抽象表达式 DAG + 形状检查 + 重写规则**;稠密数值是 `eval` / `as_explicit` 的终点,不是默认形态。
### 2.2 教学与展示(效果最好的做法)
| 做法 | 来源 | 效果 | Marqdo 映射 |
|------|------|------|-------------|
| KaTeX / MathJax 渲染 `bmatrix` / `pmatrix` | SymPy `latex()` + Jupyter `init_printing` | 公式即排版;多式用 `display` 并列 | 既有 view `formula-card` + KaTeX |
| 标签化等式 `A = UΣV^\top` | 教材 / Qiita display+Math | 步骤可读 | `show` / writeback 多卡片 |
| **结构图**(SVD / QR / 消元轨) | [LAFigureSpecs](https://github.com/ea42gh/LAFigureSpecs) + matrixlayout;TeX `drawmatrix` | 比数字表更能讲「秩 / 零空间 / 对角结构」 | SVG `kind=svd|qr|ge|eig` |
| 热力图 / Hinton | Qiskit / QuTiP / 既有 quantum | 稠密数值矩阵的幅度/符号 | `kind=heatmap|hinton`(经典实/复) |
| 分块着色矩形 | CTAN `drawmatrix` | 零块 / 三角 / 带状一目了然 | `kind=structure`(形状示意图,可无元素值) |
| 仅打印 ASCII | CLI 默认 | 金样可断言 | `str` / `print` → 规范 ASCII / LaTeX 源 |
**展示优先级(锁定建议):**
1. **符号式**:始终可 `latex` → view KaTeX(不依赖数值)
2. **结构式 SVG**:分解 / 分块 / 秩示意(教学主图)
3. **数值热力图**:仅在 `eval` 后、维数可控时
4. CLI:短 ASCII;大矩阵默认摘要 `m×n …` + 可选 `preview=`
### 2.3 一门「够用」的线性代数库需要什么
按大学一学期 + 数据科学入门,能力桶:
| 桶 | 内容 | 符号层 | 数值层 |
|----|------|--------|--------|
| A 构造 | 符号阵、常数阵、单位/零/对角、从 `$$` / 表 / list | ✅ | ✅ |
| B 代数 | 加减乘、转置、逆、伴随、幂、Kronecker、分块 | ✅ 重写 | ✅ |
| C 分解 | LU / QR / 特征 / SVD / Cholesky(对称) | 结果对象 + 结构图 | ✅ |
| D 系统 | `Ax=b`、最小二乘、伪逆 | 公式写法 + 数值解 | ✅ |
| E 度量 | 行列式、迹、秩、范数、条件数 | 部分可符号 | ✅ |
| F 展示 | latex / ASCII / SVG 结构 / heatmap | ✅ | ✅ |
| G 微积分 | 矩阵导数、Jacobian 积木 | 远期 | — |
**不做(首版):** 稀疏专用格式、GPU、分布式、完整 CAS 证明、通用张量网络、与 `lib/math` 高中标量混成一个巨模块。
---
## 3. 与现有 Marqdo 的衔接点
| 已有 | 用法 | 扩展时注意 |
|------|------|------------|
| `$$` + Matrix 数值字面量 | 小门矩阵、手算核对 | 保留;符号阵用 `MatrixSymbol` 或 `matrix.symbol`,勿与数值 Matrix 混为一谈 |
| `lib/math` formula | 标量 simplify/diff/plot | **不**把大学线性代数塞进 `lib/math`(与 Q7 结论一致) |
| view KaTeX | formula-card | 符号 MatExpr 的 `latex` 字符串直接喂 KaTeX |
| `ext/quantum` Q7 linop | 量子密度 / 纠缠 | **经典 API 不复用 quantum 命名空间**;共享算法可在插件内私有复用,作者面分离 |
| `plugins/*` ABI | 重数值 / SVG | 稠密分解与大图走 `plugins/linalg` |
| GFM 表 | 数据即代码 | 矩阵输入:表或 `$$`;分解步骤:`@` 记录表 |
---
## 4. 「大规模优化」具体指什么
在公式类语境下,优化 ≠ BLAS 微内核,而是:
1. **惰性**:`A*B*C` 保持乘积树,直到 `eval` / `explicit`
2. **形状短路**:不相容维数在符号阶段报错,不跑数值
3. **代数恒等**:`(A^{-1})^{-1}→A`,`(AB)^\top→B^\top A^\top`,`I*A→A`,分块 `block_collapse`
4. **禁止爆炸展开**:Kronecker / 高维符号积默认不 `expand`
5. **数值批处理**:同形状多 RHS、分解一次多用(`factorize` 对象)
6. **展示成本**:大矩阵不默认内嵌完整 KaTeX 数字阵;结构图 + 摘要
---
## 5. 推荐产品叙事(一句)
**线性代数文档用公式写变换,用规则做化简,用结构图讲分解,用可控数值做验算——公式是一等公民,稠密矩阵是可选终点。**
---
## 6. 参考链接
- SymPy Matrix Expressions: https://docs.sympy.org/latest/modules/matrices/expressions.html
- SymPy Matrix derivatives (远期): https://docs.sympy.org/dev/explanation/modules/matrices/matrixderivatives.html
- Symbolics.jl Symbolic Arrays: https://docs.sciml.ai/Symbolics/v6.54/manual/arrays/
- LAFigureSpecs(教学结构图): https://github.com/ea42gh/LAFigureSpecs
- CTAN drawmatrix: 矩阵形状示意
- 既有:`doc/design/stdlib-math.md` · `doc/design/ext-quantum-q7.md`
@@ -0,0 +1,154 @@
# `ext/web` 定制限制:开发者不易定制的问题盘点
| | |
|---|---|
| 状态 | **调研锁定(踩坑整理)** |
| 日期 | 2026-09-04 |
| 相关 | [ext-web.md](../design/ext-web.md) · [ext-web-net.md](../design/ext-web-net.md) · [web-net-capabilities.md](../design/web-net-capabilities.md) |
| 解决索引 | [../design/ext-web-customization/](../design/ext-web-customization/) |
结合自研后台、样式迁移与响应式改造中的实际踩坑,整理当前 `plugins/web` + `ext/web` 对站点作者的**强占与难定制点**。本文只陈述问题与证据;逐项解法见解决索引。
---
## 0. 一句话
内置 `/admin` 壳、固定鉴权路径、注入式 `SHELL_CSS` 与四区栅格,让「只写 `.mq.md`」的产品路径在**自研后台 / 品牌主题 / 移动端**上反复撞墙;作者被迫旁路前缀 + `!important` + 前端 JS 兜底。
---
## 1. 路由与路径被框架强占
**现象**
- `/admin` 及 `/admin/*` 整段保留,无法 `app.route` 注册自定义页(错误:`route path … is reserved`)。
- `app.重定向` / `redirect` 目标若落在 reserved 前缀,同样被校验拒绝。
- `后台=False`(`admin=False`)后,访问 `/admin/news` 等仍进内置壳,只显示 *Admin is disabled*,**不能**换成自研页。
- 登录/登出硬绑 `/admin/login`、`/admin/logout`;登录成功硬编码 `Redirect::to("/admin")`,无法配置回跳到 `/desk`。
**代码证据**
| 位置 | 行为 |
|------|------|
| `plugins/web/src/lib.rs` → `normalize_route_path` | `/admin`、`/_form`、`/_part`、`/static` 一律 reserved |
| `plugins/web/src/http.rs` | 始终挂 `/admin…` 路由;disabled 时仍 `admin_shell` + 文案 |
| 同文件 `admin_login_post` | 成功跳转写死 `/admin` |
**结果**
自研后台只能用 `/desk` 等旁路前缀;入口与鉴权路径分裂,还要靠前端 JS(`fetch('/admin/login')` 再 `replace('/desk')`)做跳转兜底。
→ 解决:[01-routes-and-admin-prefix.md](../design/ext-web-customization/01-routes-and-admin-prefix.md)
---
## 2. 内置 `SHELL_CSS` 难以彻底覆盖
**现象**
- 每个页面都会注入框架壳样式,例如 `body.has-sidebar { grid-template-columns:14rem 1fr; … }`、默认卡片/表单/侧栏色。
- 规则**无媒体查询**、选择器优先级不低;站点主题选择器不够强时,小屏双列、侧栏占位等「幽灵布局」反复出现。
- 首页有额外 class(如 `has-rail`)时碰巧盖住,其他页没有同类 class 就暴露——表现为「只修了首页」。
- 实务上经常要 `!important` + 更高选择器,与「干净主题层」冲突。
**代码证据**
| 位置 | 行为 |
|------|------|
| `plugins/web/src/render.rs` → `SHELL_CSS` | 常量内联进每个 HTML |
| 同文件壳渲染 | `<style>{SHELL_CSS}{extra}</style>`,主题只能接在后面 |
→ 解决:[02-shell-css.md](../design/ext-web-customization/02-shell-css.md)
---
## 3. 鉴权 / 门禁模型偏固定
**现象**
- 未登录访问受保护路径:对 `/admin*` 会 **303 → 登录页**;对 `/desk` 等自定义路径往往是 **403 HTML**,行为不一致。
- 门禁匹配偏宽:`path.starts_with` / `path_matches` 使 `/desk` 匹配 `/desk/login`,公开登录页易被误伤。
- 默认鉴权挂上 `/admin*` → `admin`;`/admin-publish` 这类名字也会被当成 admin 域(`starts_with("/admin")`)。
- 会话 cookie、CSRF、登录表单字段均固定在框架实现;难换登录 UI 或改成功落地页。
**代码证据**
| 位置 | 行为 |
|------|------|
| `http.rs` → `rbac_middleware` | visitor + `/admin*` → redirect;其它 gate → 403 |
| `http.rs` → `path_matches` | 前缀匹配,无「精确路径 + 子路径排除」DSL |
| `lib.rs` → `web_app_auth` | 默认塞入 `/admin*` gate |
→ 解决:[03-auth-gates.md](../design/ext-web-customization/03-auth-gates.md)
---
## 4. 样式作者体验受限
**现象**
- 样式表是 GFM 表格;含 `/` 的值必须加引号(如 `"1 / 5"`),否则单元格表达式把 `/` 当除法(曾出现 `grid-column` 变成 `0`)。
- `@keyframes`、复杂选择器、多层媒体查询(`min-width` and `max-width`)表达能力有限,装配顺序要小心。
- 主题 CSS 与 `SHELL_CSS` 同页串联,级联顺序不透明,调试成本高。
- 响应式不能指望框架;壳层几乎不提供移动端抽屉/折叠。
→ 解决:[04-stylesheet-authoring.md](../design/ext-web-customization/04-stylesheet-authoring.md)
---
## 5. 页面壳与插槽约定僵硬
**现象**
- 壳结构固定为 `topnav` / `side` / `main` / `foot` 栅格命名区。
- 侧栏一旦装配,`body` 即 `has-sidebar`,套上框架双列;杂志风单列、抽屉必须自己拆布局。
- 组件表驱动导航,难做运行时条件导航(小屏合并顶栏+侧栏),通常再补 `theme.js`。
→ 解决:[05-page-shell-slots.md](../design/ext-web-customization/05-page-shell-slots.md)
---
## 6. 后台 CRUD 与表单能力边界
**现象**
- 内置 admin 是通用表管理,不是产品级 CMS;**关了又占着 `/admin` 路径**(与 §1 叠加)。
- 表单以声明式字段表为主;Markdown 分栏、专栏元数据联动等只能外挂 JS。
- 列表「链接前缀」等约定简单;编辑/新建状态机常靠前端拼(`?id=`、`?new=1`)。
→ 解决:[06-admin-crud-forms.md](../design/ext-web-customization/06-admin-crud-forms.md)
---
## 7. 静态资源与脚本生命周期
**现象**
- 头资源脚本常在 `<head>` **同步**加载;若脚本假设 DOM 已就绪会直接失败(登录页曾因此不跳转)。
- 缓存靠 `?v=` 手动 bump;无构建管线时易出现「改了 JS 浏览器仍用旧文件」。
→ 解决:[07-assets-script-lifecycle.md](../design/ext-web-customization/07-assets-script-lifecycle.md)
---
## 8. 扩展与部署耦合
**现象**
- 能力依赖 web 插件 ABI / Marqdo 版本(如 0.3.2 起的样式引号约定);升级要同步 Docker / 本机二进制。
- 定制若依赖改插件源码(放宽 `/admin` reserved、可配置 login redirect),就脱离「只写 `.mq.md`」的产品路径,维护成本陡增。
→ 解决:[08-ext-deploy-coupling.md](../design/ext-web-customization/08-ext-deploy-coupling.md)
---
## 9. 优先级建议(给实现排期)
| 优先级 | 项 | 理由 |
|--------|-----|------|
| P0 | §1 路由/前缀 + §3 鉴权一致 | 阻塞自研后台产品路径 |
| P1 | §2 SHELL_CSS + §5 壳布局 | 阻塞品牌主题与响应式 |
| P2 | §4 样式作者体验 + §7 脚本生命周期 | 降低日常踩坑,不改架构也能缓解 |
| P3 | §6 CRUD 边界 + §8 部署耦合 | 文档/约定/可选增强为主 |
详细验收与实现切片见解决索引 README。
+144
View File
@@ -0,0 +1,144 @@
# 调研:Mid M1–M6 之后标准库还缺什么
| | |
|---|---|
| 状态 | **调研笔记 · 缺口盘点(M1–M6 闭环之后)** |
| 日期 | 2026-09-08 |
| 基线 | **v0.3.7+** · Mid M1–M6 **done** |
| 已落地设计 | [stdlib-mid.md](../design/stdlib-mid.md) · [stdlib-modules.md](../design/stdlib-modules.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
| 补齐设计 | [stdlib-mid2.md](../design/stdlib-mid2.md) |
| 实现路线 | [stdlib-mid2.md](../roadmap/stdlib-mid2.md) |
| 外部对照 | Python stdlib([use-case 索引](https://www.socratopia.app/library/python-programming-ai-era-en/chapter-15) · [PEP 680 tomllib](https://peps.python.org/pep-0680/))· Go `strings`/`regexp`/`encoding/*`/`crypto`/`path`/`time`/`net/url` · Node 内置 vs userland |
---
## 0. 一句话结论
**M1–M6 已把「写日常脚本 / 多数扩展库不再事事插件」的硬缺口补齐。** 相对 Python / Go 的「通用原语层」,Marqdo **不再缺** 正则、编解码、路径、哈希、CSV、集合糖、CLI、日志、UUID。
仍缺的是 **第二档通用能力**:日历与时区、URL/查询串、配置格式(优先 TOML)、HTML 安全转义、文件系统再厚一点(`mkdir -p` / 元数据 / 递归删除)、轻量统计。这些**值得开 Mid2(M7+)**,但**不应**再开一轮「事事插件」;也**不要**把 YAML 全家桶、HTTP 服务端、SQLite、图像/ML 塞进 `lib/`。
---
## 1. 已有基线(不是缺口)
| 族 | Marqdo | 对标 |
|----|--------|------|
| 文本 / 正则 | `text`++ · `re` | Python `str`/`re` · Go `strings`/`regexp` |
| 编解码 | `encoding`(base64/hex)· `net.url_encode` | Go `encoding/base64`/`hex` · Python `base64`/`binascii` |
| 路径 / 文件 | `path` · `fs`(含 copy/move/temp) | Go `path/filepath` · Python `pathlib`(子集) |
| 完整性 / 机密 | `hash` · `secrets` | Go `crypto` 子集 · Python `hashlib`/`secrets` |
| 表数据 | `csv` · `table`++ · `json` | Go `encoding/csv`/`json` · Python `csv`/`json` |
| CLI / 可观测 | `cli` · `log` · `uuid` | Python `argparse`/`logging`/`uuid`(窄) |
| 时间(极简) | `time`:unix/ms · format · parse · sleep | **远薄于** Python `datetime`/`zoneinfo` · Go `time` |
| 网络客户端 | `net`:HTTP/SSE/cookie/multipart/markdown | Go `net/http` **客户端**侧;服务端在 `ext/web` |
| 数学 | `math`(含公式/作图) | Python `math` + 教学向扩展 |
准入宪法仍见 [stdlib-mid.md](../design/stdlib-mid.md) §3:跨领域、难写对、解锁无插件写库、宿主面积极小。
---
## 2. 对照总表(按「脚本作者是否还要 foreign / 自造轮子」)
| 能力 | Python / Go 常态 | Marqdo 现状 | 缺口级别 | Mid2 建议 |
|------|------------------|-------------|----------|-----------|
| 日历日期 / 时区 / timedelta | `datetime`+`zoneinfo` · `time` | 仅 unix 戳 + 简单 format/parse | **高** | **M7** `datetime` |
| URL 解析 / 查询串 | `urllib.parse` · `net/url` | 仅 `url_encode` | **高** | **M7** `url`(或并入 `net`) |
| 配置 TOML 只读 | `tomllib`(PEP 680) | 无 | **中高** | **M8** `toml`(只读优先) |
| 配置 YAML | 第三方;**故意不进** CPython | 无 | **低 / 慎入** | 默认 **不做**;与 Python 同理(复杂度/安全) |
| HTML / XML 转义 | `html` · `html/template` 转义 | 无(`markdown_parse` ≠ 转义) | **中** | **M8** `html` 或 `text.html_escape` |
| `mkdir -p` / 递归删 / stat | `pathlib`/`shutil` | `make_dir`/`remove` 偏浅 | **中** | **M9** `fs` 加厚 |
| 文件元数据(size/mtime) | `os.stat` · `Path.stat` | 无一等 API | **中** | **M9** |
| base32 / percent 完整 | `base64.b32*` · `url` | 无 base32 | **低–中** | **M8** `encoding` 加厚 |
| 轻量统计 | `statistics` | `math` 无 mean/median | **低–中** | **M10** `stats` 或 `math` 薄加 |
| 计数 / 默认字典 / deque | `collections` | `table` 可凑 | **低** | 优先用 `table`;必要时 M10 `collections` 极薄 |
| 组合迭代 | `itertools` | 无 | **低** | 多数可用 `table`;**延后** |
| 模板引擎 | Jinja / Go `text/template` | 无 | **不准入 Mid** | 应用层 / 未来 ext |
| SQLite 客户端 | `sqlite3` · `database/sql` | **`ext/web` `# db`** | **不准入** | 保持扩展 |
| HTTP 服务端 | — | **`ext/web`** | **不准入** | 已关闭(宿主波次另文) |
| 密码哈希 Argon2 | 第三方 / 框架 | `ext/web` 已有 | **不准入 Mid** | 安全产品面 |
| 完整 TLS/证书 API | `ssl` · `crypto/tls` | 客户端 HTTPS 由 ureq | **不准入** | 宿主实现细节即可 |
| 压缩 zip/tar | `zipfile` · `archive/zip` | 无 | **低** | 可选 M10;体积敏感 |
| 环境 `.env` | 第三方;Go 常自写 | **`sys.load_dotenv` 已有** | 无 | — |
---
## 3. 分项说明(高优先级)
### 3.1 日历 / 时区(M7 候选之首)
**问题**
脚本与站点大量需要「今天」「本地日界」「RFC3339」「时区换算」。现有 `time.parse`/`format` 够演示,不够「难写对」的日历语义(闰秒除外,但 DST / offset 已够劝退字符串拼接)。
**对照**
Python 强调 **aware datetime + zoneinfo**;Go `time.Location` 是日常依赖。Mid 原文已把「完整 datetime 时区库」标为刻意延后——M1–M6 完成后应升格。
**建议窄 API(设计文锁定)**
`now` / `parse` / `format` / `add`(天/时)/ `to_unix` / `from_unix` / 可选 `in_zone`(IANA 或固定 offset)。**不做**完整历法 UI、农历、业务假期库。
### 3.2 URL 与查询串
**问题**
`url_encode` 只解决「编码一段」;解析 `https://a/b?x=1&y=2#frag`、合并 query、取 path 仍靠 `re` 自造。浏览器代理 / `invoke` / webhook 场景高频。
**建议**
`url.parse` → `{scheme,host,path,query,fragment}`;`url.query_parse` / `query_stringify`;与 `url_encode` 边界写进 `net` vs 新 `lib/url`。
### 3.3 TOML vs YAML
**外部事实**
Python 因 **打包引导**(`pyproject.toml`)接受只读 `tomllib`([PEP 680](https://peps.python.org/pep-0680/));YAML 多次被拒:规范复杂、实现难维护、安全面大。
**对 Marqdo**
catalog / 工具配置若走向 TOML,只读 `toml.parse` 性价比高。YAML:**默认不准入 Mid**;若 public 强需求,单独 ADR,且优先「JSON 超集子集」而非完整 1.2。
### 3.4 HTML 转义
**问题**
`ext/web` 与浏览器 WASM 拼 HTML 时,缺 `escape` 易 XSS。这是「难写对 / 安全相关」的经典 stdlib 项(Python `html.escape`)。
**建议**
极薄:`html.escape` / `unescape`(或挂 `text`)。**不做** DOM / 模板语言。
### 3.5 文件系统再厚
**问题**
`make_dir` 是否递归、`remove` 是否递归、无 `stat`(size/mtime)、无 `walk`——脚本仍会 `foreign` 或脆弱字符串。
**建议**
`fs.make_dirs` · `fs.remove_tree` · `fs.stat` · 可选 `fs.walk`(返回路径列表,非惰性迭代器协议)。
---
## 4. 明确「不是缺口」
| 项 | 说明 |
|----|------|
| Mid M1–M6 清单本身 | 已收口;不要用本表重开 base64/re |
| HTTP 服务 / DB / Agent | `ext/*`;见 [ext-hosting](ext-hosting-gaps.md) |
| Dense embedding / 向量库默认化 | OKF 路线不变 |
| 完整 `collections` / `itertools` 类型系统 | 语言没有泛型迭代协议;用 `table` |
| 「对齐 Python 模块个数」 | 反模式;对齐**用例与难写对** |
---
## 5. 优先级建议(转入 Mid2)
| 优先级 | 波次草案 | 内容 |
|--------|----------|------|
| **高** | **M7** | `datetime` + `url` — **done** |
| **高** | **M8** | `toml` 只读 + `html.escape` + `encoding` base32 — **done** |
| **中** | **M9** | `fs` 加厚(dirs/stat/walk) — **done** |
| **低** | **M10** | `stats` 薄 · log 字段 · (zip 默认跳过) — **done**(zip 仍跳过) |
| **won't** | — | 完整 YAML · 模板引擎 · sqlite 进 `lib/` |
---
## 6. 与其它文档
| 文档 | 关系 |
|------|------|
| [stdlib-mid2.md](../design/stdlib-mid2.md) | **补齐设计(作者 API + 边界)** |
| [stdlib-mid2.md](../roadmap/stdlib-mid2.md) | 实现波次 M7–M10 |
| [stdlib-mid.md](../design/stdlib-mid.md) | Mid1 宪法;本调研不改准入原则 |
| [web-net-capabilities.md](../design/web-net-capabilities.md) | 网络服务端能力在 ext,不进 Mid2 |
+35
View File
@@ -0,0 +1,35 @@
# 路线图:浏览器 Marqdo 路线 D(作者零 JS)
| | |
|---|---|
| 状态 | **Completed**(D0–D4 已落地;续作见 [browser-wasm-e.md](browser-wasm-e.md)) |
| 日期 | 2026-09-03 |
| 前置 | [browser-wasm.md](browser-wasm.md)(C0–C5 **Completed**) |
| ADR | [0002](../adr/0002-browser-marqdo-wasm.md) · [0003](../adr/0003-browser-async-effects.md) |
| 设计 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §16 |
## 一句话
作者侧**零业务 JS**:页面逻辑与交互只写 `.mq.md`;官方 `marqdo-bridge.js` 仍作不透明宿主胶(加载 WASM / DOM / fetch),由 `mount` + `client_embed` 自动启动。
## 阶段
| 阶段 | 内容 | 状态 |
|------|------|------|
| **D0** | 路线图 + 设计增补 | **done** |
| **D1** | bridge `mount` + data-mq / `#marqdo-boot` 自启;hello 去掉 loader/interact/fetch.js | **done** |
| **D2** | `client_embed` / `客户端挂载`:`wasm` / `source` / `boot` | **done** |
| **D3** | DOM/表单效应 + wire 传 `value`;`dom_patch` L1 | **done** |
| **D4** | `examples/web-client-site` + skill / README | **done** |
## 非目标
- 消灭官方 bridge 文件本身(宿主胶必须存在)
- 任意 `eval(JS)` / React 式 VDOM
- 把 axum / SQLite 搬进浏览器(仍属 C 非目标)
## 验收
- 示例无作者业务 `.js`(允许构建拷贝的 `marqdo-bridge.js`)
- `ext/web` 一行挂载即可 boot + wire
- 点击、表单 input、`fetch` 效应可演示
+32
View File
@@ -0,0 +1,32 @@
# 路线图:浏览器 Marqdo 路线 E(前端能力补齐)
| | |
|---|---|
| 状态 | **Completed** |
| 日期 | 2026-09-04 |
| 前置 | [browser-wasm-d.md](browser-wasm-d.md)(D0–D4 **Completed**) |
| 续作 | [browser-wasm-f.md](browser-wasm-f.md)(媒体 / 文件 / Canvas 等) |
| 设计 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §16–§17 |
## 原则(已修正)
**禁止的只有:作者手写业务 JS。**
官方 `marqdo-bridge.js` / 构建生成物可以包含任意宿主机制(含轻量列表装配、路由、存储、WebSocket、内部模板等)。
## 阶段
| 阶段 | 内容 | 状态 |
|------|------|------|
| **E0** | 原则修正 + 能力矩阵 | **done** |
| **E1** | `set_style` / `focus` / `blur` / `scroll_into`;键盘;wire `委托`;多节点 `querySelectorAll` | **done** |
| **E2** | `set_html` / `append_html` / `replace_children` / `render_list` / `remove`;L1 `list_html` | **done** |
| **E3** | `navigate` / `replace`;`window`+`popstate` | **done** |
| **E4** | `storage` local/session/**cookie** | **done** |
| **E5** | `ws` open/send/close + callbacks | **done** |
| **E6** | `fetch_all`(数组或 map)/ `interval` / FormData / `clipboard` / `download` | **done** |
| **E7** | `add_class` / `remove_class`;示例列表真删除 + net 面板 | **done** |
## 验收
- [examples/browser-app/](../../examples/browser-app/):列表 CRUD、storage、三页路由、interval、fetch_all、ws、clipboard、download
- 冒烟:`tests/wasm/smoke.mjs`
+26
View File
@@ -0,0 +1,26 @@
# 路线图:浏览器 Marqdo 路线 F(进阶宿主能力)
| | |
|---|---|
| 状态 | **Completed**(F1–F5;F6 Service Worker 可选未做) |
| 日期 | 2026-09-04 |
| 发布 | **v0.3.3** |
| 前置 | [browser-wasm-e.md](browser-wasm-e.md)(E **Completed**) |
| 写法 | 客户端 `.mq.md`:**GFM 表格 + `lib/browser`**,禁止 `json.set` 链([marqdo-dev](../../.cursor/skills/marqdo-dev/SKILL.md)) |
## 原则
同 E:禁止作者手写业务 JS;官方 bridge 可扩展。作者数据与效应用**可读表格/助手**表达。
## 阶段
| 阶段 | 内容 | 状态 |
|------|------|------|
| **F1** | `read_file` → text / DataURL → `mq_call` | **done** |
| **F2** | Canvas 2D 指令表(`canvas.commands`) | **done** |
| **F3** | Audio play / pause / stop;`src=beep` Web Audio | **done** |
| **F4** | `observe` / `unobserve`(Intersection / Resize) | **done** |
| **F5** | drag/drop wire + `data-drag` / `drop_text` | **done** |
| **F6** | Service Worker / 离线缓存 | optional / skipped |
示例:[examples/browser-media/](../../examples/browser-media/) · 助手:`lib/browser.mq.md`。
+40
View File
@@ -0,0 +1,40 @@
# 路线图:浏览器 Marqdo(WASM)
| | |
|---|---|
| 状态 | **Completed**(路线 C 首版功能完备;续作见 [browser-wasm-d.md](browser-wasm-d.md)) |
| 日期 | 2026-09-01 |
| ADR | [0002](../adr/0002-browser-marqdo-wasm.md) · [0003](../adr/0003-browser-async-effects.md) |
| 设计 | [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) |
| 阶段 | 内容 | 状态 |
|------|------|------|
| **C0** | feature 门控;`wasm32` check | **done** |
| **C1** | `run_source` + `mq_run` | **done** |
| **C2** | loader + `marqdo wasm build`(含 bridge 拷贝) | **done** |
| **C3** | session wire + `set_text` | **done** |
| **C4** | `fetch` / `after` 效应 | **done** |
| **C5** | `release-wasm` 体积;冒烟;站点挂载文档 / L1 | **done** |
## 交付物
| 产物 | 路径 |
|------|------|
| ABI crate | `crates/marqdo-wasm` |
| 官方 bridge | `crates/marqdo-wasm/js/marqdo-bridge.js` |
| CLI | `marqdo wasm build -o DIR` |
| 示例 | `examples/browser-hello/` |
| 冒烟 | `tests/wasm/smoke.mjs` · `tests/wasm_smoke.rs` |
| L1 | `web.client_embed` / `网页.客户端挂载` |
## 明确非目标(本版不做)
- 浏览器会话 bytecode(缺 entry-env invoke;一发 `run_source` 已支持 bytecode)
- 把 axum / SQLite 服务端搬进 WASM
- 业务手写 JS 框架
## 进度
| 日期 | 记录 |
|------|------|
| 2026-09-01 | C0–C5 完结并 push;收口 bridge 规范路径 + 冒烟 + 挂载 L1 |
+66
View File
@@ -0,0 +1,66 @@
# 路线图:代码即文档叙述面摩擦(G1–G4)
| | |
|---|---|
| 状态 | **Done**(实现已合入工作树;金样绿) |
| 日期 | 2026-09-14 |
| 设计 | [code-as-docs-gaps.md](../design/code-as-docs-gaps.md) |
| 样例 | `examples/code-as-docs/index.mq.md` |
---
## 里程碑
### M1 — 文档与金样夹具
- [x] 设计文档记录 G1–G4 与启发式
- [x] 本路线图
- [x] `tests/markup-v03/` 四缝金样 + `gold.rs` `markup_v03_*`
### M2 — G1 模块级 `---`
- [x] `parse_classified`:顶层 frame 行 skip;顶层 Comment 引言 skip
- [x] 函数体内 `---` / `***` 改为叙述跳过(不再收束;空返回收束)
- [x] 金样:`module-hr.mq.md`
### M3 — G3 浮点面量与运算
- [x] `Literal::Num(f64)`
- [x] `parse_primary` 识别 `digits.digits`(及 `.5` / `3.` 形态)
- [x] `eval_binary` + bytecode Int/Num 提升(Int/Int `/` 仍为整除)
- [x] 金样:`float-discount.mq.md`
### M4 — G2 叙述强调启发式
- [x] `scan_prose_line`:非代码形粗体、非返回形行内斜体 → 丢弃
- [x] 保持 `**n=n+1**`、`**加一 37**`、整行 `*n*`、「返回*n*」
- [x] 更新 Skill:允许装饰性强调;可执行仍看形状
- [x] 金样:`soft-emphasis.mq.md`
### M5 — G4 动态脚注键
- [x] AST:`IndexKey::{Lit,Var}`(`` [^`ident`] ``)
- [x] 解析、求值、bytecode
- [x] 金样:`dynamic-footnote.mq.md`
- [x] 回写 `examples/code-as-docs`(浮点折扣 + 动态键)
### M6 — 出门
- [x] `examples/code-as-docs` 展示四缝修复后的写法
- [x] `cargo test --test gold` 绿
- [x] 设计验收覆盖(见金样)
---
## 顺序建议
G1(小)→ G3(中,Literal/运算)→ G2(启发式,依赖金样钉行为)→ G4(AST 面)→ 回写样例。
---
## 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿 |
| 2026-09-14 | 实现完成并勾选 |
+23 -12
View File
@@ -2,9 +2,9 @@
| | |
|---|---|
| 状态 | **A0–A4 完成**(调研驱动优化闭环;A4:corpus/MCP 证据工具,权威仍是 `.mq.md`) |
| 日期 | 2026-08-28 |
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · **缺口盘点** [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) |
| 状态 | **A0–A4 完成**;**Wave B Active**(宪法优先:代码即文档 / call_site / OKF) |
| 日期 | 2026-09-04 |
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) · **[agent-framework-2026-09.md](../research/agent-framework-2026-09.md)** |
| 设计 | [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md) · [okf.md](../design/okf.md) |
| 邻近 | [agent-streaming.md](agent-streaming.md) · [okf-near-match.md](okf-near-match.md) |
@@ -13,21 +13,32 @@
## 1. 优化原则(来自调研)
1. **强化差异化,不向 LangChain 薄循环回退**(禁止隐藏 TOOL: 主路径、禁止整文件 LLM 重写工作簿)。
2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视**。
2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视、源码/调用位置注入**。
3. 外部 RAG/MCP 只作**工具**,不升为权威真相源。
自评四问见调研 §9。A0–A4 之后的缺口与建议分期 **B0–B5** 见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md)。
自评四问见调研 §9。A0–A4 之后的缺口见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md)。**2026-09 Wave B** 锁定见 [agent-framework-2026-09.md](../research/agent-framework-2026-09.md)。
---
## 2. 建议分期(摘要)
## 2. A0–A4(已完成)
| 波次 | 主题 | 验收线索 |
|------|------|----------|
| **A0** | 工作簿补丁 / 固化可靠性 | **done** — 整文件 FIND 护栏;`soft` 仅 miss;decompose `n` 检查;`workbook_solidify` 单测;金样 `agent-workbook-patch-a0`(双 CONTINUE + solidify) |
| **A1** | OKF 复用飞轮(lookup / near / soft_match UX) | **done** — `list_tasks` 含 description/aliases/status/llm_free/hits;`plan` 命中路径暴露 `match`/`score`;soft_match 策展行含 meta;view plan 卡显示 match;金样 `agent-kb-plan-hit`(exact hit + near soft-hit) |
| **A2** | 过程可见(stream + view 过程卡) | **done** — `plan_append_*` / `plan_finish_stream` 始终写入 `events`(SSE 仍仅 `stream=True`);OKF REUSE 记 `decision`;view `plan-card` 渲染过程时间线(跳过 delta);金样断言 `events-ok`;对齐 [agent-streaming.md](agent-streaming.md) |
| **A3** | 上下文预算(源码/Skill 渐进披露) | **done** — `source_brief` / 加深 `skill_brief`;`build_step_context` 默认预算 + `READ:source|skill`;`step max_reads`;父 `READ:skill`;金样 `agent-context-budget-a3` |
| **A4** | 可选:RAG/MCP 工具适配器 | **done** — `corpus_search`(本地语料关键词);`mcp_list_tools` / `mcp_call`(JSON fixture);`authority=workbook`;金样 `agent-tools-rag-a4` |
| **A0** | 工作簿补丁 / 固化可靠性 | **done** — 金样 `agent-workbook-patch-a0` |
| **A1** | OKF 复用飞轮 | **done** — 金样 `agent-kb-plan-hit` |
| **A2** | 过程可见 | **done** — events + view plan 卡 |
| **A3** | 上下文预算 | **done** — `source_brief` / `READ:`;金样 `agent-context-budget-a3` |
| **A4** | RAG/MCP 证据工具 | **done** — 金样 `agent-tools-rag-a4` |
细节与行业对照以调研正文为准;本文件只跟踪 **A0–A4** 实现分期。后续产品化 / 评测 / live MCP 等见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) §5(草案 B0–B5)。
---
## 3. Wave B(Active — 宪法优先)
| 波次 | 主题 | 状态 |
|------|------|------|
| **B0** | 官方示例演示 call_site/源码/OKF;Skill/文档;上下文管道可读 | **done** |
| **B0.5** | 本机 live(`.env` → 开发模型)验证「模型用上了文档」 | **done**(`AGENT_LIVE` / `AGENT_HARNESS_LIVE`) |
| **B1** | 评测 harness 锁差异化指标(constitution / dump / writeback 遮蔽) | **Active** |
| **B2–B5** | 真 MCP / resume+HITL / stats / 并行 | 暂缓 |
示例:`examples/agent-pong/` · `examples/agent-okf-flywheel/`。
+102
View File
@@ -0,0 +1,102 @@
# 路线图:宿主集成补齐(H0–H4)
| | |
|---|---|
| 状态 | **Active · 规划** |
| 日期 | 2026-09-07 |
| 缺口 | [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) |
| 设计 | [ext-hosting-fill.md](../design/ext-hosting-fill.md) |
| 相关 | [ext-web.md](ext-web.md)(W/C 完结)· [ext-agent-optimize.md](ext-agent-optimize.md) · [agent-streaming.md](agent-streaming.md) |
| 基线 | v0.3.6+ |
本文只跟踪**实现波次**。作者 API、ABI 边界、禁止项以设计文为准。
---
## 0. 目标回顾
让 `ext/web` + `ext/ai` 具备:同域 SSE 中继、HTTP→用户 `##`、MCP Server(至少 stdio)、跨模块 db/corpus 可发现——从而下游无需 Python 旁路进程。
---
## 1. 波次总表
| 波次 | 内容 | 关闭缺口 | 状态 |
|------|------|----------|------|
| **H0** | 文档契约:跨模块 `db` 传 `url`;`corpus_search` 调用前 `ensure_plugin` 说明;缺口索引进 `doc/README` | GAP-05 文档侧 | **done** |
| **H1** | `app.proxy` / `configure proxy=`:上游 SSE/HTTP **流式**转发 | GAP-01 | **done** |
| **H2** | `app.invoke` / `configure invoke=`:请求 → 白名单 `##` → JSON | GAP-02 | **done** |
| **H3** | 跨模块插件对象 `_type` 分发修补 + `corpus_search` 自动 `ensure_plugin` | GAP-05 运行时 | **done** |
| **H4** | `agent.mcp_server` + `serve transport=stdio`(HTTP 可选 H4b) | GAP-03 | **done**(stdio) |
| **H4b** | MCP Streamable HTTP | GAP-03 余量 | **todo**(可选) |
| **—** | 副端口 API | GAP-04 | **won't**:H1+H2 同端口关闭 |
建议顺序:**H1 → H2 → H3 → H4**(H2 的 invoke 内核可被 H4 工具复用,故 H2 不宜晚于 H4)。
---
## 2. 分波工作项
### H1 — 流式代理
1. `plugins/web`:`proxy.rs` + `web_app_proxy`;listen 挂流式 handler。
2. `ext/web`:`## proxy` + `configure proxy=` 表。
3. 金样 `web-proxy-sse-smoke`(mock 上游)。
4. 教程/public 短节:「浏览器同域调 LLM」。
**完成定义:** `curl -N` 同域 path 收到多帧 SSE;密钥仅 env 注入。
### H2 — HTTP invoke
1. 共享或插件内 `invoke_fn`(解析 `库.成员`、映射 body)。
2. `web_app_invoke` + 白名单。
3. 金样:临时 `##` 写文件 + JSON 响应;拒绝未允许路径。
4. 迁移说明:替换 `/store/*` + 外挂 `marqdo run`。
**完成定义:** 单进程 `listen` 下表单/fetch 可触发用户 `##`。
### H3 — db / corpus
1. 复现并修跨模块 `unknown object type db`(设计选项 A)。
2. `ext/ai` `corpus_search` 路径 `ensure_plugin`。
3. 金样 `web-db-cross-module-smoke` + corpus CLI run 金样。
### H4 — MCP Server
1. `plugins/agent` stdio JSON-RPC 最小子集:`initialize` / `tools/list` / `tools/call`。
2. `ext/ai` `# mcp_server` · `## tool` · `## serve`。
3. 工具调用复用 H2 `invoke_fn`。
4. 金样夹具;文档对接 Cursor `mcp.json` 示例。
**H4b:** Streamable HTTP 与鉴权;不阻塞 H4 stdio 发版。
---
## 3. 刻意不做
| 项 | 原因 |
|----|------|
| 默认开启任意 `##` 远程执行 | 安全 |
| 中继进 `lib/net` / `src/host` | 边界 |
| 重开 W0–W7 内容站清单 | 已完结 |
| 以副端口为推荐架构 | H1+H2 同端口即可 |
| Dense embedding 默认 | OKF 路线不变 |
---
## 4. 与发版
- 每波可随小版本发布;H1+H2 建议同一版本对外宣传「可去掉 llm_proxy」。
- H4 可标 `ext/ai` 能力点,与「真 MCP 客户端」分列 Release notes。
---
## 5. 进度勾选(落地时改)
- [x] H0 缺口 + 补齐文档
- [x] H1 proxy SSE
- [x] H2 invoke
- [x] H3 db/corpus
- [x] H4 mcp_server stdio
- [ ] H4b mcp http(可选)
- [x] 研究文 GAP 状态改为 closed(H4b 除外)
+126
View File
@@ -0,0 +1,126 @@
# 官方扩展:`ext/linalg` 实现路线图
| | |
|---|---|
| 状态 | **L0–L6 + 公式文档面 F1–F3 已落地 · L7+ 远期** |
| 日期 | 2026-09-07 |
| **锁定设计** | [design/ext-linalg.md](../design/ext-linalg.md) · [design/ext-linalg-formula-doc.md](../design/ext-linalg-formula-doc.md) |
| 调研 | [research/ext-linalg-formula.md](../research/ext-linalg-formula.md) |
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [view.md](../design/view.md) · [ext-quantum-q7.md](../design/ext-quantum-q7.md) |
| 安装(规划) | `marqdo ext add linalg`(`linalg` / `线性代数`) |
本文只跟踪**实现阶段**。作者面、公式规则、展示以设计文为准。
---
## 1. 目标回顾(一句)
**可运行的线性代数公式文档**:矩阵公式可化简、可 KaTeX 展示;跑通即在规则集内正确;需要时再稠密求值与分解,并内嵌结构 SVG。
---
## 2. 落地阶段
| 阶段 | 内容 | 状态 |
|------|------|------|
| **L0** | CATALOG + `plugins/linalg` ping + L1 `ensure_plugin`;`ext add` 条目 | **done** |
| **L1** | MatExpr:`symbol` / 稠密叶子 / `mul`·`add`·`T`·`inv`;`simplify` R1–R5;`latex`·`ascii`·`show` | **done** |
| **L2** | `explicit` / 小阵 gemm·解系·`det`·`trace`;维数护栏;金样 `linalg-basic-smoke` | **done** |
| **L3** | `block` + `collapse`;`kron` 惰性 + R7;金样 `linalg-block-kron` | **done** |
| **L4** | `factorize` LU/QR/SVD/eig(+ 可选 chol);结构 SVG `svd|qr|ge|eig`;金样 `linalg-factor-smoke` | **done** |
| **L5** | `heatmap`/`hinton`;examples(最小二乘 / SVD 示意);public + skill 摘要 | **done** |
| **L6** | 复数 dtype;`lstsq`;`norm`/`cond`;主题令牌对齐 | **done** |
| **F1** | 展示路径默认 simplify;公式文档金样 | **done** |
| **F2** | 符号引入降噪;examples 讲义化 | **done** |
| **F3** | 紧凑糖 + public「如何写公式文档」 | **done** |
| **L7+** | 矩阵微积分 / 更大 BLAS 依赖(仅当用户明确要求) | **deferred** |
验收金样(规划路径):`tests/ext/linalg-*-smoke.mq.md`;示例:`examples/linalg-least-squares/`、`examples/linalg-svd/`。
---
## 3. 每阶段出口检查
### L0
- [x] `ext/linalg` CATALOG 含 `linalg`
- [x] 插件 `ping` → ok
- [x] 文档:`marqdo ext add linalg`
### L1
- [x] `(AB)^\top` → `simplify` → `B^T*A^T`(无 dense)
- [x] 形状错误含行列信息
- [x] CLI `ascii` / `show` SVG 通道
- [x] 中英 L1 各一 smoke
### L2
- [x] `from_formula` 吸收 `$$` 数值阵
- [x] `solve` 与手算 2×2 一致
- [x] 超维 `explicit` 硬错误(单元测护栏)
### L3
- [x] 分块乘 `collapse` 后块级正确
- [x] Kronecker 默认不膨胀元素个数(惰性 `A⊗B`)
### L4
- [x] SVD/特征结果对象字段稳定
- [x] SVG 含可断言标记(如 `data-linalg="eig"`)
- [x] `factorize` + 二次 `solve` 复用(LU)
### L5
- [x] 至少 1 个 examples 可 `marqdo run`
- [x] public/features 或 tutorial 短页
- [x] skill / CHANGELOG Unreleased 条目
### L6
- [x] `lstsq` / `norm` / `cond` / `rank` 金样
- [x] `dtype=complex` 基线(Frobenius;分解仍为实数)
- [x] `draw theme=light|dark|bw` 与 quantum Q8 令牌对齐(`data-theme`)
### F1
- [x] `ascii` / `latex` / `show` 默认 simplify
- [x] 金样:`.T` 后直接 `ascii` 得 `B^T*A^T`(无需显式 simplify)
- [x] 设计文 [ext-linalg-formula-doc.md](../design/ext-linalg-formula-doc.md) 落地
### F2
- [x] 符号引入降噪(选定候选) — GFM `@` 表 + `la.declare`
- [x] 至少 1 个 example 以代数面为主叙述 — `examples/linalg-transpose/`
### F3
- [x] `T_ascii` / `转置文本` 一步展示糖
- [x] `explicit` 默认先 simplify(`raw=` 可关)
- [x] public `07-linalg` / `07-线性代数`「如何写公式文档」
---
## 4. 依赖与并行
| 依赖 | 说明 |
|------|------|
| ABI v2 + ext CLI | 已有 |
| view KaTeX / plot | 已有;L1 `show` 接现成通道 |
| Release native zip | 随首次含 `plugins/linalg` 的发版接入 |
| quantum 数值核 | **可选**私有复用;不阻塞 L1–L2 |
不阻塞项:浏览器 WASM 上的 linalg(默认 host/native;WASM 另议)。
---
## 5. 建议开发顺序(下一手)
1. **L7+** 仅当用户明确要求更深符号(微积分等)。公式文档面 F1–F3 已收口。
---
## 6. 一句话
**代数面像讲义、计算面是步骤;跑通即在规则集内正确;每阶段都有可跑金样。**
+13
View File
@@ -35,6 +35,18 @@
| **W7** | Cache-Control / 404·500 / 重定向 / sitemap·robots / init 唯一·索引 / HTTPS 反代说明 | **done** |
| **P3** | 审计时间戳 / 外键 / RBAC / 相册 / ETag | **done** |
### 定制波次(规划中)
自研后台 / 主题 / 响应式踩坑见 [ext-web-customization-limits.md](../research/ext-web-customization-limits.md);解法索引 [ext-web-customization/](../design/ext-web-customization/)。
| 波次 | 内容 | 状态 |
|------|------|------|
| **C0** | `admin` 关则不占路径;`admin_prefix` / 登录回跳可配 | **done** |
| **C1** | gate 匹配与未登录策略一致;段边界默认 admin gate | **done** |
| **C2** | `shell_css` + `layout` 松绑 | **done** |
| **C3** | 样式 strict / 脚本 defer·version | **done** |
| **C4** | 条件导航 when/media(layout 见 C2) | **done** |
验收金样:`tests/ext/web-smoke.mq.md`、`tests/ext/web-security-smoke.mq.md`、`tests/ext/web-drivers-smoke.mq.md`、`tests/ext/web-upload-smoke.mq.md`、`tests/ext/web-db-w6-smoke.mq.md`、`tests/ext/web-w7-finish-smoke.mq.md`、`tests/ext/web-p3-smoke.mq.md`、`ext_cli_add_web`。
---
@@ -57,3 +69,4 @@
| [design/ext-web.md](../design/ext-web.md) | **真理** |
| [user-site.md](../design/user-site.md) | 静态站互补 |
| [ext-quantum.md](ext-quantum.md) | 同属官方 ext + ABI + `ext add` |
| [ext-hosting.md](ext-hosting.md) · [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) | **W/C 之后**:同域 SSE 中继、HTTP→`##`(不重开本表 W0–W7) |
+2 -1
View File
@@ -109,7 +109,8 @@ Phase I 对齐 Crafting Interpreters 的 **jlox(树遍历)**;Phase II 对
- 更完整表达式文法、错误模型、外联围栏 FFI
- 生成 OKF 依赖目录
- (可选)另一后端:编译到 Python/WASM——**另开 ADR**,不替代自研语义
- (可选)另一后端:编译到 Python/WASM——**另开 ADR**,不替代自研语义
- **浏览器内运行(路线 C)**:解释器/VM 上 WASM(**非**把 `.mq.md` 译成 JS)——已锁定 [ADR 0002](../adr/0002-browser-marqdo-wasm.md) · [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [roadmap/browser-wasm.md](browser-wasm.md)
---
+59
View File
@@ -0,0 +1,59 @@
# Roadmap:lib / ext 代码即文档
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-09-14 |
| 相关 | [lib-code-as-docs.md](../design/lib-code-as-docs.md) · [view-markup-surface.md](../design/view-markup-surface.md) · [bracket-call-modifiers.md](../design/bracket-call-modifiers.md) · [collection-access-link.md](../design/collection-access-link.md) |
---
## 0. 总序(防返工)
1. **方括号标记调用**(设计 + AST + 金样)— **已落地**
2. lib / view 设计文档 — **已写**
3. View 表面(Index 链接形、括号调用)— **已落地**
4. 分波改造 `lib/*` → `ext/*`
旧 `>` / 粗体调用、脚注取元解析均保留。
## 1. 里程碑
| 波 | 内容 | 状态 |
|----|------|------|
| **Call** | `pre_modifiers`;`tests/structure/bracket-call.mq.md`;mapping / call-arguments | **done** |
| **M0 View** | `InterpPart::Index` → `[k](base)`;`call_display` 修饰表面 | **done** |
| **M1** | 试点 `lib/table` · `lib/text` · `lib/json`(中英)+ public/stdlib | **done** |
| **M2** | 其余 `lib/*` 叙述化;禁新脚注取元 | **done** |
| **M3–M4** | `ext/web`、`ext/ai`:脚注→链接取元;叙述;示例可逐步换括号调用 | **done**(取元迁移) |
| **M5** | quantum / linalg + full gold | **done** |
| **M6** | examples + public/structure + tests/ext·lib 链接取元;cafe 括号调用例 | **done** |
| **M7** | structure collection 金样改链接形;public/stdlib 括号调用例 | **done** |
| **M8** | 教程第 9 章 + Skill examples → 链接取元 / v0.3 标记 | **done** |
| **M9** | 教程其余章节(1–8、10–12、14)全面对齐 v0.3 + 链接取元 | **done** |
| **M10** | public/stdlib 剩余演示统一括号调用;public import 返回面修到 v0.3 | **done** |
| **M11** | View:`bracket_marked` 使无修饰 `[callee]` 也显示括号形 | **done** |
## 2. 验收(出门)
- 括号调用与 `[k](c)` 取元金样并存、不回归。
- 试点库可读:目的句 + 叙述形参 + 一例 + 短实现。
- `cargo test --test gold` 绿。
- 脚注取元金样(`tests/structure/footnote*`)仍保留作兼容门禁。
- 教程与 Skill 示例以链接取元 / `**` 代码 / `*` 返回为准。
## 3. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿;Call + M0 标 done |
| 2026-09-14 | M1 试点 table/text/json + public/stdlib 标 done |
| 2026-09-14 | M2 其余 lib 叙述化标 done |
| 2026-09-14 | M3–M4 ext/web+ai 脚注→链接取元 |
| 2026-09-14 | M5 quantum/linalg 叙述 + public/features 取元 |
| 2026-09-14 | M6 examples/public/tests 批量链接取元 + cafe 括号调用 |
| 2026-09-14 | M7 structure collection 金样 + stdlib 括号调用例 |
| 2026-09-14 | M8 教程 + Skill examples 同步 |
| 2026-09-14 | M9 教程全书对齐 v0.3 标记与链接取元 |
| 2026-09-14 | M10 public/stdlib 括号调用扫尾 + import 返回面 |
| 2026-09-14 | M11 View `bracket_marked` 无修饰括号调用表面 |
+111
View File
@@ -0,0 +1,111 @@
# 路线图:Marqdo Markdown 语法映射 v0.3(叙述统一)
「Markup」= Marqdo 把 Markdown 标记当成语法的那一层(不是另一个产品)。v0.3 = 现行映射:粗体代码、斜体返回。
| | |
|---|---|
| 状态 | **Done(v1.0.0)** |
| 日期 | 2026-09-13 |
| 设计 | [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) |
| ADR | [0005-prose-unified-markup.md](../adr/0005-prose-unified-markup.md) |
| 依赖 | 现有管线 [interpreter.md](interpreter.md) · [pipeline-debug.md](../design/pipeline-debug.md) |
---
## 目标
把 v0.3 宪法落到词法 → AST → 语义 → 双后端,使动机示例(加一函数)成为金样例,并安全迁移存量代码。
---
## 里程碑
### M0 — 设计冻结与双模式骨架(文档 ✅ / 代码 ⏳)
- [x] 设计文档 + ADR Proposed + 本路线图
- [x] **钉死**:空返回词法(设计 §7.2);提及/未使用变量(§4.4);升参 vs 绑定图(§8.2)
- [x] **钉死**:一行多 `**…**` 按序执行(设计 §12 #6)
- [x] **不做双模式** — 直接 v0.3 默认
**出门:** 设计评审通过;旗标可切换;无行为默认变化。
### M1 — 内联扫描与 AST
- [x] 金样例目录 `tests/markup-v03/`(夹具 + `gold.rs` `#[ignore]`;见目录 README)
- [x] `Prose` 行内联扫描:`` `ident` `` / `**…**` / `*…*`
- [x] `Stmt::Return` ← italic;`Stmt` ← bold Assign/Call
- [x] `Param.inferred` + 升参
- [x] `tests/markup-v03/` 金样通过(默认运行时)
**出门:** `cargo test markup_v03`(无 ignore)绿。
### M2 — 形参推断
- [x] `InferParams`:首次 `` `名` `` = 必选;`` `名`=默认 `` = 可选
- [x] 体赋值 `n=n+1` 不误判为默认
- [x] 与显式 `+` 合并规则 + 警告
- [x] 方法 `self`/`自` 排除
- [x] 金样例:默认实参、位置/具名调用、粗体内调用
**出门:** 推断签名与 `+` 兼容套件绿。
### M3 — 调用面与消歧
- [x] `**callee args**` ≡ `> callee args`
- [x] else 臂 `N. *` 与返回斜体消歧
- [x] 一行多 `**…**` 按序执行
- [x] 金样例:`---` / `*None*` / 整行 `**` / 兼容 `****`;叙述死绑定不升参
- [x] 诊断:必选缺失、未知 callee(已有 errors 金样);死变量不报错
- [x] 残缺粗体:与 GAP-06/07「未闭合后恢复」冲突,保持 Comment 跳过恢复,不硬报错
- [x] 粗体内表达式语句:`**n + 1**` 求值后丢弃(非误判为调用)
- [x] 叙述斜体:仅整行 / `返回*…*` / 表达式形当返回(`*very important*` 不收束函数)
**出门:** `tests/markup-v03/*` 覆盖设计 §9 示例。
### M4 — 双后端与工具
- [x] 字节码发射跟随新 Stmt 源
- [x] `view` / Structure:推断形参 `chip inferred` + Functions 大纲标注
- [ ] (可选)`marqdo migrate markup-v03` 机械改写提示/工具
**出门:** tree 与 bytecode 后端对 `markup-v03` 金样一致。
### M5 — 默认切换与存量迁移
- [x] 默认 `MarkupEdition::V03`
- [x] 迁移 `tests/**`、`lib/**`、`ext/**`、`public/**`、教程
- [x] 更新 `.cursor/skills/marqdo/SKILL.md` 硬规则
- [x] 修订 [markdown-mapping.md](../design/markdown-mapping.md) 为 v0.3 正式正文(或声明由 v0.3 文件接任)
- [x] ADR 0005 → **Accepted**
- [x] CHANGELOG / 发版说明(破坏性:标记对调)— **v1.0.0**
**出门:** 全量 gold 默认绿(live LLM 无钥跳过);无 v0.2 双模式。
---
## 非目标(本路线)
- 不改插件 ABI / Go libweb
- 不引入 `def`/`return` 关键字
- M0–M4 不强制改生产 `.mq.md`
---
## 风险
| 风险 | 缓解 |
|------|------|
| 标记对调导致海量假失败 | 双模式 + 分目录金样;默认晚切换 |
| 形参推断误伤局部变量 | 金样例钉启发式;允许过渡期写 `+` |
| 空返回 vs `**` 词法 | §7.2 已钉:整行 `**` = 空返回;推荐优先 `---` |
| 叙述反引号误升参 | §8.2 升参需可执行面读取;死绑定不进 params |
| Skill/AI 仍按 v0.2 生成 | M5 同步 Skill;过渡期文档标明版本 |
---
## 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-13 | 初稿与设计/ADR 同步 |
| 2026-09-13 | 空返回与提及性反引号决议合入;M0 文档项勾选 |
Loaded 100 of 797 files, more files were not shown because too many files have changed in this diff. Show more