Compare commits

..
Author SHA1 Message Date
cflmyandCursor 1e5e6f4891 release: v0.3.0 — web/agent/quantum wave + docs
Ship W0–W7+P3, agent A1–A4, quantum Q7/Q8; fix web prose parse;
document ASGI/proxy deploy; refresh README how-to for latest Marqdo.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-29 10:35:13 +08:00
cflmyandCursor 4c37e79dae docs(agent): record post-A4 framework gaps and next-wave B0–B5
Capture productization, eval, live MCP, resume/HITL, and metrics gaps after the A0–A4 optimize loop; link from roadmap and doc index.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 17:56:31 +08:00
cflmyandCursor 9a8545b725 feat(agent): A4 corpus search and MCP fixture evidence tools
Add local keyword corpus_search and offline MCP fixture adapters as parent CALL tools; keep authority on workbook .mq.md.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 17:47:59 +08:00
cflmyandCursor ee3116513b feat(agent): A3 context budget and progressive READ disclose
Budget source/skill in step prompts with truncation markers; allow READ:source|skill deepen; parent READ:skill.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 17:26:16 +08:00
cflmyandCursor 729357b7c0 feat(agent): A2 process visibility — events always on plan result
Record decision/round/done without requiring stream; render process timeline on view plan cards; keep SSE gated on stream=True.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 17:06:59 +08:00
cflmyandCursor 07ab7d52c6 feat(agent): A1 OKF reuse flywheel — list_tasks curation and plan match
Enrich list_tasks for soft_match curation; expose match/score on plan hits; add offline plan-hit gold.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 16:53:27 +08:00
cflmyandCursor d7be903297 test(agent): A0 gold for multi-CONTINUE patches and solidify
Offline coverage: two precise workbook patches then agent_workbook_solidify
freezes the step worker into a quoted return.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 16:41:44 +08:00
cflmyandCursor d0b184939f fix(agent): harden workbook patches against whole-file rewrites
Reject large whole-file FIND spans, narrow soft=True to miss-only, check
decompose CONTINUE patch counts, and unit-test workbook_solidify.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 16:22:39 +08:00
cflmyandCursor c36383bf28 docs(agent): research frameworks vs Marqdo document-driven advantages
Add detailed survey of LangGraph/CrewAI/SDK landscape, lock Marqdo
differentiators, and sketch A0–A4 optimize roadmap for ext/agent.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 16:06:11 +08:00
cflmyandCursor eba0d703c5 docs(quantum): document Q8 themes in skill and user-facing pages
Align SKILL/reference/examples, design docs, CHANGELOG, and feature demos
with theme=dark|light|bw and the rebuild → ext add reload note.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 15:54:47 +08:00
cflmyandCursor dfb27d41dc feat(quantum): Q8 circuit SVG themes and view plot chrome
Fix label/wire overlap with gutter + chip labels; default dark tech palette
with light/bw themes; restyle probs/bloch and darken view plot frames.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 15:46:02 +08:00
cflmyandCursor cf4dbdeade chore: gitignore quantum draw SVG runtime outputs
Keep gold/example .mq.md sources tracked; ignore generated circuit and
state-plot SVGs under tests/ext and examples/quantum-*.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 14:47:19 +08:00
cflmyandCursor f3fe7f268e docs(quantum): Q7c entanglement example and skill summary
Add examples/quantum-entanglement lab, update skill/reference/examples
and public feature page for Q7 density/viz APIs; mark roadmap Q7 complete.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 14:28:11 +08:00
cflmyandCursor 88fe076216 feat(quantum): Q7 density linear algebra and advanced SVG viz
Add density-matrix ops (partial trace, Hermitian eig, Schmidt, Pauli
expect, purity/fidelity, kron) and hinton/city/qsphere/paulivec/multibloch
draw kinds via plugins/quantum ABI, with EN/ZH L1 and gold smokes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 14:23:24 +08:00
cflmyandCursor 4956460773 docs: align skill and docs with ext/web W7+P3 completion
Update Marqdo AI skill (SKILL/reference/examples) with ext/web authoring
rules and API summary; reconcile web-net-capabilities conclusions and blog
checklist with shipped W0–W7+P3 surface.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 13:41:50 +08:00
cflmyandCursor eafa203205 fix(ci): build quantum plugin for public pages demos
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 13:29:05 +08:00
cflmyandCursor 7317a653c7 fix(ci): run public pages via bash script with per-file logging
Move the Build & export loop into scripts/run-public-pages.sh (explicit
bash, skip files without # main) so CI failures show which demo broke.
Also quote remaining time/json italic string args.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 12:27:57 +08:00
cflmyandCursor 0fddc3bf05 fix(ci): skip public mq.md files without # main
Avoid locale-sensitive find -name/?? matching for 工具.mq.md; only run
demos that define # main so import helpers are skipped on all runners.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 12:18:52 +08:00
cflmyandCursor 724a22e48d fix(ci): exclude import helpers with path-scoped ?? pattern
Literal 工具.mq.md in the workflow shell can fail to match on runners;
limit ?? to structure/import so utils/工具 are skipped without dropping
other two-character public docs (数学, 文本, …).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 12:15:20 +08:00
cflmyandCursor 6db3da1cc0 fix(public): quote italic call-arg string literals for pages CI
Bare identifiers inside *…* are variables; quote text args (and var="x")
so marqdo run on public/*.mq.md succeeds. Narrow pages.yml exclude to
utils.mq.md and 工具.mq.md instead of overly broad ??.mq.md.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 11:59:10 +08:00
cflmyandCursor 86bfb0648c fix(ci): exclude UTF-8 工具.mq.md from pages site build
The pages workflow used a mojibake exclude name, so import helper
工具.mq.md was executed and failed without a # main entry.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 11:44:11 +08:00
cflmyandCursor c6360adccb ext/web P3: RBAC, audit timestamps, FK, gallery, ETag
Complete the remaining network-extension gaps so media sites can
gate by role, auto-stamp rows, declare foreign keys, browse uploads,
and conditional-get downloads.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 11:37:02 +08:00
cflmyandCursor 2d51f29199 fix(web): restore sitemap_json helper used by ABI
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 11:26:01 +08:00
cflmyandCursor 323449c2c3 ext/web W7: finish network extension polish
Ship Cache-Control, 301 redirects, custom 404/500, sitemap/robots, and
init unique/index so the web capability roadmap is complete for P0–P2.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 11:25:33 +08:00
cflmyandCursor 6808d56c9d ext/web W6b: WebSocket broadcast and access logging
Add route_ws mode=broadcast with a per-path hub, configure access_log
for stderr request lines, and cover both offline and live gold.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 11:13:24 +08:00
cflmyandCursor e3b0314382 ext/web W6: schema migrate and SQLite FTS5 search
Add db.migrate with _marqdo_migrations, db.fts/search (bm25), and gold
covering published filters plus a comments table convention.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 11:07:24 +08:00
cflmyandCursor a900fd550f ext/web W5: multipart upload receive and download
Add app.upload/download routes over # storage, offline media validate/save
helpers, form type=file + enctype, and curl live gold coverage.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 11:01:18 +08:00
cflmy 034f52b7e7 ext/web W4: Postgres, Redis/memory cache, and S3/file storage drivers
URL-scheme backends keep the same # db CRUD author API; add # cache and

Co-authored-by: Cursor <cursoragent@cursor.com>
# storage with offline memory:/file: gold coverage.
2026-08-28 10:33:05 +08:00
cflmyandCursor e7c9c21a49 ext/web W4c: SEO meta, Markdown render, RSS, pagination UI
Add lib/net markdown_parse, page.meta/paginate and app.route_rss author
APIs, GFM Markdown article bodies, head SEO tags, list pagination nav, and
RSS 2.0 feed routes — keeping tables + class methods as the author surface.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 09:46:16 +08:00
cflmyandCursor be6223f1fb ext/web W1–W3: middleware, data layer, and security hardening
Deliver the interrupted network extension backlog: declarative middleware
(CORS, security headers, gzip, JSON API), SQLite pool/transactions/pagination,
and W3 security (argon2 passwords, CSRF on forms/login, persistent sessions,
CSPRNG ids, login rate limiting). Adds gold smokes and author-facing
hash_password on ext/web.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-28 09:35:39 +08:00
cflmyandCursor da9fc75b1e Add marqdo-blog example with GFM-table style assembly
Introduce web_style ABI (样式装配) so themes are GFM style tables
(|选择器|属性|值|, optional |媒体| column for @media) assembled by
functions instead of hand-written CSS strings — 文档即代码. The new
examples/marqdo-blog shows a full blog: card grid, dynamic /post/{slug},
tag archive, WebSocket live widget, and session-gated admin CRUD, plus a
smoke test (15 checks) and README.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-26 13:03:55 +08:00
cflmyandCursor 7645dd4c1f Extend network stack: session/auth, WebSocket, cookie/multipart primitives
Add the network-extension wave to lib/net and the web ABI plugin:
- lib/net cookie_parse / multipart_parse host primitives (EN/ZH)
- plugins/web session store + /admin login gate + WebSocket client/server
- ext/web author surface (EN/ZH) for session, auth, ws
- form update flow and page-level validation echo tests
- fix string escapes: \xHH, \u{...}, unknown escapes kept verbatim
- map Chinese component slots (导航/侧栏/页脚) so sidebar renders
- resolve relative static/db paths against the entry script dir (entry_dir)
- new tutorial chapter 14, EN/ZH example sites, and gold tests

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-25 14:58:46 +08:00
cflmyandCursor 7dfa161422 Document proxy-7890 push fallback for git network failures
Records the working one-shot command (proxy + larger postBuffer) used
when direct push fails with curl 35/56 connection resets.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-24 14:56:32 +08:00
cflmyandCursor b84e82eb56 Support footnote indexing inside interpolated call args and strings
Parse `` `var`[^key] `` in `` *…* `` segments and quoted strings as an
Index part (chained `` [^a][^b] `` folds into one part) in both the
tree-walk interpreter and the bytecode compiler, and render it back in
`view`. Also make bytecode `_type` stamping always overwrite like the
interpreter does, so child constructors yield the most specific type.

Adds gold/unit tests for interp footnote indexing and a bytecode
inherit-explicit-super case.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-24 14:45:56 +08:00
cflmyandCursor d7924ea8c7 Add Marqdo Chinese syntax tutorial under doc/tutorial/
13 chapters plus a README index covering syntax, variables, functions,
control flow, collections, objects/inheritance, modules and the CLI.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-24 14:45:26 +08:00
cflmyandCursor bd5555afaa Unify bare-identifier semantics in *…* / **…** (Python namespace)
Inside italic/bold code segments every bare word is a variable — including
call arguments and method-call receivers — so text literals must be quoted
and receivers no longer need backticks. A bare dotted callee `a.b` resolves
as a method call when `a` is a local variable, otherwise as a library path
(Python-style unified namespace), in both the tree-walk and bytecode backends.

Migrate ~70 tests plus ext/web, ext/quantum, ext/ai and the example projects
to the new idiom; update SKILL.md and the design docs; fix the web/quantum
example data model (db/index.mq.md). Unit and gold suites pass; only the 3
network-live tests fail offline.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-18 11:20:46 +08:00
cflmyandCursor f275d1e030 Drop redundant backticks in *…* / **…** code segments
Value-expression variables inside *…* / **…** segments no longer need
backticks (the segment markers already mark code). Drop trailing spaces
and de-tick value-expression variable names in tests and skill docs;
keep backticks for string interpolation, call args, and method receivers.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-17 17:22:45 +08:00
cflmyandCursor 1bf414c745 Harden plan parent: first DECISION, soft patches, and empty-tool step retry.
Stop import/fence prompt breakage, prefer modern workbook imports, accept
common patch shapes, and recover when workers CALL disallowed tools.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-16 12:07:17 +08:00
cflmyandCursor ecc92f473a Unify frontmatter imports as import bind:target and drop > imports.
`import json:lib/json.mq.md` binds file libraries; `import fmt:time.format`
binds member short names (replaces `> use`). Legacy `> path.mq.md` / `> use`
now hard-error with a hint. Migrates repo docs, skills, ext, lib, public, examples,
man-test and tests; adds a negative gold and updates view/catalog rendering.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-13 10:03:21 +08:00
cflmyandCursor 56b9bfa5a3 Fix subtask overview pages so tables are not parsed as statements.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 15:37:26 +08:00
cflmyandCursor 209dc4fc5d Fix public docs run errors and optional gate matrix binding.
Markdown list dashes were parsed as loops; quantum.gate name=H failed because plugin bind required matrix. Repair user-site pages and redeploy-ready sources.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 15:36:58 +08:00
cflmyandCursor db27f5c8d3 Fix release workflow VSIX output path by creating dist first.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 15:03:26 +08:00
cflmyandCursor 106e1d5136 Release Marqdo 0.2.0 with official extension libraries.
Document ext add for llm/agent/web/quantum, ship release notes and installer assets for the extension-focused release.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 14:52:13 +08:00
cflmyandCursor d269ccb7e7 Add formula-matrix custom gates and fix Variables modal in view.
Parse $$ pmatrix/[[…]] into executable matrices for quantum.gate matrix=, and make the vars panel open a rich modal without breaking the page script.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 14:40:55 +08:00
cflmyandCursor 505d478724 Add amplitude_damping teaching noise for quantum run trajectories.
Extends Q5 with a dissipative jump channel and EN/ZH golds so docs can show energy loss, not only Pauli flips.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 13:59:51 +08:00
cflmyandCursor b842644686 Add gate matrix heatmaps, GHZ example, and ZH quantum golds.
Completes the Q4 matrix-draw follow-up and mirrors author/noise APIs in Chinese smokes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 13:57:13 +08:00
cflmyandCursor 60d570756f Add quantum Q5 teaching noise and finish author-facing circuit APIs.
Barrier/measure/append/state plus bitflip/depolarizing run trajectories let docs show noisy sampling without a full open-system simulator.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 13:46:56 +08:00
cflmyandCursor eea6fe1a0e Land quantum Q4 visuals and gate Stream to LLM/agent imports.
Add probs/Bloch draw kinds and matches_matrix, plus feature docs; hide the view Stream panel unless llm/agent is imported, and stop rewriting method names like 绘图 through host_plot aliases.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 12:36:51 +08:00
cflmyandCursor 25b7be6739 Add usable table/map stdlib with put, and show run bindings in view.
Authors can update nested collections via table.put/表.改 instead of json.set chains; view’s right rail adds collapsible Variables from the entry env.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 11:49:48 +08:00
cflmyandCursor 91d51f3f0a Treat bare ids as variables in italic/bold, and land table/quantum follow-ups.
Prefer-var parsing in *…* / **…* (quoted strings for text), table cell expressions, digit map footnotes, and quantum steps/draw with updated golds and LLM sources.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 11:21:23 +08:00
cflmyandCursor ff6425e6c5 Add quantum Q2 gate set, seeded run, and EN/ZH L1 APIs.
Expand the simulator beyond H/CX with Y/Z/S/T/R*/CZ/SWAP and deterministic shot sampling so authors can write full circuits and reproducible measurement checks.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 10:28:41 +08:00
cflmyandCursor e853b00fe2 Update Cargo.lock for marqdo_plugin_quantum workspace member.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 10:24:38 +08:00
cflmyandCursor 4a7a33e29a Add ext/quantum Q0–Q1: ABI simulator with H/CX and Bell smoke.
Register the quantum catalog package, English/Chinese circuit APIs, and a state-vector plugin that verifies Bell-state probabilities.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 10:24:33 +08:00
cflmyandCursor 25b6b86c26 Document ext/quantum design and implementation roadmap.
Lock author API, simulator bounds, view SVG plan, and Q0–Q5 phases before coding the ABI plugin.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 10:21:07 +08:00
cflmyandCursor e4be0b0492 Ignore local web SQLite fixture directories.
Keep smoke and example runtime databases out of the working tree status.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 09:29:14 +08:00
cflmyandCursor db6158e9e2 Polish admin UI and add app.static file serving.
Admin gets a sidebar shell, flash messages, empty states, and forms in-chrome; listen can nest a public directory under /static (or a custom mount).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 09:26:30 +08:00
cflmyandCursor a0c56fa352 Add Chinese web-site example and 网页.mq.md smoke.
Mirrors the English sample on port 18082 using only Chinese class APIs for page, db, form, and app.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 09:20:34 +08:00
cflmyandCursor c181b74a88 Implement db.select where= with simple map and filter-table ops.
Equality maps and |字段|操作|值| rows (including like) feed parameterized AND clauses; admin smoke resets the SQLite sequence for stable ids.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 09:16:03 +08:00
cflmyandCursor 02b3dfab48 Resolve /_part against home or routed pages.
Stamp _route on app.route pages and emit {path}/_part/{id} slot sources so partials refresh the correct page.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 09:05:50 +08:00
cflmyandCursor b09538d242 Embed forms in page main via compose_form.
listen collects forms from home and routed pages so mount_form is optional; validation errors re-render the owning page shell.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 09:02:37 +08:00
cflmyandCursor 0dcd9e3d03 Add app.route for mounting extra pages by path.
Register GET routes from assembled pages; sample /about + offline smoke.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 08:57:07 +08:00
cflmyandCursor 897db76aa7 Add admin CRUD via schema-derived forms sharing validate/submit.
Infer fields from SQLite table_info; serve /admin/{table}/new|edit|delete.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-12 08:55:06 +08:00
cflmyandCursor ee019fb1c2 Add ext/web forms (design §5.5): fields, validate, submit, GET|POST /_form.
Also fix static links (URLs with dots) being misread as db fields.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-11 17:55:29 +08:00
cflmyandCursor 9599303c4c Rewrite ext/web around tables and class methods.
Drop bag/scaffold glue and rebuild the web plugin for compose, SQLite CRUD, and listen, with call_lib_path support and a §4 English site sample.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-11 15:06:39 +08:00
cflmyandCursor 8041a2274c Add ext/web with table-driven pages and polished admin CRUD.
Ship the web L1/plugin stack (bind tables, variable-named db.init, live render) and tighten the admin UI with sidebar, toolbar, forms, and activity log.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-11 11:42:17 +08:00
cflmyandCursor ab8ea8438f Add local n-gram near match for OKF agent-kb reuse.
Sparse bigram cosine closes near-duplicate goal fragmentation; soft_match parents now judge ranked scored candidates instead of a flat task list.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-11 10:07:03 +08:00
cflmyandCursor f240bdf156 Stream child agent events into view SSE without jumpy drip.
Forward quiet file-subtask EventBus frames while wait blocks, coalesce
DOM updates per rAF, and keep one SSE write per event so Stream stays
live during child work instead of freezing or dumping bursts.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-11 09:45:08 +08:00
cflmyandCursor ff84c43c10 Add OKF soft match, CALL tool streaming, and lib whitelist dispatch.
Canonicalize/alias lookup and optional soft_match parent REUSE cut kb
fragmentation; stream tool_start/end for Plan-and-Move visibility; allow
safe CALL:lib.* without FC.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-11 09:26:59 +08:00
cflmyandCursor dbb2765553 Add parent Plan-and-Move: CALL/READ tools and quiet I/O capture.
Give the plan loop actionable observation (source excerpts, stderr/stdout tails) and short stop rules so the parent can inspect children and use stdlib helpers instead of inventing long patches.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-11 09:11:15 +08:00
cflmyandCursor 7e3b193d49 Stop plan loops after child success; harden stream UX.
Prefer DONE + runtime solidify when the child already returned a value, compact parent observations, drop the SSE 8MiB raw-buffer abort, and drip-stream the view panel via POST /api/run.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-10 17:25:24 +08:00
cflmyandCursor 2a9fceb51c Land OKF aliases, view SSE, workbook nav, and explicit parent ctor.
Complete the core agent roadmap: soft KB hits via Task aliases, EventBus-backed view streaming, D4 writeback/workbook navigation, and I3 explicit-super without implicit auto-super.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-10 11:58:26 +08:00
cflmyandCursor d1ddb74235 Plan parent-first decompose, reasoning streaming, TTY input editing.
Reorder non-hit plan pipeline so the parent decomposes before spawning the child, stream DeepSeek thinking (reasoning_content) to TTY, and add Unicode-aware line editing for interactive input to fix CJK backspace corruption.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-10 11:45:58 +08:00
cflmyandCursor b6bb42e460 Implement streaming S0-S2: SSE complete, step/plan events.
Add net/llm SSE primitives and optional stream/echo/trace on step and plan so callers can watch deltas and rounds without changing final return values.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-10 11:03:04 +08:00
cflmyandCursor 5456d9ff83 Implement object inheritance: # Child = > Parent (I0-I2)
- Parse `# Child = > Parent` object decls (base must be a simple
  name after `>`; dotted bases and `# Foo = 1` are diagnostics).
- Validate in load: unknown base types and cyclic inheritance (A → B → A)
  fail with line/col.
- Method resolution walks the base chain (most specific first) on both
  tree and bytecode backends; `_type` stays the child name; same-name
  child ## overrides the parent.
- Add inherit.rs, wire Program.object_bases, gold fixtures
  (inherit-parent-method / inherit-override + cycle/unknown-base/bad-rhs)
  and public 09-inherit demo pages. Docs: objects.md, markdown-mapping,
  roadmap, skill.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-10 10:01:05 +08:00
cflmyandCursor a23fdedfa2 Implement table semantic T0-T4: map/records/footnote get
- 1-col table stays a List; >=2-col becomes a column-oriented Map
  (1 data row -> scalar values, >=2 -> Map of Lists).
- First header @ / 行 / row opts into row-oriented List of Maps
  (marker column excluded); missing field cols is a diagnostic.
- Footnote index: `xs`[^1] (1-based list), `m`[^key] (map key), chained.
  Errors for [^0], out-of-range, missing key, duplicate headers.
- foreach walks list items or map keys; Map values now display as {k: v}.
- Sync both tree and bytecode backends; new gold + error fixtures, docs
  (markdown-mapping, roadmap, skill, public), and public 07/08 pages.
- Fix subtask-spawn fixture return value to child_ok (child-ok parses as
  subtraction).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-10 09:50:21 +08:00
cflmyandCursor 3463628165 Document roadmap plans for soft OKF match, streaming, syntax, and new exts.
Capture near-match, agent streaming, inheritance, table/map footnotes, plus
planned web and quantum extensions with ABI and ext-cli install conventions.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-09 10:29:18 +08:00
cflmyandCursor d1b33c78c6 Make file subtasks return #main value and expose it as plan.result.
Quiet spawn still hides child stdout; workbooks solidify to **returns**, agent-kb lives in the plugin, and multi-step follows OKF file relay rather than print-based answers.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 17:53:14 +08:00
cflmyandCursor fbece725e1 Enable default writeback on agent step and lock the plan design.
Document multi-step workbooks in ext-agent-plan, and make step/单步 persist ok/error slots unless writeback is turned off.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 13:47:34 +08:00
cflmyandCursor 1f23e2ed93 Add module namespaces and harden L1/agent after the import redesign.
Bind imports to library names with bare path calls (and use), forward optional host args through mq wrappers, stabilize writeback replacement newlines, and document the M1/M2 decisions.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 13:28:32 +08:00
cflmy 99132ac8fc update 2026-08-07 10:06:33 +08:00
cflmy 118448538c update 2026-08-07 09:50:03 +08:00
cflmyandCursor 2e65c055b8 Release v0.1.2: embedded stdlib, docs, and extension branch policy.
Embed lib/*.mq.md in binary; marqdo version --check; public writeback/subtask pages; restore /vscode-extension/ ignore. VSIX built from branch vscode-extension only (see doc/design/vscode-extension-commit.md).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 09:41:53 +08:00
cflmyandCursor 3da7b276d3 Extend subtask stdlib for file, function, and foreign concurrency.
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-07 09:41:22 +08:00
cflmyandCursor 63e5be80ab Add v0.2 surface syntax, writeback/subtask stdlib, and view input deferral.
Use + for parameters, ordered-list branches, backtick identifiers, and quoted strings with escapes. Add writeback and subtask host libs, optional parameter defaults, narrative-bold comment fix, and defer view execution until preset stdin is submitted.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-06 17:52:33 +08:00
cflmyandCursor 92d88fe761 Move LLM and agent into ext/ai with host tool catalog and call_fn.
Consolidate official AI extensions under ext/ai/, add agent history/context host APIs, dynamic call_fn, and a first-pass TOOL:name loop so runbooks can list zero-arg tools in a table.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-06 15:28:39 +08:00
cflmyandCursor c4ffb9473f Extend ext/agent with skill match/assign and multi-column tables.
Compose ext/llm, add ABI match_skill/bump_load, map-valued GFM tables, and agent-assign gold coverage.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-06 13:46:34 +08:00
cflmyandCursor 3a7e11c995 Add ext/agent layout framework, ext CLI, and docs catch-up.
Ship ABI agent plugin helpers, marqdo ext list/add/remove, and document the agent development roadmap (compose LLM, match/assign).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-06 13:31:25 +08:00
cflmyandCursor b0c777c480 Add versioned C ABI for optional native plugins.
Load .dll/.so/.dylib at runtime via libloading, register JSON-wired functions, and ship a Rust cdylib demo with lib/plugin wrappers and gold coverage.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-06 12:45:18 +08:00
cflmyandCursor b00b018056 Add object primitives, official ext/llm, and HTTPS/dotenv platform.
Introduce # objects with ## methods (handles + ` x.method `), ship OpenAI-compatible ext/llm, and upgrade net/sys for HTTPS headers and dotenv loading.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-06 11:53:14 +08:00
cflmy b974f10c6e Add Marqdo AI skill for correct .mq.md authoring.
Ship a portable skills/marqdo package (and Cursor mirror) so agents follow markup-as-syntax rules, stdlib imports, and the run-fix loop.
2026-08-05 17:36:21 +08:00
cflmyandCursor 72777a8c74 Release v0.1.1: debug page Logo branding and packaging notes.
Bump crate version, use official Logo for marqdo debug favicon/brand, and document VS Code extension assets in the Windows release script.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-08-05 17:17:00 +08:00
510 changed files with 59123 additions and 7313 deletions

No files matched your search

+244
View File
@@ -0,0 +1,244 @@
---
name: marqdo
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.
---
# 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).
## 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.
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.
## Markup → meaning (v0.2)
| Marker | Meaning |
|--------|---------|
| `#` | **Object / type** (constructor body). `# main` = entry object. `# Child = > Parent` = inherit (**no** implicit parent constructor; call `` `self` = > Parent … `` explicitly when needed). |
| `##` … `######` | **Function / method** (nesting by heading depth). |
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
| `1.` `2.` … in body | Branch arm (condition or `N. *` else). **Same-indent restart at `1.` = new branch statement** (not more arms of the previous list). |
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
| Line `N. *` | Else arm |
| `> fn args` | Call (named `k=v` or positional) |
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
| Frontmatter `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] `` |
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
| Unmarked prose | Comment |
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
## Minimal program
```markdown
# main
> print text=Hello World!
```
Chinese builtins (same functions, no import):
```markdown
# main
> 打印 内容=你好
```
## Functions, calls, end-body
```markdown
# main
> greet who=Marqdo
## greet
+ `who`
> print text=Hello, `who`!
---
```
- Call: `> name key=value` or `> name value`.
- Nested helpers use deeper `#` (`##`, `###`, …).
- After a helper with only side effects, end with `---` / `***`.
## Statements, returns, branches
```markdown
*x = 1*
*y = x + 2*
## add_one
+ `n`
**n + 1**
```
```markdown
*n = 0*
1. `n` > 0
> print text=positive
2. `n` < 0
> print text=negative
3. *
> print text=zero
```
## Frontmatter imports + stdlib
Imports use `import bind:target` (`导入` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
```markdown
---
title: example
import text:lib/text.mq.md
import clock:lib/time.mq.md
---
# main
*xs = > text.split value="a,b,c" sep=","*
> print text=`xs`
*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).
- 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/web` (dynamic sites)
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin first: `cargo build --release -p marqdo_plugin_web`.
Import **one language file** — never mix EN/ZH API names in the same `.mq.md`:
- EN: `import web:ext/web/web.mq.md`
- ZH: `导入 网页:ext/web/网页.mq.md`
**Hard rules (web):**
- Authors use **GFM tables + `#` classes** — no `json.parse` / `json.set` glue, no hand-built part JSON.
- Table cells stay **literal strings**; path text like `` `posts`.`title` `` is resolved by web classes.
- **`ext/**` never calls `host_*`** — hot path is native `plugins/web` ABI.
- HTTPS: terminate at reverse proxy; set `cookie_secure=True` on auth (no in-process TLS).
**Typical layout:**
```text
index.mq.md # entry + home page table + listen
pages/ # sub-pages
components/ # reusable |属性|值|样式| tables
styles/ # CSS modules
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`.
**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.
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/).
Web patterns: [examples.md](examples.md) §13 · API index: [reference.md](reference.md).
## Official extension: `ext/quantum` (circuits + Q7/Q8)
Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --release -p marqdo_plugin_quantum`, then **`marqdo ext add quantum` again** so view loads the new `libquantum.so` (stale plugin = old black/white circuits).
- EN: `import quantum:ext/quantum/quantum.mq.md`
- ZH: `导入 量子:ext/quantum/量子.mq.md`
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; ≤12 qubits for statevector; density-matrix ops ≤6 qubits; one language file per program; quote draw string args (`kind="…"`, `theme="…"`).
**Core:** `# circuit` / `# gate` / `# density` — table `steps=` or method chain; `simulate` / `probabilities` / `run` / `draw`.
**Q7 linear algebra:** `density`, `partial_trace`, `eig`, `expect` (Pauli string, left=high bit), `purity`, `kron`, `schmidt`, `fidelity`.
**Draw kinds:** `circuit|probs|bloch|hinton|city|density|paulivec|qsphere|multibloch`.
**Q8 themes (circuit / probs / bloch):** `theme="dark"|"light"|"bw"` (ZH `主题=`; **default `dark`** — slate lab look, gate-family colors, label chips so wires never cross `q0` text). View plot chrome follows `data-theme` on the SVG. Advanced kinds (hinton/…) still Q8c pending full re-skin.
```markdown
*_ = > `qc`.draw kind="circuit" theme="dark"*
*_ = > `qc`.draw kind="probs" theme="light"*
```
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
## AI authoring workflow
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
2. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
3. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
4. On `path:line:col: message`, fix that span; re-run until exit 0.
5. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
## Anti-patterns (common model mistakes)
| Wrong | Right |
|-------|-------|
| `**Hello**` to print | `> print text=Hello` |
| `# main` then prose then code with no blank line | Blank line before code |
| `if x > 0:` | `1. `x` > 0` |
| `* > print text=hi *` | `> print text=hi` |
| `` *`a` = 1 * `` (trailing space + backticks) | `*a = 1*` — bare bind, no trailing space before `*` / `**` |
| `*xs = > text.split value=a,b sep=,*` (bare text args) | `*xs = > text.split value="a,b" sep=","*` — quote text literals; bare words are variables |
| Forgetting `---` after nested `##` helper | Add `---` / `***` / `****` |
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
| `json.set` to build page parts | GFM tables + `page.compose_*` / `web.page` methods |
| Mix `web.page` and `网页.页面` in one file | One import language per `.mq.md` |
| Call `host_web_*` from `ext/web` | Use `# app` / `# db` methods; plugin ABI only |
| Call `host_*` from `ext/quantum` | Use `# circuit` / `# density` methods; plugin ABI only |
| Bare `kind=hinton` inside `*…*` | `kind="hinton"` — quote text literals |
| Bare `theme=dark` inside `*…*` | `theme="dark"` — quote; ZH `主题="dark"` |
| Rebuild plugin but skip `ext add` | `cargo build -p marqdo_plugin_quantum` then `marqdo ext add quantum` (or set `MARQDO_QUANTUM_PLUGIN`) |
## Checklist before finishing
- [ ] File ends with `.mq.md`
- [ ] 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
- [ ] Imports and call names share the same language file
- [ ] Web sites: tables + web classes only (no JSON glue); `data/` gitignored
- [ ] Quantum draw: quote `kind=` / `theme=`; rebuild plugin → `ext add quantum` before view
- [ ] `marqdo run` succeeds (or errors addressed)
+302
View File
@@ -0,0 +1,302 @@
# Marqdo examples (AI)
## 1. Hello (English)
```markdown
# main
> print text=Hello World!
```
## 2. Hello (Chinese builtins)
```markdown
# main
> 打印 内容=你好,世界!
```
## 3. Function + named call + body end
```markdown
# main
Greeting via a nested function:
> greet who=Marqdo
## greet
+ `who`
> print text=Hello, `who`!
---
```
## 4. Bindings and return
```markdown
# main
*a = 2*
*b = > add_one n=`a`*
> print text=`b`
## add_one
+ `n`
**n + 1**
```
## 5. Branch with else
```markdown
# main
*n = 0*
1. `n` > 0
> print text=positive
2. `n` < 0
> print text=negative
3. *
> print text=zero
```
## 6. Foreach loop
```markdown
# main
`篮子` =
| 果 |
|----|
| 苹果 |
- [果](篮子)
> print text=`果`
```
## 6b. Map table + footnote get
```markdown
# main
`分类` =
| 苹果 | 黄瓜 |
|------|------|
| 水果 | 蔬菜 |
*种 = 分类[^苹果]*
> print text=`种`
*第一 = 篮子[^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**.
Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of maps (marker column excluded):
```markdown
`订单` =
| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
*名 = 订单[^1][^品名]*
```
## 7. Import text stdlib
```markdown
---
title: split demo
import text:lib/text.mq.md
---
# main
*parts = > split value=a,b,c sep=,*
> print text=`parts`
```
## 8. Comment paragraphs (blank-line rule)
```markdown
# main
This whole paragraph is a comment, including lines that look like code:
*not_executed = 1*
> print text=also still comment
After a blank line, code runs:
> print text=this runs
```
## 9. Frontmatter import only
```markdown
---
description: loads math
import math:lib/math.mq.md
---
# main
*t = > num value=3.5*
> print text=`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` / `自`.
## 10b. Object inheritance
```markdown
# Greeter
## hello
+ `who`
*msg = "Hello, `who`!"*
**msg**
# Loud = > Greeter
## hello
+ `who`
*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:
```markdown
# Child = > Parent
+ `name`
*self = > Parent name=`name`*
*self = > json.set map=`self` key=extra value=1*
**self**
```
## 11. Agent layout (ABI)
```markdown
---
import agent:ext/agent.mq.md
---
# main
> load_native
*ws = > agent*
*n = > `ws`.ensure_layout*
> print text=`n`
```
Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see `doc/design/ext-agent.md`).
## 12. What not to emit
```markdown
# BAD — bold is return, not print
**Hello**
# BAD — Python control keywords
if x > 0:
print(x)
# BAD — wrapping a call in italics
*> print text=hi*
# BAD — old branch syntax (removed)
+ `x` > 0
# GOOD — ordered list arms
1. `x` > 0
> print text=pos
2. *
> print text=other
# GOOD — another independent branch (restart at 1.)
1. `y` > 0
> print text=y-pos
2. *
> print text=y-other
```
## 13. Dynamic site (ext/web, minimal)
```markdown
---
title: hello-site
import web:ext/web/web.mq.md
import db:db/index.mq.md
---
# main
`shell` =
| 组件 | 样式 |
|------|------|
| nav | |
`main` =
| 属性 | 值 | 样式 |
|------|-----|------|
| title | posts.title | |
| body | posts.summary | |
*store = > db.open*
*css = "body{font-family:sans-serif}"*
*page = > web.page title="Hello"*
*page = > page.compose_components components=`shell`*
*page = > page.compose_main main=`main`*
*page = > page.css css=`css`*
*app = > web.app page=`page` port=8080*
*app = > app.static prefix="/static" dir="static"*
> listen app=`app`
```
- Import `ext/web/web.mq.md` **or** `ext/web/网页.mq.md` — not both; match API language to the file.
- Full blog/CMS patterns: `examples/marqdo-blog/` (routes, SEO, RSS, auth, upload, WS).
- Run after `marqdo ext add web` and building `marqdo_plugin_web`.
## 14. Quantum entanglement lab (ext/quantum Q7/Q8)
```markdown
---
import quantum:ext/quantum/quantum.mq.md
---
# main
`steps` =
| step | gate | qubits |
|------|------|--------|
| 1 | H | 0 |
| 2 | CX | 0,1 |
*qc = > quantum.circuit qubits=2 steps=`steps`*
*rho = > `qc`.density*
*red = > `rho`.partial_trace keep=0*
*sch = > `qc`.schmidt cut=1*
*_ = > `qc`.draw kind="circuit" theme="dark"*
*_ = > `qc`.draw kind="hinton"*
> print text=`red`
```
- Full lab: `examples/quantum-entanglement/`. Bell-only: `examples/quantum-bell/`.
- `theme="dark"|"light"|"bw"` (default dark) on `circuit` / `probs` / `bloch`. Quote `kind=` / `theme=`.
- After rebuilding the plugin: `marqdo ext add quantum` so view loads the new native lib.
+180
View File
@@ -0,0 +1,180 @@
# Marqdo reference (AI)
Load this when you need stdlib names, CLI, or edge cases. Core rules stay in [SKILL.md](SKILL.md).
## CLI
```text
marqdo --version
marqdo run FILE.mq.md
marqdo run FILE.mq.md --backend bytecode
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
```
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`.
Stdlib search order for `lib/…` imports: `MARQDO_LIB`, `./lib`, directory of the `marqdo` executable (and a few parents). Prefer the **bundle zip** (`marqdo.exe` + `lib/`) over a bare exe.
官方扩展(`ext/…`,非 stdlib):`marqdo ext add` 装到 `MARQDO_EXT` 或 `~/.marqdo/ext`;导入仍写 `import llm:ext/llm.mq.md`。解析还含 cwd `ext/`、二进制旁 `ext/`。对象:`doc/design/objects.md`。Agent:`doc/design/ext-agent.md` · 安装器:`doc/design/ext-cli.md`。
## Builtins (no import)
| EN | ZH | Role |
|----|----|------|
| `print` | `打印` | stdout; arg `text` / `内容` |
| `input` | `输入` | one line; arg `prompt` / `提示` |
| `len` | `长度` | length; arg `value` / `值` |
| `str` | `文本` | to text; arg `value` / `值` |
| `int` | `整数` | to int; arg `value` / `值` |
Keywords (not variable names): `True`/`真`, `False`/`假`, `None`/`空`, `and`/`且`, `or`/`或`, `not`/`非`.
## Standard library files
Import one file; use **that** file’s function names.
| EN import | ZH import | Typical APIs (EN / ZH) |
|-----------|-----------|-------------------------|
| `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/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/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/web/web.mq.md` | `ext/web/网页.mq.md` | dynamic sites — see **ext/web** section below |
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below |
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
## ext/web (dynamic sites)
Install: `marqdo ext add web` (`网页`). Native: `cargo build --release -p marqdo_plugin_web`.
| EN import | ZH import | Core types |
|-----------|-----------|------------|
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | `# page` `# style` `# db` `# form` `# app` `# auth` `# cache` `# storage` |
| Area | EN methods (representative) | Notes |
|------|----------------------------|-------|
| Page | `compose_components`, `compose_main`, `render`, `meta`, `paginate` | GFM tables; cells are literal path strings |
| DB | `init`, `insert`, `select`, `paginate`, `get`, `update`, `delete`, `migrate`, `fts`, `search`, `count`, `事务`/`txn` | init supports `unique`/`index`/`fk`; auto `created_at`/`updated_at` |
| App | `route`, `static`, `configure`, `listen`, `auth`, `gate`, `upload`, `download`, `gallery`, `route_rss`, `redirect`, `error_page`, `sitemap`, `robots` | W0–W7 + P3 complete |
| Auth | `login`, `check`, `logout`, `hash_password` | argon2 + CSRF + SQLite sessions; `role` for RBAC |
Drivers (Postgres / Redis / S3): `db url=postgres://…`, `cache url=memory:`, `storage url=file:…` — see `doc/design/ext-web-drivers.md`.
Example project: `examples/marqdo-blog/`. Capability matrix: `doc/design/web-net-capabilities.md`.
## ext/quantum (circuits + Q7/Q8)
Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p marqdo_plugin_quantum`, then re-run `ext add` so view picks up the new `.so`.
| EN import | ZH import | Core types |
|-----------|-----------|------------|
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | `# circuit` `# gate` `# density` |
| Area | EN APIs | Notes |
|------|---------|-------|
| Circuit | `h`/`cx`/…, `simulate`, `probabilities`, `run`, `draw`, `noise` | `steps=` GFM table; ≤12 qubits |
| Gate | `matrix`, `matches_matrix`, `draw` | named or `matrix=` custom unitary |
| Density (Q7) | `purity`, `partial_trace`, `eig`, `expect`, `draw` | ≤6 qubits for dense ρ |
| Free (Q7) | `kron`, `schmidt`, `fidelity` | top-level on import bind |
| Draw kinds | `circuit\|probs\|bloch\|hinton\|city\|density\|paulivec\|qsphere\|multibloch` | quote `kind="…"` |
| Themes (Q8) | `theme="dark"\|"light"\|"bw"` (ZH `主题=`) | default **dark**; circuit/probs/bloch themed; SVG `data-theme` |
Examples: `examples/quantum-bell/`, `examples/quantum-entanglement/`. Design: `doc/design/ext-quantum.md` · Q7: `doc/design/ext-quantum-q7.md` · Q8: `doc/design/ext-quantum-viz-style.md`.
## Formula + plot (math)
```markdown
---
import math:lib/math.mq.md
---
# main
`f` =
$$
x^2 - 2
$$
*_svg = > plot formula=`f` var=x min=-3 max=3*
```
Empty RHS assignment + following `$$…$$` binds a formula value. Narrative-only `$$` without binding is display, not assignment.
## Foreign (Python example)
```markdown
---
import foreign:lib/foreign.mq.md
---
# main
`hi` =
```python
print("hello-from-python")
```
```
Lines starting with `` ` `` can be code (binding). Keep a blank line before/after fences per comment rules.
## Function-end details
| Form | Effect |
|------|--------|
| Lone `---` or `***` (≥3 same chars) at function body top level | End function; no return value |
| `****` or empty bold | Return `None` and end body |
| `**expr**` | Return `expr`; does **not** by itself cut off later sibling statements — still use HR or shallower heading |
File-leading paired `---` is frontmatter only; body `---` is not frontmatter.
## Call arguments
- Named: `> greet who=World`
- Positional: `> greet World`
- Spaces in values: allowed in named forms as in docs (`who=marqdo user`)
- Inline call in statement: `` *`n` = > len value=`s`* ``
See `doc/design/call-arguments.md`.
## Identifiers
- Variables: `` `name` ``
- Comparisons: `==` `>` `<` `>=` `<=`
- Do not use keyword tokens as names
## Design docs (repo)
| Doc | Topic |
|-----|--------|
| `doc/design/markdown-mapping.md` | Syntax constitution |
| `doc/design/objects.md` | `#` objects / `##` methods |
| `doc/design/keywords.md` | Builtins / keywords |
| `doc/design/return-hr-and-code-surface.md` | Function end / surfaces |
| `doc/design/stdlib-i18n.md` | EN/ZH lib files |
| `doc/design/stdlib-modules.md` | L1 modules including plugin |
| `doc/design/ext-abi.md` | Native C ABI v1 |
| `doc/design/ext-llm.md` | `ext/llm` |
| `doc/design/ext-agent.md` | `ext/agent` agent **framework** (layout shipped; LLM orchestration roadmap) |
| `doc/design/ext-cli.md` | `marqdo ext list/add/remove` |
| `doc/design/ext-web.md` | `ext/web` dynamic sites (author API) |
| `doc/design/web-net-capabilities.md` | ext/web capability matrix (W0–W7 + P3) |
| `doc/design/ext-quantum.md` | `ext/quantum` circuits |
| `doc/design/ext-quantum-q7.md` | Q7 density linear algebra + advanced SVG |
| `doc/design/ext-quantum-viz-style.md` | Q8 themed SVG (`dark`/`light`/`bw`; circuit/probs/bloch) |
| `doc/design/view-debug.md` | view / debug hosts |
+3 -5
View File
@@ -11,6 +11,7 @@ on:
- "Cargo.lock"
- ".github/workflows/pages.yml"
- "scripts/build-public.*"
- "scripts/run-public-pages.sh"
workflow_dispatch:
permissions:
@@ -26,11 +27,8 @@ jobs:
uses: dtolnay/rust-toolchain@stable
- name: Build & export site
run: |
cargo build --release
find public -name '*.mq.md' ! -name 'utils.mq.md' ! -name '¹¤¾ß.mq.md' -print0 \
| xargs -0 -n1 ./target/release/marqdo run
./target/release/marqdo view output public -o public
shell: bash
run: bash scripts/run-public-pages.sh
- name: Verify site shape
run: |
+63 -5
View File
@@ -14,13 +14,34 @@ jobs:
runs-on: windows-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
- name: Install Node (VS Code extension)
uses: actions/setup-node@v4
with:
node-version: "20"
- name: Build release
run: cargo build --release
- name: Checkout extension sources (branch vscode-extension only)
run: git fetch origin vscode-extension && git checkout origin/vscode-extension -- vscode-extension
- name: Build VSIX
shell: pwsh
run: |
$ver = "${{ github.ref_name }}".TrimStart("v")
New-Item -ItemType Directory -Force -Path dist | Out-Null
Push-Location vscode-extension
npm ci
npm run compile
npx @vscode/vsce package --no-dependencies -o "../dist/marqdo-$ver.vsix"
Pop-Location
- name: Package
shell: pwsh
run: |
@@ -30,7 +51,20 @@ jobs:
$exe = "marqdo-$ver-$target.exe"
$zip = "marqdo-$ver-$target.zip"
$stdlib = "marqdo-$ver-stdlib.zip"
$source = "marqdo-$ver-source.zip"
$vsix = "marqdo-$ver.vsix"
$public = "marqdo-$ver-public.zip"
$extZip = "marqdo-$ver-ext.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
Compress-Archive -Path public/* -DestinationPath "dist/$public" -Force
$stageExt = "dist/stage-ext"
if (Test-Path $stageExt) { Remove-Item $stageExt -Recurse -Force }
New-Item -ItemType Directory -Force -Path $stageExt | Out-Null
Copy-Item ext "$stageExt/ext" -Recurse
if (Test-Path "dist/$extZip") { Remove-Item "dist/$extZip" -Force }
Compress-Archive -Path "$stageExt/*" -DestinationPath "dist/$extZip" -Force
$stage = "dist/stage-bundle"
if (Test-Path $stage) { Remove-Item $stage -Recurse -Force }
New-Item -ItemType Directory -Force -Path $stage | Out-Null
@@ -47,24 +81,48 @@ jobs:
echo "EXE=$exe" >> $env:GITHUB_ENV
echo "ZIP=$zip" >> $env:GITHUB_ENV
echo "STDLIB=$stdlib" >> $env:GITHUB_ENV
echo "VSIX=$vsix" >> $env:GITHUB_ENV
echo "SOURCE=$source" >> $env:GITHUB_ENV
echo "PUBLIC=$public" >> $env:GITHUB_ENV
echo "EXT=$extZip" >> $env:GITHUB_ENV
- name: Upload release assets
uses: softprops/action-gh-release@v2
with:
body: |
## Downloads
## 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`**.
### Downloads
| Asset | Contents |
|-------|----------|
| `marqdo-*-windows-msvc.exe` | **Executable only** — does **not** include the standard library |
| `marqdo-*-windows-msvc.zip` | **Recommended**: `marqdo.exe` + `lib/` (keep them together) |
| `marqdo-*-stdlib.zip` | Standard library only — unpack next to the exe, or set `MARQDO_LIB` |
| `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib |
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` (optional disk override) |
| `marqdo-*-stdlib.zip` | `lib/` only |
| `marqdo-*-ext.zip` | Official `ext/` L1 sources (for `MARQDO_EXT_SOURCE` / local `./ext`) |
| `marqdo-*-source.zip` | Source snapshot (`git archive`) |
| `marqdo-*.vsix` | VS Code / Cursor extension |
| `marqdo-*-public.zip` | Static user docs site |
> The standalone `.exe` does **not** ship `lib/`. Use the bundle zip or stdlib zip for `lib/…` imports.
Extension workflow: [vscode-extension-commit.md](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension-commit.md)
files: |
dist/${{ env.EXE }}
dist/${{ env.ZIP }}
dist/${{ env.STDLIB }}
dist/${{ env.EXT }}
dist/${{ env.VSIX }}
dist/${{ env.SOURCE }}
dist/${{ env.PUBLIC }}
fail_on_unmatched_files: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+44 -3
View File
@@ -1,17 +1,36 @@
/target/
/target/
/dist/
# Copied by gold harness for ABI plugins
/tests/lib/demo.dll
/tests/lib/libdemo.so
/tests/lib/libdemo.dylib
/tests/ext/agent.dll
/tests/ext/libagent.so
/tests/ext/libagent.dylib
/tests/ext/skel.mq.md
/tests/ext/out-demo.mq.md
/tests/ext/ticket.txt
/tests/ext/ticket-stub.txt
/tests/ext/agents/
/tests/ext/runbooks/
/tests/ext/templates/
/tests/ext/reports/
**/*.rs.bk
.idea/
# Editor settings at repo root only (keep vscode-extension/.vscode for F5)
/.vscode/
.vscode/
*.pdb
.DS_Store
.marqdo/
**/.marqdo/
.env
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
/public/index.html
/public/pages/
# VS Code extension: source only on branch `vscode-extension` (see doc/design/vscode-extension-commit.md)
/vscode-extension/
# Python spike venv (local)
spike/.venv/
@@ -19,3 +38,25 @@ spike/__pycache__/
spike/.pytest_cache/
**/__pycache__/
*.pyc
# Local sqlite / scratch
/data/
/tmp/
plugins/*/tmp/
# web smoke/example DBs (cwd-relative or fixture data dirs)
/web-fixtures/
/tests/ext/web-fixtures/data/
/tests/ext/entrydir-fixtures/data/
/examples/web-site/data/
/examples/web-site-zh/data/
/examples/web-net-site/data/
/examples/web-net-site-zh/data/
/examples/marqdo-blog/data/
# Quantum draw/SVG runtime outputs (sources & gold .mq.md stay tracked)
/tests/ext/quantum-*.svg
/examples/quantum-*/**/*.svg
/examples/quantum-*/*.svg
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
/ext/native/
+128
View File
@@ -0,0 +1,128 @@
# Changelog
## Unreleased
## v0.3.0 — 2026-08-29
### Highlights
本版把 **`ext/web` 网络能力(W0–W7 + P3)**、**`ext/quantum` Q7/Q8**、**`ext/agent` A1–A4** 一并收口到正式发布;并修了网页扩展叙述行误解析、补充 ASGI/生产部署说明与 agent 下一波(B0–B5)缺口调研。
**如何拿到本版**
```bash
# 从源码(推荐跟 main / 本 tag)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v0.3.0
cargo build --release
./target/release/marqdo version
# 或从 GitHub Releases 下载 Windows 包 / 源码 zip(见 Release 资产)
marqdo version --check
```
**扩展(非 stdlib)**
```bash
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
marqdo ext add web && marqdo ext add agent && marqdo ext add quantum
# 中文 id:网页 / 智能体 / 量子 / 大模型
```
### Added
- **调研:`ext/agent` A0–A4 之后缺口** ([agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)):产品化示例、评测 harness、真 MCP、plan resume/HITL、飞轮指标与建议分期 B0–B5;挂到 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md) 与 [doc/README.md](doc/README.md)。
- **生产部署调研(ASGI)** ([web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)):不能挂 Daphne/Uvicorn;路径为反向代理 → 嵌入式 `listen`(axum)。
- **`ext/agent` A4(RAG/MCP 证据工具)**: `corpus_search` 本地语料关键词检索;`mcp_list_tools` / `mcp_call` 读 JSON fixture;返回 `authority=workbook`。金样 `agent-tools-rag-a4`。
- **`ext/agent` A3(上下文预算)**: `source_brief` / 加深版 `skill_brief`;`build_step_context` 默认截断并提示 `READ:source|skill`;`step` 支持最多 `max_reads` 次加深;父 `READ:skill`。金样 `agent-context-budget-a3`。
- **`ext/agent` A2(过程可见)**: `plan` 过程事件默认写入返回 map 的 `events`(SSE 仍仅 `stream=True`);OKF 命中记 `REUSE` decision;view plan 卡渲染过程时间线。对齐 [agent-streaming.md](doc/roadmap/agent-streaming.md)。
- **`ext/agent` A1(OKF 复用飞轮)**: `agent_kb_list_tasks` 返回 description/aliases/status/llm_free/hits;`plan` 命中路径暴露 `match`/`score`(summary 含 match kind);soft_match 策展提示带 status/llm_free/description;view plan 卡显示 match。金样 `agent-kb-plan-hit`。路线 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md)。
- **`ext/web` 样式装配(`web_style` / `网页.样式装配`)**: 样式即数据表格 —— GFM 样式表(`|选择器|属性|值|`,可用 `|媒体|` 列分组进 `@media` 块)经 `样式装配` 函数转成 CSS 文本,再拼装成完整主题。替代"整段手写 CSS 字符串"的写法,贯彻 文档即代码。见 [marqdo-blog](examples/marqdo-blog/styles/theme.mq.md)。
- **网络能力调研(`doc/design/web-net-capabilities.md`)**: 盘点 `ext/web` + `plugins/web` + `lib/net` 现状,对照主流语言网络栈(FastAPI / Express / Flask / axum),给出「开发一个完整 Web 项目」所需能力的差距清单与分波次补强路线(W1–W7 + P3,**2026-08-28 已全部落地**)。
- **AI Skill + 文档(ext/web 完结复核)**: `skills/marqdo/` 与 `.cursor/skills/marqdo/` 增加 **ext/web 动态站** 专节(硬规则、API 摘要、§13 最小站点样例);`doc/design/web-net-capabilities.md` 结论/对照表与 W7+P3 实现对齐;`doc/design/ai-skill.md` 更新用途说明。
- **`ext/quantum` Q7(高阶线性代数 + 高级可视化)**: 密度矩阵 / 部分迹 / Hermitian 谱 / Schmidt / Pauli 期望 / 纯度;SVG:hinton、city、density、paulivec、qsphere、multibloch。全部经 `plugins/quantum` ABI。设计 [ext-quantum-q7.md](doc/design/ext-quantum-q7.md);金样 `quantum-linalg-smoke`、`quantum-viz-advanced-smoke`;示例 [quantum-entanglement](examples/quantum-entanglement/)。
- **`ext/quantum` Q8a/Q8b(可视化美学)**: `draw theme=dark|light|bw`(默认 dark);标签芯片 + gutter 消除线穿字;门族分色;probs/bloch 共用令牌;view 对 `data-theme` 换图框。设计 [ext-quantum-viz-style.md](doc/design/ext-quantum-viz-style.md)。改插件后须 `marqdo ext add quantum` 再开 view。
### Fixed
- **`ext/web` / `网页.mq.md`**:叙述行勿以反引号开头,避免被解析为语句(`examples/marqdo-blog` 可正常 `listen`)。
### Changed
- **Frontmatter import syntax**: `import bind:target` / `导入 bind:target` (file `.mq.md` or short name `lib.member`). Removed legacy `> path.mq.md` / `> use` imports. See [module-namespace.md](doc/design/module-namespace.md).
## v0.2.0 — 2026-08-12
### Highlights — official extension libraries
This release centers on **`ext/`**: optional packages that are **not** part of the embedded stdlib. Install them with the CLI; native plugins (`.so` / `.dll`) ship beside L1 Markdown APIs.
**How to get extensions**
```bash
# List what the installer knows about
marqdo ext list
# Install from the repo's ./ext (or MARQDO_EXT_SOURCE), into ~/.marqdo/ext (or MARQDO_EXT)
marqdo ext add llm
marqdo ext add agent
marqdo ext add web
marqdo ext add quantum
# Chinese ids work the same (大模型 / 智能体 / 网页 / 量子)
marqdo ext add 量子
marqdo ext remove quantum
```
Native plugins (agent / web / quantum) must be built once, then `ext add` copies them into `MARQDO_EXT/native/`:
```bash
cargo build --release -p marqdo_plugin_agent
cargo build --release -p marqdo_plugin_web
cargo build --release -p marqdo_plugin_quantum
marqdo ext add agent
marqdo ext add web
marqdo ext add quantum
```
Runtime also resolves plugins from `CARGO_TARGET_DIR`, `target/`, next to the `marqdo` binary, or `MARQDO_*_PLUGIN` env vars. Design: [ext-cli.md](doc/design/ext-cli.md) · [ext-abi.md](doc/design/ext-abi.md).
| Package | What you get |
|---------|----------------|
| **llm** | OpenAI-compatible chat — [ext-llm.md](doc/design/ext-llm.md) |
| **agent** | Agent layout / orchestration helpers + native plugin — [ext-agent.md](doc/design/ext-agent.md) |
| **web** | HTTP + SQLite site helpers + native plugin — [ext-web.md](doc/design/ext-web.md) |
| **quantum** | State-vector circuits, draw, noise, formula `matrix=` custom gates — [ext-quantum.md](doc/design/ext-quantum.md) |
User-facing intro: [`public/features/05-extensions.mq.md`](public/features/05-extensions.mq.md) / [`05-扩展.mq.md`](public/features/05-扩展.mq.md).
### Added
- Full **ext CLI** catalog: `llm`, `agent`, `web`, `quantum` (EN/ZH ids).
- **Quantum (Q0–Q6)**: gates, `run`/`steps`, draw (circuit/probs/bloch), heatmaps, teaching noise incl. amplitude damping, **custom gates from `$$` / `matrix=`**.
- **Web** extension (listen / render / SQLite) with L1 EN/ZH.
- **Agent** native plugin path + installer copy into `native/`.
- View **Variables** panel: previews + click-to-open rich modal (matrices / KaTeX).
- Formula matrix parse (`pmatrix` / `[[…]]`) for executable gate matrices.
### Changed
- Release notes and docs emphasize extensions vs embedded stdlib.
- Highlight.js CDN path for view pages; Variables panel script escaping fixed.
## v0.1.2 — 2026-08-07
### Added
- **Embedded standard library**: official `lib/*.mq.md` ships inside the `marqdo` binary; disk `lib/` and `MARQDO_LIB` still override.
- **`lib/writeback`** / **`lib/subtask`**: Jupyter-style writeback; concurrent subtasks (file / function / foreign).
- **Surface syntax v0.2**: `` + `param` `` parameters, `1.` ordered branches, backtick identifiers, quoted strings.
- **`marqdo version --check`**: compare installed CLI with latest GitHub release.
- **VS Code extension v0.0.6** (branch **`vscode-extension` only**): v0.2 grammar, update check — see [doc/design/vscode-extension-commit.md](doc/design/vscode-extension-commit.md)
### Changed
- Subtask `spawn` accepts `path=`, `fn=`, `code=`, or `lang=`+`source=` (not file-only).
- Release notes: standalone `.exe` includes stdlib; bundle/stdlib zips remain optional for overrides.
## v0.1.1
- v0.2 syntax migration, writeback/subtask v1 (file subprocess only), view input deferral, optional parameters.
## v0.1.0
- Initial public releases: tree + bytecode backends, `view` / `debug` / `catalog`, core stdlib, `ext/` installer.
Generated
+1816 -26
View File
File diff suppressed because it is too large. Load diff
+15 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "0.1.0"
version = "0.3.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -19,7 +19,21 @@ pulldown-cmark = "0.12"
serde_json = "1"
thiserror = "1"
tiny_http = "0.12"
# 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"
include_dir = "0.7"
libc = "0.2"
[workspace]
members = ["plugins/demo", "plugins/agent", "plugins/web", "plugins/quantum"]
resolver = "2"
[dev-dependencies]
assert_cmd = "=2.0.14"
predicates = "=3.1.0"
tokio = { version = "1", features = ["rt-multi-thread", "macros", "time", "net"] }
tokio-tungstenite = "0.24"
futures-util = "0.3"
+62 -17
View File
@@ -6,7 +6,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 `vscode-extension`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/)
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
---
@@ -23,7 +23,7 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
---
## 语法速览(v0.1)
## 语法速览(v0.2)
| 标记 | 含义 |
|------|------|
@@ -32,9 +32,11 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
| `**…**` | **返回值**(架构) |
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
| `#` / `##` | 函数与作用域 |
| `+` / `1.` | 分支(臂头单独 `*` = else) |
| `-` | 循环(头下纯名则为形参) |
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
| `##` … | 函数 / 方法(按标题深度嵌套) |
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
| `+` / `1.` … | 函数头下 `` + `名` `` = 形参;体内 `1.` `2.` … = 分支(`N. *` = else) |
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) `` / `` - [`项`](`集合`) ``) |
| 表格 | 集合 |
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
@@ -45,14 +47,14 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
> 问候 谁=World
## 问候
- 谁
+ `谁`
> print text=Hello `谁`!
---
## 加一
- n
+ `n`
**`n` + 1**
```
@@ -87,6 +89,8 @@ marqdo sync [PATH] -o OUT_DIR # catalog 的别名
产物示例:`catalog.yaml`、`index.md`、`modules/*.md`(`type: Marqdo Module` 等)。设计见 [generated-yaml-manifest.md](doc/design/generated-yaml-manifest.md) · 调研 [okf-and-marqdo.md](doc/research/okf-and-marqdo.md)。
智能体框架横向调研(LangGraph / CrewAI / 厂商 SDK 等 vs Marqdo 文档驱动优势):[agent-frameworks-and-marqdo.md](doc/research/agent-frameworks-and-marqdo.md) · 优化路线 [ext-agent-optimize.md](doc/roadmap/ext-agent-optimize.md)。
```bash
cargo run -- catalog public -o .marqdo
# 或已安装二进制时:
@@ -95,30 +99,71 @@ marqdo catalog public -o .marqdo
---
## 现状(v0.1.0)
## 现状(v0.3.0)
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Source)
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430)
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
- 标准库:文本、文件、系统、时间、JSON、网络、数学(公式/绘图)、外联(Python 等)
- **`marqdo version --check`**:与 GitHub 最新 release 对比
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**
- **官方扩展库 `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)
- **`quantum`**:Q0–Q7 + Q8a/b 主题 SVG;示例 [quantum-entanglement](examples/quantum-entanglement/)
- **`agent`**:A1–A4(OKF 复用、过程事件、上下文预算、RAG/MCP fixture);下一波缺口 [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
- **`llm`**:OpenAI 兼容对话
- 安装:`marqdo ext list` / `add …` / `remove`([ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum}`
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md)
### 如何使用最新 Marqdo(v0.3.0)
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v0.3.0 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
marqdo version --check
# 2) 跑解释器 / 文档站 / catalog
marqdo run tests/structure/hello.mq.md
marqdo run tests/structure/hello.mq.md --backend bytecode
marqdo view public --no-open
marqdo debug public --no-open
marqdo catalog public -o .marqdo
# 3) 安装官方扩展(需先编原生插件)
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum
marqdo ext add web # 或:网页
marqdo ext add agent # 或:智能体
marqdo ext add quantum # 或:量子
marqdo ext add llm # 或:大模型
# 4) 动态站示例(扩展装好后)
marqdo run examples/marqdo-blog/index.mq.md
# 浏览器打开终端打印的 listen 地址
# 5) Windows:也可从 GitHub Releases 下载 exe / zip / vsix
# https://github.com/cflmy/marqdo/releases/tag/v0.3.0
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
```bash
cargo run -- run tests/structure/hello.mq.md
cargo run -- run tests/structure/hello.mq.md --backend bytecode
cargo run -- view public --no-open
cargo run -- debug public --no-open
cargo run -- catalog public -o .marqdo
cargo run -- view output public -o public
powershell -File ./scripts/build-public.ps1
```
**发布包(GitHub Releases)**:单独 `.exe` **不含** `lib/`;请下载带 `lib/` 的 zip,或另下 `*-stdlib.zip` 解压到可执行文件旁(亦可设 `MARQDO_LIB`)。
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md)
**发布包(GitHub Releases)**:单独二进制 **已内置**官方 `lib/`(`import …:lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发。**扩展库**用 `marqdo ext add …` 安装(见 [CHANGELOG](CHANGELOG.md) 与 [ext-cli.md](doc/design/ext-cli.md));原生 `.so`/`.dll` 需本地编译或从带 `native/` 的安装目录解析。
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md) · 变更 [CHANGELOG.md](CHANGELOG.md)
---
## 命名
+28 -6
View File
@@ -16,32 +16,54 @@
| 文档 | 摘要 |
|------|------|
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.1 语法宪法** |
| [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) | 叙述 / 可执行 / 外联 |
| [design/return-hr-and-code-surface.md](design/return-hr-and-code-surface.md) | 语句/返回/输出决议 |
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单 |
| [design/generated-yaml-manifest.md](design/generated-yaml-manifest.md) | 生成式 OKF 清单(早期方向) |
| [design/okf.md](design/okf.md) | **Marqdo OKF 实现规范**(catalog v0 + 任务知识包) |
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
| [design/tech-stack.md](design/tech-stack.md) | 实现栈对比 |
| [adr/0001-implementation-language.md](adr/0001-implementation-language.md) | **Accepted:Rust 参考解释器;不用 Flex/Bison** |
| [design/dependencies.md](design/dependencies.md) | 依赖详单(无 Flex/Bison) |
| [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置函数** |
| [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** |
| [design/stdlib.md](design/stdlib.md) | **P2 标准库:内置 + `lib/` + 错误约定** |
| [design/module-namespace.md](design/module-namespace.md) | **模块命名空间:导入绑定库名、`库.成员` / `use`(M1+M2 已落地)** |
| [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/网络(JSON 中英同库)** |
| [design/stdlib-math.md](design/stdlib-math.md) | **方案:数学库(数值/随机/作图/轻量求解)** |
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **暂缓:外联胶水(\`\`\`lang 具名块)** |
| [design/stdlib-modules.md](design/stdlib-modules.md) | **L1:文件/系统/时间/JSON/网络/数学/外联/插件** |
| [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`) |
| [design/ext-llm.md](design/ext-llm.md) | **官方扩展 `ext/llm`(OpenAI 兼容)** |
| [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(文档驱动:单步 / 多步工作簿 + 自写回;废弃 thin TOOL 循环)** |
| [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/web-asgi-servers-and-marqdo.md](design/web-asgi-servers-and-marqdo.md) | **Daphne/Uvicorn 等 vs Marqdo**:不能直接托管;反代 + axum `listen` |
| [design/call-arguments.md](design/call-arguments.md) | **调用:具名 + 位置实参** |
| [design/examples-and-tests.md](design/examples-and-tests.md) | **tests/ 金样例目录布局** |
| [design/view.md](design/view.md) | **`marqdo view` / `view output` 黑白极简 + 静态文档** |
| [design/user-site.md](design/user-site.md) | **用户站:`public/` → `gh-pages`** |
| [design/catalog-cli.md](design/catalog-cli.md) | **`marqdo catalog` / `sync` OKF 清单命令** |
| [design/view-debug.md](design/view-debug.md) | **`marqdo debug` 独立调试页** |
| [design/vscode-extension.md](design/vscode-extension.md) | **VS Code 扩展:分支 `vscode-extension`(main 不跟踪源码)** |
| [design/vscode-extension-commit.md](design/vscode-extension-commit.md) | **扩展提交约定(禁止在 main 提交 `vscode-extension/`)** |
| [design/bytecode.md](design/bytecode.md) | **M5 字节码 / 双后端** |
| [design/pipeline-debug.md](design/pipeline-debug.md) | **流水线 `--dump-*` 可视调试** |
| [dev-setup.md](dev-setup.md) | 开发环境配置(Rust M0) |
| [roadmap/interpreter.md](roadmap/interpreter.md) | 正经解释器路线图 |
| [roadmap/next-phase.md](roadmap/next-phase.md) | **下一阶段:input / 诊断 / 标准库 / view 调试** |
| [roadmap/okf-near-match.md](roadmap/okf-near-match.md) | **规划:OKF 相近任务命中**(精确 sig 之外的可选软复用) |
| [roadmap/agent-streaming.md](roadmap/agent-streaming.md) | **流式输出**(SSE + `complete`/`step` stream;S0–S1 已落地) |
| [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/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**(已完成) |
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
+29
View File
@@ -0,0 +1,29 @@
# Marqdo AI Skill
| | |
|---|---|
| 状态 | 已提供 |
| 日期 | 2026-08-05(初版)· 2026-08-28(ext/web 完结复核 · ext/quantum Q8) |
| 路径 | [`skills/marqdo/`](../../skills/marqdo/)(权威);Cursor 镜像 [`.cursor/skills/marqdo/`](../../.cursor/skills/marqdo/) |
---
## 目的
让接入方(Cursor Agent、其它支持 Agent Skills 的模型宿主)在**加载本 skill 后**即可按 v0.2 语法正确编写 / 修改 `.mq.md`,并在使用 **`ext/web` 动态站** 或 **`ext/quantum` 电路/可视化** 时遵循官方作者面(不混中英 API、不写 JSON 袋胶水;量子绘图须引用 `kind=`/`theme=` 字符串)。
## 内容
| 文件 | 用途 |
|------|------|
| `SKILL.md` | 必读:硬规则、标记表、**ext/web**、**ext/quantum(Q7/Q8)**、工作流、反模式 |
| `reference.md` | 按需:CLI、stdlib/ext 索引、web/quantum API 摘要 |
| `examples.md` | 按需:可复制样例(§13 最小站点 · §14 纠缠实验) |
## 使用
- **本仓库 Cursor**:项目 skill 已在 `.cursor/skills/marqdo/`;描述含 `.mq.md` / Marqdo 触发词,可自动选用。
- **其它 AI**:将 `skills/marqdo/` 整目录作为 skill 包导入,或把 `SKILL.md` 贴进系统/项目说明并允许模型按需打开 `reference.md` / `examples.md`。
- **校验**:生成后执行 `marqdo run <file>.mq.md`,按 `path:line:col` 诊断迭代。
语法真相仍以 [markdown-mapping.md](markdown-mapping.md) 与 [keywords.md](keywords.md) 为准;skill 是面向模型的压缩操作手册。
+2 -1
View File
@@ -67,7 +67,8 @@
| `keywords/bool-logic` | ✅ | ✅ |
| `structure/nested-call` | ✅ | ✅ |
| `structure/positional-call` | ✅ | ✅ |
| `structure/import/*` | ✅ | ✅(load 合并 AST 后编译) |
| `structure/import/*` | ✅ | ✅(导入模块树后编译) |
| `structure/ns/*` | ✅ | ✅ |
| `tests/errors/*` | ✅(非零退出) | 同 tree 语义(编译期/运行期诊断) |
核心金样例双后端已对齐;后续可扩展 Op、优化与更好的调试信息。
+6 -3
View File
@@ -3,8 +3,8 @@
| | |
|---|---|
| 状态 | 已定(v0.1 增补) |
| 日期 | 2026-08-04 |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) |
| 日期 | 2026-08-07 |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) |
---
@@ -32,6 +32,9 @@ positional ::= value_token
- `value`(具名右侧):可含空格与 `` `var` `` 插值,直到下一个 `ident=` 边界。
- `value_token`(位置):空白分隔的一个词法单元——数字、`` `名` ``、标识/文本词;**不含空格**。多词字符串请用具名,例如 `> print text=Hello World!`。
- 实参值中 `` `变量` `` 后**紧跟** `[^…]` 时按**脚注取元**解析(可链式),而非文本:`> print text=苹果单价:`水果价格`[^苹果]`、`> print text=`订单`[^2][^品名]`。
- **独立 `>` 调用**:裸词 = 文本字面量。
- **`*…*` / `**…**` 段内的调用**(如 `*x = > text.split value=src sep=","*`):裸词 = **变量**(Python 统一命名空间),文本字面量必须加引号(`value="a,b"`);`` `名` `` 变量形式仍合法。
- 内置 `print` / `打印` 形参:`text` ≡ `内容`。
- `input` / `输入`:`prompt` ≡ `提示`。
- `len` / `长度`、`str` / `文本`、`int` / `整数`:`value` ≡ `值`。
@@ -50,4 +53,4 @@ positional ::= value_token
## 4. 金样例
见 `tests/structure/positional-call.mq.md` 与更新后的 `tests/structure/import/`。
见 `tests/structure/positional-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。
+32 -33
View File
@@ -2,18 +2,18 @@
| | |
|---|---|
| 状态 | 已定(v0 命令落地) |
| 日期 | 2026-08-04 |
| 状态 | 已定(O1 + O3:工程目录包 + agent-kb 概念并入) |
| 日期 | 2026-08-07 |
| 取代 | [generated-yaml-manifest.md](generated-yaml-manifest.md) 中「待决:sync/doc 命令」的命令名部分 |
| 相关 | [generated-yaml-manifest.md](generated-yaml-manifest.md) · [view.md](view.md) · [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
| 相关 | [okf.md](okf.md)(**实现规范总览**)· [generated-yaml-manifest.md](generated-yaml-manifest.md) · [view.md](view.md) · [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
---
## 1. 决策(重申)
YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。详见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配置。完整词汇、任务知识包与路线图见 [**okf.md**](okf.md)。生成式方向见 [generated-yaml-manifest.md](generated-yaml-manifest.md)。
本文件规定 **CLI 与 v0 落盘格式**。
本文件规定 **CLI 与工程目录包落盘格式**(含 O3:扫入本地 `agent-kb` 概念,供人与工具同览)。
---
@@ -28,26 +28,31 @@ marqdo sync [PATH] -o OUT_DIR
| 参数 | 默认 | 说明 |
|------|------|------|
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件) |
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件;扫描时跳过该目录) |
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
---
## 3. 生成物(v0)
## 3. 生成物
```
OUT_DIR/
catalog.yaml # 机器向总清单(OKF 风格字段)
index.md # 人/Agent 可读总览(含 YAML frontmatter)
index.md # 人可读总览:Modules + Agent knowledge
modules/
<stem>.md # 每个 .mq.md 一个概念页(frontmatter + 摘要)
<stem>.md # 每个工程 .mq.md 一个 Module 页
concepts/ # 从 **/.marqdo/agent-kb/concepts/ 复制(O3)
tasks/…
skills/…
```
路径中的目录层级拍扁为文件名时用 `__` 连接,例如:
`structure/import/main.mq.md` → `modules/structure__import__main.md`
`.marqdo/agent-kb/` 下的可执行 `.mq.md` **不**进 Module 表(由 Task/Skill 概念页的 `resource` 指向)。
### 3.1 `catalog.yaml`(示意)
```yaml
@@ -55,12 +60,11 @@ OUT_DIR/
type: Marqdo Catalog
title: marqdo-project
generated:
by: marqdo/0.0.1
# at: 可选 ISO8601;CI 比对时可忽略
by: marqdo/0.1.2
modules:
- id: structure/hello
resource: structure/hello.mq.md
title: Hello World # 来自源 frontmatter title,缺省用文件名
title: Hello World
imports: []
exports:
- name: Hello World
@@ -72,35 +76,28 @@ modules:
exports:
- name: main
kind: fn
concepts: [] # 有 agent-kb 时为 Task/Skill 条目列表
```
字段约定(v0 最小集):
| 字段 | 含义 |
|------|------|
| `type` | 固定 `Marqdo Catalog`(OKF:未知 type 可降级) |
| `modules[].resource` | 相对 `PATH` 的源路径 |
| `modules[].imports` | 源 frontmatter 中的 `> *.mq.md` |
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`);嵌套 `##` 列入 `children`(可选,v0 可扁平只列顶层) |
| `modules[].exports` | 顶层 `#` 函数名(`kind: fn`) |
| `modules[].verified` / `sources` | 源 frontmatter 有则透传(O3) |
| `concepts[]` | 本地 agent-kb 概念摘要(`id`/`type`/`page`/…) |
| `generated.by` | `marqdo/<crate version>` |
不在 v0:版本锁定哈希、跨仓 URL、完整符号类型。
不在现行范围:版本锁定哈希、跨仓 URL、完整符号类型、`log.md`(见 okf O4)。
### 3.2 模块概念页 frontmatter
### 3.2 模块概念页
```yaml
---
type: Marqdo Module
title: …
resource: structure/hello.mq.md
depends: [] # imports 列表
exports: [Hello World]
generated:
by: marqdo/0.0.1
---
```
Frontmatter 仍用 `depends` 字符串列表(机器可读);**正文 Dependencies** 链到同包其它 Module 页(人可点)。源若带 `verified` / `sources` 则写入页头。
正文含「请勿手改」提示、依赖列表、导出列表;可链到同包其它模块页。
### 3.3 Agent knowledge
`index.md` 的 **Agent knowledge** 节列出扫到的 Task/Skill,链到 `concepts/…`。概念页内容从本地 `agent-kb` **复制**,与 Agent 运行时包同源,便于人审阅晋升结果。
---
@@ -109,7 +106,7 @@ generated:
| 命令 | 产物 | 受众 |
|------|------|------|
| `marqdo view output` | 静态 HTML(结构 + 运行结果) | 人类读程序文档站 |
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引 | 工具 / Agent / 依赖总览 |
| `marqdo catalog` | OKF 风格 YAML + Markdown 索引(含 agent-kb) | 人浏览依赖/技能 · 工具 / Agent |
二者都从同一源树生成,互不替代。发布用户文档时可同时:
@@ -122,7 +119,9 @@ marqdo catalog tests -o .marqdo
## 5. 验收
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml` 与 `modules/`。
1. `marqdo catalog tests -o /tmp/mq-cat` 写出 `catalog.yaml`、`modules/`、`concepts:` 键。
2. `catalog.yaml` 含 `structure/hello` 与 import 模块的 `imports: [utils.mq.md]`。
3. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
4. `marqdo sync` 与 `catalog` 行为一致。
3. 模块页 Dependencies 对已解析导入为 Markdown 链接。
4. 若扫描根下有 `.marqdo/agent-kb/concepts/`,则复制进 `OUT_DIR/concepts/` 且 `index.md` 有 Agent knowledge 条目。
5. 文件头或 `generated` 标明 GENERATED;文档声明勿手改。
6. `marqdo sync` 与 `catalog` 行为一致。
+2 -1
View File
@@ -21,7 +21,8 @@
- 以**空行**划分段落。
- 段首行:首字符非标记 → 注释。
- 段内续行:一律注释(即使以 `` ` `` / `-` 等开头)。
- 段内续行:一律注释(即使以 `` ` `` / `-` / `**` 等开头)。
- **例外**:整行仅为 `**expr**`(或 `****`)→ Marqdo **返回**;`**强调**` 后还有文字 → 仍是叙述注释。
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
---
+3 -2
View File
@@ -41,7 +41,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
│
├─① 行分类(自研) 无标记 → 注释;有标记 → 代码行
├─② GFM 块/行内(库) 标题、表、强调、列表结构
├─③ 行扫描补强(自研) 保留 '-' / '+';frontmatter `> file.mq.md`
├─③ 行扫描补强(自研) 保留 '-' / '+';frontmatter `import file:file.mq.md`
└─④ Marqdo 语法(自研) 递归下降:Module/Fun/Stmt/Expr → AST
└─ 表达式子语言 可手写,或仅对 Expr 用 pest/nom
```
@@ -80,7 +80,8 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 |
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
| **clap** | CLI | `marqdo run [path]` |
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`> x.mq.md` 仍按**行**抽取(见 Spike) |
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`import x:x.mq.md` 仍按**行**抽取(见 Spike) |
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
#### 强烈建议
+11 -3
View File
@@ -3,7 +3,7 @@
| | |
|---|---|
| 状态 | 已定 |
| 日期 | 2026-08-04 |
| 日期 | 2026-08-07 |
| 原则 | **夹具即金样例**:`tests/{structure,keywords,errors}/**/*.mq.md` 由 `cargo test` / CI 跑通;`marqdo view tests` 也可浏览 |
---
@@ -26,10 +26,17 @@ tests/
import/
main.mq.md
utils.mq.md
ns/
helpers.mq.md
path3.mq.md
use.mq.md
keywords/ # 关键字与内置名
print.mq.md
bool-logic.mq.md
ext/
agent-run-live.mq.md
errors/ # 期望失败(诊断文案稳定后再加金样例)
ns-instance-method.mq.md
…
```
@@ -42,7 +49,7 @@ tests/
| 类别 | 测什么 | 不测什么 |
|------|--------|----------|
| **structure** | `#`/`##`、形参、`>` 调用、`*`/`**`、`+`/`-`、表、导入、位置/具名实参 | 关键字边角 |
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、点号路径 / `use`、位置/具名实参 | 关键字边角 |
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
@@ -51,7 +58,8 @@ tests/
- **流水线调试**:`--dump-lines` / `--dump-ast` / `--trace-eval`
- **CLI**:默认 `index.mq.md`、退出码
- **view**:目录扫描、单文件页、执行区(见 [view.md](view.md))
- **模块图**:循环导入拒绝
- **模块图**:循环导入拒绝;`errors/ns-instance-method`(实例方法路径)
- **ext live**:`ext/agent-run-live`(需 `.env` + `libagent`)
---
+105
View File
@@ -0,0 +1,105 @@
# Native plugin ABI (v2)
| | |
|---|---|
| Status | Accepted |
| Date | 2026-08-07 |
| Header | [`include/marqdo_abi.h`](../../include/marqdo_abi.h) |
| Related | [ext-agent.md](ext-agent.md) · [stdlib-modules.md](stdlib-modules.md) |
## Goals
- Optional **native** extensions as shared libraries (`.dll` / `.so` / `.dylib`).
- **Not** linked into the `marqdo` binary; load at runtime.
- Stable **C** ABI only (no cross-compiler Rust ABI for plugins).
- Official / local paths only — **no** third-party package registry.
- **v2**: allowlisted `host_query` so plugins can read entry source / call site / skill without baking agent logic into the core.
## Contract
`MARQDO_ABI_VERSION = 2` (host accepts plugins with version `1..=2`).
Every plugin exports:
| Symbol | Role |
|--------|------|
| `marqdo_plugin_abi_version` | `1` or `2` |
| `marqdo_plugin_init` | Register functions via `MarqdoHostApi` |
| `marqdo_plugin_shutdown` | Teardown |
Host provides `register_fn`, `alloc`, `free`, and (v2) `host_query`.
### Wire format
Arguments and results are **UTF-8 JSON**:
- Args: JSON object keyed by parameter names (from `params` CSV at registration).
- Result: any JSON value mappable to Marqdo `Value` (same rules as `lib/json`).
Plugin fn returns `0` + `*out_json` on success; non-zero + optional `*err_msg` on failure. Host frees both strings with the host `free`.
### `host_query` allowlist (v2)
| name | Result JSON | Notes |
|------|-------------|--------|
| `module_source` | string | Entry `.mq.md` text |
| `call_site` | `{path,function,line}` | Active call site |
| `marqdo_skill` | string | Skill pack text |
| `cwd` | string | Host `cwd` (entry file directory) for path resolution |
| `record_plot` | `{ok:true}` | Args `{svg}` + optional `path`; push SVG into host plots (view embed / CLI auto-write), same channel as math plots |
Unknown names fail. Queries are only valid during a plugin function call (host sets thread-local context).
## Marqdo surface (`lib/plugin` / `lib/插件`)
| English | Chinese | Host |
|---------|---------|------|
| `## load` (`path`) | `## 加载` (`路径`) | `host_plugin_load` |
| `## unload` | `## 卸载` | `host_plugin_unload` |
| `## list` | `## 列出` | `host_plugin_list` |
| `## native_path` (`name`) | `## 原生路径` (`名`) | `host_ext_native_path` |
```markdown
---
import plugin:lib/plugin.mq.md
---
# main
> load path=demo.dll
*`sum` = > demo_add a=1 b=2 *
> print text=`sum`
```
After `load`, registered names are callable like other functions (plugin registry lookup after fixed host fns, before user `#`/`##` defs).
**Path sandbox:** `path` resolves under the program’s cwd / `fs_root` (same as `lib/fs`). Absolute paths outside the root are rejected unless trusted (`MARQDO_EXT` / `MARQDO_AGENT_PLUGIN` / built `libagent.*`). Prefer `native_path name=agent` for the official agent plugin.
## Demo / agent
```bash
cargo build -p marqdo_plugin_demo
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`.
## Layering
| Layer | May call `host_*` |
|-------|-------------------|
| `lib/*` | Yes (only L1 wrappers of generic L0.5) |
| `ext/*` | **No** — compose `lib/*` or ABI plugin names via `lib/plugin` |
| Application `.mq.md` | Prefer same as ext; do not add agent/OKF originals to `src/host` |
**Hard rule:** agent / OKF domain primitives live in `plugins/agent`, never in `HostFn` / `src/host/kb.rs`.
## Non-goals
- Embedding plugins in the release exe by default
- Callbacks from plugin into arbitrary Marqdo evaluation
- Arbitrary HostFn passthrough via `host_query`
- **Third-party** plugin / package registry
+150
View File
@@ -0,0 +1,150 @@
# 父智能体 Plan-and-Move(`## plan` 行动面)
| | |
|---|---|
| 状态 | **Accepted** |
| 日期 | 2026-08-11 |
| 父文档 | [ext-agent-plan.md](ext-agent-plan.md) · [ext-agent.md](ext-agent.md) |
| 相关 | [stdlib-subtask.md](stdlib-subtask.md) · [okf.md](okf.md) · [ai-skill.md](ai-skill.md) |
---
## 1. 一句话
**父智能体 = Plan-and-Move 控制器**:观察工作簿与子任务结果 → 规划下一步 → 行动(读 / 调工具 / 补丁 / 再跑 / 停);Marqdo「文档即代码」让工具、记忆与程序都落在 `.mq.md` 上。
---
## 2. 为何需要强化
单靠 `DECISION: DONE|CONTINUE|RUN` 时,父侧几乎没有「手」:
| 缺口 | 后果 |
|------|------|
| 看不到子源码 / 报错 / stdout | 空想 FIND/REPLACE,输出又臭又长 |
| 标准库未进入行动表 | 无法在规划环内用 `fs` / `json` / `subtask` 等 |
| 不能用 Marqdo 造工具 | 无法把可复用步骤沉淀为 `##` |
| 提示词过长且互相打架 | 模型「继续帮忙」而不停机 |
业界对 agent 回环的共识:成功标准、停机动作、**确定性行动面**三者必须写清;停机最终靠代码护栏,不只靠 prompt。
---
## 3. Marqdo 赋予的特性(相对通用 Plan-and-Move)
| 特性 | 含义 |
|------|------|
| 工作簿即程序 | 子执行物是可 `spawn path=` 的 `.mq.md`,不是隐式任务图 |
| 固化即记忆 | `DECISION: DONE` → `agent_workbook_solidify` + OKF 晋升 |
| `lib/*` 即工具 | 标准库是父可调度能力;经父 helper 或写入工作簿/`tools/` 后调用 |
| 补丁即改代码 | `CONTINUE` + 精确 FIND/REPLACE;禁止整文件 LLM 重写 |
| 文档即提示 | 站立提示、Skill 摘要、观察切片都是可读 Markdown,而非黑盒 system blob |
---
## 4. 循环形状(锁定)
```text
┌──────────────┐
│ Plan (LLM) │
└──────┬───────┘
│ 协议回复
┌─────────────┼─────────────┐
▼ ▼ ▼
READ:/CALL: DECISION: (无效 → error)
│ DONE/RUN/
│ CONTINUE
▼ ▼
Act 工具 Move(固化/补丁/spawn)
│ │
└──────┬──────┘
▼
Observe(有界)
│
└──► 回到 Plan 或终止
```
优先级(解析父回复时):
1. **`CALL:<name>` / `调用:`** — 跑父侧工具,结果并入 observation,再 Plan
2. **`READ:<kind>` / `读取:`** — 加深某一观察切片,再 Plan
3. **`DECISION:`** — Move(含运行时 solidify / apply_patch / spawn)
---
## 5. 观察面(有界、可加深)
`inspect_workbook` / `await_workbook` 在磁盘上可持有全文;**注入父 prompt 的默认紧凑观察**必须可行动且短:
| 字段 | 默认 | `READ:` 加深 |
|------|------|----------------|
| `source_excerpt` | 去 `<!-- … -->` 后的结构摘录,硬顶 ~4KiB / ~80 行 | `READ:source` → 更大但仍有硬顶的摘录 |
| `stderr_tail` / `stdout_tail` | 子任务捕获尾部 ~2KiB | `READ:stderr` / `READ:stdout` |
| `value` | ≤200 字;否则 `value_preview` + `value_len` | (一般不必加深) |
| `slots` | `{key,line,body_len}`;`error` 槽可带短预览 | `READ:slots` |
| `skill_brief`(父 / 子) | ~1.2KiB(`skill_brief`) | `READ:skill` → ~4KiB |
| `has_worker_step` / `solidify_on_done` | 布尔提示 | — |
`## step` 同样默认注入 **预算后的** `source_brief` + `skill_brief`(非全文);截断处带 `[truncated …; emit READ:…]` 标记,子轮最多 `max_reads` 次加深后再 CALL/作答。
`quiet=True` **只表示不污染父 TTY**;file `wait` 仍返回截断后的 `stdout` / `stderr` 供父观察。
---
## 6. 工具面
### 6.1 父侧内建 helper(`CALL:` 首批)
写在 `ext/ai/agent.mq.md`,由 plan 循环直接调度(**不用** OpenAI function calling):
| 名称 | 作用 |
|------|------|
| `workbook_read` | 按 depth 读工作簿摘录 |
| `workbook_excerpt` | 结构摘录(默认观察同源) |
| `lib_catalog` | 枚举 `lib/*.mq.md` 能力摘要 |
| `scratch_tool_write` | 写入 `.marqdo/agent-runs/tools/<name>.mq.md` |
| `corpus_search` | 本地语料关键词检索(RAG-lite;`ARGS.query` / `root`) |
| `mcp_list_tools` / `mcp_call` | MCP 形 JSON fixture 列工具 / 调用(离线证据) |
以上 **corpus / mcp** 返回一律带 `authority=workbook`:检索与外置工具只是证据,**可跑的 `.mq.md` 工作簿 / OKF 技能仍是权威真相**。
### 6.2 标准库与造工具
- **标准库直调(白名单)**:`CALL:lib.fs.read_text`(及 `exists` / `list_dir` / `json.parse` / `json.stringify` / `sys.cwd`)+ 可选 `ARGS:{…}` JSON 行;拒绝 `net.*` / `sys.exec` / 写删类。
- **目录**:`lib_catalog` 列出可 CALL 的 dotted 名。
- **造工具**:优先 `CONTINUE` + 短 PATCH 在工作簿内新增 `##`;或 `CALL:scratch_tool_write` 沉淀独立工具文件。
- **流式**:父 CALL/READ 发 `tool_start` / `tool_end`(view Tool 卡)。
- **非目标**:全量 `lib/*` JSON schema 反射;OpenAI function calling。
---
## 7. 输出纪律(停机规则)
父回复**只允许**协议行 + 一行 `SUMMARY` + 短 PATCH(`<20` 行)。禁止长独白 / 行程散文 / 把 observation 粘进 REPLACE。
修订阶段硬规则(自上而下):
1. `exit_code==0` 且 `has_value` → **立刻** `DECISION: DONE`(运行时 solidify);`has_worker_step` **不是** CONTINUE 的理由。
2. 仅失败 / 无值 / 明确未达目标时才 `CONTINUE`。
3. 代码护栏:非 `improve` 时,子已返回值则 **跳过父 LLM**,直接 solidify + DONE。
---
## 8. 与 `## step` 的关系
| | `step`(子) | `plan`(父) |
|---|-------------|-------------|
| 协议 | `CALL:` 或最终答案 | `CALL:` / `READ:` / `DECISION:` |
| 工具来源 | 工作簿 / 调用方 allowlist | 父 helper + 写入的 Marqdo `##` |
| 成功出口 | 返回答案文本 | `DONE` + solidify / promote |
---
## 9. 实现落点
| 组件 | 路径 |
|------|------|
| 设计(本文) | `doc/design/ext-agent-parent.md` |
| 多步总设计增量 | `doc/design/ext-agent-plan.md` §4.1 / 协议 |
| 子任务 I/O | `src/host/subtask.rs`、`lib/subtask.mq.md` |
| 父循环 / 观察 / 提示 | `ext/ai/agent.mq.md` |
+356
View File
@@ -0,0 +1,356 @@
# 智能体多步(`## 多步` / `## plan`)
| | |
|---|---|
| 状态 | **Accepted;D2a–D2f 已落地;父 Plan-and-Move / OKF 软命中见配套文档** |
| 日期 | 2026-08-11 |
| 父文档 | [ext-agent.md](ext-agent.md) |
| 相关 | [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move 行动面**) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [module-namespace.md](module-namespace.md) · [ai-skill.md](ai-skill.md) · [objects.md](objects.md) · [调研:主流框架与 Marqdo](../research/agent-frameworks-and-marqdo.md) |
---
## 1. 动机
单步(`## 单步` / `## step`)适合原子任务。复杂目标需要:
1. **把分解与执行过程落成一份可运行的 `.mq.md`**(工作簿),而不是藏在进程内的任务图。
2. **用子任务真正跑这份工作簿**,与主推理隔离。
3. **父智能体作为「智能体开发大师」**:结构化读取执行结果与写回,再二次规划;用**精确补丁**改工作簿代码,并把确定步骤**固化为普通 Marqdo `##`**。
4. **允许工作簿演化**——代码与 `<!-- marqdo-out … -->` 均可更新,但**禁止**以整文件 LLM 重写作为修订主路径。
5. 子智能体只做不确定的 `单步`;能写成代码的就不要再问模型。
本文锁定 **`## 多步` / `## plan`** 的语义。总览与分层见 [ext-agent.md](ext-agent.md);实现以 D2 为准。
---
## 2. 一句话
**多步 = 父智能体(开发大师)生成并演进一份子 Marqdo 程序:经 `lib/subtask` 运行它,结构化观察写回与源码,再二次规划并精确打补丁;子 `# 智能体` 只跑 `单步`,确定步骤固化为代码。**
---
## 3. 角色与产物
| 角色 | 职责 |
|------|------|
| **父智能体** | 持有目标;创建 / 改写工作簿;`spawn path=` 运行工作簿;读执行结果与写回块;决定改代码还是改提示;汇总并写回父文档 |
| **工作簿 `.mq.md`** | 任务实现的**详细步骤文档兼程序**:导入、工具、一个或多个子智能体、可固化的普通函数与 `# main` 编排 |
| **子智能体** | 工作簿内的 `# 智能体` / `# agent`;走 `单步`(默认);工具表白名单可收窄 |
| **子任务通道** | `lib/subtask`:`spawn path=<工作簿>` → `wait`;与工具 `spawn fn=` 同一套能力 |
| 产物 | 说明 |
|------|------|
| 工作簿路径 | 默认目录 `.marqdo/agent-runs/`(可参数覆盖);文件名含时间 / 短 id |
| 父侧返回值 | 结构化 map:`status`、`goal`、`workbook`(路径)、`result`(子 `# main` 返回值优先)、`summary` / `error`;可选 `observation` |
| 写回 | 工作簿内各 `单步` 默认落盘;父 `多步` 调用行亦可汇总写回 |
---
## 4. 调用流水线(锁定)
```text
父:`助手`.多步 目标=…
▼
① 解析参数(目录、深度、是否确认分解、是否覆盖已有工作簿…)
▼
② 创建(或打开)工作簿 .mq.md
- frontmatter:导入 ext/ai/llm|agent、json、writeback、subtask…
- **大模型配置与父智能体一致**(见 §5)
- 正文:总目标叙述 + 子智能体骨架 / 或父模型生成的首版步骤
▼
③ 父模型「分解」(非 OKF 命中路径必跑):`phase=decompose`,尚未 spawn;可 `DECISION: RUN` / `CONTINUE`+补丁 / 固化后 `DONE`
▼
④ lib/subtask:spawn path=<工作簿绝对或相对路径>
▼
⑤ wait → 收集 `{code, value}`(`# main` 返回)+ 工作簿内写回块;TTY 默认静默
▼
⑥ 父智能体 **结构化观察**(工作簿最新源码 + 写回槽 + 退出码 + `value`)
- 充分 → 汇总,写回父文档,返回
- 不足 / 失败 → **二次规划** → 对工作簿打**精确补丁**(禁止整文件重写)→ 回到 ④
▼
⑦ 触达最大修订轮次或深度 → 以 error / 部分摘要返回
```
要点:
- **创建文件发生在 `多步` 内**,不是调用方手写脚手架(调用方可传已有 `工作簿=` 路径以续跑)。
- **执行工作簿 = 子任务跑整文件**(入口 `# main`),不是父进程内嵌解释子 AST。
- **父是智能体开发大师**:读真实执行结果再规划;修订靠精确补丁与代码固化,不靠整文件重生。
- **修订循环属于父智能体职责**:同一 `多步` 调用内可多轮「观察 → 规划 → 补丁 → 再 spawn」。
---
## 4.1 观察面与补丁(锁定)
父每次二次规划前必须拿到观察 map(`inspect_workbook` / `await_workbook`)。磁盘可持全文;**注入父 LLM 的默认观察为有界紧凑面**(摘录 + I/O 尾部)。完整语义与 `READ:` / `CALL:` 行动面见 [ext-agent-parent.md](ext-agent-parent.md)。
| 字段 | 含义 |
|------|------|
| `path` | 工作簿路径 |
| `source` | 最新全文(磁盘);prompt 默认用 `source_excerpt` |
| `exit_code` | 上一轮子任务退出码 |
| `value` | 子 `# main` 返回值(经 `await_workbook` / `wait.value`) |
| `stdout` / `stderr` | 子任务捕获(`quiet` 仅静音 TTY,不丢弃数据) |
| `slots` | 命名写回列表(`key` + `body`) |
| `last_ok` / `last_error` | 便捷字段 |
二次规划输出协议(机器可解析;**禁止**只输出整份 `.mq.md`;**禁止**长独白):
```text
CALL:<parent-tool>
READ:source|stderr|stdout|slots
DECISION: DONE
SUMMARY: <一行>
DECISION: RUN
DECISION: CONTINUE
PATCH:
<<<
FIND
<确切旧片段>
===
REPLACE
<新片段>
>>>
```
解析优先级:`CALL` → `READ` → `DECISION`。应用器对文件做**精确** FIND→REPLACE;找不到则报错。`DONE` 时运行时 `agent_workbook_solidify` 固化答案(不必靠长 REPLACE 粘贴子散文)。
---
## 4.2 多轮哲学:仅子智能体接力(模式 C)
复杂 / 多轮目标 = **多份可执行 `.mq.md` 接力**,经 OKF 索引与复用;父 `plan` 聚合各子 `wait.value` 为 `result`。
| 做 | 不做 |
|----|------|
| 每主题 / 子目标一份工作簿(`resources/` / `explore/`) | 单文件无限追加「对话日志」 |
| OKF task/skill 做索引与命中 | 单文件状态机表冒充流程 UI |
| `# main` **返回**答案;`quiet` 只管 TTY | 依赖子 `print` 把答案刷到父终端 |
---
## 5. 大模型配置与父保持一致
工作簿内构造子智能体时:
| 从父继承 | 说明 |
|----------|------|
| `model` / `大模型` 句柄字段 | `api_key`、`base_url`、`model`、`suffix`、`bearer` 及拼装前缀等与父相同 |
| 默认站立提示基调 | 可追加「只负责本工作簿内子任务」等收窄句;不得更换供应商端点 |
实现约定(D2):
1. 父把当前 llm 句柄 **序列化进工作簿**(例如构造段直接写 `> llm.llm` 前先 `load_env`,或写入由父生成的配置表 / 环境约定)。
2. 优先:**工作簿与父共享同一套 `OPENAI_*` / `.env` 加载路径**,子文件内 `> llm.load_env` + `> llm.llm`(或中文面),避免把密钥明文写进工作簿。
3. 若父句柄来自非默认 env,父须在生成工作簿时写出等价构造(仍禁止把密钥写进 git 跟踪路径;工作簿目录应默认被 ignore)。
**禁止**:子工作簿默默改用另一 `base_url` / 另一模型名,除非调用方显式参数允许覆盖(v1 不提供覆盖;一律继承)。
---
## 6. 工作簿内容形态
### 6.1 推荐:多个子智能体
面对多种情形时,**多个 `# 智能体`(或一个类型多次构造)** 优于单一巨型提示:
```markdown
---
title: agent-run-…
import llm:ext/ai/llm.mq.md
import agent:ext/ai/agent.mq.md
import json:lib/json.mq.md
import writeback:lib/writeback.mq.md
import subtask:lib/subtask.mq.md
---
# 总目标
(父写入的目标叙述)
## 工具甲
…
# main
> llm.load_env path=…
*`模型` = > llm.llm *
*`调研` = > agent.agent model=`模型` tools=`表甲` standing=… *
*`撰写` = > agent.agent model=`模型` tools=`表乙` standing=… *
*`a` = > `调研`.step task=… *
*`b` = > `撰写`.step task=… *
```
### 6.2 也可:一个智能体多次单步
适合线性流水线;每次 `step` 仍默认写回,便于中断续跑。
### 6.3 固化为代码(强烈推荐)
一旦某步输入输出稳定(例如「取今日日期」「解析固定 JSON」),父智能体应把该步 **改写成普通 `##` 函数 + 直接调用**,不再经子智能体推理:
| 不确定 | 已确定 |
|--------|--------|
| `` > `子`.step task=… `` | `` *`x` = > 本地函数 … `` |
| 宽工具表 + 长 standing | 窄函数、表驱动、分支 `1.` / `2.` |
**多步的价值之一就是把「试出来的正确步骤」沉淀成工作簿里的代码**,而不仅是 chat 痕迹。
### 6.4 持续更新的两类内容
| 更新 | 含义 |
|------|------|
| **代码更新** | 增删 `##`、改 `# main` 编排、改工具表、把 step 换成固化调用、修分支 |
| **写回注释更新** | `<!-- marqdo-out ok|error -->` 被单步 / 父汇总刷新;替换时**不得累积空行**(见 writeback 实现约定) |
工作簿是活文档:子任务跑完后磁盘上的 `.mq.md` 应比创建时更「像最终报告」。
---
## 7. 单步自动写回(服务多步)
### 7.1 决议
| | |
|---|---|
| **默认** | `单步` / `step` **自动写回** 本步结果(命名槽) |
| **开关** | 参数 `写回` / `writeback`(布尔,默认 `真` / `True`) |
| **槽** | 成功 → `key=ok`;失败 → `key=error`;正文为结构化 map 的 JSON(或与现 live 样例一致的 stringify) |
| **锚点** | 本步调用行(与现 `writeback.record` 锚点规则一致) |
这样:
- 父 / 工作簿**不必**靠提示词强迫模型「请记得写回」。
- 编排方仍可 `写回=假` 拿到纯 map,自行 `writeback.record`(测试、嵌套去重时有用)。
### 7.2 与父写回的分工
| 层级 | 写什么 |
|------|--------|
| 子 `step`(默认开) | 该步 decision / tool / result 或 error |
| 父 `plan` | 工作簿路径、轮次、汇总摘要;可选把关键子 ok 块索引写在父调用行下 |
**推荐**:载荷以子 `# main` 返回值(`wait.value` → `plan.result`)为准;写回作审计与 step 缓存。避免只靠 stdout(默认静默会丢弃)。
### 7.3 返回值
`step` 仍返回结构化 map(与现 D1 一致)。自动写回是**附加副作用**,不取代返回值。
---
## 8. 父智能体上下文(每次修订 / 汇总前)
父在多步循环中每次「想下一步」时,注入不得弱于单步,且额外包含工作簿:
| 片段 | 来源 |
|------|------|
| 站立提示 | 父构造 |
| 总目标 | `多步` 实参 |
| **父文件源码** | `agent_module_source` |
| **调用位置** | `agent_call_site` |
| **Marqdo Skill** | `agent_marqdo_skill` |
| 工作簿全文 / 写回 / 子返回 | `inspect_workbook`(源码 + slots + 退出码 + `value`) |
| 子任务退出码 | `subtask.wait` |
| 对话 / 历史 | 父 session;真相以写回为准 |
父模型输出必须是 **DONE / CONTINUE+精确补丁** 协议(见 §4.1),禁止整文件重写。
---
## 9. 公开 API(D2 契约)
### 9.1 `## 多步` / `## plan`
| 参数 | 中 / 英 | 默认 | 说明 |
|------|---------|------|------|
| 目标 | `目标` / `goal` | 必填 | 复杂任务描述 |
| 工作簿目录 | `工作簿目录` / `workbook_dir` | `.marqdo/agent-runs` | 新建文件所在目录 |
| 工作簿 | `工作簿` / `workbook` | 空 | 若给路径则**续跑 / 修订**该文件,跳过空白创建 |
| 最大深度 | `最大深度` / `max_depth` | `2` | 工作簿内再调 `多步` 的嵌套上限;叶强制单步 |
| 最大轮次 | `最大轮次` / `max_rounds` | 实现选定(如 `4`) | 父「改文件 → 再执行」循环上限 |
| 确认分解 | `确认分解` / `confirm` | `假` | `真` 时首版工作簿生成后暂停(返回 pending + 路径),不自动 spawn |
| 写回 | `写回` / `writeback` | `真` | 父侧汇总写回 |
| 骨架 | `骨架` / `skeleton` | `single` | `single` 单 worker;`dual` 为 research→writer 两子智能体 |
返回 map(字段名英文字段,中文面可读同一结构):
| 字段 | 含义 |
|------|------|
| `status` | `ok` / `error` / `pending`(待确认) |
| `goal` | 回显目标 |
| `workbook` | 工作簿路径 |
| `rounds` | 实际执行轮次 |
| `summary` | 成功时的汇总 |
| `error` | 失败信息 |
### 9.2 `## 单步` / `## step`(修订)
在 D1 参数上增加:
| 参数 | 默认 | 说明 |
|------|------|------|
| `写回` / `writeback` | `真` | 是否自动 `record` 到 ok/error 槽 |
### 9.3 内部辅助(非稳定对外)
工作簿模板渲染、从父句柄生成子文件 frontmatter、解析子写回摘要等——可随实现调整。
---
## 10. 安全与边界
| 风险 | 对策 |
|------|------|
| 无限修订 / 嵌套 | `最大轮次`、`最大深度`;叶任务禁止再 `plan` |
| 工作簿写爆仓库 | 默认目录 `.marqdo/agent-runs/` + gitignore;禁止默认写到 `lib/` / `ext/` |
| 密钥进工作簿 | 继承 env / load_dotenv,不写明文 key |
| 子文件乱改父仓 | 子任务 cwd / fs_root 落到工作簿目录;工具表白名单 |
| 写回空行膨胀 | 替换跨度含 `-->` 行尾换行(已实现) |
| 并发写同一工作簿 | writeback 全局锁;同一 plan 内串行 spawn 为 v1 默认 |
---
## 11. 与旧 §3.2 叙述的差异(显式)
| 旧粗述 | 本文锁定 |
|--------|----------|
| 分解表 + 每行一个子智能体实例 | **整文件工作簿**可含多智能体与固化代码;表只是可选骨架 |
| 子任务默认单步,写回在流水线步骤里点到为止 | **单步默认自动写回**;父负责修订循环与汇总 |
| 缓存命中略写 | **以 OKF 任务知识包为准**([okf.md §7](okf.md)):Task→Skill→resource 命中则跳过父模型;D2 + O2 已落地;人读目录见 O3 `marqdo catalog` |
| 父上下文未强调工作簿全文 | 父每次修订前必须能读**最新工作簿 + 写回** |
---
## 12. 实现路线(D2)
| 项 | 内容 |
|----|------|
| D2a | `step` 增加 `writeback=`(默认真);金样例改默认行为并保留 `writeback=False` 测例 | **done** |
| D2b | 工作簿模板 + 创建路径 + 父 llm 继承;`inspect_workbook` 观察面 | **done** |
| D2c | `plan`:生成 → `spawn path` → wait → **观察** → 返回;`confirm` | **done** |
| D2d | 二次规划 + **精确补丁**循环(`max_rounds`);禁止整文件重写 | **done**(主路径) |
| D2e | 多子智能体模板与固化提示 | **done**(`skeleton=dual` + Solidify 段 + 父规划优先级) |
| D2f | 离线骨架金样例 + 可选 live 多步 | **done**(decision 离线 + `agent-plan-live`) |
---
## 13. 决议摘要
1. **`多步` 自动创建(或续跑)工作簿 `.mq.md`**,内容为任务的详细可执行步骤。
2. **子文件大模型配置与父一致**(共享 env / 等价句柄;v1 无静默换模)。
3. **经 `lib/subtask` 启动该文件**;可多轮执行。
4. **工作簿内推荐多个智能体**;也允许单智能体多 `step`;**确定步骤固化为代码**。
5. **工作簿持续更新**:代码 + `marqdo-out`。
6. **`单步` 默认自动写回**(`写回=` 可关);父维护汇总写回。
7. **父具备源码、Skill、位置、历史与工作簿观察面**,二次规划后以**精确补丁**修改再执行(禁止整文件重写主路径)。
---
## 14. 一句话
**多步不是更长的聊天,而是父智能体编写、运行、修订一份子 Marqdo 程序——程序里的智能体可多可少,写回默认打开,能写成代码的就不要再问模型。**
+349
View File
@@ -0,0 +1,349 @@
# Official agent development framework (`ext/ai/agent`)
| | |
|---|---|
| Status | **Accepted · redesign**(取代「thin TOOL: loop」方案) |
| Date | 2026-08-07 |
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [**调研:主流框架与 Marqdo 优势**](../research/agent-frameworks-and-marqdo.md) · [**缺口:A0–A4 之后**](../research/agent-framework-gaps-after-a4.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md) · [markdown-mapping.md](markdown-mapping.md) |
## 0. 为什么要改掉旧方案
旧版把智能体做成「黑盒对话循环」:隐藏提示拼装、`TOOL:<name>` 协议、host 历史袋、一次(或几次)模型往返。这是对 LangChain 类框架的平移,**背离了 Marqdo 的初衷**。
Marqdo 的宪法是 **代码即文档、文档即知识库**:
| 旧方案的问题 | Marqdo 应有的形态 |
|--------------|-------------------|
| 提示词藏在框架字符串里,与编排源码分离 | 提示、工具、任务、结果都在 `.mq.md` 里,人与模型同读同写 |
| 执行过程是不透明的 chat transcript | 思考与行动写回文档;`view` / `debug` 可跟可审 |
| 复杂任务与简单任务同一套循环 | **单步**与**多步(工作簿)**两级模型 |
| 成功经验留在进程内存 | **自写回**做成果缓存与失败知识;同类任务可复用 |
本文件锁定新方向。仓库里现有的 `ext/ai/agent.mq.md` / `智能体.mq.md`(TOOL: 薄循环)视为 **待替换实现**,以本文为准。
---
## 1. 我们在建什么
一个 **文档驱动的智能体开发框架**:编排本身就是可读的 `.mq.md`;模型吃的是这份文档与调用位置;写回让思考过程可控、可调试、可沉淀。
**不是** 外挂任务队列、**不是** 官方捆绑领域工具、**不是** 第二套聊天栈(模型 I/O 仍用 `ext/ai/llm`)。
| 在范围内 | 在范围外(应用 / runbook) |
|----------|---------------------------|
| `# 智能体` / `# agent` 构造 | 领域工具:`## 查天气`、`## 分配任务` … |
| `## 单步` / `## step` | 业务表格、队列、工单流程 |
| `## 多步` / `## plan`(生成并驱动工作簿) | 具体分解策略模板库(可放用户仓) |
| 上下文:源码、调用位置、工作簿路径、Skill | 第二套 HTTP / 聊天协议 |
| 与 `lib/writeback`、**`lib/subtask`(工具执行通道)**、**`lib/plugin` + ABI v2 `plugins/agent`** 协作 | 把领域技能塞进官方 `ext/ai/`;在 `ext` 内直调 `host_*` |
---
## 2. 核心理念:编排可读,过程可写回
1. **提示词与代码不分离**
站立提示、工具表、任务叙述都写在 `.mq.md` 里。框架把**当前模块源码**与**调用位置**交给模型,而不是另起一套 system prompt 黑盒。
2. **把 Marqdo 源码交给智能体**
每次推理可注入:入口 / 工作簿 `.mq.md` 全文(或相关切片)、`host_call_site`(路径、函数、行)、`skills/marqdo`(写 / 读 `.mq.md` 的语法纪律)。模型输出应优先是 **可解释的决策** 与 **对文档的结构化改动意图**,而不是私有 JSON 协议。
3. **自写回 = 思考轨迹 + 成果缓存**
成功或失败都写回文档(见 [stdlib-writeback.md](stdlib-writeback.md))。成功块可被后续同类任务命中,避免重复失败;失败块成为可读的「避坑记录」。`marqdo view` 在语句下展示 output-card,调试面可对齐同一份真相。
4. **相对其他框架的优势**
无需外挂向量库 / 状态机才能「记住」某次子任务已成功:记忆就是仓库里的 Markdown。审计、合规、复盘 = `git log` + 打开工作簿。
---
## 3. 两级执行模型
### 3.1 模式 A — 单步(原子任务)
| | |
|---|---|
| **输入** | 小任务描述 + 必要上下文(工具表、站立提示、源码切片) |
| **过程** | 一次(或有限次)推理;可选调用 **runbook 内** 的工具函数;结果写回 |
| **输出** | 原子结果(文本 / 表 / 句柄字段) |
| **适用** | 问答、单一工具、确定性一步 |
公开方法(中 / 英):`## 单步` / `## step`。
示意(语法外形;实现以落地代码为准):
```markdown
---
导入 智能体:ext/ai/智能体.mq.md
导入 大模型:ext/ai/大模型.mq.md
导入 自写回:lib/自写回.mq.md
导入 时间:lib/时间.mq.md
---
## 获取时间
*`u` = > 时间.此刻秒 *
**> 时间.格式化 秒=`u` 格式=%Y-%m-%d**
# main
*`模型` = > 大模型.大模型 *
`工具表` =
| 工具 |
|------|
| 获取时间 |
*`助手` = > 智能体 大模型=`模型` 工具=`工具表` 站立提示=你是可调试的 Marqdo 助手。 *
*`结果` = > `助手`.单步 任务=今天日期是什么?请在需要时调用工具。 *
> 打印 内容=`结果`
```
单步约定:
- 模型看到的上下文 **包含本文件源码与调用位置**,因此「有哪些 `##` 工具」对模型是可见的;行动约定写在提示里(人可读),例如单独一行 `CALL:<工具名>` / `调用:<工具名>`,最终答案则直接正文回复。
- 工具仍是 **runbook 里的 `##` 函数**(v1 以零参为主;可经 `args=` 扩展)。
- **调用工具走 [`lib/subtask`](stdlib-subtask.md)**:白名单校验通过后 `spawn fn=<名>`(中文面 `启动 函数=`)→ `wait` / `等待`,而不是进程内直接 `call_fn`。这样工具与主推理隔离在子任务语义下,并可与并行、超时、探测同一套主机能力对齐。
- 结束后用自写回记录:任务摘要、选用工具、结果或错误。
### 3.2 模式 B — 多步 / 复杂执行(工作簿)
> **完整锁定设计**见 [**ext-agent-plan.md**](ext-agent-plan.md)。以下为摘要。
| | |
|---|---|
| **输入** | 复杂目标 |
| **过程** | 父智能体**创建(或续跑)工作簿** →(非命中)**父先分解** → **`lib/subtask` spawn** 跑子文件 → 观察写回 → **父修订补丁后再执行**(有轮次上限) |
| **输出** | 汇总 map(含 `result`)+ 磁盘上的工作簿(代码与 `marqdo-out` 均可演化) |
| **适用** | 需分解、多情形、可固化步骤、可复用子成果的任务 |
公开方法:`## 多步` / `## plan`。
流水线要点:
1. **创建工作簿** — 默认 `.marqdo/agent-runs/`;内容为任务的详细可执行步骤(导入、工具、`# main`、子智能体)。
2. **模型配置继承父智能体** — 共享 env / 等价 llm 句柄;v1 不静默换模。
3. **子任务执行整文件** — 不是父进程内嵌解释。
4. **工作簿内推荐多个 `# 智能体`**;也允许一个智能体多次 `单步`;**已确定步骤应固化为返回答案的普通代码**(多轮 = 多文件接力 + OKF,见 [ext-agent-plan.md §4.2](ext-agent-plan.md))。
5. **持续更新** — 代码修订 + 写回注释刷新(替换不累积空行)。
6. **`单步` 默认自动写回**(`写回=` / `writeback=` 可关),父侧再汇总写回。
7. **父上下文** — 与单步同级的源码 / Skill / 调用位置 / 历史,外加工作簿全文与子写回。
示意:
```markdown
*`报告` = > `编排`.多步 目标=调研并汇总三篇资料的要点 *
> 打印 内容=`报告`
```
工作簿概念形状与修订循环细节 → [ext-agent-plan.md](ext-agent-plan.md)。
## 4. 分层与仓库布局
```text
ext/
ai/
llm.mq.md / 大模型.mq.md # 模型 I/O
agent.mq.md / 智能体.mq.md # 本框架(按本文重写)
```
| 层 | 职责 |
|----|------|
| **应用 runbook** | 领域 `##` 工具、任务表、是否人工确认分解 |
| **`ext/ai/agent`** | 单步 / 多步、工作簿生成、子智能体编排、写回约定 |
| **`ext/ai/llm`** | 补全 / 聊天 |
| **`lib/writeback`** | 持久化输出块 |
| **`lib/subtask`** | **工具调用与(多步时)子智能体并行的执行通道**;见 [stdlib-subtask.md](stdlib-subtask.md) |
安装:[`ext-cli.md`](ext-cli.md) — `marqdo ext add agent` / `add llm`(`.mq.md` + `native/libagent.so`)。导入:`导入 智能体:ext/ai/智能体.mq.md`。
**原生插件(ABI v2)**:`ext/ai/agent` 经 `lib/plugin` 加载;优先 `> plugin.native_path name=agent`,否则按序查找:
1. `MARQDO_AGENT_PLUGIN`(显式 `.so` / `.dylib` 路径)
2. `CARGO_TARGET_DIR/{debug,release}/libagent.so`(或 `.dylib`)
3. cwd `target/{debug,release}/`
4. 可执行文件旁 `libagent.*` 或 `target/debug/`
5. `MARQDO_EXT/native/libagent.*`(`marqdo ext add agent` 安装)
本地开发须先 `cargo build -p marqdo_plugin_agent`(或 `ext add agent` / 设 `MARQDO_AGENT_PLUGIN`)。详见 [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md)。
**分层纪律(硬规则,勿破)**:
1. `ext/**/*.mq.md` **禁止**出现任何 `host_*` / `host_` 调用。
2. Agent 专属能力(含 OKF agent-kb:`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / …)只进 **`plugins/agent` 注册名**,由 `ext/ai/agent` 在 `plugin.load` 后调用。
3. **禁止**向 `src/host/`(`HostFn` 表)添加 agent / OKF 领域原语,以免核心包体膨胀。通用 L0.5 仅保留 fs/json/subtask 等标准库底层。
4. 进程退出用 `sys.exit` / `系统.退出`,不用裸 `exit`。
官方 `ext/ai/` 用 `lib/*` 包装或插件注册名;见 [module-namespace.md](module-namespace.md) §8 · [ext-abi.md](ext-abi.md)。
---
## 5. 公开 API(目标契约)
| 中文 | 英文 | 角色 |
|------|------|------|
| `# 智能体` | `# agent` | 构造:`大模型`/`model`,`工具`/`tools`,可选 `站立提示`/`standing` |
| `## 单步` | `## step` | 原子执行;注入源码 + 位置;可选工具;返回结构化 map;**默认自动写回**(`写回=` / `writeback=` 可关) |
| `## 多步` | `## plan` | 建/续工作簿 → subtask 跑文件 → 修订循环 → 汇总(见 [ext-agent-plan.md](ext-agent-plan.md)) |
| `## 分解` | `## decompose` |(可公开或内部)目标 → 子任务表 |
| `## 清空历史` | `## clear_history` | 若仍保留会话式辅助状态则清空;**不以隐藏 chat 袋为真相源**——真相在文档写回 |
构造参数(v1):
| 参数 | 说明 |
|------|------|
| `大模型` / `model` | `ext/ai/llm` 句柄 |
| `工具` / `tools` | 工具名表(单列文本,或多列且含 `工具`/`tools`/`name`) |
| `站立提示` / `standing` | 写在文档里的常驻说明(可空) |
`## 单步` 参数:`任务` / `task`;可选 `写回` / `writeback`(默认真)、深度、是否强制不用缓存等。
`## 多步` 参数:`目标` / `goal`;可选 `工作簿目录`、`工作簿`(续跑路径)、`最大深度`、`最大轮次`、`确认分解` —— 详见 [ext-agent-plan.md §9](ext-agent-plan.md)。
模块内辅助函数(组装上下文、解析模型回复、匹配写回缓存)**不是**稳定对外契约,可随实现调整。
---
## 6. 工具表与子任务调用
工具 **不是** 框架内置能力。在 runbook 定义 `##`,再用表登记名称:
```markdown
`工具表` =
| 工具 |
|------|
| 获取时间 |
| 读取摘要 |
```
- 单列表 → 名称列表。
- 多列表 → 从列 `工具` / `tools` / `name` 取名。
- 名称须对应当前模块(或导入可见)的 `##`。
- **不要** 用 `parse text=["fn"]` 列工具(未加引号的标识符会被当成调用)。
### 6.1 调用路径(锁定)
```text
模型回复含 CALL:<名> / 调用:<名>
▼
host_tool_allowed(工具表白名单)
▼
lib/subtask:spawn fn=<名> → wait
▼
工具返回值写回上下文 / 自写回
```
| | |
|---|---|
| 英文面 | `> spawn fn=`名`` → `> wait id=`…`` |
| 中文面 | `> 启动 函数=`名`` → `> 等待 id=`…`` |
| 可选 | `args=` / `参数=` 传给带形参的工具;多工具并行时多次 `spawn` 再 `wait_all` / `等待全部` |
**非目标:** 以裸 `call_fn` 作为框架默认工具通道(应用仍可直接 `call_fn`,但官方智能体走子任务库)。
领域逻辑永远留在应用文件,不进官方 `ext/ai/`。
---
## 7. 上下文注入(每次单步 / 子步)
必须可注入(实现可切片,但不得默默丢掉「代码即文档」):
| 片段 | 来源 |
|------|------|
| 站立提示 | 构造参数 / 文档正文 |
| 任务 / 目标 | 方法实参 |
| 工具表(人可读) | 构造参数 |
| **当前 `.mq.md` 源码** | 插件 `agent_module_source`(经 ABI v2 `host_query`) |
| **调用位置** | 插件 `agent_call_site` |
| **Marqdo skill** | 插件 `agent_marqdo_skill` |
| Marqdo Skill | `skills/marqdo/`(`MARQDO_SKILL` 可覆盖) |
| 相关写回块 | `lib/writeback` 的 `get` / `list` |
禁止:把整份 Skill + 全文源码藏进不可审查的二进制提示且不在文档中留迹。框架拼装的提示应能在调试时落盘或写回(至少摘要)。
---
## 8. 自写回与缓存语义
依赖 [stdlib-writeback.md](stdlib-writeback.md):`record` / `写回` → `<!-- marqdo-out … -->`。
### 8.1 单步返回值与默认写回
`单步` / `step` 返回结构化 map,并在 **`写回` / `writeback` 默认真** 时自动 `record` 到命名槽(成功 `ok` / 失败 `error`)。关闭写回则行为与早期「纯返回值」一致,由编排方自行 `writeback.record`。
| 字段 | 何时 | 含义 |
|------|------|------|
| `status` | 总是 | `ok` / `error` |
| `task` | 总是 | 本步任务 |
| `decision` | 总是 | 模型首轮输出(含 CALL 行等) |
| `tool` / `tool_result` | 成功且调了工具 | 工具名与子任务返回 |
| `result` | 成功 | 最终答复 |
| `error` | 失败 | 错误信息 |
```markdown
*`out` = > `助手`.step task=… *
*`回复` = > json.get value=`out` key=result *
# 默认已写回;若 writeback=False 则需自行 record:
# > writeback.record value=`body` key=ok
```
命名槽 `ok` / `error` 互不覆盖;锚点为调用行。多步工作簿内依赖此默认写回,避免靠提示词强制落盘 —— 见 [ext-agent-plan.md §7](ext-agent-plan.md)。
**命中规则(后续缓存)**:读 `key=ok` 且非占位时可复用。失败知识读 `key=error`。
用户可 `clear key=ok` / `clear key=error` 强制重跑。
复杂执行中,子结果写回优先落在 **工作簿** 文件;父 `多步` 维护汇总写回。
### 8.2 Live 金样例
[`tests/ext/agent-run-live.mq.md`](../../tests/ext/agent-run-live.mq.md):`agent.step`(**默认写回** `ok`/`error`)+ 子任务工具。凭证:`tests/ext/.env`;`> llm.load_env path=.env` 相对**源文件目录**。需已构建 agent 原生库(见 §4)。
---
## 9. 安全与边界
| 风险 | 对策 |
|------|------|
| 无限多步递归 | `最大深度`(默认小,如 2);叶任务强制单步 |
| 工具越权 | 仅工具表白名单;子智能体可传更窄的表 |
| 工作簿爆炸 | 统一目录、命名含时间 / id;可选总超时 |
| 缓存过期 | 签名 + 时间戳;手动清块 |
| 模型乱改仓库 | 写回 API 约束写入形态;多步生成文件限于工作簿目录 |
---
## 10. 相对旧 API 的迁移
| 旧(废弃方向) | 新 |
|----------------|----|
| 唯一的 `## 执行` / `## run` + 隐藏 TOOL: 循环 | `## 单步` / `## 多步` |
| host 历史袋为真相 | 文档写回 + 工作簿为真相;历史袋至多辅助 |
| 提示全在框架字符串 | 站立提示与任务在 `.mq.md`;源码注入 |
| `tests/ext/agent-smoke` 测 TOOL 上下文拼接 | 重写为单步离线 / 写回 / 工作簿骨架测试 |
兼容:可短期保留 `## 执行` 作为 `## 单步` 的别名,但文档与金样例迁到新名后删除别名。
---
## 11. 实现路线(文档锁定后)
| 阶段 | 内容 | 状态 |
|------|------|------|
| D0 | 本文 Accepted;废弃 thin TOOL 设计叙述 | **本文件** |
| D1 | 重写 `ext/ai/agent.mq.md` / `智能体.mq.md`:`单步` + 源码/位置注入 + **子任务调工具** + **结构化返回值**;运行时经 **ABI v2 agent 插件**(禁 ext 直调 host) | **done** |
| D2 | `多步`:按 [ext-agent-plan.md](ext-agent-plan.md)(观察→精确补丁;禁止整文件重写);**D2a–D2f 主路径已落地** | **done** |
| D3 | 金样例:离线单步 / 写回;**live 单步**(`tests/ext/agent-run-live.mq.md`);多步骨架(可不打网) | **live done** |
| D4 | `view` / `debug` 对工作簿与写回块的导航体验 | done(workbook 链到 `/file?path=`;写回槽 `ok`/`error`/`trace` 徽章 + `#wb-{line}`;plan 结果卡) |
| O2 | OKF 任务知识包:`plan` reuse/promote([okf.md §7](okf.md)) | **done** |
### 非目标
- 在官方 `ext/ai/` 捆绑领域工具或工单技能
- 在 `ext/` 根目录摊平 `.mq.md`
- 平行再造一套 LLM HTTP 栈
- 以不可读的私有二进制协议作为编排主界面
---
## 12. 一句话
**智能体框架必须让编排看起来像文档、跑起来像程序、留痕像知识库。**
单步解决原子问题(默认写回);多步让父智能体编写并修订子 Marqdo 工作簿、经子任务执行、把确定步骤固化为代码——详见 [ext-agent-plan.md](ext-agent-plan.md)。
流式:`## step` / `## plan` 支持 `stream=True` / `echo=True`(SSE 增量;返回 map 不变;`plan` 另附 `events`,可选 `trace` 写回)。非命中时先流式父分解再 spawn 子任务。见 [agent-streaming.md](../roadmap/agent-streaming.md)。
+72
View File
@@ -0,0 +1,72 @@
# Official extension installer (`marqdo ext`)
| | |
|---|---|
| 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) |
## Commands
```text
marqdo ext list
marqdo ext add llm
marqdo ext add agent
marqdo ext remove llm
marqdo ext remove agent
```
## Install root
1. `MARQDO_EXT` if set
2. Else `~/.marqdo/ext`
Imports use paths like `import llm:ext/ai/llm.mq.md` (see [`load.rs`](../../src/load.rs)).
## Source for `add`
1. `MARQDO_EXT_SOURCE` — directory containing `ai/llm.mq.md` …
2. Else repo `./ext` near cwd / binary
## 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
```
Future optional ext domains get their own subdirs (e.g. `ext/web/`, `ext/quantum/`), not mixed into `ai/`.
## 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) |
`add agent` copies the built native plugin into `MARQDO_EXT/native/`. Build it first:
```bash
cargo build -p marqdo_plugin_agent
marqdo ext add agent
```
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/`.
## 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`).
## Non-goals
- Third-party registry
- Merging into `lib/`
- Bundling domain/task helpers in official ext
+85
View File
@@ -0,0 +1,85 @@
# Official extensions (`ext/`) — LLM
| | |
|---|---|
| Status | Accepted (v0.1.x) |
| Date | 2026-08-06 |
| Related | [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) |
## Scope
`ext/ai/` holds **official LLM + agent** extensions. Import paths:
```markdown
---
import llm:ext/ai/llm.mq.md
---
```
Resolution: `MARQDO_EXT/ai/…`, repo `ext/ai/…`, cwd `ext/ai/…` (see [ext-cli.md](ext-cli.md)).
Other official ext: [ext-agent.md](ext-agent.md) / [ext-agent-plan.md](ext-agent-plan.md) (**document-driven agent** — step with default writeback / plan workbook; thin `TOOL:` loop superseded). Installer: [ext-cli.md](ext-cli.md). Native plugins: [ext-abi.md](ext-abi.md).
Streaming: `complete stream=True` returns an event list (`reasoning` / `delta` / `done` / `error`); `echo=True` prints thinking (`reasoning_content`) and answer tokens as they arrive. See [agent-streaming.md](../roadmap/agent-streaming.md). Default (`stream=False`) is unchanged (answer string).
**Note:** Prefer `marqdo ext add llm`. Import `import llm:ext/ai/llm.mq.md` from repo or install root.
## Platform prerequisites
| Capability | Surface |
|------------|---------|
| HTTPS + headers | `lib/net` → `http_post` / `headers=` map |
| Dotenv | `## load_env` in ext (or `load_dotenv` / `lib/sys`) |
| JSON quote | `lib/json` → `quote` |
## `ext/ai/llm` / `ext/ai/大模型` (object handles)
| English | Chinese | Role |
|---------|---------|------|
| `## load_env` | `## 加载环境` | Free function: load `.env` |
| `## stream_result` | `## 流式结果` | Collapse event list → final text |
| `# llm` | `# 大模型` | Object ctor → handle map |
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Methods; optional `stream` / `流式`, `echo` / `打印增量` |
```markdown
---
import llm:ext/ai/llm.mq.md
---
# main
> load_env
*`model` = > llm *
*`reply` = > `model`.complete prompt=Say hi in one word *
> print text=`reply`
*`events` = > `model`.complete prompt=Say hi stream=True *
- [`ev`](`events`)
*`t` = > json.get value=`ev` key=type *
1. `t` == "delta"
*`chunk` = > json.get value=`ev` key=text *
> print text=`chunk`
2. *
*`_` = 1*
```
Environment (create a **project-local** `.env`; do not commit secrets):
```env
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
```
Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`.
## Tests
- Import smoke: `tests/ext/llm-import.mq.md`
- Offline stream: `tests/ext/llm-stream-offline.mq.md` + `tests/lib/net-openai-sse.mq.md`
- Live complete (local): `tests/ext/llm-complete.mq.md` + `tests/ext/.env`
- Live agent `## step`: `tests/ext/agent-run-live.mq.md` (DeepSeek; gold: `ext_agent_run_live`)
- Agent smoke (real `llm` handle): `tests/ext/agent-smoke.mq.md` (gold: `ext_agent_framework_smoke`)
- Live complete: `tests/ext/llm-complete.mq.md` (gold: `ext_llm_complete_live`)
+49
View File
@@ -0,0 +1,49 @@
# `ext/quantum` — 自定义酉门(公式矩阵 → 可施加)
| | |
|---|---|
| 状态 | **Accepted · 已落地** |
| 日期 | 2026-08-12 |
| 父设计 | [ext-quantum.md](ext-quantum.md) |
---
## 1. 目标
作者用 `$$…$$`(或嵌套 list)写出酉矩阵 → `quantum.gate matrix=…` 得到可复用门句柄 → `` `qc`.apply gate=… qubits=… `` 施加到电路。
---
## 2. 公式矩阵
`$$` 围栏若含 `[[…]]` 或 `\begin{pmatrix}` / `\begin{bmatrix}`,在**解析期**求值为嵌套数值 list(非整棵 `Formula` 标量树)。
支持:
- ASCII:`[[1,0],[0,-1]]`、`(1/sqrt(2))*[[1,1],[1,-1]]`
- LaTeX 子集:`\frac{…}{…}`、`\sqrt{…}`、`pmatrix` / `bmatrix`(`&` / `\\`)
复数:list 路径仍可用 `{re,im}` 或 `[re,im]`;公式路径本切片以实矩阵为主。
---
## 3. API
```markdown
*`U` = > quantum.gate matrix=`H_matrix` name=U *
# 或构造参数 matrix=;name 可选(默认 U)
*`qc` = > `qc`.apply gate=`U` qubits=0 *
# qubits= 标量或 list;矩阵维数须为 2^k
```
中文:`量子.门 矩阵=` / `` `qc`.施加 门= 比特= ``。
具名门仍可用 `name=H`;`matrix` / `matches_matrix` / `draw` 对自定义门同样有效。
---
## 4. 验收
- 公式(或 list)定义的 H 与内置 `H` 概率一致
- EN/ZH 金样
+48
View File
@@ -0,0 +1,48 @@
# `ext/quantum` Q5.5 — 振幅阻尼(教学轨迹)
| | |
|---|---|
| 状态 | **Accepted · 已落地** |
| 日期 | 2026-08-12 |
| 父设计 | [ext-quantum.md](ext-quantum.md) · [ext-quantum-q5.md](ext-quantum-q5.md) |
| 路线图 | [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
---
## 1. 目标
在 Q5 的 `bitflip` / `depolarizing` 之外,补一种**耗散**教学噪声:`amplitude_damping`(中文 `振幅阻尼`),仍只影响 `run` 轨迹;`simulate` / `probabilities` 忽略。
**刻意不做:** 完整 Kraus 表 API、任意算符噪声、密度矩阵引擎、相位阻尼完整 Lindblad。
---
## 2. 作者面
```markdown
*`qc` = > `qc`.noise kind=amplitude_damping p=0.1 *
# 中文
*`qc` = > `qc`.噪声 种类=振幅阻尼 概率=0.1 *
```
别名:`amp_damp` / `amplitude-damping`。
---
## 3. 模拟语义
与 Q5 相同:每个改态门后,对涉及比特独立掷骰。
对每个比特,以概率 `p` 施加**跳跃**算符 \(E_1 = |0\rangle\langle 1|\)(只作用该比特),再归一化:
- 若态在该比特上几乎全为 `|0⟩`(范数 ≈ 0),跳跃无效,态不变。
- 否则振幅从 `|…1…⟩` 搬到对应 `|…0…⟩` 并归一化。
金样:`X` 后 `amplitude_damping p=1` → 全部 shot 落在 `|0⟩`。
---
## 4. 验收
- `tests/ext/quantum-amp-damp-smoke.mq.md`(+ 中文对称)
- L1 EN/ZH 文档列出第三种 `kind`
+69
View File
@@ -0,0 +1,69 @@
# `ext/quantum` Q5 — 最小噪声(教学用)
| | |
|---|---|
| 状态 | **Accepted · 最小实现已落地** |
| 日期 | 2026-08-12 |
| 父设计 | [ext-quantum.md](ext-quantum.md) |
| 路线图 | [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
---
## 1. 目标
在 **不** 引入完整开放系统 / 云后端的前提下,让教学文档能写「带噪声的采样」,金样可复现。
**刻意不做(本 Q5 切片):** 任意 Kraus 组、振幅阻尼完整表、>12 qubits 张量网络、噪声参数学习。振幅阻尼教学轨迹见 [ext-quantum-q5.5.md](ext-quantum-q5.5.md)。
---
## 2. 作者面
电路上可选噪声字段(方法链设置,返回新句柄):
```markdown
*`qc` = > `qc`.noise kind=bitflip p=0.05 *
# 或
*`qc` = > `qc`.noise kind=depolarizing p=0.02 *
```
| 参数 | 含义 |
|------|------|
| `kind` | `bitflip` \| `depolarizing`(中文:`比特翻转` / `退极化`) |
| `p` | 每比特、每个非 `barrier`/`measure` 门后的错误概率,`0…1` |
`simulate` / `probabilities`:**忽略噪声**(仍为理想酉演化),避免概率图被蒙特卡洛抖动。
`run shots= seed=`:**启用噪声**(若 `p>0`):按轨迹采样,结果可复现。
---
## 3. 模拟语义(轨迹)
每个 shot:
1. 从 `|0…0⟩` 施电路门(跳过 `BARRIER`;`MEASURE` 不改变酉演化)。
2. 每施一个会改态的门后,对**该门涉及的每个比特**独立:
- `bitflip`:以概率 `p` 施 `X`;
- `depolarizing`:以概率 `p` 均匀随机施 `X`/`Y`/`Z` 之一。
3. 若电路含 `MEASURE` 标记:只对标记比特做计算基采样;否则测全部比特。
RNG:与现有 `run seed=` 同一 SplitMix64 流(门后噪声与最终采样共用)。
---
## 4. 与作者面补齐的关系
| API | 行为 |
|-----|------|
| `barrier` | 仅可视化;模拟跳过 |
| `measure` | 可视化测量符号;决定 `run` 读出哪些比特 |
| `append` | 追加另一 `circuit` 的 `ops`(或单门) |
| `state` | 等价于当前理想 `simulate` 结果(`quantum_state`) |
---
## 5. 验收
- 金样:理想 Bell `run` 不变;`noise kind=bitflip p=1` 在已知电路上计数偏离理想(`seed=` 固定)。
- `barrier`/`measure` 出现在 `draw kind=circuit` SVG。
- 中英 L1 对称;仍无 `host_*` 于 `ext/**`。
+230
View File
@@ -0,0 +1,230 @@
# `ext/quantum` Q7 — 高阶线性代数 + 高级可视化
| | |
|---|---|
| 状态 | **Accepted · Q7a/Q7b/Q7c 已落地** |
| 日期 | 2026-08-28 |
| 父设计 | [ext-quantum.md](ext-quantum.md) |
| 路线图 | [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
| 对照 | [IBM Quantum state plots](https://quantum.cloud.ibm.com/docs/en/guides/plot-quantum-states) · [QuTiP visualization](https://qutip.readthedocs.io/en/latest/guide/guide-visualization.html) · Cirq `plot_density_matrix` |
---
## 0. 一句话
在 **Q0–Q6 态向量教学模拟**之上,补齐两块「教科书级」能力:
1. **高阶线性代数**(密度矩阵、Kronecker、部分迹、Hermitian 谱分解、Schmidt / SVD、Pauli 期望值)
2. **高级静态 SVG 展示**(Hinton / City / Pauli 向量 / QSphere 风格 / 多比特布洛赫)
全部经 **`plugins/quantum` ABI**;`ext/quantum/**` 只做 L1 表包装,**禁止** `host_*`。
---
## 1. 动机与业界对照(联网调研 2026-08)
### 1.1 为何现在做
| 已有(Q0–Q6) | 缺口 |
|---------------|------|
| 纯态态向量 + 施门 + 采样 | 混态 / 约化子系统无法一等公民表达 |
| `bloch` 单比特约化 | 纠缠与多比特关联只能猜 |
| `gate.draw kind=matrix` 热力图 | 无密度矩阵 / Pauli 分解 / 球面振幅布局 |
| 内部 `apply_unitary` / Kronecker | **未**暴露为作者面 API |
教学文档写「贝尔态纠缠」时,读者需要:**约化密度矩阵 → 纯度 < 1 → Schmidt 系数 → Hinton/QSphere 图**。这些正是 Qiskit / QuTiP / Cirq 的标配。
### 1.2 可视化对标(只取可静态 SVG 落地的子集)
| 业界 | 含义 | Q7 决策 |
|------|------|---------|
| Qiskit `plot_state_hinton` | 元大小表示幅值,色表示正负 | ✅ `kind=hinton` |
| Qiskit `plot_state_city` | Re/Im 三维条 | ✅ **2.5D 等轴测 SVG**(非 Matplotlib) |
| Qiskit `plot_state_paulivec` | Pauli 串期望值柱 | ✅ `kind=paulivec` |
| Qiskit `plot_state_qsphere` | 振幅点在球面上,色=相位 | ✅ `kind=qsphere`(教学投影) |
| Qiskit `plot_bloch_multivector` | 每比特一球 | ✅ `kind=multibloch` |
| Cirq density Argand 格 | 每元幅值圆 + 相位针 | ✅ 并入 `kind=density`(默认) |
| QuTiP Wigner / 过程层析 | 连续相空间 / χ 矩阵 | ❌ 本切片不做 |
### 1.3 线性代数对标(经典模拟侧,非量子算法)
| 能力 | 教学用途 | Q7 |
|------|----------|-----|
| ρ = \|ψ⟩⟨ψ\| | 纯→密度 | ✅ |
| Kronecker / 张量积 | 复合系统 | ✅ |
| 部分迹 | 约化、纠缠证据 | ✅ |
| Hermitian 本征分解 | 谱 / 测量可观测量 | ✅(小维) |
| Schmidt(纯态二分)= 整形 SVD | 纠缠熵入口 | ✅ |
| Pauli 期望 ⟨P⟩ | 布洛赫 / paulivec 数据源 | ✅ |
| 纯度 Tr(ρ²)、保真度 | 混态度量 | ✅ 最小 |
| 量子奇异值变换 / VQSVD / 云后端 | 算法研究 | ❌ |
---
## 2. 硬约束(沿用 + 本切片追加)
1. **仅 ABI**:新 FFI 全部注册在 `marqdo_plugin_init`;L1 经 `plugin.load`。
2. **`ext/**` 无 `host_*`**。
3. **中英分文件**,禁止混 API。
4. **维数上限**:
- 态向量模拟:仍 ≤ 12 qubits(既有)。
- **密度矩阵稠密运算**(部分迹结果展示、谱分解、Hinton/City):默认 **≤ 6 qubits**(dim ≤ 64);超限显式报错。
5. **无新核心依赖**:插件内手写复数矩阵 + Jacobi / 薄 SVD;**不**捆绑 BLAS / nalgebra(可后续再议)。
6. **view**:仍走 `host_query("record_plot")` + `quantum_svg`;无外链字体/CDN。
---
## 3. 新运行时类型
| `_type`(英) | 中文 | 字段(锁定) |
|---------------|------|----------------|
| `quantum_state` | `量子态` | 既有:`qubits`, `amplitudes:[{re,im}]` |
| `quantum_density` | `密度矩阵` | `qubits`, `dim`, `matrix`(dim×dim 嵌套 `{re,im}`) |
| `quantum_spectrum` | `谱` | `eigenvalues:[f64]`, `eigenvectors`(列向量嵌套 list) |
| `quantum_schmidt` | `施密特` | `coeffs:[f64]`, `ua`, `ub`(局域基),`entropy`(可选) |
| `quantum_svg` | — | 既有;`kind` 扩展见 §5 |
---
## 4. 作者面 API
### 4.1 英文(`ext/quantum/quantum.mq.md`)
在既有 `# circuit` / `# gate` 之外增加(或扩展方法):
```markdown
# density
+ `state`=None # quantum_state 或 circuit(先 simulate)
+ `matrix`=None # 直接给定 ρ
## matrix # → 嵌套 list
## purity # Tr(ρ²)
## expect
+ `obs` # Pauli 串 "ZI" / "XX" 或门矩阵
## partial_trace
+ `keep` # 保留的比特列表(LSB=0)
## eig # Hermitian 谱 → quantum_spectrum
## draw
+ `kind`=hinton # hinton|city|density|paulivec
+ `path`=None
# linop # 自由线性代数(也可挂在 quantum.* 模块函数)
## kron
+ `a`
+ `b` # 矩阵或态 → 张量积
## schmidt
+ `state`
+ `cut`=1 # 前 cut 个比特为 A,其余为 B
## fidelity
+ `a`
+ `b` # 两态或两密度(纯态公式优先)
```
**电路侧便捷方法**(返回新句柄,不改旧对象):
```markdown
## density # simulate 后 ρ=|ψ⟩⟨ψ|
## expect
+ `obs`
## schmidt
+ `cut`=1
## draw
+ `kind`=… # 扩展:hinton|city|density|paulivec|qsphere|multibloch
```
### 4.2 中文对称
| 英文 | 中文 |
|------|------|
| `density` | `密度` |
| `partial_trace` | `部分迹` |
| `purity` | `纯度` |
| `expect` | `期望` |
| `eig` | `本征` |
| `kron` | `张量积` |
| `schmidt` | `施密特` |
| `fidelity` | `保真度` |
| `hinton` / `city` / `paulivec` / `qsphere` / `multibloch` | 同音译或 `欣顿`/`城市`/`泡利向量`/`球`/`多布洛赫`(L1 锁定中英别名表) |
### 4.3 ABI 函数名(稳定英文)
| FFI | 作用 |
|-----|------|
| `quantum_density_from_state` | 态 / 电路 → `quantum_density` |
| `quantum_density_from_matrix` | 校验 Hermitian / 维数 → 句柄 |
| `quantum_density_matrix` | 取出嵌套矩阵 |
| `quantum_density_purity` | Tr(ρ²) |
| `quantum_density_partial_trace` | keep 列表 |
| `quantum_density_eig` | Jacobi Hermitian |
| `quantum_density_expect` | Pauli 串或矩阵 |
| `quantum_density_draw` | hinton/city/density/paulivec |
| `quantum_kron` | 两矩阵或两态振幅 |
| `quantum_schmidt` | 纯态二分 |
| `quantum_fidelity` | 两态 |
| `quantum_draw_circuit` | **扩展** kind 枚举(向后兼容) |
---
## 5. 高级绘图语义
| `kind` | 输入 | SVG 要点 |
|--------|------|----------|
| `hinton` | ρ | 网格方块;边长 ∝ √\|ρᵢⱼ\|;正 Re 浅 / 负深;小 dim 可标数值 |
| `city` | ρ | 等轴测「楼宇」:左 Re、右 Im 两城,或单城双色柱 |
| `density` | ρ | Cirq 风格:每格幅值圆 + 相位线段;对角概率矩形 |
| `paulivec` | 态或 ρ | 全 Pauli 基(n≤3)或用户 `ops=` 列表;柱高 = ⟨P⟩ |
| `qsphere` | 纯态 | 基矢点映射到球/圆;半径∝振幅,色相∝arg;n≤4 推荐 |
| `multibloch` | 纯态 | 每比特约化布洛赫并排 |
既有 `circuit|probs|bloch|gate|matrix` **不变**。
---
## 6. 数值语义(锁定)
| 项 | 规则 |
|----|------|
| 比特序 | **qubit 0 = LSB**(与既有概率标签一致) |
| `partial_trace keep=` | 保留比特升序组成新系统的 LSB…MSB |
| Pauli 串 | 左→右 = **高位→低位** 或文档写死「左=qubit n-1」——**锁定:字符串左端 = 最高比特(qubit n−1)**,与 Qiskit 习惯一致;文档 + 金样双锁 |
| Hermitian 检查 | ‖ρ−ρ†‖_F < 1e-8,否则报错 |
| 谱 | 实特征值降序;特征向量列归一 |
| Schmidt | 将 \|ψ⟩ 整形为 `2^cut × 2^(n-cut)` 复矩阵做薄 SVD;奇异值 = Schmidt 系数 |
| 纯度 | 纯态 ≈ 1;最大混态 = 1/dim |
---
## 7. 分期交付
| 子阶段 | 内容 | 验收 |
|--------|------|------|
| **Q7a** | density / kron / partial_trace / eig / schmidt / expect / purity / fidelity + L1 中英 | `tests/ext/quantum-linalg-smoke.mq.md`(+ zh) |
| **Q7b** | draw kinds:hinton, city, density, paulivec, qsphere, multibloch | `tests/ext/quantum-viz-advanced-smoke.mq.md`(SVG 含关键标记) |
| **Q7c** | 示例页 + 用户站短页 + skill/reference 摘要 | `examples/quantum-entanglement/` 或扩展 bell |
---
## 8. 刻意不做(本 Q7)
- 任意 Kraus / 完整 CPTP 通道库(仍用 Q5 轨迹噪声)
- >6 qubit 稠密 ρ 的谱 / Hinton(请用态向量 API)
- Matplotlib / WebGL / 交互拖拽
- 量子线性系统算法(HHL)、QSVT 电路构造
- 把线性代数并入 `lib/math`
---
## 9. 评审清单
1. 密度矩阵上限 6 qubits 是否可接受?
2. Pauli 串左右端比特约定是否锁定为「左=高比特」?
3. City 用 2.5D SVG 而非真 3D 是否足够?
4. `# density` 独立类 vs 仅 `circuit.density` —— **两者都提供**(类用于给定矩阵;电路方法便捷)?
评审默认:**全部锁定为上文**;实现按 Q7a → Q7b → Q7c。
---
## 10. 一句话
**Q7 让 Marqdo 量子文档能「算清纠缠、画清态」:线性代数在 ABI 里跑,高级图用自绘 SVG 进 view——仍是代码即文档。**
+153
View File
@@ -0,0 +1,153 @@
# `ext/quantum` Q8 — 可视化美学升级(科技感电路图)
| | |
|---|---|
| 状态 | **Accepted · Q8a/Q8b landed · Q8c pending** |
| 日期 | 2026-08-28 |
| 父设计 | [ext-quantum.md](ext-quantum.md) · [ext-quantum-q7.md](ext-quantum-q7.md) |
| 路线图 | [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
| 对照 | [IBM Quantum Composer](https://quantum.cloud.ibm.com/docs/guides/composer) · [Qiskit `iqp` / `iqp-dark`](https://quantum.cloud.ibm.com/docs/api/qiskit/qiskit.visualization.circuit_drawer) · Cirq / Quirk 视觉习惯 |
---
## 0. 一句话
修复 view 内嵌量子 SVG 的**文字–导线粘连**,并把电路 / 概率 / 布洛赫 / 密度类图统一到一套**量子实验室科技感**视觉令牌(深底、门族分色、清晰留白)——仍只输出自包含 SVG,无外链字体/CDN。
---
## 1. 问题诊断(对照用户截图)
| 现象 | 根因(`plugins/quantum/src/draw.rs`) |
|------|----------------------------------------|
| `q0`/`q1` 与导线穿过文字 | 导线从 `x=8` 起画满宽;标签 `x=4` 且基线对齐导线中心 → 线穿字 |
| 「不好看 / 无科技感」 | 单色 `#1a1a1a` + 浅灰盒;无门族色、无背景板、无线宽层次 |
| 门盒贴线、略挤 | `COL_W=56`、盒 28×28、标签栏与第一列无独立 gutter |
| 测量/控点辨识弱 | 与单比特门同色同描边,缺少语义色 |
**不在本切片**:交互拖拽、WebGL、外链字体、第二套 view 皮肤。
---
## 2. 业界对照(联网 2026-08)
| 来源 | 可借鉴点 | 本仓取舍 |
|------|----------|----------|
| **Qiskit `iqp` / `iqp-dark`** | 门族 `displaycolor`(面色+字色);深色底;线色弱于门 | 移植**色板与分类**,不绑 matplotlib |
| **IBM Composer** | 经典门深蓝、相位门浅蓝、非酉灰;导出 light/dark | 默认 **dark tech**(view 卡片上更醒目);可选 `theme=light` |
| **Quirk** | 高对比栅格、测量仪表清晰 | 测量盒保留仪表符号,加强描边/填充对比 |
| **教科书 bw** | 印刷友好 | 保留为 `theme=bw` 后备,非默认 |
**刻意避开**:紫白渐变「AI 默认皮肤」;过重 glow 光晕(打印/浅底卡片会糊)。科技感靠:**深 slate 底 + 青/靛门色 + 清晰层级 + 留白**,而非堆霓虹。
---
## 3. 视觉令牌(锁定 `marqdo-iqp`)
### 3.1 主题
| `theme` | 用途 |
|---------|------|
| `dark`(**默认**) | view / 教学演示科技感 |
| `light` | 浅底文档打印 |
| `bw` | 无彩色、高对比 |
作者面:
```markdown
*`svg` = > `qc`.draw kind="circuit" theme="dark"*
*`svg` = > `qc`.draw kind="probs" theme="light"*
```
| 参数 | 默认 | 说明 |
|------|------|------|
| `kind` | `circuit` | 既有枚举不变 |
| `theme` | `dark` | 新增;非法值报错 |
| `path` | — | 既有 |
中文:`主题=dark|light|bw`。ABI:`quantum_draw_circuit` 增可选 `theme`(circuit/probs/bloch 已生效;gate/density 高级图见 Q8c)。
### 3.2 Dark 色板(默认)
| 令牌 | 色 | 用途 |
|------|-----|------|
| `bg` | `#0a0e14` → `#141c28` 渐变 | SVG 圆角底板 |
| `wire` | `#6b7f96` | 比特线(双层描边) |
| `label` / `chip` | `#e8eef6` / `#1e2a3a` | `q0` 芯片标签(线不穿字) |
| `gate.clifford` | 面 `#4c6fff` / 字 `#f2f6ff` | H、X、Y、CX、SWAP… |
| `gate.phase` | 面 `#2de2e6` / 字 `#042024` | S、T、Rz、CZ… |
| `gate.rotation` | 面 `#3dd6c6` / 字 `#041a18` | Rx、Ry |
| `gate.measure` | 面 `#8fa3b8` / 字 `#0a1018` | MEASURE |
| `barrier` | `#9aafc0` 虚线 | BARRIER |
| `ctrl` | `#f0f5ff` | 控制点 / ⊕ |
Light / bw 在实现里各给一套平行表;金样以 dark 主断言(SVG 含 `data-theme="dark"` 与背景色)。
### 3.3 布局(消灭粘连)
```text
| pad | label_col | gutter | col0 | … | colN | pad |
^q0 芯片标签 ^导线从此开始(不穿过文字)
```
| 常量 | 实现值 |
|------|--------|
| `LABEL_W` | 52 |
| `GUTTER` | 20 |
| `PAD_X` / `PAD_Y` | 24 / 36 |
| `COL_W` | 80 |
| `ROW_H` | 64 |
| 门盒 | 40×40,`rx=8` |
| 线宽 | 导线双层 3.2+1.8;门描边 ~1.1;控制竖线 2.25 |
标签:圆角芯片 + 居中文字;导线 `x1 = PAD_X + LABEL_W + GUTTER`。
### 3.4 门族映射
| 族 | 门名(归一化后) |
|----|------------------|
| clifford | I X Y Z H CX CNOT SWAP |
| phase | S T RZ CZ |
| rotation | RX RY |
| measure | MEASURE M |
| barrier | BARRIER |
| custom / U | clifford 色或中性 `#546e7a` |
---
## 4. 作者面(增量,向后兼容)
见 §3.1。字符串参数须加引号:`kind="circuit"`、`theme="dark"`(中文 `种类=` / `主题=`)。改插件后须 `marqdo ext add quantum` 再开 view,否则仍加载旧 `.so`。
---
## 5. 分期
| 子阶段 | 内容 | 验收 |
|--------|------|------|
| **Q8a** | 电路轨线:布局 gutter + dark/light/bw 令牌 + 门族分色 | 标签不与线相交;SVG 含 `data-theme`;更新 draw smoke |
| **Q8b** | probs / bloch / gate heatmap 共用令牌 | 柱/球/热力与电路同族色 |
| **Q8c** | hinton / city / qsphere / paulivec / multibloch 换肤 | 高级图不「脱节」;viz-advanced smoke 仍绿 |
---
## 6. 实现约束
1. 仅改 `plugins/quantum` 绘图 + L1 透传 `theme`;**不**改 Marqdo 核心。
2. SVG **内联**颜色与字体栈(`ui-sans-serif, system-ui, …`);无 `@import` / CDN。
3. view 仍走 `record_plot`;底板自带圆角矩形,避免白底卡片上「漂浮黑线」。
4. 金样:断言结构标记(`data-theme`、`data-gate-family`)+ 既有 kind;不像素比对。
---
## 7. 非目标
- 复制 Qiskit matplotlib 像素级一致
- 动画 / 3D 电路
- 用户自定义完整 JSON 主题文件(可 Q9)
---
## 8. 一句话
**先把字从线上挪开,再给门族涂上实验室色——默认 dark tech,打印用 light,论文用 bw。**
+408
View File
@@ -0,0 +1,408 @@
# 官方扩展:`ext/quantum` 量子计算模拟
| | |
|---|---|
| 状态 | **Accepted · Q0–Q7 完结 · Q8a/Q8b 完结**([ext-quantum-q7.md](ext-quantum-q7.md) · [ext-quantum-viz-style.md](ext-quantum-viz-style.md);Q8c 高级态图换肤待做) |
| 日期 | 2026-08-12(初版)· 2026-08-28(Q7 · Q8 viz) |
| 相关 | [stdlib-math.md](stdlib-math.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [ext-web.md](ext-web.md) · [view.md](view.md) · [stdlib-i18n.md](stdlib-i18n.md) · [roadmap/ext-quantum.md](../roadmap/ext-quantum.md) |
| 安装(目标) | `marqdo ext add quantum`(中英:`quantum` / `量子`) |
| 本文目的 | 锁定**作者面**、**模拟语义**、**view 可视化**与**分期**;指导 ABI 插件实现 |
---
## 0. 一句话
`ext/quantum` 用 **GFM 表格 + 类方法 +(可选)`$$` 狄拉克/矩阵公式** 描述量子门与电路;**经典状态向量模拟**给出概率与采样。
文档能跑通,公式与电路约定就成立——这是 Marqdo「代码即文档」在量子教学上的最强展示位。
**不改 Marqdo 核心语法**;热路径只在 ABI 插件;**禁止**把量子核链进 `marqdo` 主二进制或在 `ext/**` 里调用 `host_*`。
---
## 1. 为何做量子扩展(与 math 的关系)
### 1.1 与 `lib/math` 的相似处
| math | quantum |
|------|---------|
| `` `f` = `` + `$$…$$` → `formula` | 门矩阵 / 态矢量可用 `$$` **展示与核对** |
| 库函数对公式求值、求导、作图 | 类方法对电路施门、模拟、画图 |
| view 内嵌 SVG;CLI 可 `path=` | view 内嵌**电路图 / 概率条 / 布洛赫**;CLI 可落盘 |
| 金样例失败 = 文档/公式错 | 金样例失败 = 门定义或电路叙述错 |
math 是**高中符号与曲线**;quantum 是**离散希尔伯特空间上的可执行电路文档**。两者都是「写出公式 → 跑通 → 证明文档正确」。
### 1.2 与 math 的刻意分界
| 做 | 不做 |
|----|------|
| 量子在 **`ext/quantum`**,经 `plugin.load` | **不**并进 `lib/math`(避免 stdlib 膨胀) |
| 复数振幅用 `{re, im}` map(与现有 `Value` 兼容) | **不**为量子在核心新增 `Value::Complex`(可二期) |
| 角度可用 `math.pi` 等常量 | **不**在 quantum 插件内重写 CAS |
### 1.3 「代码即文档」在这里的作用
典型教学页:
```markdown
# 贝尔态 |Φ+⟩
对 qubit 0 施 H,再 CNOT(0→1)。理想测量:`00` 与 `11` 各约 1/2。
# main
`steps` =
| 步 | 门 | 比特 |
|----|----|------|
| 1 | H | 0 |
| 2 | CX | 0,1 |
*`qc` = > quantum.circuit qubits=2 steps=`steps` *
*`p` = > `qc`.probabilities *
```
- 叙述与表格是**给人看的电路说明**;
- 同一文件是**可执行程序**;
- gold / CI 断言概率 → **文档与物理约定同步**,无需另维护「幻灯片公式」。
---
## 2. 硬约束(评审锁定)
1. **仅 ABI 插件接入**:`plugins/quantum` → `libquantum.so`;L1 在 `ext/quantum/*.mq.md`。
2. **`ext/quantum/**` 禁止 `host_*`**;经 `plugin.native_path` + `plugin.load`(同 web/agent)。
3. **中英分文件**:`quantum.mq.md` / `量子.mq.md`,**禁止**混排 API([stdlib-i18n.md](stdlib-i18n.md))。
4. **不改核心语法**;电路表单元格保持字面量;门名/比特下标由类方法解析。
5. **模拟器有硬上限**(默认 ≤ 12 qubits);超限报错,不静默截断。
6. **view 必须有专项展示**(结构卡 + 执行区 SVG),禁止只 dump JSON。
---
## 3. 布局与安装
```text
ext/quantum/
quantum.mq.md # 英文类 API
量子.mq.md # 中文类 API
plugins/quantum/
Cargo.toml
src/lib.rs # ABI v2:线性代数 / 施门 / 画 SVG
examples/quantum-bell/ # 规范示例(Q3)
tests/ext/quantum-*.mq.md
```
```bash
cargo build -p marqdo_plugin_quantum
marqdo ext add quantum
```
导入:
```markdown
---
import quantum:ext/quantum/quantum.mq.md
---
```
或中文:`导入 量子:ext/quantum/量子.mq.md`。
---
## 4. 核心模型
### 4.1 运行时句柄(JSON map + `_type`)
| `_type`(英) | 中文类名 | 含义 |
|---------------|----------|------|
| `quantum_gate` | `量子门` | 具名门或自定义酉矩阵 |
| `quantum_circuit` | `量子电路` | n qubits + 有序门列表 |
| `quantum_state` | `量子态` | 状态向量(振幅列表) |
| `quantum_result` | `量子结果` | 概率 / 采样 / 可选坍缩态 |
| `quantum_svg` | (产物) | 带 `svg` 字段的可视化结果 |
插件返回 map;Marqdo 对象系统挂 `_type` 后可用方法链。
### 4.2 状态表示
- **纯态**状态向量:长度 `2^n`,每元 `{re, im}`(f64)。
- 默认初态:`|0…0⟩`(仅 index 0 振幅为 1)。
- 门作用后可选重归一化(阈值误差阈值,默认开)。
### 4.3 公式面(对齐 math 精神,不抢 math 实现)
允许用 `` `G` = `` + `$$…$$` 书写门矩阵(**可执行**,见 [ext-quantum-custom-gate.md](ext-quantum-custom-gate.md)):
````markdown
`H_matrix` =
$$
\frac{1}{\sqrt{2}}\begin{pmatrix}1&1\\1&-1\end{pmatrix}
$$
*`U` = > quantum.gate matrix=`H_matrix` *
*`qc` = > `qc`.apply gate=`U` qubits=0 *
*`ok` = > `H`.matches_matrix matrix=`H_matrix` *
````
- v1:**具名门**以插件内置酉矩阵为准;`matrix=` 可从嵌套 list / `$$` 矩阵围栏构造自定义门。
- `$$` 含 `[[…]]` 或 `\begin{pmatrix}` 时解析期求值为数值 list;标量公式仍为 `Formula`。
- `matches_matrix` 仍可用于核对。
---
## 5. 作者面 API(锁定草图)
### 5.1 英文 `ext/quantum/quantum.mq.md`
```markdown
# gate
+ `name`=None # H X Y Z S T I CX CZ SWAP …
+ `theta`=None # Rx/Ry/Rz
## matrix # → 振幅表 / 嵌套 list(文档与调试)
## draw # → quantum_svg(`kind=gate|matrix` 符号 / 热力图)
## matches_matrix
+ `matrix`
+ `tol`=1e-9
# circuit
+ `qubits`
+ `steps`=None # 可选:GFM 门序列表
## h / x / y / z / s / t
+ `qubit`
## rx / ry / rz
+ `qubit`
+ `theta`
## cx / cz
+ `control`
+ `target`
## swap
+ `a`
+ `b`
## barrier # 仅可视化分隔,不改变态
## measure # 标记测量(模拟时按计算基)
+ `qubits`=None # 默认全部
## append # 追加另一电路或门
+ `op`
## simulate # → quantum_state(不坍缩)
## probabilities # → map 基矢标签 → 概率
## run
+ `shots`=1024
+ `seed`=None # → quantum_result(计数直方图)
## draw
+ `path`=None # SVG;无 path 时仍可进 view 产物
+ `kind`=circuit # circuit|probs|bloch|hinton|…(见 Q7)
+ `theme`=dark # dark|light|bw(Q8;电路/概率/布洛赫)
## state # 当前缓存态(若已 simulate)
```
门方法返回**更新后的 circuit 句柄**(与 web `compose_*` 相同:`` `qc` = > `qc`.h qubit=0 *``)。
### 5.2 中文 `ext/quantum/量子.mq.md`
| 英文 | 中文 |
|------|------|
| `gate` | `门` |
| `circuit` | `电路` |
| `h` | `哈达玛` |
| `x` / `y` / `z` | `泡利X` / `泡利Y` / `泡利Z` |
| `cx` | `控非` |
| `cz` | `控相` |
| `rx`/`ry`/`rz` | `绕X`/`绕Y`/`绕Z` |
| `simulate` | `模拟` |
| `probabilities` | `概率` |
| `run` | `运行` |
| `draw` | `绘图` |
| `kind` | `种类` |
| `theme` | `主题` |
| `measure` | `测量` |
| `qubits` | `比特数` |
| `steps` | `步骤` |
| `shots` / `seed` | `次数` / `种子` |
插件 FFI 名稳定英文:`quantum_circuit_new`、`quantum_h`、`quantum_cx`、`quantum_simulate`、`quantum_draw_circuit`…
### 5.3 电路表(文档优先写法)
```markdown
`steps` =
| 步 | 门 | 比特 | 参数 |
|----|----|------|------|
| 1 | H | 0 | |
| 2 | CX | 0,1 | |
| 3 | RZ | 1 | pi/4 |
```
列名中英兼容:`步|step`、`门|gate`、`比特|qubits|qubit`、`参数|theta|params`。
*`qc` = > quantum.circuit qubits=2 steps=`steps` *` 与方法链**等价**;表更适合「整页即电路说明书」。
### 5.4 返回值形态
| 方法 | 返回 |
|------|------|
| `simulate` | `{_type, qubits, dim, amplitudes:[{re,im},…]}` |
| `probabilities` | `{ "00": 0.5, "11": 0.5 }`(标签为小端比特串,文档写死) |
| `run` | `{ counts: {…}, shots, seed }` |
| `draw` | `{_type: quantum_svg, kind: circuit\|gate\|probs\|bloch, svg: "…" }` |
---
## 6. 模拟器语义
| 项 | 锁定 |
|----|------|
| 模型 | 封闭系统纯态;计算基测量 |
| 默认上限 | **12 qubits**;`MARQDO_QUANTUM_MAX_QUBITS` 可下调(不可暗中上调超过编译期硬顶,硬顶建议 16) |
| 超限 | 错误信息含当前 n 与上限 |
| `simulate` / `probabilities` | **无 RNG**、确定性 |
| `run` | 多项式采样;`seed=` 可复现(金样必用) |
| 数值 | f64;门后 ‖ψ‖ 偏离阈值则重归一化并可选 warning 字段 |
实现:插件内 Kronecker / 按比特作用稀疏更新;可用 `nalgebra` 或手写,**不**捆绑外部量子云。
---
## 7. view 模式支持(专项)
对齐 [view.md](view.md) 与 math 作图:**Structure / Execution / Source 共用渲染**;禁止第二套皮肤。
### 7.1 Structure(结构区)
| 源形态 | 展示 |
|--------|------|
| `` `qc` = `` + 电路表 | **circuit-card**:比特数、门序列时间线(文本/紧凑 SVG) |
| `` `G` = `` + `$$` 门矩阵 | 沿用 **formula-card**(KaTeX);徽章可标 `gate`(若绑定来自 quantum.gate) |
| 方法链语句 | 普通调用行;不强制每步展开 |
### 7.2 Execution(执行区)
| 产物 | 展示 |
|------|------|
| `quantum_svg` | 与 math `plots` 同级:**内嵌 SVG**(电路轨线图 / 概率直方图 / 单比特布洛赫) |
| `probabilities` / `counts` | 表格 + 可选自动条形 SVG |
| `quantum_state` | 默认折叠振幅表;小 n(≤3)可并排显示基矢 |
### 7.3 产物如何进入 view(实现锁定)
插件**不能**直接碰核心 `HostContext.plots`。采用其一(实现时二选一,优先 A):
| 方案 | 做法 |
|------|------|
| **A(推荐)** | ABI `host_query("record_plot")`:参数 JSON `{svg}`;写入与 math 相同的 plots 列表([ext-abi.md](ext-abi.md) allowlist 增补一条) |
| **B** | 仅返回 `quantum_svg`;view 在渲染执行值时识别 `_type`/`svg` 字段并内嵌(不扩 ABI) |
CLI:`draw path=bell.svg` 写沙箱文件;无 path 时不把整段 SVG 灌 stdout(同 math §5)。
### 7.4 可视化内容(v1 必须 / 可后)
| 图 | v1 | 说明 |
|----|----|------|
| 电路轨线(qubit 线 + 门盒 + 控点) | **必须** | `circuit.draw`;Q8 默认 `theme=dark`(标签芯片 + 门族分色) |
| 测量概率条形图 | **必须** | `probabilities` / `run` 后可 `draw kind=probs` |
| 单比特布洛赫球(SVG) | 应有 | 仅 n=1 或指定 qubit 约化(纯态投影) |
| 门矩阵热力图 | **必须** | `gate.draw kind=matrix`(幅值热图 + 小数标注) |
| 高级态图(hinton/city/…) | Q7 | 见 [ext-quantum-q7.md](ext-quantum-q7.md);换肤见 Q8c |
| 交互拖拽编辑电路 | **不做** | 静态文档足够 |
视觉:内联 SVG 色与字体栈;**无外链**字体/CDN(同 view 硬规则)。主题令牌与布局:[ext-quantum-viz-style.md](ext-quantum-viz-style.md)。view 对 `svg[data-theme=dark]` 使用深色图框。
---
## 8. 分期(开发计划)
```text
Q0 脚手架:CATALOG + plugins/quantum Hello + L1 ensure_plugin
Q1 态向量 + I/X/H/CX + simulate/probabilities;贝尔态 gold
Q2 Y/Z/S/T/Rx/Ry/Rz/CZ/SWAP + run(seed) + 中英 API 对齐
Q3 电路表 steps= + draw 电路 SVG + view record_plot/识别;examples/
Q5 教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext-quantum-q5.md) ← **done(最小)**
```
| 阶段 | 交付物 | 验收 |
|------|--------|------|
| **Q0** | `marqdo_plugin_quantum` 注册 `quantum_ping`;L1 加载失败可读 | `ext add quantum` 路径通 |
| **Q1** | 贝尔态 `probabilities` ≈ 0.5/0.5 | `tests/ext/quantum-bell-smoke.mq.md` |
| **Q2** | 旋转门 + `run seed=` 计数稳定 | 中英双金样 |
| **Q3** | `steps=` 表;`draw` SVG 在 `view` HTML 含 `<svg` | 与 math-plot 同级断言 |
| **Q4** | 概率图 + 布洛赫;`matches_matrix`;用户文档页 | `quantum-draw-smoke` / `quantum-gate-matrix-smoke`;`view output` 可浏览示例 |
| **Q5** | `noise` 轨迹;`barrier`/`measure`/`append`/`state` | `quantum-noise-smoke` / `quantum-author-api-smoke` |
| **Q6** | 公式/`matrix=` 自定义门 | [ext-quantum-custom-gate.md](ext-quantum-custom-gate.md) |
| **Q7** | 密度矩阵线性代数 + Hinton/City/QSphere 等 SVG + 纠缠示例 | [ext-quantum-q7.md](ext-quantum-q7.md) ✅ |
| **Q8** | 可视化美学:`theme` + 标签 gutter + 门族分色 | [ext-quantum-viz-style.md](ext-quantum-viz-style.md) · Q8a/Q8b ✅ · Q8c 待做 |
实现路线图跟踪见 [roadmap/ext-quantum.md](../roadmap/ext-quantum.md)。
---
## 9. 规范示例(目标作者体验)
```markdown
---
title: Bell state
import quantum:ext/quantum/quantum.mq.md
---
# Bell |Φ+⟩
H on qubit 0, then CNOT. Expect |00⟩ and |11⟩ each with probability 1/2.
# main
`steps` =
| step | gate | qubits |
|------|------|--------|
| 1 | H | 0 |
| 2 | CX | 0,1 |
*`qc` = > quantum.circuit qubits=2 steps=`steps` *
*`p` = > `qc`.probabilities *
*`svg` = > `qc`.draw *
> print text=`p`
```
中文面对称:`量子.电路`、`哈达玛`、`控非`、`概率`、`绘图`。
---
## 10. 刻意不做(本 Accepted 范围)
- 真机 / 云后端(IBM、Braket…)
- 开放系统、完整噪声模型(可 Q5+)
- 符号电路编译优化器
- 交互式电路编辑器
- 把量子并入 `lib/math` 或核心 opcode
- 无上限比特的「生产级」模拟
---
## 11. 开放点(已收敛 / 剩余)
| 议题 | 结论 |
|------|------|
| 对象面 vs 自由函数 | **主推对象/方法链**;自由函数不平行提供 |
| 电路表 | **v1 纳入**(Q3),与方法链等价 |
| 振幅过大 | v1 全进 Value;n≤12 可接受;超限已挡 |
| view 产物 | **优先** `host_query("record_plot")` |
| 与 web | **不依赖** web 做可视化;SVG 自绘 |
---
## 12. 评审清单
1. ABI-only + 中英分文件是否认可?
2. 默认 12 qubits 上限是否合适?
3. 电路表列设计(步/门/比特/参数)是否够用?
4. view:电路轨线 + 概率条为 v1 必须,是否同意?
5. `$$` 矩阵核对放 Q4,是否同意先表驱动?
评审通过后:本文冻结为 Accepted → 按 §8 从 Q0 实现。
---
## 13. 一句话
**表格写出电路,类方法模拟与绘图;跑通金样即证明文档中的量子公式与步骤成立——math 管曲线,quantum 管希尔伯特空间上的可执行说明书。**
+124
View File
@@ -0,0 +1,124 @@
# `ext/web` 驱动:Postgres · Redis · S3
| | |
|---|---|
| 状态 | **Accepted · 已落地** |
| 日期 | 2026-08-28 |
| 相关 | [ext-web.md](ext-web.md) · [roadmap/ext-web.md](../roadmap/ext-web.md) · [ext-abi.md](ext-abi.md) |
| 目标 | 在**不改作者面 CRUD 心智**的前提下,用 URL 方案切换数据库;另增缓存与对象存储两类驱动。贯彻「表格 + 类方法」:配置即数据,装配即函数。 |
---
## 0. 一句话
**`# db` 的 `url=` 决定后端**:`sqlite:` 默认;`postgres://` / `postgresql://` 走 Postgres,作者面 API 不变。
**缓存**与**对象存储**是独立类(`# cache` / `# storage`),不塞进 `# db`。
---
## 1. 边界
| 能力 | 归属 | 理由 |
|------|------|------|
| SQLite / Postgres CRUD | `plugins/web` + `ext/web` `# db` | 同一套 `init/select/insert/…`;热路径 ABI |
| Redis 缓存 | `plugins/web` + `ext/web` `# cache` | 键值语义,不是表 CRUD |
| S3 / MinIO 对象 | `plugins/web` + `ext/web` `# storage` | 对象键 + 字节/路径,不是行 |
| 禁止 | 核心 `src/host/` | 驱动依赖重,只进 ABI 插件 |
---
## 2. URL 方案(锁定)
| 方案 | 含义 | 例 |
|------|------|-----|
| `sqlite:` / 裸路径 | SQLite 文件(既有) | `sqlite:data/site.db` |
| `postgres://` / `postgresql://` | Postgres | `postgres://user:pass@127.0.0.1:5432/app` |
| `redis://` / `rediss://` | Redis | `redis://127.0.0.1:6379/0` |
| `memory:` | **进程内** Redis 兼容后端(金样/离线) | `memory:` |
| `s3://bucket` + 查询参数 | S3 兼容(含 MinIO) | `s3://mybucket?endpoint=http://127.0.0.1:9000&region=us-east-1` |
| `file:` | **本地目录**对象存储(金样/离线) | `file:data/blobs` |
凭证:优先 URL 内嵌;S3 亦读环境变量 `AWS_ACCESS_KEY_ID` / `AWS_SECRET_ACCESS_KEY`(或 `S3_ACCESS_KEY` / `S3_SECRET_KEY`)。
---
## 3. 作者面(代码即文档)
### 3.1 数据库 — 只换 URL
英文:
```markdown
import web:ext/web/web.mq.md
# main
*store = > web.db url="postgres://marqdo:marqdo@127.0.0.1:5432/site"*
*store = > store.init name="posts" fields=`schema`*
```
中文:`网页.数据库` + `url=` 同形。`init` / `select` / `insert` / `paginate` / `事务` **API 不变**。
Postgres 差异(实现层消化,作者尽量无感):
- `id INTEGER PRIMARY KEY` → `SERIAL PRIMARY KEY`(或 `GENERATED …`)
- 占位符 `?` → `$1,$2,…`
- 标识符双引号规则对齐
### 3.2 缓存 `# cache` / `# 缓存`
```markdown
*c = > web.cache url="memory:"*
*c = > c.set key="k" value="v" ttl=60*
*v = > c.get key="k"*
*c = > c.del key="k"*
```
方法:`get` · `set`(可选 `ttl` 秒)· `del` · `exists` · `ttl`。
配置表可选(装配时合并进 url / 默认 TTL):
| 键 | 值 |
|----|-----|
| url | redis://127.0.0.1:6379/0 |
| ttl | 3600 |
### 3.3 对象存储 `# storage` / `# 存储`
```markdown
*blob = > web.storage url="file:data/blobs"*
> `blob`.put key="avatar/1.png" path="local.png" content_type="image/png"
*got = > `blob`.get key="avatar/1.png"*
> `blob`.delete key="avatar/1.png"
*keys = > `blob`.list prefix="avatar/"*
```
方法:`put`(`path=` 本地文件或 `body=` 文本)· `get`(返回 `{ok, body|path, content_type}`)· `delete` · `list`。
---
## 4. ABI 名
| ABI | 说明 |
|-----|------|
| 既有 `web_db_*` | 内部按 `url` 方案分发 SQLite / Postgres |
| `web_cache_new/get/set/del/exists/ttl` | 缓存 |
| `web_storage_new/put/get/delete/list` | 对象存储 |
---
## 5. 测试
| 金样 | 内容 |
|------|------|
| `tests/ext/web-drivers-smoke.mq.md` | `memory:` 缓存往返;`file:` 存储 put/get/list/delete;`web_db_new` 接受 `postgres://` 句柄形状(不要求本机有库) |
| 可选 live | `MARQDO_TEST_POSTGRES` / `MARQDO_TEST_REDIS` / `MARQDO_TEST_S3` 非空时跑真实连通(CI 默认关) |
---
## 6. 非本波次
- 连接池大小 / 读写分离配置表
- Redis 集群 / Sentinel
- S3 预签名 URL 作者面糖(可后续加方法)
- 把 session 默认改存 Redis(仍默认 SQLite 表;可选后续)
+285
View File
@@ -0,0 +1,285 @@
# 网络扩展波次:`ext/web` 鉴权 · WebSocket · 标准库网络原语
| | |
|---|---|
| 状态 | **Draft(本波次锁定设计)** |
| 日期 | 2026-08-24 |
| 相关 | [ext-web.md](ext-web.md) · [ext-abi.md](ext-abi.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-cli.md](ext-cli.md) |
| 目标 | 补齐 `ext/web` 登录鉴权(session/cookie)、WebSocket 端点;为网络扩展所需的**基础设施解析原语**适当补强 `lib/net`(标准库)。 |
---
## 0. 一句话
**领域能力(鉴权、WebSocket 服务器)全部走 ABI 插件 `plugins/web`;纯解析基础设施(cookie / multipart 解析、WS 客户端)按需进入标准库 `lib/net`,因为标准库需要支撑扩展库开发。**
---
## 1. 边界判定:什么进标准库 `lib/net`,什么进扩展
### 1.1 跨语言调研结论
| 语言 | 标准库 | 扩展/生态 | 边界准则 |
|------|--------|----------|---------|
| Python | `urllib`(URL/基础 HTTP)、`http.cookies`(**cookie 解析器在标准库**) | `requests`/`httpx`(session/连接池/便利层) | 标准库 = 基础设施原语(解析器);便利层 = 第三方 |
| Node.js | `http`/`https`/`http2`(低层流式,不解析 body) | express、ws、formidable | 足够 fancy 就不进核心;核心只放几乎人人要用的低层原语;**先 userland 验证再拉进 core** |
| Go | `net/http`(服务器+客户端都在标准库)、`net/http/cookiejar`(**RFC 6265 cookie jar 在标准库**) | `golang.org/x/net`(publicsuffix 等演进性) | HTTP 是「与 stdin 同级」的核心能力;**cookie 解析/管理进标准库**;持久化等演进性能力在外 |
| Rust | 极小 std(无 HTTP) | `http`(词汇)→ `hyper`(传输)→ `reqwest`(便利) | 分层;HTTP 因生态多样不进 std |
**共识**:
1. **cookie 解析/管理(RFC 6265)**在 Python/Go 都是**标准库**(`http.cookies`、`net/http/cookiejar`)。
2. **multipart/form-data 解析**在 Go 是标准库(`net/http`),在 Python 是第三方 `multipart`。
3. **WebSocket** 几乎总在扩展/第三方(Node `ws`、Python `websockets`、Go `gorilla/websocket`),**很少进语言标准库**。
4. **session 是领域级便利**,几乎所有语言都在框架层(express-session、Django session),不在语言标准库。
### 1.2 Marqdo 判定(锁定)
| 能力 | 类型 | 归属 | 理由 |
|------|------|------|------|
| `cookie.parse` / `cookie.parse_response` | 基础设施解析 | **`lib/net`(标准库)** | 对齐 Go/Python 标准库;`ext/web` 鉴权依赖 |
| `multipart.parse` | 基础设施解析 | **`lib/net`(标准库)** | 对齐 Go 标准库;`ext/web` 文件上传依赖 |
| `ws.connect`(客户端) | 基础连接 | **`plugins/web`(ABI)+ `ext/web`** | WS 栈(tokio-tungstenite)已在 web 插件依赖链;核心 `Cargo.toml` 锁定 rustc 1.81 不宜再引入 WS 栈;符合「尽量只 ABI」 |
| `web.session_*`(session 管理) | 领域 | **`plugins/web`(ABI)+ `ext/web`** | session 是框架层便利,不进标准库 |
| `/admin` 登录鉴权 | 领域 | **`plugins/web`(ABI)+ `ext/web`** | 网站领域能力 |
| `web_ws`(服务器端点) | 领域 | **`plugins/web`(ABI)+ `ext/web`** | WebSocket 服务器是网站能力 |
**实现约束(用户要求)**:
- 标准库新增的**解析原语**(cookie/multipart)是纯函数、无网络 I/O,作为 L0.5 宿主原语进 `src/host/`(与 `url_encode` 同模式),由 `lib/net` 薄包装——这符合「标准库需要支持扩展库开发」。
- **涉及网络 I/O 的 WS 能力**(客户端 + 服务器端点)一律进 `plugins/web`(ABI v2),由 `ext/web` / `ext/web/网页.mq.md` 包装。核心运行时(rustc 1.81 锁定)**不再新增** WS 栈依赖。
- **网站领域能力**(session、鉴权中间件)一律进 `plugins/web`(ABI v2),由 `ext/web` 包装。
- **禁止**:为这些能力修改核心语法;禁止在 `src/host/` 塞领域逻辑。
---
## 2. 标准库 `lib/net` 新增(基础设施原语)
### 2.1 `cookie.parse` / `解析Cookie`
- 形参:`text`(`Cookie:` 请求头或 `Set-Cookie:` 响应头)
- 结果:`[{name, value, path, domain, expires, max_age, secure, http_only, same_site}]`
- 行为:RFC 6265 解析;`Set-Cookie` 多 cookie 分条;无属性则字段为空。
**英文(`lib/net.mq.md`):**
```markdown
## cookie_parse
+ `text`
**> host_cookie_parse text=`text`**
```
**中文(`lib/网络.mq.md`):**
```markdown
## 解析Cookie
+ `内容`
**> host_cookie_parse text=`内容`**
```
### 2.2 `multipart.parse` / `解析多部分`
- 形参:`body`(文本)、`boundary`
- 结果:`[{name, filename, content_type, value}]`(`value` 为字段值;文件字段用 `filename` + `content_type` + `value`(base64 或文本))
- 行为:解析 `multipart/form-data` 正文;字段名 → value;文件字段带 filename。
**英文:**
```markdown
## multipart_parse
+ `body`
+ `boundary`
**> host_multipart_parse body=`body` boundary=`boundary`**
```
**中文:**
```markdown
## 解析多部分
+ `正文`
+ `边界`
**> host_multipart_parse body=`正文` boundary=`边界`**
```
### 2.3 WebSocket 客户端 — 见 §3.4(`plugins/web` ABI)
WS 客户端为领域能力,放 `plugins/web`(ABI)而非标准库,理由见 §1.2。`lib/net` 不新增 WS 客户端包装,避免标准库依赖 ext 插件。
---
## 3. `plugins/web`(ABI v2)新增:领域能力
### 3.1 Session 存储(`web_session_*`)
插件进程内 `static` 内存存储(`HashMap<session_id, HashMap<String,Value>>`),与 `web_listen` 同生命周期。
| ABI 名 | 形参 | 结果 |
|--------|------|------|
| `web_session_new` | 可选 `ttl_sec` | `{id}`(新 session id) |
| `web_session_set` | `id`, `key`, `value` | `{ok:true}` |
| `web_session_get` | `id`, `key` | 值或 `{ok:false}` |
| `web_session_del` | `id`, `key` | `{ok:true}` |
| `web_session_destroy` | `id` | `{ok:true}` |
### 3.2 `/admin` 登录鉴权(`web_auth_*`)
- 作者面:`web.auth` 类(`网页.鉴权`),形参 `admin_users`(`|用户名|密码|` 表)、可选 `session_ttl`。
- `listen` 时若配置了 auth:`/admin*` 未登录 → 跳转 `/admin/login`;登录页 `POST` → 校验 `admin_users` 表 → 写 session cookie → 重定向。
- 登出:`/admin/logout` → 销毁 session。
| ABI 名 | 形参 | 结果 |
|--------|------|------|
| `web_auth_login` | `username`, `password`, `users`, `session_ttl` | `{ok:true, session_id}` 或 `{ok:false}` |
| `web_auth_check` | `session_id`, `users` | `{ok:true}` 或 `{ok:false}` |
| `web_auth_logout` | `session_id` | `{ok:true}` |
### 3.3 WebSocket 服务器端点(`web_ws_route`)
- 作者面:`app.route_ws` / `应用.路由实时`,形参 `path`、可选 `echo=True`。
- `listen` 时 `{path}` 升级为 WS:`echo=True` 回发原文;否则接收并丢弃(扩展点)。
| ABI 名 | 形参 | 结果 |
|--------|------|------|
| `web_app_route_ws` | `app`, `path`, `echo` | `{app}`(登记 WS 端点) |
### 3.4 WebSocket 客户端(`web_ws_connect`)
- 作者面:`web.ws` / `网页.实时`,形参 `url`、`message`、可选 `headers`、`timeout_sec`。
- 行为:客户端连接一次 WS,发 `message`,收**全部**服务器回文后关闭。**单请求-响应式**(非长驻),与 Marqdo 同步模型一致。
| ABI 名 | 形参 | 结果 |
|--------|------|------|
| `web_ws_connect` | `url`, `message`, `headers`(map), `timeout_sec` | `{ok:true, messages:[…]}` 或 `{ok:false, error}` |
**英文(`ext/web/web.mq.md`):**
```markdown
# ws
+ `timeout_sec`=30
## connect
+ `url`
+ `message`
+ `headers`=None
```
**中文(`ext/web/网页.mq.md`):**
```markdown
# 实时
+ `超时秒`=30
## 连接
+ `地址`
+ `消息`
+ `headers`=None
```
> `plugins/web` 用 `tokio-tungstenite`(与 axum WS 同栈,版本兼容 rustc 1.81)。
---
## 4. `ext/web` 作者面新增
### 4.1 英文面(`web.mq.md`)
```markdown
# auth
+ `users` # |用户名|密码| 表
+ `session_ttl`=3600
## login
+ `username`
+ `password`
## check
+ `session_id`
## logout
+ `session_id`
```
`# app` 新增 `## route_ws`:
```markdown
## route_ws
+ `path`
+ `echo`=True
```
### 4.2 中文面(`网页.mq.md`)
```markdown
# 鉴权
+ `用户表`
+ `会话时长`=3600
## 登录
+ `用户名`
+ `密码`
## 校验
+ `会话id`
## 登出
+ `会话id`
```
`# 应用` 新增 `## 路由实时`:
```markdown
## 路由实时
+ `路径`
+ `回显`=真
```
### 4.3 用法示例(英文)
```markdown
# main
`admins` =
| 用户名 | 密码 |
|--------|------|
| admin | secret |
*store = > db.open *
*page = > web.page title="Site" *
*app = > web.app page=`page` db=`store` admin=True host=127.0.0.1 port=18081 *
*app = > `app`.route_ws path="/live" echo=True *
*app = > web.auth users=`admins` *
> `app`.listen
*echo = > web.ws.connect url="ws://127.0.0.1:18081/live" message="hi" *
```
---
## 5. form 完善(现有功能验证 + 补测试)
现状已具备(无需改代码,需验证):
- `action=update`:hidden `id` + `db.update`(form.rs `from_schema`/`submit` 已实现)
- 校验失败页级回显:`submit_and_respond` → `render_page_ex`(http.rs 已实现)
本波次为 update 流程和页级回显补 gold 测试,确认端到端可用。
---
## 6. 测试与验收
| 测试 | 内容 |
|------|------|
| `tests/ext/web-net-smoke.mq.md` | session new/set/get/del + auth login/check/logout + `route_ws`/`app.auth` 登记 + ws 连接失败路径(离线) |
| `tests/lib/net-cookie.mq.md` | `cookie_parse` 解析 |
| `tests/lib/net-multipart.mq.md` | `multipart_parse` 解析 |
| `tests/ext/web-admin-smoke.mq.md` | form `action=update` 全流程 + 校验失败 `errors` 回显 |
| 现有 gold | 全量回归(树遍历 + 字节码) |
验收:`cargo test --test gold` 全绿(除网络 live),双后端一致。
### 6.1 字典操作约束(作者面)
Marqdo 原生字典操作:GFM 横表**构造**、脚注取元 `变量[^键]` **读取**。`ext/web` 作者面**不使用** `json.get` / `json.set` 做字典读取/改写——所有字段读取一律 `self[^键]`(或实例变量 `[^键]`),避免"用 json 标准库做字典操作"的反模式。`json.parse` / `json.stringify` 仅用于文本 ↔ 结构化数据的序列化转换(如 HTTP body 解析),不用于本地字典读写。
### 6.2 相对路径按入口脚本解析(host_query `entry_dir`)
`static_dir`(如 `public`)与相对 db 路径(如 `sqlite:data/site.db`)此前按**进程 cwd** 解析——从仓库根目录跑 `examples/*/index.mq.md` 时,`/static` 404、db 会建到根目录,这是错误行为。
本波次修复:宿主新增 `host_query("entry_dir")`(返回入口 `.mq.md` 所在目录的绝对路径,回退 cwd),`plugins/web` 的 `web_listen` 将相对 `static_dir`、`db_url_of` 将相对 db 路径统一 `entry_dir().join(...)` 到绝对路径。于是无论从仓库根目录还是示例目录运行,静态资源与数据库都落在**脚本目录**下。绝对路径不受影响;`host_query` 不可用时回退旧 cwd 行为。
---
## 7. 非本波次
- Postgres / Redis / S3 驱动(roadmap W4,另行)
- WS 广播房间、多客户端(先 echo 单连接)
- session 持久化到 SQLite / 文件(先内存)
- 复杂权限 / RBAC
+600
View File
@@ -0,0 +1,600 @@
# 官方扩展:`ext/web` 动态网站
| | |
|---|---|
| 状态 | **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) |
| 安装(目标) | `marqdo ext add web`(中英:`web` / `网页`) |
| 本文目的 | 锁定**作者面**与**类 API**;指导实现 |
---
## 0. 一句话
`ext/web` 用 **GFM 表格 + Marqdo 类方法** 描述动态网站:表仍是字典/列表嵌套;类方法把表装配成可渲染页面。
**不改 Marqdo 核心语法**;扩展库存在的理由,正是让「文档即代码」在网站场景下成立。
---
## 1. 为何要做网络扩展库
### 1.1 问题
若没有专用扩展,作者只能:
- 手写 JSON 袋、`json.set` 拼装组件/样式;或
- 要求改语言(让表格单元格求值、点号取值等)。
二者都破坏 Marqdo 的「代码即文档」。
### 1.2 答案
在 **`ext/web/web.mq.md`(英文)** 与 **`ext/web/网页.mq.md`(中文)** 中各提供一套 **`#` 类**:
- 作者只写**表** + **少量实例方法调用**;
- 表单元格保持**字面量**;
- **寻址字符串**由类方法解析;
- **导入英文文件 → 只用英文 API;导入中文文件 → 只用中文 API**(见 [stdlib-i18n.md](stdlib-i18n.md))。
### 1.3 硬约束(评审锁定)
| # | 约束 |
|---|------|
| C1 | **禁止**为 web 改动 Marqdo 核心:单元格求值、import、点号值读取等保持不变 |
| 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 者)评审通过后**删除或清空后重写**;禁止在旧代码上打补丁演进 |
| C6 | `# db` / `# 数据库` 必须提供完整**增删改查**;列表查询英文方法名为 **`select`**(中文 **`查询`**);后台 `/admin` 与表单提交走同一套写库 API |
| C7 | 用户输入经 `# form` / `# 表单`:字段表 + 校验表;**服务端校验必须在写库前执行**(见 §5.5) |
---
## 2. 作者心智与目录
```text
myapp/
index.mq.md # 入口 + 首页:页面表 +(可选)就地主体表 + 类方法 + listen
pages/ # 子页:同形的页面表(导出布局表或由入口再装配)
components/ # 可复用组件:导出与路径同名的 ##,体为 |属性|值|样式|
styles/ # 样式模块:每个样式一个 ##,体为 |属性|值|
db/ # 库:schema 表 +(可选)open/种子
data/ # sqlite 等运行时数据(gitignore)
```
| 表种 | 列 | 一句话 |
|------|-----|--------|
| **页面表** | `组件` \| `样式` | 本页用哪些组件、各套哪套样式 |
| **组件 / 主体表** | `属性` \| `值` \| `样式` | 前端属性 ↔ 取值(库字段或字面量)↔ 样式名 |
| **样式表** | `属性` \| `值` | CSS 声明 |
| **库结构表** | `字段` \| `类型` \| `可空` | schema |
---
## 3. 表内寻址约定(单元格仍是字符串)
单元格**不求值**。下列写法是 **web 扩展约定的路径文本**,由 `# 页面` / `# 样式` / `# 数据库` 的方法解析。
### 3.1 反引号与裸名
| 含义 | 写法 | 例 |
|------|------|-----|
| 要「去导入树 / 定义里解析」的名字 | 反引号 `` `名` `` | `` `nav` ``、`` `title` ``、`` `topnav` ``、`` `articles` ``(表名) |
| 字面量(文案、URL、CSS 属性名/值、SQL 类型、**列名**) | **裸**或 `"…"` | `首页`、`/about`、`font-size`、`integer`、`title`(作为列名时) |
### 3.2 路径形态(锁定)
| 场景 | 形态 | 例 | 方法内语义 |
|------|------|-----|------------|
| 引用导入模块的导出 | `模块.`导出`` | `nav.`nav``、`shell.`topnav`` | 在**站点入口模块**的 import 树上调用 `模块.导出`(零参 `##`),取回表 Value |
| 引用库字段 | `模块.`表`.列` | `articles.`articles`.title` | 模块名 = 命名空间(对应导入的 db 文件);`` `表` `` = 库表名;**列名裸写**(列不是变量)→ 运行时绑定 `表.列` |
| 前端属性名 | `` `title` `` | 组件表「属性」列 | 解析为字段名 `title` |
| 样式引用 | 同「模块.导出」或纯样式名 | `shell.`card-title`` | 取回 `|属性|值|` 表并编译为 CSS 类 |
**刻意不做的事:**
- 不把「组件变量名」魔法等同于「库表名」;
- 不要求作者写 `json.set` 才能把 `nav` 放进袋;
- 不把 `articles.`articles`.title` 做成语言级表达式。
### 3.3 与模块命名空间的关系
- 库名来自 frontmatter 导入(茎名或 `as`),**裸名**,见 [module-namespace.md](module-namespace.md)。
- `nav.`nav`` 中:前段 `nav` = 导入库名;`` `nav` `` = 该库上的 `## nav` 导出。
- 组件/样式文件应导出 **与路径第二段同名的 `##`**,直接返回表(不要 `## bag` / `## bind` 袋)。
---
## 4. 规范示例:`index.mq.md`(作者面唯一样板)
**语言与导入绑定(锁定,纠正手写混用):**
| 导入 | 库名(默认茎) | 类 / 方法 / 形参 |
|------|----------------|------------------|
| `import web:ext/web/web.mq.md` | `web` | **仅英文**:`page` · `compose_components` · `db` · `app` · `components=` … |
| `导入 网页:ext/web/网页.mq.md` | `网页` | **仅中文**:`页面` · `组件装配` · `数据库` · `应用` · `组件=` … |
禁止:`import web:ext/web/web.mq.md` 后写 `web.页面` / `` `页`.组件装配 ``(英文库混中文成员)。
禁止:在 `web.mq.md` 文件内定义中文 `## 组件装配` 别名。中英对等靠**两个文件**,不靠同一文件双份导出。
### 4.1 英文面(导入 `web.mq.md`)
```markdown
---
title: web-site
description: Home = page table; main may be inline; class methods assemble.
import web:ext/web/web.mq.md
import shell:styles/shell.mq.md
import nav:components/nav.mq.md
import side:components/side.mq.md
import foot:components/foot.mq.md
import articles:db/articles.mq.md
import db:db/index.mq.md
---
# main
`home` =
| 组件 | 样式 |
|------|------|
| nav.`nav` | shell.`topnav` |
| side.`side` | shell.`side-panel` |
| foot.`foot` | |
Main content is not a reusable component, so it is authored here.
`index` =
| 属性 | 值 | 样式 |
|------|-----|------|
| `title` | articles.`articles`.title | shell.`card-title` |
| `body` | articles.`articles`.body | shell.`card-body` |
*`store` = > db.open *
*`page` = > web.page title="Marqdo Web Site" intro="<h1>Web Site</h1>" *
*`page` = > `page`.compose_components components=`home` *
*`page` = > `page`.compose_main main=`index` *
*`app` = > web.app page=`page` db=`store` admin=True host=127.0.0.1 port=18081 *
> `app`.listen
```
说明:表头列名可用中文(`组件`/`样式`/`属性`/`值`)——那是**表约定词汇**,不是库成员名;库成员必须与导入语言一致。
### 4.2 中文面(导入 `网页.mq.md`)
```markdown
---
title: 站点
导入 网页:ext/web/网页.mq.md
import shell:styles/shell.mq.md
import nav:components/nav.mq.md
import side:components/side.mq.md
import foot:components/foot.mq.md
import articles:db/articles.mq.md
import db:db/index.mq.md
---
# main
`首页` =
| 组件 | 样式 |
|------|------|
| nav.`nav` | shell.`topnav` |
| side.`side` | shell.`side-panel` |
| foot.`foot` | |
主体不是可复用组件,因此就地撰写。
`index` =
| 属性 | 值 | 样式 |
|------|-----|------|
| `title` | articles.`articles`.title | shell.`card-title` |
| `body` | articles.`articles`.body | shell.`card-body` |
*`库` = > db.open *
*`页` = > 网页.页面 标题="站点" 引言="<h1>站点</h1>" *
*`页` = > `页`.组件装配 组件=`首页` *
*`页` = > `页`.主体装配 主体=`index` *
*`应用` = > 网页.应用 页面=`页` 数据库=`库` 后台=True 主机=127.0.0.1 端口=18081 *
> `应用`.监听
```
**允许出现在 index 的非表内容:** frontmatter 导入、开库一行、构造页面/应用并装配、`listen` / `监听`。
**不允许:** `json.*` 袋、手写 `/_part` 注册、中英 API 混用。
---
## 5. 类 API(分文件 · 分语言)
依据 [stdlib-i18n.md](stdlib-i18n.md):**导入哪个文件,就用哪套名字。**
`ext/web/web.mq.md` = 全英文;`ext/web/网页.mq.md` = 全中文。中文实现可委托插件同一套原语,或薄封装英文库,但**对外导出的 `#` / `##` / 形参名必须是中文**。
### 5.1 页面 · `page` / `页面`
**英文(`web.mq.md`):**
```markdown
# page
+ `title`=…
+ `intro`=…
## compose_components
+ `components` # page table |组件|样式|
## compose_main
+ `main` # bind table |属性|值|样式|
```
**中文(`网页.mq.md`):**
```markdown
# 页面
+ `标题`=…
+ `引言`=…
## 组件装配
+ `组件`
## 主体装配
+ `主体`
```
| 行为 | 说明 |
|------|------|
| compose_components / 组件装配 | 解析组件·样式路径 → 填 nav/sidebar/footer → CSS → 登记 part |
| compose_main / 主体装配 | 解析库字段与样式路径 → 填 main → 登记 part(如 id=`index`) |
**槽位推断:** 由组件导出名决定(`nav`→顶栏,`side`→侧栏,`foot`→底栏;其余→main)。
### 5.2 样式 · `style` / `样式`
**英文:** `# style` · `## process` · `+ style=` / `name=` / `path=`
**中文:** `# 样式` · `## 样式处理` · `+ 样式=` / `名=` / `路径=`
页面装配可内部调用;作者一般不必在 index 显式调。
### 5.3 数据库 · `db` / `数据库`
完整**增删改查**;页面绑定、种子、`/admin`、表单提交共用。
**英文(`web.mq.md`):**
```markdown
# db
+ `url`=…
## init
+ `name`
+ `fields` # or table= schema
## insert
+ `table`
+ `rows`
## select
+ `table`
+ `where`=None # optional simple filters
+ `limit`=200
## get
+ `table`
+ `id`
## update
+ `table`
+ `id`
+ `row`
## delete
+ `table`
+ `id`
## exec
+ `sql`
+ `args`=None # escape hatch: raw SQL (not everyday authoring)
```
**中文(`网页.mq.md`):**
```markdown
# 数据库
+ `地址`=…
## 初始化
+ `数据库表` # 或 名= + 字段=
## 插入
+ `表`
+ `行` # 或 多行=
## 查询
+ `表`
+ `条件`=None
+ `上限`=200
## 获取
+ `表`
+ `id`
## 更新
+ `表`
+ `id`
+ `行`
## 删除
+ `表`
+ `id`
## 执行
+ `sql`
+ `参数`=None
```
| 中文 | 英文 | 职责 |
|------|------|------|
| 初始化 | `init` | 建表;登记表名 |
| 插入 | `insert` | 增 |
| 查询 | `select` | 查列表(可带简单条件 / limit) |
| 获取 | `get` | 按主键一行 |
| 更新 | `update` | 改 |
| 删除 | `delete` | 删 |
| 执行 | `exec` | 可选原始 SQL(进阶) |
`table=` / `表=` 接受表名或句柄;行数据优先 GFM 表。
**命名锁定:** 列表查询用 `select` / `查询`,**不用** `all`;原始 SQL 用 `exec` / `执行`,避免与 `select` 混淆。
### 5.4 应用 · `app` / `应用`
**英文:** `# app` · `## route` · `## static` · `## listen` · 形参 `page` `db` `admin` `host` `port`
**中文:** `# 应用` · `## 路由` · `## 静态` · `## 监听` · 形参 `页面` `数据库` `后台` `主机` `端口`
`listen` / `监听`:加载插件、注入 `db_url`、按页面 part 提供 `/_part/{id}`(首页)与 `{path}/_part/{id}`(`app.route` 页)、可选 `static` 目录挂载、启动 HTTP。作者不必手写 part 注册。
`static` / `静态`:`dir=`(或 `目录=`)+ 可选 `mount=`(默认 `/static`);`listen` 时用 `tower-http` 提供只读文件服务。
### 5.5 表单 · `form` / `表单`(规划锁定)
用户输入也走「表 + 类方法」,与页面/库同一心智;**提交最终调用 `# db` 的 insert/update**,不另开旁路。
**英文(`web.mq.md`):**
```markdown
# form
+ `table`=None # bound db table name (optional until submit)
+ `action`=insert # insert | update
+ `id`=None # required when action=update
## fields
+ `fields` # |字段|标签|类型|必填|默认|…
## validate
+ `rules`=None # |字段|规则|消息|… (optional extra rules)
+ `data` # submitted row / map
## render
# → HTML form (or form descriptor for page slot)
## submit
+ `data`
+ `db` # db handle
```
**中文(`网页.mq.md`):**
```markdown
# 表单
+ `表`=None
+ `动作`=插入 # 插入 | 更新
+ `id`=None
## 字段
+ `字段`
## 校验
+ `规则`=None
+ `数据`
## 渲染
## 提交
+ `数据`
+ `数据库`
```
#### 5.5.1 字段表(作者面)
```markdown
`文章表单` =
| 字段 | 标签 | 类型 | 必填 | 默认 |
|------|------|------|------|------|
| title | 标题 | text | true | |
| body | 正文 | textarea | false | |
```
| 列 | 含义 |
|----|------|
| `字段` | 对应库列名(裸名或 `` `列` ``,与 schema 对齐) |
| `标签` | 展示文案(字面量) |
| `类型` | 控件/值类型:`text` `textarea` `number` `email` `url` `checkbox` `select` … |
| `必填` | 是否必填 |
| `默认` | 可选默认值 |
#### 5.5.2 校验表(作者面)
```markdown
`文章校验` =
| 字段 | 规则 | 消息 |
|------|------|------|
| title | required | 标题不能为空 |
| title | max:120 | 标题过长 |
| body | max:8000 | 正文过长 |
```
| 规则(初版) | 含义 |
|--------------|------|
| `required` | 非空 |
| `min:N` / `max:N` | 字符串长度或数值范围 |
| `email` / `url` | 格式 |
| `match:字段` | 与另一字段相等(如确认密码) |
| `in:a,b,c` | 枚举 |
schema 上的「可空 / 类型」在 **submit 时自动并入校验**(不必重复写 `required`,但校验表可覆盖消息)。
#### 5.5.3 行为流程
```text
render → 按字段表出 HTML(或嵌入 page 主区)
用户填写 → POST /_form/{id} 或同页提交
validate → 合并 schema + 校验表;失败则带回字段级错误、不写库
submit → action=insert → db.insert;action=update → db.update
→ 成功后刷新槽位或跳转(由 form 选项约定)
```
| 层 | 校验 |
|----|------|
| **服务端(必须)** | `validate` 在写库前执行;唯一可信边界 |
| **浏览器(可选增强)** | 同源规则可生成 `required`/`maxlength` 等 HTML 属性;**不能**替代服务端 |
`/admin` 的新建/编辑页 = 内置 form:字段来自 schema,校验来自类型/可空;与站点自定义 form **同一套** `validate` + `db.insert`/`update`。
#### 5.5.4 与页面的关系
- 表单可以是独立路由页,或页面表里的一个「组件」导出(仍用 `|属性|值|样式|` 描述展示,提交走 form 类)。
- **`page.compose_form id=… form=…`**:把 form 嵌入该页主区;`listen` 从首页与路由页收集表单并挂载 `/_form/{id}`(`app.mount_form` 仍可用)。校验失败时若表单有所属页,则带回该页壳重渲染。
### 5.6 文件职责
| 文件 | 内容 |
|------|------|
| `ext/web/web.mq.md` | 英文 `# page` `# style` `# db` `# form` `# app` |
| `ext/web/网页.mq.md` | 中文 `# 页面` `# 样式` `# 数据库` `# 表单` `# 应用`(可包装英文实现,**不得**把中文名写进 `web.mq.md`) |
---
## 6. 模块导出形状(配合寻址)
### 6.1 组件 `components/nav.mq.md`
```markdown
## nav
`nav` =
| 属性 | 值 | 样式 |
|------|-----|------|
| `title` | `nav`.`title` | |
| `href` | `nav`.`href` | |
**`nav`**
```
说明:组件**内部**绑定仍可用 `` `表`.`列` ``(表名+列名皆引用)。与 index 主体里「模块命名空间 + 裸列名」的 `articles.`articles`.title` 分工:
- **跨文件、带导入命名空间** → `模块.`表`.列`;
- **组件文件内、表已明确** → `` `表`.`列` `` 即可。
(若评审希望全站统一为一种形态,可在评审意见中二选一;默认允许上述两种。)
### 6.2 样式 `styles/shell.mq.md`
每个样式一个 `##`,**禁止** `## bag` + `json.set`:
```markdown
## topnav
… |属性|值| …
**`topnav`**
## card-title
…
```
### 6.3 库 `db/articles.mq.md` / `db/index.mq.md`
- `articles`:`## schema`(或同名导出)返回结构表;
- `index`:`## open` → 确保插件、建库、init、幂等种子,返回 `# 数据库` 句柄。
---
## 7. 运行时职责划分
```text
作者 .mq.md 表(字面量单元格)
│
▼
ext/web 类方法(Marqdo)
│ 解析路径;需要时经 ABI host_query
│ 调用入口模块 import 树上的 lib.member
▼
plugins/web(HTTP / SQL / HTML 壳)
│
▼
浏览器:四区布局 + /_part 局部刷新 + /admin(可选)
```
| 层 | 做 | 不做 |
|----|----|------|
| Marqdo 核心 | 表→Value、类/方法、import | 不识别 web 路径语法 |
| `ext/web/*.mq.md` | 作者 API、中英面、委托插件 | 不直接 `host_*` |
| `plugins/web` | 路径解析辅助、装配结果、listen、SQL、渲染 | 不要求作者写袋 |
**实现要点(评审通过后再做):**
1. ABI `host_query("call_lib_path")`:在**站点入口模块**上执行 `lib.member`;
2. 插件函数由类方法调用(如 compose_components / compose_main);
3. `listen` 合并页面内 part,注入 `db_url`。
---
## 8. 全部废弃 · 从头开发(锁定)
**旧有网络扩展库内容一律作废**,包括但不限于:
| 范围 | 处理 |
|------|------|
| [`plugins/web/`](../../plugins/web/) | 评审通过后**删除或清空**,按本文重写 cdylib |
| [`ext/web/`](../../ext/web/)(`web.mq.md` / `网页.mq.md` / templates) | 同上,**不**在旧 L1 上打补丁 |
| 依赖旧 API 的示例(如当前 `examples/web-site`、`web-demo`、`man-write-site` 可跑胶水版) | 按 §4 规范重写或暂时移除 |
| 依赖旧 API 的 gold / 单测 | 删除后按新 API 重写 |
| 本文之前的袋式 / assemble / wire / `## bag` 等作者面 | 永久移出正典 |
**禁止**:在遗留代码上「修到能跑」再文档化。
**允许**:实现时参考旧代码中的 HTTP/SQLite 技术经验,但**新树另起**,不以 ABI 表面或作者面兼容为目标。
历史摸索中明确不再回归的作者面模式:
- `json.parse` / `json.set` 拼 components/styles 袋;
- 手写 `web.assemble` + 袋参数;
- 手写 part JSON + `` `app`.part ``;
- `|前端变量|后端数据库|` 填路由;
- 「变量名即表名」魔法默认表;
- 样式 `## bag`;掏空 index 只留 `wire.boot`。
---
## 9. 非本波次(可记入路线图)
- Postgres / Redis / S3 驱动细节(SQLite 已落地);
- 复杂权限与多租户;
- 子页路由糖的更多约定(`# 应用.route` 已够用)。
---
## 10. 评审清单
请确认或批注:
1. **§3 路径**:`模块.`导出`` 与 `模块.`表`.列`(列裸名)是否定为唯一正典?组件内 `` `表`.`列` `` 是否保留?
2. **§4 index**:开库是否允许单独一行 `` db.open ``,还是必须进一步藏进 `web.应用`?
3. **§5 分文件**:英文 `web.mq.md` / 中文 `网页.mq.md` 是否严格分语言、禁止混排?
4. **§5.3**:列表查询用 `select` / `查询`、原始 SQL 用 `exec` / `执行` 是否认可?
5. **§5.5 表单/校验**:字段表、校验表、服务端必校、admin 共用是否认可?
6. **§5 槽位**:仅由组件导出名推断,是否足够?
7. **§8 废弃**:是否确认**全部推倒重来**、不兼容旧实现?
评审通过后:冻结本文为 Accepted → **清空旧 web 扩展代码** → 按本文从零实现(骨架 → db CRUD/`select` → form/validate → 页面装配 → app listen → 规范示例 → gold)。
+3 -3
View File
@@ -4,9 +4,9 @@
|---|---|
| 状态 | 草案(已采纳方向;修正「配置文件」误解) |
| 日期 | 2026-08-04 |
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) |
| 相关 | [OKF 调研](../research/okf-and-marqdo.md) · **实现规范 [okf.md](okf.md)** |
| 取代 | 此前「YAML = 人手写的编译器配置 / frontmatter 契约」的表述 |
| 说明 | 原则仍有效;**类型表、任务知识包、路线图以 [okf.md](okf.md) 为准** |
---
## 决策
@@ -28,7 +28,7 @@ Marqdo 项目中的 **YAML(及由其组成的 OKF 风格知识包)是工具
**唯一手写真相**仍是 `.mq.md` 源文件正文。YAML 清单是派生工件;过时则重新生成,禁止当成第二套权威配置去手改(除非工具链明确支持的「生成后微调」流程,且须可复现)。
**与源 frontmatter 的分工**(见 [markdown-mapping.md](markdown-mapping.md)):源文件 `---` 块可含 `title` 等元信息,以及人手声明的跨文件导入行 `> other.mq.md`。那是**源上的导入声明**,不是工程依赖锁。工具仍应据此(及正文 `>` 调用)**生成** OKF 风格依赖/模块目录;不要把生成目录手改成权威。
**与源 frontmatter 的分工**(见 [markdown-mapping.md](markdown-mapping.md)):源文件 `---` 块可含 `title` 等元信息,以及人手声明的跨文件导入行 `import other:other.mq.md`。那是**源上的导入声明**,不是工程依赖锁。工具仍应据此(及正文 `>` 调用)**生成** OKF 风格依赖/模块目录;不要把生成目录手改成权威。
---
+3 -3
View File
@@ -26,7 +26,7 @@ Marqdo 要中英文都能自然书写。标准库已约定「**库文件名区
| 层 | 是否导入 | 中英怎么区分 |
|----|----------|--------------|
| **L0 内核** | 否 | **同一文件内双名**:`print` ≡ `打印`;`True` ≡ `真` |
| **L1 标准库** | 是(`> lib/…`) | **不同文件**:`text.mq.md` vs `文本.mq.md`(见 i18n 草案) |
| **L1 标准库** | 是(`import …:lib/…`) | **不同文件**:`text.mq.md` vs `文本.mq.md`(见 i18n 草案) |
L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英文,写中文名就用中文,可在同一程序里混用。
@@ -36,7 +36,7 @@ L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英
### 3.1 字面量 / 逻辑关键字(词法保留)
控制流仍靠 Markdown(`#` `+` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。
控制流仍靠 Markdown(`#` `1.` `-` `*` `**`),**不**为 `if`/`while`/`def` 做中英关键字。形参用 `+`。
| 英文 | 中文(提案) | 备注 |
|------|--------------|------|
@@ -107,7 +107,7 @@ L0 **不做** `lang:`、不做「当前语言模式」;写英文名就用英
- 旧文「中文 `print` 废弃、统一为 `print`」:**废止**;改为正式双名 `print` / `打印`。
- [keywords.md](keywords.md) 原则条「英文标识」改为「**内核双名;标准库分文件**」——实现阶段改正文。
- 不引入中文控制流关键字(`如果`/`循环` 等);分支循环仍用 `+` / `-`。
- 不引入中文控制流关键字(`如果`/`循环` 等);分支用 `1.` …,循环用 `-`。
---
+5 -3
View File
@@ -11,7 +11,7 @@
## 1. 设计原则
1. **标记承担架构**:函数=`#`,分支=`+`,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
1. **标记承担架构**:函数=`#`,**形参=`+`**,**分支=`1.`…**,循环=`-`,返回=`**…**`,语句=`*…*`。因此 **不**把 `def`/`if`/`else`/`while`/`for`/`return` 做成关键字。
2. **内核双名**:字面量 / 逻辑词 / 五个核心内置函数均有中英别名,**无需导入**,可混用。
3. **学 Python 的边界**:区分 **关键字** vs **内置函数名**。
4. **宁少勿多**:扩展能力进可导入标准库(中英分文件,见 [stdlib-i18n.md](stdlib-i18n.md))。
@@ -43,6 +43,8 @@
| `str` | `文本` | 转为显示文本 |
| `int` | `整数` | 转为整数 |
**文本**:裸 token 按字面量;需 `\n` 等转义时用 `"..."`(见 [markdown-mapping.md](markdown-mapping.md) §7)。
形参别名:
| 英文 | 中文 | 用于 |
@@ -71,9 +73,9 @@
*`n` = 1*
+ `n` > 0
1. `n` > 0
> print text=positive
+ *
2. *
> 打印 内容=other
```
+186 -52
View File
@@ -1,11 +1,11 @@
# Marqdo 语法映射 v0.1(Markup-as-Syntax)
# Marqdo 语法映射 v0.2(Markup-as-Syntax)
| | |
|---|---|
| 状态 | 已定论(修订:语句 / 返回 / 输出职责分离) |
| 日期 | 2026-08-04 |
| 取代 | v0 中「`**`=输出、`*`=返回」 |
| 相关 | [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) |
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、同级再 `1.` 为新分支、标识符反引号、`-` 专用于循环) |
| 日期 | 2026-08-07 |
| 取代 | v0.1 中「函数头 `-` 形参 / 裸名形参与遍历变量 / `+` 分支」 |
| 相关 | [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))。
@@ -15,8 +15,13 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
1. `.mq.md`:打开即文档,运行即程序。
2. **叙述注释**以空行分段:段首无标记 → 注释;段内续行一律注释(见 §2)。
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` 表…)与 **斜体语句** / **粗体返回**。
4. 作用域 = `#` 层数;入口 = `index.mq.md`。函数体可用 `---` / `***` 或空返回收束(见 §11)。
3. **可执行**靠标记:结构标记(`#` `>` `+` `-` `1.` 表…)与 **斜体语句** / **粗体返回**。
4. **`#` = 对象/类型**,**`##`+ = 函数/方法**(嵌套按标题深度);入口优先 `# main`(见 [objects.md](objects.md))。函数体可用 `---` / `***` 或空返回收束(见 §11)。
5. **标识符默认反引号**:形参、绑定、引用写作 `` `名` ``,与 Markdown 无序列表/链接脱钩。
**豁免:**
- foreach 头 `` - [项](集合) `` 允许裸名或反引号(可混用),推荐裸名;循环体内引用仍用 `` `名` ``。
- 脚注取元 `` 名[^键] ``:基名在紧跟 `` [^…] `` 时可省略反引号(`` `名`[^键] `` 仍合法);链式同理。
- **斜体语句 / 粗体返回内部**:裸标识符默认是**变量**(含调用实参与方法接收者);文本字面量须 `"…"` 或 `'…'` 或引号实参(`key="文本"`);`` `名` `` 仍合法。这是 **Python 统一命名空间**:裸点号 `a.b` 在 `a` 为局部变量时为方法调用,否则为库路径。
---
@@ -29,23 +34,26 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
| 普通文字 / 空 | **注释** |
| 标记字符 | **代码** |
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
标记含:`#` `*` `>` `+` `-` `` ` `` `|`、有序数字 `1.`、围栏 `` ` ``、以及函数体内的结束分割线 `---` / `***`(见 §11)。
**成段注释(空行分段)**:段首一旦判定为注释,则直至下一空行之前的所有非空行一律为注释——即使续行以 `` ` `` / `-` / `*` 等开头也不升级为代码。叙述与可执行代码之间**必须空一行**。例外:单独一行的 `---` / `***` / `****`(函数结束或 frontmatter 闭合)始终为代码,并打断注释段。
---
## 3. 映射总表(v0.1)
## 3. 映射总表(v0.2)
| 标记 | 语义 |
|------|------|
| `#` … `######` | 函数;层数 = 作用域 |
| 函数头下 `-` 纯名 | 形参 |
| 体内 `-` | 循环 |
| 体内 `+` 或 `1.` | 分支 |
| 分支臂头整行恰为 `*` | else |
| `#` … `######` | **`#` = 对象/类型**(可 `# Child = > Parent`);**`##`+ = 函数/方法**(层差=嵌套)。见 [objects.md](objects.md) |
| 函数头下 `+ `` `名` `` ` | 形参 / 构造参数(可选 `` `名`=默认值 ``) |
| 体内 `1.` `2.` … | **分支**(有序列表臂;条件行或 else) |
| 体内 `-` | **循环**(`while` 条件,或 `[项](集合)` / `` [`项`](`集合`) `` 遍历) |
| 分支臂头整行恰为 `*`(在 `N.` 后) | else,如 `2. *` |
| `> 函数 形参=实参` 或 `> 函数 实参` | 调用(具名 / 位置,见 [call-arguments.md](call-arguments.md)) |
| frontmatter `> path.mq.md` | 跨文件导入 |
| `` > `对象`.方法 … `` | 方法调用(独立 `>`;实例 map 须含 `_type`)。`*…*` 段内接收者裸名:`*x = > 对象.方法 …*` |
| frontmatter `import bind:path.mq.md` / `导入` | 导入文件并绑定库名 |
| frontmatter `import bind:lib.member` / `导入` | 将库路径成员绑为本地短名(与文件导入同形) |
| `> lib.member …` / `> lib.Type.member …` | 点号路径调用(路径段裸名、无反引号) |
| `*…*` | **程序语句**(绑定、表达式句、可写的调用句等) |
| `**…**` | **返回值**(架构级;函数结果) |
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
@@ -55,13 +63,23 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
| ` ```lang ` | 外联异种代码 |
| 函数体内 `---` / `***` | **结束本函数体**(无返回值函数的收束;见 §11) |
### `+` / `-` / `1.` 消歧
| 位置 | `+` | `1.` … | `-` |
|------|-----|--------|-----|
| 函数标题后、**首条体语句前** | 形参:`` + `名` `` / `` + `名`=默认 `` | (非法) | (非法作形参) |
| 函数体内 | (非法作分支) | 分支臂:`1. `条件`` / `2. *` | 循环 |
**分支从未使用 `+`。** 自 v0 起即采用 GFM 有序列表;`+` 在 v0.2 专用于形参,与 `-` 循环彻底分离。
### 输出不是架构
| 错误(旧) | 正确(v0.1) |
| 错误(旧) | 正确(v0.2) |
|------------|--------------|
| `**Hello**` 表示打印 | `> print text=Hello` |
| 中文名 `输出`(已废弃) | 统一英文内置 `print` |
| 输出与返回抢粗体 | 粗体只表示 **返回** |
| `+ `x` > 0` 作分支 | `1. `x` > 0` |
| `- 谁` 作形参 | `` + `谁` `` |
| `[果](篮子)` 裸名遍历 | **仍合法**(foreach 豁免);亦可用 `` [`果`](`篮子`) `` |
`print` / `input` 为内置函数,完整表见 [keywords.md](keywords.md)。
@@ -72,22 +90,27 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
### 程序语句(斜体)
```markdown
*`x` = 1*
*`y` = `x` + 2*
*x = 1*
*y = x + 2*
*answer = ev[^message]*
*亦可用 = 1*
```
行首已是结构标记的构造(`#` `>` `+` `-` `|`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
斜体内部:裸标识符 = 变量;字符串写 `"…"` / `'…'`。行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包一层斜体;斜体用于「一般语句」槽位。
### 返回值(粗体)
```markdown
# 加一
- n
## 加一
+ `n`
**n + 1**
**"ok"**
**`n` + 1**
```
粗体内部与斜体相同的值语法(裸词 = 变量;文本须引号)。
### 输出(内置函数 `print`)
```markdown
@@ -98,7 +121,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
### else 与斜体消歧
- 分支臂**第一行整行只有一个** `*` → else。
- 分支臂有序行 `N. *`(或 `N.` 后仅 `*`)→ else。
- `*中间有内容*` → 程序语句。
- `**…**` → 返回(与 else 无关)。
@@ -106,14 +129,18 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
## 5. Frontmatter 与跨文件
同 v0:文件头 `---` 对为元信息;其中 `> file.mq.md` 为导入。
文件头 `---` 对为元信息。其中 `import bind:path.mq.md` / `导入` 为**文件导入**;`import bind:lib.member` 为**短名**(废除独立 `use` 与 frontmatter `>` 导入)。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法在独立 `>` 调用须 `` > `var`.method ``(`*…*` 段内接收者裸名)。详见 [module-namespace.md](module-namespace.md)。
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
---
## 6. 函数、作用域、提升
## 6. 对象、函数、形参
规则同 v0。推荐:
- `# Name`:对象(构造体);`# main` 为入口对象。
- `# Child = > Parent`:单继承(基类须为已定义对象名;方法沿链查找,子类可覆盖)。见 [objects.md](objects.md) §5。
- `##` / `###` …:函数或方法;挂在对象下则为方法。
- 标准库顶层 API 使用自由函数 `## name`(见 [objects.md](objects.md))。
```markdown
# main
@@ -121,53 +148,166 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
> print text=Hello World!
## 加问候
- 谁
+ `谁`
**你好,`谁`**
```
(需要打印时对返回值再 `> print`,或直接 `> print`。)
可选形参:
形参 `- 名` → 体内 `` `名` ``。
```markdown
## 问候
+ `谁`
+ `礼貌`=False
```
方法体内自动绑定 `` `自` `` / `` `self` ``。
---
## 7. 绑定与比较
## 7. 绑定、比较与字符串
| 写法 | 含义 |
|------|------|
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定(两种均允许;实现应统一) |
| `*`x` = 1*` 或行首 `` `x` = 1 `` | 绑定 |
| `` `x` == 1 `` | 相等比较 |
| `"text"` | **双引号字符串**(复杂文本;见下) |
| `hello` / `路径` | **裸 token**(无转义,按字面量) |
v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致;行首 `` ` `` 仍合法以便表格右值绑定。
### 双引号字符串(复杂文本)
需要转义或嵌入变量时用 `"..."`;**裸 token 不转义**,保持文档简洁:
```markdown
> input prompt="你叫什么名字\n"
*`msg` = "Hello, `name`!\n"*
```
| 转义 | 含义 |
|------|------|
| `\n` | 换行 |
| `\t` | 制表 |
| `\r` | 回车 |
| `\\` | `\` |
| `\"` | `"` |
| `\'` | `'` |
| `\xHH` | 十六进制字符(如 `\x22` → `"`) |
| `\u{...}` | Unicode 码点(如 `\u{4e2d}` → `中`) |
引号内仍可用 `` `变量` `` 插值。字面反斜杠+n 写 `\\n`(裸 token `\\n` 则就是两个字符)。未知转义(如 `\q`)按字面保留,不报错。
---
## 8. 分支与循环
分支(`+` / 有序),循环(`-`),语义同 v0。臂体内打印改为调用 `print`:
分支(**有序列表** `1.` `2.` …),循环(`-`):
```markdown
*`x` = 0*
+ `x` > 0
1. `x` > 0
> print text=正数
+ `x` < 0
2. `x` < 0
> print text=负数
+ *
3. *
> print text=零
```
```markdown
*`bool_value` = True*
1. `bool_value` == True
> print text=True
2. *
> print text=False
```
**一条分支语句 = 从 `1.` 起、序号递增的一段有序列表。** 同级缩进上**再次出现 `1.`**(无论中间有无空行)开启**下一条**独立分支语句,不得并入上一段的臂列表:
```markdown
1. `a`
> print text=A
2. *
> print text=not-A
1. `b`
> print text=B
2. *
> print text=not-B
```
上例为两次独立判断(先 `a` 再 `b`),不是「四个臂的一个分支」。臂序号在同一分支内递增(`1.` → `2.` → `3.` …);**不要**在同一分支中途把序号重置为 `1.`。
```markdown
- [果](篮子)
> print text=今天吃`果`
```
反引号形式等价:`` - [`果`](`篮子`) ``。两侧可混用。
`while`:
```markdown
- `n` > 0
> print text=`n`
*`n` = `n` - 1*
```
---
## 9. 集合(表格)
同 v0。`` `篮子` = `` 后接 GFM 表。
`` `名` = `` 后接 GFM 表;几何决定值类型(详见 [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md)):
| 形状 | 值 |
|------|-----|
| **1 列**(竖表) | `List`(表头 = foreach 元素名,不进入元素) |
| **≥2 列 + 1 行数据**(横表) | `Map`:键 = 表头,值 = 该列标量 |
| **≥2 列 + ≥2 行数据** | `Map`:键 = 表头,值 = 该列 `List`(列向) |
| **≥2 列 + 0 行数据** | `Map`:键存在,值为空列表 |
| **首列表头 `@` / `行` / `row`** | **行向** `List` of `Map`(标记列不进入字段;任意数据行数) |
| 重复表头 | 诊断错误 |
**数据单元格是表达式**(与调用实参值语法相同:裸词、数字、`` `var` ``、算术、引号串;URL / `gpt-4o-mini` 等按路径·连字符折叠为文本)。表头仍是键名文本。细则:[table-cell-expressions.md](table-cell-expressions.md)。
```markdown
*`k` = secret *
`cfg` =
| api_key | model |
|---------|-------|
| `k` | gpt-4o-mini |
```
行向示例:
```markdown
`订单` =
| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
| 2 | 梨 | 3 |
*`名` = `订单`[^1][^品名] *
```
**脚注取元**(表达式级;可链式):
```markdown
*`第一` = 篮子[^1] * # 基名可省略反引号(`[^` 已标明取元)
*`种` = 分类[^苹果] *
*`第一种苹果` = 货架[^苹果][^1] *
*`亦可用` = `分类`[^苹果] * # 反引号形式并存
```
- **List**:标签须为纯数字(1-based);`[^0]` / 越界 → 报错。
- **Map**:标签为键文本(含 `"00"` 这类数字串键);缺键 → 报错。同一外形按接收值类型分派,不把 map 上的 `[^1]` 当成「第 1 个条目」。
- 基名:`` `名`[^键] `` 与 `` 名[^键] `` 等价;无 `` [^ `` 时裸词仍是**文本字面量**(不是变量)。
- **插值中的取元**:在调用实参值 / 引号字符串里,`` `变量` `` 后**紧跟**(无空白)`` [^…] `` 时按取元解析,而不是字面文本:`> print text=苹果单价:`水果价格`[^苹果]`;链式 `` `货架`[^苹果][^1] `` 同理。`` `变量` [^…] ``(有空白)则 `` [^…] `` 仍是文本。
- 文末 `[^1]: …` 定义块仍是注释,与取元无关。
- foreach:`List` 遍历元素;`Map` 遍历**键**(值用脚注取)。
---
@@ -176,21 +316,19 @@ v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致
1. 加载 `index.mq.md` + 导入。
2. Pass1 收集定义。
3. Pass2 执行 `# main`。
4. `*` 语句、`**` 返回、`>` 调用、`+`/`-` 控制流、表绑定按语义执行;`> print` 写 stdout。
4. `*` 语句、`**` 返回、`>` 调用、`1.` 分支、`-` 循环、表绑定按语义执行;`> print` 写 stdout。
---
## 11. 函数体结束(`---` / `***` / 空返回)
无返回值(或已写完副作用)的函数,在体末用分割线收束,避免后续同级语句被吞进嵌套函数:
```markdown
# main
> 问候 谁=World
## 问候
- 谁
+ `谁`
> print text=Hello `谁`!
@@ -199,20 +337,16 @@ v0.1 **推荐**绑定写在斜体语句内,以保持「语句=斜体」一致
| 约定 | 说明 |
|------|------|
| `---` 或 `***` | 函数体**顶层**单独一行(长度 ≥ 3 且全为 `-` 或全为 `*`)→ **结束本函数**;后续语句属于外层 |
| `****` / 空粗体 | 空返回(值为 `None`),并同样结束本函数体 |
| 有值 `**expr**` | 普通返回;**不**自动截断后续兄弟句(仍可用分割线或下一同级/更浅标题收束) |
| Frontmatter | 仅**文件开头**成对 `---` = 元信息;与函数体内结束符消歧 |
| 分支/循环臂内 | 分割线仍可忽略(噪声),不截断外层函数 |
曾设想的「可选框住分支/循环」废止,分割线专用于函数收束。
| `---` 或 `***` | 函数体**顶层**单独一行 → **结束本函数** |
| `****` / 空粗体 | 空返回(`None`),并结束本函数体 |
| Frontmatter | 仅**文件开头**成对 `---` = 元信息 |
---
## 12. v0.1 非目标
## 12. v0.2 非目标
- break/continue、完整错误模型、静态类型、完整 FFI
- 用 `*` 作无序列表符
- `+` 作分支、`+`/`-` 作形参(**不保留**)
---
+220
View File
@@ -0,0 +1,220 @@
# 模块命名空间(import / 点号寻址)
| | |
|---|---|
| 状态 | **Accepted;统一 `import bind:target` 已锁定** |
| 日期 | 2026-08-13 |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [ext-agent.md](ext-agent.md) |
---
## 1. 动机
加载器曾把每个导入文件的顶层 `#` / `##` **扁平合并**进同一全局函数表;同名则**后导入静默覆盖**。
后果:
- `lib/json` 的 `parse` 与 `lib/time` 的 `parse` 不能共存。
- 官方 ext / 多库编排无法按大型语言习惯书写 `time.parse` / `json.parse`。
- 旧 frontmatter `import path:path.mq.md` 对 Markdown / 编辑器不友好,且与调用标记 `>` 抢外形。
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为可读的 `import bind:target`。
---
## 2. 目标与非目标
### 2.1 目标
1. **导入绑定库名**:导入一个 `.mq.md` 得到一个**库(模块)绑定**,成员不倒进全局。
2. **点号寻址调用**:`库.成员`、`库.对象.成员`;`.` 表示定义树寻址。
3. **库名不是变量**:路径段为**裸标识符**,不加反引号。
4. **短名与文件导入同形**:`import fmt:time.format`,废除独立 `use` 关键字。
5. **中英对等**:`import` / `导入`。
### 2.2 非目标
- 第三方包管理 / 版本求解。
- 旧 `> path.mq.md` / `> use` 双轨兼容。
- `` `time`.parse ``(库名加反引号)。
- `import fmt:time.*` 通配。
---
## 3. 核心语义
### 3.1 模块 / 库
| 内容 | 归属 |
|------|------|
| 顶层 `##` 自由函数 | 库根下的**函数** |
| 顶层 `#` 对象 | 库根下的**类型(对象)** |
| 类型下的 `##` 方法 | 该对象节点下的**成员函数** |
| 被导入文件的 `# main` | **不**作为入口执行 |
### 3.2 导入句法(frontmatter)
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。
| 含义 | 英文 | 中文 |
|------|------|------|
| 导入文件 | `import utils:utils.mq.md` | `导入 utils:utils.mq.md` |
| 标准库 | `import json:lib/json.mq.md` | `导入 json:lib/json.mq.md` |
| 短名(成员) | `import fmt:time.format` | `导入 fmt:时间.格式化` |
规则:
- **绑定名必填**,在 `:` 左侧(裸名,无反引号)。
- `:` 右侧 `target`:
- 以 `.mq.md` 结尾 → **文件导入**;
- 否则为 **点号路径**(≥2 段),把该成员绑为本地短名(须先有对应文件导入)。
- 同一文件内绑定名不得冲突(文件库名与短名共用命名空间)→ 硬错误。
- 旧写法 `> ….mq.md`、`> … as …`、`> use …`、`> 使用 …` → **硬错误**,并提示新句法。
### 3.3 废除的旧规则
不再支持:
- 省略绑定名时用文件名茎作库名;
- 导入侧 `as` / `作为`;
- 独立关键字 `use` / `使用`。
### 3.4 调用解析顺序
1. **点号路径 callee**(§4)→ 按段在导入库 / 类型树上寻址。
2. **当前文件**顶层 `#` / `##` 与 frontmatter **短名绑定**。
3. **L0 内置**。
4. **插件注册名**。
5. 否则 → 未知 callee。
---
## 4. 点号寻址(核心外形)
### 4.1 文法
```text
path_callee ::= ident ('.' ident)+
```
### 4.2 二段:`库.成员`
```markdown
---
import time:lib/time.mq.md
import json:lib/json.mq.md
---
# main
*t = > time.now_unix*
*s = > time.format unix=`t` pattern="%Y-%m-%d"*
*obj = > json.parse text={"a":1}*
*a = > json.get value=`obj` key="a"*
> print text=`s`
```
### 4.3 三段:`库.对象.成员`
```markdown
> agent.agent # 库 → 类型:构造
```
实例方法须 `` > `var`.method ``;无接收者的 `库.类型.方法` → 硬错误。
### 4.4 变量 / 实例 vs 库路径(Python 统一命名空间)
| 写法 | 含义 |
|------|------|
| `time.parse` | 库路径(裸名,第一段非变量) |
| `` > `助手`.step `` | 独立 `>` 调用:实例方法(接收者反引号) |
| `*回复 = > 助手.step …*` | `*…*` 段内:若 `助手` 是变量 → 实例方法;否则 → 库路径 |
**统一规则**(与 Python 一致):对裸点号 `a.b`,当 `a` 是当前作用域**局部变量**时解释为**方法调用**(`a` 为接收者);否则解释为**库路径**(`lib.a.b`)。此规则同时应用于树遍历与字节码两后端。
- 在**独立 `>` 调用**中裸词 = 文本,故方法接收者仍须反引号:`` > `助手`.step ``。
- 在 **`*…*` / `**…**` 段内**裸词 = 变量,接收者不加反引号:`*回复 = 助手.step …*`。
### 4.5 短名示例
```markdown
---
import time:lib/time.mq.md
import fmt:time.format
---
# main
*t = > time.now_unix*
*s = > fmt unix=`t` pattern="%Y-%m-%d"*
```
### 4.6 应用侧完整示例
```markdown
---
import time:lib/time.mq.md
import writeback:lib/writeback.mq.md
import agent:ext/ai/agent.mq.md
import json:lib/json.mq.md
---
# main
*`助手` = > agent.agent model=… tools=… *
*`out` = > `助手`.step task=… *
*`body` = > json.stringify value=`out` *
> writeback.record value=`body` key=ok
```
---
## 5. 导出面
默认:库内顶层 `#` / `##` 均可被路径访问。本版不引入 `private`。
---
## 6. 与旧行为的关系(破坏性变更)
| 旧 | 新 |
|----|----|
| `import time:lib/time.mq.md` | `import time:lib/time.mq.md` |
| `import t`:lib/time.mq.md | `import t:lib/time.mq.md` |
| `import fmt`:time.format
| 茎名默认库名 | 绑定名始终显式 |
| 扁平合并进全局 | 仅库绑定 + 可选短名 |
不提供旧 `>` 导入过渡开关。
---
## 7. 对分层与 ext 的影响
| 层 | 影响 |
|----|------|
| L0 内置 | 仍为全局短名 |
| L1 / 官方 ext | 经库路径调用;**`ext/**/*.mq.md` 严禁 `host_*`** |
| ABI 插件 | 插件注册表 |
---
## 8. 实现要点
1. frontmatter 只解析 `import` / `导入` 行;右侧分流文件 / 成员。
2. AST 仍用 `Import`(文件)与 `Use`(短名)存储,对外无 `use` 关键字。
3. 金样例:`tests/structure/import/`、`tests/structure/ns/`。
| 阶段 | 内容 |
|------|------|
| M1+M2 | 点号路径 + 短名 — 已落地 |
| **Import 句法** | 统一 `import bind:target` — **本波次** |
---
## 9. 决议摘要
1. 导入 = `import bind:target`(`导入` 等价)。
2. target = `.mq.md` 文件 **或** `库.成员` 点号路径。
3. 调用以裸名点号路径寻址;实例方法用反引号接收者(仅独立 `>` 调用;`*…*`/`**…**` 段内接收者不加反引号)。
4. 裸点号 `a.b`:`a` 为局部变量 → 方法调用,否则 → 库路径(Python 统一命名空间)。
+104
View File
@@ -0,0 +1,104 @@
# Objects(`#`)与函数(`##`+)
| | |
|---|---|
| 状态 | Accepted |
| 日期 | 2026-08-06 |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [ext-llm.md](ext-llm.md) |
## 1. 约定
| 标题层 | 含义 |
|--------|------|
| `#`(恰好一层) | **对象 / 类型**。正文 = 构造体;调用类型名 = 构造实例。 |
| `##` 及更深 | **函数**(自由函数或方法)。层数差表示嵌套,与 v0.1 相同。 |
`# main` 是**入口对象**:运行文件 = 执行其构造体。若无 `main`,且文件恰好只有一个无参顶层 `#` 对象(如 `# Hello World`),则把它当作入口。
## 2. 实例句柄
构造返回值若为 `map`,运行时写入 `_type`(文本,值为类型名),形成句柄。
方法调用通过 `_type` 找到定义对象,再解析其下的 `##` 方法。
方法体内自动绑定:
- `自`(中文)
- `self`(英文)
二者同一接收者。
## 3. 调用外形
```markdown
# 大模型
+ `模型名`
*自 = …配置 map…*
**自**
## 运行
+ `提示`
…使用 `自` …
**内容**
# main
*模型 = > 大模型 模型名="gpt-4o-mini"*
*回复 = > 模型.运行 提示="你好"*
> print text=`回复`
```
- `> 大模型 …` — 构造
- `` > `模型`.运行 … `` — 方法(接收者 + `.` + 方法名;**独立 `>` 调用**需反引号接收者 `` `模型` ``;**在 `*…*` / `**…**` 段内**接收者不加反引号:`*回复 = > 模型.运行 提示="你好"*`)
- `## 自由函数` 挂在模块顶层(非某对象子标题)— 与旧版顶层 `# http_get` 对等,现写为 `## http_get`
## 4. 标准库
官方 `lib/*.mq.md` 以**顶层自由函数**为主:全部为 `##`(不再使用 `#` 冒充类型)。
真正的类型化扩展(如 `ext/llm`)使用 `# 类型` + `##` 方法。
## 5. 继承(`# 子类 = > 父类`)
```markdown
# Greeter
## hello
+ `who`
*msg = "Hello, `who`!"*
**msg**
# Loud = > Greeter
## hello
+ `who`
*msg = "HELLO, `who`!"*
**msg**
```
| 规则 | 说明 |
|------|------|
| 语法 | `# Child = > Parent`(右侧必须是 `>` + 简单类型名;无路径) |
| `_type` | 构造后仍为**最具体子类名** |
| 方法查找 | 先子类 `##`,未命中再沿基类链;同名则子类覆盖 |
| 构造 | **不**隐式调用父构造(无 auto-super)。需要父字段时在子类正文首行显式 `` `self` = > Parent … ``,再改字段并 `**`self`**`;返回 map 的 `_type` 仍为子类名 |
| 多继承 | 不支持 |
| 诊断 | 未知基类、循环继承、非法 RHS(如 `# Foo = 1`) |
详见 [object-inheritance.md](../roadmap/object-inheritance.md)。
## 6. 非目标(本波)
- 接口 / 可见性 / 多继承
- 无 `_type` 的「鸭子」方法分发
- 用表格声明字段 schema(表格仍表示数据集合;见 [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md))
## 7. 迁移摘要
| 旧 | 新 |
|----|----|
| 库顶层 `# http_get` | `## http_get` |
| `# main` + `## 嵌套` | 不变(main = 入口对象) |
| `ext` 顶层 `# complete` | `# llm` / `# 大模型` 构造 + `## complete` / `## 运行` |
+482
View File
@@ -0,0 +1,482 @@
# Marqdo 的 OKF 实现
| | |
|---|---|
| 状态 | **Accepted(规范);实现分层见 §10** |
| 日期 | 2026-08-07 |
| 调研 | [okf-and-marqdo.md](../research/okf-and-marqdo.md) |
| 命令现状 | [catalog-cli.md](catalog-cli.md)(v0 已落地) |
| 生成式清单方向 | [generated-yaml-manifest.md](generated-yaml-manifest.md) |
| 智能体消费面 | [ext-agent.md](ext-agent.md) · [ext-agent-plan.md](ext-agent-plan.md) · 任务知识包见本文 §7 |
| 外部规范 | [OKF SPEC v0.2](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md) |
本文是 **Marqdo 语言侧 OKF 实现的详细设计**:界定我们借鉴什么、已经实现什么、下一阶段必须补什么。
**不把 Google OKF 整本照搬进语言语义**;Marqdo 的可执行真相永远是 `.mq.md` 源。
---
## 1. 定位
### 1.1 OKF 是什么(对我们)
[Open Knowledge Format](https://github.com/GoogleCloudPlatform/knowledge-catalog) 用 **目录中的 Markdown + YAML frontmatter** 表示可交换知识:概念一页一文、路径即 ID、链接成图、最小强制面(几乎只强制 `type`),并在 v0.2 加入信任信号。
Marqdo 对齐的判断是:
> 人类可读的 Markdown 可以成为人与 Agent 的一等交换面;**程序本身也应能投影成同一形态的知识包**。
### 1.2 Marqdo 多走的一步
| | OKF(通用知识) | Marqdo |
|--|-----------------|--------|
| 正文 | 自由散文 | **可执行语法**(`.mq.md`) |
| 成功标准 | 互通、可策展、可信任 | 能跑 + 能读 + 可被 Agent 索引 |
| 清单角色 | 知识本身 | **从源派生的投影**(非第二套权威配置) |
一句话:
**OKF 形、Marqdo 义 — 形态对齐 OKF;词汇与生命周期服务模块、依赖、任务技能与信任,而不是 BigQuery 业务概念表。**
### 1.3 三层文档(勿混)
| 层 | 谁写 | 是什么 |
|----|------|--------|
| **源** | 人 / 编码 Agent | `.mq.md`:唯一语义权威,打开即读、即可跑 |
| **工程目录包** | `marqdo catalog` | 模块依赖/导出总览(`Marqdo Module`) |
| **任务知识包** | `plan` 晋升等 | 任务↔技能↔可执行资源(`Marqdo Task` / `Marqdo Agent Skill`) |
`marqdo view output` 出 HTML 站点,与 OKF 包**分工**:人读程序站 vs Agent/工具读知识包。见 [view.md](view.md)、[catalog-cli.md](catalog-cli.md) §4。
---
## 2. 设计原则(锁定)
1. **源为唯一权威** — 依赖、导出、可执行行为以 `.mq.md` 为准;知识包是提取或晋升结果。
2. **生成、可复现** — 同一源树 + 同一工具版本 → 同一工程目录包(时间戳字段可规范化忽略)。
3. **勿手改生成物** — 文件头 / `generated` 标明 GENERATED;手改不被承认为权威。
4. **最小强制面** — 互通只要求:合法 frontmatter、`type` 字段、可解析的 `resource` / 链接;未知 `type` **必须优雅降级**(仍可读正文与已知字段)。
5. **格式而非平台** — 包可 `cat` / `git clone`;不绑定某一云或某一模型。
6. **清单可删可再生** — 无 catalog 时解释器仍能直接从源工作;catalog **不是**语言语义的一部分。
7. **可执行资源显式** — 凡声称「可跑」的概念必须有 `resource:` 指向 `.mq.md`(或等价路径),禁止只靠散文描述冒充程序。
---
## 3. 概念模型
### 3.1 Bundle(知识包)
一个 OKF 风格 bundle 是目录树:
```text
<bundle-root>/
index.md # 可选:人/Agent 总览
log.md # 可选:变更史(策展用)
catalog.yaml # 可选:机器向总清单
concepts/… # 或 modules/…:概念页(frontmatter + Markdown)
resources/… # 可选:被引用的可执行 .mq.md(任务包常用)
```
**Concept ID** = 相对 bundle 根、去掉扩展名的路径(OKF 惯例)。
例:`concepts/tasks/a1b2c3d4e5f6.md` → ID `concepts/tasks/a1b2c3d4e5f6`。
**联系** = frontmatter 中的路径字段 + 正文中的 Markdown 链接,形成可遍历图。
### 3.2 Marqdo 使用的两类 bundle
| Bundle | 默认根 | 生产者 | 消费者 |
|--------|--------|--------|--------|
| **工程目录包** | `.marqdo/`(`-o` 可改) | `marqdo catalog` / `sync` | 人、CI、未来编译加速、通用 Agent |
| **任务知识包** | `.marqdo/agent-kb/` | `ext/ai` 的 `plan` 晋升等 | 父智能体快路径、策展、复用 |
二者词汇共享(`type` / `generated` / `verified` / `status`),目录职责分离:
**不要**把探索用的 `agent-runs/` 时间戳文件当成稳定概念 ID。
---
## 4. Frontmatter 词汇表
### 4.1 所有概念页的公共字段
| 字段 | 必填 | 含义 |
|------|------|------|
| `type` | **是** | 概念类型字符串(见 §5) |
| `title` | 推荐 | 短标题 |
| `description` | 可选 | 一句话说明 |
| `tags` | 可选 | 字符串列表 |
| `resource` | 视类型 | 指向权威源或可执行 `.mq.md` 的相对路径 |
| `status` | 推荐 | `draft` \| `stable` \| `deprecated` |
| `generated` | 生成物必有 | `{ by, at? }` — 谁生成 |
| `verified` | 可选 | `{ by, at? }` — 谁核验(非 LLM 口述) |
| `sources` | 可选 | 出处列表(OKF v0.2) |
| `stale_after` | 可选 | 绝对日期,过期后消费者应降级信任 |
| 未知字段 | — | **保留、不拒绝** |
信任档位(推导,不必单独存字段):
| 条件 | 档位 |
|------|------|
| 无 `verified` | 未验证(机器生成草稿) |
| 有 `verified.by` 为确定性工具(如 `marqdo-agent/spawn`) | 机器确认 |
| 有人工审核约定(未来) | 人工审核 |
### 4.2 工程模块页额外字段(v0 已用)
| 字段 | 含义 |
|------|------|
| `depends` | 导入列表(从源 frontmatter `> path` 提取) |
| `exports` | 顶层 `#` 导出名列表 |
### 4.3 任务 / 技能页额外字段(目标词汇)
| 字段 | 所在 type | 含义 |
|------|-----------|------|
| `skill` | `Marqdo Task` | 指向 Skill 概念页的相对路径 |
| `goal` 或正文中的规范化 goal | `Marqdo Task` | 匹配材料(规范化规则见 §7.3) |
| `llm_free` | `Marqdo Agent Skill` | 资源是否仍含 `agent.step` / LLM 调用(机器启发) |
| `quality` | `Marqdo Agent Skill` | 整数启发分(长度、llm_free 等),**非**模型打分 |
---
## 5. `type` 注册表(Marqdo 义)
未知 type **不得**导致解析失败;工具可跳过专用逻辑,仍展示 title/正文/链接。
| `type` | 状态 | 含义 | 主要生产者 |
|--------|------|------|------------|
| `Marqdo Catalog` | **v0 已实现** | 包总览(`catalog.yaml` / `index.md`) | `marqdo catalog` |
| `Marqdo Module` | **v0 已实现** | 一个 `.mq.md` 模块的投影 | `marqdo catalog` |
| `Marqdo Task` | **规范已定;实现待做** | 一项可匹配的任务意图 | `plan` 晋升 |
| `Marqdo Agent Skill` | **规范已定;实现待做** | 指向可执行工作簿的技能 | `plan` 晋升 |
| 其他 | 开放 | 第三方/未来扩展 | — |
**不**引入 Google OKF 的 `Metric` / BigQuery 表类型作为 Marqdo 核心词汇;需要时可由用户包自行使用,运行时降级。
---
## 6. 工程目录包(v0 — 已实现)
### 6.1 CLI
```bash
marqdo catalog [PATH] -o OUT_DIR
marqdo sync [PATH] -o OUT_DIR # 别名
```
| 参数 | 默认 | 说明 |
|------|------|------|
| `PATH` | `.` | 工程根或单文件;目录则递归 `*.mq.md` |
| `-o` | `.marqdo` | 输出根;写入前创建,**覆盖**同名生成文件 |
实现:[`src/catalog.rs`](../../src/catalog.rs)。金样:`tests/gold.rs` → `catalog_writes_yaml`、`catalog_includes_agent_kb_concepts`。
### 6.2 生成物布局
```text
OUT_DIR/
catalog.yaml
index.md
modules/
<path-with-__>.md
concepts/ # O3:从 **/.marqdo/agent-kb/concepts/ 复制
tasks/…
skills/…
```
路径拍扁:`structure/import/main.mq.md` → `modules/structure__import__main.md`。
`agent-kb` 下的可执行 `.mq.md` **不**进 Module 表(避免与概念/资源重复);Task/Skill 概念页进 `concepts/` 与 `catalog.yaml` 的 `concepts:`。
### 6.3 `catalog.yaml`(现行字段)
```yaml
# GENERATED by marqdo — do not edit by hand
type: Marqdo Catalog
title: marqdo-project
generated:
by: marqdo/<crate-version>
modules:
- id: structure/hello # resource 去掉 .mq.md
resource: structure/hello.mq.md
title: … # 源 frontmatter title,否则用路径
imports: [] # 或 ["lib/x.mq.md as x", …]
exports:
- name: Hello World
kind: fn
# 可选(源 frontmatter 有则透传):
# verified: { by: … }
# sources: […]
concepts: [] # 或 Task/Skill 条目(O3)
# - id: concepts/tasks/<sig>
# type: Marqdo Task
# title: …
# status: …
# page: concepts/tasks/<sig>.md
# resource: …
# skill: …
```
提取规则:
- **imports**:源文件 YAML frontmatter 中以 `>` 开头的导入行(经 `parse_import_spec`)。
- **exports**:解析成功则用 AST 顶层函数名;否则回退扫描 `# ` 标题行。
- **verified / sources**:源 frontmatter 有则写入 module/concept 条目(O3)。
- **concepts**:扫描 `**/.marqdo/agent-kb/concepts/**/*.md`,复制到 `OUT_DIR/concepts/`。
- **不**提取正文 `>` 动态调用图、不写锁哈希、不写跨仓 URL。
### 6.4 模块概念页(现行)
```yaml
---
type: Marqdo Module
title: …
resource: path/to/file.mq.md
depends: […]
exports: […]
generated:
by: marqdo/<version>
# verified / sources:源有则透传
---
```
正文含「勿手改」、**可点击依赖链接**(解析到同包其它 Module 页)、导出表。`index.md` 含 Modules 表与 **Agent knowledge** 节(链到 `concepts/`)。
### 6.5 仍相对完整 OKF 愿景的缺口
| 缺口 | 说明 |
|------|------|
| 无通用 Concept ID 遍历 API | catalog 为生成物;无独立查询命令 |
| 无 `stale_after` / Attested 再现 | 信任信号仅可选 `verified`/`sources` |
| 无 `log.md` | 无策展历史(O4) |
| 运行时不读 catalog | 解释器不依赖生成物(有意为之) |
O2/O3 已补:Task/Skill 知识包、catalog 扫入 agent-kb、模块页可点依赖、可选信任字段。
---
## 7. 任务知识包(规范 — 实现路线 O2)
服务「父智能体优化过的工作簿,同任务应直接执行」:把子 Marqdo / 技能登记为 OKF 概念,用 ID 与链接匹配,而不是私有 `index.json`。
### 7.1 布局(锁定)
```text
.marqdo/
agent-runs/workbook-<slug>-<ts>.mq.md # 仅当显式 workbook_dir= 时(可 gc)
agent-kb/ # 任务知识包 bundle(默认首次 plan 就写这里)
index.md
log.md # 可选
catalog.yaml # 可选;可由 promote 或 catalog 刷新
concepts/
tasks/<slug>.md # type: Marqdo Task;sig 在 frontmatter
skills/<slug>.md # type: Marqdo Agent Skill
resources/
<slug>.mq.md # 默认可执行工作簿(探索与晋升同一路径)
```
默认根可通过 `plan` 参数 `kb_dir` / `知识库目录` 覆盖。`.gitignore` 已忽略 `**/.marqdo/`。
路径用可读 **slug**(由 goal 派生:拉丁小写、CJK 保留、其它变 `-`,最长约 48 字符)。**`sig` 仅写在 frontmatter**,用于精确匹配。同 slug 异 sig 时用 `slug-<sig前4位>`。旧包若仍以 `<sig>` 为文件名,lookup 会回退识别。
### 7.2 概念页模板
**Task**(匹配入口):
```yaml
---
type: Marqdo Task
title: <短摘要>
description: <规范化 goal>
sig: <12hex>
status: stable
tags: [agent-task]
skill: ../skills/<slug>.md
generated:
by: marqdo-agent/plan
verified:
by: marqdo-agent/spawn
at: <ISO8601>
---
# Task
See [skill](../skills/<slug>.md).
```
**Skill**(可执行绑定):
```yaml
---
type: Marqdo Agent Skill
title: <短名>
sig: <12hex>
resource: ../../resources/<slug>.mq.md
status: stable | candidate
llm_free: true | false
quality: <int>
hits: <int>
generated:
by: marqdo-agent/plan
at: <ISO8601>
verified:
by: marqdo-agent/spawn
at: <ISO8601>
---
# Skill
Prefer spawning `resource` over re-planning.
```
`status`:`llm_free` 的 resource 晋升为 **stable**(零父 LLM 快路径);否则为 **candidate**(可复用,但按 `improve_every` 偶发再优化,每轮最多 1 次改进)。失败运行不晋升;质量更差不覆盖。
### 7.3 任务签名 → Concept 路径
材料:
1. `goal`:Unicode NFC → trim → 连续空白折叠为单空格。
2. 若调用方工具表非空:工具名排序后追加进材料。
3. **不**把父 `standing` 计入签名(易变导致永不命中)。
输出:稳定短哈希 `sig`(`agent_goal_sig`)+ 可读 `slug`(`agent_goal_slug`)。路径:
- `concepts/tasks/<slug>.md`
- `concepts/skills/<slug>.md`
- `resources/<slug>.mq.md`
匹配顺序:
1. **精确**:slug 试探 + frontmatter `sig` → 扫目录 `sig:` → 旧 hex 文件名。
2. **别名(Accepted)**:精确 miss 后,扫 Task FM `aliases:`(YAML 列表或 `[a, b]`);`normalize_goal(query)` 与某条 alias **精确相等**则命中同一 Skill/resource。lookup 返回 `match: exact|alias`;`plan` 对 alias 写 `cache=soft-hit`。
3. **规范句(Accepted)**:仍 miss 时对 goal 做轻量 `agent_kb_canonicalize`(剥站立前缀、去尾标点),再精确/别名各试一次;命中返回 `match: canonical`,`cache=soft-hit`。
4. **近义(Accepted,默认开)**:仍 miss 且 `near_match=True` 时,对 Task `title|description|aliases` 做本地**字符 bigram 词袋 + 余弦**;`best.score >= near_threshold`(默认 `0.78`)则 `match: near` 并带 `score`,`cache=soft-hit`,并可 `agent_kb_add_alias`。这是稀疏词法近邻,**不是** embedding 模型。
5. **父裁决 soft_match(Accepted,默认关)**:仍 miss 且 `plan soft_match=True` 时,把 `agent_kb_near_match` 排序候选(含 score;空则退回 `list_tasks`)交给父模型:`DECISION: REUSE` + `SLUG:` 或 `DECISION: NEW`;REUSE 后可 `agent_kb_add_alias`。
6. **不做**默认 dense embedding / 远程向量库。远期 dense 仍见 [okf-near-match.md](../roadmap/okf-near-match.md) E。
`agent_kb_promote` 可选 `aliases=`(字符串或列表)写入 Task;再晋升时合并既有 aliases。
### 7.4 与 `## plan` 的契约
| 参数 | 默认 | 含义 |
|------|------|------|
| `reuse` / `复用` | `True` | 允许知识包快路径 |
| `optimize` / `优化` | `False` | 跳过知识包,强制再规划 |
| `force` / `强制` | `False` | 忽略知识包 |
| `soft_match` / `软命中` | `False` | miss 后父裁决 REUSE/NEW(须显式打开;候选为 near 排序列表) |
| `near_match` / `近义命中` | `True` | lookup 第四趟本地 n-gram;`False` 关闭 |
| `near_threshold` / `近义阈值` | `0.78` | near 自动命中最低余弦分 |
| `promote` / `晋升` | `True` | DONE 后固化并写入/更新概念与 resource |
| `kb_dir` / `知识库目录` | `.marqdo/agent-kb` | bundle 根 |
| `workbook_dir` / `工作簿目录` | `None` | 默认直接写 `kb_dir/resources/<slug>.mq.md`;显式传入则用该目录下的临时 `workbook-<slug>-<ts>.mq.md` |
| `improve_every` / `改进周期` | `3` | candidate 每 N 次命中触发 ≤1 轮改进 |
| `explore_n` / `探索次数` | `3` | 同任务已有文件数 `< N` 且非 `llm_free` 时,强制新建 `explore/<slug>/<k>.mq.md` 尝试不同路径(第 2 次默认 dual 骨架) |
调用示例(路径可直接写在参数里,无需 `json.parse`):
```markdown
> `助手`.plan goal=… max_rounds=3
> `助手`.plan goal=… workbook_dir=".marqdo/agent-runs"
> `助手`.plan goal=… explore_n=3
```
快路径:
1. lookup 命中且 resource **llm_free**(含现场检测已固化源)→ spawn → `cache=hit`,**父 LLM 不调用**。
2. 否则若任务相关文件数 `< explore_n` → 写入新的 explore 变体,父 LLM 被提示尝试不同路径;成功则固化并晋升。
3. 否则走 candidate 命中 / `improve_every` 改进逻辑。
`DECISION: DONE` 时先 `agent_workbook_solidify`(把仍含 `worker.step` 的簿固化为 `# main` **返回**答案,而非仅 `print`),再晋升并写 `verified`。
显式 `workbook=` 续跑优先于知识包查找。
质量启发(覆盖 skill 时,不调模型):`llm_free` 优先;源更短优先;同质取较新。更差 `quality` 不覆盖现 skill。
### 7.5 自我成长如何落在 OKF 上
| 能力 | 机制 |
|------|------|
| 优化 | 规划循环固化代码 → 更优 `resources/<slug>.mq.md` |
| 迭代 | 同 Concept slug/`sig` 覆盖 resource + 刷新 `generated`/`verified` |
| 成长 | 命中快路径;`candidate`/`hits`/`improve_every` 驱动再优化;`log.md` 可审计 |
| 分发 | 整包 `agent-kb/` 可复制(格式即契约) |
---
## 8. 运行时与工具职责
| 组件 | 读 OKF? | 写 OKF? | 备注 |
|------|----------|----------|------|
| 解释器 / 字节码 VM | 否(语义) | 否 | 只跑 `.mq.md` |
| `marqdo catalog` | — | 工程目录包 | v0 |
| `plugins/agent`(`agent_kb_*`)+ `ext/ai` `plan` | 任务包 | 晋升时写任务包 | O2;**不**进核心 `src/host` |
| `lib/fs` | 通用文件 | 通用文件 | L1 包装 |
| `marqdo view` | 否 | 否 | HTML 另一轨 |
| 未来 `marqdo kb query` | 是 | 否 | 可选:按 type/tag/链接查询 |
agent-kb 运行时实现归属 **agent 插件**(`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / `agent_kb_record_hit` / `agent_workbook_solidify` / `agent_kb_task_files`),由 `ext/ai/agent` 调用;禁止把这些原语加回 `HostFn`。
解释器**不得**因缺少 catalog 而拒绝运行源文件。
---
## 9. 安全与边界
| 风险 | 对策 |
|------|------|
| 把生成物当配置手改 | 文档 + GENERATED 头;CI 可选校验 |
| 错误技能被复用 | 快路径必 spawn+inspect;失败标 `draft` 并重规划 |
| 签名过宽 | tools 指纹;文档强调 exact goal |
| 密钥进入知识包 | 继承 env;禁止把 key 写入 resource/概念正文 |
| 包膨胀 | runs 与 kb 分离;仅 DONE 晋升 |
| 与语言语义耦合 | catalog/kb 失败不影响 `marqdo run` 源文件 |
---
## 10. 实现路线
| 阶段 | 内容 | 状态 |
|------|------|------|
| **O0** | 调研 + 生成式清单方向 + `.mq.md` 后缀 | **done** |
| **O1** | `marqdo catalog` / `sync`:Module + Catalog YAML | **done**(v0) |
| **O2** | 本文锁定的任务知识包:`Marqdo Task` / `Agent Skill`;`plan` reuse/promote | **done**(host kb_* + plan 快路径) |
| **O3** | catalog 增强:`verified`/`sources` 可选;模块页可点击依赖;扫入 `agent-kb` 概念供人浏览 | **done** |
| **O4** | `log.md` 策展、可选 `kb query`、Attested-style「再现跑通」收据(非 BigQuery) | 远期 |
| **O5** | 相近任务软命中:aliases + canonicalize + 本地 n-gram `near` + `soft_match` 父裁决已落地;dense embedding 仍见 [okf-near-match.md](../roadmap/okf-near-match.md) E | **A/B/C/D-near done** |
O2 设计落盘后,智能体侧实现文档可薄化为指向本文 §7,避免两套真理。
---
## 11. 非目标
- 在 Marqdo 内核实现完整 OKF 验证器产品或云托管知识库。
- 用 OKF 清单替代模块命名空间 / 导入语义([module-namespace.md](module-namespace.md))。
- 强制用户提交 `.marqdo/` 进 git。
- **默认**语义相似检索 / 向量库(可选软命中见 O5 / [okf-near-match.md](../roadmap/okf-near-match.md);不进内核)。
- 跨仓技能市场(可后续在概念图上扩展)。
- 照搬 OKF `Attested Computation` 的 BigQuery executor 模型。
---
## 12. 与既有文档的关系
| 文档 | 关系 |
|------|------|
| [okf-and-marqdo.md](../research/okf-and-marqdo.md) | 调研;产业背景与借鉴边界 |
| [generated-yaml-manifest.md](generated-yaml-manifest.md) | 早期「生成式清单」方向;**词汇与原则并入本文,命令细节见 catalog-cli** |
| [catalog-cli.md](catalog-cli.md) | O1 CLI 与 v0 落盘的操作说明 |
| [ext-agent-plan.md](ext-agent-plan.md) | 多步执行;缓存/复用应引用本文 §7 |
| [ext-agent.md](ext-agent.md) | 框架总览;自写回 ≠ 跨调用 OKF 知识包 |
---
## 13. 决议摘要
1. Marqdo 的 OKF 实现 = **形态对齐 + Marqdo 类型词汇 + 生成/晋升管道**,不是语言换皮。
2. **O1–O3 已落地**(工程目录包、任务知识包、catalog 扫入 agent-kb + 人读链接图);**O4** 策展/查询为远期。
3. 可执行真相是 `.mq.md`;概念页负责**寻址、信任与联系**——人与 Agent 都是闭环里的一环。
4. 父智能体复用优化结果,应走 **Task → Skill → resource → spawn**,而不是私有 JSON 缓存主路径。
5. 未知 `type` 降级;无清单亦可运行源码。
---
## 14. 一句话
**Marqdo 用 OKF 风格的知识包索引程序与任务技能:源负责跑,概念负责找与信,catalog 与 agent-kb 分管工程目录与自我成长。**
+2 -2
View File
@@ -2,8 +2,8 @@
| | |
|---|---|
| 状态 | **已定(v1)** |
| 日期 | 2026-08-05 |
| 状态 | **已落地(v1)** |
| 日期 | 2026-08-06 |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
---
+10 -10
View File
@@ -26,16 +26,16 @@
| 导入 | 库内函数名(示例) |
|------|-------------------|
| `> lib/text.mq.md` | `trim` · `split` · `join` |
| `> lib/文本.mq.md` | `去空白` · `拆分` · `拼接` |
| `> lib/table.mq.md` | `rows` · `row_at` |
| `> lib/表.mq.md` | `行数` · `取行` |
| `import text:lib/text.mq.md` | `trim` · `split` · `join` |
| `导入 文本:lib/文本.mq.md` | `去空白` · `拆分` · `拼接` |
| `import table:lib/table.mq.md` | `put` · `rows` · `row_at` · list/map(见 [stdlib-table.md](stdlib-table.md)) |
| `导入 表:lib/表.mq.md` | `行数` · `取行` |
示例:
```markdown
---
> lib/text.mq.md
import text:lib/text.mq.md
---
# main
@@ -44,7 +44,7 @@
```markdown
---
> lib/文本.mq.md
导入 文本:lib/文本.mq.md
---
# main
@@ -59,8 +59,8 @@
| 导入 | 含义 |
|------|------|
| `> lib/text-en.mq.md` | 英文 API |
| `> lib/text-zh.mq.md` | 中文 API |
| `import text-en:lib/text-en.mq.md` | 英文 API |
| `import text-zh:lib/text-zh.mq.md` | 中文 API |
这与 §2.1 **等价可选**,不是第二套解析器:仍然是「写哪个路径就加载哪个文件」。
**优先推荐 §2.1**(`text` / `文本`),后缀形式留给需要 ASCII-only 路径的环境。
@@ -81,7 +81,7 @@
`JSON` 为专有缩写,**不强求**中文库名或中文 API 翻译。官方只提供:
```text
lib/json.mq.md # 中英文档均 `> lib/json.mq.md`;函数 parse / stringify / get / keys
lib/json.mq.md # 中英文档均 `import json:lib/json.mq.md`;函数 parse / stringify / get / keys
```
不设 `lib/数据.mq.md` 等平行文件。其余模块仍遵守 §2.1。详见 [stdlib-modules.md](stdlib-modules.md) §3.4。
@@ -93,7 +93,7 @@ lib/json.mq.md # 中英文档均 `> lib/json.mq.md`;函数 parse / stringif
| 层 | 内容 | 如何获得 |
|----|------|----------|
| **内置(L0)** | 极少:`print` `input` `len` `str` `int`(及语言字面量关键字) | 直接调用,无需导入 |
| **标准库(L1)** | 文本/表等扩展 API;**通常**中英各一套文件、各一套函数名(**JSON 例外**:仅 `lib/json.mq.md`) | frontmatter `> lib/…` |
| **标准库(L1)** | 文本/表等扩展 API;**通常**中英各一套文件、各一套函数名(**JSON 例外**:仅 `lib/json.mq.md`) | frontmatter `import …:lib/…` |
| **宿主原语(实现细节)** | 若 `trim`/`split` 等暂由解释器实现 | 仅供标准库包装调用;**文档与用户站引导走 L1**,不鼓励当「关键字」堆砌 |
日后若某能力足够「核心」,可再升格为 L0;升格前先留在 L1。
+1 -2
View File
@@ -198,8 +198,7 @@ src/host/math.rs # 数值、随机、对 formula 的 host 入口
src/host/plot.rs # SVG
lex/parse:空 RHS 赋值 + $$ 围栏 → Expr::Formula
Value::Num / Value::Formula
Interpreter.plots: Vec<String>
lib/math.mq.md · lib/数学.mq.md
Interpreter.plots: Vec<Stringimport math:lib/math.mq.md · lib/数学.mq.md
```
依赖:纯 Rust;不绑 SymPy。公式复杂度、采样点、SVG 大小设硬上限。
+100 -133
View File
@@ -1,32 +1,36 @@
# 标准库下一波(L1 扩展模块)
# 标准库 L1 模块
| | |
|---|---|
| 状态 | **五库 + 数学已落地**;下一波:**外联**([stdlib-foreign.md](stdlib-foreign.md)) |
| 日期 | 2026-08-05 |
| 本波范围 | 文件 / 系统 / 时间 / JSON / 网络 / 数学(已完成) |
| 下一波 | **外联**(本机解释器 / 具名围栏) |
| 暂缓 | — |
| 状态 | **已落地**: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) · [keywords-i18n.md](keywords-i18n.md) · [view.md](view.md) |
| 相关 | [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`) |
---
## 1. 目标
在现有 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本。标准库**必须导入**才可用。
在 `lib/text`·`lib/文本`、`lib/table`·`lib/表` 之上,把 Marqdo 推进到可写日常脚本与可选原生扩展。标准库**必须导入**才可用。
| 模块族 | 英文库 | 中文库 | 本波 |
| 模块族 | 英文库 | 中文库 | 状态 |
|--------|--------|--------|------|
| 文本(已有) | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 |
| 表(已有) | `lib/table.mq.md` | `lib/表.mq.md` | 已有 |
| **文件** | `lib/fs.mq.md` | `lib/文件.mq.md` | **做** |
| **系统** | `lib/sys.mq.md` | `lib/系统.mq.md` | **做** |
| **时间** | `lib/time.mq.md` | `lib/时间.mq.md` | **做** |
| **JSON** | `lib/json.mq.md` | **同文件(特例,§3.4)** | **做** |
| **网络(简)** | `lib/net.mq.md` | `lib/网络.mq.md` | **做** |
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | **下一波** |
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | **做** |
| 文本 | `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/sys.mq.md` | `lib/系统.mq.md` | 已有(含 `load_dotenv`) |
| 时间 | `lib/time.mq.md` | `lib/时间.mq.md` | 已有 |
| JSON | `lib/json.mq.md` | **同文件** | 已有(含 `quote`) |
| 网络 | `lib/net.mq.md` | `lib/网络.mq.md` | 已有(HTTPS + headers) |
| 数学 | `lib/math.mq.md` | `lib/数学.mq.md` | 已有 |
| 外联 | `lib/foreign.mq.md` | `lib/外联.mq.md` | 已有 |
| **插件** | `lib/plugin.mq.md` | `lib/插件.mq.md` | **已有**(加载 C ABI 共享库) |
| **自写回** | `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-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md)。
---
@@ -34,35 +38,73 @@
```text
用户 .mq.md
│ > lib/fs.mq.md
│ import fs:lib/fs.mq.md / import llm:ext/llm.mq.md
▼
L1 官方库(.mq.md)
L1 官方库 / 官方 ext(.mq.md)
│
▼
L0.5 宿主原语(Rust,英文蛇形)
L0.5 宿主原语(Rust)或 原生插件(ABI v1)
│
▼
OS / HTTP / 时钟 / …
OS / HTTP / 时钟 / 共享库 …
```
| 层 | 谁实现 | 用户是否直接调用 |
|----|--------|------------------|
| **L0** | 解释器内置 | 是(`print`/`len`/…) |
| **L0.5 宿主原语** | Rust(`src/builtin` 或 `src/host/`) | **原则上否**;供 L1 包装;金样例可直测 |
| **L1 官方库** | `lib/*.mq.md` | **是**(文档与用户站只教这一层) |
| **L0.5 宿主原语** | Rust(`src/host/`) | **原则上否**;供 L1 包装;ABI v2 `host_query` 仅插件可调 |
| **L1 官方库** | `lib/*.mq.md` | **是** |
| **官方 ext** | `ext/*.mq.md`(+ 可选 ABI 插件) | **是**(需显式导入 `ext/`);**禁止** `host_*`,经 `lib/*` 或插件注册名 |
规则:
> **已变更(M1+M2)**:[module-namespace.md](module-namespace.md) — 取消跨文件扁平合并;L1/ext 经**裸名点号路径**调用(`time.parse`、`agent.agent`;M2:`库.对象.成员` + `use`),库名不加反引号;实例方法须 `` `var`.method ``;不再靠 import 顺序覆盖同名。
1. **导入即选择语言**(JSON 除外):`lib/fs.mq.md` → 英文 API;`lib/文件.mq.md` → 中文 API(见 [stdlib-i18n.md](stdlib-i18n.md))。
2. **不设 `lang:`**。
3. 宿主原语保持英文;中英差异只存在于 L1 包装层(JSON 无第二套包装)。
4. 失败一律 `path:line:col: message`([stdlib.md](stdlib.md) §4)。
### 2.1 L1 薄包装 → 宿主(命名空间后必读)
点号路径 `net.http_post` / `json.stringify` 等解析到 **`lib/*.mq.md` 的 `##` 函数**,再转发 `host_*`。未在包装形参表声明的可选实参会被**静默丢弃**(曾导致 live agent 401:`Authorization` 等 `headers` 从未到达宿主)。
| 规则 | 说明 |
|------|------|
| 每个 `host_*` 包装 | 须在 `+` 形参表声明**全部**宿主可选参数,默认 `None`,并在 `**> host_…**` 中**原样转发** |
| `http_post` / `提交` | `content_type=None` 时宿主按默认 JSON charset 处理 |
| 已对齐(2026-08-07) | `net`/`网络`(headers、content_type、body)、`sys`/`系统`(load_dotenv、exec)、`ext/ai/llm`(load_env / 加载环境 path)、`json.stringify` indent、`foreign`/`外联` stdin、`math`/`数学` plot*/solve 可选项 |
**无**扁平合并回退;**无**裸名双轨兼容。
---
## 3. 核心模块 API 草图(L1)
## 3. 核心模块 API(摘要)
### 3.1 文件 — `fs` / `文件`
文件 / 系统 / 时间 / JSON / 网络 API 见下文历史草图(已实现)。补充:
### 3.2 系统 — 已含 dotenv
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `load_dotenv` | `加载环境` | 可选 `path` | 新写入的键数量;缺文件 → `0`;不覆盖已有环境变量 |
### 3.4 JSON — 已含 `quote`
| 函数 | 形参 | 结果 |
|------|------|------|
| `quote` | `text` | JSON 字符串字面量(含引号) |
### 3.5 网络 — HTTPS
仅 **HTTP / HTTPS**(ureq);可选 `headers=`(map)、`content_type=`。
### 3.6 插件 — `plugin` / `插件`
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `load` | `加载` | `path` / `路径` | 注册函数个数 |
| `unload` | `卸载` | (无) | `None` |
| `list` | `列出` | (无) | 已注册名列表 |
契约:[ext-abi.md](ext-abi.md)。路径受 cwd/fs_root 沙箱约束。
### 3.1–3.5 历史 API 草图
#### 文件 — `fs` / `文件`
| 英文 | 中文 | 形参(英 / 中) | 结果 |
|------|------|-----------------|------|
@@ -74,22 +116,19 @@ OS / HTTP / 时钟 / …
| `make_dir` | `建目录` | `path` / `路径` | `None` |
| `remove` | `删除` | `path` / `路径` | `None` |
约定:路径相对工作目录或绝对路径;二进制 I/O 本波不做;写/删默认需 `--allow-fs-write`(§6)。
### 3.2 系统 — `sys` / `系统`
#### 系统 — `sys` / `系统`
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `env_get` | `取环境` | `name` / `名` | 文本或 `None` |
| `env_set` | `设环境` | `name`, `value` / `名`, `值` | `None` |
| `load_dotenv` | `加载环境` | 可选 `path` | 见上 |
| `args` | `参数表` | (无) | 文本列表 |
| `cwd` | `工作目录` | (无) | 文本 |
| `exit` | `退出` | `code` / `码` | 不返回 |
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码(实现时写死语义) |
| `exec` | `执行` | `cmd`, 可选 `args` | 退出码 |
`exec` 默认关(`--allow-exec`);view / 静态站永不开放。
### 3.3 时间 — `time` / `时间`
#### 时间 — `time` / `时间`
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
@@ -99,130 +138,58 @@ OS / HTTP / 时钟 / …
| `sleep_ms` | `睡眠毫秒` | `ms` / `毫秒` | `None` |
| `parse` | `解析时间` | `text`, `pattern` / `内容`, `格式` | 整数秒或诊断失败 |
view 中 `sleep_ms` 设上限(如 5s)。
### 3.4 JSON — `json`(**中英同库特例**)
JSON 是专有缩写,**很难也不必要**做合规中文库名/API 翻译。本波定稿:
| 项 | 约定 |
|----|------|
| 唯一路径 | **`lib/json.mq.md`**(中英文档均导入此路径) |
| 函数名 | 国际通行英文:`parse` / `stringify` / `get` / `keys` |
| 形参 | 英文:`text` / `value` / `key` / `indent` |
| 不设 | `lib/数据.mq.md`、音译名、中文函数双份 |
这是对 [stdlib-i18n.md](stdlib-i18n.md)「一概念两文件」的**显式例外**;其它模块仍中英分文件。
#### JSON — `json`
| 函数 | 形参 | 结果 |
|------|------|------|
| `parse` | `text` | 值(见下) |
| `parse` | `text` | 值 |
| `stringify` | `value`, 可选 `indent` | JSON 文本 |
| `get` | `value`, `key` | 值或 `None` |
| `keys` | `value` | 文本列表 |
| `quote` | `text` | JSON 字符串字面量 |
**类型映射(草案)**:
| JSON | Marqdo Value |
|------|----------------|
| `null` | `None` |
| bool | bool |
| number(整数可表) | int |
| number(其余) | 文本(本波不引入 float)或诊断拒绝 |
| string | text |
| array | list |
| object | 倾向新宿主类型 **`map`**(`type` → `map`);否则体验差 |
`map` 为 L0.5 类型扩展,可与 json 同期或紧随;不阻塞 `fs`/`time` 先行。
### 3.5 网络(简)— `net` / `网络`
#### 网络 — `net` / `网络`
| 英文 | 中文 | 形参 | 结果 |
|------|------|------|------|
| `http_get` | `获取` | `url` / `地址` | 响应文本(或 map:status/body) |
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` | 同上 |
| `http_get` | `获取` | `url` / `地址` | 响应文本 |
| `http_post` | `提交` | `url`, `body`, 可选 `content_type` / `headers` | 同上 |
| `url_encode` | `编码地址` | `text` / `内容` | 文本 |
仅 **HTTP 明文**(HTTPS 本波未做,会诊断提示);短超时、响应体上限;默认需 `--allow-net`;view / 静态站默认关。
**路径字面量:** 具名实参里 `path=a/b` 会被解析成除法。请用无斜杠文件名,或先赋给变量再传入。
---
## 4. 中英路径总表(本波)
## 4. 中英路径总表
```text
lib/
text.mq.md / 文本.mq.md # 已有
table.mq.md / 表.mq.md # 已有
fs.mq.md / 文件.mq.md # 本波
text.mq.md / 文本.mq.md
table.mq.md / 表.mq.md
fs.mq.md / 文件.mq.md
sys.mq.md / 系统.mq.md
time.mq.md / 时间.mq.md
json.mq.md # 本波;中英共用,无第二文件
json.mq.md # 中英共用
net.mq.md / 网络.mq.md
# 暂缓:math / 数学 · foreign / 外联
math.mq.md / 数学.mq.md
foreign.mq.md / 外联.mq.md
plugin.mq.md / 插件.mq.md
ext/ # 非 stdlib
llm.mq.md / 大模型.mq.md
agent.mq.md / 智能体.mq.md
```
别名:`std/…` ≡ `lib/…`。
别名:`std/…` ≡ `lib/…`。扩展解析:`MARQDO_EXT` / `./ext` / 二进制旁 `ext/`。
---
## 5. 落地分期(本波 = M1–M5)
## 5. 安全与 view / 静态导出
| 期 | 内容 | 完成定义 |
|----|------|----------|
| **M1** | 宿主能力框架:权限旗标、`host` 分发、错误文案 | `--allow-*` 可测 |
| **M2** | `fs` + `time`(只读 fs + 时钟) | 中英库 + 金样例 |
| **M3** | `sys`(env/cwd/args;`exec` 默认关) | 同上 |
| **M4** | `json`(+ 可选 `map`) | 往返金样例;唯 `lib/json.mq.md` |
| **M5** | `net`(默认关) | 本地 mock 或录制夹具 |
**不做 M6/M7**(数学 / 外联):详稿仅存档,待五库稳定后再议。
文档站:`fs`/`sys`/`time`/`net` 英中各一页;`json` 可一页双语叙述、同一导入路径。
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**。差异仅在软退出 / sleep 钳制。相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。插件路径同沙箱。
---
## 6. 安全与 view / 静态导出
## 6. 一句话
### 6.1 行为一致
`marqdo run`、live `view`、`view output` 对标准库 **默认同一套能力**(读/写盘、HTTP、exec 均可用)。导入库即表示要用;不再要求 `--allow-*`。
差异仅在 **软退出**:
| | CLI `run` | view / capture / 静态导出 |
|--|-----------|---------------------------|
| `exit` | 结束进程 | 报诊断,不杀 view/构建进程 |
| `sleep_ms` | 默认可睡(有上限) | live 有上限;导出通常为 0 |
沙箱:相对路径落在源文件目录(或 view 根)下,防止 `..` 逃逸。
### 6.2 静态部署
访客浏览器 **不再执行** Marqdo;HTML 里是构建时冻结的输出。源码中的路径/URL 访客改不了、也触发不了新的 host 调用。审 PR 时审查写死的目标即可。
勿在静态页嵌入「用户可改 URL 再请求」的浏览器脚本。
---
## 7. 与现有库的关系
- `text` / `table` 继续纯包装、无 IO。
- JSON `stringify` ≠ `str`(显示)。
---
## 8. 刻意不做(本波)
- 数学库、外联/胶水库(及其依赖、权限旗标实现)。
- 数据库、异步事件循环、WebSocket、原始 TCP。
- float/复数进 L0。
- `lang:` 或按 locale 自动选库。
- 为 JSON 强造中文库名或中文 API 双份。
---
## 9. 一句话
**本波只落地文件 / 系统 / 时间 / JSON / 网络;JSON 中英共用 `lib/json.mq.md`;数学与外联暂缓。**
**L1 含文件 / 系统 / 时间 / JSON / 网络 / 数学 / 外联 / 插件;`ext/` 为可选官方扩展(llm、agent)。**
+29
View File
@@ -0,0 +1,29 @@
# 子任务标准库(subtask)
| | |
|---|---|
| 状态 | v2 |
| 库 | `lib/subtask.mq.md` · `lib/子任务.mq.md` |
## 定位
**并发**执行单元。`spawn` 四选一:
| 参数 | 执行方式 | `join` / `wait` 返回值 |
|------|----------|------------------------|
| `path=` | `marqdo run <file> --emit-result <tmp>` 子进程 | map `{ code, value, stdout?, stderr? }`(`# main` 返回值;quiet 时 piped 捕获 I/O 尾部,不 inherit TTY) |
| `fn=` + 可选 `args=` | 当前入口模块中的函数(进程内线程) | 函数返回值 `Value` |
| `code=` | 外联代码块(`Value::Code`)子进程 | stdout `Text` |
| `lang=` + `source=` | 外联源码子进程 | stdout `Text` |
`args=`:文件子任务为 `List`(命令行参数);函数子任务为 `Map`(形参绑定)或 `List`(按 `arg0`… 命名)。
`quiet=` / `静默=`(默认 `True`):仅影响 **文件** 子任务的 **TTY**。默认 **piped 捕获** stdout/stderr(父终端不被污染,`wait` map 带截断后的 `stdout`/`stderr` 供父智能体观察);`False` 时继承父进程 stdout/stderr(map 中 I/O 字段为空)。**答案载荷仍以 `# main` 返回值为主**(经 `--emit-result` 旁路)。外联子任务仍经管道收集 stdout 供 `join` 返回,不受此参数影响。
**事件转发(文件子任务)**:spawn 时设置 `MARQDO_EVENT_FORWARD=<临时 ndjson>`;子进程内 `EventBus.publish` 追加写入该文件;父在 `wait` 阻塞期间 tail 并 republish(加 `source=child`)。这样子 LLM `stream=True` 的 token 能进 `marqdo view` SSE,而不破坏 quiet TTY 契约。函数子任务在同进程内,本来就共享 EventBus。
父进程结束(含 panic)时 **KillOnDrop** 终止所有文件/外联子进程;函数线程标记为 killed 并 detach(无法强杀 OS 线程)。
`poll` → `{ status: running | done | failed, … }`;函数 done 时含 `value`,进程/外联 failed 时含 `code` 或 `error`。
Host:`host_subtask_*`(`src/host/subtask.rs`)。
+82
View File
@@ -0,0 +1,82 @@
# `lib/table` / `lib/表` — 列表与字典
| | |
|---|---|
| 状态 | **已落地**(可用级集合 API) |
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [table-cell-expressions.md](table-cell-expressions.md) · [roadmap/tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) |
---
## 1. 读写对
| 读 | 写 |
|----|----|
| 脚注 `` `xs`[^1] `` / `` `m`[^key] `` / 嵌套 `` `m`[^a][^1] `` | **`table.put` / `表.改`** |
`put` / `改` 的 `at=`(`于=`)与脚注同构:文本键、**1-based** 整数下标,或键/下标组成的路径列表。
```markdown
---
import table:lib/table.mq.md
---
# main
*`h` = > table.put in=None at=Authorization value=Bearer-x*
`xs` =
| v |
|---|
| a |
| b |
*`xs` = > table.put in=`xs` at=1 value=A*
```
`in=None` 且 `at=` 为单个文本键 → 新建单键字典。值一律不可变更新(返回新集合)。
---
## 2. 索引约定
| API | 基数 |
|-----|------|
| `put` / `改` 路径中的整数;脚注 `[^n]` | **1-based** |
| `at` / `row_at` / `set_at` / `insert` / `remove_at` / `slice` / `index_of` | **0-based** |
---
## 3. API 摘要(EN ↔ ZH)
| EN | ZH | 说明 |
|----|----|------|
| `put` | `改` | 按路径改一元(首选写入) |
| `len` / `rows` | `长度` / `行数` | 长度 |
| `at` / `row_at` | `取` / `取行` | 0-based 取元 |
| `append` / `prepend` / `concat` | `追加` / `前插` / `拼接` | 列表 |
| `insert` / `set_at` / `remove_at` / `pop` | `插入` / `改位` / `删位` / `弹出` | 列表位操作 |
| `first` / `last` / `slice` | `首` / `末` / `切片` | |
| `contains` / `index_of` / `reverse` | `含有` / `下标` / `反转` | |
| `clear` | `清空` | 列表或字典 |
| `get` / `set` / `delete` / `has` | `取键` / `设` / `删键` / `有键` | 浅层字典 |
| `keys` / `values` / `items` / `merge` / `size` | `键表` / `值表` / `项表` / `合并` / `键数` | |
| `empty_list` / `empty_map` | `空表` / `空字典` | |
嵌套改写优先 `put`/`改`;`set`/`set_at` 仅浅层。
---
## 4. 与 `lib/json`
| 用途 | 用 |
|------|----|
| 解析 / 序列化 / `quote` | `json.parse` · `json.stringify` · `json.quote` |
| 集合读写 | **`table.*` / `表.*`** |
| 兼容 | `json.set` / `json.append` / `json.get` / `json.keys` 仍为别名,新代码勿依赖 |
---
## 5. 宿主
`host_collection_put` + list/map 原语(见 `src/host/collection.rs`)。作者面经 `lib/table` / `lib/表` 调用,不直接写 `host_*`。
+59
View File
@@ -0,0 +1,59 @@
# 自写回标准库(writeback)
| | |
|---|---|
| 状态 | v1 已落地 |
| 日期 | 2026-08-07 |
| 库 | `lib/writeback.mq.md` · `lib/自写回.mq.md` |
## 定位
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` 的 `<!-- marqdo-out … -->` → `marqdo view` 在对应语句下显示 **output-card**。普通 Markdown 预览不显示该区域。
## 存储格式
```markdown
*`n` = > len value=`xs` *
<!-- marqdo-out
42
-->
```
命名槽(智能体成功/失败互不覆盖):
```markdown
<!-- marqdo-out ok
status=ok result=…
-->
<!-- marqdo-out error
pending
-->
```
- 注释内为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
- 默认在**调用行下方**插入或替换紧邻**无键**块
- `at_end=true`:替换文件末尾的**无键**块
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽(智能体单步用父调用行,即 `step` 语句下方);`ensure` 在缺失时写入占位且不覆盖已有正文。命名槽互不覆盖,也不使用文件末尾单块。
- `line=` / `行=`:显式锚点行号。子任务 / 异步写回必须带上,否则会锚到子任务内部调用行。主机侧有全局互斥锁,写前从磁盘重读入口源,避免并发写互相覆盖。
### 替换跨度与空行
替换 `<!-- marqdo-out … -->` 时,被替换跨度**包含**注释块结束 `-->` 后的**单个**换行符(不把该换行留在文件里)。这样多次 `record` **不会**在块下方累积多余空行。
命名槽仍锚在调用行(如 `step` / `写回`)下方;整簇结束后保留**一条**有意空行即可,且应稳定。
## API
| EN | ZH | 说明 |
|----|-----|------|
| `record` | `写回` | `value=`;可选 `at_end`、`key`、`line` |
| `get` | `取` | 可选 `at_end`、`key`、`line` |
| `clear` | `清除` | 可选 `at_end`、`key`、`line` |
| `ensure` | `确保` | `key=` + 可选 `placeholder=`、`line=`;槽已存在则不动 |
| `list` | `列出` | 全文所有输出块(命名槽含 `key` 字段) |
可选参数语法:`` + `参数名`=默认值 ``(与现有参数列表兼容)。
Host:`host_writeback_*`(`src/host/writeback.rs`);智能体侧经 `lib/subtask` 异步调用写回,避免阻塞推理主路径。
**与 `ext/ai/agent`:** `## step` / `## 单步` 在 D2 起 **默认自动** `record` 到 `ok`/`error` 槽(参数 `writeback=` / `写回=` 可关)。多步工作簿依赖此默认,见 [ext-agent-plan.md](ext-agent-plan.md) · [ext-agent.md](ext-agent.md)。
+29 -19
View File
@@ -2,12 +2,13 @@
| | |
|---|---|
| 状态 | **S0–S3 落地** |
| 日期 | 2026-08-04 |
| 相关 | [keywords.md](keywords.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [roadmap/next-phase.md](../roadmap/next-phase.md) |
| 状态 | **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) |
> **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。
> **下一波模块(本波:文件 / 系统 / 时间 / JSON / 网络;数学·外联暂缓)**:见 [stdlib-modules.md](stdlib-modules.md)。
> **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。
> **`ext/` 不是 stdlib**:官方可选扩展见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
---
@@ -15,8 +16,9 @@
| 层 | 内容 |
|----|------|
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at` |
| **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 / 用户站收录(随发版) |
---
@@ -28,7 +30,7 @@
| `len` | `value` | 文本标量数或列表长度 |
| `str` | `value` | 显示文本 |
| `int` | `value` | 整数(失败 → 诊断) |
| `type` | `value` | `none`/`bool`/`int`/`text`/`list` |
| `type` | `value` | `none`/`bool`/`int`/`text`/`list`/`map` |
| `trim` | `value` | 去首尾空白 |
| `split` | `value`, `sep` | 文本列表 |
| `join` | `value`, `sep` | 拼接文本 |
@@ -40,37 +42,45 @@
## 3. 官方库导入(S2)
Frontmatter:
Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可改)。成员经点号路径调用(`time.parse`、`json.get`),不倒进全局短名。完整语义见 [module-namespace.md](module-namespace.md)。
```markdown
---
> lib/text.mq.md
> lib/table.mq.md
import text:lib/text.mq.md
import table:lib/table.mq.md
---
```
调用示例:`> time.now_unix`、`> json.parse text=…`。需要本地短名时用 `导入 format`(冲突:time.format`(冲突 → 硬错误)。
`std/text.mq.md` 等价于 `lib/text.mq.md`。解析顺序:
1. 相对当前文件
2. `MARQDO_LIB`(可指向 `lib` 目录或仓库根)
3. 当前工作目录的 `lib/`
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
4. 可执行文件附近的 `lib/`(含 `cargo run` 的相对路径)
5. **内嵌 stdlib**(v0.1.2+,编译进二进制;无磁盘 `lib/` 时自动使用)
当前模块:
当前模块(API 多为 `##` 自由函数;见 [objects.md](objects.md)):
| 路径 | 导出函数 |
|------|----------|
| 路径 | 导出 |
|------|------|
| `lib/fs.mq.md` / `lib/文件.mq.md` | `read_text`… / `读文本`… |
| `lib/time.mq.md` / `lib/时间.mq.md` | `now_unix`… / `此刻秒`… |
| `lib/sys.mq.md` / `lib/系统.mq.md` | `env_get`… / `取环境`… |
| `lib/json.mq.md` | `parse` `stringify` `get` `keys`(中英同文件) |
| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`… / `获取`… |
| `lib/sys.mq.md` / `lib/系统.mq.md` | `env_get`…、`load_dotenv`… / `取环境`…、`加载环境`… |
| `lib/json.mq.md` | `parse` `stringify` `get` `keys` `quote`(中英同文件) |
| `lib/net.mq.md` / `lib/网络.mq.md` | `http_get`…(HTTPS)/ `获取`… |
| `lib/math.mq.md` / `lib/数学.mq.md` | 数值 / 随机 / 公式 / 绘图 |
| `lib/foreign.mq.md` / `lib/外联.mq.md` | 具名围栏外联 |
| `lib/plugin.mq.md` / `lib/插件.mq.md` | `load` / `unload` / `list`(原生 ABI) |
| `lib/writeback.mq.md` / `lib/自写回.mq.md` | `record` `get` `clear` `list` |
| `lib/subtask.mq.md` / `lib/子任务.mq.md` | `spawn` `poll` `wait` `kill` `wait_all` |
| `lib/text.mq.md` | `str_trim` `str_split` `str_join` |
| `lib/文本.mq.md` | `去空白` `拆分` `拼接` |
| `lib/table.mq.md` | `rows` `row_at` |
| `lib/表.mq.md` | `行数` `取行` |
| `lib/table.mq.md` | `put` 为首选写入;`rows`/`row_at` 及完整 list/map API — 见 [stdlib-table.md](stdlib-table.md) |
| `lib/表.mq.md` | `改` 为首选写入;`行数`/`取行` 及完整 list/map API |
规划中的 L1 扩展见 [stdlib-modules.md](stdlib-modules.md)。
完整清单见 [stdlib-modules.md](stdlib-modules.md)。
---
+138
View File
@@ -0,0 +1,138 @@
---
title: table cell expressions
status: Accepted
date: 2026-08-12
related: markdown-mapping.md · roadmap/tables-maps-footnotes.md · call-arguments.md
---
# 表单元格表达式(T5)
| | |
|---|---|
| 状态 | **Accepted** |
| 日期 | 2026-08-12 |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) · [call-arguments.md](call-arguments.md) |
---
## 1. 问题
v1 把 GFM 数据单元格一律收成 **字面量**(`Int` / `Text`)。结果虽是 `Map` / `List`,却不能写:
```markdown
`h` =
| api_key | model |
|---------|-------|
| `api_key` | `model` |
```
作者只好用 `json.set` 链或 JSON 字符串拼接——这是**实现缺口**,不是「字典只能装字面量」的语义必然。
---
## 2. 锁定规则
### 2.1 数据单元格 = 与调用实参相同的值语法
每个**数据**单元格(非表头、非分隔行)按 [`parse_call_arg_value`](../../src/parse/expr.rs) 解析,再在绑定求值时执行:
| 单元格写法 | 含义 |
|------------|------|
| `苹果` / `Alpha` | 裸词 → 文本字面量(与今日竖表兼容) |
| `42` | 整数 |
| `` `api_key` `` | 变量引用 |
| `` `a` + `b` `` | 普通表达式 |
| `True` / `假` / `None` | 布尔 / 空 |
| `"https://…"` / `".marqdo/x"` | 引号字符串(可含 `/`、插值) |
| `https://api.openai.com/v1` | **路径折叠**:无空格的 `Text/Text/…` 除法链收成整段文本(同调用实参) |
| `gpt-4o-mini` | **连字符散文**:不拆成减法(同调用实参) |
| `` /about ``、`` /chat/completions `` | 以 `/` 开头的路径散文 → 整段文本 |
| 空单元格 | 空文本 `""` |
### 2.2 表头仍是键名文本
表头单元格**不**求值:键 = trim 后的表头字符串(与今日一致)。不允许 `` | `k` | `` 当动态键(v1 非目标;需要时另文)。
### 2.3 几何语义不变
竖表 / 横表单行 Map / 多行列向 Map / `@`·`行`·`row` 行向记录——**形状规则不变**;只把「单元格 → `Expr::Literal`」换成「单元格 → 完整 `Expr`」。
求值已由解释器对 `Expr::List` / `Expr::Map` 递归完成,字节码后端已发射列表/字典,**无需新 AST 节点**。
### 2.4 求值时机
表出现在 `` `名` = `` 右侧时,在**该绑定语句**求值:单元格内变量读**当时**环境。构造函数体里的表与语句表规则相同。
### 2.5 错误
- 单元格表达式非法 → 与别处表达式相同的 `path:line:col` 诊断(行号取该表行)。
- 变量未定义 → 求值期报错。
- 不引入「单元格静默当字面量」的回退(除 §2.1 已列的路径/连字符折叠,与调用实参对齐)。
---
## 3. 作者示例(目标体验)
```markdown
*`api_key` = > sys.env_get name=OPENAI_API_KEY *
*`model` = "gpt-4o-mini" *
`handle` =
| api_key | base_url | model | suffix |
|---------|----------|-------|--------|
| `api_key` | https://api.openai.com/v1 | `model` | /chat/completions |
```
`handle` 为含运行时 `api_key` / `model` 的字典;静态 URL 与 suffix 仍可裸写(路径折叠)。
嵌套:
```markdown
*`prompt` = hello *
`msg` =
| role | content |
|------|---------|
| user | `prompt` |
*`messages` = > json.append list=None item=`msg` *
```
(列表字面量表仍可用竖表;需要「单行记录」时用横表或 `@` 行向表。)
---
## 4. 兼容性
| 旧写法 | 行为 |
|--------|------|
| 纯中文/英文词、整数 | **不变** |
| `gpt-4o-mini`、URL、`/path` | **不变**(折叠规则与调用实参一致) |
| 真正要做除法 / 减法 | 用空格或括号:`` `n` / 2 ``、`` `a` - 1 ``;或先在表外算再 `` `x` `` 填入 |
破坏性:几乎无。唯一需注意的是「想在单元格里写算术且两侧是裸词」——与调用实参同一套消歧。
---
## 5. 非目标(本阶段)
- 表头动态键
- 单元格内 `>` 调用(可用表外算完再引用)
- 单元格内多语句 / 分支
- 把叙述区(注释段)里的 GFM 表当成可执行(仍为注释)
---
## 6. 验收
| 项 | 标准 |
|----|------|
| 金样 | 横表单元格 `` `var` `` 读环境;竖表旧金样全绿 |
| 路径 | `https://…`、`/chat/completions`、`gpt-4o-mini` 仍为文本 |
| 扩展 | `ext/ai/llm` 构造可用表写入运行时字段,去掉无必要的 `json.set` 链 |
| 文档 | 本页 + roadmap T5 + markdown-mapping §9 同步 |
实现跟踪见 [roadmap/tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) **T5**。
+1 -1
View File
@@ -130,7 +130,7 @@
- 候选 A:TS + remark-gfm — 能否区分 `-`/`+` bullet、解析单列表格、读 strong/emphasis。
- 候选 B:Rust + comrak/pulldown — 同上。
- (可选)C 或 D 若团队有偏好再做。
2. **对照验收用例**(固定):`tests/structure/hello.mq.md`、`branch.mq.md`(`+`)、`collection.mq.md`(表)、含 `> x.mq.md` 的 frontmatter 行。
2. **对照验收用例**(固定):`tests/structure/hello.mq.md`、`branch.mq.md`(`+`)、`collection.mq.md`(表)、含 `import x:x.mq.md` 的 frontmatter 行。
3. **出 ADR**:选定「验证期实现」与(可选)「生产目标实现」是否同一语言。
4. **再**建仓库脚手架与测试——禁止在 ADR 前默认生成 `package.json` / `Cargo.toml` 当既成事实。
+11 -2
View File
@@ -13,7 +13,7 @@
| 路径 | 是否入库 | 职责 |
|------|----------|------|
| `doc/` | 是 | 开发者设计 / ADR / 路线图(单数 `doc`,勿再造 `docs/`) |
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / 特性迭代);**双语**:拉丁文件名 = 英文,中文文件名 = 中文编程,同目录并列 |
| `public/**/*.mq.md` | 是 | 用户可读、可执行、可下载的介绍(结构 / 关键字 / **stdlib** / 特性迭代);**双语**:拉丁文件名 = 英文,中文文件名 = 中文编程,同目录并列。stdlib 含 `plugin`;特性页覆盖对象与 `ext/`(llm / agent) |
| `public/index.html`、`public/pages/` | **否**(ignore) | `marqdo view output` 生成的 HTML |
| `tests/{structure,keywords,errors}/` | 是 | 金样例与失败夹具(含 errors) |
| 远程分支 `gh-pages` | 发布产物 | 发布整个 `public/`(源文件 + 生成 HTML) |
@@ -50,7 +50,16 @@ public/
---
## 4. 验收
## 4. 内容分层(用户站)
| 目录 | 内容 |
|------|------|
| `public/stdlib/` | L1 模块页(含 `plugin` / `插件`);概述注明 `ext/` 非 stdlib |
| `public/features/` | 迭代特性:树遍历、字节码、view、**对象**、**官方扩展** |
设计文档仍在 `doc/design/`(`objects.md`、`ext-llm.md`、`ext-abi.md`、`ext-agent.md`)。
## 5. 验收
1. `public/` 下每个 `.mq.md`(除纯工具模块外)`marqdo run` 退出码 0。
2. `view output public -o public` 后首页为欢迎页,侧栏无 errors。
+49 -4
View File
@@ -90,8 +90,16 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
## 4. 信息架构
侧栏文件索引 + 主区:结构(AST+注释;旁侧函数大纲可搜索)· 执行 · 源码。表达式为表面语法。
**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
侧栏文件索引 + 主区:结构(AST+注释)· 执行 · 源码。结构旁**右侧栏**(现有 outline 槽)为:
| 区块 | 内容 |
|------|------|
| **Functions** | 原函数大纲 + 搜索;可折叠(默认展开) |
| **Variables** | 跑完后的入口(`# main`)顶层绑定只读快照;List/Map/`@` 行向渲成 HTML 表;可折叠(默认展开) |
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板。
表达式为表面语法。**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
---
@@ -102,8 +110,44 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
| `GET` | `/` | 默认打开第一个 `.mq.md`(无文件时为空提示) |
| `GET` | `/file?path=…` | 单文件页 |
| `GET` | `/api/tree` | JSON 树(可选) |
| `GET` | `/api/events?path=…` | 可选长订 EventBus(调试);**Stream 面板默认不用**(避免页载常连导致标签页一直转圈) |
| `POST` | `/api/run` | JSON `{path, stdin?}` → **直接返回** `text/event-stream`(本次 run 的事件);结束后关流 |
| `POST` | `/api/foreign-run` | 外联代码块试跑 |
根目录锁死;拒绝 `..` 逃逸。
根目录锁死;拒绝 `..` 逃逸。默认页加载仍可整页执行;Stream 为增强路径。
### 5.1 Stream 面板(对齐主流 LLM 呈现)
**仅当**当前文件 frontmatter 导入了 `ext/ai/llm` / `大模型` 或 `ext/ai/agent` / `智能体`(及等价路径)时,在 live Execution 区显示;普通脚本页不出现该组件。
参考常见助手产品(思考折叠 + 正文流式、工具/子步骤独立卡片):**不要**把所有 SSE 事件打成一条混色终端日志。
| 区块 | 事件 | 呈现 |
|------|------|------|
| **Thinking** | `reasoning` | 可折叠;流式追加到同一块;默认展开直至本轮 `delta`/`done` 开始,之后可收起 |
| **Answer** | `delta` | **主文**;token 连续拼进同一段落(禁止每 token 换行);主色正文 |
| **Decision** | `decision` | 时间线条目标记(`RUN` / `CONTINUE` / `DONE` / `REUSE` / `NEW` + 可选 summary) |
| **Tool** | `tool_start` / `tool_end` | 父 Plan-and-Move 的 CALL/READ:名称 + kind;`tool_end` 可带截断 `result` |
| **Phase** | `decompose` | 父 pre-run 分解开始(workbook 链);填补「决策后到首 token」空隙 |
| **Child / Workbook** | `await` → `round` | `await`:Child **running…** 占位卡(quiet 子任务等待中);`round`:升级为完成卡(退出码 + 可选 `result`) |
| **Status** | `run_start` / `done` / `error` | 顶栏状态 + 错误行;嵌套 LLM `done`(无 `run_id`)只冲刷 drip,不改顶栏;终态 `done.result` 仅在无 Answer 时作摘要 |
**传输与流畅度(对齐 ChatGPT 类产品):**
1. **Run = 一次 `fetch` POST**,用 `ReadableStream` 读响应体里的 SSE 帧;**不要**页载常驻 `EventSource`。
2. **「Run with input」拦截表单**:`preventDefault` 后走同一 Stream `/api/run`,**禁止整页重载**;带 `?stdin=` 进入时 live 页也不再阻塞跑完,改为自动开 Stream。
3. **只改 Stream 对话框 DOM**;token **按动画帧合批一次写入**(rAF coalesce,不人为节流;打字感来自网络到达节奏)。
4. **Stick-to-bottom**:仅在用户仍贴底时跟随;程序化 `scrollTop` 产生的 scroll 事件忽略;上拉后不抢滚动,可点「↓ Latest」。
5. **Stop**:`AbortController` 中止 fetch。
6. **子任务并发进度**:`spawn` 立即返回;`wait` 阻塞父循环期间,子进程经 `MARQDO_EVENT_FORWARD` 把 EventBus 帧实时转发到父 SSE;view 把 `source=child` 的 delta 画进 Child 卡。quiet 仍不污染父 TTY。
视觉约束(与 §2 一致):
- 浅色内容面,不用深色「伪终端」底;Thinking 用次要字色 / 浅底。
- 一屏只突出 Answer;Thinking 与 Child 是附属。
- plan 多轮:每一轮 Child 一张卡;父侧 Thinking/Answer 按 decision 分轮,不清空历史。
事件字段约定(与 [agent-streaming.md](../roadmap/agent-streaming.md) 一致):`round` 可带 `result`(子 `# main` 返回值摘要);`reasoning`/`delta` 的 `text` 为增量。
---
@@ -113,4 +157,5 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
2. `view output public -o public`(或临时目录)生成可点的 `index.html`(首文件)与各 `pages/…`。
3. 静态页中执行区与 `marqdo run` 一致(未加 `--no-exec` 时);失败诊断路径无 `\\?\`。
4. 冷启动无明显外网依赖。
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
6. Stream:`fetch`+SSE 局部更新;Thinking/Answer 分栏;stick-to-bottom;rAF 合批;页载不常连 EventSource。
+82
View File
@@ -0,0 +1,82 @@
# VS Code 扩展 — 分支与提交约定
| | |
|---|---|
| 状态 | **强制约定**(勿在 `main` 提交扩展源码) |
| 扩展分支 | **`vscode-extension`** |
| 设计说明 | [vscode-extension.md](vscode-extension.md) |
---
## 1. 原则(必读)
| 分支 | 是否跟踪 `vscode-extension/` |
|------|-------------------------------|
| **`main`** | **否** — `.gitignore` 含 `/vscode-extension/` |
| **`vscode-extension`** | **是** — 扩展唯一源码所在分支 |
**禁止**在 `main` 上:
- 删除 `.gitignore` 里的 `/vscode-extension/`
- `git add vscode-extension/`
- 把扩展目录「合并进 main」以便发版
发版时从 **`vscode-extension` 分支检出**扩展目录打 VSIX(见 §4),**不是**把扩展提交进 `main`。
---
## 2. 日常开发(扩展)
```bash
git fetch origin
git checkout vscode-extension
cd vscode-extension && npm ci && npm run compile
```
改语法、CLI 检测、扩展版本 → **只在 `vscode-extension` 分支提交**:
```bash
git add vscode-extension/
git commit -m "vscode-extension: <简要说明>"
git push origin vscode-extension
```
---
## 3. 日常开发(CLI / 语言)
在 **`main`** 上改 `src/`、`lib/`、`public/`、`tests/` 等;**不要**顺带提交 `vscode-extension/`。
若本地为了调试 checkout 过扩展目录,工作区里可以有 `vscode-extension/` 文件夹,但应被 ignore,且 **`git status` 不应出现**该目录下文件。
---
## 4. 发版(CLI tag + VSIX)
1. **`main`**:打 tag(如 `v0.1.2`),CI 构建 `marqdo.exe` 等。
2. **VSIX**:Release 工作流在 tag 构建时执行:
```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
```
3. 本地脚本 `scripts/release-windows.ps1` 同样假定:先 `git checkout origin/vscode-extension -- vscode-extension`(或已在 `vscode-extension` 分支),再打 VSIX。
扩展版本号与最低 CLI 要求写在 **`vscode-extension/package.json`** 与分支 README,**不要**在 `main` 的 CHANGELOG 里冒充已合并扩展源码。
---
## 5. 给 Agent / 协作者
执行「更新 VS Code 插件」类任务时:
1. **切到或基于 `vscode-extension` 分支**改 `vscode-extension/**`
2. **不要**移除 `main` 上 `.gitignore` 的 `/vscode-extension/`
3. **不要**在 `main` 的 release 提交里包含 `vscode-extension/package-lock.json` 等大文件
4. 仅需在 `main` 更新时:改 `doc/design/vscode-extension.md`、Release 说明、**本文件** — 指针文档即可
---
## 6. 历史说明
v0.1.2 准备阶段曾误将 `vscode-extension/` 并入 `main`(并删除 ignore),导致推送体积过大。已恢复:**扩展仅 `vscode-extension` 分支**;`main` 只保留本约定与设计指针。
+5 -5
View File
@@ -3,9 +3,9 @@
| | |
|---|---|
| 状态 | **已定分支模型** |
| 日期 | 2026-08-05 |
| 代码分支 | **`vscode-extension`**(同仓库) |
| 目录 | 工作区 `vscode-extension/`(仅在该分支跟踪;**`main` 忽略**) |
| 目录 | 工作区 `vscode-extension/`(**仅在该分支跟踪;`main` 在 `.gitignore` 忽略**) |
| 提交约定 | **[vscode-extension-commit.md](vscode-extension-commit.md)**(必读,避免误提交到 `main`) |
---
@@ -13,8 +13,8 @@
| 分支 | 内容 |
|------|------|
| `main` | Marqdo 语言 / CLI / `public/*.mq.md` 源;**不**存放扩展实现 |
| `vscode-extension` | VS Code 扩展源码、开发规范、TextMate 语法 |
| `main` | Marqdo 语言 / CLI / `public/*.mq.md`;**不**存放扩展实现 |
| `vscode-extension` | VS Code 扩展源码、TextMate 语法、VSIX 发版 |
| `gh-pages` | 用户站生成 HTML |
```bash
@@ -22,7 +22,7 @@ git checkout vscode-extension
cd vscode-extension && npm install
```
规范入口(在该分支上阅读):
规范入口(在 **`vscode-extension` 分支**上阅读):
- `vscode-extension/README.md` — 目标与目录
- `vscode-extension/DEVELOPMENT.md` — 日常流程
+164
View File
@@ -0,0 +1,164 @@
# 调研:Marqdo `ext/web` 能否对接 Daphne / 业界应用服务器
| | |
|---|---|
| 状态 | **调研笔记** |
| 日期 | 2026-08-29 |
| 范围 | Daphne、Uvicorn、Gunicorn、Hypercorn 等 ASGI/WSGI 服务器;对照 Marqdo `plugins/web`(axum) |
| 相关 | [web-net-capabilities.md](web-net-capabilities.md) · [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) |
| 触发 | `app.listen` 已能本地起站;问「能否像业界一样用 Daphne 等服务器」 |
---
## 0. 一句话结论
**不能把 Marqdo 站点「塞进」Daphne / Uvicorn / Gunicorn 当 Python ASGI/WSGI 应用跑。**
Marqdo 的 HTTP 服务**已经是**应用服务器:`plugins/web` 内嵌 **axum + tokio**,由 `` `app`.listen `` / `` `应用`.监听 `` 绑定端口。这在 Rust 生态里的角色,约等于 Python 里的 **Uvicorn/Daphne**,而不是 Django/Flask「应用代码」。
业界生产部署要支持的,通常不是「换成 Daphne」,而是:
1. **反代 + TLS**(Nginx / Caddy / Traefik)→ 已文档锁定;
2. **进程监督**(systemd / Docker / k8s)→ 运维层,与框架无关;
3. (可选)多进程 / 多副本水平扩展 → 需会话外置等,见下文。
---
## 1. Daphne「等」服务器是什么
| 名称 | 协议面 | 典型搭档 | 角色 |
|------|--------|----------|------|
| **Daphne** | ASGI | Django Channels | Python 异步/WebSocket 参考服务器 |
| **Uvicorn** | ASGI | FastAPI、Django ASGI | 高性能 ASGI(常作 Gunicorn worker) |
| **Gunicorn** | 主要为 WSGI | Django/Flask | 进程管理 + worker;**不能**直接跑 ASGI/WebSocket |
| **Hypercorn** | ASGI | 需 HTTP/2/3 时 | ASGI 另一实现 |
| **Granian** | ASGI(Rust 实现) | Python 应用 | 用 Rust 加速 Python ASGI |
共同点:它们都假设应用暴露 **Python ASGI/WSGI callable**(`application` / `asgi.py`)。服务器负责 accept、协议解析、生命周期;**业务在 Python 进程里**。
2026 常见生产组合示例:
```text
Internet → Nginx/Caddy (TLS) → Uvicorn/Daphne (ASGI) → Django/FastAPI 应用
```
---
## 2. Marqdo 今天怎么起服务
```text
.mq.md(ext/web 作者面)
→ ABI:web_listen / 路由装配
→ plugins/web:组装 axum::Router
→ tokio TcpListener + axum::serve ← 这里就是「应用服务器」
```
关键事实(实现):
- `plugins/web/src/http.rs`:`TcpListener::bind` + `axum::serve`;
- 依赖:`axum` 0.8、`tokio` multi-thread;含 WS、multipart、中间件层;
- HTTPS:设计上 **进程内 TLS 不作为默认**;生产用反代终止 TLS + `cookie_secure`(见 [web-net-capabilities.md](web-net-capabilities.md) W7)。
因此:
| 问法 | 答案 |
|------|------|
| 能否 `daphne marqdo_app:app`? | **否** — 没有 Python ASGI 入口 |
| 能否 `gunicorn -k uvicorn.workers…`? | **否** — 同上 |
| 能否用 Nginx 反代到 `127.0.0.1:18085`? | **是** — 推荐生产路径 |
| Marqdo 有没有「业界级」HTTP 栈? | **有** — axum/hyper 即 Rust 侧业界默认之一 |
---
## 3. 分层对照(避免角色错位)
| 层级 | Python 典型 | Marqdo 对应 |
|------|-------------|-------------|
| 应用 / 路由 / 模板 / DB | Django / FastAPI | `ext/web` + `plugins/web` 装配 |
| 应用服务器(accept / HTTP / WS) | Daphne / Uvicorn | **内嵌 axum::serve** |
| 反代 / TLS / 静态边缘 | Nginx / Caddy | **外置反代**(文档已写) |
| 进程管理 | systemd / Gunicorn master | systemd / Docker / k8s |
把 Daphne 接到 Marqdo,相当于要求「用 Python ASGI 服务器去托管 Rust axum 应用」——协议面不匹配,没有现成插槽。
---
## 4. 若目标是「生产级部署」,已支持什么 / 还差什么
### 4.1 已支持(或已锁定)
| 能力 | 状态 |
|------|------|
| 本地 / 内网 `listen` | ✅ |
| HTTP + WebSocket | ✅(axum) |
| 反代终止 HTTPS | ✅ 文档路径 |
| 访问日志、限速、CORS、安全头等 | ✅ W1–W7 |
| 会话可 SQLite 持久化 | ✅(单机多启需注意) |
### 4.2 与「Daphne 集群」对等时仍需注意
| 主题 | 说明 |
|------|------|
| **多进程副本** | 每进程各自 `listen` 时,内存会话 / 内存 cache / 内存 WS hub **不共享**;多副本需 sticky session,或会话/缓存外置(Redis 等,驱动面已有雏形) |
| **优雅重启 / 零停机** | axum 可接 signal;未做成一等作者 API(运维可用 systemd + 反代) |
| **HTTP/2 末端** | 多由反代提供;进程内 HTTP/1.1 足够常见场景 |
| **与 Python 生态混部** | 可同机 Nginx 分流:`/api/py` → Uvicorn,`/` → Marqdo;**不是**共用一个 Daphne |
### 4.3 不建议的路线
1. **实现完整 ASGI 适配器让 Daphne 加载 Marqdo**
成本高、收益低:等于在 Python 进程里再调一层 FFI/子进程,丢掉 axum 直驱优势。
2. **把 axum 拆掉、改写为「纯应用、外挂任意服务器」**
Rust 没有统一 ASGI;外挂只能是自定义协议或「只当 CGI」,与当前架构相反。
### 4.4 可选增强(若要对标「可换服务器」的体验)
| 方向 | 含义 | 优先级建议 |
|------|------|------------|
| **A. 部署文档 + 示例 Compose** | Nginx/Caddy + `marqdo run` + systemd | **高**(满足绝大多数「业界部署」诉求) |
| **B. listen 运维旋钮** | workers 说明、graceful shutdown、Unix socket | 中 |
| **C. 多副本清单** | 会话/WS/cache 外置检查表 | 中 |
| **D. 反向:Marqdo 作边缘、反代到既有 ASGI** | 已可用 HTTP 客户端/路由外置服务 | 按需 |
| **E. ASGI bridge** | 明确 **非目标** | 不做 |
---
## 5. 推荐生产拓扑(等价于「Nginx + Daphne」)
```text
客户端
│ HTTPS
▼
Nginx / Caddy / Traefik ← TLS、压缩、限流、静态可旁路
│ HTTP proxy_pass
▼
marqdo run index.mq.md ← 内部 axum::serve(角色 ≈ Uvicorn/Daphne)
(host=127.0.0.1 port=18085,cookie_secure=True)
```
要点:
- Marqdo **只绑回环**;对外只暴露反代。
- WebSocket:反代需 `Upgrade` / `Connection` 正确转发(与反代 Daphne 相同注意点)。
- 多机:共享 DB(或 Postgres 驱动)、共享会话存储;WS 广播跨机需外置 pub/sub(当前 hub 为进程内)。
---
## 6. 结论与建议
| 问题 | 结论 |
|------|------|
| 能支持 Daphne 吗? | **不能直接托管**;协议是 Python ASGI,Marqdo 是 Rust axum 自托管。 |
| 能支持「业界服务器」吗? | **能**:用 **Nginx/Caddy 等业界反代** 挂在 `listen` 前面;应用服务器层已由 axum 承担。 |
| 缺的是换 Daphne,还是缺部署体验? | 主要是 **部署文档 / Compose / 多副本约定**,不是再嵌一套 ASGI 运行时。 |
**建议下一刀(若产品化):** 写一份 `examples/` 或 `doc/design` 下的「反代部署」最小样例(Caddyfile / nginx.conf + `cookie_secure`),而不是调研 ASGI bridge。
---
## 7. 参考
- 本仓:[web-net-capabilities.md](web-net-capabilities.md)(HTTPS 反代锁定)· [ext-web.md](ext-web.md)
- Daphne:Django Channels 参考 ASGI 服务器
- Uvicorn / Gunicorn worker:当代 Python ASGI 生产主流组合
- axum:Tokio 生态 HTTP 应用框架(Rust 侧与 Uvicorn 同层)
+265
View File
@@ -0,0 +1,265 @@
# 网络能力调研:从「能跑」到「完整项目」
| | |
|---|---|
| 状态 | **Accepted · W0–W7 + P3 完结**(2026-08-28 复核) |
| 日期 | 2026-08-26(初稿)· 2026-08-28(完结复核) |
| 相关 | [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) · [ext-abi.md](ext-abi.md) · [stdlib-modules.md](stdlib-modules.md) |
| 目标 | 盘点 `ext/web` + `plugins/web` + `lib/net` 现状,对照主流语言网络栈,给出「开发一个完整 Web 项目」所需能力的差距清单与补强路线 |
---
## 0. 一句话结论
**`ext/web` + `plugins/web` 已完成 W0–W7 + P3 路线图**:中间件/JSON API、数据层(连接池/事务/分页/FTS/迁移/外键/审计时间戳)、安全硬化(argon2/CSRF/会话持久化/限速/RBAC)、内容站点标配(SEO/RSS/Markdown/分页 UI)、上传下载/相册/ETag、sitemap/robots/错误页/重定向、WebSocket 广播与访问日志。足以在 Marqdo 上实现博客/CMS/中小型 API 站点;**未内置**的仅剩标签页模板(D6,可用路由+`db.count` 自建)与应用层反垃圾。边界不变:**纯解析进 `lib/net`,HTTP 服务器与领域能力进 `plugins/web` + `ext/web` 作者面**。
---
## 1. 现状盘点(2026-08-26 实测)
### 1.1 `lib/net`(标准库,L0.5 宿主原语薄包装)
| 能力 | 归属 | 现状 |
|---|---|---|
| `http_get` / `获取` | host `net.rs` (ureq) | ✅ GET,返回 `{status, body}` |
| `http_post` / `提交` | host `net.rs` | ✅ POST,默认 JSON CT |
| `http_request` / `请求` | host `net.rs` | ✅ 通用 method+body+headers |
| `http_post_sse` / `提交流式` | host `net.rs` | ✅ OpenAI 兼容 SSE 流式消费 |
| `openai_sse_parse` / `解析流式` | host `net.rs` | ✅ 离线 SSE 解析 |
| `url_encode` / `编码地址` | host `net.rs` | ✅ URL 编码 |
| `cookie_parse` / `解析Cookie` | host `net.rs` | ✅ RFC6265 子集(请求头/响应头) |
| `multipart_parse` / `解析多部分` | host `net.rs` | ✅ multipart/form-data 解析 |
| `markdown_parse` / `解析Markdown` | host `net.rs` | ✅ GFM/Markdown → HTML(纯解析,W4c) |
**标准库网络原语已齐备**:客户端 GET/POST/SSE、URL 编码、cookie、multipart、Markdown 解析。服务器侧上传/下载/ETag 在 `plugins/web`(A5/P3)。
### 1.2 `plugins/web`(ABI v2,领域能力)
**服务器侧已实现:**
| 域 | ABI | 能力 |
|---|---|---|
| 页面 | `web_page_new` · `web_compose_components` · `web_compose_main` · `web_page_query` · `web_page_order` · `web_page_link_prefix` · `web_page_css` · `web_page_detail` | 页面装配、列表/排序、CSS、详情页 |
| 样式 | `web_style` | GFM 表 → CSS(`make_style`/`样式装配`) |
| 表单 | `web_form_new/fields/rules/validate/render/submit/from_schema` · `web_compose_form` | 字段表、校验表、渲染、提交、schema→form |
| 数据库 | `web_db_new/init/insert/select/get/update/delete/exec/table_info/list_tables` | SQLite CRUD + where + order + limit |
| 应用 | `web_app_new/route/mount_form/static/auth` · `web_app_route_ws` | 路由、静态目录、admin、鉴权、WS 端点 |
| 会话 | `web_session_new/set/get/del/destroy` | 内存 TTL 会话 |
| 鉴权 | `web_auth_login/check/logout/new` · `web_app_auth` | `/admin` 登录门禁 |
| WebSocket | `web_ws_connect`(客户端)· `web_app_route_ws`(服务器) | 单请求-响应式客户端 + echo 服务器 |
**关键实现事实(2026-08-28 W7+P3 后):**
- **中间件 + JSON API**(W1):`app.configure` 装配 CORS、安全头、gzip、请求体上限、JSON 端点。
- **数据层**(W2/W6/W7/P3):连接池、事务、分页、OR/IN/BETWEEN、`db.count`、迁移、FTS5 搜索、init 唯一/索引/外键、审计时间戳。
- **安全**(W3s/P3):argon2、CSRF、SQLite 会话、CSPRNG session id、登录限速、RBAC(`app.gate` + 用户 `role`)。
- **内容站点**(W4c/W7):SEO `page.meta`、RSS、Markdown 正文、`page.paginate`、sitemap/robots。
- **媒体**(W5/P3):multipart 上传、下载、`app.gallery`、ETag/Cache-Control。
- **运维向**(W6/W7):访问日志、自定义 404/500、301/307 重定向、WS 广播;HTTPS 由反代终止 + `cookie_secure`。
- **仍属应用层约定**:标签聚合页模板(D6)、评论反垃圾、草稿/定时发布(表+where 即可)。
---
## 2. 主流网络栈对照(联网调研 2026-08)
### 2.1 分层共识(决定「标准库 vs 扩展」边界)
| 语言 | 标准库网络能力 | 扩展/框架能力 | 边界准则 |
|---|---|---|---|
| Python | `urllib`(HTTP 客户端)、`http.cookies`(cookie 解析器)、`http.server`(简易服务器)、`email` 多部分解析 | `requests`/`httpx`(连接池/session)、`FastAPI`/`Flask`(中间件/校验/模板) | 解析器进标准库;便利层/框架层在第三方 |
| Node.js | `node:http`(低层流式,**不解析 body**)、`node:https` | express、fastify、ws、formidable | 低层原语进核心;fancy 功能 userland 验证后再进 core |
| Go | `net/http`(服务器+客户端**都在标准库**)、`net/http/cookiejar`(RFC6265)、`net/smtp` | `golang.org/x/net`(演进性)、gin/echo | HTTP 与 stdin 同级的核心能力;cookie 解析进标准库 |
| Rust | 极小 std(无 HTTP) | `hyper`→`reqwest`→`axum` | 分层;HTTP 生态多样不进 std |
**对本项目的三处判定(与 [ext-web-net.md](ext-web-net.md) 一致并延伸):**
1. **纯解析原语**(cookie / multipart / url)→ `lib/net` 标准库。✅ 已达成。
2. **HTTP 服务器结构能力**(JSON / 中间件 / 上传下载 / HTTPS / 缓存头)→ `plugins/web`(ABI)。这是 axum 本身就在依赖链里的,不需要新增核心依赖。
3. **领域能力**(session / auth / 分页 / 搜索 / RSS / SEO / 限流)→ `plugins/web` + `ext/web` 作者面。
### 2.2 「完整 Web 框架」能力清单(FastAPI / Express / Flask / axum 共通项)
> **marqdo 列**反映 **2026-08-28 W7+P3 完结** 后状态(见 §3 差距表)。
| 能力 | FastAPI | Express | Flask | axum | marqdo |
|---|---|---|---|---|---|
| 路由(含动态参数) | ✅ | ✅ | ✅ | ✅ | ✅ 动态路由 `/post/{slug}` |
| 中间件管道 | ✅ | ✅ | ✅ | ✅(tower) | ✅ W1 `app.configure` |
| CORS | ✅ 内置 | ✅ 中间件 | ✅ flask-cors | ✅ tower-http | ✅ W1 |
| JSON 请求/响应 | ✅ 原生 | ✅ | ✅ | ✅ | ✅ W1 JSON API 表 |
| 校验(schema/字段) | ✅ Pydantic | 手动(zod) | 手动 | ✅ extractor | ✅ form 校验表 |
| 静态文件 | ✅ Starlette | ✅ | ✅ | ✅ | ✅ `app.static` |
| 模板/渲染 | ✅ Jinja | ✅ | ✅ | ✅ | ✅ GFM 表装配 |
| 会话 | ✅ | ✅ express-session | ✅ | ✅ | ✅ SQLite 持久化(W3s) |
| 鉴权 | ✅ OAuth2/APIKey | ✅ | ✅ | ✅ | ✅ admin + RBAC(P3) |
| 文件上传 | ✅ | ✅ multer | ✅ | ✅ | ✅ W5 upload |
| WebSocket | ✅ | ✅ ws | ✅ Flask-SocketIO | ✅ | ✅ echo + 广播(W6) |
| 安全头 | ✅ | ✅ helmet | ✅ | ✅ tower-http | ✅ W1 |
| 限流 | ✅ | ✅ | ✅ | ✅ | ✅ 登录限速(W3s) |
| 日志 | ✅ | ✅ morgan | ✅ | ✅ | ✅ access_log(W6) |
| gzip 压缩 | ✅ | ✅ | ✅ | ✅ | ✅ W1 |
| 分页 | 手动 | 手动 | ✅ paginate | ✅ | ✅ db + page UI(W2/W4c) |
| 迁移 | ✅ alembic | ✅ | ✅ | ✅ sqlx | ✅ W6 `db.migrate` |
| 测试工具 | ✅ TestClient | ✅ supertest | ✅ | ✅ | gold 测试(`tests/ext/web-*`) |
| HTTPS/TLS | 反代 | 反代 | 反代 | ✅ rustls | 反代 + `cookie_secure`(W7 文档锁定) |
---
## 3. 差距分析:按「完整项目」四类需求
### 3.1 类 A:结构化 HTTP 基础设施(做 API / 前后端分离 / SPA 支撑)
| # | 缺失能力 | 影响 | 归属 | 优先级 |
|---|---|---|---|---|
| A1 | **JSON 请求/响应**(`Json` extractor、`application/json` 响应、body 大小限制) | ✅ **已实现(W1)**:`接口` 表声明 JSON API 端点;`请求体上限` 配置 body 限制 | `plugins/web` | **P0 ✅** |
| A2 | **中间件管道**(`app.configure` / `应用.装配`:CORS、安全头、压缩、请求体限制统一挂载) | ✅ **已实现(W1)**:`middleware.rs` 装配 GFM 表并 `app.layer` 挂到 axum | `plugins/web` | **P0 ✅** |
| A3 | **CORS 支持**(`Access-Control-Allow-Origin` 可配) | ✅ **已实现(W1)**:`跨域` 表 `|允许来源|方法|头|暴露头|凭证|` | `plugins/web` | P1 ✅ |
| A4 | **安全响应头**(CSP / X-Frame-Options / X-Content-Type-Options / HSTS / Referrer-Policy / 去 `X-Powered-By`) | ✅ **已实现(W1)**:`安全` 表 `|头|值|` | `plugins/web` | P1 ✅ |
| A5 | **文件上传接收**(multipart extractor → 校验类型/大小 → 落盘)与**下载**(`Content-Disposition`) | ✅ **已实现(W5)**:`app.upload` / `app.download`;`file:` storage;离线 + curl live 金样 | `plugins/web` | P1 ✅ |
| A6 | **HTTPS / TLS**(rustls 终止或反代提示) | ✅ **文档锁定(W7)**:进程内 TLS 不启用;反代终止 HTTPS,并设 `cookie_secure=True` | 文档 + `cookie_secure` | P2 ✅ |
| A7 | **gzip / br 压缩** + **ETag / Cache-Control 缓存头** | gzip ✅(W1);Cache-Control ✅(W7);ETag ✅ **已实现(P3,下载/相册 + If-None-Match→304)** | `plugins/web` | P2 ✅ |
| A8 | **访问日志**(请求方法/路径/状态/耗时) | ✅ **已实现(W6b)**:`configure access_log=True` → stderr | `plugins/web` | P2 ✅ |
| A9 | **自定义 404/500 错误页** | ✅ **已实现(W7)**:`app.error_page` / `应用.错误页`;404 fallback + 500 页袋 | `plugins/web` | P2 ✅ |
| A10 | **重定向增强**(permanent/自定义状态码) | ✅ **已实现(W7)**:`app.redirect` → 301/307 | `plugins/web` | P3 ✅ |
### 3.2 类 B:数据层深化(内容站点/社区的根基)
| # | 缺失能力 | 影响 | 归属 | 优先级 |
|---|---|---|---|---|
| B1 | **连接池 / busy_timeout / WAL** | 高并发下 `database is locked`、每请求重连开销 | `plugins/web`(db.rs) | **P0 ✅** |
| B2 | **事务 API**(`begin` / `commit` / `rollback`,或 `with_transaction` 包装) | 批量/多表写无原子性 | `plugins/web` | **P0 ✅** |
| B3 | **结果集型裸查询**(exec 返回 rows) | count / join / group / 子查询完全不可用 | `plugins/web` | P1 ✅ |
| B4 | **分页**(db 层 `limit`+`offset`;页面层上一页/下一页) | 列表页只能限量 | `plugins/web` + `ext/web` | P1 ✅(db 层;页面 UI 属 D4) |
| B5 | **查询表达力**:OR / IN / BETWEEN / IS NULL / LIKE 转义 / 括号组合 | where 只能 AND | `plugins/web` | P1 ✅ |
| B6 | **迁移机制**(schema 版本表 + 迁移脚本) | ✅ **已实现(W6)**:`db.migrate` + `_marqdo_migrations`(SQLite) | `plugins/web` + `ext/web` | P2 ✅ |
| B7 | **索引 / 唯一 / 外键声明**(init 表增强) | ✅ **已实现(W7+P3)**:`唯一`/`索引`/`外键`(`posts.id` / `posts`) | `plugins/web` | P2 ✅ |
| B8 | **聚合辅助**:count / group 便捷 API | 统计面板、标签计数 | `plugins/web` | P2 ✅(`db.count`) |
| B9 | **全文搜索**(SQLite FTS5) | ✅ **已实现(W6)**:`db.fts` + `db.search`(bm25) | `plugins/web`(FTS5 现成) | P2 ✅ |
| B10 | **时间戳 / 审计字段自动维护** | ✅ **已实现(P3)**:表含 `created_at`/`updated_at` 时 insert/update 自动写入 | `plugins/web` | P3 ✅ |
### 3.3 类 C:安全硬化(能上线的前提)
| # | 缺失能力 | 影响 | 归属 | 优先级 |
|---|---|---|---|---|
| C1 | **密码哈希**(argon2/bcrypt/sha+盐,替代明文) | ✅ **已实现(W3s)**:argon2 | `plugins/web` | **P0 ✅** |
| C2 | **CSRF 防护**(session-bound token,写操作校验) | ✅ **已实现(W3s)** | `plugins/web` | **P0 ✅** |
| C3 | **登录限速/失败锁定**(每 IP/用户名 5 次/15min) | ✅ **已实现(W3s)** | `plugins/web` | P1 ✅ |
| C4 | **会话持久化**(SQLite/文件,替代内存) | ✅ **已实现(W3s)** | `plugins/web` | P1 ✅ |
| C5 | **加密安全 session id**(CSPRNG + 碰撞重试) | ✅ **已实现(W3s)** | `plugins/web` | P1 ✅ |
| C6 | **cookie 增强**:`Secure` 标志、签名、滑动过期 | ✅ **已实现**:`cookie_secure` + 滑动 TTL(touch);cookie 签名未单独做 | `plugins/web` | P2 ✅ |
| C7 | **防暴力破解 / 会话上限 / 后台过期清理** | ✅ 限速 + prune;会话条数硬上限可后续 | `plugins/web` | P2 ✅ |
| C8 | **RBAC / 多角色**(作者/管理员/访客) | ✅ **已实现(P3)**:用户表 `role`/`角色`;`app.gate`;`/admin*` 默认需 `admin` | `plugins/web` + `ext/web` | P3 ✅ |
### 3.4 类 D:内容站点标配(博客/CMS 特有)
| # | 缺失能力 | 影响 | 归属 | 优先级 |
|---|---|---|---|---|
| D1 | **SEO**:每页 `<title>`/`meta description`/OG 标签/`canonical`/结构化数据 | ✅ **已实现(W4c)**:`page.meta` | `ext/web` | **P0 ✅** |
| D2 | **sitemap.xml / robots.txt** 生成 | ✅ **已实现(W7)**:`app.sitemap` / `app.robots` | `plugins/web` + `ext/web` | P1 ✅ |
| D3 | **RSS/Atom 输出**(`content_type=application/rss+xml` 路由) | ✅ **已实现(W4c)**:`route_rss` | `ext/web` + 插件 | P1 ✅ |
| D4 | **分页导航 UI**(上一页/下一页,依赖 B4) | ✅ **已实现(W4c)**:`page.paginate` | `ext/web` | P1 ✅ |
| D5 | **Markdown 渲染**(正文存储为 Markdown,渲染为 HTML) | ✅ **已实现(W4c)**:`lib/net` + 页面装配 | `lib/net` | **P0 ✅** |
| D6 | **标签/分类聚合页**(`/tag/{slug}` 动态路由 + 计数) | 可用路由+`db.count` 自建(未内置模板) | `ext/web` | P2 |
| D7 | **评论系统**(表单 + 审核 + 反垃圾) | ✅ 约定:表+表单+where(W6);反垃圾属应用层 | `ext/web` | P2 ✅ |
| D8 | **草稿/发布/定时**(状态字段 + 过滤查询) | ✅ 约定:`status` + where(W6) | `ext/web` + db where | P2 ✅ |
| D9 | **图片/附件库**(依赖 A5 上传 + 相册页) | ✅ **已实现(P3)**:`app.gallery` HTML 相册 + A5 上传/下载 | `ext/web` + `plugins/web` | P3 ✅ |
---
## 4. 补强路线(分波次,按「标准库 vs 扩展」边界)
### 4.1 波次建议(每波独立可交付、可回归)
| 波次 | 主题 | 内容 | 对应差距 |
|---|---|---|---|
| **W1** | 服务器基础设施 | 中间件管道(CORS/安全头/压缩/请求体限制)+ JSON API(`application/json` 响应 + DB 查询端点) | A1 A2 A3 A4 A7 ✅ **已完成** |
| **W2** | 数据层深化 | 连接池/busy_timeout/WAL + 事务 API + 结果集裸查询 + 分页(offset) + OR/IN/BETWEEN + 聚合 count | B1 B2 B3 B4 B5 B8 ✅ **已完成** |
| **W3** | 安全硬化 | 密码哈希 + CSRF + 会话持久化 + CSPRNG session id + cookie 增强 + 登录限速/锁定 | C1–C7 ✅ |
| **W4** | 内容站点标配 | SEO 元数据 + sitemap/robots + RSS + Markdown 渲染 + 分页导航 UI + 标签/分类 | D1–D5 ✅;D6 约定 |
| **W5** | 上传与媒体 | multipart 文件上传接收 + 落盘 + 下载 + 图片库 | A5 ✅;D9 相册 P3 ✅ |
| **W6** | 进阶 | 全文搜索(FTS5) + 迁移机制 + 评论系统 + 草稿/发布 + WS 广播 | B6 B9 ✅;WS 广播 + access_log ✅;D7/D8 用表+where ✅ |
| **W7** | 完结打磨 | Cache-Control、自定义 404/500、301 重定向、sitemap/robots、init 唯一/索引、HTTPS 反代文档 | A6 A7 A9 A10 B7 D2 ✅ |
| **P3** | 真·网络扩展补齐 | 审计时间戳、外键、RBAC 门禁、媒体相册、下载 ETag | B10 C8 D9 + ETag/FK ✅ |
### 4.2 边界判定要点(严格遵守既有约束)
1. **进标准库 `lib/net`**(纯解析、无网络 I/O、支持扩展库开发):
- `markdown_parse`(GFM/Markdown → HTML,纯解析)→ D5 ✅。
- `xml_escape` / RSS/Atom 纯文本装配辅助(如需)→ D3(作者面 `route_rss` 已够用)。
- **不得**放进标准库:JSON API、中间件、上传接收、事务、会话(均涉 I/O 或领域语义)。
2. **进 `plugins/web`(ABI)**:A1–A10、B1–B10、C1–C8、D7–D8 的插件侧 — **均已落地**(2026-08-28)。
3. **进 `ext/web` 作者面(Marqdo)**:D1–D4、A5/D2/D9 等 GFM 表包装 — **均已落地**(中英 `web.mq.md` / `网页.mq.md`)。
4. **已具备、无需新增**:动态路由、静态文件、表单校验/回显、session、admin/RBAC、WebSocket、SSE 客户端、cookie/multipart/Markdown 解析。
### 4.3 作者面示例(示 W4 落地形态,保持「代码即文档」)
**SEO 元数据(扩展页面表):**
```markdown
`meta` =
| 键 | 值 |
|---|---|
| `title` | 文章标题 |
| `description` | 摘要 |
| `og_type` | article |
| `canonical` | /post/{slug} |
```
页面装配时并入 `<head>` —— 仍是「表 + 函数装配」,不引入 `json.*` 袋。
**RSS(扩展路由,响应头 `content_type=application/rss+xml`):**
```markdown
*feed = > 页面.列出表 rows=`文章` 分页=20 排序="published desc"*
*xml = > 文本.拼装 xs=`rss 片段们`*
*`app` = > `应用`.路由 路径="/feed.xml" 内容=`xml` 类型="application/rss+xml"*
```
---
## 5. 结论
**W0–W7 + P3 已全部落地**(路线图见 [roadmap/ext-web.md](../roadmap/ext-web.md))。验收覆盖:
- 离线/在线 gold:`tests/ext/web-*-smoke.mq.md`(含 security、drivers、upload、w6、w7、p3)
- 完整示例:`examples/marqdo-blog/`(列表/详情/标签/RSS/后台/上传/WS)
- 作者面:`ext/web/web.mq.md` · `ext/web/网页.mq.md`
- AI 编写指引:`skills/marqdo/`(§ ext/web)
**后续可选(非阻塞)**:标签页内置模板(D6)、cookie 签名、会话条数硬上限、应用层反垃圾、进程内 TLS(仍建议反代)。
**部署对照(Daphne / Uvicorn / 反代):** 见 [web-asgi-servers-and-marqdo.md](web-asgi-servers-and-marqdo.md) — Marqdo **不能**被 Daphne 托管;生产等价路径是 **反代 → 内嵌 axum `listen`**。
**一句话:`ext/web` 已是可上线级别的 Marqdo 动态站扩展;博客/CMS/中小型 API 可在表格 + 类方法作者面上完整实现。**
---
## 6. 附:博客示例能力对照(`examples/marqdo-blog`)
| 博客功能 | 现状 |
|---|---|
| 文章列表(首页) | ✅ |
| 文章详情(动态路由) | ✅ |
| 标签/分类 | ✅ 路由 + `db.where` + `db.count` |
| 分页 | ✅ `db.paginate` + `page.paginate` |
| 搜索 | ✅ FTS5 `db.search` |
| SEO 元数据 | ✅ `page.meta` |
| RSS | ✅ `app.route_rss` |
| 评论 | ✅ 表 + form + where(反垃圾属应用层) |
| 后台写文章 | ✅ admin CRUD + RBAC |
| 草稿/发布 | ✅ `status` 字段 + where |
| 上传配图 | ✅ `app.upload` + `app.gallery` |
| 用户登录 | ✅ argon2 + CSRF + SQLite 会话 + 限速 |
| sitemap / robots | ✅ W7 |
| 实时终端(WS) | ✅ W6 广播 |
---
## 7. 附:Markdown 正文渲染(D5,已落地)
博客详情页正文经 `lib/net.markdown_parse`(`host_markdown_parse`)解析为 HTML,由 `plugins/web` 渲染层在页面装配时调用(W4c)。作者存储 Markdown 字符串于 DB,展示侧自动渲染 GFM 子集(标题、列表、链接、代码块等)。纯解析留在标准库;**不得**在 `ext/web` 作者面直接调 `host_*`。
+25 -3
View File
@@ -54,8 +54,8 @@ cargo clippy --all-targets
```bash
# Windows PowerShell 示例
$env:HTTPS_PROXY="http://127.0.0.1:7897"
$env:HTTP_PROXY="http://127.0.0.1:7897"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
$env:HTTP_PROXY="http://127.0.0.1:7890"
cargo build
```
@@ -63,11 +63,33 @@ cargo build
```toml
[http]
proxy = "http://127.0.0.1:7897"
proxy = "http://127.0.0.1:7890"
```
---
## 3.5 Git 推送(遇网络失败时使用代理)
直连 `git push` 偶尔会报 `RPC failed; curl 35 Recv failure: Connection reset by peer` 或 `curl 56`(远端挂断,常见于数据包稍大时)。此时**通过本机代理 7890 推送**:
```bash
# Linux/macOS(本机 clash 监听 127.0.0.1:7890)
git -c http.proxy=http://127.0.0.1:7890 -c http.postBuffer=524288000 push origin main
```
要点:
- 代理可用性先探测:`curl -x http://127.0.0.1:7890 -o /dev/null -w "%{http_code}\n" https://github.com`,返回 `200` 再推。
- `http.postBuffer=524288000`(500 MB)用于规避推送大包被断开(`curl 56`);两个 `-c` 可叠加。
- 该命令**一次性生效**,不写死仓库配置。若想长期默认走代理,可执行:
```bash
git config http.proxy http://127.0.0.1:7890
git config http.postBuffer 524288000
```
- 若是别的代理端口,把 `7890` 换成实际端口(如 Windows 示例里 `$env:HTTPS_PROXY` 的同款端口)。
---
## 4. 目录约定
| 路径 | 含义 |
@@ -0,0 +1,190 @@
# 调研:`ext/agent` 在 A0–A4 之后还差什么
| | |
|---|---|
| 状态 | **调研笔记 · 缺口盘点(A0–A4 闭环之后)** |
| 日期 | 2026-08-28 |
| 前置调研 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md)(优势与优化原则) |
| 已落地路线 | [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md)(**A0–A4 done**) |
| 设计 | [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md) · [okf.md](../design/okf.md) |
| 邻近规划 | [agent-streaming.md](../roadmap/agent-streaming.md) · [okf-near-match.md](../roadmap/okf-near-match.md) |
| 外部对照(2026) | LangGraph persistence / CrewAI+Flows / MCP 工具协议 / 业界 Agent 评测与记忆层讨论 |
---
## 0. 一句话结论
调研驱动的 **A0–A4** 已把 Marqdo 智能体的**差异化内核**补齐:工作簿补丁可靠、OKF 复用飞轮可读可用、过程事件可审、上下文有预算、外置检索/MCP 只作证据。
相对 2026 年主流框架(LangGraph、CrewAI、厂商 SDK、MCP 生态),Marqdo **不再缺「能跑的 Agent loop」**;缺口集中在:
1. **产品化与可发现性**(示例、文档新鲜度、上手路径)
2. **生产配套**(评测 harness、真 MCP、断点续跑、HITL、飞轮指标)
3. **可选扩展面**(并行 fan-out、多 Agent/A2A、trace 外发)
**不要**用缺口清单去证明应回退到隐藏 TOOL: 循环或把向量库升为权威真相——那与宪法冲突,也抵消已落地的优势。
---
## 1. 已落地基线(A0–A4)
| 波次 | 主题 | 验收要点 |
|------|------|----------|
| **A0** | 工作簿补丁 / 固化 | 整文件 FIND 护栏;`soft` 仅 miss;`workbook_solidify`;金样 `agent-workbook-patch-a0` |
| **A1** | OKF 复用飞轮 | `list_tasks` 策展字段;`plan` 暴露 `match`/`score`;金样 `agent-kb-plan-hit` |
| **A2** | 过程可见 | `events` 默认落盘;view plan 过程卡;SSE 仍仅 `stream=True` |
| **A3** | 上下文预算 | `source_brief` / `skill_brief`;`READ:source|skill`;`step max_reads` |
| **A4** | RAG/MCP 证据工具 | `corpus_search`;fixture `mcp_*`;`authority=workbook` |
原则回顾(见前置调研 §9):强化差异化;资源砸在工作簿 / 写回 / 固化 / OKF / 过程可视;外置 RAG/MCP **只作工具**。
---
## 2. 相对业界:已经「够格」的部分
下列能力若取消「可执行 Markdown 为权威」即消失——这是护城河,不是功能点攀比:
| 能力 | Marqdo 形态 | 业界常见替代 |
|------|-------------|--------------|
| 单一真相源 | 源码即提示 + 调用点注入 | Prompt Hub / 字符串 system |
| 过程可审 | 写回块 + `events` + view 过程卡 | Langfuse / LangSmith 外挂 |
| 成功可复用 | OKF 任务技能再跑 | transcript 再聊 / 向量片段召回 |
| 复杂任务边界 | 工作簿文件 + `subtask` | 无限加长 chat / 临时工具输出 |
| 确定步骤降本 | solidify → `llm_free` 快路径 | 每轮仍问模型 |
自评四问(前置调研 §9)粗判:
| 问 | 现状 |
|----|------|
| 新人能否只读一份 `.mq.md` 理解 Agent? | **部分** — 机制在,缺 canonical 示例教程 |
| 失败后能否在 git + view 复盘、不强制外部 trace? | **基本可以** |
| 成功任务下周能否以同一技能复用? | **可以**(金样已锁二次命中) |
| 确定步骤是否越来越多变成普通 `##`、模型调用下降? | **路径有**(solidify / llm_free),缺量化看板证明 |
---
## 3. 缺口总表(按优先级)
| 优先级 | 缺口 | 为何还缺 | 建议验收线索 |
|--------|------|----------|--------------|
| **高** | 官方端到端示例 + 文档新鲜度 | 无独立 `examples/agent-*`;Skill/参考里仍有「layout / roadmap」陈旧表述;外人难「照抄即跑通 plan→固化→二次命中」 | `examples/agent-pong`(或同类)+ README;Skill 专节与 A0–A4 对齐 |
| **高** | Agent 评测 / 回归 harness | 有离线金样,缺成本·恢复·命中率·补丁质量的系统评测;业界强调 evaluation 先于上线 | `tests/` 或脚本:命中率、llm_free 占比、失败恢复、可选 live 预算 |
| **高** | 真 MCP(HTTP/SSE)与凭证 | A4 仅 JSON fixture;缺 streamable HTTP、鉴权、resources/prompts | 金样打 mock MCP server;返回仍带 `authority=workbook` |
| **中** | Plan 断点续跑 | 工作簿在盘上,缺显式 checkpoint / resume(对标 LangGraph checkpointer) | `plan resume=` 从第 N 轮 DECISION 继续;进程崩溃可恢复 |
| **中** | 人机协同(HITL)加深 | 仅有 `confirm=True` 建簿即停;缺审批卡、拒绝重开、view 一键继续 | view 审批控件 + 金样 |
| **中** | 飞轮可观测指标 | `hits` / `improve_every` / `llm_free` 有字段,缺汇总与 CLI/view 报表 | `agent_kb_stats` 或 view 面板:命中率、探索浪费 |
| **中** | 受控并行 fan-out | `subtask` 能并行,plan 主路径偏串行 | 父协议允许有界并行调研再合并 |
| **低** | 多 Agent / A2A | dual skeleton 有;缺角色班组、跨进程 A2A | 多数场景可用「多工作簿 + 父 CALL」覆盖;有明确跨组织需求再开 |
| **低** | Trace 外发(OTLP / Langfuse) | 本地复盘已够;外发是集成题 | 可选 adapter;默认不依赖 |
| **刻意不做** | Dense embedding 默认化 | [okf-near-match.md](../roadmap/okf-near-match.md) **E** 仅在 n-gram 证据不足时评估 | 不宣传为默认向量库 |
| **刻意不做** | 私有 JSON TOOL 主路径 / 整文件 LLM 重写 | 与宪法及 parent 设计冲突 | 继续禁止 |
---
## 4. 分项说明
### 4.1 产品化(高)
**问题**
内核能力已超过「能演示」门槛,但**可感知产品体验**仍依赖读设计文档与翻 `tests/ext/`。对照 quantum / web 已有 `examples/`,agent 侧空白最明显。
**建议**
1. 一份最小可运行示例:`step` → `plan` → promote → 二次 `plan` 打印 `cache=hit`。
2. 同步 Skill / `doc/README` / 公开页,删掉「仅 layout」类过时句。
3. 示例强调「权威在 `.mq.md`」,corpus/mcp 仅作证据旁路。
### 4.2 评测 harness(高)
**问题**
金样锁行为正确性;不锁「飞轮是否在变好」「一次失败后能否恢复」「live 成本是否失控」。2026 多 Agent 讨论普遍把 **evaluation** 列为上线前缺失步骤。
**建议**
- 离线:命中路径、补丁护栏、预算截断(已有)再加 **stats 断言**。
- 半自动 / live:固定小 goal 集,记录 rounds、cache 分布、token 粗估(若可从供应商响应取得)。
- 明确:评测消费的是工作簿与 kb,而不是外部 transcript 库。
### 4.3 真 MCP(高)与「证据≠权威」(不变)
**问题**
Fixture 证明协议形状与权威字段;生产要接真实 MCP server(工具、资源、鉴权)。
**约束**
- 工具结果进入 observation / CALL 回执,**不得**静默写成 OKF 权威技能。
- 晋升仍走 promote / solidify / 人审(既有路径)。
### 4.4 断点续跑与 HITL(中)
**问题**
LangGraph 类框架的 checkpointer / interrupt 是生产差异点。Marqdo 已有文件化状态(工作簿、写回、events),差的是**一等恢复 API**与**可视审批**。
**建议方向**
- Resume:序列化「当前 round、path、last observation、events」到约定槽或旁路文件,重启后跳过已完成子跑。
- HITL:扩展 `confirm` 语义(建簿 / 危险 PATCH / promote);view 展示 pending 卡。
### 4.5 飞轮指标与并行(中)
**问题**
第四问(模型调用是否下降)需要数字。并行能缩短探索,但须有界,避免工作簿爆炸(见 [ext-agent.md](../design/ext-agent.md) §9)。
### 4.6 多 Agent / A2A / 外发 trace(低)
**问题**
业界热度高(Crews、A2A、共享记忆层)。Marqdo 的「父 + 多工作簿」已覆盖多数单组织编排;跨组织 A2A 与共享记忆库是另一产品层,可用 MCP/证据工具接入,而不必把记忆权威搬出 `.mq.md`。
---
## 5. 建议的下一波分期(草案 B)
> 非正式锁定;落地时再写入 [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) 或独立 `ext-agent-productize.md`。
| 波次 | 主题 | 验收线索 |
|------|------|----------|
| **B0** | 官方示例 + Skill/文档去陈 | `examples/agent-*` 可 `marqdo run`;Skill 与 A0–A4 一致 |
| **B1** | 评测 harness | 命中率 / llm_free / 恢复用例可一键跑 |
| **B2** | Live MCP 客户端 | mock server 金样;`authority=workbook` 不变 |
| **B3** | Plan resume + HITL | 崩溃可续;view 审批 |
| **B4** | kb stats 面板 | CLI 或 view 展示飞轮数字 |
| **B5** | 有界并行(可选) | fan-out 上限 + 合并观察 |
---
## 6. 明确「不是缺口」的清单
避免把差异化优势误判为缺陷:
1. **没有默认 dense 向量库** — 有意;OKF near 是稀疏词法;corpus 是关键词证据。
2. **没有隐藏 TOOL: JSON 主协议** — 有意;CALL/READ/DECISION 与文档同构。
3. **子任务默认 quiet** — 有意;答案走返回值,过程走 events/stream。
4. **ext 不直调 host_*** — 有意;Agent 域在插件,防核心膨胀。
5. **不捆绑领域工单技能** — 有意;官方框架保持可教、可审、可扩展。
---
## 7. 结论与推荐下一刀
A0–A4 之后,Marqdo `ext/agent` 在「文档驱动智能体」叙事上已经**自洽且可演示**。相对业界,短板是 **被人用起来的路径** 与 **生产级配套**,不是再堆一条编排 DSL。
**推荐下一刀顺序:**
1. **B0 官方示例 + 文档去陈**(最低成本、最高感知)
2. **B1 评测 harness**(锁住飞轮与质量,防止回退)
3. 按真实用户需求选 **B2 live MCP** 或 **B3 resume/HITL**
若四问在 B0–B1 后均可回答「是」,再考虑 B4/B5 与低优先级项。
---
## 8. 参考
### 本仓
- [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md)
- [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md)
- [okf-near-match.md](../roadmap/okf-near-match.md)(E dense 仍非默认)
- [agent-streaming.md](../roadmap/agent-streaming.md)
### 外部(抽样,2026)
- LangGraph Persistence(checkpointer / store)
- CrewAI Crews + Flows;MCP 作为工具连接层而非编排本体
- 业界对 Agent evaluation、durable memory / A2A 状态层的讨论(共享记忆 ≠ 应取代可执行文档权威)
+533
View File
@@ -0,0 +1,533 @@
# 调研:主流智能体开发框架与 Marqdo「代码即文档 / 文档即知识库」优势
| | |
|---|---|
| 状态 | **调研笔记 · 供 `ext/agent` 深入优化参考** |
| 日期 | 2026-08-28 |
| 范围 | 2025–2026 开源/厂商智能体框架形态;对照 Marqdo `ext/ai/agent` 设计 |
| 相关设计 | [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md) · [okf.md](../design/okf.md) · [stdlib-writeback.md](../design/stdlib-writeback.md) · [stdlib-subtask.md](../design/stdlib-subtask.md) |
| 姊妹调研 | [okf-and-marqdo.md](okf-and-marqdo.md) · **A0–A4 后缺口** [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) |
| 外部对照(抽样) | [Langfuse 框架对比(2026-07)](https://langfuse.com/blog/2025-03-19-ai-agent-comparison) · [LangGraph persistence](https://docs.langchain.com/oss/python/langgraph/persistence) · [Microsoft Agent Framework / AutoGen 维护模式](https://github.com/microsoft/autogen) · CrewAI / OpenAI Agents SDK / Claude Agent SDK / Google ADK / LlamaIndex 公开文档 |
---
## 0. 一句话结论
主流智能体框架几乎都在解决同一组工程问题——**编排、工具、状态、记忆、可观测、人机协同**——但它们的「权威真相」默认落在 **Python/TS 对象图 + 会话 transcript + 外部 Store/向量库** 上。
Marqdo 的宪法把权威真相定在 **可执行 Markdown(`.mq.md`)**:人写的程序、模型读的提示、执行后的写回、可复用的任务技能,是**同一份文档的不同生命阶段**。这不是「又一个 Agent SDK」,而是把 **Agent 开发本身做成文档工程**。
由此产生的突出优势(后文展开):
1. **编排可读 = 提示词不再黑盒**(源码即上下文)
2. **过程可审 = 写回进源文件,而不是只进遥测平台**
3. **记忆可 git = 成功经验晋升为任务知识包(OKF),审计=仓库历史**
4. **复杂任务=子程序,而不是无限加长的 chat**(工作簿 + `subtask`)
5. **确定步骤固化为代码,不确定步骤才问模型**(父 Plan-and-Move)
6. **语言与知识形态同构**(与 Google OKF「Markdown 知识包」同向,但多走「可执行」一步)
**优化 `ext/agent` 时应守住这些差异化,而不是向 LangChain 类「隐藏循环 + TOOL: 协议」回退。**
---
## 1. 调研方法与边界
### 1.1 做了什么
| 动作 | 说明 |
|------|------|
| 横向扫盘 | 2026 年主流开源框架:LangGraph / LangChain DeepAgents、CrewAI、OpenAI Agents SDK、Claude Agent SDK、Google ADK、Microsoft Agent Framework(AutoGen 继承者)、Pydantic AI、LlamaIndex、Strands、Mastra / Vercel AI SDK、smolagents 等 |
| 结构抽象 | 抽取「框架如何形成」的共性分层,而不是比 GitHub stars |
| 对照本仓 | 精读 `ext-agent*`、`okf`、`writeback`、`subtask`、parent Plan-and-Move;对照旧 TOOL: 薄循环为何被否定 |
| 找优越点 | 只保留 **Marqdo 结构上必然领先**、而非「以后可以加插件追上」的点 |
### 1.2 不做的
- 不宣称 Marqdo 在吞吐、多模态、托管运维上已全面领先(这些不是当前差异化)。
- 不把「有没有向量检索」当成胜负手——那是应用层可加能力。
- 不做厂商营销话术复读;优缺点按**开发者体验与系统真相源**评。
---
## 2. 智能体框架是怎么「形成」的
无论品牌如何包装,成熟框架通常收敛为同一条装配线:
```text
┌─────────────────────────────────────────────────────────────┐
│ 1. Model I/O │
│ 补全 / 工具调用 / 流式 / 多模供应商适配 │
├─────────────────────────────────────────────────────────────┤
│ 2. Agent 单元 │
│ 指令(system) + 工具表 + 可选角色/人设 │
├─────────────────────────────────────────────────────────────┤
│ 3. 编排(Orchestration) │
│ 图 / 角色队 / 对话群 / 工作流 API / supervisor │
├─────────────────────────────────────────────────────────────┤
│ 4. 状态与记忆 │
│ 短:thread checkpoint / 会话历史 │
│ 长:Store / 向量 RAG / 用户偏好库 │
├─────────────────────────────────────────────────────────────┤
│ 5. 工具与行动面 │
│ 函数 schema、MCP、沙箱、权限、CodeAct │
├─────────────────────────────────────────────────────────────┤
│ 6. 可观测与治理 │
│ Trace、评测、护栏、HITL、配额 │
└─────────────────────────────────────────────────────────────┘
```
### 2.1 三种主流「编排哲学」
| 范式 | 核心隐喻 | 代表 | 可预测性 | 原型速度 |
|------|----------|------|----------|----------|
| **图 / 状态机** | 节点=步骤,边=转移,状态显式 | LangGraph、Google ADK workflow、MAF workflows | 高 | 中–慢(先画图) |
| **角色协作** | Agent=工种,Crew=班组 | CrewAI、早期 AutoGen 群聊 | 中 | 快 |
| **薄循环 + 工具** | 「模型自己决定下一步」 | OpenAI Agents SDK、Claude Agent SDK、Strands、smolagents | 低–中(靠护栏) | 最快 |
2026 年的趋势不是「哪个范式消灭其它」,而是:
- **生产复杂流** → 图(可控、可恢复、HITL)。
- **内容/研究班组** → 角色。
- **编码助手 / 生态绑定** → 厂商 SDK 自带 hardened loop。
- **LangChain DeepAgents** 等开始把「规划器 + 子代理 + 文件记忆」打包成 opinionated harness——说明业界也意识到:纯 chat 不够,需要**文件与子上下文**。
### 2.2 记忆层的行业共识(与 Marqdo 对照的关键)
以 LangGraph 文档为代表(行业事实上的标准划分):
| 层 | 行业做法 | 作用 |
|----|----------|------|
| **短时** | Checkpointer / thread_id | 会话续跑、崩溃恢复、time-travel |
| **长时** | BaseStore / 向量库 / Mem0·Zep 等 | 跨会话事实、偏好 |
| **检索知识** | RAG corpus | 领域文档,不与会话状态混用 |
常见架构错误:把 checkpointer 当成长时记忆——换 `thread_id` 就「失忆」。
**这一点对 Marqdo 极关键:**
行业把「记忆」拆成多个后端;Marqdo 默认把**任务级成功经验**落成 **`.mq.md` + agent-kb(OKF)**,用文件系统与 git 当记忆平面——见 §7。
### 2.3 框架「形成产品」的路径
```text
PoC(脚本循环)
→ SDK(Agent + tools)
→ 编排(图 / 多代理)
→ 持久化(checkpoint / store)
→ 平台(托管、评测、护栏、计费)
```
越往后,**编排源码与运行时真相越分离**:提示在字符串常量或 Prompt Hub,状态在 DB,轨迹在 Langfuse,知识在向量库。人要复盘一次失败,往往要开四个系统。
Marqdo 的赌注是:**尽量把真相拉回单一 `.mq.md` 时间线**。
---
## 3. 代表框架解剖(如何形成 + 优缺点)
### 3.1 LangGraph(显式状态图)
**如何形成**
- 把 Agent 步骤建模为 **有向图**:节点读/写共享 state,条件边决定下一跳。
- 编译为可执行应用;挂 checkpointer → 持久化、HITL interrupt、故障续跑。
- 长时记忆另挂 Store;生态上接 LangChain 工具与 LangSmith/Langfuse 轨迹。
**优点**
- 生产向可控性最强;分支、重试、并行边清晰。
- 状态类型化后,测试与回放(time-travel)可行。
- 云中立:图在你自己的进程里跑。
**缺点**
- 上手成本高:先设计图,再写节点。
- 「提示词 / 业务说明」仍常散落在 Python 字符串;**图代码 ≠ 给人读的说明书**。
- 记忆与知识仍依赖外置 Store/RAG;审计链路长。
- DeepAgents 等上层 harness 说明:光有图仍不够「文件化协作」。
**对 Marqdo 的启示**
- 要学其「显式控制与可恢复」;不要学其「状态默认在对象里」。
- Marqdo 多步的工作簿修订环 ≈ **把图展开成磁盘上的可执行文档**。
---
### 3.2 CrewAI(角色班组 + Flows)
**如何形成**
- Agent = role / goal / backstory;Crew 协调任务;近年加 **Flows** 把确定性业务逻辑包住自治班组。
**优点**
- 多代理叙事直观,原型极快。
- 适合内容流水线、调研班组。
**缺点**
- 协作转移大量靠描述,**可预测性弱于图**。
- 过程真相仍是运行时对象与日志;与「文档即程序」无关。
- HITL / 企业治理相对弱。
**对 Marqdo 的启示**
- 「多角色」可用多个 `# 智能体` / 多个工作簿表达,但应以**可跑文档**为边界,而不是隐式群聊。
---
### 3.3 AutoGen → Microsoft Agent Framework(MAF)
**如何形成**
- AutoGen:对话对 / 群聊驱动;历史在内存。
- 2026:AutoGen **维护模式**;能力并入 **Microsoft Agent Framework**(与 Semantic Kernel 合流):ChatAgent + 多种编排(sequential / concurrent / handoff / group / Magentic)+ 工作流图 + Azure Foundry 治理面。
**优点**
- 企业栈(.NET / Azure)一体;A2A、MCP、护栏、托管轨迹。
- CodeAct 等模式:让 Agent **写代码执行**而非只吐 JSON——与「固化为代码」方向有共鸣。
**缺点**
- 生产治理深度常绑定云平台;开源核心与托管能力分层。
- 编排语言仍是通用编程语言;**业务知识与程序不同构**。
- 对话范式易导致「无限闲聊」式多代理。
**对 Marqdo 的启示**
- CodeAct / 固化步骤:与 Marqdo「确定步骤写成 `##`」同向,但 MAF 写的是 Python;Marqdo 写的是**人与模型共用的 `.mq.md`**。
---
### 3.4 OpenAI Agents SDK / Claude Agent SDK / Google ADK / Strands
**如何形成(共性)**
- 提供 **hardened agent loop**(工具、handoff、权限、会话)。
- 深度绑定自家模型或云(OpenAI / Anthropic Claude Code harness / Gemini+ADK / Bedrock)。
**优点**
- 最快接入「能干活的助手」;权限与工具路径经过产品锤炼(尤其 Claude Code 同源 SDK)。
- 官方 tracing、realtime 等增值。
**缺点**
- 编排与提示仍在宿主语言;**跨团队知识复用靠复制仓库或 Prompt 平台**。
- 供应商锁定风险;换模时常换范式。
- 「记忆」默认会话式;企业知识仍外挂。
**对 Marqdo 的启示**
- 模型 I/O 应继续放在 `ext/llm`,**不要**在 agent 里重造聊天栈。
- 不要把「官方 loop」当哲学:Marqdo 的哲学是文档驱动,不是 SDK 驱动。
---
### 3.5 LlamaIndex / Haystack(文档与 RAG 优先)
**如何形成**
- 以索引、检索、查询引擎为中心;Agent 是检索之上的编排层。
**优点**
- 企业文档智能、多格式摄取成熟。
- 「知识」有一等公民地位。
**缺点**
- 知识默认是 **被检索的被动语料**,不是 **可执行的任务程序**。
- Agent 编排能力弱于 LangGraph 系;常需再叠一层框架。
- 索引与源文档易漂移(双源真相)。
**对 Marqdo 的启示(尖锐对比)**
- LlamaIndex:**文档 → 向量 → 检索 → 回答**。
- Marqdo:**文档 → 可执行语法 → 运行 → 写回 →(可选)晋升为任务知识包**。
同一「Markdown 知识」在 Marqdo 里可以是 **会跑的技能**,而不仅是 chunk。
---
### 3.6 Pydantic AI / Mastra / Vercel AI SDK
**如何形成**
- 强调类型安全(Pydantic)或 TS 全栈 DX(Mastra / Vercel)。
- 把 Agent 当普通后端组件:校验、otel、耐久执行。
**优点**
- 工程化体验好;与现有 Web/API 栈融合。
**缺点**
- 仍是「代码库里的 Agent」;非技术干系人无法直接打开同一份编排当说明书。
- 知识沉淀路径仍外置。
---
### 3.7 横向对比表(开发者真相源)
| 维度 | 典型框架落点 | Marqdo 落点 |
|------|--------------|-------------|
| 编排定义 | Python/TS 图或类 | `.mq.md` 标题/表/调用 |
| 系统提示 | 字符串 / Prompt Hub | 站立提示写在同一文档 |
| 工具 | 装饰器函数 / MCP | runbook 内 `##` + `subtask` |
| 短时状态 | checkpoint / session | 工作簿文件 + 写回块 + view |
| 长时记忆 | Store / 向量 | agent-kb(OKF)+ git |
| 复杂任务 | 子图 / 子代理上下文窗 | **子 `.mq.md` 程序** `spawn path=` |
| 复盘 | Langfuse trace | `git log` + 打开工作簿 + view output-card |
| 成功复用 | 手工抽 prompt / 存 Store | **固化 + OKF 晋升 / lookup** |
---
## 4. 行业共性痛点(框架越强,痛点越清晰)
下列痛点在 LangGraph、CrewAI、厂商 SDK 文档与实践文章中反复出现;它们正是 Marqdo 要正面打穿的:
### 4.1 提示词与编排分离
- 行为由 system prompt + 隐藏模板决定;code review 审不到「模型真正看见什么」。
- Prompt 漂移与代码漂移双轨发生。
### 4.2 过程不透明或只对平台透明
- 本地只有最终返回值;细节在 SaaS trace。
- 合规团队要的「这份文档当时怎么决策的」难以直接交付。
### 4.3 记忆碎片化
- thread / store / RAG / 日志四套系统;「上次同类任务怎么做成的」检索成本高。
- 成功经验很少自动变成**可再执行资产**。
### 4.4 多步任务变成超长 transcript
- 上下文窗口被工具输出撑爆;DeepAgents 才开始「卸到文件系统」。
- 说明业界被迫走向 **文件化**——而 Marqdo **一开始就以文件为执行边界**。
### 4.5 确定性逻辑仍反复问模型
- 已验证的步骤下一轮又被重新「推理」,浪费且不稳。
- 缺少「晋升为普通代码」的一等路径。
### 4.6 Agent 框架与知识格式断裂
- Google OKF 等推动「知识用 Markdown 包交换」,但主流 Agent 框架并不把 **可执行程序** 当作知识页。
- 结果:知识包给人策展,Agent 另跑一套 Python。
---
## 5. Marqdo 在智能体域的设计思想(必须找准)
### 5.1 宪法重申
| 口号 | 在 Agent 语境下的含义 |
|------|------------------------|
| **代码即文档** | 智能体编排、工具表、站立提示、任务叙述写在同一份 `.mq.md`;打开即读、即可跑 |
| **文档即知识库** | 写回块、工作簿、OKF 任务页都是知识;Agent 与人共用同一交换面 |
| **文档能跑通 = 约定成立** | 金样 / `marqdo run` / view 是验收,不是「旁边另有一份真实现状」 |
旧「TOOL: 黑盒循环」被官方设计明确否定,正是因为它把 Marqdo **降级成了 LangChain 的薄壳**。
### 5.2 两级执行(与业界范式对齐但不抄袭)
| Marqdo | 业界近似 | 关键差异 |
|--------|----------|----------|
| `## step` 单步 | 薄 Agent loop | 注入**本文件源码 + 调用位置 + Skill**;默认写回 |
| `## plan` 多步 | 规划器 + 子代理 | 产物是 **工作簿 `.mq.md`**;经 `subtask` 整文件执行;父以补丁演进 |
| 父 Plan-and-Move | supervisor / orchestrator | 行动面:READ/CALL/DECISION;**禁止整文件 LLM 重写** |
| OKF agent-kb | long-term store | 命中的是 **可再跑的任务技能**,不是抽象 embedding 片段(可再叠加 soft near) |
### 5.3 执行与隔离
- 工具与子工作簿走 `lib/subtask`(`spawn fn=` / `spawn path=`),与主推理隔离——对应业界「子代理独立上下文」,但边界是 **文件与子进程语义**,不是仅换一个 message list。
---
## 6. Marqdo 的必要突出优势(核心章节)
下列优势要求满足:**若取消「可执行 Markdown 为权威」,优势即消失**。这才是「必要」优越点,而不是功能清单攀比。
### 6.1 单一真相源:编排 / 提示 / 结果共址
**优势陈述**
模型在 `step`/`plan` 中看到的上下文,可以就是**人类正在编辑的那份源码**(及调用点)。站立提示不是隐藏 system blob,而是文档段落。
**为何必要**
消除「提示词仓库 vs 代码仓库」双源;code review、教学、合规审计面对同一人造物。
**相对框架**
LangGraph/CrewAI/SDK:提示常在字符串或控制台配置;trace 在另一系统。Marqdo:`view` 在语句下挂 output-card,与源同行。
### 6.2 写回 = 内建的「Notebook 输出单元」式过程记忆
**优势陈述**
`lib/writeback` 把成功/失败写入 `<!-- marqdo-out … -->`,锚在调用行下。智能体默认写回后,**过程留在源文件**,不是只留在遥测。
**为何必要**
教学与调试要「看见刚才那一步」;失败成为可读避坑记录;成功可被后续命中。
**相对框架**
业界靠 Langfuse/LangSmith;本地仓库往往是空的。Marqdo 仓库本身就是过程库(可再导出到 trace,但不依赖它才能复盘)。
### 6.3 复杂任务 = 生成并演进子程序,而不是堆 transcript
**优势陈述**
`plan` 创建 `.marqdo/agent-runs/*.mq.md`,用 `spawn path=` 跑完整 `# main`。父观察**真实退出码、返回值、写回、源码**,再 FIND/REPLACE 补丁。
**为何必要**
上下文窗口有限;长工具输出必须卸出。DeepAgents 用「文件系统抽象」补课;Marqdo **语言层原生就是文件程序**。
**相对框架**
子代理多是「新对话 + 摘要」;Marqdo 子任务是 **可独立 `marqdo run` 的文档**,可被人类直接打开修改后重跑。
### 6.4 确定步骤固化为代码;模型只处理不确定残差
**优势陈述**
父作为「智能体开发大师」:能写成 `##` 的就固化;子智能体只跑不确定的 `step`。`DECISION: DONE` 可 solidify + OKF 晋升。
**为何必要**
降本、降方差、形成组织资产。业界常把每次任务重新推理;Marqdo 把「学会的技能」编译回语言。
**相对框架**
MAF CodeAct 写出的是通用语言脚本;Marqdo 固化的是 **仍保持文档属性的 `.mq.md` 技能**——人不用会 Python 也能读懂并改。
### 6.5 文档即知识库 + OKF:记忆可交换、可策展、可信任
**优势陈述**
任务知识包(`.marqdo/agent-kb/`)以 OKF 形承载 `Marqdo Task` / skill,`resource:` 必须指向可执行 `.mq.md`。lookup / near / soft_match 走插件,不进核心 host。
**为何必要**
Google OKF 证明行业需要「Markdown 知识包」;Marqdo 多走一步:**知识页声明的可执行资源真能跑**。记忆不是不可解释的向量命中,而是 **带路径的技能复用**。
**相对框架**
LlamaIndex 检索散文块;Store 存 JSON 事实。Marqdo agent-kb:**命中 → 再跑同一技能路径**(精确 / 规范化 / near / 父裁决)。
### 6.6 审计与协作默认路径 = Git
**优势陈述**
工作簿演进、写回、晋升都是文件变更 → `git log` / PR / blame。
**为何必要**
企业已有代码治理;不必为 Agent 另建「提示治理平台」才能起步。
**相对框架**
多数框架的状态在 DB;要审计得接专用平台。Marqdo 从第一天就兼容软件工程工作流。
### 6.7 中英双面 API 与「说明书即程序」教学属性
**优势陈述**
`# 智能体` / `# agent`、`单步`/`step`、`多步`/`plan` 对称;教程文档可以直接是金样。
**为何必要**
智能体开发教育成本高;Marqdo 把教材和运行物合一(与 quantum/math 扩展同一哲学)。
### 6.8 分层纪律:扩展不脏核心
**优势陈述**
`ext/**` 禁 `host_*`;agent-kb 在 `plugins/agent`;核心保持瘦。
**为何必要**
避免「Agent 框架把语言运行时变成巨石」——这是许多 Python Agent 栈的终局病。
---
## 7. 优势地图(一图看懂定位)
```text
可预测性 / 生产控制
▲
│ LangGraph / MAF workflows
│
│ ★ Marqdo plan
│ (workbook = program)
│
角色班组 ──────────┼────────────── 薄循环 SDK
CrewAI │ OpenAI / Claude SDK
│
│ LlamaIndex (RAG)
│
└────────────────────────────►
文档/知识一等公民程度
★ Marqdo 同时偏右上:控制来自「可执行文档+补丁环」,
知识来自「同源 Markdown + OKF」,而非向量库单独称王。
```
---
## 8. 诚实边界:什么时候不该硬吹 Marqdo
| 场景 | 更合适的选择 | 原因 |
|------|--------------|------|
| 超大规模并行图、成熟 Python 数据栈 | LangGraph + 现有 infra | 生态与库广度 |
| 强绑定 Azure 治理 / .NET | MAF | 平台一体 |
| 纯文档问答 / 海量非结构化语料 | LlamaIndex 等 | 摄取与检索成熟;Marqdo 可 **调用** 它们作工具,不必重造 |
| 只要一个 ChatGPT 式助手周末原型 | 厂商 Agents SDK | 启动最快 |
| 需要强实时语音 / 多模原生 | 厂商 SDK | 非 Marqdo 当前主场 |
Marqdo 的正确叙事不是「取代所有 Agent 框架」,而是:
> **当你希望智能体开发成果沉淀为组织可维护的文档资产,并且编排本身必须可教、可审、可跑时——选 Marqdo。**
---
## 9. 对 `ext/agent` 深入优化的建议方向(调研导出)
优化应强化 §6 优势,避免回退到「隐藏 TOOL 循环」。
| 优先级 | 方向 | 理由 |
|--------|------|------|
| P0 | **工作簿质量与补丁可靠性**(精确 FIND/REPLACE、固化、观察切片) | 直接决定「子程序演进」是否优于 transcript |
| P0 | **OKF 命中体验**(精确 / near / soft_match 默认真策略、策展 UX) | 落实「文档即知识库」的复用飞轮 |
| P1 | **过程可见**(streaming / view 过程卡,见 [agent-streaming.md](../roadmap/agent-streaming.md)) | 对标 Langfuse,但真相仍写回文档 |
| P1 | **Skill / 源码注入的预算与渐进披露** | 避免上下文爆炸,同时保持「源码即提示」 |
| P2 | **与外部 RAG/MCP 的工具化接入** | 补齐语料检索,但不把向量库升为权威真相 |
| P2 | **评测金样:同类任务二次 plan 应命中 kb 快路径** | 用测试锁住差异化 |
| 避免 | 再引入私有 JSON 工具协议作主路径 | 与宪法冲突 |
| 避免 | 整文件 LLM 重写工作簿 | 已在 parent 设计禁止 |
验收提问(产品自评):
1. 新人能否只读一份 `.mq.md` 理解 Agent 在干什么?
2. 失败后能否在 git 与 view 内完成复盘,不强制打开外部 trace?
3. 成功任务下周能否以 **跑同一技能** 的方式复用,而不是「再聊一遍」?
4. 确定步骤是否越来越多地变成普通 `##`,模型调用是否下降?
若四问皆是——优化方向正确。
---
## 10. 结论
2026 年的智能体框架市场在 **图控、角色班组、厂商 hardened loop、RAG 知识** 四条线上分化;共同短板是 **真相源碎片化** 与 **成功经验难以变成可执行组织资产**。
Marqdo 用「代码即文档、文档即知识库」把 Agent 开发收束到 **可执行 Markdown 生命循环**:
**书写 → 注入模型 → 执行 → 写回 →(多步)补丁演进 → 固化 → OKF 晋升 → 再命中。**
这不是功能点堆砌,而是架构级选择。深入优化 `ext/agent` 时,应把资源砸在 **工作簿、写回、固化、知识包命中、过程可视** 上,把「文档驱动的智能体开发框架」做成可感知的产品体验——这才是相对 LangGraph / CrewAI / 厂商 SDK **不可替代** 的优越点。
---
## 11. 参考与延伸阅读
### 本仓
- [ext-agent.md](../design/ext-agent.md) — 框架总设计(否定 TOOL 薄循环)
- [ext-agent-plan.md](../design/ext-agent-plan.md) — 多步工作簿
- [ext-agent-parent.md](../design/ext-agent-parent.md) — 父 Plan-and-Move
- [okf.md](../design/okf.md) · [okf-and-marqdo.md](okf-and-marqdo.md)
- [stdlib-writeback.md](../design/stdlib-writeback.md) · [stdlib-subtask.md](../design/stdlib-subtask.md)
- [roadmap/agent-streaming.md](../roadmap/agent-streaming.md) · [roadmap/okf-near-match.md](../roadmap/okf-near-match.md) · [roadmap/ext-agent-optimize.md](../roadmap/ext-agent-optimize.md)
- [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) — A0–A4 之后还差什么
### 外部(抽样,2025–2026)
- Langfuse: *Comparing Open-Source AI Agent Frameworks*(2026-07 更新盘点)
- LangGraph docs: Persistence(checkpointer vs store)
- Microsoft: AutoGen maintenance → Agent Framework migration
- CrewAI: Crews + Flows
- OpenAI Agents SDK / Claude Agent SDK / Google ADK 公开 README
- Google OKF SPEC v0.2(知识包形态;与 Marqdo 可执行源对照)
+1 -1
View File
@@ -192,7 +192,7 @@ OKF 规范强调:一页纸能讲清 v0.1 的互通面;v0.2 只**加词汇、
来自本次调研、建议在 `design/` 或 `adr/` 中跟进:
1. **`.mq.md` 的双重解析模型** — Markdown CST 与 Marqdo AST 如何共享同一文本、何处分叉。
2. **生成式 OKF 清单的落盘与命令** — 路径、是否提交 git、`sync`/`doc` 行为(方向已采纳,见 [design/generated-yaml-manifest.md](../design/generated-yaml-manifest.md))。
2. **生成式 OKF 清单的落盘与命令** — 路径、是否提交 git、`sync`/`doc` 行为(方向已采纳;**实现规范见 [okf.md](../design/okf.md)**,命令见 [catalog-cli.md](../design/catalog-cli.md))。
3. **正文中的依赖声明语法** — import / 链接如何写出,供工具提取进生成清单。
4. **Agent 友好但不 Agent 绑定** — 源格式对 LLM 可写,语义对确定性工具可检。
5. **可渲染结果的 attestation(后期)** — 文档内求值结果的可验证性。
+181
View File
@@ -0,0 +1,181 @@
# 智能体流式输出(未来规划)
| | |
|---|---|
| 状态 | **S0–S3 已落地**(view SSE) |
| 日期 | 2026-08-10 |
| 相关 | [ext-llm.md](../design/ext-llm.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)(父 Plan-and-Move / CALL·READ) · [stdlib-subtask.md](../design/stdlib-subtask.md) · [view.md](../design/view.md) |
| 痛点 | `complete` / `step` / `plan` 均为整段返回;用户看不到思考与中间输出 |
---
## 1. 问题
当前体验:
| 路径 | 行为 | 体验问题 |
|------|------|----------|
| `` `model`.complete `` | 等 HTTP 整包结束再返回字符串 | 长推理「卡住」无反馈 |
| `` `助手`.step `` | 拼提示 → complete → 解析 CALL/答案 | 工具轮次与模型吐字均不可见 |
| `` `助手`.plan `` | 多轮 spawn + 父 LLM;子任务默认 `quiet` | 父侧只有最终 `result` map;过程静默 |
这与「文档驱动、过程可审计」并不矛盾——**落盘真相**仍可以是工作簿与写回;缺的是**运行时的渐进呈现**(TTY / view / 调用方回调)。
约束回顾(不得破坏):
1. 文件子任务默认静默:答案走 `# main` **返回值**([stdlib-subtask.md](../design/stdlib-subtask.md))。
2. `ext/**` 不直调 `host_*`;流式原语进 `ext/ai/llm` + 必要时薄 host/net。
3. 多轮哲学仍是模式 C(子文件接力 + OKF),不是把 transcript 堆进单文件。
---
## 2. 目标
1. **可选**流式看到:模型增量文本、(可选)工具调用开始/结束、plan 轮次边界。
2. 默认保持今日语义:未开流式 = 整段 `complete` / 整包 `result`。
3. 流式是**呈现与旁路**,不替代 `**返回**` / `plan.result` / 写回。
4. CLI、`marqdo view`、嵌入调用方可共用同一事件模型。
非目标(本规划):
- 把 Marqdo 做成聊天产品 UI 框架。
- 强制所有 `print` 改流式 API。
- 在 quiet 子进程里把子 `print` 默认真传父 TTY(与返回优先冲突)。
---
## 3. 分层设计
```text
LLM 供应商 SSE / chunked
↓
ext/ai/llm stream=True → 事件迭代 / 回调 / 写 channel
↓
ext/ai/agent step/plan 订阅事件 → 可选透传或写回「过程槽」
↓
呈现面:TTY | view EventSource | 调用方 foreach 事件表
```
### 3.1 事件模型(锁定方向)
统一为可 JSON 化的小 map(便于写回与 view):
| `type` | 含义 | 主要字段 |
|--------|------|----------|
| `reasoning` | 模型思考增量(如 DeepSeek `reasoning_content`) | `text` |
| `delta` | 模型答案增量文本 | `text` |
| `tool_start` / `tool_end` | 工具轮(父 plan CALL/READ 已发;view Tool 卡) | `name`, `kind?`, `result?` |
| `round` | plan 轮次边界(子工作簿跑完) | `round`, `workbook`, `exit_code?`, `result?`(子返回值摘要) |
| `decision` | DONE / CONTINUE / RUN | `decision`, `summary?` |
| `done` | 本调用结束 | `result`(答案正文;不含 thinking) |
| `error` | 失败 | `message` |
中英键名可在 L1 包装层镜像;插件/wire 先用英文 `type`。
### 3.2 `llm`:流式完成
```markdown
*`model` = > llm *
*`stream` = > `model`.complete prompt=… stream=True *
- [`ev`](`stream`)
*`t` = > json.get value=`ev` key=type *
1. `t` == delta
*`chunk` = > json.get value=`ev` key=text *
> print text=`chunk`
2. `t` == done
*`answer` = > json.get value=`ev` key=result *
```
或回调形(若日后支持函数值作实参):`on_delta=` —— v1 优先 **事件列表 / 可迭代句柄**,少发明回调语法。
实现要点:
- `lib/net` 或 llm 插件支持 **读 SSE / chunked body**(今日 `http_post` 偏整包)。
- `stream=False`(默认)路径零行为变化。
- 金样:mock SSE fixture,不强制打真网。
### 3.3 `agent.step` / `plan`:过程透传
| 开关(草案) | 默认 | 行为 |
|--------------|------|------|
| `stream=False` | ✓ | 与今日相同 |
| `stream=True` | | 向**当前进程**呈现面推送事件;返回值仍是最终 map |
| `trace=True` | 可选 | 把事件追加写入调用行写回槽 `trace`(审计);与 TTY 流式可分立 |
plan 特有:
- `await_workbook` **前**发 `await`(view Child running 占位);结束后发 `round`。
- 父 pre-run 分解发 `decompose`。
- 父 LLM 的 `complete` 若 `stream=True`,`delta` 冒泡到 plan 的 stream。
- **子文件 quiet 不变(TTY)**;默认骨架 `step stream=True`,子 EventBus 经 `MARQDO_EVENT_FORWARD` **实时转发**到父 SSE(`source=child`)。答案仍以 `# main` 返回为准。
### 3.4 呈现面
| 面 | 做法 |
|----|------|
| CLI | `delta` 直接写 stdout(无额外 JSON 包装);结构化事件可 `--trace-events` 走 stderr / 旁路文件 |
| `marqdo view` | Execution 区 Stream 面板订阅 SSE(见 [view.md](../design/view.md) §5.1):Thinking / Answer / Child 分栏,非混色日志 |
| 库调用方 | foreach 事件集合,自行决定 UI |
**view Stream 锁定(S3 UI):**
1. `reasoning` → 可折叠 Thinking;`delta` → 主文 Answer(连续拼接)。
2. `round` → 独立 Child/Workbook 卡(路径链 + 可选 `result`);不与父 Answer 混排。
3. `decision` → 时间线条目标记。
4. 视觉跟 view HIG 浅色壳,不用深色终端底。
5. **传输**:`POST /api/run` 直接 SSE;前端 `fetch`+`ReadableStream`(非页载 EventSource);rAF 合批;stick-to-bottom。
---
## 4. 与「返回优先」的关系
| 通道 | 职责 |
|------|------|
| stream / trace | **过程**(体验、调试、审计) |
| `# main` `**…**` / `plan.result` | **结果**(编排、OKF、调用方消费) |
| writeback `ok`/`error` | **落盘摘要**(默认可关) |
禁止:仅靠 stream 文本当作子任务成功条件;DONE / 固化仍看退出码、返回值与源码形态。
---
## 5. 推荐落地顺序
```text
S0 net/llm:SSE 读 + complete stream=True + 事件 foreach ✅
S1 step stream=True(echo 增量;返回 map 不变) ✅
S2 plan stream=True:round + 父 delta;trace 写回可选 ✅
S3 view 订阅(EventBus + GET /api/events + POST /api/run) ✅
```
### 开放点决议(S0)
1. **Eager 事件列表**(非惰性句柄):`complete stream=True` 返回 `List` of maps,可用今日 foreach。
2. **默认不自动 print**:`echo=False`;需要边读边打时传 `echo=True` / `打印增量=真`。
3. 中文:`## 运行` 用 `流式=` / `打印增量=`。
### 开放点决议(S2)
1. `plan` / `多步` 增加 `stream` / `echo` / `trace`(中文 `流式` / `打印增量` / `轨迹`)。
2. 事件挂在返回 map 的 `events`;父 `complete` 只冒泡 `delta`/`error`(嵌套 `done` 不进列表)。
3. `trace=True` → 写回槽 `trace`(与 TTY `echo` 可分立)。
4. **体验(父先子后)**:非命中路径先 `decompose`(SSE + 可选 TTY `plan:decompose`),再 `await`(SSE 占位 + 可选 TTY `plan:await`),子 quiet。修订轮仍是观察后父决策。SSE 本身用 `tests/ext/llm-stream-live.mq.md`。
验收:
1. 未传 `stream` 的金样零 diff。
2. `stream=True` 时用户在首包 token 到达前不应长时间无输出(允许短连接建立延迟)。
3. 最终 `result` 与非流式路径一致(同 prompt fixture)。
4. quiet 子任务仍不污染父 TTY。
---
## 6. 开放点
1. ~~Eager vs 惰性~~ → S0 选 eager;惰性句柄可后补。
2. ~~delta 默认 print~~ → 默认关;`echo=True` 可选。
3. ~~中文面~~ → `流式=` / `打印增量=`。
4. ~~S2~~ → `plan stream=True`:`round` / 父 delta / `decision` / `done`;可选 `trace`。
5. ~~**S3**~~ → `marqdo view`:进程内 EventBus;`GET /api/events`(SSE);`POST /api/run` 后台执行;Execution 区 EventSource 面板。CLI 默认不订阅。
S0 可与 [okf-near-match.md](okf-near-match.md) 并行,互不阻塞。
+33
View File
@@ -0,0 +1,33 @@
# `ext/agent` 深入优化(调研驱动)
| | |
|---|---|
| 状态 | **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) |
| 设计 | [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md) · [okf.md](../design/okf.md) |
| 邻近 | [agent-streaming.md](agent-streaming.md) · [okf-near-match.md](okf-near-match.md) |
---
## 1. 优化原则(来自调研)
1. **强化差异化,不向 LangChain 薄循环回退**(禁止隐藏 TOOL: 主路径、禁止整文件 LLM 重写工作簿)。
2. 把资源砸在:**工作簿质量、写回、固化、OKF 命中、过程可视**。
3. 外部 RAG/MCP 只作**工具**,不升为权威真相源。
自评四问见调研 §9。A0–A4 之后的缺口与建议分期 **B0–B5** 见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md)。
---
## 2. 建议分期(摘要)
| 波次 | 主题 | 验收线索 |
|------|------|----------|
| **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–A4** 实现分期。后续产品化 / 评测 / live MCP 等见 [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) §5(草案 B0–B5)。
+62
View File
@@ -0,0 +1,62 @@
# 官方扩展:`ext/quantum` 实现路线图
| | |
|---|---|
| 状态 | **Q0–Q7 完结 · Q8a/Q8b 完结 · Q8c 待做** |
| 日期 | 2026-08-28 |
| **锁定设计** | [design/ext-quantum.md](../design/ext-quantum.md) |
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-math.md](../design/stdlib-math.md) · [view.md](../design/view.md) |
| 安装 | `marqdo ext add quantum`(`quantum` / `量子`) |
本文只跟踪**实现阶段**。作者面、模拟语义、view 可视化、分期以设计文为准。
---
## 1. 目标回顾(一句)
**可运行的量子电路文档**:表声明门序列 → ABI 模拟概率/采样 → view 内嵌电路/概率 SVG;文档跑通即公式约定成立。
---
## 2. 落地阶段
| 阶段 | 内容 | 状态 |
|------|------|------|
| **Q0** | CATALOG + `plugins/quantum` ping + L1 `ensure_plugin` | **done** |
| **Q1** | 态向量;I/X/H/CX;`simulate` / `probabilities`;贝尔态 gold | **done** |
| **Q2** | Y/Z/S/T/R\* /CZ/SWAP;`run seed=`;中英 API | **done** |
| **Q3** | `steps=` 电路表;`draw` 轨线 SVG;view `record_plot` 或值识别 | **done** |
| **Q4** | 概率条 / 布洛赫;`matches_matrix`;examples + 用户文档 | **done** |
| **Q5** | 教学噪声 + barrier/measure/append/state — [ext-quantum-q5.md](../design/ext-quantum-q5.md) | **done(最小)** |
| **Q5.5** | `amplitude_damping` 轨迹 — [ext-quantum-q5.5.md](../design/ext-quantum-q5.5.md) | **done** |
| **Q6** | 公式/`matrix=` 自定义门 + `apply` — [ext-quantum-custom-gate.md](../design/ext-quantum-custom-gate.md) | **done** |
| **Q7a** | 密度矩阵 / Kronecker / 部分迹 / Hermitian 谱 / Schmidt / Pauli 期望 / 纯度·保真度 — [ext-quantum-q7.md](../design/ext-quantum-q7.md) | **done** |
| **Q7b** | 高级 SVG:hinton / city / density / paulivec / qsphere / multibloch | **done** |
| **Q7c** | 纠缠示例 + 用户文档 / skill 摘要 | **done** |
| **Q8a** | 电路 SVG:标签 gutter + dark/light/bw 门族分色 — [ext-quantum-viz-style.md](../design/ext-quantum-viz-style.md) | **done** |
| **Q8b** | probs / bloch / heatmap 共用令牌 | **done** (probs/bloch;heatmap → Q8c) |
| **Q8c** | 高级态图(hinton/city/…)换肤 | **pending** |
验收金样:既有 `tests/ext/quantum-*-smoke.mq.md`;Q7:`quantum-linalg-smoke`、`quantum-viz-advanced-smoke`。示例:`examples/quantum-bell/`、`examples/quantum-entanglement/`。
---
## 3. 已收敛的原开放点
| 原疑问 | 锁定结论(见设计文) |
|--------|----------------------|
| 并进 math? | **否**,独立 `ext/quantum` |
| 电路表 | **要做**(Q3),与方法链等价 |
| view 图 | 自绘 SVG;优先 `host_query("record_plot")`;不依赖 web |
| 自由函数面 | **不**与对象面并行 |
---
## 4. 与其它文档
| 文档 | 关系 |
|------|------|
| [design/ext-quantum.md](../design/ext-quantum.md) | **真理** |
| [stdlib-math.md](../design/stdlib-math.md) | 公式/作图精神对照;实现分离 |
| [ext-web.md](../design/ext-web.md) | 同属官方 ext + ABI + `ext add` 模板 |
| [view.md](../design/view.md) | 结构卡 + Execution 内嵌 SVG |
+59
View File
@@ -0,0 +1,59 @@
# 官方扩展:`ext/web` 实现路线图
| | |
|---|---|
| 状态 | **W0–W7 + P3 完结**(审计/RBAC/相册/ETag/外键已落地) |
| 日期 | 2026-08-28 |
| **锁定设计** | [design/ext-web.md](../design/ext-web.md) |
| 相关 | [ext-cli.md](../design/ext-cli.md) · [ext-abi.md](../design/ext-abi.md) · [ext-llm.md](../design/ext-llm.md) |
| 安装 | `marqdo ext add web`(`web` / `网页`) |
本文只跟踪**实现阶段**。类模型、赋值绑定、后台、`.env`、异步边界、ABI 名等以设计文为准。
---
## 1. 目标回顾(一句)
**表格完成动态站**:页面表拼组件、组件表绑库与样式、样式表定外观;热路径进 ABI 插件;可选 S3 / Redis。人写目标见设计 §0.1 与 `examples/man-write-site/`。
---
## 2. 落地阶段
| 阶段 | 内容 | 状态 |
|------|------|------|
| **W0** | CATALOG + L1 + `web_listen` Hello | **done** |
| **W1** | env 端口;`page` 四栏;nav 表;static | **done** |
| **W2** | SQLite `define`/`migrate`/`all` | **done** |
| **W3** | 三列绑定;变量名即表名;`/admin` CRUD+日志+布局 | **done** |
| **W3s** | 安全硬化:argon2 密码哈希、CSRF、SQLite 会话持久化、CSPRNG、登录限速 | **done** |
| **W3.5** | 人写面首版:`web.assemble` + `` `表`.`字段` `` + `examples/man-write-site` | **done**(编排袋仍可再瘦) |
| **W4** | Postgres;Redis / S3 驱动(见 [ext-web-drivers.md](../design/ext-web-drivers.md)) | **done** |
| **W4c** | 内容标配:SEO / Markdown / RSS / 分页 UI(见 [web-net-capabilities.md](../design/web-net-capabilities.md)) | **done** |
| **W5** | 上传与媒体:multipart 接收 + 落盘 + 下载(见 [web-net-capabilities.md](../design/web-net-capabilities.md) A5) | **done** |
| **W6** | 迁移 + FTS5 搜索;草稿/评论用既有 where/表;WS 广播 + 访问日志 | **done** |
| **W7** | Cache-Control / 404·500 / 重定向 / sitemap·robots / init 唯一·索引 / HTTPS 反代说明 | **done** |
| **P3** | 审计时间戳 / 外键 / RBAC / 相册 / ETag | **done** |
验收金样:`tests/ext/web-smoke.mq.md`、`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`。
---
## 3. 已收敛的原开放点
| 原疑问 | 锁定结论(见设计文) |
|--------|----------------------|
| listen 阻塞 vs 后台任务 | `# main` 内 `listen` **同步阻塞**;插件内部异步 |
| handler 形态 | **不主推**手写 REST;表 href + bind + 自动后台 |
| `marqdo web` 子命令 | scaffold 经 `web.scaffold`;`marqdo web new` 可后续补 |
| Windows + SQLite | 路径用 `DATABASE_URL` |
---
## 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` |
+2 -2
View File
@@ -47,7 +47,7 @@ index.mq.md (+ 导入的 .mq.md)
│
▼
┌───────────────────┐
│ 0. 源加载 / 模块图 │ frontmatter `> a.mq.md` → 依赖图
│ 0. 源加载 / 模块图 │ frontmatter `import a:a.mq.md` → 依赖图
└─────────┬─────────┘
▼
┌───────────────────┐
@@ -62,7 +62,7 @@ index.mq.md (+ 导入的 .mq.md)
└─────────┬─────────┘
▼
┌───────────────────┐
│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入合并
│ 3. 语义·绑定 │ Pass1: 收集函数(提升)+ 导入模块树(见 module-namespace)
│ │ 作用域链、形参、未定义名诊断
└─────────┬─────────┘
▼
+2 -2
View File
@@ -19,7 +19,7 @@
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
| **标准库** | S0–S3 完成;本波扩展 = 文件/系统/时间/JSON/网络([stdlib-modules.md](../design/stdlib-modules.md));数学/外联暂缓 | **P2 完成;五库扩展设计中** |
| **模块** | `> file.mq.md` 顶层函数合并,无命名空间 | 短期可继续用 |
| **模块** | [module-namespace.md](../design/module-namespace.md):**M1+M2 已落地**(库名绑定、`库.成员` / `use`;无扁平合并) | — |
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
@@ -131,7 +131,7 @@ L2 生态约定 catalog 收录;用户站专章
|------|------|------|
| **S0** | `len`(文本/表)、`str`、`int` | keywords.md 已列候选;字节码已有闲置 `Op::Len` 可接线 |
| **S1** | 表工具:取列、行数;字符串 trim/split(先内置或纯 mq 实现二选一) | 文档型语言高频 |
| **S2** | 官方 `lib/` 或 `std/` + 导入约定(仍可用 frontmatter;或日后 `> std/text.mq.md`) | 可生长而不破现有导入 |
| **S2** | 官方 `lib/` 或 `std/` + 导入约定(仍可用 frontmatter;或日后 `import text:std/text.mq.md`) | 可生长而不破现有导入 |
| **S3** | 错误类型约定(如非法 `int` 文本 → 诊断) | 依赖 P0 |
### 完成定义(S0)
+167
View File
@@ -0,0 +1,167 @@
# 对象继承语法(未来规划)
| | |
|---|---|
| 状态 | **I0–I3 已落地**(显式父构造约定;**不做**隐式 auto-super) |
| 日期 | 2026-08-10 |
| 相关 | [objects.md](../design/objects.md) · [markdown-mapping.md](../design/markdown-mapping.md) · [keywords.md](../design/keywords.md) |
| 提案语法 | `# 子类 = > 父类` |
---
## 1. 动机
今日 [`objects.md`](../design/objects.md) 明确非目标:**继承 / 接口 / 可见性**。
实际扩展(如 `# agent` / `# llm`)靠「再写一个对象 + 组合句柄」,缺少:
- 复用父构造 / 父方法而不复制 `.mq.md`
- 子类型在 `_type` 链上解析方法
- 与 Markdown 标题体系一致的、可读的继承声明
需要一种**不引入 `class`/`extends` 关键字**、且与现有 `=`(绑定)与 `>`(调用)语义兼容的写法。
---
## 2. 锁定语法(提案)
```markdown
# 子类 = > 父类
```
| 片段 | 既有含义 | 组合后含义 |
|------|----------|------------|
| `# 子类` | 定义对象 / 类型 | 子类型名 |
| `=` | 绑定 / 赋值 | 类型关系写在「类型定义槽」上 |
| `> 父类` | 调用(此处为类型名) | **基类引用**(不是构造实例) |
可选带参基类(若基类本身是泛化构造,v1 可暂不支持):
```markdown
# 特化智能体 = > 智能体
```
中英对称:
```markdown
# Child = > Parent
# 子类 = > 父类
```
### 2.1 为何不冲突
1. **今日** `# 名` 后接的是构造体正文,不是 `` `# 名 = …` `` 标题行。
2. **语句绑定**是 `*…*` 或行内 `` `x` = ``,不是 ATX `#` 标题。
3. **`> 父类` 在标题行**出现在 `=` 右侧:解析器可把「`#` 标题含 `=` 与 `>`」识别为**类型声明**,而非执行构造。
4. 真正构造实例仍是正文或 `# main` 里的 `` `x` = > 子类 … ``。
反例(仍是今日语义,不变):
```markdown
# main
*`a` = > 父类 *
```
---
## 3. 运行时语义(草案)
### 3.1 方法解析
实例 map 仍有 `_type` = 构造时的类型名(子类名)。
查找 `` `obj`.方法 ``:
1. 在 `_type` 对应对象上找 `## 方法`
2. 未找到 → 沿 **基类链** 查找
3. 仍无 → 报错(带类型链)
构造:
1. 若子类构造体未显式处理,可先调基类构造(见开放点:是否自动 `super`)。
2. 返回 map 的 `_type` = **最具体子类名**(不是父类名)。
### 3.2 子类正文
```markdown
# 工蜂 = > 智能体
## 采蜜
+ `花`
*`out` = > `self`.step task=`花` *
**`out`**
```
- 子类可定义新 `##`
- 可覆盖同名 `##`(子类优先)
- 站立提示 / 字段约定:文档层说明,v1 不引入可见性关键字
### 3.3 多继承
**v1 不支持。** 一个 `# 子 = > 父` 仅一条基类。混入用组合(句柄字段)而非多 `>`。
---
## 4. 解析与 AST
标题形态需在 [markdown-mapping.md](../design/markdown-mapping.md) / parse 中新增一种 object decl:
| 字段 | 值 |
|------|-----|
| `name` | 子类 |
| `base` | 父类(标识符) |
| `body` | 与今日 object body 相同 |
歧义处理:
- `# Foo = 1` → **非法**(右侧必须是 `> 类型名`)
- `# Foo = > bar.baz` → v1 **非法**(基类须为已定义对象名,不走任意调用表达式)
- 基类尚未定义 → Pass1 收集后解析;循环继承报错
---
## 5. 与标准库 / 扩展
| 用途 | 例子 |
|------|------|
| 扩展官方智能体 | `# 客服 = > agent` / `# 客服 = > 智能体` |
| 扩展 llm 句柄 | 一般不必要;优先组合 |
| 用户域模型 | `# 订单服务 = > 服务基类` |
官方 `lib/*` 仍以自由函数为主;继承主要服务 `ext/` 与用户对象。
---
## 6. 推荐落地顺序
```text
I0 语法 + AST + 金样(解析/循环继承错误) ✅
I1 方法解析沿基类链;构造 _type=子类 ✅
I2 覆盖方法;文档更新 objects.md ✅
I3 显式父构造约定(**不做**隐式 auto-super) ✅
```
验收:
1. 无继承文件行为不变。
2. 子类实例能调父类 `##`;覆盖后只走子类。
3. `` # A = > B `` / `` # B = > A `` 诊断清晰。
4. Skill / 金样:`tests/structure/inherit-*.mq.md`(含显式 `` `self` = > Parent ``)。
---
## 7. 开放点
1. ~~**隐式 super**~~ → **不做**:子类构造体不自动跑父构造。需要父初始化时正文写 `` `self` = > 父类 … `` 再改字段后 `**`self`**`;构造完成时 `_type` 仍为最具体子类名。
2. 中英基类别名:`> agent` 与 `> 智能体` 是否同一对象(取决于模块导出)。
3. 继承是否写入 OKF Module 页(catalog 展示 `extends`)——可随 O3/O4 增强。
---
## 8. 非目标
- 接口 / 抽象方法 / 可见性(`public`)
- 多继承、mixin 关键字
- 用继承替代 `plan` 工作簿接力
- 把 `# 子 = > 父` 解析成「定义时立即构造父实例」
+108
View File
@@ -0,0 +1,108 @@
# OKF 相近任务命中
| | |
|---|---|
| 状态 | **A 规范句 + B aliases + C 父裁决(soft_match)+ D 本地 n-gram `near` 已落地**;E dense embedding 仍非目标 |
| 日期 | 2026-08-11 |
| 相关 | [okf.md](../design/okf.md) §7 · [ext-agent-plan.md](../design/ext-agent-plan.md) §4.2 · [ext-agent.md](../design/ext-agent.md) |
| 触发观察 | `man-test`:相近 goal 生成两份独立 resource |
---
## 1. 问题
v1 agent-kb **精确命中仍是默认快路径**:
1. `normalize_goal`:去首尾空白、合并连续空白(**不做**近义改写)。
2. `sig` = 规范化字符串的稳定短哈希;`slug` = 可读路径名。
3. `agent_kb_lookup`:精确 → aliases → canonicalize → **本地 n-gram `near`(默认开)**;仍 miss 且 `plan soft_match=True` 时父裁决 REUSE/NEW(候选为排序 near 列表)。
历史痛点(已由 A/B/C/D 缓解):
| goal(调用方输入) | 旧行为 |
|--------------------|--------|
| `你是一个智能体,帮我规划明天的行程` | 独立 slug,与下方不命中 |
| `帮我规划明天的行程` | 另一份 resource |
| `帮我规划明天行程` | 又一份(近句碎片) |
调用方直觉:「这不是同一件事吗?」——现可用 canonicalize、默认 `near_match`,或显式 `soft_match` 父裁决。
---
## 2. 为何精确指纹仍优先
| 理由 | 说明 |
|------|------|
| 假阳性代价高 | 错复用旧工作簿比多建一个文件更糟 |
| 可审计 | `sig` 可复算;`near` 留下 `match`/`score` |
| 哲学 | 多轮 = 子文件接力 + OKF 索引,不是聊天式模糊检索 |
**结论:** 精确命中长期保留为**默认快路径**;`near` 是可关闭的第四趟(`near_match=False`)。
---
## 3. 已落地层
### A. 规范化后再精确命中 — **已落地**
`agent_kb_canonicalize`:剥站立前缀、去尾标点;`match: canonical`。
### B. 别名 / 标签表 — **已落地**
Task FM `aliases:`;`match: alias`。
### C. 父智能体软裁决 — **已落地(默认关)**
`plan soft_match=True`:`agent_kb_near_match` 排序候选(含 `score`;空则退回 `list_tasks`)→ 父 `DECISION: REUSE` + `SLUG:` 或 `DECISION: NEW`。
### D. 本地字符 bigram + 余弦 — **已落地(默认开)**
| | |
|--|--|
| 做法 | 稀疏词法向量化(**不是** embedding 模型):canonicalize 后对 goal 与 Task `title\|description\|aliases` 建字符 bigram 词袋,算余弦 |
| API | `agent_kb_near_match`;`agent_kb_lookup` 第四趟 |
| 参数 | `near_match`/`近义命中` 默认 `True`;`near_threshold`/`近义阈值` 默认 `0.78` |
| 痕迹 | `match: near` + `score`;`cache=soft-hit`;可写 alias |
术语:这是 **sparse lexical near-match**,勿宣传为向量库 / embedding 检索。
### E. Dense embedding(可选远期)
远程 / 本地 dense 向量与 ANN **仍非本仓默认目标**;仅当 D 在真实包体量下证据不足时再评估。
---
## 4. 演进顺序
```text
精确 sig(永不删除)
→ A 规范句 + B aliases(已落地)
→ C soft_match 父裁决(已落地,默认关)
→ D 本地 n-gram near(已落地,默认开)
→ E dense embedding(仅有证据再开)
```
验收原则:
1. `near_match=False` 时与无 near 行为一致;`force`/`optimize` 仍跳过 reuse。
2. 软/近义命中留下 `cache=soft-hit` / `match` / 可选 `score`。
3. 假阳性可被 `force=True` / 显式 `workbook=` / 调高 `near_threshold` 覆盖。
4. 实现仍在 **agent 插件 + `ext/ai`**,不进核心 `src/host`。
---
## 5. 调用方建议
- 固定规范 goal;站立语可由 canonicalize 剥掉。
- 近句碎片依赖默认 `near_match`;字面差更大时开 `soft_match=True`。
- 策展:合并重复 task,次要措辞写入 `aliases`(O4)。
---
## 6. 与现有路线图的关系
| 条目 | 关系 |
|------|------|
| [okf.md](../design/okf.md) O2 / O5 | 精确 reuse + A/B/C/D;E dense 仍待 |
| [okf.md](../design/okf.md) O4 | `kb query` / 策展可继续扩 aliases |
| [ext-agent-plan.md](../design/ext-agent-plan.md) | 多轮仍只走子文件接力;软命中只影响「选哪个子文件」 |
+303
View File
@@ -0,0 +1,303 @@
# 表格语义打磨:列表 · 字典 · 嵌套 · 脚注取元(未来规划)
| | |
|---|---|
| 状态 | **T0–T5 已落地**(单元格表达式见 [table-cell-expressions.md](../design/table-cell-expressions.md)) |
| 日期 | 2026-08-12 |
| 相关 | [markdown-mapping.md](../design/markdown-mapping.md) §9 · [table-cell-expressions.md](../design/table-cell-expressions.md) · [objects.md](../design/objects.md) · [stdlib.md](../design/stdlib.md)(`lib/table`) · [keywords.md](../design/keywords.md) |
| 现状金样 | [tests/structure/collection.mq.md](../../tests/structure/collection.mq.md) |
---
## 1. 问题
### 1.1 今日表格 =「竖表 → 列表」
```markdown
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
| 桃 |
```
语义(已落地):绑定为**列表**(列值);表头名供 `` [`果`](`篮子`) `` 遍历。
单列表头是当前唯一一等集合外形;**没有**一等「横表 = 字典」。
### 1.2 缺字典外形与嵌套
用户期望:GFM 表的两种几何对应两种结构,并允许嵌套——这样「多行表格」才有稳定、可教的含义。
### 1.3 不能按下标 / 键直接取元
今日要从列表取第 *n* 项,往往只能遍历或走 `lib/table`(`row_at` 等),**语言级**缺少与 Markdown 同构的取元语法。字典亦然。
---
## 2. 目标
1. **竖表**继续表示列表(兼容现有金样)。
2. **横表**(多列表头 + 数据行)表示字典及「字典 ↔ 列表」嵌套。
3. 用 **Markdown 脚注外形** 做列表下标 / 字典键的取元(表达式级)。
4. 不引入 `[]` 下标关键字风暴;少而精,与「标记即语法」一致。
非目标:
- 完整电子表格公式引擎
- 用表声明对象字段 schema(仍见 objects 非目标;与数据集合分开)
- 破坏现有单列竖表金样
---
## 3. 表格几何 → 值(锁定提案)
判定在 **绑定右侧的 GFM 表** 上做(`` `名` = `` 后接表)。
### 3.1 竖表 → 列表(现状,保留)
**形状:** 恰好 **1** 列。
```markdown
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
| 桃 |
```
| 结果 | 说明 |
|------|------|
| 值 | `List`:`["苹果","梨","桃"]` |
| 表头 | 元素逻辑名(foreach 绑定名);不进入列表元素 |
### 3.2 横表单数据行 → 字典
**形状:** ≥2 列,且 **恰好 1 行数据**(表头 + 分隔 + 一行)。
```markdown
`分类` =
| 苹果 | 黄瓜 | 鼠标 |
|------|------|------|
| 水果 | 蔬菜 | 数码用品 |
```
| 结果 | 说明 |
|------|------|
| 值 | `Map`:`苹果→水果`, `黄瓜→蔬菜`, `鼠标→数码用品` |
| 键 | 表头单元格文本(规范化空白后) |
| 值 | 唯一数据行对应列 |
### 3.3 横表多数据行 → 字典套列表(默认)
**形状:** ≥2 列,且 **≥2 行数据**。
```markdown
`货架` =
| 苹果 | 黄瓜 |
|------|------|
| 红富士 | 青瓜 |
| 嘎啦 | 黄瓜条 |
```
**默认语义(锁定):列向聚合**
```text
{
"苹果": ["红富士", "嘎啦"],
"黄瓜": ["青瓜", "黄瓜条"]
}
```
即:**键 = 表头,值 = 该列数据行组成的列表**。
这与竖表「一列 = 一列表」在多列时自然推广,嵌套外形稳定。
**备选语义(不默认):行向记录列表**
```text
[
{"苹果":"红富士","黄瓜":"青瓜"},
{"苹果":"嘎啦","黄瓜":"黄瓜条"}
]
```
更像 SQL / CSV。若未来需要,用显式标记区分(见 §3.5),**不得**与默认列向字典静默混用。
### 3.4 单列多行 vs 多列
| 列数 | 数据行 | 值类型 |
|------|--------|--------|
| 1 | ≥0 | `List` |
| ≥2 | 1 | `Map`(标量值) |
| ≥2 | ≥2 | `Map`(值均为 `List`) |
| ≥2 | 0 | `Map`(键存在,值空列表或错误——开工时锁定为「空列表」) |
### 3.5 显式形态标记(行向记录)— **已落地**
首列表头为下列之一时,整表改为**行向**(不静默混用列向默认):
| 标记 | 说明 |
|------|------|
| `@` | ASCII 短标记 |
| `行` | 中文 |
| `row` | 英文 |
规则:
1. 标记列**不进入**记录字段(数据格可写行号给人看)。
2. 其余列 → 每行一个 `Map`;整体为 `List`。
3. 须至少有一列字段(仅 `| 行 |` → 诊断)。
4. 数据行数任意(含 0 → 空列表;1 行仍是 `List` of one `Map`,不是列向 `Map`)。
```markdown
`订单` =
| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
| 2 | 梨 | 3 |
```
→ `[{品名: 苹果, 数量: 2}, {品名: 梨, 数量: 3}]`。取元:`` `订单`[^1][^品名] ``。
---
## 4. 脚注取元(提案)
### 4.1 为何用脚注外形
- Markdown 已有 `[^…]` 引用形态,读者不陌生。
- 避免 `篮子[0]` 与链接 / 图片语法纠缠。
- 与「标识符反引号」组合清晰:`` `篮子`[^1] ``。
### 4.2 列表:按下标
```markdown
*`第一` = `篮子`[^1] *
> print text=`第一`
```
| 约定 | 选择(提案) |
|------|----------------|
| 下标基准 | **1-based**(与 Markdown / 人类表格行语感一致;脚注 `[^1]` 即第一项) |
| `[^0]` | 报错(保留 0 不用)或日后表示「最后一项」—— v1 **报错** |
| 越界 | 清晰诊断 `path:line:col` |
### 4.3 字典:按键
键为脚注标签文本(推荐与表头一致;**允许纯数字键**,如基矢标签 `00`)。基名可写 `` `概率`[^00] `` 或 `` 概率[^00] ``(紧跟 `[^` 时可省略反引号):
```markdown
*`种` = `分类`[^苹果] *
*`p00` = `概率`[^00] *
> print text=`种`
```
| 规则 | 说明 |
|------|------|
| `[^苹果]` | 键文本 `苹果` |
| `[^00]` / `[^1]` | 键文本 `00` / `1`(**不是**「第 n 个 map 条目」) |
| 含空格的键 | 允许 `[^数码用品]`;极端键用引号策略开工前定 |
| 缺失键 | 报错或 `None`——建议 v1 **报错**(少静默) |
### 4.4 嵌套取元
列向字典套列表:
```markdown
*`货架` = …多行横表… *
*`第一种苹果` = `货架`[^苹果][^1] *
```
从左到右:先键、再下标。
类型不对(对 List 用非数字键名脚注)→ 诊断。Map 上的纯数字标签按**键名**解析。
### 4.5 与 GFM「定义脚注」正文
标准 Markdown 文末 `[^1]: 说明` 是**注释/文献**,不是取元。
规则:
- **表达式位置**的 `` `名`[^…] `` → 取元。
- **文末脚注定义块** → 仍作注释(或不支持,避免混用)。
- 不要求为每个 `[^1]` 写定义;Marqdo 取元**不依赖**定义块。
### 4.6 与 `lib/table` 关系
| 层 | 职责 |
|----|------|
| 语言脚注取元 | 一等、短、金样覆盖 |
| `lib/table` | 行列切片、整表变换;可逐步把 `row_at` 文档改为「等价于脚注」 |
---
## 5. foreach 与字典
今日:`` [果](篮子) `` / `` [`果`](`篮子`) `` 遍历列表(裸名与反引号均可)。
扩展草案:
| 集合 | 遍历 |
|------|------|
| List | 不变,项为元素 |
| Map | `` [`键`](`映射`) `` 遍历键;或 `` [`对`](`映射`) `` 若引入对类型—— v1 建议 **遍历键**,值用 `` `映射`[^…] `` / 辅助 |
具体键值对遍历语法开工前写一小段进 mapping;避免与链接外形 `` [`x`](`y`) `` 冲突(今日已是 foreach)。
---
## 6. 推荐落地顺序
```text
T0 横表单行 → Map;金样;竖表回归 ✅
T1 横表多行 → Map of List(列向);嵌套金样 ✅
T2 脚注取元:List [^n]、Map [^键]、链式 ✅
T3 文档:markdown-mapping §9;Skill / examples;table 库 ✅
T4 行向记录表:首列 `@` / `行` / `row` ✅
T5 数据单元格 = 表达式(同调用实参值语法) ✅
```
验收:
1. `tests/structure/collection.mq.md` 行为不变。
2. 新金样:`collection-map.mq.md`、`collection-map-list.mq.md`、`footnote-index.mq.md`。
3. 错误下标 / 缺键带 `line:col`。
4. 双后端(tree / bytecode)一致。
5. **T5:** 单元格 `` `var` `` / 算术;URL 与 `gpt-4o-mini` 仍为文本;设计见 [table-cell-expressions.md](../design/table-cell-expressions.md)。
---
## 7. 教学对照(写入 Skill 的素材)
| 几何 | 含义 | 取元 |
|------|------|------|
| 单列竖表 | 列表 | `` `a`[^1] `` |
| 多列 + 一行 | 字典 | `` `m`[^键] `` |
| 多列 + 多行 | 字典 → 列表 | `` `m`[^键][^1] `` |
| 首列 `@`/`行`/`row` | 记录列表 | `` `r`[^1][^字段] `` |
竖表表头是「元素名」;横表表头是「键名」——几何决定角色,减少「这张表到底是啥」的歧义。
---
## 8. 开放点
1. 表头重复列名:报错还是后缀 `_2`?建议 **报错**。
2. 数字表头:字典键为文本 `"1"` 还是整数?建议 **文本**(与单元格一致)。
3. 脚注 1-based 与宿主语言习惯(0-based)的文档警示。
4. 字节码:`Index` / `KeyGet` 操作码是否与 T2 同批。
---
## 9. 与其它规划的关系
| 文档 | 关系 |
|------|------|
| [object-inheritance.md](object-inheritance.md) | 正交;表不表示类字段 schema |
| [agent-streaming.md](agent-streaming.md) | 正交;事件列表可用竖表金样演示 foreach |
| [okf-near-match.md](okf-near-match.md) | 正交 |
+88
View File
@@ -0,0 +1,88 @@
# 第 1 章:Marqdo 是什么
## 1.1 一句话介绍
**Marqdo = Markdown(Marq)+ 执行(do)**。它把 Markdown 的**标记当作编程语法**:同一个 `.mq.md` 文件,打开给人看是文档,运行给机器看是程序。
在大型项目里,说明、示例与实现往往分叉成三份「真相」,改一处忘另一处。Marqdo 让这三者**同源**——你写的文档本身就是可执行的代码。
## 1.2 与其他语言的区别
传统编程语言(如 Python)需要单独写文档和注释;Marqdo 反过来了——**文档本身就是程序**。
| 传统语言 | Marqdo |
|----------|--------|
| 代码在 `.py`,文档在 `.md` | 代码与文档同在 `.mq.md` |
| `def` / `if` / `for` / `return` 是关键字 | 用 Markdown 标记 `##` / `1.` / `-` / `**…**` 表达 |
| 注释用 `#` 或 `//` | **无标记的叙述就是注释** |
| 大括号 `{}` 或缩进界定代码块 | 标题层级 `#` / `##` 界定作用域 |
关键点:**不要**试图写 `if`、`else`、`while`、`for`、`def`、`return` 这些关键字——它们不是 Marqdo 的语法。控制流由 Markdown 承担。
## 1.3 安装
Marqdo 用 Rust 编写。从以下任一方式获取:
- **发布包**:从 GitHub Releases 下载预编译二进制(已内置标准库)。
- **源码构建**:
```bash
git clone https://github.com/cflmy/marqdo.git
cd marqdo
cargo build --release
# 二进制位于 target/release/marqdo
```
验证安装:
```bash
marqdo --version
```
## 1.4 第一个程序
创建一个文件 `hello.mq.md`:
```markdown
# Hello World
这是叙述文字,也就是注释。
> print text=Hello World!
```
- `# Hello World` —— 对象标题。`# main` 是入口;当文件只有唯一一个顶层 `#` 对象时,它也可作为入口。
- 空行后的普通文字是**注释**(叙述)。
- `> print text=Hello World!` —— 调用内置函数 `print` 输出一行文本。
运行:
```bash
marqdo run hello.mq.md
```
输出:
```text
Hello World!
```
## 1.5 中英双语内核
Marqdo 内核内置函数都有中英别名,**无需导入,可混用**:
```markdown
# main
> 打印 内容=你好,世界!
```
`打印` 与 `print` 是同一个内置函数,`内容` 与 `text` 是同一个参数名。
## 1.6 文件后缀:`.mq.md`
Marqdo 程序的**后缀必须是 `.mq.md`**(可执行源文件),不能用普通的 `.md`。一个 `.md` 文件默认只是文档;一个 `.mq.md` 文件既是文档又是程序。
## 1.7 下一步
你已经能写出并运行第一个程序了。接下来学习[第 2 章:基本语法](./02-基本语法.md)——理解 `.mq.md` 里哪些是代码、哪些是注释,以及标识符的写法。
+151
View File
@@ -0,0 +1,151 @@
# 第 2 章:基本语法
## 2.1 文件结构
一个 `.mq.md` 文件由以下几部分组成:
1. **Frontmatter**(可选):文件开头的成对 `---` 之间的元信息,如标题、导入。
2. **对象 / 函数定义**:以 `#` / `##` 开头的标题。
3. **叙述注释**:无标记的普通文字段落。
4. **可执行语句**:以标记开头的行。
```markdown
---
title: 我的程序
---
# main
这是叙述段落,整段都是注释。
> print text=Hello
```
## 2.2 代码 vs 注释:空行分段规则
Marqdo 的注释规则很特别:**无标记的叙述就是注释**,靠空行分段。
规则:
- 空行之后的第一行若**无标记**(普通文字)→ 这一段是**注释**。
- 注释段内的**每一行**(直到下一个空行)都是注释——即使它长得像代码。
```markdown
# main
这段注释里有一行看起来像代码,但它不会执行:
*not_executed = 1*
> print text=这也是注释
空行之后,代码开始运行:
> print text=这行会运行
```
> **注意**:叙述与可执行代码之间**必须空一行**。忘记空行会让本意是注释的文字被当作代码,或让代码被吞进注释段。
## 2.3 标记一览表
以下标记表示「这是代码」:
| 标记 | 含义 |
|------|------|
| `#` | 对象 / 类型(`# main` = 入口) |
| `##` … `######` | 函数 / 方法(嵌套按标题深度) |
| `` + `名` `` | 函数标题下的形参 |
| `1.` `2.` … | 条件分支 |
| `-` | 循环(遍历或 while) |
| `> 函数 参数` | 调用 |
| `*…*` | 程序语句(赋值 / 表达式) |
| `**…**` | 返回值 |
| `|` 开头的 GFM 表格 | 集合(列表 / 字典) |
| `---` / `***`(函数体内) | 结束函数体 |
## 2.4 标识符与反引号
Marqdo 中,**变量、参数名用反引号 `` ` `` 包裹**,这与 Markdown 的代码/链接语法脱钩,避免歧义。
```markdown
## 问候
+ `谁`
> print text=Hello, `谁`!
```
- `+ `谁`` —— 声明形参 `谁`
- `> print text=Hello, `谁`!` —— 在字符串中引用变量 `谁`
> **注意**:反引号规则有例外。在 `*…*`(斜体语句)和 `**…**`(粗体返回)内部,**裸标识符就是变量**,反引号可以省略(详见 [第 3 章](./03-变量与赋值.md))。
## 2.5 字面量
Marqdo 的字面量:
| 类型 | 示例 | 说明 |
|------|------|------|
| 数字 | `1` `3.14` `-5` | 整数 / 浮点 / 负数 |
| 布尔 | `True` `False`(`真` `假`) | 布尔值 |
| 空值 | `None`(`空`) | 空值 |
| 文本 | `hello`(裸 token) | 无转义,按字面量 |
| 字符串 | `"Hello\n"` | 双引号,支持转义与变量插值 |
| 列表 | `[1, 2, 3]` | 通过表格构造 |
| 字典 | `{"a": 1}` | 通过表格构造 |
文本 vs 字符串的区别:
- **裸 token**(如 `hello`、`路径`):按字面量,不转义,适合简短文本。
- **双引号字符串**:需要转义(`\n` 等)或嵌入变量时使用。
```markdown
> print text=Hello World! # 裸 token,按字面量
*msg = "Hello, `name`!\n"* # 字符串,可插值、可转义
```
## 2.6 关键字(不可作变量名)
以下单词是 Marqdo 的**保留关键字**,不能用作变量名:
| 英文 | 中文 | 含义 |
|------|------|------|
| `True` | `真` | 布尔真 |
| `False` | `假` | 布尔假 |
| `None` | `空` | 空值 |
| `and` | `且` | 逻辑与 |
| `or` | `或` | 逻辑或 |
| `not` | `非` | 逻辑非 |
**不要**尝试用 `if` / `else` / `while` / `for` / `def` / `return` ——它们不是关键字,也没有意义。
## 2.7 一个完整的例子
把学到的串起来:
```markdown
# main
这是一个完整示例:定义函数、调用、输出。
> 问候 谁=Marqdo
## 问候
+ `谁`
> print text=你好,`谁`!
---
## 加一
+ `n`
**n + 1**
```
运行输出:
```text
你好,Marqdo!
```
## 2.8 下一步
你已经理解 `.mq.md` 的基本结构了。接下来学习[第 3 章:变量与赋值](./03-变量与赋值.md),掌握 Marqdo 的值存储方式。
+121
View File
@@ -0,0 +1,121 @@
# 第 3 章:变量与赋值
## 3.1 什么是变量
变量是给数据起的一个名字。Marqdo 中,变量在**斜体语句 `*…*`** 中通过 `=` 绑定:
```markdown
*x = 1*
*name = "Marqdo"*
*ok = True*
```
> **重要**:在 `*…*` / `**…**` 内部,**裸标识符就是变量**——不需要反引号。这是 Marqdo 的关键约定。
## 3.2 绑定的三种写法
### 写法一:斜体语句 `*…*`(推荐)
```markdown
*x = 1*
*y = x + 2*
```
这是最常用的绑定方式。裸标识符就是变量。
### 写法二:行首反引号绑定(无 `*…*`)
```markdown
`x` = 1
```
不带 `*…*` 的绑定,变量名**需要反引号**。常用于绑定集合(表格)或公式:
```markdown
`篮子` =
| 果 |
|----|
| 苹果 |
```
### 写法三:绑定调用结果
```markdown
*len_s = > len value="hello"*
```
`*…*` 内用 `= >` 表示「把调用结果赋给变量」。
## 3.3 引用变量
在 `*…*` 内部,直接写变量名即可:
```markdown
*a = 5*
*b = a * 2*
> print text=`b` # 独立 > 调用中,变量要反引号
```
> **关键区别**:在**独立 `>` 调用**(如 `> print …`)里,裸词是**文本**,所以引用变量要加反引号:`> print text=`b``。而在 `*…*` / `**…**` 内,裸词是**变量**:`*b = a * 2*`。
## 3.4 字符串与插值
### 双引号字符串
```markdown
*msg = "Hello, World!"*
```
### 转义字符
| 转义 | 含义 |
|------|------|
| `\n` | 换行 |
| `\t` | 制表 |
| `\r` | 回车 |
| `\\` | 反斜杠 `\` |
| `\"` | 双引号 `"` |
| `\'` | 单引号 `'` |
| `\xHH` | 十六进制字符(如 `\x22` → `"`) |
| `\u{...}` | Unicode 码点(如 `\u{4e2d}` → `中`) |
未知转义(如 `\q`)**按字面保留**(`\q` → `\q`),不报错。
### 变量插值
字符串内用 `` `变量` `` 插值:
```markdown
*name = "Marqdo"*
*msg = "Hello, `name`!"*
> print text=`msg` # 输出:Hello, Marqdo!
```
## 3.5 完整示例
```markdown
# main
*name = "Alice"*
*age = 30*
*next_age = age + 1*
> print text=名字:`name`
> print text=明年:`next_age` 岁
*msg = "你好,`name`!你明年 `next_age` 岁。"*
> print text=`msg`
```
输出:
```text
名字:Alice
明年:31 岁
你好,Alice!你明年 31 岁。
```
## 3.6 下一步
你已经会存取数据了。接下来学习[第 4 章:输出与输入](./04-输出与输入.md),与用户交互。
+93
View File
@@ -0,0 +1,93 @@
# 第 4 章:输出与输入
## 4.1 输出:`print` / `打印`
`print`(中文 `打印`)是内置函数,用于向标准输出写一行文本。**输出不是 `**粗体**`**——粗体是返回值,不是打印。
```markdown
# main
> print text=Hello World!
```
中英等价:
```markdown
> 打印 内容=你好,世界!
```
| 英文 | 中文 | 参数 |
|------|------|------|
| `> print text=…` | `> 打印 内容=…` | `text` ≡ `内容` |
### 输出变量
独立 `>` 调用中,变量用反引号:
```markdown
*x = 42*
> print text=`x` # 输出:42
```
### 输出拼接
```markdown
*name = "Marqdo"*
> print text=欢迎使用 `name`!
```
## 4.2 输入:`input` / `输入`
`input`(中文 `输入`)读取一行用户输入:
```markdown
# main
> input prompt=你叫什么名字?
```
| 英文 | 中文 | 参数 |
|------|------|------|
| `> input prompt=…` | `> 输入 提示=…` | `prompt` ≡ `提示` |
### 读取并保存输入
```markdown
# main
*name = > input prompt="请输入名字:"*
> print text=你好,`name`!
```
> `input` 的 `prompt` 参数可省略(缺省)。
## 4.3 完整示例:一个问答程序
```markdown
# main
这是一个人机问答程序。
*name = > input prompt="你叫什么名字?\n"*
> print text=你好,`name`!
*age = > int value=`age_input`*
```
> **注意**:上面的示例为了展示 `int` 用法,`age_input` 尚未定义。实际中你需要先从 `input` 得到字符串,再用 `int` 转换。完整可运行版本:
```markdown
# main
*name = > input prompt="你叫什么名字?\n"*
> print text=你好,`name`!
*age_str = > input prompt="你几岁?\n"*
*age = > int value=`age_str`*
*next_age = age + 1*
> print text=`name`,你明年 `next_age` 岁。
```
## 4.4 下一步
你已经能与用户交互了。接下来学习[第 5 章:运算符与比较](./05-运算符与比较.md)。
+122
View File
@@ -0,0 +1,122 @@
# 第 5 章:运算符与比较
## 5.1 算术运算符
在 `*…*` 表达式内部:
```markdown
*a = 10*
*b = 3*
*sum = a + b* # 13
*diff = a - b* # 7
*prod = a * b* # 30
*quo = a / b* # 3.33…(浮点除法)
```
| 运算符 | 含义 |
|--------|------|
| `+` | 加法 / 拼接 |
| `-` | 减法 |
| `*` | 乘法 |
| `/` | 除法 |
> **注意**:在裸表达式里 `/` 是除法;但在**调用实参 / 参数默认值**中,不空格相连的 `a/b` 会被当作路径文本(详见[第 11 章](./11-模块与导入.md))。
## 5.2 字符串拼接
`+` 也可以拼接字符串:
```markdown
*first = "Hello, "*
*second = "World!"*
*msg = first + second*
> print text=`msg` # Hello, World!
```
> 在 `*…*` 内变量是裸名;若拼接的是字符串字面量,要加引号。
## 5.3 比较运算符
| 运算符 | 含义 |
|--------|------|
| `==` | 相等 |
| `>` | 大于 |
| `<` | 小于 |
| `>=` | 大于等于 |
| `<=` | 小于等于 |
```markdown
*n = 5*
1. `n` > 3
> print text=大于 3
2. *
> print text=小于等于 3
```
## 5.4 逻辑运算符
| 英文 | 中文 | 含义 |
|------|------|------|
| `and` | `且` | 逻辑与 |
| `or` | `或` | 逻辑或 |
| `not` | `非` | 逻辑非 |
```markdown
*age = 20*
*has_id = True*
1. `age` >= 18 and `has_id`
> print text=可以进入
2. *
> print text=不能进入
```
## 5.5 布尔值
布尔值字面量:`True` / `False`(中文 `真` / `假`)。
```markdown
*is_admin = False*
1. `is_admin` == True
> print text=管理员
2. *
> print text=普通用户
```
也可以直接用布尔变量作条件:
```markdown
*flag = True*
1. `flag`
> print text=为真
2. *
> print text=为假
```
## 5.6 完整示例
```markdown
# main
*score = 85*
*passed = score >= 60*
*bonus = passed and score >= 80*
> print text=及格:`passed`
> print text=优秀:`bonus`
```
输出:
```text
及格:True
优秀:True
```
## 5.7 下一步
你已经能计算和判断了。接下来学习[第 6 章:函数](./06-函数.md),把逻辑封装起来复用。
+188
View File
@@ -0,0 +1,188 @@
# 第 6 章:函数
## 6.1 定义函数
在 Marqdo 中,函数用 `##`(及更深)标题定义:
```markdown
## 加一
+ `n`
**n + 1**
```
- `## 加一` —— 函数名
- `+ `n`` —— 参数
- `**n + 1**` —— 返回值(**粗体 = 返回**)
函数可以挂在 `# main` 之下作为嵌套函数,也可以作为顶层自由函数。
## 6.2 调用函数
使用 `>` 调用(具名参数或位置参数):
```markdown
# main
> greet who=World # 具名参数
> greet World # 位置参数
## greet
+ `who`
> print text=Hello, `who`!
---
```
### 具名 vs 位置
```markdown
> 问候 谁=Marqdo # 具名:名=值
> 问候 Marqdo # 位置:按形参顺序
```
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。
> 具名实参的值可以含空格,直到下一个 `名=` 边界;位置实参是单个词法单元(不含空格)。
## 6.3 参数与默认值
可选参数用 `=默认值`:
```markdown
## 问候
+ `谁`
+ `礼貌`=False
1. `礼貌`
> print text=您好,`谁`!
2. *
> print text=嗨,`谁`!
```
调用:
```markdown
> 问候 谁=小明
> 问候 谁=小明 礼貌=True
```
## 6.4 返回值:`**…**`
用 `**…**` 返回表达式结果:
```markdown
## 加一
+ `n`
**n + 1**
```
调用并绑定结果:
```markdown
# main
*b = > 加一 n=1*
> print text=`b` # 2
```
### 返回 None:`****`
`****`(或空粗体 `**` + 空白 + `**`)返回 `None` 并结束函数体:
```markdown
## 静默
+ `x`
****
```
### 字符串返回
```markdown
## 问候语
+ `谁`
**"你好," + 谁 + "!"**
```
## 6.5 结束函数体:`---` / `***`
对于**没有返回值、只有副作用**的函数,用单独一行 `---` 或 `***` 结束函数体,避免后续兄弟语句被吞掉:
```markdown
# main
> 问候 谁=World
## 问候
+ `谁`
> print text=Hello, `谁`!
---
## 下一个函数
...
```
> `---` 仅在**函数体顶层单独一行**时表示「结束本函数」;文件开头的成对 `---` 是 frontmatter,不会混淆。
## 6.6 完整示例
```markdown
# main
> 问候 谁=Alice 礼貌=True
## 问候
+ `谁`
+ `礼貌`=False
1. `礼貌`
> print text=您好,`谁`!
2. *
> print text=嗨,`谁`!
---
## 加一
+ `n`
**n + 1**
```
输出:
```text
您好,Alice!
```
## 6.7 函数嵌套(标题深度)
嵌套辅助函数用更深的标题:
```markdown
# main
> 处理 名字=小明
## 处理
+ `名字`
*上 = > 大写 文本=`名字`*
> print text=`上`
### 大写
+ `文本`
**> str `文本`**
```
> 深度约定:`##` 是 `#` 的子级,`###` 是 `##` 的子级……按标题深度嵌套。
## 6.8 下一步
你已经会封装函数了。接下来学习[第 7 章:条件分支](./07-条件分支.md)。
+138
View File
@@ -0,0 +1,138 @@
# 第 7 章:条件分支
## 7.1 基本分支:`1.` `2.` …
Marqdo 用**有序列表** `1.` `2.` `3.` … 表达条件分支:
```markdown
# main
*n = 5*
1. `n` > 0
> print text=正数
2. `n` < 0
> print text=负数
3. *
> print text=零
```
- `1. 条件` —— 第一个分支(条件为真时执行其下的缩进行)
- `2. 条件` —— 第二个分支
- `3. *` —— else 臂(`N. *` = 否则)
输出:
```text
正数
```
## 7.2 else 臂:`N. *`
在 `1.` 之后的任意臂上,**整行恰为 `*`** 表示 else:
```markdown
*age = 15*
1. `age` >= 18
> print text=成年
2. *
> print text=未成年
```
## 7.3 布尔分支
```markdown
*is_admin = False*
1. `is_admin`
> print text=管理员
2. *
> print text=普通用户
```
## 7.4 多条件分支
```markdown
*score = 85*
1. `score` >= 90
> print text=优秀
2. `score` >= 80
> print text=良好
3. `score` >= 60
> print text=及格
4. *
> print text=不及格
```
## 7.5 逻辑组合条件
```markdown
*age = 25*
*has_id = True*
1. `age` >= 18 and `has_id`
> print text=可以进入
2. *
> print text=不能进入
```
## 7.6 多个独立分支语句
**一条分支语句 = 从 `1.` 起、序号递增的一段有序列表。** 同级缩进上**再次出现 `1.`** 会开启**下一条**独立分支语句:
```markdown
# main
*a = True*
*b = False*
1. `a`
> print text=A 为真
2. *
> print text=A 为假
1. `b`
> print text=B 为真
2. *
> print text=B 为假
```
这是**两次独立判断**,不是「四个臂的一个分支」。输出:
```text
A 为真
B 为假
```
> 臂序号在同一分支内递增(`1.` → `2.` → `3.` …);不要在同一分支中途把序号重置为 `1.`。
## 7.7 完整示例:成绩评级
```markdown
# main
*score = 72*
1. `score` >= 90
> print text=评级:A
2. `score` >= 80
> print text=评级:B
3. `score` >= 70
> print text=评级:C
4. `score` >= 60
> print text=评级:D
5. *
> print text=评级:F
```
输出:
```text
评级:C
```
## 7.8 下一步
你已经能根据条件走不同路线了。接下来学习[第 8 章:循环](./08-循环.md)。
+179
View File
@@ -0,0 +1,179 @@
# 第 8 章:循环
## 8.1 遍历循环:`- [项](集合)`
Marqdo 用 `-`(无序列表)表达循环。遍历列表用 `- [项](集合)`:
```markdown
# main
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
| 桃 |
- [果](篮子)
> print text=今天吃`果`
```
输出:
```text
今天吃苹果
今天吃梨
今天吃桃
```
- `[果](篮子)` —— 遍历 `篮子` 列表,每个元素绑定到 `果`
- 循环体内用 `` `果` `` 引用元素(独立 `>` 调用中变量要反引号)
反引号形式等价(可混用):
```markdown
- [`果`](`篮子`)
> print text=`果`
```
## 8.2 遍历字典:遍历键
`Map`(字典)用 `- [键](映射)` 遍历**键**:
```markdown
# main
`分类` =
| 苹果 | 黄瓜 |
|------|------|
| 水果 | 蔬菜 |
- [键](分类)
> print text=`键`
```
输出:
```text
苹果
黄瓜
```
> 遍历字典遍历的是键;要取值,用脚注取元(见[第 9 章](./09-集合.md))。
## 8.3 while 循环:`- 条件`
`-` 后直接写条件就是 while 循环:
```markdown
# main
*n = 3*
- `n` > 0
> print text=`n`
*n = n - 1*
```
输出:
```text
3
2
1
```
> 循环体内用 `*…*` 语句更新变量。
## 8.4 嵌套循环
循环可以嵌套:
```markdown
# main
`外层` =
| 项 |
|----|
| A |
| B |
`内层` =
| 项 |
|----|
| 1 |
| 2 |
- [o](外层)
- [i](内层)
> print text=`o``i`
```
输出:
```text
A1
A2
B1
B2
```
## 8.5 循环 + 分支组合
```markdown
# main
`数字` =
| 值 |
|----|
| 1 |
| 2 |
| 3 |
| 4 |
- [n](数字)
1. `n` >= 3
> print text=`n` 是大数
2. *
> print text=`n` 是小数
```
> 循环体里的 `1.` / `2.` 是分支语句(见[第 7 章](./07-条件分支.md)),与 `-` 循环嵌套使用。
## 8.6 完整示例:累计求和
```markdown
# main
`数字` =
| 值 |
|----|
| 1 |
| 2 |
| 3 |
| 4 |
| 5 |
*sum = 0*
- [n](数字)
*sum = sum + n*
> print text=总和:`sum`
```
输出:
```text
总和:15
```
## 8.7 下一步
你已经掌握循环了。接下来学习[第 9 章:集合(表格)](./09-集合.md),深入理解列表、字典与记录。
+203
View File
@@ -0,0 +1,203 @@
# 第 9 章:集合(表格)
Marqdo 用 **GFM 表格**直接构造数据集合。表格的**几何形状**决定值的类型——这是 Marqdo 最有特色的部分:你看到的 Markdown 表格就是数据结构。
## 9.1 绑定一个集合
集合绑定用「空右侧赋值 + 表格」:
```markdown
`名字` =
| 表头1 | 表头2 |
|-------|-------|
| 值 | 值 |
```
表格绑定变量名**需要反引号**(不在 `*…*` 内)。
## 9.2 单列竖表 → 列表(List)
**恰好 1 列** → 列表:
```markdown
`篮子` =
| 果 |
|----|
| 苹果 |
| 梨 |
| 桃 |
```
等价于 `["苹果", "梨", "桃"]`。表头 `果` 是元素逻辑名(foreach 绑定名),**不进入列表元素**。
```markdown
- [果](篮子)
> print text=`果`
```
## 9.3 多列 + 一行 → 字典(Map)
**≥2 列 + 恰好 1 行数据** → 字典,键 = 表头:
```markdown
`分类` =
| 苹果 | 黄瓜 |
|------|------|
| 水果 | 蔬菜 |
```
等价于 `{"苹果": "水果", "黄瓜": "蔬菜"}`。
## 9.4 多列 + 多行 → 字典套列表
**≥2 列 + ≥2 行数据** → 字典,值为该列的列表(列向聚合):
```markdown
`货架` =
| 苹果 | 黄瓜 |
|------|------|
| 红富士 | 青瓜 |
| 嘎啦 | 黄瓜条 |
```
等价于:
```text
{"苹果": ["红富士", "嘎啦"], "黄瓜": ["青瓜", "黄瓜条"]}
```
## 9.5 行向记录表 → 记录列表
首列表头为 `@` / `行` / `row` 时,整表改为**行向**(SQL/CSV 风格):
```markdown
`订单` =
| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
| 2 | 梨 | 3 |
```
等价于:
```text
[{"品名": "苹果", "数量": 2}, {"品名": "梨", "数量": 3}]
```
标记列(`行`)不进入记录字段。
## 9.6 表格形状速查
| 形状 | 值类型 |
|------|--------|
| 1 列 | `List` |
| ≥2 列 + 1 行 | `Map`(标量值) |
| ≥2 列 + ≥2 行 | `Map`(值均为 `List`) |
| ≥2 列 + 0 行 | `Map`(键存在,值空列表) |
| 首列 `@`/`行`/`row` | `List` of `Map`(行向记录) |
## 9.7 脚注取元:`[^…]`
用 Markdown 脚注外形从集合取元素(**表达式级**,可链式)。
### 从列表按下标取
**下标是 1-based**(与人类读表一致):
```markdown
*第一 = 篮子[^1]*
> print text=`第一` # 苹果
```
### 从字典按键取
```markdown
*种 = 分类[^苹果]*
> print text=`种` # 水果
```
### 嵌套取元
```markdown
*第一种苹果 = 货架[^苹果][^1]* # 先键,再下标 → 红富士
```
### 基名的反引号
`` 名[^键] `` 与 `` `名`[^键] `` 等价(紧跟 `[^` 时可省略反引号):
```markdown
*种 = `分类`[^苹果]*
```
### 插值中的取元
在**调用实参值 / 引号字符串**里,`` `变量` `` 后**紧跟**(无空白)`[^…]` 时也按取元解析,而不必先绑定再输出:
```markdown
> print text=苹果单价:`水果价格`[^苹果] # 输出:苹果单价:5
> print text=第一种:`货架`[^苹果][^1] # 链式取元 → 红富士
> print text="价 `水果价格`[^香蕉] 元" # 引号字符串内也可取元 → 价 3 元
```
> 规则:`` `变量` [^…] ``(**有空白**)时 `[^…]` 仍是普通文本;只有 `` `变量`[^…] ``(无空白)才算取元。
> 规则:
> - **List**:标签须为纯数字(1-based);`[^0]` 或越界 → 报错。
> - **Map**:标签为键文本(含纯数字键,如 `[^00]`);缺键 → 报错。
> - 文末的 `[^1]: …` 定义块仍是注释,与取元无关。
## 9.8 表格单元格是表达式
数据单元格支持表达式(与调用实参值语法相同):裸词、数字、`` `var` ``、算术、引号串。URL / `gpt-4o-mini` 等按路径/连字符折叠为文本。
```markdown
*k = "secret"*
`cfg` =
| api_key | model |
|---------|-------|
| `k` | gpt-4o-mini |
```
## 9.9 完整示例
```markdown
# main
`水果价格` =
| 苹果 | 香蕉 |
|------|------|
| 5 | 3 |
> print text=苹果单价:`水果价格`[^苹果]
`购物单` =
| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
| 2 | 香蕉 | 3 |
- [行](购物单)
> print text=`行`[^品名] × `行`[^数量]
```
输出:
```text
苹果单价:5
苹果 × 2
香蕉 × 3
```
## 9.10 下一步
你已经掌握 Marqdo 的数据组织了。接下来学习[第 10 章:对象与方法](./10-对象与方法.md)。
+195
View File
@@ -0,0 +1,195 @@
# 第 10 章:对象与方法
Marqdo 用 `#` 标题定义**对象 / 类型**,用 `##` 定义其下的**方法**。这是一种轻量、可读的面向对象写法。
## 10.1 定义对象(类型)
`#`(恰好一层)定义一个对象 / 类型,其正文是**构造体**:
```markdown
# 大模型
+ `模型名`
*配置 = > json.parse text={"model":"gpt-4o-mini"}*
**配置**
```
- `# 大模型` —— 类型名
- `+ `模型名`` —— 构造参数
- 构造体执行后 `**…**` 返回一个 map,运行时写入 `_type` 字段,形成实例句柄
## 10.2 构造实例
调用类型名即可构造实例:
```markdown
# main
*模型 = > 大模型 模型名="gpt-4o-mini"*
```
## 10.3 定义方法
对象下的 `##` 标题是方法:
```markdown
# 计数器
+ `初始值`
*状态 = > json.parse text={"n":0}*
*状态 = > json.set map=`状态` key="n" value=`初始值`*
**状态**
## 加一
*n = > json.get value=`self` key="n"*
*n2 = n + 1*
*t = > json.set map=`self` key="n" value=`n2`*
**t**
```
方法体内自动绑定:
- `self`(英文)
- `自`(中文)
二者是同一个接收者,指向当前实例。
## 10.4 调用方法
### 独立 `>` 调用(接收者加反引号)
```markdown
*计数器 = > 计数器 初始值=3*
*新值 = > `计数器`.加一*
```
### `*…*` 段内调用(接收者裸名)
```markdown
*计数器 = > 计数器 初始值=3*
*新值 = > 计数器.加一*
```
> **重要**:在 `*…*` / `**…**` 段内,裸词是变量,所以**方法接收者不加反引号**:`*新值 = > 计数器.加一*`。而在独立 `>` 调用中,裸词是文本,接收者需要反引号:`> `计数器`.加一`。
## 10.5 完整对象示例
对象(`#`)定义在**顶层**,与 `# main` 平级:
```markdown
---
import json:lib/json.mq.md
---
# main
*c = > 计数器 初始值=5*
*ty = > json.get value=`c` key="_type"*
> print text=类型:`ty`
*c2 = > c.加一*
*n = > json.get value=`c2` key="n"*
> print text=加一后:`n`
# 计数器
+ `初始值`
*状态 = > json.parse text={"n":0}*
*状态 = > json.set map=`状态` key="n" value=`初始值`*
**状态**
## 加一
*n = > json.get value=`self` key="n"*
*n2 = n + 1*
*t = > json.set map=`self` key="n" value=`n2`*
**t**
```
输出:
```text
类型:计数器
加一后:6
```
## 10.6 继承:`# Child = > Parent`
```markdown
# Greeter
## hello
+ `who`
*msg = "Hello, `who`!"*
**msg**
# Loud = > Greeter
## hello
+ `who`
*msg = "HELLO, `who`!"*
**msg**
```
规则:
| 规则 | 说明 |
|------|------|
| 语法 | `# Child = > Parent` |
| `_type` | 构造后仍为**最具体子类名** |
| 方法查找 | 先子类 `##`,未命中再沿基类链;同名则子类覆盖 |
| 构造 | **不**隐式调用父构造(无 auto-super) |
| 多继承 | 不支持 |
### 显式调用父构造
子类需要父字段时,在子类正文首行显式调用父构造:
```markdown
# Child = > Parent
+ `name`
*self = > Parent name=`name`*
*self = > json.set map=`self` key="role" value="child"*
**self**
```
## 10.7 完整继承示例
```markdown
# main
*c = > Child name="Ada"*
*ty = > json.get value=`c` key="_type"*
*role = > json.get value=`c` key="role"*
> print text=`ty`
> print text=`role`
# Parent
+ `name`
*out = > json.parse text={"role":"parent"}*
*out = > json.set map=`out` key="name" value=`name`*
**out**
# Child = > Parent
+ `name`
*self = > Parent name=`name`*
*self = > json.set map=`self` key="role" value="child"*
**self**
```
输出:
```text
Child
child
```
## 10.8 下一步
你已经会面向对象编程了。接下来学习[第 11 章:模块与导入](./11-模块与导入.md),组织大型项目。
+175
View File
@@ -0,0 +1,175 @@
# 第 11 章:模块与导入
大型项目需要把代码拆成多个文件。Marqdo 用 **frontmatter 导入**和**点号寻址**组织模块。
## 11.1 Frontmatter 元信息
文件开头的成对 `---` 之间是 frontmatter,存放元信息(标题、描述、导入):
```markdown
---
title: 我的程序
description: 描述文字
---
```
## 11.2 导入文件:`import 绑定:路径.mq.md`
```markdown
---
import text:lib/text.mq.md
import time:lib/time.mq.md
---
```
- `text` —— 绑定名(本地库名)
- `lib/text.mq.md` —— 目标文件路径
导入后得到一个**库(模块)绑定**,成员**不会**倒进全局。
中文等价:`导入 文本:lib/文本.mq.md`。
## 11.3 点号寻址调用:`库.成员`
导入后用裸点号路径调用库成员:
```markdown
---
import time:lib/time.mq.md
import json:lib/json.mq.md
---
# main
*t = > time.now_unix*
*s = > time.format unix=`t` pattern="%Y-%m-%d"*
> print text=`s`
```
- `time.now_unix` —— 调用 `time` 库的 `now_unix` 函数
- `time.format` —— 调用 `time` 库的 `format` 函数
**库名不是变量**:路径段是裸标识符,不加反引号。
## 11.4 三段路径:`库.类型.方法`
```markdown
---
import agent:ext/ai/agent.mq.md
---
# main
*助手 = > agent.agent model="gpt-4o-mini"* # 库 → 类型:构造
```
`agent.agent` —— `agent` 库中的 `agent` 类型(构造)。
## 11.5 短名:`import 绑定:库.成员`
把库路径成员绑为本地短名:
```markdown
---
import time:lib/time.mq.md
import fmt:time.format
---
# main
*t = > time.now_unix*
*s = > fmt unix=`t` pattern="%Y-%m-%d"*
```
`fmt` 现在是 `time.format` 的短名。
## 11.6 方法调用 vs 库路径(Python 统一命名空间)
对裸点号 `a.b`,规则是:
- 若 `a` 是当前作用域的**局部变量** → **方法调用**(`a` 为接收者)
- 否则 → **库路径**
| 写法 | 含义 |
|------|------|
| `time.parse` | 库路径(裸名,第一段非变量) |
| `` > `助手`.step `` | 独立 `>` 调用:实例方法(接收者反引号) |
| `*回复 = > 助手.step …*` | `*…*` 段内:`助手` 是变量 → 实例方法;否则 → 库路径 |
```markdown
---
import agent:ext/ai/agent.mq.md
---
# main
*助手 = > agent.agent model="gpt-4o-mini"*
*out = > 助手.step task="你好"* # 助手是变量 → 方法调用
```
## 11.7 完整示例:多模块程序
假设项目结构:
```text
project/
├── main.mq.md
├── lib/
│ ├── 数学.mq.md
│ └── 问候.mq.md
```
`lib/数学.mq.md`:
```markdown
## 加倍
+ `n`
**n * 2**
```
`lib/问候.mq.md`:
```markdown
## 你好
+ `谁`
> print text=你好,`谁`!
```
`main.mq.md`:
```markdown
---
import 数学:lib/数学.mq.md
import 问候:lib/问候.mq.md
---
# main
*结果 = > 数学.加倍 n=21*
> print text=`结果`
> 问候.你好 谁=世界
```
输出:
```text
42
你好,世界!
```
## 11.8 库路径解析
`lib/…` 按以下顺序解析:
1. 环境变量 `MARQDO_LIB`
2. 当前目录下的 `lib/`
3. `marqdo` 可执行文件旁边的 `lib/`(及几个父目录)
官方扩展(`ext/`)用 `marqdo ext add llm|agent|web|quantum` 安装,导入仍写 `import llm:ext/llm.mq.md` 等。
## 11.9 下一步
你已经能组织大型项目了。接下来学习[第 12 章:标准库](./12-标准库.md),使用官方能力。
+172
View File
@@ -0,0 +1,172 @@
# 第 12 章:标准库
Marqdo 内置函数无需导入即可使用;更丰富的能力通过导入 `lib/` 模块获得。
## 12.1 内置函数(无需导入)
| 英文 | 中文 | 作用 |
|------|------|------|
| `print` | `打印` | 写标准输出(参数 `text` ≡ `内容`) |
| `input` | `输入` | 读一行(参数 `prompt` ≡ `提示`) |
| `len` | `长度` | 文本 / 集合长度(参数 `value` ≡ `值`) |
| `str` | `文本` | 转为显示文本(参数 `value` ≡ `值`) |
| `int` | `整数` | 转为整数(参数 `value` ≡ `值`) |
```markdown
# main
> print text=Hello
*s = "Marqdo"*
*n = > len value=`s`*
> print text=长度:`n`
```
## 12.2 标准库模块
导入一个 `lib/` 文件,使用**该文件**的函数名:
| 英文导入 | 中文导入 | 典型功能 |
|----------|----------|----------|
| `lib/text.mq.md` | `lib/文本.mq.md` | 文本处理(去空白、拆分、拼接) |
| `lib/table.mq.md` | `lib/表.mq.md` | 列表 / 字典元素更新 |
| `lib/fs.mq.md` | `lib/文件.mq.md` | 文件系统 |
| `lib/sys.mq.md` | `lib/系统.mq.md` | 进程 / 当前目录 / 加载环境变量 |
| `lib/plugin.mq.md` | `lib/插件.mq.md` | 加载原生 ABI 插件 |
| `lib/time.mq.md` | `lib/时间.mq.md` | 时间 / 格式化 |
| `lib/net.mq.md` | `lib/网络.mq.md` | HTTP(S) |
| `lib/json.mq.md` | — | JSON 解析 / 序列化 |
| `lib/math.mq.md` | `lib/数学.mq.md` | 数值、三角函数、随机、公式、绘图 |
| `lib/foreign.mq.md` | `lib/外联.mq.md` | 运行异种语言代码块 |
> **语言一致性**:导入英文库文件,就用其英文 API;导入中文库文件,就用其中文 API。不要混用语言。
## 12.3 JSON 模块示例
`json` 模块负责**文本 ↔ 结构化数据**的序列化转换,以及把文本字符串里的 `\n` 等转义还原:
| 函数 | 作用 |
|------|------|
| `json.parse` | 解析 JSON 文本 |
| `json.stringify` | 序列化为 JSON 文本 |
| `json.get` | 取字段(键) |
| `json.keys` | 取所有键 |
| `json.set` | 设字段 |
| `json.append` | 向列表追加 |
```markdown
---
import json:lib/json.mq.md
---
# main
*obj = > json.parse text={"a":1}*
*out = > json.stringify value=`obj`*
> print text=`out` # {"a":1}
*nl = > json.parse text={"n":"\n"}*
> print text=第一行`nl`[^n]第二行 # 换行还原
```
> **字典操作**:本地字典的读取用脚注取元 `变量[^键]`,**不要**用 `json.get`。`json.get` / `json.set` 仅用于跨文本边界的序列化场景(例如与外部 JSON API 交换数据时)。构造字典用 GFM 横表(见[第 9 章](./09-集合.md))。
`json` 常用函数:
| 函数 | 作用 |
|------|------|
| `json.parse` | 解析 JSON 文本 |
| `json.stringify` | 序列化为 JSON 文本 |
| `json.get` | 取字段(键) |
| `json.keys` | 取所有键 |
| `json.set` | 设字段 |
| `json.append` | 向列表追加 |
## 12.4 文本模块示例
```markdown
---
import text:lib/text.mq.md
---
# main
*parts = > text.str_split s="a,b,c" sep=","*
> print text=`parts`
*joined = > text.str_join xs=`parts` sep="-"*
> print text=`joined` # a-b-c
```
## 12.5 数学模块:公式与绘图
```markdown
---
import math:lib/math.mq.md
---
# main
*值 = > math.num value=3.5*
> print text=`值`
```
公式绑定:
```markdown
---
import math:lib/math.mq.md
---
# main
`f` =
$$
x^2 - 2
$$
*_svg = > math.plot formula=`f` var=x min=-3 max=3*
```
空 RHS 赋值 + 后随 `$$…$$` 绑定一个公式值。
## 12.6 官方扩展库(`ext/`)
扩展库不是 stdlib,需安装:
```bash
marqdo ext list
marqdo ext add llm
marqdo ext add agent
marqdo ext add web
marqdo ext add quantum
```
导入仍写 `import …:ext/….mq.md`:
```markdown
---
import llm:ext/llm.mq.md
---
# main
*模型 = > llm.llm model="gpt-4o-mini"*
```
| 扩展 | 功能 |
|------|------|
| `llm` | 大模型对话 |
| `agent` | 文档驱动的智能体框架 |
| `web` | Web 应用 |
| `quantum` | 量子电路模拟 |
## 12.7 查看库的精确 API
打开 `lib/` 或 `ext/` 下对应的 `.mq.md` 文件,即可看到精确的 `##` / `#` 名称和参数。例如 `lib/json.mq.md` 顶层就是 `## parse`、`## stringify` 等。
## 12.8 下一步
你已经会使用标准库了。继续学习:
- [第 13 章:命令行工具](./13-命令行工具.md) —— 运行、调试、扩展管理
- [第 14 章:网络与 Web 扩展](./14-网络与Web扩展.md) —— `lib/net` 与 `ext/web` 实战
+111
View File
@@ -0,0 +1,111 @@
# 第 13 章:命令行工具
Marqdo 提供一组命令行工具,覆盖运行、浏览、调试、发布全流程。
## 13.1 命令总览
```text
marqdo --version # 查看版本
marqdo run 文件.mq.md # 运行程序
marqdo view 路径 # 文档浏览器(默认端口 7429)
marqdo debug 路径 # 调试界面(默认端口 7430)
marqdo catalog 路径 -o 目录 # 生成 OKF 风格清单
marqdo sync 路径 -o 目录 # catalog 的别名
marqdo ext list # 列出扩展
marqdo ext add llm|agent|web|quantum
marqdo ext remove llm|agent|web|quantum
```
## 13.2 运行程序:`run`
```bash
marqdo run hello.mq.md
```
指定后端(树遍历默认 / 字节码):
```bash
marqdo run hello.mq.md --backend bytecode
```
### 错误诊断
诊断信息格式:`path:line:col: message`(行 / 列从 1 开始)。
```text
error: hello.mq.md:5:1: undefined variable `x`
```
根据 `path:line:col` 定位并修复,再重新运行直到退出码为 0。
## 13.3 文档浏览器:`view`
`view` 启动一个本地文档浏览器,把 `.mq.md` 渲染成可浏览的文档站:
```bash
marqdo view public --no-open
```
浏览器打开后可看到:
- Structure(结构)
- 函数大纲 / 搜索
- Execution(执行)
- Variables(变量浮窗)
## 13.4 调试器:`debug`
```bash
marqdo debug public --no-open
```
提供独立调试页面,支持:
- 断点
- 单步执行
- 局部变量查看
## 13.5 生成清单:`catalog` / `sync`
从源码派生 OKF 风格的 YAML / Markdown 知识包:
```bash
marqdo catalog public -o .marqdo
# 或
marqdo sync public -o .marqdo
```
| 参数 | 默认 | 说明 |
|------|------|------|
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
| `-o` / `--out` | `.marqdo` | 输出目录 |
产物:`catalog.yaml`、`index.md`、`modules/*.md` 等。
## 13.6 扩展管理:`ext`
```bash
marqdo ext list
marqdo ext add llm
marqdo ext add agent
marqdo ext remove llm
```
扩展默认安装到 `~/.marqdo/ext`(或 `MARQDO_EXT`)。
## 13.7 标准库与可执行文件解析
- **标准库**:内置于二进制;磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。
- **库路径解析**:`MARQDO_LIB` → 当前目录 `lib/` → 可执行文件旁 `lib/`。
## 13.8 下一步
恭喜!你已经完成了 Marqdo 语法教程。你现在可以:
- 写出带输入输出、函数、分支、循环的程序
- 用表格组织列表、字典、记录
- 用对象和方法做面向对象编程
- 拆分模块、使用标准库和扩展
- 用命令行工具运行、调试、发布
祝你在「代码即文档」的世界里愉快!
+205
View File
@@ -0,0 +1,205 @@
# 第 14 章:网络与 Web 扩展
Marqdo 的网络能力分两层:**标准库 `lib/net`**(HTTP 客户端、cookie / multipart 解析)与**官方扩展 `ext/web`**(网页应用、数据库、表单、登录鉴权、WebSocket)。分层的依据是「代码即文档」的可读性——基础、通用、低依赖的进标准库;领域性强、依赖重、只在 Web 场景才用的进扩展。
## 14.1 概览
| 能力 | 位置 | 典型函数 |
|------|------|----------|
| HTTP(S) 客户端 | `lib/net` | `http_get` / `http_post` / `http_request` |
| Cookie 解析 | `lib/net` | `cookie_parse` |
| multipart/form-data 解析 | `lib/net` | `multipart_parse` |
| 网页应用 / 路由 / 静态 | `ext/web` | `web.page` / `web.app` |
| SQLite 数据库 | `ext/web` | `web.db` |
| 表单 | `ext/web` | `web.form` |
| 登录鉴权(session) | `ext/web` | `web.auth` / `app.auth` |
| WebSocket 客户端 / 端点 | `ext/web` | `web.ws` / `app.route_ws` |
```bash
# 运行使用 ext/web 的程序前,先安装扩展
marqdo ext add web
```
## 14.2 HTTP 客户端(`lib/net`)
导入 `lib/net.mq.md`(中文 `lib/网络.mq.md`),用 `http_get` / `http_post` 发请求:
```markdown
---
import net:lib/net.mq.md
---
# main
*resp = > net.http_get url="https://api.example.com/status"*
> print text=`resp`[^status]
```
`http_post` 默认以 JSON 提交,可用 `content_type=` / `headers=` 覆盖:
```markdown
*body = > net.http_post url="https://api.example.com/echo" body={"msg":"hi"}*
> print text=`body`
```
> **字典操作**:返回值是字典(如 `resp`),直接取元 `resp[^键]`,不要用 `json.get`。
### Cookie 解析
`cookie_parse` 把 `Cookie` 请求头或 `Set-Cookie` 响应头解析成列表:
```markdown
*req = > net.cookie_parse text="session=abc123; theme=dark"*
> print text=`req`[^1][^name] # session
> print text=`req`[^1][^value] # abc123
*resp = > net.cookie_parse text="id=42; Path=/; HttpOnly; SameSite=Lax" is_response=True*
> print text=`resp`[^1][^http_only] # True
```
### multipart 解析
`multipart_parse` 解析 `multipart/form-data` 正文(给定 `boundary`):
```markdown
*parts = > net.multipart_parse body=`body` boundary="----WebKitFormBoundary"*
*field = parts[^1]*
> print text=`field`[^name]
```
## 14.3 网页应用(`ext/web`)
`ext/web` 用类 + 方法装配页面。导入 `web:ext/web/web.mq.md`(中文 `网页:ext/web/网页.mq.md`)。
### 页面、组件、主体
```markdown
---
import web:ext/web/web.mq.md
---
# main
`首页` =
| 组件 | 样式 |
|------|------|
| nav.`导航` | shell.`顶栏` |
*page = > web.page title="我的站点" intro="<h1>你好</h1>"*
*page = > `page`.compose_components components=`首页`*
*html = > `page`.render*
> print text=`html`
```
### 应用 + 路由 + 监听
```markdown
*app = > web.app page=`page` host=127.0.0.1 port=18081*
*app = > `app`.route path="/about" page=`关于`*
> web_listen app=`app`
```
`listen` 提供 `/`、路由页、表单端点 `/_form/{id}`、可选静态目录与 `/admin`。
### 数据库(SQLite)
```markdown
*store = > web.db url="sqlite:site.db"*
> `store`.init name=articles fields=`字段表`
> `store`.insert table=articles rows=`数据`
*rows = > `store`.select table=articles limit=10*
- [行](rows)
> print text=`行`[^title]
```
## 14.4 登录鉴权(session / cookie)
给 `/admin*` 加登录门禁:`app.auth` 挂用户表,未登录重定向到 `/admin/login`。
```markdown
`管理员` =
| 行 | 用户名 | 密码 |
|----|--------|------|
| 1 | admin | secret |
| 2 | 站长 | pw123 |
*app = > web.app page=`page` admin=True*
*app = > `app`.auth users=`管理员` session_ttl=3600*
> web_listen app=`app`
```
`session_ttl` 是会话有效期(秒),过期后重新登录。
**独立鉴权工具** `web.auth`:登录、校验、登出(不依赖页面),返回 `{ok, session_id, username}`:
```markdown
*auth = > web.auth users=`管理员` session_ttl=3600*
*login = > `auth`.login username="admin" password="secret"*
1. `login`[^ok]
> print text=登录成功:`login`[^username]
2. *
> print text=登录失败
*sid = login[^session_id]*
*check = > `auth`.check session_id=`sid`*
> print text=`check`[^username]
> `auth`.logout session_id=`sid`
```
## 14.5 WebSocket
`app.route_ws` 注册端点,`web.ws.connect` 单次请求–响应:
```markdown
*app = > `app`.route_ws path="/live" echo=True*
> web_listen app=`app`
```
客户端(另开终端):
```markdown
*ws = > web.ws timeout_sec=30*
*echo = > `ws`.connect url="ws://127.0.0.1:18081/live" message="hi"*
1. `echo`[^ok]
> print text=`echo`[^messages]
2. *
> print text=连接失败:`echo`[^error]
```
## 14.6 字典操作:用表格与取元,不用 `json.get`/`json.set`
Marqdo 用 **GFM 表格**构造字典、用 **脚注取元 `变量[^键]`** 读取字典——这是语言原生能力,是「代码即文档」的体现。**不要**用 `json.get` / `json.set` 读写本地字典(那只用于文本 ↔ 结构化的序列化,如 `json.parse` / `json.stringify`)。
构造字典(横表,≥2 列 + 1 行):
```markdown
`配置` =
| 主机 | 端口 |
|------|------|
| 127.0.0.1 | 18081 |
```
读取字典(取元):
```markdown
> print text=`配置`[^主机] # 127.0.0.1
> print text=`配置`[^端口] # 18081
```
读取函数返回的字典字段,同样直接取元:
```markdown
*login = > `auth`.login username="admin" password="secret"*
> print text=`login`[^ok] # 而不是 json.get value=`login` key="ok"
```
## 14.7 下一步
你已经掌握 Marqdo 的网络与 Web 能力。继续探索:
- [第 13 章:命令行工具](./13-命令行工具.md) —— `marqdo ext` 管理扩展
- 设计文档:[`doc/design/ext-web-net.md`](../design/ext-web-net.md) —— 本波次网络扩展的完整设计与边界判定
+94
View File
@@ -0,0 +1,94 @@
# Marqdo 语法教程
> **代码即文档,文档即代码。** Marqdo 把 Markdown 的标记当作编程语法:同一个 `.mq.md` 文件既是给人读的文稿,也是给机器跑的程序。
本教程面向所有读者——从没写过代码的文档作者,到熟悉 Python 的工程师。每章都配有可直接运行的完整示例。
## 目录
### 第一部分 · 入门
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 1 章:Marqdo 是什么](./01-入门.md) | 理念、安装、第一个程序、运行 | 写出并运行你的第一个 `.mq.md` 程序 |
| [第 2 章:基本语法](./02-基本语法.md) | 文件结构、注释、标识符、字面量 | 看懂 `.mq.md` 里哪些是代码、哪些是注释 |
### 第二部分 · 变量与数据
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 3 章:变量与赋值](./03-变量与赋值.md) | 绑定、变量引用、字符串 | 存取值,拼接文本 |
| [第 4 章:输出与输入](./04-输出与输入.md) | `print` / `打印`、`input` / `输入` | 与用户交互 |
| [第 5 章:运算符与比较](./05-运算符与比较.md) | 算术、比较、逻辑 | 计算与判断 |
### 第三部分 · 流程控制
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 6 章:函数](./06-函数.md) | 定义、参数、返回值、函数结束 | 封装可复用逻辑 |
| [第 7 章:条件分支](./07-条件分支.md) | `1.` `2.` 分支、else | 让程序根据条件走不同路线 |
| [第 8 章:循环](./08-循环.md) | `-` 遍历、`-` while | 重复执行 |
### 第四部分 · 数据集合
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 9 章:集合(表格)](./09-集合.md) | 列表、字典、记录、脚注取元 | 用 Markdown 表格组织数据 |
### 第五部分 · 面向对象与模块
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 10 章:对象与方法](./10-对象与方法.md) | `#` 类型、构造、方法、继承 | 面向对象编程 |
| [第 11 章:模块与导入](./11-模块与导入.md) | frontmatter、import、库路径、短名 | 组织大型项目 |
### 第六部分 · 进阶
| 章节 | 内容 | 你能学会什么 |
|------|------|-------------|
| [第 12 章:标准库](./12-标准库.md) | 内置函数、`lib/` 模块 | 直接使用官方能力 |
| [第 13 章:命令行工具](./13-命令行工具.md) | `run` / `view` / `debug` / `catalog` | 运行、浏览、调试、发布 |
| [第 14 章:网络与 Web 扩展](./14-网络与Web扩展.md) | `lib/net`、`ext/web`、鉴权、WebSocket | 构建 HTTP 客户端与网页应用 |
---
## 快速示例
一个完整的 Marqdo 程序长这样:
```markdown
# main
> 问候 谁=World
## 问候
+ `谁`
> print text=Hello, `谁`!
---
## 加一
+ `n`
**n + 1**
```
- `# main` —— 入口
- `> 问候 谁=World` —— 调用函数(具名参数)
- `## 问候` + `+ `谁`` —— 定义函数及其参数
- `> print text=…` —— 输出(副作用,是普通函数)
- `**n + 1**` —— 返回值
- 单独一行 `---` —— 结束函数体
---
## 运行方式
```bash
marqdo run 文件.mq.md
```
更多运行、浏览、调试、发布方式见 [第 13 章](./13-命令行工具.md)。
> **提示**:语法宪法与精确定义见 [`doc/design/markdown-mapping.md`](../design/markdown-mapping.md);本教程是它的通俗讲解版。
+50
View File
@@ -0,0 +1,50 @@
# examples/marqdo-blog
一个用 Marqdo 的 `ext/web` 网络扩展库搭建的博客系统示例:美观大气的现代化主题、
SQLite 驱动的文章/标签、动态路由、WebSocket 实时终端、以及受会话门禁保护的后台 CRUD。
## 运行
```bash
cargo build -p marqdo_plugin_web
cargo run -- examples/marqdo-blog/index.mq.md
```
打开 http://127.0.0.1:18085/:
- `/` — 首页:文章卡片网格 + 实时 WebSocket 终端
- `/post/{slug}` — 动态路由渲染单篇文章(标题/日期/标签/正文)
- `/tags` — 标签归档;`/tag/{slug}` 查看某标签下的文章
- `/about` — 关于页
- `/admin` — 会话门禁后台,登录 `admin` / `marqdo`,可增删改文章与标签
- `/live` — WebSocket 回显端点
- `/static/*` — 静态资源(`public/` 下的 `live.js`)
## 设计亮点(文档即代码)
- **样式即数据表格,装配即函数**(`styles/theme.mq.md`):
主题不再是一大段手写 CSS 字符串,而是由一张张 GFM 样式表组成 ——
`|选择器|属性|值|` 规则行(同一选择器多行自动合并成一条规则),
响应式用 `|媒体|选择器|属性|值|` 分组进 `@media` 块。
每个 `## 段`(基础/顶栏/侧栏/主体/卡片/页脚/表单/响应式)导出一张样式表,
`## 全局` 用 `网页.样式装配` 函数把每张表装配成 CSS 文本,再 `text.str_join` 拼成完整样式表,
最后经 `页面.样式` 注入页面。样式保持可读的数据表格,不写胶水代码。
- **页面 = 组件装配 + 主体绑定**(`index.mq.md`):
导航/侧栏/页脚用 `|组件|样式|` 表装配,文章列表用 `|属性|值|` 绑定 SQLite 字段。
- **动态路由**:`/post/{slug}` 的 `slug` 注入查询条件,`页面.详情` 把首行渲染成文章。
- **数据模型**(`db/`):`schema.mq.md` 定义 `posts`/`tags`/`post_tags` 三张表,
`seed.mq.md` 提供种子数据,`index.mq.md` 幂等建表 + 灌数据。
## 冒烟测试
服务器启动后(端口 18085),运行:
```bash
bash examples/marqdo-blog/smoke.sh
```
覆盖:首页/卡片/主题 CSS/媒体查询、静态资源、动态路由详情、标签归档、鉴权门禁、
登录会话、后台表单、WebSocket 回显。全部通过时输出 `通过 N / N`。
可从仓库根目录或本目录运行:相对 `static_dir`(`public`)与相对数据库路径
(`data/marqdo-blog.db`)都按**入口脚本所在目录**解析,不依赖终端工作目录。
@@ -0,0 +1,13 @@
## 页脚
站点页脚。放版权与概览链接。
`页脚` =
| 属性 | 值 | 样式 |
|------|-----|------|
| © 2026 Marqdo 博客 | / | |
| 关于 | /about | |
| 后台 | /admin | |
**`页脚`**
+15
View File
@@ -0,0 +1,15 @@
## 导航
站点顶部导航。首项是站点名(渐变 Logo 由主题 CSS 处理),`后台` 指向需要登录的 `/admin`。
`导航` =
| 属性 | 值 | 样式 |
|------|-----|------|
| Marqdo 博客 | / | |
| 首页 | / | |
| 标签 | /tags | |
| 关于 | /about | |
| 后台 | /admin | |
**`导航`**
@@ -0,0 +1,15 @@
## 侧栏
右侧归档面板:文章入口、标签、实时小部件。
`侧栏` =
| 属性 | 值 | 样式 |
|------|-----|------|
| 全部文章 | / | |
| 标签归档 | /tags | |
| 关于本站 | /about | |
| 发布文章 | /admin/new | |
| 实时终端 | /#live | |
**`侧栏`**
+28
View File
@@ -0,0 +1,28 @@
---
title: db/index
description: 打开 sqlite、建三张表、幂等种子。
导入 网页:ext/web/网页.mq.md
import schema:schema.mq.md
import seed:seed.mq.md
---
## 打开
*store = > 网页.数据库 地址="sqlite:data/marqdo-blog.db"*
*字段 = > schema.posts*
*标签字段 = > schema.tags*
*关联字段 = > schema.post_tags*
> `store`.初始化 名=posts 字段=`字段`
> `store`.初始化 名=tags 字段=`标签字段`
> `store`.初始化 名=post_tags 字段=`关联字段`
*行 = > store.查询 表="posts" 上限=1*
1. `行`
**store**
2. *
*文章 = > seed.posts*
*标签 = > seed.tags*
*关联 = > seed.post_tags*
> `store`.插入 表=posts 行=`文章`
> `store`.插入 表=tags 行=`标签`
> `store`.插入 表=post_tags 行=`关联`
**store**
+46
View File
@@ -0,0 +1,46 @@
## posts
文章主表结构。`slug` 用于详情页 `/post/{slug}` 的动态路由;`content` 存 Markdown 正文;`tag` 是主标签(tags 表 slug)。
`schema` =
| 字段 | 类型 | 可空 |
|------|------|------|
| id | integer | false |
| title | text | false |
| slug | text | false |
| summary | text | true |
| content | text | true |
| tag | text | true |
| created_at | text | true |
| updated_at | text | true |
**`schema`**
## tags
标签表结构。
`tags` =
| 字段 | 类型 | 可空 |
|------|------|------|
| id | integer | false |
| name | text | false |
| slug | text | false |
**`tags`**
## post_tags
文章-标签关联表结构。
`post_tags` =
| 字段 | 类型 | 可空 |
|------|------|------|
| id | integer | false |
| post_id | integer | false |
| tag_id | integer | false |
**`post_tags`**
+53
View File
@@ -0,0 +1,53 @@
## posts
种子文章。首页与详情页的初始数据。created_at 用于按时间倒序展示;tag 是主标签 slug。
`posts` =
| 行 | title | slug | summary | content | tag | created_at | updated_at |
|----|-------|------|---------|---------|-----|------------|------------|
| 1 | 你好,Marqdo 博客 | hello-marqdo | 用 Marqdo 的 web 扩展库搭建的第一个博客。表格即组件、文档即代码。 | 这是一篇介绍博客系统的文章。它由 Marqdo 脚本在启动时写入 SQLite,通过 ext/web 的组件装配渲染成页面。 | marqdo | 2026-08-01 | 2026-08-02 |
| 2 | 动态路由与文章详情 | dynamic-routing | 如何用 /post/{slug} 动态路由渲染单篇文章。 | 本文说明动态路由机制:作者面注册带 {slug} 占位符的路由,请求时把路径参数注入页面查询条件。 | web | 2026-08-05 | 2026-08-05 |
| 3 | 用 GFM 表格表达数据 | gfm-tables | Marqdo 的字典操作不依赖 json 库,GFM 表格即可完成。 | 表格即数据、表格即组件。这篇文章展示如何在 .mq.md 里用横向表写种子数据,用脚注索引读取字段。 | tutorial | 2026-08-10 | 2026-08-11 |
| 4 | WebSocket 实时小部件 | websocket-live | 给博客加一个实时回显的 WebSocket 端点。 | 通过 app.路由实时 注册 /live 端点,配合 public/live.js 在首页显示实时连接状态。 | realtime | 2026-08-15 | 2026-08-15 |
| 5 | 会话与登录鉴权 | session-auth | 后台用 session 门禁保护,只有登录用户能发布文章。 | 用 app.鉴权 配置管理员用户表,/admin 下的 CRUD 页面都需要有效会话。 | web | 2026-08-18 | 2026-08-20 |
| 6 | 数据库与 CRUD | database-crud | 博客的文章、标签、关联全部由 SQLite 支撑。 | db.初始化 建表、db.插入 写种子、后台表单增删改。文章与标签通过 post_tags 关联。 | database | 2026-08-20 | 2026-08-21 |
**`posts`**
## tags
种子标签。
`tags` =
| 行 | name | slug |
|----|------|------|
| 1 | Marqdo | marqdo |
| 2 | Web | web |
| 3 | 教程 | tutorial |
| 4 | 数据库 | database |
| 5 | 实时 | realtime |
**`tags`**
## post_tags
种子文章-标签关联。
`post_tags` =
| 行 | post_id | tag_id |
|----|---------|--------|
| 1 | 1 | 1 |
| 2 | 1 | 2 |
| 3 | 2 | 2 |
| 4 | 3 | 1 |
| 5 | 3 | 3 |
| 6 | 4 | 5 |
| 7 | 4 | 2 |
| 8 | 5 | 2 |
| 9 | 6 | 4 |
| 10 | 6 | 1 |
**`post_tags`**
+109
View File
@@ -0,0 +1,109 @@
---
title: Marqdo 博客
description: 用 web 扩展库搭建的博客系统示例:首页列表、动态文章详情、标签归档、登录门禁后台。
导入 网页:ext/web/网页.mq.md
import theme:styles/theme.mq.md
import nav:components/nav.mq.md
import side:components/side.mq.md
import foot:components/foot.mq.md
import db:db/index.mq.md
---
# main
`首页` =
| 组件 | 样式 |
|------|------|
| nav.`导航` | |
| side.`侧栏` | |
| foot.`页脚` | |
`列表` =
| 属性 | 值 | 样式 |
|------|-----|------|
| title | posts.title | |
| body | posts.summary | |
| meta | posts.created_at | |
| tag | posts.tag | |
| href | posts.slug | |
`详情绑定` =
| 属性 | 值 | 样式 |
|------|-----|------|
| title | posts.title | |
| meta | posts.created_at | |
| tag | posts.tag | |
| body | posts.content | |
`标签列表` =
| 属性 | 值 | 样式 |
|------|-----|------|
| title | tags.name | |
| meta | 点击查看该标签下的文章 | |
| href | tags.slug | |
`文章条件` =
| 字段 | 操作 | 值 |
|------|------|-----|
| slug | = | {slug} |
`标签条件` =
| 字段 | 操作 | 值 |
|------|------|-----|
| tag | = | {slug} |
`管理员` =
| 行 | 用户名 | 密码 |
|----|--------|------|
| 1 | admin | marqdo |
*store = > db.打开*
*首页CSS = > theme.全局*
*page = > 网页.页面 标题="Marqdo 博客" 引言="<h1>Marqdo 博客</h1><p>用 web 扩展库搭建的博客:表格装配页面、SQLite 数据、动态路由、实时终端。</p><h2 id=\"live\">实时终端</h2><p id=\"live-status\" class=\"live-pill\">connecting…</p><input id=\"live-msg\" placeholder=\"输入一条消息…\"><button id=\"live-send\" disabled>发送</button><div id=\"live-out\"></div><script src=\"/static/live.js\"></script>"*
*page = > page.组件装配 组件=`首页`*
*page = > page.主体装配 主体=`列表`*
*page = > page.排序 排序="-created_at"*
*page = > page.样式 样式=`首页CSS`*
*about = > 网页.页面 标题="关于" 引言="<h1>关于本站</h1><p>一个用 Marqdo 的 web 扩展库(ext/web)写成的博客系统。</p><p>它演示了:GFM 表格装配导航与侧栏、SQLite 驱动的主体绑定、动态路由 /post/{slug}、标签归档、以及受 session 保护的后台 CRUD。</p>"*
*about = > about.组件装配 组件=`首页`*
*about = > about.样式 样式=`首页CSS`*
*post = > 网页.页面 标题="文章"*
*post = > post.组件装配 组件=`首页`*
*post = > post.主体装配 主体=`详情绑定`*
*post = > post.查询条件 条件=`文章条件`*
*post = > post.详情 详情=True*
*post = > post.样式 样式=`首页CSS`*
*tags = > 网页.页面 标题="标签归档" 引言="<h1>标签归档</h1><p>点击标签查看该主题下的文章。</p>"*
*tags = > tags.组件装配 组件=`首页`*
*tags = > tags.主体装配 主体=`标签列表`*
*tags = > tags.链接前缀 前缀="/tag/"*
*tags = > tags.样式 样式=`首页CSS`*
*tagged = > 网页.页面 标题="标签"*
*tagged = > tagged.组件装配 组件=`首页`*
*tagged = > tagged.主体装配 主体=`列表`*
*tagged = > tagged.查询条件 条件=`标签条件`*
*tagged = > tagged.排序 排序="-created_at"*
*tagged = > tagged.样式 样式=`首页CSS`*
*app = > 网页.应用 页面=page 数据库=store 后台=True 主机="127.0.0.1" 端口=18085*
*app = > app.路由 路径="/about" 页面=about*
*app = > app.路由 路径="/post/{slug}" 页面=post*
*app = > app.路由 路径="/tags" 页面=tags*
*app = > app.路由 路径="/tag/{slug}" 页面=tagged*
*app = > app.静态 目录="public" 挂载="/static"*
*app = > app.路由实时 路径="/live" 回显=True*
*app = > app.鉴权 用户表=`管理员` 会话时长=3600*
> `app`.监听
+40
View File
@@ -0,0 +1,40 @@
// 实时 WebSocket 小部件(连接 /live 端点)。
// 连接 ws://host/live,发送输入,展示服务器回显。
(function () {
var out = document.getElementById("live-out");
var input = document.getElementById("live-msg");
var btn = document.getElementById("live-send");
var status = document.getElementById("live-status");
if (!out || !input || !btn || !status) return;
var proto = location.protocol === "https:" ? "wss" : "ws";
var ws = new WebSocket(proto + "://" + location.host + "/live");
status.textContent = "connecting…";
ws.onopen = function () {
status.textContent = "connected";
btn.disabled = false;
};
ws.onmessage = function (ev) {
var p = document.createElement("p");
p.textContent = "echo: " + ev.data;
out.appendChild(p);
out.scrollTop = out.scrollHeight;
};
ws.onclose = function () {
status.textContent = "closed";
btn.disabled = true;
};
ws.onerror = function () {
status.textContent = "error";
btn.disabled = true;
};
btn.onclick = function () {
var m = input.value.trim();
if (m) ws.send(m);
};
input.addEventListener("keydown", function (e) {
if (e.key === "Enter") btn.onclick();
});
})();
+68
View File
@@ -0,0 +1,68 @@
#!/usr/bin/env bash
# 冒烟测试:marqdo-blog 全功能验证。
# 用法:bash examples/marqdo-blog/smoke.sh
set -uo pipefail
BASE="http://127.0.0.1:18085"
PASS=0; FAIL=0
ok() { echo " ok: $1"; PASS=$((PASS+1)); }
bad() { echo " FAIL: $1"; FAIL=$((FAIL+1)); }
echo "== 首页 =="
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/")
[ "$code" = "200" ] && ok "GET / -> $code" || bad "GET / -> $code"
curl -s "$BASE/" | grep -q '<title>Marqdo 博客</title>' && ok "title" || bad "title"
curl -s "$BASE/" | grep -q 'class="card"' && ok "卡片渲染" || bad "卡片缺失"
curl -s "$BASE/" | grep -q 'aside.side' && ok "主题 CSS 注入" || bad "主题 CSS 缺失"
curl -s "$BASE/" | grep -q '@media (max-width: 860px)' && ok "响应式媒体查询" || bad "媒体查询缺失"
echo "== 静态 =="
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/static/live.js")
[ "$code" = "200" ] && ok "GET /static/live.js -> $code" || bad "static -> $code"
echo "== 动态路由 =="
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/post/hello-marqdo")
[ "$code" = "200" ] && ok "GET /post/hello-marqdo -> $code" || bad "post detail -> $code"
curl -s "$BASE/post/hello-marqdo" | grep -q 'article-title' && ok "文章详情渲染" || bad "文章详情缺失"
echo "== 标签 =="
curl -s "$BASE/tags" | grep -q 'href="/tag/marqdo"' && ok "标签归档链接" || bad "标签链接缺失"
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/tag/web")
[ "$code" = "200" ] && ok "GET /tag/web -> $code" || bad "tag page -> $code"
echo "== 鉴权门禁 =="
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/admin")
[ "$code" = "303" ] && ok "未登录 /admin -> $code (重定向登录)" || bad "未登录 /admin -> $code"
echo "== 登录 =="
rm -f /tmp/mq_smoke_cookies.txt /tmp/mq_smoke_headers.txt
curl -s -D /tmp/mq_smoke_headers.txt -o /dev/null -d "username=admin&password=marqdo" "$BASE/admin/login"
sid=$(grep -i "set-cookie" /tmp/mq_smoke_headers.txt | sed 's/.*marqdo_sid=\([^;]*\).*/\1/')
[ -n "$sid" ] && ok "登录获取会话 cookie" || bad "登录未返回 cookie"
code=$(curl -s -b "marqdo_sid=$sid" -o /dev/null -w "%{http_code}" "$BASE/admin")
[ "$code" = "200" ] && ok "带会话访问 /admin -> $code" || bad "带会话 /admin -> $code"
echo "== 发布文章 (CRUD) =="
code=$(curl -s -b "marqdo_sid=$sid" -o /dev/null -w "%{http_code}" "$BASE/admin/posts/new")
[ "$code" = "200" ] && ok "GET /admin/posts/new -> $code" || bad "new form -> $code"
echo "== WebSocket =="
wsok=$(python3 -c "
import socket, base64, os
s = socket.create_connection(('127.0.0.1', 18085), timeout=3)
key = base64.b64encode(os.urandom(16)).decode()
s.sendall((f'GET /live HTTP/1.1\r\nHost: x\r\nUpgrade: websocket\r\nConnection: Upgrade\r\nSec-WebSocket-Key: {key}\r\nSec-WebSocket-Version: 13\r\n\r\n').encode())
r = s.recv(1024).decode(errors='replace')
if '101' not in r.split('\r\n')[0]:
print('NO'); s.close(); raise SystemExit
mask = os.urandom(4); payload = b'ping'
m = bytes(b ^ mask[i%4] for i, b in enumerate(payload))
s.sendall(bytes([0x81, 0x80|len(payload)]) + mask + m)
d = s.recv(1024)
print('OK' if b'ping' in d else 'NO')
s.close()
" 2>/dev/null)
[ "$wsok" = "OK" ] && ok "WebSocket /live 回显" || bad "WebSocket 回显 $wsok"
echo
echo "通过 $PASS / $((PASS+FAIL))"
[ "$FAIL" = "0" ] || exit 1
+405
View File
@@ -0,0 +1,405 @@
---
title: styles/theme
description: 博客主题:样式即数据表格,装配即函数。
import 网页:ext/web/网页.mq.md
import text:lib/text.mq.md
---
博客主题的样式即数据表格:每个 `## 段` 导出一张 GFM 样式表(`|选择器|属性|值|`,
或用 `|媒体|选择器|属性|值|` 表达响应式),`## 全局` 用 `样式装配` 函数把它们
装配成一份完整 CSS。这符合 文档即代码 —— 样式是可读的表格,装配是显式调用。
## 基础
配色与字体变量、页面骨架。衬线标题 + 无衬线正文,暖白纸感背景。
`基础` =
| 选择器 | 属性 | 值 |
|--------|------|-----|
| :root | --ink | #1c1917 |
| :root | --ink-soft | #44403c |
| :root | --muted | #78716c |
| :root | --faint | #a8a29e |
| :root | --paper | #f7f5f2 |
| :root | --card | #ffffff |
| :root | --line | #e7e5e4 |
| :root | --accent | #4f46e5 |
| :root | --accent-2 | #7c3aed |
| :root | --accent-ink | #ffffff |
| :root | --radius | 16px |
| :root | --shadow | 0 1px 2px rgba(28,25,23,.05), 0 8px 24px rgba(28,25,23,.06) |
| :root | --shadow-lg | 0 4px 12px rgba(28,25,23,.08), 0 20px 48px rgba(28,25,23,.12) |
| :root | --serif | "Noto Serif SC", Georgia, "Songti SC", serif |
| :root | --sans | "Noto Sans SC", "IBM Plex Sans", system-ui, -apple-system, sans-serif |
| html | scroll-behavior | smooth |
| * | box-sizing | border-box |
| ::selection | background | rgba(79,70,229,.18) |
| body | margin | 0 |
| body | font-family | var(--sans) |
| body | background | var(--paper) |
| body | color | var(--ink) |
| body | display | grid |
| body | min-height | 100vh |
| body | line-height | 1.7 |
| body | grid-template-rows | auto 1fr auto |
| body.has-sidebar | grid-template-columns | 15rem 1fr |
| body.has-sidebar | grid-template-areas | "top top" "side main" "foot foot" |
| body.no-sidebar | grid-template-areas | "top" "main" "foot" |
**`基础`**
## 顶栏
吸顶导航:磨砂玻璃 + 细分隔线,Logo 处用渐变强调。
`顶栏` =
| 选择器 | 属性 | 值 |
|--------|------|-----|
| header.topnav | grid-area | top |
| header.topnav | position | sticky |
| header.topnav | top | 0 |
| header.topnav | z-index | 20 |
| header.topnav | background | rgba(255,255,255,.82) |
| header.topnav | backdrop-filter | blur(10px) |
| header.topnav | -webkit-backdrop-filter | blur(10px) |
| header.topnav | border-bottom | 1px solid var(--line) |
| header.topnav | padding | .9rem 2rem |
| header.topnav | display | flex |
| header.topnav | align-items | center |
| header.topnav | justify-content | space-between |
| ul.nav | list-style | none |
| ul.nav | margin | 0 |
| ul.nav | padding | 0 |
| ul.nav | display | flex |
| ul.nav | align-items | center |
| ul.nav | gap | .35rem |
| ul.nav li | margin | 0 |
| ul.nav a | display | inline-block |
| ul.nav a | padding | .45rem .9rem |
| ul.nav a | border-radius | 999px |
| ul.nav a | color | var(--ink-soft) |
| ul.nav a | font-weight | 500 |
| ul.nav a | text-decoration | none |
| ul.nav a | transition | background .18s ease, color .18s ease |
| ul.nav a:hover | background | rgba(79,70,229,.1) |
| ul.nav a:hover | color | var(--accent) |
| ul.nav li:first-child a | font-family | var(--serif) |
| ul.nav li:first-child a | font-size | 1.25rem |
| ul.nav li:first-child a | font-weight | 700 |
| ul.nav li:first-child a | background | linear-gradient(120deg, var(--accent), var(--accent-2)) |
| ul.nav li:first-child a | -webkit-background-clip | text |
| ul.nav li:first-child a | background-clip | text |
| ul.nav li:first-child a | -webkit-text-fill-color | transparent |
| ul.nav li:first-child a | color | transparent |
| ul.nav li:first-child a | padding-left | .2rem |
| ul.nav li:first-child a | padding-right | .2rem |
**`顶栏`**
## 侧栏
归档面板:浅底圆角卡片,链接胶囊化。
`侧栏` =
| 选择器 | 属性 | 值 |
|--------|------|-----|
| aside.side | grid-area | side |
| aside.side | padding | 2rem 1.25rem |
| aside.side | border-right | 1px solid var(--line) |
| aside.side | background | linear-gradient(180deg, #fbfaf8, #f3f1ec) |
| ul.side-nav | list-style | none |
| ul.side-nav | margin | 0 |
| ul.side-nav | padding | 0 |
| ul.side-nav | display | flex |
| ul.side-nav | flex-direction | column |
| ul.side-nav | gap | .25rem |
| ul.side-nav li | margin | 0 |
| ul.side-nav a | display | block |
| ul.side-nav a | padding | .55rem .85rem |
| ul.side-nav a | border-radius | 10px |
| ul.side-nav a | color | var(--ink-soft) |
| ul.side-nav a | text-decoration | none |
| ul.side-nav a | font-weight | 500 |
| ul.side-nav a | transition | background .15s ease, transform .15s ease, color .15s ease |
| ul.side-nav a:hover | background | #fff |
| ul.side-nav a:hover | color | var(--accent) |
| ul.side-nav a:hover | transform | translateX(4px) |
| ul.side-nav a:hover | box-shadow | 0 1px 3px rgba(28,25,23,.08) |
**`侧栏`**
## 主体
内容区留白与节奏。
`主体` =
| 选择器 | 属性 | 值 |
|--------|------|-----|
| main.main | grid-area | main |
| main.main | padding | 2.5rem 2.5rem 3.5rem |
| main.main | max-width | 76rem |
| main.main | width | 100% |
| .main-intro | margin-bottom | .5rem |
| .main-intro h1 | font-family | var(--serif) |
| .main-intro h1 | margin | 0 0 .5rem |
| .main-intro h1 | font-size | clamp(2rem, 5vw, 2.9rem) |
| .main-intro h1 | line-height | 1.2 |
| .main-intro h1 | font-weight | 700 |
| .main-intro h1 | letter-spacing | -.01em |
| .main-intro p | color | var(--muted) |
| .main-intro p | margin | 0 |
| .main-intro p | font-size | 1.05rem |
**`主体`**
## 卡片
文章卡片:白底大圆角、柔和阴影、hover 抬升,整卡可点。
`卡片` =
| 选择器 | 属性 | 值 |
|--------|------|-----|
| .content.cards | display | grid |
| .content.cards | gap | 1.5rem |
| .content.cards | margin-top | 2rem |
| .content.cards | grid-template-columns | repeat(auto-fill, minmax(17rem, 1fr)) |
| .content.cards article.card | background | var(--card) |
| .content.cards article.card | border | 1px solid var(--line) |
| .content.cards article.card | border-radius | var(--radius) |
| .content.cards article.card | padding | 1.6rem 1.7rem |
| .content.cards article.card | box-shadow | var(--shadow) |
| .content.cards article.card | transition | transform .22s ease, box-shadow .22s ease, border-color .22s ease |
| .content.cards article.card | display | flex |
| .content.cards article.card | flex-direction | column |
| .content.cards article.card | gap | .55rem |
| .content.cards article.card:hover | transform | translateY(-6px) |
| .content.cards article.card:hover | box-shadow | var(--shadow-lg) |
| .content.cards article.card:hover | border-color | rgba(79,70,229,.35) |
| .content.cards a.card-link | text-decoration | none |
| .content.cards a.card-link | color | inherit |
| .content.cards a.card-link | display | flex |
| .content.cards a.card-link | flex-direction | column |
| .content.cards a.card-link | gap | .55rem |
| .content.cards a.card-link | height | 100% |
| .content.cards a.card-link:hover | color | inherit |
| .content.cards h2 | font-family | var(--serif) |
| .content.cards h2 | margin | 0 |
| .content.cards h2 | font-size | 1.35rem |
| .content.cards h2 | line-height | 1.35 |
| .content.cards h2 | font-weight | 700 |
| .content.cards h2 | transition | color .18s ease |
| .content.cards a.card-link:hover h2 | color | var(--accent) |
| .card-meta | font-size | .82rem |
| .card-meta | color | var(--faint) |
| .card-meta | letter-spacing | .04em |
| .card-meta | text-transform | uppercase |
| .card-tag | align-self | flex-start |
| .card-tag | font-size | .78rem |
| .card-tag | color | var(--accent) |
| .card-tag | background | rgba(79,70,229,.08) |
| .card-tag | padding | .15rem .65rem |
| .card-tag | border-radius | 999px |
| .card-tag | font-weight | 600 |
| .content.cards p | color | var(--muted) |
| .content.cards p | margin | 0 |
| .content.cards p | font-size | .95rem |
| .content.cards p | flex | 1 |
**`卡片`**
## 页脚
`页脚` =
| 选择器 | 属性 | 值 |
|--------|------|-----|
| footer.foot | grid-area | foot |
| footer.foot | padding | 1.4rem 2rem |
| footer.foot | border-top | 1px solid var(--line) |
| footer.foot | color | var(--muted) |
| footer.foot | background | #fff |
| footer.foot | font-size | .9rem |
| footer.foot | display | flex |
| footer.foot | justify-content | space-between |
| footer.foot | align-items | center |
| footer.foot | flex-wrap | wrap |
| footer.foot | gap | .5rem |
| ul.foot-nav | list-style | none |
| ul.foot-nav | margin | 0 |
| ul.foot-nav | padding | 0 |
| ul.foot-nav | display | flex |
| ul.foot-nav | gap | 1rem |
| ul.foot-nav | flex-wrap | wrap |
| ul.foot-nav li | margin | 0 |
| ul.foot-nav a | color | var(--muted) |
| ul.foot-nav a | text-decoration | none |
| ul.foot-nav a:hover | color | var(--accent) |
**`页脚`**
## 表单
后台表单统一风格。
`表单` =
| 选择器 | 属性 | 值 |
|--------|------|-----|
| .site-form | margin-top | 1.75rem |
| .site-form | max-width | 34rem |
| .site-form | background | var(--card) |
| .site-form | border | 1px solid var(--line) |
| .site-form | border-radius | var(--radius) |
| .site-form | padding | 1.8rem |
| .site-form | box-shadow | var(--shadow) |
| .site-form form | display | grid |
| .site-form form | gap | 1rem |
| .site-form label | display | grid |
| .site-form label | gap | .35rem |
| .site-form label | font-size | .92rem |
| .site-form label | font-weight | 600 |
| .site-form label | color | var(--ink-soft) |
| .site-form input | padding | .65rem .8rem |
| .site-form input | border | 1px solid var(--line) |
| .site-form input | border-radius | 10px |
| .site-form input | font | inherit |
| .site-form input | background | #fdfcfb |
| .site-form input | transition | border-color .15s ease, box-shadow .15s ease |
| .site-form textarea | padding | .65rem .8rem |
| .site-form textarea | border | 1px solid var(--line) |
| .site-form textarea | border-radius | 10px |
| .site-form textarea | font | inherit |
| .site-form textarea | background | #fdfcfb |
| .site-form textarea | transition | border-color .15s ease, box-shadow .15s ease |
| .site-form select | padding | .65rem .8rem |
| .site-form select | border | 1px solid var(--line) |
| .site-form select | border-radius | 10px |
| .site-form select | font | inherit |
| .site-form select | background | #fdfcfb |
| .site-form select | transition | border-color .15s ease, box-shadow .15s ease |
| .site-form input:focus | outline | none |
| .site-form input:focus | border-color | var(--accent) |
| .site-form input:focus | box-shadow | 0 0 0 3px rgba(79,70,229,.12) |
| .site-form textarea:focus | outline | none |
| .site-form textarea:focus | border-color | var(--accent) |
| .site-form textarea:focus | box-shadow | 0 0 0 3px rgba(79,70,229,.12) |
| .site-form select:focus | outline | none |
| .site-form select:focus | border-color | var(--accent) |
| .site-form select:focus | box-shadow | 0 0 0 3px rgba(79,70,229,.12) |
| .site-form input[readonly] | background | #f5f5f4 |
| .site-form input[readonly] | color | var(--muted) |
| .site-form textarea | min-height | 10rem |
| .site-form textarea | resize | vertical |
| .site-form .err | color | #b91c1c |
| .site-form .err | font-size | .85rem |
| .site-form .actions | display | flex |
| .site-form .actions | gap | .75rem |
| .site-form .actions | align-items | center |
| .site-form .actions | flex-wrap | wrap |
| .site-form .actions | padding-top | .25rem |
| .site-form button | background | linear-gradient(120deg, var(--accent), var(--accent-2)) |
| .site-form button | color | var(--accent-ink) |
| .site-form button | border | 0 |
| .site-form button | padding | .6rem 1.3rem |
| .site-form button | border-radius | 999px |
| .site-form button | cursor | pointer |
| .site-form button | font-weight | 600 |
| .site-form button | font-size | .95rem |
| .site-form button | transition | opacity .15s ease, transform .15s ease, box-shadow .15s ease |
| .site-form button:hover | opacity | .92 |
| .site-form button:hover | transform | translateY(-1px) |
| .site-form button:hover | box-shadow | 0 6px 18px rgba(79,70,229,.3) |
| .site-form a.btn | display | inline-block |
| .site-form a.btn | padding | .6rem 1.3rem |
| .site-form a.btn | border-radius | 999px |
| .site-form a.btn | border | 1px solid var(--line) |
| .site-form a.btn | color | var(--ink-soft) |
| .site-form a.btn | text-decoration | none |
| .site-form a.btn | font-weight | 500 |
| .site-form a.btn | font-size | .95rem |
| .site-form .meta | color | var(--muted) |
| .site-form .meta | font-size | .9rem |
| .site-form .admin-list | margin | 0 |
| .site-form .admin-list | padding | 0 |
| .site-form .admin-list | list-style | none |
| .site-form .admin-list | display | grid |
| .site-form .admin-list | gap | .5rem |
| .site-form .admin-list li | background | #fdfcfb |
| .site-form .admin-list li | border | 1px solid var(--line) |
| .site-form .admin-list li | border-radius | 10px |
| .site-form .admin-list li | padding | .6rem .9rem |
| .site-form .admin-list li | display | flex |
| .site-form .admin-list li | justify-content | space-between |
| .site-form .admin-list li | align-items | center |
| .site-form .admin-list li | gap | 1rem |
| .site-form .admin-list a | color | var(--accent) |
| .site-form .admin-list a | text-decoration | none |
| .site-form .admin-list a | font-size | .9rem |
**`表单`**
## 响应式
窄屏收为单栏,导航换行。
`响应式` =
| 媒体 | 选择器 | 属性 | 值 |
|------|--------|------|-----|
| (max-width: 860px) | body.has-sidebar | grid-template-columns | 1fr |
| (max-width: 860px) | body.has-sidebar | grid-template-areas | "top" "main" "side" "foot" |
| (max-width: 860px) | aside.side | border-right | 0 |
| (max-width: 860px) | aside.side | border-bottom | 1px solid var(--line) |
| (max-width: 860px) | aside.side | padding | 1rem 2rem |
| (max-width: 860px) | ul.side-nav | flex-direction | row |
| (max-width: 860px) | ul.side-nav | flex-wrap | wrap |
| (max-width: 860px) | main.main | padding | 1.75rem 1.25rem 2.5rem |
| (max-width: 860px) | header.topnav | padding | .75rem 1.25rem |
| (max-width: 860px) | footer.foot | padding | 1.2rem 1.25rem |
| (max-width: 860px) | .content.cards | grid-template-columns | 1fr |
| (max-width: 520px) | ul.nav | flex-wrap | wrap |
**`响应式`**
## 全局
用 样式装配 函数逐个把段落表装配成 CSS,再拼接成完整样式表。
*基础表 = > 基础*
*顶栏表 = > 顶栏*
*侧栏表 = > 侧栏*
*主体表 = > 主体*
*卡片表 = > 卡片*
*页脚表 = > 页脚*
*表单表 = > 表单*
*响应式表 = > 响应式*
*css基础 = > 网页.样式装配 名="基础" 表=`基础表`*
*css顶栏 = > 网页.样式装配 名="顶栏" 表=`顶栏表`*
*css侧栏 = > 网页.样式装配 名="侧栏" 表=`侧栏表`*
*css主体 = > 网页.样式装配 名="主体" 表=`主体表`*
*css卡片 = > 网页.样式装配 名="卡片" 表=`卡片表`*
*css页脚 = > 网页.样式装配 名="页脚" 表=`页脚表`*
*css表单 = > 网页.样式装配 名="表单" 表=`表单表`*
*css响应式 = > 网页.样式装配 名="响应式" 表=`响应式表`*
`css段` =
| css |
|-----|
| `css基础` |
| `css顶栏` |
| `css侧栏` |
| `css主体` |
| `css卡片` |
| `css页脚` |
| `css表单` |
| `css响应式` |
*css = > text.str_join xs=`css段` sep=""*
**css**
+11
View File
@@ -0,0 +1,11 @@
# quantum-bell
Bell |Φ⁺⟩ via `ext/quantum` circuit table + draw (default `theme=dark` tech lab SVG).
```bash
cargo build -p marqdo_plugin_quantum
marqdo ext add quantum # after rebuild, so view loads the new .so
marqdo run examples/quantum-bell/index.mq.md
```
Writes `bell.svg` next to the program (sandbox cwd). Themes: `theme="dark"|"light"|"bw"` — see [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md).
+27
View File
@@ -0,0 +1,27 @@
---
title: Bell state
description: H then CX; probabilities ≈ 1/2; circuit SVG.
import quantum:ext/quantum/quantum.mq.md
import math:lib/math.mq.md
import json:lib/json.mq.md
---
# Bell |Φ+⟩
H on qubit 0, then CNOT(0→1). Ideal measurement: |00⟩ and |11⟩ each with probability 1/2.
# main
`steps` =
| step | gate | qubits |
|------|------|--------|
| 1 | H | 0 |
| 2 | CX | 0,1 |
*qc = > quantum.circuit qubits=2 steps=`steps`*
*p = > qc.probabilities*
*_ = > qc.draw path="bell.svg"*
*_ = > qc.draw kind="probs" path="bell-probs.svg"*
> print text=`p`
+14
View File
@@ -0,0 +1,14 @@
# quantum-entanglement
Bell |Φ⁺⟩ **entanglement lab** via `ext/quantum` Q7/Q8: density matrix, partial trace, Schmidt entropy, and SVG plots (circuit themed dark by default; hinton / qsphere / multibloch / city).
```bash
cargo build --release -p marqdo_plugin_quantum
marqdo ext add quantum # once (re-run after rebuilding the plugin)
marqdo run examples/quantum-entanglement/index.mq.md
# optional: marqdo view examples/quantum-entanglement/
```
Prints probabilities, full/reduced purity, ⟨ZZ⟩, and Schmidt entropy; writes SVGs next to the program (sandbox cwd). Circuit/probs/bloch accept `theme="dark"|"light"|"bw"`.
Design: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · sibling: [quantum-bell](../quantum-bell/).
+45
View File
@@ -0,0 +1,45 @@
---
title: Entanglement lab
description: Bell state — density, partial trace, Schmidt, themed SVG (Q7/Q8).
import quantum:ext/quantum/quantum.mq.md
import math:lib/math.mq.md
---
# Entanglement from a runnable document
Build |Φ⁺⟩ with H then CX. Full-state purity stays 1; tracing out one qubit yields a mixed state (purity 1/2). Schmidt coefficients and entropy quantify the bipartition. SVG plots (hinton / qsphere / multibloch) make the same facts visible.
# main
`steps` =
| step | gate | qubits |
|------|------|--------|
| 1 | H | 0 |
| 2 | CX | 0,1 |
*qc = > quantum.circuit qubits=2 steps=`steps`*
*p = > `qc`.probabilities*
*rho = > `qc`.density*
*pur = > `rho`.purity*
*red = > `rho`.partial_trace keep=0*
*rpur = > `red`.purity*
*zz = "ZZ"*
*ezz = > `qc`.expect obs=`zz`*
*sch = > `qc`.schmidt cut=1*
*ent = sch[^entropy]*
*_ = > `qc`.draw path="entangle-circuit.svg" theme="dark"*
*_ = > `qc`.draw kind="hinton" path="entangle-hinton.svg"*
*_ = > `qc`.draw kind="qsphere" path="entangle-qsphere.svg"*
*_ = > `qc`.draw kind="multibloch" path="entangle-multibloch.svg"*
*_ = > `rho`.draw kind="city" path="entangle-city.svg"*
> print text=`p`
> print text=`pur`
> print text=`rpur`
> print text=`ezz`
> print text=`ent`
+28
View File
@@ -0,0 +1,28 @@
---
title: GHZ state
description: 3-qubit GHZ; |000⟩/|111⟩ ≈ 1/2; probs + H matrix heatmap.
import quantum:ext/quantum/quantum.mq.md
---
# GHZ
H on qubit 0, CX(0→1), CX(0→2). Ideal: |000⟩ and |111⟩ each with probability 1/2.
# main
`steps` =
| step | gate | qubits |
|------|------|--------|
| 1 | H | 0 |
| 2 | CX | 0,1 |
| 3 | CX | 0,2 |
*qc = > quantum.circuit qubits=3 steps=`steps`*
*p = > qc.probabilities*
*_ = > qc.draw path="ghz.svg"*
*_ = > qc.draw kind="probs" path="ghz-probs.svg"*
*H = > quantum.gate name="H"*
*_ = > H.draw kind="matrix" path="ghz-h-matrix.svg"*
> print text=`p`
Loaded 100 of 510 files, more files were not shown because too many files have changed in this diff. Show more