Compare commits

...
111 Commits
Author SHA1 Message Date
cflmy 33a14d272c release: v1.5.2 — foreign v3 P0/P1 (stdin, plan API, snapshot, capture, persist) 2026-10-18 14:57:15 +08:00
cflmy 6ed70fd8b8 docs(design): defer G7 and G8 from the v3 target
Keep the cross-document scope and non-Python/Node adapter designs in the document for future work, but remove them from the current implementation target and priorities.
2026-10-18 14:51:12 +08:00
cflmy 115d1f6c0b feat(view): explicit persist and nested-plan boundary
Add per-cell Persist backed by lib/writeback and /api/session/cell/persist. Reject nested foreign.session plans with a top-level diagnostic and tests.
2026-10-18 14:47:54 +08:00
cflmy 7dc5e56850 feat(foreign): reject nested view plans
Enforce the v3 plan boundary: foreign.session must be a top-level binding. Nested plans are diagnosed instead of silently becoming stateless. Tests cover the AST helper and DocumentSession open.
2026-10-18 14:46:57 +08:00
cflmy 514caa55ae docs(design): mark G9 snapshot capture implemented
view capture and view output --snapshot are implemented with source-hash validation; remaining gaps are G3/G7/G8/G10.
2026-10-18 14:46:20 +08:00
cflmy 74908ebf04 feat(view): capture live snapshots for static export
Add view capture to record per-cell outputs and session summary with source hashes. view output --snapshot consumes the capture without re-executing and rejects source drift. Includes snapshot parsing tests.
2026-10-18 14:45:26 +08:00
cflmy 0f852593bc docs(design): record foreign v3 P0/P1 implementation status
Mark stdin/per-cell inputs/interrupt and plan/snapshot APIs as implemented; keep G3/G7/G8/G9/G10 as pending design items.
2026-10-18 14:44:29 +08:00
cflmy 34e2fb4f74 feat(foreign): snapshot export, import and replay
Export JSON-safe kernel values, cells and journal; restore values into a matching plan; replay cells with recorded stdin. Add /api/session/snapshot/{export,import,replay}.
2026-10-18 14:43:53 +08:00
cflmy 0e407b2bd3 feat(foreign): runtime plan updates and generation
Add explicit add/remove cell and set-value operations with a plan generation counter. Expose /api/session/plan/{assign,add,remove,value}.
2026-10-18 14:43:26 +08:00
cflmy e5e532d83f fix(foreign): keep session_list arity empty
ForeignSessionList accepts no id; only ForeignSessionInterrupt takes id.
2026-10-18 14:38:27 +08:00
cflmy 064522a338 feat(foreign): raw stdin, per-cell inputs and interrupt
Persistent Python/Node kernels receive raw program stdin per eval; foreign.session accepts an inputs table and view exposes per-cell stdin. Add session interrupt host API and view control.
2026-10-18 14:37:45 +08:00
cflmy c85f1a2829 feat(foreign): support raw stdin and per-cell inputs
Session eval now carries raw stdin, and the Python/Node workers temporarily replace program stdin during evaluation. foreign.session accepts an inputs table; view exposes per-cell stdin and Run All sends a per-cell input map. Stateless and persistent cells share the same input semantics.
2026-10-18 14:36:47 +08:00
cflmy a7266185b2 docs(design): propose foreign v3 capability plan
Document the remaining foreign runtime gaps: persistent raw stdin, per-cell input, dynamic plan boundaries, runtime plan updates, interrupt, state export/replay, cross-document scope, non-Python/Node adapters, live-to-static snapshots and explicit writeback policy.
2026-10-18 14:31:44 +08:00
cflmy 4d7c0bea1b fix: sync Cargo.lock with v1.5.1 version bump 2026-10-18 14:23:20 +08:00
cflmy 53758ebd1c debian: changelog entry for 1.5.1-1ppa1 2026-10-18 14:20:24 +08:00
cflmy dff0b700ae release: v1.5.1 — view static/live unified + foreign value passing 2026-10-18 14:05:19 +08:00
cflmy 4da07c1b26 fix(view): do not turn documentation tables into call chips
Keep descriptive table labels non-callable and suppress call annotations on table blocks. This removes the collapsed call {步骤...} chip while preserving the table and the return 950 chips at the actual foreign/writeback calls.
2026-10-18 13:59:24 +08:00
cflmy 78922102e4 fix(view): anchor imported-function returns at their call site
Track the caller line on CallFrame and use it for return annotations instead of the callee library line. Return 950 stays visible on the actual foreign/writeback calls; the Markdown table remains intact and no longer receives stray return chips.
2026-10-18 13:56:50 +08:00
cflmy 064bae2c65 docs(view): keep writeback table labels as inline code
Wrap foreign.run/session and writeback.record table labels in code spans so the prose table is not traced as executable calls; this removes the stray return 950 chips.
2026-10-18 13:52:51 +08:00
cflmy 92b91ffc81 fix(view): group and theme writeback blocks
Render contiguous writeback comment lines as one block, and map output-card/writeback tokens to the View dark theme. Static and live pages no longer show three dashed fragments or light output cards on dark.
2026-10-18 13:51:11 +08:00
cflmy ab6648ae0e docs(view): make the writeback page itself the runnable example
Move the foreign + writeback demo into the user persistence page. The page runs a Python code fence, records a keyed total slot, and the slot is visible in both source and static rendering. Remove the separate example document.
2026-10-18 13:48:05 +08:00
cflmy 5acf026e0c docs(view): add a runnable foreign writeback example
Move persistence guidance out of the walkthrough into separate static pages. Add examples/foreign-writeback/index.mq.md, which executes a foreign code fence and writes a keyed total slot into its own source.
2026-10-18 13:45:27 +08:00
cflmy 8dcd69412f docs(view): recommend static snapshots and writeback persistence
Add a persistence recommendation to the user-facing foreign walkthrough: static export for published snapshots, and lib/writeback for opt-in result slots in the .mq.md source. Show a readable code-fence based writeback example.
2026-10-18 13:40:44 +08:00
cflmy 2a13e52981 docs(view): show low-level session evaluation as code fences
Replace inline source strings with readable Python code fences bound as Marqdo code values. The low-level session evaluates those values; no long escaped source argument remains.
2026-10-18 13:35:51 +08:00
cflmy 9b269f6447 feat(foreign): pass Marqdo values into multi-kernel view sessions
foreign.session accepts a values table and initializes each kernel from ordinary Marqdo values. The static walkthrough now uses two kernels and a shared 订单 value instead of redefining orders inside Python. Static pages embed the session summary so kernel controls and Clean stay visible.
2026-10-18 13:32:51 +08:00
cflmy 15362cb048 fix(view): restore per-cell kernel switch and Clean
Code cards again show a kernel selector and a Clean button. Clean calls /api/session/cell/clear for live sessions and clears local output in static snapshots, without restarting kernels.
2026-10-18 13:27:15 +08:00
cflmy 05d48f68a4 docs(view): show kernel state and Marqdo value passing
Rewrite the static foreign walkthrough without stdin-driven examples. It now demonstrates session_set from an ordinary Marqdo table, persistent kernel state across evaluations, and a foreign.session view plan sharing state across cells. Static export executes those cells and embeds the real outputs.
2026-10-18 13:23:03 +08:00
cflmy e4387259ba fix(view): make static examples self-contained
Foreign cell examples read stdin with a deterministic fallback, so static exports show real output without tracebacks. Low-level session bindings named 会话 are no longer mistaken for a view plan; static export runs all cells again.
2026-10-18 13:19:41 +08:00
cflmy 518f8e386b fix(view): avoid stdin tracebacks in static snapshots
Static export skips cells that read stdin when the document has no preset stdin, and shows a short explanation instead of a traceback. Preset stdin still executes normally.
2026-10-18 13:14:17 +08:00
cflmy 9da12c9093 feat(view): add cell stdin for live and static runs
View gets a Cell stdin/input field wired to cell Run, Step and Run All. Stateless cells receive raw stdin; persistent kernels receive marqdo_input. Static export uses the document preset stdin and the same run_all path.
2026-10-18 13:10:08 +08:00
cflmy e0d34669e0 fix(view): use the same run path for static and live cells
Run All now records per-cell failures and continues; static export uses the same foreign_doc run_all and injects those records. A cell that succeeds in view therefore succeeds in the static snapshot, and failures match.
2026-10-18 13:03:46 +08:00
cflmy 0ba4d3d2d7 feat(view): render real cell outputs in static exports
Static export opens the foreign document session, runs cells once, and injects stdout/stderr/error into the code cards. Failures are shown as real errors; --no-exec still skips execution.
2026-10-18 13:00:41 +08:00
cflmy ad3ebf243a fix(view): keep static buttons with a no-live notice
Static pages now render the same toolbar and Execution Clear button as live view. Clicking any execution control shows a static-export notice instead of hiding controls or pretending to run.
2026-10-18 12:55:07 +08:00
cflmy 142d30ce08 fix(view): share the same shell between static and live output
Static exports now include the View shell and dark theme; interactive toolbar and Execution Clear stay hidden, while dynamic pages show them.
2026-10-18 12:52:48 +08:00
cflmy 4757b82edd fix(view): run stateless documents and clear Execution output
No-session view Run All now runs the document and renders stdout into Execution; Clear outputs clears Execution output, plots and plan cards as well as cell outputs.
2026-10-18 12:51:13 +08:00
cflmy bff2f53e52 fix(view): clear Execution output from the view surface
Add an Execution Clear button and clear the Execution out/plots/plan card in addition to code-cell outputs. The same clearOutputs path calls /api/session/clear, so ordinary stateless pages and foreign sessions are both wired.
2026-10-18 12:47:56 +08:00
cflmy fb28eee62f feat(foreign): own view sessions and clear outputs
foreign.session returns a handle from ordinary kernel/cell tables; view consumes only the 会话 binding. Sessions live in host foreign_doc. Without 会话, view cells run stateless one-shot. Add /api/session/clear and a Clear outputs button for every view page; clearing keeps persistent kernel state.
2026-10-18 12:42:15 +08:00
cflmy 01468ad976 test(view): add foreign and non-foreign preview fixtures
Add a pure Marqdo control page and make the Python view-cells example explicitly import lib/foreign.
2026-10-18 12:22:36 +08:00
cflmy f3791d11b4 refactor(view): evaluate cell plans through the interpreter
Delete the source-line table scanner. 内核表/会话表 are now evaluated as ordinary Marqdo bindings (with simple assignment dependencies) via Interpreter::capture_declarations. Every view page uses the same cell toolbar; run/watch semantics are unchanged; no new CLI or Markdown marker.
2026-10-18 12:17:42 +08:00
cflmy 7fef690167 refactor(view): unify cells into the view surface
Cell controls now appear only when a document declares 内核表/会话表. Remove Notebook branding and Jupyter In/Out prompts; ordinary view pages stay classic. There is no new CLI command or second interactive mode; run remains canonical execution and view is the only interactive surface.
2026-10-18 12:03:17 +08:00
cflmy 024cdee82a debian: add 1.5.0 PPA changelog 2026-10-18 03:36:53 +08:00
cflmy f666eaaf40 release: v1.5.0
Foreign v2 + document-native notebooks, view contrast/themes/resize, public OKF/EKC and Python examples. Bump CLI/wasm/ext to 1.5.0; no core surface delta.
2026-10-18 03:17:53 +08:00
cflmy e6f05c7748 docs(public): showcase foreign v2, OKF and EKC
Rewrite the public foreign reference, add bilingual complex Python notebook and OKF/EKC pages, and expand both homepages with executable foreign, notebook, knowledge and preflight examples.
2026-10-18 03:15:34 +08:00
cflmy 81f9ea0072 fix(view): map document tokens to the active theme
Legacy view tokens (--ink, --fill, --line, --muted) now resolve from the notebook theme. This fixes dark text and white annotation chips on the dark STRUCTURE surface, including function names, binding labels, tables, and the right rail.
2026-10-18 03:05:29 +08:00
cflmy dbf3f3a14b fix(view): raise code contrast and unify syntax colors
Remove the two conflicting highlight.js stylesheets and define one high-contrast token palette. Dark code foreground is #f0f0f0 on #1e1e1e (14.6:1); light is #24292f on #f6f8fa (13.8:1). Keywords, strings, and comments stay above readable contrast, and base view code blocks are resizable too.
2026-10-18 03:03:08 +08:00
cflmy 654e89d98c style(view): make cell resize affordance visible
Style the native vertical resize grip and add a hover hint on code and output panes.
2026-10-18 02:59:36 +08:00
cflmy be20629496 feat(view): resizable cells and light/dark themes
Add native vertical resize to code and output panes; add a VS Code Light token set with Jupyter light syntax highlighting, a toolbar theme toggle, and localStorage persistence. Keep the restored three-column layout.
2026-10-18 02:59:21 +08:00
cflmy 3223295841 fix(view): restore notebook left nav and right rail
Keep the original three-column layout (file navigation, main structure, Functions/Variables rail) and execution/source sections; restyle them with the same VS Code dark surface tokens so the notebook remains readable and consistent.
2026-10-18 02:56:34 +08:00
cflmy beb5bdbe8c style(view): align notebook with VS Code dark and Jupyter cells
Flat VS Code Dark surfaces and borders, Jupyter In[n]/Out[] cell structure, unified top cell toolbar, consistent typography and spacing, removed gradients, glows, heavy shadows, and multi-color pills.
2026-10-18 02:51:28 +08:00
cflmy b8cb022018 style(view): redesign notebook layout and controls
Single-column notebook shell, sticky glass toolbar, card cells with language/kernel/status pills, output panel, dark-mode support, responsive layout, and hidden duplicate Execution/Source sections.
2026-10-18 02:45:10 +08:00
cflmy b9e331cb31 test(notebook): add Python business-insights example
Five-cell Python notebook sharing one kernel: deterministic order generation, regional/product metrics, z-score anomaly detection, ASCII report + JSON, and an isolated second Python kernel that validates the report through an explicit file bridge.
2026-10-18 02:38:48 +08:00
cflmy 476c2b607b fix(view): use relative API URLs for path-prefix reverse proxy
Notebook and debugger controls now call api/... and open debug?path=... relative to the page, so the same HTML works under a path prefix such as /marqdo-view/<token>/. This enables same-origin DSH preview without publishing another Docker port.
2026-10-18 02:33:50 +08:00
cflmy d99b275336 fix(parse): do not over-promote branch-local variables to params
If/else arms that all bind a local (e.g. # llm key/url/mdl/nm) no longer leak it into constructor params. This fixes the missing `key` error in llm.create and restores the agent/llm gold tests. Adds a regression test.
2026-10-18 02:09:16 +08:00
cflmy 1415aee08f docs(notebook): record D1–D3 implementation status 2026-10-18 01:45:41 +08:00
cflmy 0f2c12b636 feat(notebook): link statement debugger from view
Expose /debug and /api/debug/* on the live view server; add a notebook Debug button so Marqdo statement stepping is reachable from the same page/session as cell stepping.
2026-10-18 01:44:05 +08:00
cflmy 9873df7099 feat(notebook): reload, journal and state panel polish
D3 (partial): reload re-parses the document while preserving kernels, marks changed cells dirty; Journal and Reload view actions; filtered Node variable names for the state panel; per-session timeout parsing before spawn.
2026-10-18 01:41:36 +08:00
cflmy 3001ed7ba5 feat(notebook): document session with shared kernels and view controls
D1/D2: 内核表/会话表 parsing, DocumentSession cell index, named/default kernels, shared state + isolation, run_cell/step/run_all/restart/assign, state bridge, journal, POST /api/session/*, and a live-view notebook bar with status badges, per-cell kernel selector, step/run-all and push/pull state form.
2026-10-18 01:39:36 +08:00
cflmy 050d71927f feat(foreign): persistent Python/Node kernels and state bridge
F3/F3.5: session_open/eval/close/list, session_set/get/names, Python and Node bootstraps, strict serial protocol, per-session timeout, crash isolation, drop cleanup, and node/bash gold tests (python conditional).
2026-10-18 01:32:48 +08:00
cflmy 7859170aec feat(foreign): JSON call and parallel fan-out
F2: call/call_many JSON bridge, run_many ordered parallel execution with per-item isolation and concurrency cap, plus node gold tests for call and call_many.
2026-10-18 01:29:15 +08:00
cflmy e32ff8f6b3 feat(foreign): structured invoke, presets, probe and config
F0/F1: safe execution core (exec gate, bounded IO, process-group timeout), structured invoke records, run options, 15 language presets, register/unset/probe/config, view stderr/exit/ms, and node/bash gold tests.
2026-10-18 01:26:53 +08:00
cflmy c21a28c3bc docs(foreign): design kernel runtime and document session
Record the Jupyter-beyond discussion, decisions, and the document-native notebook syntax (内核表/会话表). Split the design into F (foreign kernel runtime) and D (document session) layers, with roadmaps, state bridge, stepping, journal, and security rules.
2026-10-18 00:43:31 +08:00
cflmyandCursor 1e61dca9d8 release: Marqdo 1.4.6
CLI and wasm only. Bare self-increment now promotes a required parameter, matching design §8.2. Extension pack stays 1.4.5.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 23:58:09 +08:00
cflmyandCursor ba675a4767 fix(parse): promote a bare self-increment to a required parameter.
Design §8.2 treats the first bold assignment as a declaration, but merging only walked backtick mentions, so n = n + 1 never entered the signature.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 23:55:30 +08:00
cflmyandCursor bfd468d5e3 release: Marqdo 1.4.5
Streamable HTTP MCP, web invoke Bearer/401, openai/agent json.get hardening.
Bump CLI/Ext/wasm and debian changelog.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 17:36:07 +08:00
cflmyandCursor 8353ba38fe Add Streamable HTTP MCP and harden web /v1 invoke auth.
agent_mcp_serve gains http transport; invoke injects Bearer/X-Api-Key and maps
unauthorized to 401; openai/agent field access prefers json.get over footnotes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 17:33:24 +08:00
cflmyandCursor b43a08b2e2 release: Marqdo 1.4.4
Soft LLM transport errors and table-first ext/ai; CLI + Ext + wasm SemVer bump.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 14:38:16 +08:00
cflmyandCursor 1908bf1a53 fix(ai): soft LLM transport errors and strip ext/ai json glue
Host/plugin HTTP failures return structured finish|status=error instead of
aborting the VM; agent/llm/openai/智能体 result maps use GFM tables and
table.put. SKILL gains positive copy-paste examples so agents stop mirroring
legacy json.set chains.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 14:27:45 +08:00
cflmyandCursor c44ea38ae2 release: Ext pack 1.4.3 — agent.run cold EFI / resolve llm_free
Bump ext/VERSION only (CLI stays 1.4.2). Ships agent facade + native miss-field fix for qdagent cold OKF.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 12:56:40 +08:00
cflmyandCursor d489f7c088 fix(ext/ai): cold agent.run EFI — self.preflight and resolve llm_free
Miss resolve omitted llm_free and run called bare preflight, which crashed
qdagent on empty OKF. Align miss fields, use self.preflight + json.get, add
regression gold and research note.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 12:54:00 +08:00
cflmyandCursor a993cfd76a chore: sync Cargo.lock package versions to 1.4.2
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 12:21:23 +08:00
cflmyandCursor d5f826a8c8 release: Marqdo 1.4.2
Bump CLI/wasm/ext to 1.4.2 for Agent/LLM optimize O1–O5 (sandbox trial,
promote proof, step_route/EFI, lint, quarantine).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 11:51:41 +08:00
cflmyandCursor 0f72173d08 feat(ext/ai): land Agent/LLM optimize waves O1–O5
Wire opt-in sandbox trial into agent, require sandbox proof before OKF
promote, add step_route/EFI/cost surfaces, style lint + quarantine, and
offline policy optimize script—keeping GFM tables over json glue.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 11:47:28 +08:00
cflmyandCursor a707758d47 docs: research and plan Agent/LLM optimization with OKF and sandbox
Capture the 2026-10 landscape (skills, Skill Lift, routing, GEPA) against Marqdo’s code-as-docs assets and list feasible optimize directions without editing doc/next.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 11:13:48 +08:00
cflmyandCursor 63bcb882a6 feat(ext/ai): add CoW sandbox for Marqdo-only agent trials
Give agents a capability-capped run path that stages workspace edits until commit, so generated .mq.md can be verified without polluting the real tree.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-16 11:11:54 +08:00
cflmyandCursor 1bb16dd6db release: Marqdo 1.4.1
View annot leaders mid-to-mid SVG, frame chip id unify; bump CLI/wasm/ext.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 20:37:24 +08:00
cflmyandCursor 58ec2172d6 fix(view): mid-to-mid annot leaders and prose chip density
Unify frame chip ids with marks, reorder chips under anchors, and draw
SVG leaders from underline mid-bottom to chip mid-top so crowded bands
stay readable.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 20:36:12 +08:00
cflmyandCursor 66926e9e0a release: Marqdo 1.4.0
Prose-unified control flow, formula meta bind, image writeback, view
inferred params; sync CLI/wasm/ext/VERSION and install docs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 15:54:45 +08:00
cflmyandCursor dcf4c05663 fix(ext/net): wrap url.encode via lib/net, not host_*
Gold rule bans host_* from ext/**; encode must go through stdlib.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 15:47:07 +08:00
cflmyandCursor f47a1e143a feat(writeback): image form ![marqdo-out](…) with view parity
Auto-persist image paths/URLs as Markdown images (validated extension);
keep HTML comment for text. View and static export share styled source
markers and output-card <img> rendering.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 15:45:52 +08:00
cflmyandCursor 9cf98a98b5 feat: block formula meta bind and control-flow prose
Support $$ % marqdo: var= binding, arm/loop narrative (fix comment-paragraph
swallow of branch arms), foreach ZH/EN sugar, and condition-line narrative.
Welcome pages and gold samples updated; view skips meta formula fence bodies.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 15:28:46 +08:00
cflmyandCursor f99d552d87 feat(view): show inferred param values; migrate welcome to v0.3 prose
Param chips carry call-frame values (and refresh with the call picker).
Welcome pages and the marqdo skill prefer body-inferred, conversational markup.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 14:32:50 +08:00
cflmyandCursor 7d49c358c1 fix(view): nested-call welcome + clean formula/code cards
Welcome pages put greet calls in # main so CallFrames/pickers appear;
document surface skips fence body lines and Bind chips under formula/code cards.
Adds view-static-interactive design and entry-vs-method regression tests.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 14:13:42 +08:00
cflmyandCursor a32c0cd78f fix(ppa): skip cp when local orig already sits in build-area
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 13:42:37 +08:00
cflmyandCursor 0a8f76d9b4 release: v1.3.3 — view document-surface Structure
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 13:18:51 +08:00
cflmyandCursor 4e2419b598 feat(view): document-surface Structure with frame-aware annotations
Browse Structure keeps narration and surfaces post-stmt values, branch
arms, and call/loop pickers; static `view output` shares the same render
path so exported HTML matches live view.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 13:12:53 +08:00
cflmy f6374d1593 release: ext pack v1.3.2 trailing slash route fix 2026-10-13 15:37:42 +08:00
cflmy 9ede4bc63d fix(web): strip trailing slash so /post/foo/ matches /post/foo
Go ServeMux does exact-match routing; a trailing slash caused dynamic
routes like /post/{slug} to fall through to the 404 catch-all. Add
withStripTrailingSlash middleware as the outermost handler wrapper so
all downstream middleware (RBAC, tenant, mux) see the normalized path.

Tested: static routes, dynamic routes, root path, query-string preservation.
2026-10-13 15:24:26 +08:00
cflmyandCursor 3ae8f2c843 release: ext pack v1.3.1 OIDC path redirect_uri
Bump ext/VERSION only; CLI remains 1.3.0.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-08 11:42:08 +08:00
cflmyandCursor e9c1a8a730 feat(web): resolve OIDC redirect_uri from request Host
Allow path-style redirect_uri (/oidc/callback) so apex/www and
proxied HTTPS share one config; persist the absolute URI for token exchange.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-08 11:35:12 +08:00
cflmyandCursor 5554b1642c feat(run): add --fs-root / MARQDO_FS_ROOT for subdirectory entries
marqdo run cli/… sandboxes to the entry directory by default; repo-root
sandbox+cwd lets qdagent keep thin CLI wrappers under cli/ without
escaping .marqdo or polluting cli/.marqdo.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 22:17:24 +08:00
cflmyandCursor fe15603a91 fix(llm): hoist ask result fields out of the return table
Table cells shadowed self/column names (model, usage), so [model](self)
and [total_tokens](usage) raised "footnote index needs list or map" and
blocked live agent.step / qdagent BUILD.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 22:08:48 +08:00
cflmyandCursor 1418742655 Skip docker/data/.cursor when compiling engineering knowledge.
Packaging trees and runtime vaults were inflating EKC with duplicate noise; dogfood agents should index product sources only.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 21:50:58 +08:00
cflmyandCursor ed31a2b31d release: v1.3.0 Engineering Knowledge Compiler (EKC)
Bump CLI/ext/wasm to 1.3.0; document L0–L4 catalog, reuse preflight, and
agent eng_* surfaces for AI-native engineering.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 16:46:30 +08:00
cflmyandCursor 56ab52356f feat(knowledge): land Engineering Knowledge Compiler (EKC) from 008
Give agents Engineering First Information before codegen: L0–L4 catalog,
reuse/preflight (REUSE→ADAPT→CREATE), graph, and CLI surfaces so large
repos stop reinventing existing capabilities.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 16:44:39 +08:00
cflmyandCursor 2e425c3010 chore: sync Cargo.lock to 1.2.0 for PPA vendor
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 11:59:48 +08:00
cflmyandCursor 46a0263d7f release: v1.2.0 Web Artifact (ADR 0007) Document/Endpoint/Resource
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 11:39:25 +08:00
cflmyandCursor ff252fd469 feat(web): land Artifact serve/endpoint path and retire compose golds
Wire data_source into Document render, register Endpoint handlers via
run_artifact, restore marqdo-blog as an Artifact site, and replace old
compose_* web golds with ADR 0007 fixtures and docs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 11:36:45 +08:00
cflmyandCursor 67bac1bf02 feat(web): Document/Endpoint/Resource artifact rewrite (ADR 0007)
Replace the monolithic compose_*/configure author surface with file-level
web|endpoint artifacts, split ext/{web,data,security,net}, and lock
no-degrade rules so the model cannot regress to God-object APIs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-28 11:06:38 +08:00
cflmyandCursor 33f8b94bb0 release: v1.1.1 AI stack (llm/agent/metadata) + ship plugins/llm
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:34:08 +08:00
cflmyandCursor 0ed57b6d54 feat(agent): ext APIs, goldens, and docs for MCP/resume/small-llm routing
Wire mcp_connect/list/call, resume_*, and demote Jev in author docs.
Offline goldens cover MCP client, resume, and small-llm/jev-alias route.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:26:55 +08:00
cflmyandCursor c29d48f38c feat(agent): MCP stdio client, resume checkpoints, small-llm router alias
Add agent_mcp_client and agent_resume_* plugin APIs. Treat jev as a
compat alias of small-llm; auto cascade no longer probes MARQDO_JEV.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:26:55 +08:00
cflmyandCursor f1e82ce4e5 feat(llm): optional plugins/llm Transport ABI for chat completions
OpenAI transport prefers llm_chat_completions when the native plugin is
resolvable, and falls back to lib/net HTTP/SSE so CI stays green without the .so.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:26:55 +08:00
cflmyandCursor 2d412e3bba feat(llm): LLMResult.tool_calls from OpenAI-shaped responses
Parse choices[0].message.tool_calls into the ask Result; empty list when
absent. Offline gold covers tool_calls_from.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:07:59 +08:00
cflmyandCursor 46d78c6e15 feat(core): Phase 2 Metadata scope lift (no body ${})
Inject bound frontmatter keys into the entry env as ordinary variables.
Reject body ${env…}; bytecode entry prologue seeds the same locals.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 20:05:25 +08:00
cflmyandCursor 81a14f9b38 feat(llm): sys.module_source + entry prompt / meta offline paths
Expose entry source via sys.module_source; ask/stream fall back to
prompt_body of the entry document. Add meta-binding and entry-prompt golds.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 19:52:57 +08:00
cflmyandCursor 88dc6d5a54 feat(core): Artifact Metadata Binding (${env|arg|sys|secret})
Load-time resolve of frontmatter bindings into Module.metadata; Secret
masking; sys.meta / --bind; llm ctor prefers meta over env_get.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 19:51:24 +08:00
cflmyandCursor 4a2d89406b fix(agent): preserve llm_free resources under plan force
Stop plan from clobbering an existing resources workbook with an explore
skeleton. Add llm.prompt helpers and agent-plan-preserve gold.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 19:34:05 +08:00
cflmyandCursor d8d435fead feat(ai-stack): metrics, named handles, prompt docs, backends, zero-LLM
Finish ai-stack steps 1–5: model_turn usage, fast/reasoning, type:prompt
load, openai/ollama split, and agent-zero-llm gold. Fix compiled-skill
Marqdo syntax so llm_free await no longer falls through to plan+HTTP.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 19:30:25 +08:00
cflmyandCursor 1f8e61f3bf feat(llm): semantic ask/stream/collect surface (005)
Lift ext/ai/llm from OpenAI HTTP client to an intelligence primitive;
keep complete as compat. Add unified ai-stack roadmap linking agent + llm.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 13:35:38 +08:00
cflmyandCursor a9ee858f53 feat(agent): Skill Compilation + Adaptive Routing (v2/P4)
Episode → maybe_learn → llm_free skills, plus abstract router backends
(marqdo/small-llm/jev?/llm/auto) via plugins/agent; no core host changes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-24 13:28:50 +08:00
cflmyandCursor 8489d90926 docs(public): 新增 feature 18 —— AI 原生闭环(契约 + MLSP)中英各一篇
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 13:46:03 +08:00
350 changed files with 49882 additions and 8239 deletions

No files matched your search

+26
View File
@@ -0,0 +1,26 @@
---
description: Marqdo Web Artifact — no degradation; Document/Endpoint/Resource only
globs: ext/web/**,ext/net/**,ext/data/**,ext/security/**,examples/**/*,tests/ext/web*,doc/design/ext-web*,doc/adr/0007*
alwaysApply: true
---
# Web Artifact — 不允许降级
Canonical: `doc/adr/0007-web-document-endpoint.md` · `doc/design/ext-web-artifact.md` · `doc/next/007.md` (superseded).
## Hard bans
1. **Do not** restore or reintroduce author-facing `compose_main` / `compose_intro` / `compose_*` fragmented table DSLs, god `# page` mutation piles, or `app.configure(...)` junk-drawer APIs.
2. **Do not** use `json.set` / `json.append` bag glue for pages, routes, or middleware. Tables = data. View schema is only `|type|slot|value|attrs|style|` (ZH aliases allowed).
3. **Do not** call `ensure_plugin` or `host_*` from author programs or from `ext/**` (plugin load is facade/capability only).
4. **Do not** register implicit user routes. Declared routes come from Artifact metadata or `web.route`. System routes (`/_part`, `/_form`, …) must appear in `web.inspect`.
5. **Do not** invent DSL, nested frontmatter under `##`, or new table dialects when the design is silent — **stop and ask**.
6. **Do not** mix EN/ZH API names in one `.mq.md`.
7. **Do not** silently delete capabilities. Removals require design text + tests updated in the same change.
8. **Do not** put DB/auth/cache/storage/websocket author APIs back into `ext/web/web.mq.md` — they live in `ext/data`, `ext/security`, `ext/net`.
## Required direction
- Document (`type: web` / `类型: 网页`), Endpoint (`type: endpoint` / `类型: 端点`), Resource modules.
- Facade only: `web.page` · `web.route` · `web.serve` · `web.render` · `web.inspect` (ZH mirrors).
- Code is documentation: the `.mq.md` is the page/API docs and the implementation.
+59 -5
View File
@@ -38,7 +38,7 @@ A `.mq.md` file must stay readable as Markdown. If a human cannot skim the data
Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = text, `` `var` `` = variable, quote paths/`/` ratios.
### 2. Good patterns
### 2. Good patterns (copy these — not `json.set`)
**Wire / steps / commands** — `@` record table:
@@ -60,7 +60,53 @@ Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = tex
| `wire` | `set_text` |
```
**Single dynamic key** — one `table.put` (or a helper), not a json chain:
**Agent / LLM result map** — one readable row, not a `json.parse` + `json.set` chain:
```markdown
`out` =
| status | task | result | llm_calls | tokens |
|--------|------|--------|-----------|--------|
| ok | `task` | `reply` | `llm_calls` | `tokens` |
*out*
```
**Soft error pack** (transport / gate failure) — still a table humans can skim:
```markdown
`pack` =
| finish | text | error | usage | tool_calls |
|--------|------|-------|-------|------------|
| error | "" | `msg` | `usage0` | `empty_tc` |
*pack*
```
**Optional / conditional key** — sparse `table.put` after the static table (one dynamic key only):
```markdown
`out` =
| status | task |
|--------|------|
| error | `task` |
1. `err`
**out = > table.put in=`out` at="error" value=`err`**
2. *
**_ = 1**
```
**Empty list / empty map** — prefer stdlib seeds over `json.parse text=[]` / `{}`:
```markdown
**empty_tc = > table.empty_list**
**empty_map = > table.empty_map**
```
**Single dynamic key from scratch** — one `table.put` (or a helper), not a json chain:
```markdown
**`set_text` = table.put in=None at="#log" value=msg**
@@ -73,14 +119,20 @@ Better still — call a named helper:
**browser.set_text sel="#log" text=msg**
```
### 3. Bad pattern (do not write)
**When `json.*` is OK:** `json.parse` / `json.stringify` / `json.quote` on **wire text**; `json.get` to read an opaque map. Never use `json.set` / `json.append` to *build* author-facing structures.
### 3. Bad pattern (do not write — and do not copy from old `ext/ai`)
```markdown
**`ret` = json.set map=None key="set_text" value=…**
**`ret` = json.set map=ret key="canvas" value=…**
**`cmds` = json.append list=cmds item=c0**
**`out` = json.parse text={"status":"ok"}**
**`out` = json.set map=out key="task" value=task**
```
Matching surrounding **legacy** `json.set` in `ext/ai/*.mq.md` is **not** compliance. Refactor the call site to tables / `table.put` instead of extending the glue.
## Writing application `.mq.md`
1. Frontmatter: title + imports (`table`, domain libs). **Do not import `json` unless parsing strings.**
@@ -92,7 +144,7 @@ Better still — call a named helper:
7. **Do not use `##` inside `# main` for document sectioning** — those become nested functions. Use paragraphs / `---` breaks instead.
8. **Index:** prefer `[键](集合)` / `` [`名`](集合) `` over footnote `` m[^k] ``.
Browser client programs: prefer `import browser:lib/browser.mq.md` (no native plugin). Server sites: `ext/web` + GFM page/style tables.
Browser client programs: prefer `import browser:lib/browser.mq.md` (no native plugin). Server sites: Artifact Metadata (`type: web|endpoint`) + `ext/web` facade + `ext/data` / `ext/security` / `ext/net` — see [ext-web-artifact.md](../../doc/design/ext-web-artifact.md). **Never** restore `compose_*` / `app.configure`.
## Developing libraries (`lib/*`, `ext/*`)
@@ -121,7 +173,9 @@ Canonical thin-template + waves: [lib-code-as-docs.md](../../doc/design/lib-code
| Need | Place |
|------|--------|
| Browser effect maps (WASM client) | `lib/browser.mq.md` |
| Site HTML / HTTP / DB | `ext/web` classes + compose from tables |
| Site HTML / HTTP | `ext/web` Document/Endpoint + View tables |
| DB / cache / storage | `ext/data` |
| Auth / OIDC / RBAC | `ext/security` |
| List/map primitives | `lib/table.mq.md` |
| Parse JSON text | `lib/json.mq.md` only |
+49 -140
View File
@@ -4,95 +4,40 @@ 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 or ext/linalg, running marqdo CLI,
building dynamic sites with ext/web, quantum circuits with ext/quantum,
formula-first linear algebra with ext/linalg, or when the user mentions
Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, quantum/量子,
or linalg/线性代数 extension.
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): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-mapping-v0.3.md) (**v0.3 · runtime**), `doc/design/keywords.md`. Legacy v0.2 notes: `doc/design/markdown-mapping.md` (historical). Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets, **ext → R2+GitHub**, **CLI → Ubuntu PPA**): use [marqdo-release](../marqdo-release/SKILL.md) — detect versions, **ask for SemVer + mode (`full` / `cli` / `ext`)**, then follow that playbook. Ext-only releases are allowed. If sudo/GPG/PPA steps need the user, print the exact commands.
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number.
## Hard rules (do not violate)
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
2. **`**…**` = code** (assign / call). **`*…*` = return value**. Output is **not** either marker — use `> print text=…` / `**print text="…"**` / `> 打印 内容=…`.
3. **Prose:** unmarked narrative may contain `` `名` `` (declare/ref), inline `**code**`, and `*return*`. Soft Markdown emphasis that is **not** code-shaped (`**说明**`, mid-line `*only*`) is ignored — see [code-as-docs-gaps.md](../../doc/design/code-as-docs-gaps.md). Dead `` `名` `` (never read) is OK and does not become a param.
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**. Params: prefer prose `` `名` `` / `` `名`=默认 `` (inferred); `` + `名` `` still accepted.
5. **Identifiers:** `` `名` `` in prose; inside `*…*` / `**…**`, bare ids are **variables**. **Text literals must be quoted** in bold/italic: `**print text="hi"**`. Standalone `>` calls: bare words = text; vars need ticks: `` > str `n` ``.
6. **Structure lines** (`#` `>` `+` `-` `|` `1.`) need not be wrapped in bold.
7. **Paths:** In bare expressions `/` is division. In call args / defaults / table cells, unspaced `a/b` and quoted paths are text.
8. Prefer ending side-effect-only bodies with `*None*` / `*无*` / whole-line `**` / `****` when the next lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped everywhere), not function end.
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 / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division.
8. Prefer ending side-effect-only function bodies with `*None*` / `*无*` / whole-line `**` / `****` when later lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped), not function end.
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug.
12. **Bracket-marked calls:** Function name may be marked with `[函数名]`; bare words before `[` are boolean modifiers (`礼貌 [问候] x` → `礼貌=True`). `]` immediately followed by `(` is **index** `[key](coll)`, not a call. Prefer `[k](c)` over footnote index in new code. See [bracket-call-modifiers.md](../../doc/design/bracket-call-modifiers.md).
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug. Read collections with **`[key](map)`**, not footnote indexes for new code. **Positive copy-paste shapes** (result map, soft-error pack, sparse `table.put`): [marqdo-dev](../marqdo-dev/SKILL.md) §2 · [examples.md](examples.md) §6e. Do **not** extend legacy `json.set` in `ext/ai` — refactor to tables.
12. **One language per file:** Do not mix EN and ZH API names in the same `.mq.md` (imports, calls, params). Pick English *or* Chinese mirrors for the whole program.
13. **Sandbox trial habit (Agent / generated `.mq.md`):** Prefer `agent.trial` / `run sandbox=True` / `sandbox.open`→`run`→`diff`→`commit` before promoting to the host tree. Host files must stay unchanged until a successful commit. Caps live in `sandbox.profile` GFM tables — do not invent a second dialect.
## 记不住语法细节?查 MLSP(AI 必读)
**不必背 Marqdo 语法细节**——语法可查、程序可验、修复有界。写码前后走**查询式**工作流:
```bash
printf '%s\n' '{"id":1,"method":"syntax","params":{"query":"返回"}}' | marqdo mlsp
printf '%s\n' '{"id":2,"method":"locate","params":{"path":"a.mq.md","symbol":"加一"}}' | marqdo mlsp
printf '%s\n' '{"id":3,"method":"validate","params":{"path":"a.mq.md"}}' | marqdo mlsp
printf '%s\n' '{"id":4,"method":"schema","params":{"path":"a.mq.md","unit":"加一"}}' | marqdo mlsp
printf '%s\n' '{"id":5,"method":"repair_targets","params":{"code":"contract.arg_mismatch","doc_anchor":"a.mq.md#L9-L15"}}' | marqdo mlsp
```
| method | 何时用 |
|--------|--------|
| `syntax` | 不确定某个语法怎么写(关键字/别名 → 构造卡片:「返回」「表」「调用」「循环」…) |
| `locate` | 找符号定义位置 + 契约;或反查构造卡片 |
| `validate` | 提交前校验(结构化诊断数组;`ok:false` 就修) |
| `schema` | 查单元契约(形参/返回/字段) |
| `repair_targets` | 拿错误的**有界**修复靶点:只改锚点范围内行,越界必弃权(abstain) |
行分隔 JSON:每行请求 `{"id","method","params"}` → 每行响应 `{"id","ok","result"|"error"}`。
语法唯一事实来源 = `doc/design/core-surface.md`(CI 守卫同步);卡片带 `manual` 指回文档行。
所有错误诊断都是结构化 JSON:`code` / `severity` / `span` / `suggestion` / `doc_anchor` / `doc_quote` / `contract_ref`。
### 渐进式契约(可选标注;schema 就长在文档表里)
契约是**未绑定文档表**(绑定表是数据,永远不是契约)。三种形状、严格位置:
| 形状(须含 `类型` 列) | 允许位置 | 附着 |
|--------------------------|----------|------|
| `参数`/`类型`/`说明` 表 + `返回`/`类型`/`说明` 表 | 函数体首个可执行行之前 | 函数 |
| `字段`/`类型`/`可空`/`说明` 表 | 紧邻 `` `名` = `` 绑定之前 | 集合(变量) |
| `字段`/`类型`/`可空`/`说明` 表 | 对象(`#`)体首成员之前 | 对象类型 |
````text
## 加一
对于输入变量`n`,期望是数字。
| 参数 | 类型 | 说明 |
|------|------|------|
| n | number | 输入值 |
| 返回 | 类型 | 说明 |
|------|------|------|
| | number | 加一结果 |
*n+1*
````
- 类型词汇:`text` / `number` / `bool` / `list` / `map` / `any` / `#` 对象名(拼错 ⇒ `contract.unknown_type` + 最近建议)。
- 契约表**永不执行**、不污染升参推断;无契约文件行为逐字节不变(动态默认,零摩擦)。
- 运行时只在四个边界校验:调用实参 / 字段访问 `[键](集合)` / 表绑定 / 返回。
- `marqdo check [FILE] [--json]` 静态互查:契约行 vs 升参推断形参**双向**漂移(错行=Error;新升参未覆盖=Warning)、未知类型、错位契约;有 Error 非零退出。
- 契约诊断带 `doc_anchor` + `doc_quote`(表原文)——修复只照锚点局部改。
## Markup → meaning (v0.3)
## Markup → meaning (v0.2)
| Marker | Meaning |
|--------|---------|
@@ -103,14 +48,13 @@ printf '%s\n' '{"id":5,"method":"repair_targets","params":{"code":"contract.arg_
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
| Line `N. *` | Else arm |
| `> fn args` | Call (named `k=v` or positional) |
| `修饰 [fn] args` | Bracket-marked call; leading words → `名=True` |
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
| `**…**` | **Code** (assign / call) — closing `**` touches last token; bare ids are variables; quote text literals |
| `*…*` | **Return value** — closing `*` touches last token; bare ids are variables |
| `****` / whole-line `**` / `*None*` | Return `None` and end function body |
| `*…*` | 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 `---` / `***` | Markdown thematic break (skip; not function end) |
| GFM table after empty RHS bind | Collection; get with `[key](coll)` (preferred) or legacy `` `m`[^key] `` |
| `- [item](coll)` | Foreach (unchanged) |
@@ -159,17 +103,17 @@ Chinese builtins (same functions, no import):
## Statements, returns, branches
```markdown
**x = 1**
**y = x + 2**
*x = 1*
*y = x + 2*
## add_one
+ `n`
*n + 1*
**n + 1**
```
```markdown
**n = 0**
*n = 0*
1. `n` > 0
> print text=positive
@@ -192,16 +136,16 @@ import clock:lib/time.mq.md
# main
**xs = > text.str_split s="a,b,c" sep=","**
*xs = > text.split value="a,b,c" sep=","*
> print text=`xs`
**t = > clock.now_unix**
*t = > clock.now_unix*
```
- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages).
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum|linalg` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below); **`ext/linalg`** — formula-first linear algebra (see below).
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum` (see `doc/design/ext-cli.md`). `ext/llm` — chat; **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below).
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`).
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
@@ -218,48 +162,22 @@ Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --releas
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only.
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import).
APIs: `# agent` / `# 智能体` → `## step` / `## plan`. Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`).
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/) · [agent-sandbox-okf](../../examples/agent-sandbox-okf/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · optimize O1–O5: [ext-ai-optimize.md](../../doc/roadmap/ext-ai-optimize.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
## Official extension: `ext/web` (dynamic sites)
**Sandbox (O1):** `import sandbox:ext/ai/sandbox.mq.md` · `agent.trial` / `智能体.试跑` · `run`/`step` take `sandbox=` / `沙盒=` (default `False`). Profile caps are tables via `sandbox.profile`. Gold: `tests/ext/agent-sandbox-optin.mq.md`.
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin first: `cargo build --release -p marqdo_plugin_web`.
## Official extension: `ext/web` (Document / Endpoint / Resource)
Import **one language file** — never mix EN/ZH API names in the same `.mq.md`:
Install: `marqdo ext add web` (ZH id: `网页`). See ADR 0007 · [ext-web-artifact.md](../../doc/design/ext-web-artifact.md).
**Do not degrade:** Document/Endpoint metadata; facade `web.page|route|serve|render|inspect`; View `|type|slot|value|attrs|style|` only; no `compose_*` / `configure` / author `ensure_plugin`. DB → `ext/data`; auth → `ext/security`; net → `ext/net`.
- EN: `import web:ext/web/web.mq.md`
- ZH: `导入 网页:ext/web/网页.mq.md`
**Hard rules (web):**
- Authors use **GFM tables + `#` classes** — no `json.parse` / `json.set` glue, no hand-built part JSON.
- Table cells stay **literal strings**; path text like `` `posts`.`title` `` is resolved by web classes.
- **Quote path/MIME cells** that contain `/` (T5 cell expressions treat bare `/` as division): `"/static/logo.svg"`, `"image/png"`.
- **`ext/**` never calls `host_*`** — hot path is native `plugins/web` ABI (default **Go `libweb`**, build via `scripts/build-web-plugin.sh`).
- HTTPS: terminate at reverse proxy; set `cookie_secure=True` on auth (no in-process TLS).
**Typical layout:**
```text
index.mq.md # entry + home page table + listen
pages/ # sub-pages
components/ # reusable |属性|值|样式| tables
styles/ # CSS modules
public/ # static + favicon.ico|png|svg
db/ # schema + open/init
data/ # sqlite runtime (gitignore)
```
**Core objects (EN / ZH):** `# page`/`页面`, `# style`/`样式`, `# db`/`数据库`, `# form`/`表单`, `# app`/`应用`, `# auth`/`鉴权`, `# cache`/`缓存`, `# storage`/`存储`.
**Typical flow:** `db.init` → `page.compose_*` → `app` + `static` / `listen`. Client: `marqdo wasm build -o static` + `web.client_embed source="/static/client.mq.md"` — **no author JS**; bridge may implement rich host effects ([browser-wasm-e.md](../../doc/roadmap/browser-wasm-e.md) · [browser-app](../../examples/browser-app/)).
**Shipped surface (W0–W7 + P3 + W8 + route D mount):** middleware + JSON API (`app.configure`); transactions, pagination, FTS search (`db.migrate`, `db.fts`, `db.search`); security (argon2, CSRF, SQLite sessions, login rate limit); SEO / RSS / Markdown (`page.meta`, `route_rss`, `lib/net.markdown_parse`); upload / download / gallery; sitemap / robots / error pages / redirects; RBAC (`app.gate`, user `role`); audit timestamps + FK in `db.init`; ETag on downloads; **W8** site icons (`app.icons` → `/favicon.ico`), head resource tables (`page.head`), image assembly (`make_images` / `page.images`); **表驱动引言** `page.compose_intro` / `页面.引言装配`(属性/值/样式表 → `.main-intro`,避免手写 HTML 字符串);**D** `client_embed` auto-mount + DOM effect helpers (`text_patch` / `dom_patch`).
Design: [ext-web.md](../../doc/design/ext-web.md) · assets: [web-assets-and-images.md](../../doc/design/web-assets-and-images.md) · capability matrix: [web-net-capabilities.md](../../doc/design/web-net-capabilities.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/) · client: [examples/web-client-site/](../../examples/web-client-site/).
Web patterns: [examples.md](examples.md) §13 · API index: [reference.md](reference.md).
Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
## Official extension: `ext/quantum` (circuits + Q7/Q8)
@@ -285,29 +203,23 @@ Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --relea
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
## Official extension: `ext/linalg` (formula-first LA)
## Foreign kernels (v1.5.0)
Install: `marqdo ext add linalg` (ZH id: `线性代数`). Build: `cargo build --release -p marqdo_plugin_linalg`, then **`marqdo ext add linalg` again** so view loads the new native lib.
`lib/foreign` is now a full foreign-kernel surface, not only `run`:
- EN: `import la:ext/linalg/linalg.mq.md`
- ZH: `导入 la:ext/linalg/线性代数.mq.md`
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; prefer top-level `la.symbol` (not `matrix.symbol` without a receiver); quote `kind=` strings; dense `explicit` / factorize obey size guards.
APIs (EN): `symbol` → `# matrix`;中缀 `+`/`-`/`*`;方法 `` `A`.T `` / ``.simplify`` / ``.ascii`` · `from_formula` / `explicit` / `factorize` / `draw` · `lstsq` / `norm` / `cond` / `rank`.
Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../../examples/linalg-least-squares/). Design: [ext-linalg.md](../../doc/design/ext-linalg.md) · formula-doc: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
- `invoke` returns a record (`ok`, `code`, `stdout`, `stderr`, `ms`, `timed_out`, `truncated`, `result`); pass `input` for JSON stdin and `output="json"` for a parsed result.
- `call` is JSON-in / JSON-out; `call_many` fans out one program over a list with ordered results.
- `session_open` starts a persistent Python/Node kernel; `session_eval` evaluates source; `session_set` / `session_get` bridge values explicitly as JSON. Close it with `session_close`.
- A view document opts into kernel state with `会话 = > foreign.session kernels=... cells=...`; the table names are free. `view` consumes only the `会话` handle and never scans source lines or reserved table names. Without `会话`, cells are stateless one-shot runs; no kernel is created. Clearing outputs calls `/api/session/clear` and keeps persistent kernel state. There is no separate notebook CLI mode or command, and no new Markdown marker exists.
- The same source remains the authority; state crossing kernels is explicit, never implicitly mirrored.
## AI authoring workflow
1. **查再写**:不确定语法就 `marqdo mlsp`(`syntax` / `locate`)——不必背语法细节。
2. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
3. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
4. 可选:给函数/集合写**渐进式契约**(上节三种表格形状;写全或不写,别写一半)。
5. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
6. On errors:结构化诊断(含 `doc_anchor` / `suggestion`)→ `repair_targets` 取有界靶点,**只改锚点范围内**的行。
7. 提交前:`marqdo check path/to/file.mq.md`(或 `mlsp validate`)清到零 Error。
8. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
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)
@@ -323,13 +235,12 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
| `json.set` / `json.append` to build maps or lists | GFM tables; sparse `table.put`; named helpers (`browser.*`, `web.*`) |
| `json.set` to build page parts | GFM tables + `page.compose_*` / `web.page` methods |
| `json.set` / `compose_*` page parts | `type: web` Document + View table / `web.render` / `web.serve` |
| Import `json` for every browser handler | `import browser:lib/browser.mq.md` + tables ([marqdo-dev](../marqdo-dev/SKILL.md)) |
| Mix `web.page` and `网页.页面` in one file | One import language per `.mq.md` |
| Call `host_web_*` from `ext/web` | Use `# app` / `# db` methods; plugin ABI only |
| Call `host_*` from `ext/quantum` | Use `# circuit` / `# density` methods; plugin ABI only |
| Call `host_*` from `ext/linalg` | Use `la.*` L1 wrappers; plugin ABI only |
| Bare `kind=eig` inside `*…*` | `kind="eig"` — quote text literals |
| 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`) |
@@ -346,5 +257,3 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
- [ ] Browser client: `lib/browser` + tables when returning effects
- [ ] Quantum draw: quote `kind=` / `theme=`; rebuild plugin → `ext add quantum` before view
- [ ] `marqdo run` succeeds (or errors addressed)
- [ ] 语法拿不准的地方已查 MLSP(`syntax`/`locate`),而不是凭记忆发明
- [ ] 契约(如有)与升参一致:`marqdo check` 零 Error
+50
View File
@@ -162,6 +162,56 @@ import browser:lib/browser.mq.md
Do **not** build effect maps with `json.set` chains. See [marqdo-dev](../marqdo-dev/SKILL.md).
## 6e. Agent / LLM result maps — GFM first (positive)
Return and soft-error packs are **tables**, not `json.set` pipelines. Full style contract: [marqdo-dev](../marqdo-dev/SKILL.md) §2.
```markdown
---
import table:lib/table.mq.md
---
## step_ok
+ `task`
+ `reply`
`out` =
| status | task | result |
|--------|------|--------|
| ok | `task` | `reply` |
*out*
## step_err
+ `task`
+ `err`
`out` =
| status | task | error |
|--------|------|-------|
| error | `task` | `err` |
*out*
## soft_http_pack
+ `msg`
+ `usage0`
**empty_tc = > table.empty_list**
`pack` =
| finish | text | error | usage | tool_calls |
|--------|------|-------|-------|------------|
| error | "" | `msg` | `usage0` | `empty_tc` |
*pack*
```
Do **not** mirror legacy `ext/ai/agent.mq.md` `json.parse`+`json.set` chains when adding new arms — convert the shape to a table.
## 7. Import text stdlib
```markdown
+31 -11
View File
@@ -38,7 +38,7 @@ jobs:
run: |
export PATH="/c/ProgramData/mingw64/mingw64/bin:/c/ProgramData/chocolatey/lib/mingw/tools/install/mingw64/bin:$PATH"
cargo build --release
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm
bash ./scripts/build-web-plugin.sh
- name: Checkout extension sources (branch vscode-extension only)
@@ -87,6 +87,7 @@ jobs:
Copy-Item target/release/agent.dll "$stageNative/native/agent.dll"
Copy-Item target/release/quantum.dll "$stageNative/native/quantum.dll"
Copy-Item target/release/linalg.dll "$stageNative/native/linalg.dll"
Copy-Item target/release/llm.dll "$stageNative/native/llm.dll"
if (Test-Path "dist/$nativeZip") { Remove-Item "dist/$nativeZip" -Force }
Compress-Archive -Path "$stageNative/*" -DestinationPath "dist/$nativeZip" -Force
$stage = "dist/stage-bundle"
@@ -100,6 +101,7 @@ jobs:
Copy-Item target/release/agent.dll "$stage/ext/native/agent.dll"
Copy-Item target/release/quantum.dll "$stage/ext/native/quantum.dll"
Copy-Item target/release/linalg.dll "$stage/ext/native/linalg.dll"
Copy-Item target/release/llm.dll "$stage/ext/native/llm.dll"
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
$stageLib = "dist/stage-stdlib"
@@ -124,14 +126,32 @@ jobs:
## Marqdo ${{ github.ref_name }}
### 亮点 / Highlights
- **v1.1.0**:AI 原生闭环三件套——核心表面守卫(问题一)· 渐进式契约 + `marqdo check`(问题二)· **MLSP for AI**(`marqdo mlsp`:locate/syntax/validate/repair_targets/repair_apply/schema,AI 按需查语法而非背诵)(问题三)· `run --json` 结构化诊断
- **v1.1.0**: AI-native loop — core-surface guard, progressive contracts + `marqdo check`, **MLSP for AI** (`marqdo mlsp`: query syntax on demand instead of memorizing), `run --json` structured diagnostics
- **v1.0.7**:WS/网络边界加固(同源握手、require_auth/需要登录、消息上限、HTTP 8 MiB 截断);`url_encode` `%20`
- **v1.0.3**:Ubuntu PPA + 扩展 CDN(ext.marqdo.com);CLI/扩展可分发;noble 捆绑 Rust 工具链
- **v1.0.3**: Ubuntu PPA + extension CDN; independent CLI/ext packs; bundled Rust for noble
- **v1.0.1**:修复 Go `libweb` 动态路由 `{param}` 查询代入、详情 Markdown、CSS 数字误报
- **v1.5.2**:外联 v3 P0/P1——raw stdin + 每 cell 输入 · plan API · snapshot · `view capture` · Persist
- **v1.5.2**: Foreign v3 P0/P1 — raw stdin + per-cell inputs, plan API, snapshot export/import/replay, `view capture`, Persist
- **v1.5.2 ext**:扩展包同步 1.5.2 / Ext pack 1.5.2
- **v1.5.1**:view 静态/动态统一 + 外联值传递——共用执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin
- **v1.5.1**: View static/live unified + foreign value passing — shared execution path, build-time run with stdout injection, `foreign.session` value passing, cell stdin
- **v1.5.0**:外联 v2 + 文档原生 Notebook——invoke/JSON call/并行/持久 Python·Node/状态桥 · cell 单步 · 高对比 view
- **v1.5.0**: Foreign v2 + document-native notebooks — invoke, JSON calls, fan-out, persistent Python/Node, state bridge, cell stepping, high-contrast view
- **v1.5.0 ext**:扩展包同步 1.5.0 / Ext pack 1.5.0
- **v1.4.6**:裸自增升参——首次粗体赋值左值即声明;`n = n + 1` 无反引号也是必选形参
- **v1.4.6**: Bare self-increment is a required parameter — first bold assignment LHS is a declaration
- **v1.4.5**:Streamable HTTP MCP + web invoke Bearer/401 · openai/agent json.get 硬化
- **v1.4.5**: Streamable HTTP MCP + web invoke Bearer/401; openai/agent json.get hardening
- **v1.4.2**:Agent/LLM 优化 O1–O5——sandbox trial · promote proof · step_route/EFI/cost · lint · quarantine
- **v1.4.2**: Agent/LLM optimize O1–O5 — sandbox trial, promote proof, step_route/EFI/cost, lint, quarantine
- **v1.4.1**:view 标注连线——SVG mid→mid(underline 底中 → chip 顶中)· 帧 chip id 对齐 · L→R 密度
- **v1.4.1**: View annot leaders — SVG mid→mid (mark bottom-center → chip top-center), frame chip id unify, L→R density
- **v1.4.0**:叙述统一——`% marqdo: var=` · 臂/循环体叙述 · foreach 中英糖 · 图片自写回 · view 推断形参
- **v1.4.0**: Prose-unified control flow — formula meta bind, arm/loop narrative, foreach sugar, image writeback, inferred-param view
- **v1.3.3**:view 文档面 Structure——叙述保真 · 标记面 · 调用/循环帧 · `#mq-view-trace` · 静态站同源
- **v1.3.3**: Browse document-surface Structure — narration, markers, call/loop frames, `#mq-view-trace`, static site parity
- **v1.3.0**:Engineering Knowledge Compiler——L0–L4 · `reuse`/`find`/`duplicate` · Agent preflight(REUSE→ADAPT→CREATE)
- **v1.3.0**: Engineering Knowledge Compiler — L0–L4 catalog, reuse/find/duplicate, Agent preflight (REUSE→ADAPT→CREATE)
- **v1.2.0**:Web Artifact(ADR 0007)——Document/Endpoint · `web.serve`/`render`/`inspect` · `ext/data|security|net` · 移除 `compose_*`/`configure`
- **v1.2.0**: Web Artifact (ADR 0007) — Document/Endpoint, web.serve/render/inspect, ext/data|security|net, compose_*/configure removed
- **Linux 包必出**:`*-native-x86_64-unknown-linux-gnu.zip` + Linux CLI bundle
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [mapping v0.3](https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping-v0.3.md)
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [ext-ai-optimize](https://github.com/cflmy/marqdo/blob/main/doc/roadmap/ext-ai-optimize.md)
### Downloads
@@ -139,7 +159,7 @@ jobs:
|-------|----------|
| `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib |
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` + `ext/`(含 native DLL) |
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`(Windows DLL + **Linux .so 必出**) |
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`/`llm`(Windows DLL + **Linux .so 必出**) |
| `marqdo-*-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + native `.so` |
| `marqdo-*-stdlib.zip` | `lib/` only |
| `marqdo-*-ext.zip` | Official `ext/` L1 sources |
@@ -184,7 +204,7 @@ jobs:
run: |
set -euo pipefail
cargo build --release
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm
bash ./scripts/build-web-plugin.sh
- name: Package Linux native zip + CLI bundle
@@ -193,7 +213,7 @@ jobs:
VER="${GITHUB_REF_NAME#v}"
TARGET="x86_64-unknown-linux-gnu"
mkdir -p dist/stage-native/native
for lib in libweb.so libagent.so libquantum.so liblinalg.so; do
for lib in libweb.so libagent.so libquantum.so liblinalg.so libllm.so; do
src="target/release/${lib}"
if [[ ! -f "$src" && "$lib" == libweb.so ]]; then
src="plugins/web/build/libweb.so"
+6
View File
@@ -87,3 +87,9 @@ tests/ext/:memory:
# local secrets
.env
# sandbox gold leftovers
tests/ext/_sbx_cow/
tests/ext/_sbx_*/
examples/**/_example_sbx/
+462
View File
@@ -1,5 +1,467 @@
# Changelog
## Unreleased
### Added
### Fixed
### Changed
## v1.5.2 — 2026-10-18
### Highlights
**外联 v3 P0/P1**:session eval 支持 raw stdin(Python/Node 持久内核);每 cell 独立 stdin 与 Interrupt;plan generation/add/remove/value API;snapshot export/import/replay;`view capture` / `view output --snapshot` 捕获实时快照;显式 Persist 按钮。CLI · wasm · ext **1.5.2**。
```bash
git checkout v1.5.2 && cargo build --release
marqdo ext add web # CDN → 1.5.2
```
**核心表面 Δ(Core surface Δ)**:**无增删**——外联 v3 扩展 `lib/foreign` 库 API;不改 MQ 关键词 / 表几何。
### Added
- **raw stdin + 每 cell 输入**:session eval 支持 raw stdin;`foreign.session inputs=` 每 cell 独立 stdin;view 增加每卡 stdin 字段与 Interrupt 按钮。
- **plan API**:plan generation/add/remove/value;运行时 plan 更新与 generation。
- **snapshot**:snapshot export/import/replay;`view capture` / `view output --snapshot` 捕获 live 快照用于静态导出。
- **显式 Persist**:Persist 按钮 + `/api/session/cell/persist`。
- **嵌套 plan 边界**:显式 persist 与嵌套 plan 边界;foreign 拒绝嵌套 view plans。
### Fixed
- **`session_list` arity**:保持空 arity。
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.5.2**。
## v1.5.1 — 2026-10-18
### Highlights
**view 静态/动态统一 + 外联值传递**:静态导出与 live view 共用同一套 `foreign_doc` 执行路径;构建时实际运行代码单元并注入 stdout;`foreign.session` 可把 Marqdo 值传入多内核会话;cell stdin 支持 live/static/持久内核三种模式。CLI · wasm · ext **1.5.1**。
```bash
git checkout v1.5.1 && cargo build --release
marqdo ext add web # CDN → 1.5.1
```
**核心表面 Δ(Core surface Δ)**:**无增删**——view 执行路径统一 + 外联值传递;不改 MQ 关键词 / 表几何。
### Added
- **外联值传递**:`foreign.session kernels= cells=` 可把 Marqdo 值传入多内核 view 会话;`view` 只消费 `会话` 绑定,不再识别 `内核表` / `会话表` 保留名。
- **Cell stdin**:view 增加 `Cell stdin / input` 输入框;Run/Step/Run All 都会传给外联 cells;无状态 cell 使用 raw stdin,持久内核使用 `marqdo_input`;静态导出使用 frontmatter `stdin` 作为构建时输入。
- **静态导出真实执行**:构建时实际执行代码单元并把 stdout/stderr 注入代码卡;静态示例通过代码 fallback 或 frontmatter `stdin` 提供输入。
- **可运行外联写回示例**:新增 `examples/foreign-writeback/index.mq.md`,用 `foreign.run` + `writeback.record` 将结果写入 `.mq.md` 的 keyed 槽位。
- **写回块分组与主题**:view 对写回块按目标分组并统一主题样式。
### Fixed
- **code 卡控制恢复**:恢复每个代码卡的内核切换下拉与 Clean 按钮;Clean 清除单个 cell 输出/记录,不重启内核。
- **导入函数返回锚定**:导入函数的返回值锚定在调用位置。
- **静态导出自包含**:静态示例不再依赖空 stdin 或外部内核状态。
- **Execution 输出清除**:view 清除 Execution 输出从 view 表面。
- **文档表不再变 call chips**:view 不再把文档表转为 call chips。
- **写回表标签**:写回表标签保持为行内代码。
### Changed
- **静态/动态统一执行路径**:static 与 live cells 使用同一 `foreign_doc` `run_all` 路径;移除 `In []` / `Out []` 与 Notebook 品牌。
- **静态按钮行为**:静态页面执行按钮点击显示"静态页面无法真实执行",不伪造成功。
- **低层会话评估可见**:文档展示低层 session evaluation 为代码围栏。
- CLI / wasm / `ext/VERSION` **同步 1.5.1**。
## v1.5.0 — 2026-10-18
### Highlights
**外联 v2 / 文档原生 Notebook**:`lib/foreign` 从“运行一段代码”升级为完整外联内核:结构化 `invoke` 记录、JSON 进出的 `call` / `call_many`、并行扇出、Python/Node 持久内核、显式状态桥,以及用绑定表声明的 Notebook 单元。`view` 增加 cell 单步、Run All、内核切换、journal、状态面板、浅/深主题与可调高度代码区;高对比度 token 修复了代码和 STRUCTURE 文字与背景区分度不足的问题。CLI · wasm · ext **1.5.0**。
```bash
git checkout v1.5.0 && cargo build --release
```
**核心表面 Δ(Core surface Δ)**:**无增删**——外联 v2 只扩展 `lib/foreign` 的库 API;Notebook 的 `内核表` / `会话表` 是既有绑定表;没有新增 Markdown 标记。
### Added
- **用户静态站(外联 / OKF / EKC)**:新增中英双语 `features/19-foreign-view-cells` 与 `features/20-okf-ekc`,重写 `stdlib/foreign`,首页加入「一份文件三个面」、外联 Python 运行、Notebook 表、OKF/EKC 与 preflight 说明。
- **`lib/foreign` F0/F1**:`invoke` 结构化记录(`ok`/`code`/`stdout`/`stderr`/`ms`/`timed_out`/`truncated`/`result`);`run`/`run_lang` 新增 `env`/`cwd`/`timeout`/`args`/`max_output`;15 个语言预设;`probe`/`register`/`unset`/`load_config`;`.marqdo/foreign.toml`。
- **`lib/foreign` F2**:JSON 进 / JSON 出 `call`;并行 `run_many` / `call_many`(有序、单项隔离、并发上限);`invoke` 的 `input` / `output` / `result` / `result_error`。
- **`lib/foreign` F3/F3.5**:Python / Node 持久会话 `session_open` / `session_eval` / `session_close` / `session_list`;状态桥 `session_set` / `session_get` / `session_names`;会话超时即杀、崩溃隔离、drop 清理。
- **Notebook D1/D2**:`内核表` / `会话表` 文档原生语法;`DocumentSession`(cell index / 命名内核 / journal / value store);view Notebook 工具栏(Run All / Restart & Run All / Step / State / Journal / Reload)、状态徽标、内核下拉、Push/Pull 状态表单;`POST /api/session/*`。
- **Notebook D3**:`reload` 重新解析并保留内核,源码变更的 cell 标为 `dirty`;Journal/Reload/Debug 按钮;Debug 打开同一 view 服务的语句级单步页(`/debug` + `/api/debug/*`);状态桥 Push/Pull。
- **安全与健壮性**:所有外联入口检查 `exec` 能力;有界 stdout/stderr 读取与截断标记;stdin 写线程;Unix 进程组 / Windows `taskkill /T` 超时清理;shell-like argv 切分。
### Fixed
- **view 文档表面与标注 chip**:把旧 view 的 `--ink` / `--fill` / `--line` 等 token 映射到当前主题,修复 STRUCTURE 中 `main`、`内核表 =`、函数名和 annot-chip 深色文字/白色卡片与暗色背景不一致的问题。
- **view 代码对比度**:移除会互相覆盖的 highlight.js 深/浅两套外链样式,改用内置高对比 token 变量;深色代码正文 `#f0f0f0` on `#1e1e1e`(14.6:1),浅色 `#24292f` on `#f6f8fa`(13.8:1);关键词/字符串/注释均使用可读的对比色。
- **view 反向代理兼容**:Notebook / Debug 的 API 与 Debug URL 改为相对路径,可在 `/marqdo-view/...` 路径前缀下工作,便于 Docker 内通过 DSH 同源预览。
- **分支内共同局部变量**:if/else 各臂都赋值的局部变量不再被误提升为必选形参;修复 `# llm` 构造器无端要求 `key`,恢复 agent/llm/ext 全量测试。新增 `branch_else_common_local_is_not_a_param` 回归测试。
- **外联临时脚本路径**:入口目录为相对路径时,脚本参数现在使用绝对路径,避免 `tests/lib/tests/lib/...` 双拼接。
- **外联失败可观测**:解释器不存在时进入 `invoke` 记录,`run` 仍报错;view 显示 stderr / exit / ms。
### Changed
- **Notebook view 视觉重做**:采用 VS Code Dark 的扁平色板与 Jupyter 的 cell 组织:单一深色底、明确 surface/border 层级、`In [n]` / `Out [ ]` 提示、顶部 cell 工具栏、无渐变/无重阴影、暗色代码区与一致的字号/间距;保留并统一原始左侧文件导航、右侧 Functions/Variables 栏与 Execution/Source 区块;支持深色/浅色主题切换(localStorage 记忆)与代码区、输出区纵向拖拽调整高度。
- **`langs`** 现在返回「预设 ∪ 注册 ∪ 配置」的已知语言(原集合是子集)。
- 大输出从 `Err` 改为「截断 + `truncated=true`」;`subtask` 外联输出同步采用该语义。
## v1.4.6 — 2026-10-16
### Highlights
**裸自增升参**:粗体首次赋值的左值按设计 §8.2 视为声明。`**n = n + 1**` 在没有反引号提及时也会把 `n` 升成必选形参;缺参报 `missing argument for parameter`,不再是函数体内的 `undefined variable`。纯局部赋值(`**score = 1**`)与循环变量不升参。CLI · wasm **1.4.6**(扩展包仍为 **1.4.5**)。
```bash
git checkout v1.4.6 && cargo build --release
```
**核心表面 Δ(Core surface Δ)**:**无增删**——升参与 §8.2 对齐(赋值左值声明);不改 MQ 关键词 / 表几何。
### Fixed
- **升参**:`merge_inferred_params` 纳入首次粗体赋值左值。右值在绑定前读取同名(`n = n + 1`)时,该名成为必选推断形参。
### Changed
- CLI / wasm SemVer **1.4.6**。扩展包保持 **1.4.5**。
## v1.4.5 — 2026-10-16
### Highlights
**Streamable HTTP MCP + web `/v1` 鉴权硬化**:`agent_mcp_serve` 支持 `transport=http`(MCP Streamable HTTP 2025-03-26);web invoke 注入 `Authorization` / `X-Api-Key`,`ok=false`+`unauthorized` → HTTP 401;`ext/ai` openai/agent 字段访问改 `json.get`,消除 footnote 硬崩。CLI · Ext · wasm **1.4.5**。
```bash
git checkout v1.4.5 && cargo build --release
cargo build --release -p marqdo_plugin_agent
# HTTP MCP:
# QDAGENT_MCP_TRANSPORT=http marqdo run cli/求道-mcp.mq.md
marqdo ext add agent # CDN → 1.4.5
```
**核心表面 Δ(Core surface Δ)**:**新增** MCP Streamable HTTP 传输(`transport=http|streamable-http`);web invoke 契约扩展(header 注入 · 401);**无** MQ 关键词 / 表几何变更。
### Added
- **`agent_mcp_serve` Streamable HTTP**:`transport=http` · `host`/`port`/`path`;POST JSON-RPC + 可选 GET SSE;`Mcp-Session-Id`。facade:`ext/ai/agent` `## serve`。
### Fixed
- **web invoke**:`Authorization` / `X-Api-Key` 注入 payload;`jsonWrapInvokeValue` 对 `unauthorized` 返回 401;`{sse}` 自动 event-stream。
- **`ext/ai/llm/openai` · `agent` · `llm`**:字段访问改 `json.get` / `at`,避免 `[field](x)` 在非 map 上硬崩。
- **explore workbook**:子任务 `stream=False`(网关 SSE 524 更稳)。
### Changed
- CLI / Ext / wasm SemVer **1.4.5**。
- 设计:[doc/design/ext-web-artifact.md](doc/design/ext-web-artifact.md)(sse / bearer)。
## v1.4.4 — 2026-10-16
### Highlights
**LLM 传输软失败 + `ext/ai` 表优先重构**:上游连接拒绝/超时/HTTP≠200 时,Runtime 返回结构化 `finish|status=error`(不再硬中断 VM);`agent` / `智能体` / `llm/openai` 去掉 `json.set`/`json.append` 袋胶水。含 CLI host · `plugins/llm` · Ext pack **1.4.4**。
```bash
git checkout v1.4.4 && cargo build --release
cargo build --release -p marqdo_plugin_llm
marqdo run tests/ext/agent-llm-transport-soft.mq.md
marqdo ext add agent # CDN → 1.4.4
```
**核心表面 Δ(Core surface Δ)**:**无增删**——HTTP 宿主软失败契约 + Extension 风格重构;不改 MQ 关键词 / 表几何。
### Fixed
- **LLM / Agent 传输软失败**:`host_http_post` / SSE · `plugins/llm` · `ext/ai/llm/openai` 结构化 `finish=error`;`agent.step` / `plan` / `run` 收成 `status=error`。金样 `tests/ext/agent-llm-transport-soft.mq.md`。说明:[doc/research/agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)。
- **`agent.run`**:`cache == "soft-hit"` 引号比较(裸 `soft-hit` 曾被解析为减法)。
### Changed
- **`ext/ai` 去 json 胶水**:结果 map / 事件用 GFM 表 + `table.put` / `table.append` / `table.empty_*`。SKILL 正面示例:`.cursor/skills/marqdo-dev` §2 · `marqdo/examples.md` §6e。
- CLI / Ext / wasm SemVer **1.4.4**。
## Ext pack v1.4.3 — 2026-10-16
### Highlights
**Agent cold EFI / resolve 硬崩修复(CLI 仍为 v1.4.2)**:qdagent 接通 `agent.run` 时空 OKF 触发 `unknown function preflight` 与 `missing map key llm_free`。本包修复 `ext/ai/agent` facade 与 `agent` native;金样 `tests/ext/agent-run-cold-efi.mq.md`。说明:[`doc/research/agent-run-efi-resolve-bugs-2026-10.md`](doc/research/agent-run-efi-resolve-bugs-2026-10.md)。
```bash
marqdo ext add agent # CDN latest → 1.4.3
# 或:MARQDO_EXT_VERSION=1.4.3 marqdo ext add agent
```
**核心表面 Δ(Core surface Δ)**:**无增删**——仅 Extension / Agent Runtime 契约修补。
### Fixed
- **`agent.run`**:`efi=True` 改为 `` `self`.preflight ``(不再裸调全局 `preflight`)。
- **`agent_resolve` miss**:返回字段对齐命中路径,含 `llm_free: false`;facade 对 `llm_free` / route 字段改用 `json.get`。
### Changed
- 扩展包 SemVer **1.4.3**(`ext/VERSION`);与 CLI **v1.4.2** 可独立安装。
## v1.4.2 — 2026-10-16
### Highlights
**Agent/LLM 优化 O1–O5**:`ext/ai/sandbox` CoW 试跑接入 `agent.trial` / `run sandbox=`(默认关);promote 强制 sandbox proof;步骤路由 `step_route` + EFI preflight + `usage`/`token_cost`;风格 lint 与 `sandbox.report`;技能 `quarantine` 与离线 standing/policy 优化脚本。表优先、少 json 胶水。路线:[ext-ai-optimize.md](doc/roadmap/ext-ai-optimize.md)。
```bash
git checkout v1.4.2 && cargo build --release
cargo build --release -p marqdo_plugin_agent
marqdo run tests/ext/agent-sandbox-optin.mq.md
marqdo run examples/agent-sandbox-okf/index.mq.md
# Ubuntu: sudo apt update && sudo apt install marqdo
marqdo ext add agent # CDN latest → 1.4.2
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Extension / Agent Runtime**(`ext/ai` 沙盒与晋升闸门),不触碰语言标记。
### Added
- **`ext/ai/sandbox`**:CoW 工作区(`open` / `run` / `diff` / `commit` / `discard` / `inspect` / `profile` / `report`);经 `plugins/agent` `sandbox_*` → `host_query`;默认拒 `plugin`/`exec`/`net`。
- **O1**:`agent.trial` · `run`/`step` `sandbox=` · 中文 `试跑`/`沙盒=` · 示例 `examples/agent-sandbox-okf/` · 金样 `agent-sandbox-optin`。
- **O2**:`agent_kb_promote` 默认 sandbox proof;OKF `applies_when`/`fixtures`/`sandbox_profile`/`proof`;harness Skill Lift。
- **O3**:`agent.step_route` · `ext/ai/policies/step-route.mq.md` · `run efi=`(缺工程知识时软放行)· 结果 `usage`/`token_cost`。
- **O4**:`scripts/mq-style-lint.sh` · `sandbox.report` markdown 审阅面。
- **O5**:`agent_kb_quarantine` / `agent.quarantine` · `scripts/optimize-standing-policy.sh`。
### Fixed
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.4.2**。
- Skill:强制表/链接取元、禁同文件混 EN/ZH、点名 sandbox 试跑习惯。
## v1.4.1 — 2026-10-15
### Highlights
**view 叙述标注连线**:Browse / `view output` 中 underline→chip 改为 SVG 正交连线(描述底边中点 → 轨道 → 短竖线 → 值顶边中点);同跨度多帧 chip 共用 annot id;可见 chip 按锚点 L→R;帧切换后重算密度。设计:[view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)。
```bash
git checkout v1.4.1 && cargo build --release
marqdo view public/00-welcome.mq.md --no-open
marqdo view output public -o /tmp/mq-public
# Ubuntu: sudo apt update && sudo apt install marqdo
marqdo ext add web # CDN latest → 1.4.1
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(view 标注几何与帧 chip 对齐),不触碰语言标记。
### Added
- 设计缺口文档 [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md):叙述 fence 卡、帧感知 chip 密度、L-leader 几何约定。
### Fixed
- view L-leader:id 与 mark 错配、chip 逆序交叉、border 无色变黑碎段、横线穿过 chip 文字;现为 mid→mid SVG path。
- 叙述 fence / 代码卡单层渲染;静态页隐藏 Run;主文函数引用 call chip + leader。
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.4.1**。
## v1.4.0 — 2026-10-15
### Highlights
**叙述统一 + 公式 meta + 图片自写回**:块公式 `% marqdo: var=`;分支/循环体与函数体同权叙述;foreach 中英糖;自写回图片 `![marqdo-out](…)`(扩展名校验)与 view/静态站同源标记;view 展示推断形参实值;欢迎页迁到 v0.3 叙述面。
```bash
git checkout v1.4.0 && cargo build --release
marqdo run tests/markup-v03/formula-meta-var.mq.md
marqdo run tests/markup-v03/foreach-narrative.mq.md
marqdo view tests/view/document-annot-demo.mq.md --no-open
# Ubuntu: sudo apt update && sudo apt install marqdo
marqdo ext add web # CDN latest → 1.4.0
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。Language 层在既有 `formula` / `branch-list` / `loop-list` 上扩展语义(块公式 TeX 注释绑定、臂/循环体叙述、foreach 糖);Runtime:自写回图片形态 + view 推断形参展示。设计:[fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.md)。
### Added
- **块公式 meta 绑定**:`$$` 内 `% marqdo: var=<ident>`(剥离后解析;可无空 RHS);金样 `tests/markup-v03/formula-meta-var.mq.md`。
- **控制流叙述统一**:臂/循环体 `parse_indented_body` 与函数体同权;分支条件行支持叙述前缀与行内 `**…**`;foreach 糖 `- 对…的每一项…` / `- for each … in …`。
- **图片自写回**:路径/URL 且扩展名合法 → `![marqdo-out](…)`;文本仍 HTML 注释;view / `view output` 同源样式卡与 `<img>`。
- **view 推断形参实值**:Browse 展示 body-inferred 参数绑定值;欢迎页 EN/ZH 迁 v0.3 叙述。
### Fixed
- `ext/net/url.encode`:经 `lib/net` 包装,不再直接 `host_*`(金样 `ext_mq_md_never_calls_host`)。
- PPA 源包:`ppa-build-source.sh` 本地 `.orig` 已在 build-area 时跳过重复 `cp`。
- view:嵌套调用欢迎页与公式/代码卡渲染清理。
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.4.0**;词法评论段遇有序分支臂 / 循环头 / 图片自写回标记时断开,避免吞掉控制流行。
## v1.3.3 — 2026-10-15
### Highlights
**view 文档面 Structure**:Browse 保真叙述与标记面(变量/语句/返回无源码定界符);表/循环/分支结构块;语句后绑定值、分支命中臂、函数多调用与循环迭代下拉(默认末帧);`#mq-view-trace` AI JSON。静态 `marqdo view output` 与 live view **同源渲染**(含用户站 `public/` → gh-pages)。
```bash
git checkout v1.3.3 && cargo build --release
marqdo view tests/view/document-annot-demo.mq.md --no-open
marqdo view output public -o public
# Ubuntu: sudo apt update && sudo apt install marqdo
marqdo ext add web # CDN latest → 1.3.3
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(view 文档面 + 帧选择),不触碰语言标记。
### Added
- **Browse Structure 文档面**(`src/view/document.rs` · `annot.rs`):叙述保真、标记面、GFM 表 / `doc-loop` / `doc-branch`、CSS L-leader 标注带。
- **StmtEvent / CallFrame / LoopFrame** 静默轨迹:post-stmt 绑定、分支 `call_id`、循环 `分 = 分数表[i] · value`;调用/迭代 picker(源码常显,只滤 chip)。
- **`ViewExecutionReport`** JSON(`#mq-view-trace` · `/api/view-trace` · SSE `trace_json`)。
- 设计:[view-document-annotations.md](doc/design/view-document-annotations.md) · [view-execution-trace.md](doc/design/view-execution-trace.md) · [view-frame-selection.md](doc/design/view-frame-selection.md);样例 `tests/view/document-annot-demo.mq.md`。
### Fixed
- 多调用分支 taken 混叠;调用切换误藏未执行臂源码;循环头重复 chip。
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.3.3**;静态导出与 live view 共用 `build_file_view` → 文档面。
## Ext pack v1.3.2 — 2026-10-13
### Highlights
**Trailing slash 路由修复(CLI 仍为 v1.3.0)**:Go `ServeMux` 精确匹配导致 `/post/foo/`(带尾部斜杠)落入 404。新增 `withStripTrailingSlash` 中间件作为最外层 handler wrapper,所有下游中间件(RBAC、Tenant、路由)均看到规范化路径。覆盖静态路由、动态路由、根路径、查询参数保留。
```bash
marqdo ext add web # CDN latest → 1.3.2
# 或:MARQDO_EXT_VERSION=1.3.2 marqdo ext add web
```
### Fixed
- **web**: `/post/foo/` trailing slash now routes the same as `/post/foo` (dynamic and static routes). Root `/` unchanged. Query strings preserved after normalization.
## Ext pack v1.3.1 — 2026-10-08
### Highlights
**OIDC 路径型 `redirect_uri`(CLI 仍为 v1.3.0)**:`redirect_uri=/oidc/callback` 按请求 Host / `X-Forwarded-*` 拼绝对回调,写入会话供 token 交换;可选 `redirect_origins` allowlist。apex / www 多域名无需写死单一绝对 URI。
```bash
marqdo ext add web # CDN latest → 1.3.1
# 或:MARQDO_EXT_VERSION=1.3.1 marqdo ext add web
```
### Added
- **路径型 redirect_uri**:绝对 URL 行为不变;路径模式解析 public origin,session 键 `oidc_redirect_uri`。
- **`redirect_origins` / `回调来源`**:逗号分隔 origin allowlist(路径模式)。
- **ABI**:`web_app_oidc` 透传 `redirect_origins`;`ext/security/oidc.attach` 文档同步。
### Changed
- 扩展包 SemVer **1.3.1**(`ext/VERSION`);与 CLI **v1.3.0** 可独立安装。
## v1.3.0 — 2026-09-28
### Highlights
**Engineering Knowledge Compiler(EKC)**:把仓库投影为 AI 可查询的工程知识系统——L0–L4 Catalog、Capability / Decision / Constraint / Failure、知识图、Reuse Preflight(REUSE→ADAPT→CREATE)与 Context Pack。本版 CLI 与扩展包 **同步为 1.3.0**。
- **杀手命令**:`marqdo reuse "task"` / `find` / `duplicate` / `impact` / `conflicts` / `stale` / `verify` / `knowledge`
- **Agent**:`agent.preflight` · `agent_eng_*`;`plan … eng_preflight=True` 在造轮子前强制 EFI
- **投影**:`.marqdo/catalog|knowledge|graph|agent/` + `engineering.yaml`;`catalog` 默认挂钩 EKC
- **示例 / 金样**:`examples/engineering-knowledge/` · `tests/engineering/` · `tests/ext/eng-preflight.mq.md`
```bash
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
git checkout v1.3.0 && cargo build --release
marqdo knowledge . -o .marqdo
marqdo reuse "resolve configuration"
marqdo ext add agent
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(知识编译器 + CLI + agent 插件),不触碰语言标记。
### Added
- **`src/knowledge/` EKC**:L0–L4 IR、指纹、能力推导、图边、compile、find/reuse/preflight、impact/lifecycle/duplicate、metrics、policy、learn。
- **CLI**:`knowledge` · `find` · `reuse` · `impact` · `conflicts` · `stale` · `duplicate` · `verify`;`catalog`/`sync` 默认编译 EKC(`--no-knowledge` 可关)。
- **Agent**:`agent_eng_preflight` / `agent_eng_reuse` / `agent_eng_record`;`ext/ai` `## preflight` + `plan eng_preflight`。
- **规范**:`doc/design/engineering-knowledge.md`;提案叙事 `doc/next/008.md`(已实现标注)。
### Fixed
### Changed
- **OKF type 注册表**扩展 Capability/Decision/Constraint/Failure/Context Pack/Policy 等([okf.md](doc/design/okf.md))。
- **核心表面 Δ**:**无增删**。
## v1.2.0 — 2026-09-28
### Highlights
**Web Artifact 重写(ADR 0007)**:Document / Endpoint / Resource 一等公民;`type: web|endpoint`(ZH `类型: 网页|端点`);facade `web.page|route|serve|render|inspect|use`;DB/auth/ws 拆到 `ext/data` · `ext/security` · `ext/net`。本版 CLI 与扩展包 **同步为 1.2.0**。
- **Document**:文件级 Artifact + `data_source` / `data_order` / `data_where`;正文 Markdown → HTML;列表卡片 / 详情文章由 serve 时加载。
- **Endpoint**:`# main` 处理器;请求经 `run_artifact` Binding 注入;`response` 序列化 JSON/text/html。
- **破坏性**:删除作者面 `compose_*` / `app.configure` / 作者 `ensure_plugin`;旧 web gold 移除,新金样 `ext_web_*`。
- **示例**:`examples/marqdo-blog/` Artifact 站(pages/api/db + smoke);`web-client-site` serve 扫描。
```bash
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
git checkout v1.2.0 && cargo build --release
bash scripts/build-web-plugin.sh && marqdo ext add web
marqdo run examples/marqdo-blog/serve.mq.md
```
**核心表面 Δ(Core surface Δ)**:**无增删**——复用 Metadata `type`;装配语义在 ext + plugin。语言标记不变。
### Added
- **Web Artifact 模型(ADR 0007)**:`type: web|endpoint`(ZH `类型: 网页|端点`);核心 `src/artifact/`;`sys.artifact_kind`;无 `# main` 时 Result 摘要。
- **`ext/web` facade**:`page` · `route` · `serve` · `render` · `inspect` · `use`;子模块 page/route/dom/client/component。
- **`ext/data` · `ext/security` · `ext/net`**:从 monolithic web 拆出 Resource。
- **统一 View** `|type|slot|value|attrs|style|` + ABI `web_render_nodes` / `web_serve_root` / `web_inspect` / `web_app_use`。
- **规则**:`.cursor/rules/web-artifact-no-degrade.mdc`;设计 `doc/design/ext-web-artifact.md`。
### Fixed
- Document `data_source` / `data_where` now drive list cards and detail articles under `web.serve` (ADR 0007 flat metadata).
### Changed
- **破坏性**:删除作者面 `compose_*` / `app.configure` / 作者 `ensure_plugin`。旧 web gold 已移除;新金样 `web-artifact-*` / `ext_web_*`。
- **核心表面 Δ**:**无增删**(复用 Metadata `type`)。
- 修订 `ext-web.md` C1;`doc/next/007.md` superseded。
## v1.1.1 — 2026-09-24
### Highlights
**AI 栈收口(agent + llm)**:语义 `ask`/`stream`/`collect`、Artifact Metadata Binding、Skill Compilation + Adaptive Routing、MCP 客户端与 resume 检查点、可选 `plugins/llm` Transport ABI。
本版 CLI 与扩展包 **同步为 1.1.1**。
- **LLM 原语**:`ext/ai/llm` 从 OpenAI HTTP 客户端提升为 `ask`/`stream`/`collect` 智能原语(`complete` 保留兼容);`LLMResult.tool_calls`;可选原生 `llm_chat_completions`(无 `.so` 时回退 `lib/net`)。
- **Metadata Binding**:frontmatter `${env|arg|sys|secret}` 加载期解析;Phase 2 将绑定键注入入口 env(正文禁止 `${…}`);`sys.meta` / `--bind`;llm ctor 优先 meta。
- **Agent**:Skill Compilation(episode → llm_free skills)+ Adaptive Routing(`marqdo` / `small-llm` / `llm` / `auto`;`jev` 为 `small-llm` 兼容别名);MCP **stdio 客户端**;resume 检查点;零 LLM 金样路径。
- **度量与后端**:`model_turn` usage、named handles(fast/reasoning)、`type:prompt` 加载、openai/ollama 分流。
```bash
# Ubuntu PPA / 源码
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
git checkout v1.1.1 && cargo build --release
marqdo ext add llm && marqdo ext add agent
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime**(Metadata Binding、LLM/agent 插件与扩展)变更,不触碰语言标记。
### Added
- **`ext/ai/llm` 语义表面**:`ask` / `stream` / `collect`(`complete` 兼容);`LLMResult.tool_calls`(OpenAI-shaped `choices[0].message.tool_calls`);`sys.module_source` + 入口文档 `prompt_body` 离线路径。
- **`plugins/llm` Transport ABI**(`llm_chat_completions`):`ext/ai/llm/openai` 优先原生插件,否则 `lib/net` HTTP/SSE。
- **Artifact Metadata Binding**:frontmatter `${env|arg|sys|secret}` → `Module.metadata`;Secret 掩码;`sys.meta` / `--bind`;Phase 2 入口 env 注入(正文拒绝 `${…}`;字节码 prologue 同源)。
- **Agent Skill Compilation + Adaptive Routing**:episode → `maybe_learn` → llm_free skills;路由后端 `marqdo` / `small-llm` / `llm` / `auto`(`jev` = `small-llm` 兼容别名,不再探测 `MARQDO_JEV`)。
- **Agent MCP stdio 客户端**(`agent_mcp_client` / `mcp_connect` / `mcp_client_list` / `mcp_client_call`)+ Python mock 离线金样。
- **Agent resume 检查点**(`.marqdo/agent-resume/<id>.json` — save/load/clear/list;`run` 可设 `resume_id=`)。
- **AI 栈度量与后端**:`model_turn` usage、named handles(fast/reasoning)、`type:prompt` 加载、openai/ollama 分流、agent-zero-llm 金样。
### Fixed
- **plan force 不再冲掉已有 `resources` workbook**(保留 llm_free 资源;金样 `agent-plan-preserve`)。
- **compiled-skill Marqdo 语法**:llm_free await 不再误落到 plan+HTTP。
### Changed
- Adaptive Routing:决策面为 `router_model`(任意 llm handle);`jev` 降为 `small-llm` 文档/兼容别名。
## v1.1.0 — 2026-09-23
### Highlights
Generated
+12 -2
View File
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "marqdo"
version = "1.1.0"
version = "1.5.2"
dependencies = [
"anyhow",
"assert_cmd",
@@ -603,7 +603,7 @@ dependencies = [
[[package]]
name = "marqdo-wasm"
version = "1.1.0"
version = "1.5.2"
dependencies = [
"marqdo",
"serde_json",
@@ -632,6 +632,16 @@ dependencies = [
"serde_json",
]
[[package]]
name = "marqdo_plugin_llm"
version = "0.1.0"
dependencies = [
"idna_adapter",
"serde_json",
"ureq",
"zeroize",
]
[[package]]
name = "marqdo_plugin_quantum"
version = "0.1.0"
+3 -2
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "1.1.0"
version = "1.5.2"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -19,7 +19,7 @@ cli = ["dep:clap"]
view = ["dep:tiny_http"]
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize", "dep:zip"]
plugin-host = ["dep:libloading"]
exec-host = []
exec-host = ["dep:libc"]
fs-host = []
tty = ["dep:libc"]
wasm-core = []
@@ -58,6 +58,7 @@ getrandom = { version = "=0.2.17", default-features = false, features = ["custom
members = [
"plugins/demo",
"plugins/agent",
"plugins/llm",
"plugins/quantum",
"plugins/linalg",
"crates/marqdo-wasm",
+38 -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) · 对象:[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)
语法宪法:[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) · Engineering Knowledge:[engineering-knowledge.md](doc/design/engineering-knowledge.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)
---
@@ -123,6 +123,13 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
```bash
marqdo catalog [PATH] -o OUT_DIR
marqdo sync [PATH] -o OUT_DIR # catalog 的别名
# Engineering Knowledge Compiler(L0–L4 能力目录 / 复用门闩)
marqdo knowledge [PATH] -o OUT_DIR
marqdo find "authentication"
marqdo reuse "implement oauth login"
marqdo duplicate [--fail]
marqdo verify
```
| 参数 | 默认 | 说明 |
@@ -130,7 +137,7 @@ marqdo sync [PATH] -o OUT_DIR # catalog 的别名
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录 |
| `-o` / `--out` | `.marqdo` | 输出目录 |
产物示例:`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)。
`catalog` 成功后默认再跑 EKC(`--no-knowledge` 可关)。产物示例:`catalog.yaml`、`engineering.yaml`、`catalog/capabilities/`、`graph/graph.json`。设计见 [engineering-knowledge.md](doc/design/engineering-knowledge.md) · [catalog-cli.md](doc/design/catalog-cli.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)。
@@ -142,30 +149,44 @@ marqdo catalog public -o .marqdo
---
## 现状(v1.1.0)
## 现状(v1.5.2)
- **AI 原生闭环(v1.1.0 新增)**:核心表面守卫(19 构造,单边改动 CI 必红)· **渐进式契约**(文档内嵌 `参数`/`返回`/`字段` 表 + 四边界校验 + `marqdo check` 防漂移)· **MLSP for AI**(`marqdo mlsp`:`locate`/`syntax`/`validate`/`repair_targets`/`repair_apply`/`schema`,AI 按需查语法而非背诵)· **结构化诊断**(`run --json`,错误即数据);验证见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)
- **外联 v3 P0/P1(v1.5.2)**:raw stdin + 每 cell 独立输入 · plan API · snapshot export/import/replay · `view capture` · Persist 按钮 · 扩展包同步 **1.5.2**
- **view 静态/动态统一 + 外联值传递(v1.5.1)**:静态导出与 live view 共用 `foreign_doc` 执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin;扩展包同步 **1.5.0**
- **裸自增升参(v1.4.6)**:首次粗体赋值左值即声明;`**n = n + 1**` 无反引号也升为必选形参。扩展包仍为 **1.4.5**
- **Streamable HTTP MCP + web invoke 鉴权(v1.4.5)**:`agent_mcp_serve transport=http` · Bearer/`X-Api-Key` 注入 · `unauthorized`→401 · openai/agent `json.get` 硬化
- **LLM 传输软失败 + `ext/ai` 表优先(v1.4.4)**:上游不可达 → `status=error`(不 abort);`agent`/`llm` 去 `json.set` 胶水 · [agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)
- **Ext pack 1.4.3**:修复 `agent.run` cold EFI(`` `self`.preflight `` + miss resolve `llm_free`);已并入 **≥1.4.4** · [agent-run-efi-resolve-bugs-2026-10.md](doc/research/agent-run-efi-resolve-bugs-2026-10.md)
- **Agent/LLM 优化 O1–O5(v1.4.2)**:`ext/ai/sandbox` CoW · `agent.trial` / `sandbox=` · promote sandbox proof · `step_route` / EFI / cost · style lint · quarantine · [ext-ai-optimize.md](doc/roadmap/ext-ai-optimize.md)
- **view 标注连线(v1.4.1)**:underline→chip SVG mid→mid(底边中点→轨道→短竖线→顶边中点)· 帧 chip 共用 id · L→R 密度 · [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)
- **叙述统一 / 公式 meta / 图片自写回(v1.4.0)**:`% marqdo: var=` 块公式绑定 · 臂/循环体叙述与 foreach 中英糖 · `![marqdo-out](…)` 图片自写回 · view 推断形参实值 · [fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.md)
- **view 文档面(v1.3.3)**:Browse Structure 叙述保真 · 标记面 · 分支/循环帧下拉 · AI `#mq-view-trace` · 静态 `view output` / gh-pages 同源 · [view-document-annotations.md](doc/design/view-document-annotations.md)
- **Engineering Knowledge(v1.3.0)**:EKC L0–L4 · `marqdo knowledge|find|reuse|duplicate|verify|…` · Agent `preflight` / REUSE→ADAPT→CREATE · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
- **Web Artifact(v1.2.0 · ADR 0007)**:Document/Endpoint 一等公民(`type: web|endpoint`)· facade `page`/`route`/`serve`/`render`/`inspect`/`use` · Resource 拆到 `ext/data`/`security`/`net` · 统一 View 表 · 破坏性移除 `compose_*`/`configure`
- **AI 栈(v1.1.1)**:`ext/ai/llm` 语义 `ask`/`stream`/`collect` · Artifact Metadata Binding(`${env|arg|sys|secret}`)· Agent Skill Compilation + Adaptive Routing · MCP stdio 客户端 + resume 检查点 · 可选 `plugins/llm` Transport ABI
- **AI 原生闭环(v1.1.0)**:核心表面守卫(19 构造,单边改动 CI 必红)· **渐进式契约**(文档内嵌 `参数`/`返回`/`字段` 表 + 四边界校验 + `marqdo check` 防漂移)· **MLSP for AI**(`marqdo mlsp`:`locate`/`syntax`/`validate`/`repair_targets`/`repair_apply`/`schema`,AI 按需查语法而非背诵)· **结构化诊断**(`run --json`,错误即数据);验证见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)
- 映射与解释器:**v0.3 语法宪法**(`**` 代码 / `*` 返回 / 叙述声明);Phase I 树遍历 + 字节码后端;金样例在 `tests/` 与 `tests/markup-v03/`
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
- **`marqdo view`**:文档浏览器(**文档面** Structure + 标注 / 调用·循环帧 + 函数大纲/搜索 + Execution + Variables 浮窗;`view output` 同构)
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页(默认挂钩 EKC)
- **`marqdo knowledge` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify`**:Engineering Knowledge Compiler([engineering-knowledge.md](doc/design/engineering-knowledge.md))
- **`marqdo version --check`**:与 GitHub 最新 release 对比
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**;**中层 Mid M1–M6** + **Mid2 M7–M10**(datetime/url/toml/html/fs++/stats/log.fields 等,见 [stdlib-mid.md](doc/design/stdlib-mid.md) · [stdlib-mid2.md](doc/design/stdlib-mid2.md))
- **官方扩展库 `ext/`**(**非** stdlib,本版收口):
- **`web`**:W0–W7 + P3 + **W8**;**定制 C0–C4**;**宿主 H1–H2**(`proxy`/`invoke`,见 [ext-hosting.md](doc/roadmap/ext-hosting.md));**表驱动引言**(`compose_intro` / `引言装配`);原生层默认 **Go `libweb`**([ADR 0004](doc/adr/0004-web-plugin-go.md),`scripts/build-web-plugin.sh`);示例 [web-site](examples/web-site/) · [web-site-zh](examples/web-site-zh/) · [marqdo-blog](examples/marqdo-blog/) · [anlian-mq](examples/anlian-mq/);生产路径见 [web-asgi-servers-and-marqdo.md](doc/design/web-asgi-servers-and-marqdo.md)
- **`web`**:**Artifact 模型(ADR [0007](doc/adr/0007-web-document-endpoint.md))** — `type: web|endpoint` Document/Endpoint;facade `page`/`route`/`serve`/`render`/`inspect`/`use`;Resource 在 `ext/data` · `ext/security` · `ext/net`;设计 [ext-web-artifact.md](doc/design/ext-web-artifact.md);原生 **Go `libweb`**([ADR 0004](doc/adr/0004-web-plugin-go.md));示例 [marqdo-blog](examples/marqdo-blog/) · [web-client-site](examples/web-client-site/) · [anlian-mq](examples/anlian-mq/)
- **`quantum`**:Q0–Q7 + Q8a/b 主题 SVG;示例 [quantum-entanglement](examples/quantum-entanglement/)
- **`linalg`**:L0–L6 + 公式文档面(中缀 / `declare` / 展示化简);示例 [linalg-transpose](examples/linalg-transpose/) · [linalg-svd](examples/linalg-svd/) · [linalg-least-squares](examples/linalg-least-squares/)
- **`agent`**:A1–A4 + **MCP Server stdio**(`mcp_server`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md)
- **`llm`**:OpenAI 兼容对话
- **`agent`**:A1–A4 + **MCP Server/Client**(stdio + **Streamable HTTP**)+ Skill Compilation + Adaptive Routing + resume + **Engineering preflight**(`agent.preflight` / `eng_preflight`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md) · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
- **`llm`**:语义 `ask`/`stream`/`collect`(OpenAI/Ollama;可选原生 `plugins/llm`)
- 安装:`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,linalg}`(`web` 为 Go;其余为 Rust)
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum,linalg,llm}`(`web` 为 Go;其余为 Rust)
- **用户静态站**:`public/` → `view output` → CI 发布 [gh-pages](https://cflmy.github.io/marqdo/)
- **VS Code 扩展**:分支 **`vscode-extension`**(`main` 不跟踪源码;见 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md));Release 附带 `.vsix`
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
### 如何使用最新 Marqdo(v1.1.0)
### 如何使用最新 Marqdo(v1.5.2)
**安装解释器(任选其一)**
@@ -180,7 +201,7 @@ marqdo catalog public -o .marqdo
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v1.1.0 # 或留在 main
git checkout v1.5.2 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -193,7 +214,7 @@ marqdo view public --no-open
marqdo debug public --no-open
marqdo catalog public -o .marqdo
# 2b) AI 原生闭环(v1.1.0):契约检查 / 结构化诊断 / MLSP 查询
# 2b) AI 原生闭环(v1.1.0+):契约检查 / 结构化诊断 / MLSP 查询
marqdo check tests/contracts/ok_contract.mq.md # 静态契约防漂移
marqdo run tests/structure/hello.mq.md --json # 结构化诊断(错误即数据)
printf '{"id":1,"method":"syntax","params":{"query":"返回"}}\n' | marqdo mlsp
@@ -203,14 +224,14 @@ marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native(
marqdo ext add agent # 或:智能体
marqdo ext add quantum # 或:量子
marqdo ext add linalg # 或:线性代数
marqdo ext add llm # 或:大模型(纯 .mq.md)
# 开发者:cargo build --release -p marqdo_plugin_{agent,quantum,linalg}
marqdo ext add llm # 或:大模型(.mq.md + 可选 native llm)
# 开发者:cargo build --release -p marqdo_plugin_{agent,quantum,linalg,llm}
# bash ./scripts/build-web-plugin.sh # 需 Go + cgo → libweb
# 离线:解压 Windows zip(已含 ext/native)或手动放下 native zip;MARQDO_EXT_NO_DOWNLOAD=1
# 4) 动态站示例(扩展装好后)
marqdo run examples/web-site-zh/index.mq.md # 表驱动引言 Demo
marqdo run examples/marqdo-blog/index.mq.md
marqdo run examples/marqdo-blog/serve.mq.md
marqdo run examples/anlian-mq/index.mq.md # W-G14 验收站
# 浏览器打开终端打印的 listen 地址;/favicon.ico 与 logo 装配见 W8
@@ -219,7 +240,7 @@ marqdo wasm build
# → dist/wasm/ … 见 examples/browser-hello/
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
# https://github.com/cflmy/marqdo/releases/tag/v1.1.0
# https://github.com/cflmy/marqdo/releases/tag/v1.5.2
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo-wasm"
version = "1.1.0"
version = "1.5.2"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
+106
View File
@@ -1,3 +1,109 @@
marqdo (1.5.2-1ppa1) noble; urgency=medium
* Marqdo 1.5.2: Foreign v3 P0/P1 — raw stdin with per-cell inputs and
interrupt, plan generation/add/remove/value API, snapshot
export/import/replay, view capture for static export, explicit Persist
button, nested plan boundary.
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 15:00:00 +0800
marqdo (1.5.1-1ppa1) noble; urgency=medium
* Marqdo 1.5.1: View static/live execution path unified; foreign value
passing into multi-kernel sessions; cell stdin for live/static/persistent
kernels; build-time execution with stdout injection in static exports;
runnable foreign writeback example; writeback block grouping.
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 22:00:00 +0800
marqdo (1.5.0-1ppa1) noble; urgency=medium
* Marqdo 1.5.0: Foreign kernels v2 (structured invoke, JSON calls,
parallel fan-out, persistent Python/Node kernels, explicit state
bridge) and document-native notebooks in view; high-contrast
light/dark view themes, resizable code/output panes, OKF/EKC and
Python examples on the user site. Fixes branch-local variables
leaking into required constructor parameters.
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 03:30:00 +0800
marqdo (1.4.6-1ppa1) noble; urgency=medium
* Marqdo 1.4.6: Promote a bare self-increment to a required parameter.
The first bold assignment LHS is a declaration (design §8.2); a missing
argument reports missing argument for parameter, not undefined variable.
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 23:56:00 +0800
marqdo (1.4.5-1ppa1) noble; urgency=medium
* Marqdo 1.4.5: Streamable HTTP MCP (agent_mcp_serve transport=http);
web invoke Bearer/X-Api-Key inject + unauthorized→401; openai/agent
field access via json.get (no footnote hard-fail).
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 17:40:00 +0800
marqdo (1.4.4-1ppa1) noble; urgency=medium
* Marqdo 1.4.4: Soft LLM transport errors (structured status=error);
ext/ai table-first refactor (no json.set glue).
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 14:40:00 +0800
marqdo (1.4.2-1ppa1) noble; urgency=medium
* Marqdo 1.4.2: Agent/LLM optimize O1–O5 — sandbox trial opt-in,
promote sandbox proof, step_route/EFI/cost, style lint, quarantine.
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 11:51:05 +0800
marqdo (1.4.1-1ppa1) noble; urgency=medium
* Marqdo 1.4.1: View annot leaders — SVG mid-to-mid (mark bottom-center
to chip top-center), unify frame chip ids, L-to-R chip density.
-- cflmy <pingan@cflmy.cn> Thu, 15 Oct 2026 20:40:00 +0800
marqdo (1.4.0-1ppa1) noble; urgency=medium
* Marqdo 1.4.0: Prose-unified control flow — block formula % marqdo: var=,
arm/loop narrative + foreach sugar, image writeback ![marqdo-out](...),
view inferred-param values; welcome pages on v0.3 prose surface.
-- cflmy <pingan@cflmy.cn> Wed, 15 Oct 2026 15:53:00 +0800
marqdo (1.3.3-1ppa1) noble; urgency=medium
* Marqdo 1.3.3: Browse document-surface Structure — narration-preserving
markers, branch/loop frame pickers, ViewExecutionReport JSON; static
view output / gh-pages share the same render path as live view.
-- cflmy <pingan@cflmy.cn> Wed, 15 Oct 2026 13:20:00 +0800
marqdo (1.3.0-1ppa1) noble; urgency=medium
* Marqdo 1.3.0: Engineering Knowledge Compiler (EKC) — L0–L4 catalog,
marqdo knowledge/find/reuse/duplicate/verify, Agent preflight
(REUSE→ADAPT→CREATE), graph + context packs.
-- cflmy <pingan@cflmy.cn> Mon, 28 Sep 2026 16:50:00 +0800
marqdo (1.2.0-1ppa1) noble; urgency=medium
* Marqdo 1.2.0: Web Artifact rewrite (ADR 0007) — Document/Endpoint/Resource,
type:web|endpoint, web.serve/render/inspect, ext/data|security|net split,
compose_* author surface removed; marqdo-blog Artifact example.
-- cflmy <pingan@cflmy.cn> Mon, 28 Sep 2026 11:39:04 +0800
marqdo (1.1.1-1ppa1) noble; urgency=medium
* Marqdo 1.1.1: AI stack closure — llm ask/stream/collect, Metadata Binding,
Skill Compilation + Adaptive Routing, MCP stdio client + resume checkpoints,
optional plugins/llm Transport ABI (fallback lib/net).
-- cflmy <pingan@cflmy.cn> Thu, 24 Sep 2026 20:32:00 +0800
marqdo (1.1.0-1ppa1) noble; urgency=medium
* Marqdo 1.1.0: core surface guard + progressive contracts + MLSP for AI.
+15 -2
View File
@@ -25,6 +25,7 @@
| [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/okf.md](design/okf.md) | **Marqdo OKF 实现规范**(catalog v0 + 任务知识包) |
| [design/engineering-knowledge.md](design/engineering-knowledge.md) | **Engineering Knowledge Compiler(EKC)**:L0–L4、reuse、EFI |
| [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** |
@@ -47,7 +48,13 @@
| [roadmap/stdlib-mid.md](roadmap/stdlib-mid.md) | **Mid M1–M6 路线(done)** |
| [roadmap/stdlib-mid2.md](roadmap/stdlib-mid2.md) | **Mid2 M7–M10 路线(规划)** |
| [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** |
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** |
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— v1 已落地** |
| [design/foreign-kernel.md](design/foreign-kernel.md) | **外联内核:持久内核 / JSON 桥 / 状态桥 / 安全** |
| [design/notebook-session.md](design/notebook-session.md) | **文档会话:cell / kernel / step / journal / 状态面板** |
| [design/notebook-syntax.md](design/notebook-syntax.md) | **文档原生 notebook 语法:内核表 / 会话表** |
| [research/foreign-notebook-decisions.md](research/foreign-notebook-decisions.md) | **外联 / notebook 决策记录(逐问逐答)** |
| [roadmap/foreign-v2.md](roadmap/foreign-v2.md) | **外联内核 v2 路线(F0–F4)** |
| [roadmap/notebook-session.md](roadmap/notebook-session.md) | **文档会话路线(D0–D5)** |
| [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 循环)** |
@@ -89,10 +96,16 @@
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** |
| [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** |
| [research/ai-agent-sandbox.md](research/ai-agent-sandbox.md) | **AI 扩展沙盒调研**:Wasm / OS / CoW / symlink 对比与 Marqdo 分层推荐 |
| [design/ext-ai-sandbox.md](design/ext-ai-sandbox.md) | **`ext/ai/sandbox` 设计锁定**:CoW · 能力表 · agent ABI(非 stdlib) |
| [roadmap/ext-ai-sandbox.md](roadmap/ext-ai-sandbox.md) | **`ext/ai/sandbox` 实现里程碑** S0–S4 |
| [research/ai-agent-llm-optimize-2026-10.md](research/ai-agent-llm-optimize-2026-10.md) | **2026-10 调研**:代码即文档×OKF×沙盒下的 Agent/LLM 优化与问题分析 |
| [design/ext-ai-optimize.md](design/ext-ai-optimize.md) | **Accepted**:Agent/LLM 优化 O1–O5 locked |
| [roadmap/ext-ai-optimize.md](roadmap/ext-ai-optimize.md) | **O1–O5 实现路线**(沙盒接入→证明晋升→路由/成本→lint→隔离) |
| [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus |
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** |
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** · 后续优化见 [ext-ai-optimize](roadmap/ext-ai-optimize.md) O 波次 |
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
+42
View File
@@ -0,0 +1,42 @@
# ADR 0006:Artifact Metadata Binding(`${…}` 进核心 · Metadata-only)
| | |
|---|---|
| Status | **Accepted** |
| Date | 2026-09-24 |
| Related | [binding.md](../design/binding.md) · [core-surface.md](../design/core-surface.md) · [layers.md](../design/layers.md) · [doc/next/006.md](../next/006.md) |
## Context
- Executable Document 需要声明「依赖哪些外部运行时资源」(模型名、API 密钥、base URL),而不是在 `ext/*` 里各自 `sys.env_get`。
- [doc/next/006.md](../next/006.md) 提出 **Marqdo Binding**(`${namespace.name}`)与 Artifact Metadata 统一解析。
- [layers.md](../design/layers.md):Language 层变更须 ADR;核心构造计数只许持平或下降;默认进 ext。
- 正文插值会与 `$$…$$` 公式面冲突,且会新增内联构造压力。
## Decision
1. 采纳 **Artifact Metadata Binding** 为 Language 层能力;正式规范见 [binding.md](../design/binding.md)。
2. **`${…}` 仅**在文件头 `---` Metadata 中生效;正文 / 粗体 / 调用 / 表 / 叙述 **永不**写 Binding Expression(否决 [006 §17](../next/006.md))。
3. **不**把 Binding 记入 [core-surface.md](../design/core-surface.md) 的 19 构造守卫表——与 `import` 同属 §4「其它语言面」。
4. 核心只做声明与解析;扩展(如 `ext/ai/llm`)消费已绑定的 `Module.metadata` / `sys.meta*` / 入口提升变量。
5. 第一版 namespace:`env` · `arg` · `sys` · `secret`。`config` / `file` 推迟。
6. 加载期一次 resolve → Bound Artifact;`Value::Secret` 遮掩展示;`sys.env_get` 保留为逃逸口。
7. **Phase 2**:入口执行前把 metadata 键提升为普通变量(形参/赋值可覆盖);正文用 `` `model` ``,不再 `${env…}`。
## Consequences
### Positive
- 配置成为文档的一部分;LLM / agent / 其它 ext 共用同一套 Binding,避免各写一套 getenv。
- 缺失 `!` 在加载期失败,而不是运行到 HTTP 401。
- 不膨胀 CORE_CONSTRUCTS;与公式 `$$` 无冲突。
- 正文保持普通变量语义,不引入第二套环境变量语法。
### Negative / Risks
- Secret 在 `Text + Secret` 拼接时会揭示明文(供 Authorization);须约束日志面。
- metadata 键与业务变量同名时依赖「形参/赋值覆盖」规则,作者需注意命名。
### Neutral
- `#` / `##` / `**` / `*` 等核心标记不变;frontmatter `import` 句法不变。
+54
View File
@@ -0,0 +1,54 @@
# ADR 0007:Web Document / Endpoint / Resource(破坏性 · 代码即文档)
| | |
|---|---|
| Status | **Accepted** |
| Date | 2026-09-28 |
| Related | [ext-web-artifact.md](../design/ext-web-artifact.md) · [ext-web.md](../design/ext-web.md) · [binding.md](../design/binding.md) · ADR [0006](0006-artifact-metadata-binding.md) · [layers.md](../design/layers.md) · [doc/next/007.md](../next/007.md) |
## Context
- [`ext/web/web.mq.md`](../../ext/web/web.mq.md) 已膨胀为小型 Web Framework(Page God Object、`configure` 垃圾抽屉、碎片 Table DSL、隐式路由),与 Marqdo「代码即文档」冲突。
- [doc/next/007.md](../next/007.md) 提出 Document / Endpoint / Resource 三原语与拆分 `ext/web` · `ext/net` · `ext/data` · `ext/security`。
- 现行 [ext-web.md](../design/ext-web.md) **C1** 禁止为 web 改核心;Document/Endpoint 装载识别需要 Language/Runtime 参与(复用 Artifact Metadata `type`,**不**新增 CORE_CONSTRUCTS 标记)。
- Binding(ADR 0006)已提供文件级 Metadata;`type: prompt` 先例在扩展侧消费 metadata。
## Decision
1. **采纳** Document / Endpoint / Resource 为 Web 模型一等公民;正式规范见 [ext-web-artifact.md](../design/ext-web-artifact.md)。
2. **修订 ext-web C1**:允许核心在装载期识别 `type: web|endpoint`(及中文 `类型: 网页|端点`)并暴露 artifact 分类;**装配 / HTTP / DB 语义仍在 ext + plugin**。单元格求值、import 句法、CORE_CONSTRUCTS 计数不变。
3. **文件级 Artifact only**:不在 `##` 函数体嵌套 `---` frontmatter(与 Binding Phase 1 / 解析器一致)。
4. **破坏性重写作者面**:删除 `compose_*` 碎片 DSL、god `# page` 变异堆、`app.configure` 多参数抽屉、作者 `ensure_plugin`;examples 与 `tests/ext/web*` 同步重写。
5. **目录定稿**(007 §三十五 + §四十):
- `ext/web/` — page · route · component · dom · client · facade
- `ext/net/` — http · websocket · url
- `ext/data/` — db · cache · storage
- `ext/security/` — auth · oidc · rbac
6. **统一 View 表**:`| type | slot | value | attrs | style |`;Table = Data,禁止每函数私有方言。
7. **declared vs system routes**:用户 route 须声明;`/_part` · `/_form` 等为 system,经 `web.inspect` 可见。
8. **import = capability**:`import web:…` 由 facade 自动加载 native plugin;作者程序不写 `ensure_plugin` / `host_*`。
9. **Metadata v1 锁定(原 007 未决项)**:
- 发现:`web.serve root=` 扫描 `root/**/*.mq.md`,仅注册 `type`/`类型` ∈ {web,网页,endpoint,端点} 的文件;无 type 的库文件忽略。
- Data:仅 flat 键 `data_source` · `data_order` · `data_where`(text;where 为 `col=val` 逗号分隔)。嵌套 YAML `data:` 推迟。
- Result:`{ok: bool, value: any, error: text|None}`。
- Realtime 模块名:`ext/net/websocket.mq.md`(ZH:`实时.mq.md`)。
- ZH metadata:`类型`←type,`路由`←route,`方法`←method,`路径`←path,`请求`←request,`响应`←response,`鉴权`←auth,`数据源`←data_source,`排序`←data_order,`条件`←data_where。
## Consequences
### Positive
- `.mq.md` 同时是文档、路由、实现与鉴权声明。
- 与 LLM/Agent Artifact Metadata 统一心智。
- 职责边界清晰,可独立演化 data/security/net。
### Negative / Risks
- 破坏性:全部现有 web 作者程序与 smokes 必须改写。
- Endpoint 热路径仍经 plugin → `CallLibPath` / 文件装载回调;须保持 ABI 稳定演进。
- flat data 键表达力弱于嵌套 YAML;后续另 ADR。
### Neutral
- 不新增 Markdown 核心标记;`${…}` 仍仅 Metadata。
- Go `plugins/web` 可分波删除死 compose ABI;作者面先断。
+186
View File
@@ -0,0 +1,186 @@
# Marqdo Binding · Artifact Metadata
| | |
|---|---|
| 状态 | **Accepted · Phase 1 + Phase 2(scope lift)** |
| 日期 | 2026-09-24 |
| ADR | [0006-artifact-metadata-binding.md](../adr/0006-artifact-metadata-binding.md) |
| 讨论稿 | [doc/next/006.md](../next/006.md) |
| 实现 | `src/binding/` · `Module.metadata` · entry env lift · `sys.meta` / `sys.meta_get` · `marqdo run --bind` |
> **边界**:核心负责「声明与解析配置」;扩展负责「解释配置的语义」。
> **`${…}` 只出现在文件头 Artifact Metadata**——正文 / 粗体 / 调用 / 表 **永不**写 `${env…}`(否决讨论稿 §17)。正文使用已绑定的普通名字。
---
## 1. Artifact Metadata
文件开头成对 `---` 之间为 **Artifact Metadata**(声明式元信息环境),不是「随便贴的 YAML」。
```text
.mq.md
├── Metadata ← Identity / Configuration / Dependencies / Bindings
└── Executable Body
```
- `import bind:…` / `导入` 行:模块依赖(既有语义不变)。
- 其它 `key: value` 行:元信息;值可为字面量或 **Binding Expression**。
- Phase 1 仅支持 **flat** 键(同级 `key: value`);块标量 `>` / `|` 收成 Text。
例:
```yaml
---
title: demo
type: llm
model: ${env.OPENAI_MODEL ?? "gpt-4o-mini"}
api_key: ${secret.OPENAI_API_KEY!}
base_url: ${env.OPENAI_BASE_URL ?? "https://api.openai.com/v1"}
import sys:lib/sys.mq.md
---
```
加载后内部为已绑定的 `Module.metadata`(确定性快照),执行期不再对同一键反复 `getenv`。
---
## 2. Binding Expression
外形:
```text
${expression}
```
### 2.1 路径
```text
${namespace.name}
```
| Namespace | 意义 | Phase 1 |
|-----------|------|---------|
| `env` | 进程环境变量 | ✅ |
| `arg` | CLI / Runtime 绑定(`marqdo run --bind KEY=VALUE`) | ✅ |
| `sys` | 系统信息:`cwd` · `platform` | ✅ |
| `secret` | 敏感环境变量 → `Value::Secret` | ✅ |
| `config` | 配置 Artifact | 推迟 |
| `file` | 外部文件内容 | 推迟 |
### 2.2 默认与必需
```text
${env.OPENAI_MODEL ?? "gpt-4o-mini"}
${secret.OPENAI_API_KEY!}
```
- `A ?? B`:A 缺失(未设置 / 空)则用 B。
- `A!`:A 必须存在,否则加载失败(`config.required_binding_missing`)。
### 2.3 类型转换
```text
${int(env.MAX_TOKENS ?? "4096")}
${float(env.TEMPERATURE ?? "0.2")}
${bool(env.STREAM ?? "false")}
```
### 2.4 独占 value vs 插值
| 形态 | 语义 |
|------|------|
| `model: ${env.OPENAI_MODEL}` | **Value binding** — 保留解析后的类型(含 Secret) |
| `title: "Hello ${env.USER}"` | **Interpolation** — 结果为 Text |
| `model: gpt-4o-mini` | **Literal** — 字面量;**不会**被环境变量静默覆盖 |
---
## 3. Resolution Policy
对每个 metadata 键:
1. 解析该键的字面量 / Binding / 插值(字面量定稿后不受 env 覆盖)。
2. 若 CLI 提供了同名 `--bind KEY=VALUE`,**覆盖**该键的最终值(Text)。
3. Binding 内部查找顺序(仅当表达式写出时):`arg` / `env` / `secret` / `sys` 按表达式 namespace;`??` 链从左到右。
推荐作者意图:
```text
CLI --bind
→ Artifact 字面量 / 已写死的 Binding 结果
→ Binding 源(env / secret / …)
→ ?? 默认
```
---
## 4. Secret
`${secret.NAME}` → `Value::Secret`。
- `print` / `str` / Display → `<secret>`(不泄露)。
- `type` → `secret`。
- 与 Text 拼接(如 `bearer + api_key`)时**揭示**明文,供 HTTP Authorization。
- 不得进入普通 episode / 错误信息明文(扩展作者责任;核心 Display 已遮掩)。
---
## 5. Runtime API
| API | 语义 |
|-----|------|
| `sys.meta` / `系统.元信息` | 入口模块已绑定 metadata(map) |
| `sys.meta_get` / `系统.取元信息` | `key=` → 值或 `None` |
| `marqdo run FILE --bind KEY=VALUE` | 可重复;写入 `arg` 并覆盖同名 metadata 键 |
| `sys.env_get` | **保留**逃逸口;新代码优先 Metadata Binding |
---
## 6. 错误
| code | 何时 |
|------|------|
| `config.required_binding_missing` | `${ns.name!}` 且源缺失 |
| `config.unknown_binding_ns` | 未知 namespace |
| `config.bad_binding` | 表达式非法 / cast 失败 |
诊断尽量带 frontmatter 行号。
---
## 7. 与扩展的分工
- **核心**:解析 Metadata、resolve Binding、暴露 `Module.metadata` / `sys.meta*`,并在入口把 metadata **提升为普通变量**。
- **`ext/ai/llm`**:构造次序为 **显式实参 → 入口作用域同名变量 / `sys.meta_get` → `sys.env_get` 回退 → 默认**。
---
## 8. Phase 2 · Metadata scope lift(Accepted)
加载期绑定完成后,入口执行(`# main` 或唯一无参顶层对象)前,把 `Module.metadata` 的每个键注入 entry 环境,成为**普通变量**:
```yaml
---
model: ${env.ModelName ?? "gpt-4o-mini"}
---
```
```marqdo
# main
> print text=`model`
```
### 规则
1. 注入时机:进入入口函数之前。
2. 冲突:形参 / 调用实参 **覆盖** 同名 metadata;程序内赋值亦然。metadata **不**覆盖已存在的绑定。
3. `sys.meta` / `sys.meta_get` 仍可用(显式通道)。
4. **拒绝** 正文 / 粗体 / 表 / 叙述中的 `${…}`(讨论稿 006 §17 否决)。普通语言也不在语句里 `${ENV}`。
### 仍推迟(P3+)
- `config` / `file` namespace
- 嵌套 YAML map
- 显式 `override:` 糖
- 计入 `CORE_CONSTRUCTS`
+5
View File
@@ -23,15 +23,20 @@ YAML / OKF 风格清单是**从 `.mq.md` 派生的生成物**,不是手写配
marqdo catalog [PATH] -o OUT_DIR
# 别名(与早期草案一致)
marqdo sync [PATH] -o OUT_DIR
# 跳过 Engineering Knowledge 投影(仅旧式 catalog)
marqdo catalog [PATH] -o OUT_DIR --no-knowledge
```
| 参数 | 默认 | 说明 |
|------|------|------|
| `PATH` | `.` | 工程根或含 `.mq.md` 的目录(递归扫描) |
| `-o` / `--out` | `.marqdo` | 生成目录(写入前创建;**覆盖**同名生成文件;扫描时跳过该目录) |
| `--no-knowledge` | off | 不跑 EKC;默认在 catalog 成功后编译 L0–L4 / graph |
退出码:成功 0;无可扫描文件或 IO/解析失败非 0(单文件解析失败时写入 `diagnostics` 并继续其余文件,最终若有失败则非 0)。
Engineering Knowledge 命令见 [engineering-knowledge.md](engineering-knowledge.md)(`find` / `reuse` / `duplicate` / …)。
---
## 3. 生成物
+1 -1
View File
@@ -44,4 +44,4 @@
## 4. 范围外(进 Language 层,但不在本守卫)
frontmatter YAML(元信息)与 `import` 行(模块装载)属于 Language 层的其它语言面,随 [layers.md](layers.md) 准入流程登记,暂不进本清单守卫;如需一并守卫,走 ADR 扩表。
frontmatter / Artifact Metadata(元信息)、`import` 行(模块装载)、以及 Metadata 内的 **Binding Expression**(`${ns.name}`,见 [binding.md](binding.md) · [ADR 0006](../adr/0006-artifact-metadata-binding.md))属于 Language 层的其它语言面,随 [layers.md](layers.md) 准入流程登记,**暂不进本清单守卫**(不增 CORE_CONSTRUCTS 计数)。Phase 2 将已绑定 metadata **提升为入口普通变量**(仍非新标记)。如需一并守卫,走 ADR 扩表。
+97
View File
@@ -0,0 +1,97 @@
# Engineering Knowledge Compiler(EKC)
| | |
|---|---|
| 状态 | **Accepted(v1 已落地)** |
| 日期 | 2026-09-28 |
| 提案 | [next/008.md](../next/008.md) |
| 相关 | [okf.md](okf.md) · [catalog-cli.md](catalog-cli.md) · [ext-agent.md](ext-agent.md) |
## 1. 定位
Marqdo 把仓库投影为 **可查询、可验证、可复用** 的工程知识系统。Source of Truth 仍是 `*.mq.md`;`.marqdo/**` 是 GENERATED 投影。
```text
.mq.md ──► EKC ──► Executable + Catalog L0–L4 + Graph + Context Pack
│
▼
Agent preflight (REUSE → ADAPT → CREATE)
```
**Engineering First Information (EFI)**:生成代码前先获得已有能力、约束、决策、失败经验与推荐复用。
## 2. 五层 Catalog
| 层 | 内容 | 落盘 |
|----|------|------|
| L0 Repository | 语言/规模 | `.marqdo/catalog/repository.mq.md` |
| L1 Module | imports/exports/responsibility | `.marqdo/catalog/modules/` |
| L2 Symbol | signature/calls/fingerprint | `.marqdo/catalog/symbols/` |
| L3 Capability | 工程能做什么 | `.marqdo/catalog/capabilities/` |
| L4 Knowledge | Decision/Constraint/Failure/… | `.marqdo/knowledge/{decisions,constraints,…}/` |
既有 `marqdo catalog` 根级 `catalog.yaml` / `index.md` / `modules/` / `concepts/` **保留**;`catalog` 成功后默认再跑 EKC(`--no-knowledge` 可关)。
## 3. 知识类型(OKF `type`)
| type | 含义 |
|------|------|
| `Capability` / `Function` | 能力与符号投影 |
| `Decision` | 为什么这样做 |
| `Constraint` | 必须/禁止 |
| `Failure` / `AntiPattern` | 负面知识 |
| `Pattern` / `Migration` / `Fact` | 模式、迁移、事实 |
| `Marqdo Context Pack` | Agent 上下文制品 |
| `Marqdo Policy` | 复用决议编译结果 |
| `Marqdo Engineering Knowledge` | 总览 / `engineering.yaml` |
未知 type 优雅降级(可读,不专属逻辑)。
## 4. 图边
`implements` · `uses` · `depends_on` · `tested_by` · `documented_by` · `constrained_by` · `decided_by` · `supersedes` · `conflicts_with` · `deprecated_by` · `derived_from` · `failed_by` · `related_to`
落盘:`.marqdo/graph/graph.json` · `edges.json` · `index.json`。
## 5. CLI
```bash
marqdo knowledge [PATH] -o .marqdo # compile(默认)
marqdo knowledge preflight "task"
marqdo knowledge record REUSE
marqdo knowledge learn --task ... --failure ...
marqdo find "authentication"
marqdo reuse "implement oauth login"
marqdo impact path/to/file.mq.md
marqdo conflicts | stale | duplicate [--fail] | verify
```
统一 `--json`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
## 6. Reuse 协议
三态:**REUSE → ADAPT → CREATE**(硬顺序)。Reuse budget:`min_candidates` / `allow_create_after`。仅 `create_allowed: true` 时允许盲生成。
## 7. Context Pack
`.marqdo/agent/contexts/task-<id>.mq.md`:Task / Existing Capabilities / APIs / Constraints / Decisions / Failures / Recommended / Forbidden。
## 8. Agent
- Plugin:`agent_eng_preflight` / `agent_eng_reuse` / `agent_eng_record`
- Facade:`agent.preflight` · `agent.eng_reuse` · `agent.eng_record`
- `agent.plan … eng_preflight=True` 在 agent-kb 之前跑 EFI;缺知识图时 `missing_knowledge` 放行(兼容纯 agent-kb 测试)
## 9. 指标
`.marqdo/agent/episodes/reuse_metrics.json`:`reuse_ratio` / `adapt_ratio` / `novel_ratio` / `duplication_rate`。
## 10. 原则(五条)
1. Discover before Create
2. Reuse before Adapt
3. Adapt before Duplicate
4. Verify before Promote
5. Code changes update knowledge
**不做**:以向量库为知识模型;embedding 仅可选检索实现,默认关闭。Hybrid = lexical + symbol + capability + graph。
+19 -3
View File
@@ -4,7 +4,7 @@
|---|---|
| Status | **Accepted · redesign**(取代「thin TOOL: loop」方案) |
| Date | 2026-08-07 |
| Related | [ext-llm.md](ext-llm.md) · [ext-cli.md](ext-cli.md) · [ext-abi.md](ext-abi.md) · [**ext-agent-plan.md**](ext-agent-plan.md)(**多步锁定设计**) · [**ext-agent-parent.md**](ext-agent-parent.md)(**父 Plan-and-Move**) · [**okf.md**](okf.md)(**OKF / 任务知识包**) · [**调研:主流框架与 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) |
| 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 / 任务知识包**) · [**engineering-knowledge.md**](engineering-knowledge.md)(**EKC / EFI preflight**) · [**调研:主流框架与 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. 为什么要改掉旧方案
@@ -167,8 +167,9 @@ ext/
**分层纪律(硬规则,勿破)**:
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 等标准库底层。
2. Agent 专属能力(含 OKF agent-kb:`agent_goal_sig` / `agent_kb_lookup` / `agent_kb_promote` / …;以及 EKC:`agent_eng_preflight` / `agent_eng_reuse` / `agent_eng_record`)只进 **`plugins/agent` 注册名**,由 `ext/ai/agent` 在 `plugin.load` 后调用。
3. **禁止**向 `src/host/`(`HostFn` 表)添加 agent / OKF / EKC 领域原语,以免核心包体膨胀。通用 L0.5 仅保留 fs/json/subtask 等标准库底层。
4. **Engineering preflight**:`agent.preflight` / `plan … eng_preflight=True` 在 agent-kb 之前解析 REUSE/ADAPT/CREATE(见 [engineering-knowledge.md](engineering-knowledge.md))。缺 `.marqdo` 知识图时返回 `missing_knowledge` 并放行,以兼容纯任务包测试。
4. 进程退出用 `sys.exit` / `系统.退出`,不用裸 `exit`。
官方 `ext/ai/` 用 `lib/*` 包装或插件注册名;见 [module-namespace.md](module-namespace.md) §8 · [ext-abi.md](ext-abi.md)。
@@ -180,11 +181,26 @@ ext/
| 中文 | 英文 | 角色 |
|------|------|------|
| `# 智能体` | `# agent` | 构造:`大模型`/`model`,`工具`/`tools`,可选 `站立提示`/`standing` |
| `## 运行` | `## run` | **v2 主入口**:Adaptive `route` → execute → record episode → maybe_learn(技能 + 策略) |
| `## 单步` | `## step` | 原子执行;注入源码 + 位置;可选工具;返回结构化 map;**默认自动写回**(`写回=` / `writeback=` 可关) |
| `## 多步` | `## plan` | 建/续工作簿 → subtask 跑文件 → 修订循环 → 汇总(见 [ext-agent-plan.md](ext-agent-plan.md)) |
| `## 解析` | `## resolve` | 技能解析:exact → alias → canonical → near |
| `## 路由` | `## route` | **P4 Adaptive Routing**:`marqdo` \| `small-llm` \| `llm` \| `auto`(`jev` 为 `small-llm` 兼容别名) |
| `## 应用路由` | `## route_apply` | 将小模型/大模型路由回复(`SKILL:<slug>` / `EXPLORE`)落到 kb 技能 |
| `## 编译策略` | `## compile_policy` | Policy Compilation → `policies/router.mq.md` |
| `## 记录情景` | `## record_episode` | 每次执行沉淀为 `.mq.md` episode(`.marqdo/agent-memory/`) |
| `## 尝试学习` | `## maybe_learn` | 情景足够时归纳 → 合成 → 编译技能,并尝试编译策略 |
| `## 编译` | `## compile` | 候选技能 → 版本化 `skills/<slug>/vN.mq.md` + 可选 OKF promote |
| `## 指标` | `## metrics` | Reasoning amortization(`avg_llm_calls` / `compiled_runs`) |
| `## 分解` | `## decompose` |(可公开或内部)目标 → 子任务表 |
| `## 清空历史` | `## clear_history` | 若仍保留会话式辅助状态则清空;**不以隐藏 chat 袋为真相源**——真相在文档写回 |
**Skill Compilation(v2)**:Agent 的记忆不是向量袋,而是可执行 `.mq.md`。路径:`episodes/` → `experiences/` → `candidates/` → `skills/vN.mq.md` → OKF `agent-kb`(`llm_free`)。编译技能正文为合法 Marqdo(`**result = …**` + 斜体返回);金样 `tests/ext/agent-zero-llm.mq.md` 验收 policy+skill 全路径 `execution.llm_calls=0`。`plan` 对已存在的 `resources/<slug>.mq.md` **不覆盖**(`agent-plan-preserve`)。
**LLM 成本**:`model_turn` 走 `model.ask` / `stream`+`collect`,把 `LLMResult.tokens` 写入 episode / `execution`。
**Adaptive Routing(P4)**:Router 是抽象能力,backend = `marqdo`(已编译 `policies/router.mq.md`)/ `small-llm`(`router_model` 任意 llm 句柄)/ `llm` / `auto` 级联。`jev` 仅为 `small-llm` 兼容别名,**不进入框架专属设计**。热路径在 **`plugins/agent`**(`route.rs`);**禁止**向 `src/host/` 加领域原语。设计:[doc/next/003.md](../next/003.md) · [doc/next/004.md](../next/004.md)。
构造参数(v1):
| 参数 | 说明 |
+142
View File
@@ -0,0 +1,142 @@
# 方案:智能体 / 大模型优化方向(代码即文档 · OKF · 沙盒)
| | |
|---|---|
| 状态 | **Accepted · O1–O5 locked** |
| 日期 | 2026-10-16 |
| 调研 | [ai-agent-llm-optimize-2026-10.md](../research/ai-agent-llm-optimize-2026-10.md) |
| 路线 | [ext-ai-optimize.md](../roadmap/ext-ai-optimize.md) |
| 相关 | [ext-ai-sandbox.md](ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [okf.md](okf.md) · [engineering-knowledge.md](engineering-knowledge.md) · [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) · [ai-stack.md](../roadmap/ai-stack.md) |
---
## 0. 方案立场
1. **强化差异化**:可执行 `.mq.md` 为权威;OKF 为复用;沙盒为证明;LLM 为探索。
2. **不向隐藏 TOOL: 循环 / 向量权威回退。**
3. 下列方向均为**可行**;推荐波次见 §3,最终裁剪由你选型。
4. **不改** `doc/next/*`;落地时另开 roadmap 切片。
---
## 1. 架构愿景(闭环)
```text
目标 / 任务
│
▼
EFI / OKF lookup ──hit──► llm_free / marqdo 执行 ──► writeback
│ miss
▼
small-llm 路由 / 父分解
│
▼
生成或修补 .mq.md(代码即文档风格)
│
▼
sandbox.open → sandbox.run(caps)→ diff
│
├─ 失败 → writeback error / 隔离,不 promote
└─ 成功 → 人审或策略 → commit → solidify / OKF promote
│
▼
下次 REUSE(降本)
```
---
## 2. 可行方向全集
每个方向标注:解决的问题(Pn)、依赖、风险、粗粒度成本。
### A. 沙盒 × Agent 闭环
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|----|------|------|--------|------|------|------|
| **A1** | `step`/`plan` 默认经 sandbox 试跑再写实树 | P1 | 生成落 upper;绿才 `commit` | sandbox | 破坏现有金样默认 | 中 |
| **A2** | Promote / solidify 强制 sandbox proof | P1 | OKF 写入前要求 proof fixture 绿 | sandbox+OKF | 过严挡复用 | 中 |
| **A3** | Sandbox profile 表(caps 宣告) | P1/P3 | GFM 表声明 net/plugin/fs | sandbox | 表方言膨胀 | 低 |
| **A4** | Guest 风格门禁(表优先、禁 json 胶水) | P5 | commit 前 lint / preflight | sandbox+parser | 误杀合法 json.parse | 中 |
| **A5** | 会话 diff → view 审阅卡 | P1/P4 | HITL 看 CoW diff | view+sandbox | UI 工时 | 中高 |
| **A6** | 多会话并行 CoW(fan-out 实验) | — | 每假设一 session | sandbox | 隔离/合并复杂 | 高 |
### B. OKF / EKC / 技能层
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|----|------|------|--------|------|------|------|
| **B1** | OKF 技能元数据:适用条件 / fixtures / sandbox_profile | P2 | frontmatter + 目录约定 | okf | 与 catalog 字段冲突 | 中 |
| **B2** | Progressive disclosure(索引轻、正文按需 READ) | P2/P6 | 对齐 Anthropic Skills 层级 | agent A3 | 实现重复 | 中 |
| **B3** | Skill Lift 评测(有/无技能配对) | P4 | harness 指标 | B1 评测 | 样本少噪声大 | 中 |
| **B4** | 失败技能隔离(quarantine)+ 回归用例跟随血缘 | P1 | ForgeAgent 式 | OKF | 状态机复杂 | 中高 |
| **B5** | near-match / soft_match 产品化默认开 | P6 | 已有 roadmap | okf-near | 误复用 | 低中 |
| **B6** | EKC preflight 默认硬门槛(REUSE→ADAPT→CREATE) | P6 | step 前强制 EFI | EKC | 拖慢探索 | 中 |
| **B7** | Capability 包与 `llm_free` 资源双向链接 | P2 | catalog L3↔任务包 | EKC+OKF | 图维护 | 中 |
### C. 大模型 / 路由 / 成本
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|----|------|------|--------|------|------|------|
| **C1** | 步骤级路由(lookup / patch / sandbox_run / net) | P3 | 扩展 route policy 表 | routing | 策略过拟合 | 中 |
| **C2** | 总成本计量(含推理 token 膨胀)写回文档 | P7 | usage→writeback/metrics | llm result | 噪声 | 低中 |
| **C3** | 用强模型「反思」优化 standing / policy `.mq.md`(类 GEPA) | P3/P5 | 离线优化环,产物仍是文件 | llm | 需评测集 | 高 |
| **C4** | 高频 OKF 技能蒸馏/微调小模型(编译进权重) | — | 长期研究 | 数据+算力 | 运维重;偏离「源码权威」 | 很高 |
| **C5** | Named model 绑定任务类型(fast=路由,reasoning=分解) | P3 | 已有 named handles 加深 | llm | 配置漂移 | 低 |
| **C6** | Prompt document 强制:无参 ask 必须来自 type:prompt 文件 | P5 | 硬化 005 | llm | 破坏脚本式调用 | 低 |
### D. 代码即文档(产出质量)
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|----|------|------|--------|------|------|------|
| **D1** | 官方「可读 Marqdo」Skill 强化(表/链接取元/禁混名) | P5 | skills/marqdo 加厚 | skill | 模型仍违规 | 低 |
| **D2** | AST/结构 lint:json.set 链、混 EN/ZH API | P5 | `marqdo lint` 或 sandbox 钩子 | parser | 误报 | 中 |
| **D3** | 工作簿补丁只允许表驱动 / 命名槽写回 | P5 | 收紧 A0 补丁面 | agent | 表达力下降 | 中 |
| **D4** | 示例库:sandbox+OKF+表风格 canonical demos | P4/P5 | examples/ | 文档 | 维护 | 低 |
### E. 评测与产品化
| ID | 方向 | 解决 | 做什么 | 依赖 | 风险 | 成本 |
|----|------|------|--------|------|------|------|
| **E1** | 完成 Wave B1 harness(constitution / writeback / call_site) | P4 | 已规划 | agent | — | 中 |
| **E2** | 指标面板:ReuseRate / ProofRate / TokenCost | P4/P7 | metrics 写回或 catalog | agent | 虚荣指标 | 中 |
| **E3** | Live 金样矩阵(sandbox 开/关 × 路由后端) | P4 | CI optional | CI | flaky | 中 |
| **E4** | 教程:「只读一份 .mq.md 理解 Agent」 | — | doc/tutorial | 文档 | — | 低 |
### F. 明确不优先 / 需单独论证
| ID | 方向 | 理由 |
|----|------|------|
| **F1** | 第二套 Agent Framework(Python/TS 对象图权威) | 违宪 |
| **F2** | 向量库升为记忆权威 | 违宪;可作证据工具 |
| **F3** | 默认通用 shell Agent | 与 Marqdo-only 沙盒战略冲突 |
| **F4** | 整库 `ext/web` 进默认沙盒 | 已否决 |
| **F5** | 人人 microVM 本地默认 | DX 过重;留给 hosted |
---
## 3. 执行顺序(O1→O5 locked)
| 波次 | 方向组合 | 为何先做 |
|------|----------|----------|
| **O1** | A1 轻量(opt-in `sandbox=True`)+ A3 + D1 + D4 | 立刻接上刚落地的沙盒,风险可控 |
| **O2** | A2 + B1 + B3 + E1 | 验证→晋升→可度量 Skill Lift |
| **O3** | C1 + C2 + B6 | 降本与 EFI 硬门槛 |
| **O4** | A4 + D2 + A5 | 质量门禁与人审 |
| **O5** | B4 + C3 | 失败隔离与离线提示优化 |
| **O∞** | C4 / A6 | 研究项,单独立项 |
切片实现见 [ext-ai-optimize.md](../roadmap/ext-ai-optimize.md)。
---
## 4. 验收原则(任一波次)
- 金样:有/无沙盒、有/无 OKF hit、路由后端切换。
- 指标:至少报告 ReuseRate 或 TokenCost 之一相对基线变化。
- 文档:`.mq.md` 示例仍可读为 Markdown(表/链接取元,少 json 胶水)。
- 红线:不改 `doc/next/*`;ext 不调 `host_*`。
---
## 5. 落地
O1–O5 已锁定;实现见 [roadmap/ext-ai-optimize.md](../roadmap/ext-ai-optimize.md)。**仍不改** `doc/next/*`。
+104
View File
@@ -0,0 +1,104 @@
# Official AI sandbox (`ext/ai/sandbox`)
| | |
|---|---|
| Status | **Accepted · implementing** |
| Date | 2026-10-16 |
| Related | [research/ai-agent-sandbox.md](../research/ai-agent-sandbox.md) · [roadmap/ext-ai-sandbox.md](../roadmap/ext-ai-sandbox.md) · [ext-agent.md](ext-agent.md) · [ext-abi.md](ext-abi.md) · [browser-marqdo-wasm.md](browser-marqdo-wasm.md) · [ai-stack.md](../roadmap/ai-stack.md) · [stdlib-writeback.md](stdlib-writeback.md) |
---
## 0. One-liner
**Agent-only Marqdo trial runtime:** capability-isomorphic to browser Wasm defaults, CoW workspace until explicit `commit`, author surface under `ext/ai` (not stdlib).
---
## 1. Goals / non-goals
### Goals
| # | Goal |
|---|------|
| G1 | Open a CoW session over a workspace root; edits stay in upper until `commit` |
| G2 | `run` executes `.mq.md` (or in-memory source) under deny-by-default caps with core `lib/*` usable |
| G3 | `diff` / `discard` / `inspect` for review gates |
| G4 | Stable `unavailable in sandbox` for plugin.load, exec foreign/subtask path|code|lang, net (default), `ext/web` server APIs |
| G5 | Author API in `ext/ai/sandbox` via `plugins/agent` — **no** public `lib/sandbox` |
### Non-goals (this wave)
| # | Non-goal |
|---|----------|
| N1 | Embed wasmtime in CLI |
| N2 | True Wasm ABI plugins (linalg/quantum) |
| N3 | bwrap / microVM |
| N4 | Full `ext/web` listen/DB/WS inside sandbox |
| N5 | Symlink-forest workspace isolation |
| N6 | Default host-proxy of all native ABI plugins |
| N7 | Wire `agent.step`/`plan` through sandbox automatically (later) |
---
## 2. Layering
```text
ext/ai/sandbox.mq.md → plugin.load agent → sandbox_* ABI
↓ host_query
HostContext + CowSession
(fs / writeback see upper)
```
| Layer | May call `host_*` | Role |
|-------|-------------------|------|
| `ext/ai/sandbox` | **No** | Author facade |
| `plugins/agent` | via `host_query` only | Register `sandbox_*`; forward to host |
| `src/host` | — | CoW session store; fs/writeback intercept; nested `run` |
---
## 3. Author API
EN: `ext/ai/sandbox.mq.md` · ZH: `ext/ai/沙盒.mq.md` (separate files, no mixed names in one module).
| Method | Params | Result |
|--------|--------|--------|
| `open` | optional `root=` (default entry dir / cwd) | map `{ id, root }` |
| `write` | `id=`, `path=`, `text=` | none |
| `read` | `id=`, `path=` | text |
| `remove` | `id=`, `path=` | none (whiteout) |
| `diff` | `id=` | list of `{ path, kind: write\|remove }` |
| `commit` | `id=` | `{ ok, applied }` |
| `discard` | `id=` | `{ ok }` |
| `run` | `id=`, `path=` **or** `source=` | `{ ok, value, stdout?, error? }` |
| `inspect` | `id=` | caps, root, change count, notes |
Default `run` caps: `fs_write=true` (CoW only), `exec=false`, `net=false`, `plugin=false`.
---
## 4. CoW semantics
- **lower** = real workspace root (read-through).
- **upper** = session map path → bytes.
- **whiteout** = logical deletes; reads miss; commit unlinks lower.
- No symlink-as-isolation; resolve paths under root; reject `..` escape.
- Until `commit`, host tree unchanged (verifiable with `git status` / file mtime).
---
## 5. Hard bans
1. No public `lib/sandbox`.
2. No symlink forest as the isolation story.
3. No silent success when capability missing — diagnose `unavailable in sandbox`.
4. `ext/**` must not call `host_*`.
5. Do not treat empty `# main` as sandbox completeness.
---
## 6. ABI / host_query
Plugin exports (registered on agent plugin): `sandbox_open`, `sandbox_write`, `sandbox_read`, `sandbox_remove`, `sandbox_diff`, `sandbox_commit`, `sandbox_discard`, `sandbox_run`, `sandbox_inspect`.
Implementation: each forwards to allowlisted `host_query` names of the same stem (e.g. `sandbox_open`), which mutate the process-local CoW store and (for `run`) invoke nested capture with a sandboxed `HostContext`.
+74 -51
View File
@@ -2,13 +2,21 @@
| | |
|---|---|
| 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) |
| Status | **Accepted · v0.3 semantic**(005:Intelligence Primitive) |
| Date | 2026-09-24 |
| Related | [objects.md](objects.md) · [ext-agent.md](ext-agent.md) · [ext-cli.md](ext-cli.md) · [ai-stack.md](../roadmap/ai-stack.md) · [doc/next/005.md](../next/005.md) |
## Scope
`ext/ai/` holds **official LLM + agent** extensions. Import paths:
`ext/ai/llm` is Marqdo’s **intelligence primitive**, not an OpenAI SDK wrapper.
```text
Author surface: ask / stream / collect / create / fast / reasoning / prompt_load
Transport: ext/ai/llm/openai.mq.md (+ ollama defaults)
Compat: complete / chat
```
Import:
```markdown
---
@@ -16,70 +24,85 @@ 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)
## Public API
| 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` / `打印增量` |
| `## load_env` | `## 加载环境` | Load `.env` |
| `## create` | `## 创建` | Factory → LLM handle |
| `## fast` / `## reasoning` | `## 快速` / `## 推理` | Named handles |
| `## prompt_load` / `## prompt` / `## prompt_body` | `## 加载提示` / `## 提示` / `## 提示正文` | Prompt artifacts (`type: prompt` → body) |
| `## ask` (module) | `## 提问` | Convenience → **text** (`prompt=` or `path=`) |
| `## collect` | `## 收集` | Events → text |
| `## stream_result` | `## 流式结果` | Alias of `collect` |
| `# llm` | `# 大模型` | Handle ctor (`backend=` openai-compatible \| ollama) |
| `## ask` (method) | `## 提问` | → **LLMResult** map |
| `## stream` | `## 流式` | → event list |
| `## complete` / `## chat` | `## 运行` / `## 聊天` | Compat / transport primitive |
### Preferred
```markdown
---
import llm:ext/ai/llm.mq.md
---
**answer = > llm.ask prompt="What is Marqdo?"**
*answer*
# main
**model = > llm.create**
**result = > `model`.ask prompt=`prompt`**
*[text](result)*
> load_env
**fast = > llm.fast**
**events = > `fast`.stream prompt=`prompt`**
**text = > llm.collect events=`events`**
*`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*
**body = > llm.prompt path="fixtures/prompt-marqdo.md"**
**body2 = > llm.prompt text=`raw`**
```
Environment (create a **project-local** `.env`; do not commit secrets):
### LLMResult
| Field | Meaning |
|-------|---------|
| `text` | Answer string |
| `model` | Model id |
| `finish` | Finish reason (`stop`, …) |
| `backend` | e.g. `openai-compatible` / `ollama` |
| `usage` | `{prompt_tokens,completion_tokens,total_tokens}` |
| `tokens` | Alias of `usage.total_tokens` (agent metrics) |
| `name` | Optional handle tag (`fast` / `reasoning`) |
| `llm_calls` | `1` per ask |
| `tool_calls` | List of OpenAI-shaped tool call objects (empty when none) |
### Compat
`complete` / `chat` still return a bare string (or event list when `stream=True`) so `ext/ai/agent` and older runbooks keep working. **New code should use `ask` / `stream` / `collect`.**
## Environment
```env
OPENAI_API_KEY=sk-...
OPENAI_BASE_URL=https://api.openai.com/v1
OPENAI_MODEL=gpt-4o-mini
MARQDO_LLM_FAST_MODEL=...
MARQDO_LLM_REASONING_MODEL=...
OLLAMA_HOST=http://127.0.0.1:11434/v1
```
Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`.
Fallbacks: `MARQDO_LLM_API_KEY`, `MARQDO_LLM_BASE_URL`, `MARQDO_LLM_MODEL`. Ctor also accepts `api_key=` / `base_url=` / `model=` / `backend=`.
## Backends
| `backend=` | Module | Notes |
|------------|--------|-------|
| `openai-compatible` (default) | `ext/ai/llm/openai.mq.md` | Chat Completions HTTP + SSE |
| `ollama` | defaults in ctor + same transport | Key defaults to `ollama`; host from `OLLAMA_HOST` |
## 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`)
- `tests/ext/llm-import.mq.md`
- `tests/ext/llm-ctor-offline.mq.md`
- `tests/ext/llm-ask-offline.mq.md` (create + collect)
- `tests/ext/llm-stream-offline.mq.md`
- `tests/ext/llm-named-offline.mq.md` (fast/reasoning + prompt_load)
- `tests/ext/llm-tool-calls-offline.mq.md` (`tool_calls_from` / Result field)
- `tests/ext/llm-meta-offline.mq.md` · `llm-entry-prompt-offline.mq.md`
- Live: `llm-complete.mq.md` · `llm-stream-live.mq.md`
+197
View File
@@ -0,0 +1,197 @@
# 官方扩展:Web Artifact(Document / Endpoint / Resource)
| | |
|---|---|
| 状态 | **Accepted · 破坏性(取代 page/app God Object 作者面)** |
| 日期 | 2026-09-28 |
| ADR | [0007-web-document-endpoint.md](../adr/0007-web-document-endpoint.md) |
| 讨论稿 | [doc/next/007.md](../next/007.md)(superseded) |
| 安装 | `marqdo ext add web`(`web` / `网页`) |
| 相关 | [binding.md](binding.md) · [ext-web.md](ext-web.md) · [stdlib-i18n.md](stdlib-i18n.md) · [layers.md](layers.md) |
---
## 0. 一句话
> **Document describes the page. Table describes the data. Endpoint describes the interaction. Metadata describes the runtime. Marqdo executes all of them.**
---
## 1. 三原语
| Artifact | Metadata `type` / `类型` | 含义 |
|----------|--------------------------|------|
| **Document** | `web` / `网页` | Markdown 正文 + View → HTML;`route`/`路由` 注册 declared HTTP |
| **Endpoint** | `endpoint` / `端点` | 可执行正文为 handler;`path`+`method` 注册 API |
| **Resource** | (绑定/导入) | `ext/data` · `ext/security` · 未来 LLM 等,经 metadata / import 声明 |
核心装载识别 `type`/`类型`(见 `src/artifact/`);渲染与 listen 在 `ext/web` + `plugins/web`。
---
## 2. 目录
```text
ext/web/
web.mq.md · 网页.mq.md # facade: page route serve render inspect
page.mq.md · route.mq.md · component.mq.md · dom.mq.md · client.mq.md
ext/net/ http.mq.md · websocket.mq.md · url.mq.md
ext/data/ db.mq.md · cache.mq.md · storage.mq.md
ext/security/ auth.mq.md · oidc.mq.md · rbac.mq.md
```
作者入口通常:
```text
site/
index.mq.md # type: web · route: / · 或 # main → web.serve
pages/*.mq.md # type: web
api/*.mq.md # type: endpoint
data/ # sqlite runtime (gitignore)
```
---
## 3. Document(`type: web`)
```markdown
---
type: web
title: Marqdo Blog
route: /
method: GET
data_source: posts
data_order: -created_at
import web:ext/web/web.mq.md
import data:ext/data/db.mq.md
---
# Marqdo
Welcome to the executable web.
```
| 键 (EN) | 键 (ZH) | 说明 |
|---------|---------|------|
| `type` | `类型` | `web` / `网页` |
| `route` | `路由` | 路径,可含 `{param}` |
| `method` | `方法` | 默认 `GET` |
| `title` | `标题` | 文档标题 / `<title>` |
| `data_source` | `数据源` | 表名 |
| `data_order` | `排序` | 如 `-created_at` |
| `data_where` | `条件` | `col=val,col2=val2` |
正文 Markdown 经 `dom` 变为 DOM Artifact,再 `web.render`。可选 View 表:
```markdown
`nodes` =
| type | slot | value | attrs | style |
|------|------|-------|-------|-------|
| text | kicker | AI Native | | eyebrow |
| title | title | Marqdo | | title |
```
`page.render nodes=` 是**唯一**主装配路径。禁止 `compose_main` / `compose_intro` 等碎片 DSL。
---
## 4. Endpoint(`type: endpoint`)
```markdown
---
type: endpoint
method: POST
path: /api/posts
request: json
response: json
auth: member
import data:ext/data/db.mq.md
---
**post = > data.db.insert …**
*post*
```
| 键 (EN) | 键 (ZH) | 说明 |
|---------|---------|------|
| `type` | `类型` | `endpoint` / `端点` |
| `path` | `路径` | URL |
| `method` | `方法` | GET/POST/… |
| `request` | `请求` | `json` / `form` / `none` |
| `response` | `响应` | `json` / `text` / `html` / `sse`(`text/event-stream`) |
| `auth` | `鉴权` | 角色名或 `none`;`bearer` / `api_key` = 不要求 cookie,把 `Authorization` / `X-Api-Key` 注入 payload 由 `# main` 校验 |
正文在请求时执行;返回值按 `response` 序列化。Result 协议见 §8。
**Handler 约定(锁定)**:Endpoint 文件用 `# main` 作为请求处理器。请求体/query/path 参数经 `run_artifact` 以 Metadata Binding 覆盖注入(与 `--bind` 同源),正文用已提升的普通变量名。无 `# main` 时返回 Artifact Result 摘要(`ok`/`value`/`error`),适合作文档型 ping。
---
## 5. Facade API(EN / ZH)
| EN | ZH | 作用 |
|----|-----|------|
| `web.page` | `网页.页面` | 从 metadata/正文/nodes 构造 Document 句柄 |
| `web.route` | `网页.路由` | 注册 declared Document 或 Endpoint |
| `web.serve` | `网页.服务` | `root=` 扫描注册 + listen |
| `web.render` | `网页.渲染` | Document → HTML(离线/预览) |
| `web.inspect` | `网页.检视` | `{declared, system}` 路由表 |
Middleware 一等:`web.use` / `route.use`,表驱动;**禁止** `configure(cors, security, …)` 垃圾抽屉。
---
## 6. 发现算法(锁定)
`web.serve root=DIR host=… port=…`:
1. 递归枚举 `DIR` 下 `*.mq.md`(跳过 `data/`、隐藏目录、`node_modules`)。
2. 解析文件头 Metadata;无 `type`/`类型` 或非 web/endpoint → 跳过。
3. Document → declared route(缺 `route` 则相对 `root` 的路径映射,`index.mq.md` → `/`)。
4. Endpoint → declared path+method(`path`/`路径` 必需)。
5. System routes(`/_part/*`、`/_form/*`、静态等)由 runtime 挂载,仅出现在 `inspect.system`。
6. 调用 native listen。
---
## 7. Table 规则
- **View**:仅 `|type|slot|value|attrs|style|`(及列名 ZH 别名:`类型|槽|值|属性|样式`)。
- **Resource schema**:`|字段|类型|可空|` 等 — 专用且文档化,不是函数私有方言。
- **禁止** `|属性|值|样式|` / `|front|back|css|` / `|组件|样式|` 作为页面主装配(已删除)。
- Raw HTML/CSS = escape hatch(`dom.raw` / `page.css`),不是默认语言。
---
## 8. Result
所有易失败的 Resource / Endpoint 边界返回 map:
| 键 | 类型 | 说明 |
|----|------|------|
| `ok` | bool | 成功 |
| `value` | any | 成功载荷 |
| `error` | text \| None | 失败信息 |
---
## 9. 硬约束(取代旧 C1–C7 作者面)
| # | 约束 |
|---|------|
| A1 | Document/Endpoint 由核心识别 `type`;装配在 ext(ADR 0007) |
| A2 | 禁止 `json.set` 袋胶水;Table = Data |
| A3 | 中英分文件;同文件禁止混 API |
| A4 | 禁止作者 `ensure_plugin` / `host_*` |
| A5 | 禁止隐式用户 route;system 须 `inspect` 可见 |
| A6 | 禁止恢复 `compose_*` / `app.configure` / god page 变异堆 |
| A7 | 能力只许迁移/提升;删除须本设计明示 + tests 同步 |
| A8 | 设计未锁定处停工提问,禁止自行发明 DSL |
---
## 10. 与旧 ext-web.md
旧「页面表 + compose_* + app.route」作者面 **废止**。历史能力矩阵见 [web-net-capabilities.md](web-net-capabilities.md);迁移后以本文件与 ADR 0007 为准。
+17 -13
View File
@@ -2,18 +2,21 @@
| | |
|---|---|
| 状态 | **Accepted · W0–W7 + P3 + W8(站点图标/Head/图片装配)完结**(SQLite/Postgres 作者面:页面装配 / db CRUD+`where` / form / 嵌入主区 / `app.route` / 路由 `/_part` / admin UI / RBAC / 上传相册 / SEO·RSS·sitemap / **favicon·头资源·图片装配**;Postgres 等见 §9) |
| 日期 | 2026-08-11(W8:2026-08-29;请求上下文:2026-09-18) |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [stdlib-i18n.md](stdlib-i18n.md) · [web-assets-and-images.md](web-assets-and-images.md) · **[ext-web-request-context.md](ext-web-request-context.md)** |
| 状态 | **Superseded(作者面)· 历史能力档案** — 现行作者面见 **[ext-web-artifact.md](ext-web-artifact.md)** · ADR [0007](../adr/0007-web-document-endpoint.md) |
| 日期 | 2026-08-11(W8:2026-08-29;请求上下文:2026-09-18;Artifact 重构:2026-09-28) |
| 相关 | [ext-web-artifact.md](ext-web-artifact.md) · [markdown-mapping.md](markdown-mapping.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [stdlib-i18n.md](stdlib-i18n.md) · [web-assets-and-images.md](web-assets-and-images.md) · **[ext-web-request-context.md](ext-web-request-context.md)** |
| 安装(目标) | `marqdo ext add web`(中英:`web` / `网页`) |
| 本文目的 | 锁定**作者面**与**类 API**;指导实现 |
| 本文目的 | **历史**类 API 与能力矩阵;新站请勿按本文 `compose_*` / `app.configure` 写作 |
> **2026-09-28**:作者面迁移到 Document / Endpoint / Resource。C1 已由 ADR 0007 修订。下文保留作迁移对照,**不是**现行推荐 API。
---
## 0. 一句话
`ext/web` 用 **GFM 表格 + Marqdo 类方法** 描述动态网站:表仍是字典/列表嵌套;类方法把表装配成可渲染页面。
**不改 Marqdo 核心语法**;扩展库存在的理由,正是让「文档即代码」在网站场景下成立。
**现行**:`.mq.md` Artifact(`type: web|endpoint`)描述页面与交互;见 [ext-web-artifact.md](ext-web-artifact.md)。
**历史(废止)**:`ext/web` 曾用 GFM 表格 + `# page`/`# app` 类方法拼装站点。该模型因 God Object / 碎片 DSL / 隐式路由被破坏性替换。
---
@@ -41,13 +44,14 @@
| # | 约束 |
|---|------|
| 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 者)评审通过后**删除或清空后重写**;禁止在旧代码上打补丁演进。**落实**:原生层 Go 全量重写见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md);作者面 ABI 名保持兼容 |
| C6 | `# db` / `# 数据库` 必须提供完整**增删改查**;列表查询英文方法名为 **`select`**(中文 **`查询`**);后台 `/admin` 与表单提交走同一套写库 API |
| C7 | 用户输入经 `# form` / `# 表单`:字段表 + 校验表;**服务端校验必须在写库前执行**(见 §5.5) |
| C1 | **修订(ADR 0007)**:核心可识别 Artifact `type: web\|endpoint`(及 ZH);**不**新增 CORE_CONSTRUCTS 标记;单元格求值 / import 句法不变;装配语义仍在 ext + plugin。旧文「禁止为 web 改核心」作废 |
| C2 | 作者面**禁止** `json.parse` / `json.set` 袋胶水(现行见 ext-web-artifact A2) |
| C3 | 中英分文件;同文件禁止混 API(现行 A3) |
| C4 | **废止**「页面表 + compose」心智 → Document Artifact + `pages/` · `api/` |
| C5 | 破坏性重写作者面(ADR 0007);原生 Go 演进见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md) |
| C6 | DB 迁至 **`ext/data`**;CRUD 仍须完整(`select` / `查询`) |
| C7 | 表单校验仍须在写库前执行;挂载经 declared Endpoint / system `/_form`(inspect 可见) |
| A1–A8 | **现行硬约束**见 [ext-web-artifact.md](ext-web-artifact.md) §9 |
---
@@ -0,0 +1,60 @@
# 块公式元数据绑定 · 控制流叙述统一
| | |
|---|---|
| 状态 | Active |
| 日期 | 2026-10-15 |
| 相关 | [stdlib-math.md](stdlib-math.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
---
## 1. 块公式 `% marqdo: var=`
在 `$$…$$` 块内用 **TeX 行注释**声明绑定名(渲染通常不可见;运行时剥离后解析公式体):
```markdown
$$
% marqdo: var=f
x^2 - 2
$$
```
- 指令:`% marqdo:` + 空白 + `var=<ident>`;未知键 → Error。
- 可无前置 `` `f` = ``;若同时写空 RHS 与 `var=`,**同名允许、异名 Error**。
- **保留**旧空 RHS + 后随 `$$`。
- **不做**:行内 `$% marqdo:…$`;\`\`\` 代码围栏内语言注释 meta(本波)。
- 行内公式继续传统绑定:`` `g` = $x+1$ ``(单 `$…$` → `formula`)或 `` `g` = $$x+1$$ ``。
无名叙述区 `$$` 仍仅展示;可执行区裸块既无空 RHS 又无 `var=` → Error。
---
## 2. 臂 / 循环体叙述(与函数体同权)
`parse_indented_body` 与函数体相同:消费 `` `名` `` / `**代码**` / `*返回*`;纯叙述跳过。
斜体返回结束**当前臂或当前循环体**,不结束外层函数。
---
## 3. 循环头
| 面 | 写法 | 说明 |
|----|------|------|
| **推荐** | `- [项](xs)` / `- [`项`](`xs`)` | 支持嵌套 |
| 中文糖 | `- 对`xs`的每一项`项`` | 可选后缀「遍历」 |
| 英文糖 | `- for each `item` in `xs`` | 大小写不敏感 `for each` / `in` |
糖与链接头语义相同,可混用嵌套。
---
## 4. 分支条件行叙述
结构行仍以 `1.` / `2.` 开头。条件提取顺序:
1. 整段可解析为表达式(现状);
2. 行内粗体代码条件 `**`n` > 0**`;
3. 剥离「当/若/如果/when/if」与「时/则」后,将「大于/小于/等于…」映射为运算符再解析。
else:`N. *`(可夹「否则」等叙述,条件位仍为 `*`)。
禁止无标记自然语言整句当条件。
+449
View File
@@ -0,0 +1,449 @@
# 外联内核(Foreign Kernel)
| | |
|---|---|
| 状态 | **F0–F3.5 已实现** |
| 日期 | 2026-10-17 |
| 层 | Runtime(`src/foreign/` · `src/host/foreign*` · `lib/foreign.mq.md`) |
| 相关 | [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [notebook-syntax.md](notebook-syntax.md) · [notebook-session.md](notebook-session.md) · [stdlib-foreign.md](stdlib-foreign.md) · [stdlib-subtask.md](stdlib-subtask.md) |
| 核心表面 Δ | 无 |
> 外联内核 = 一个长期存活的外部语言进程 + 生命周期 + 类型桥 + 记录。它既能被 `marqdo run` 里的显式调用使用,也能被 view 的 notebook 会话使用。
---
## 1. 定位与边界
### 1.1 负责
- 解释器发现、注册、配置、探测。
- 一次性执行:临时脚本、stdin/stdout/stderr、超时、输出上限。
- 持久内核:启动、求值、状态、关闭、列表。
- 状态桥:`session_set` / `session_get` / `session_names`。
- JSON 值桥:Marqdo `Value` ↔ JSON。
- 结构化记录:`ok/code/stdout/stderr/ms/timed_out/truncated/result/error`。
- 安全:`exec` 门禁、`cwd` 沙箱、进程组、并发/输出上限。
- 视图诊断:代码卡片 Run 的完整结果。
### 1.2 不负责
- 文档语法(`内核表` / `会话表`)→ [notebook-syntax.md](notebook-syntax.md)。
- 文档会话 / cell 顺序 / journal / view UI → [notebook-session.md](notebook-session.md)。
- Foreign → Marqdo 函数回调(v2 不做)。
- 依赖安装(pip/npm)。
- 远程 / 容器执行。
### 1.3 与相邻模块的区别
| 模块 | 生命周期 | 用途 |
|---|---|---|
| `foreign` | 一次性或持久 | 调外部语言;状态可选 |
| `subtask` | 一次性并发 | 后台任务、文件子任务、函数子任务 |
| `plugin` | 进程内 | 原生 C ABI 扩展 |
| `writeback` | 文档级 | 把输出写回 `.mq.md` |
`subtask` 不管理持久状态;`foreign` 不管理文档执行顺序。
---
## 1.4 实施状态(2026-10-17)
| 阶段 | 状态 | 关键文件 |
|---|---|---|
| F0 安全执行 / `invoke` 记录 | ✅ | `src/host/foreign.rs` |
| F1 预设 / probe / register / config | ✅ | `src/foreign/registry.rs` · `src/host/foreign.rs` |
| F2 JSON 桥 / run_many / call_many | ✅ | `src/host/foreign.rs` |
| F3 Python/Node 持久内核 | ✅ | `src/host/foreign_session.rs` |
| F3.5 session_set/get/names | ✅ | 同上 |
| F4 history / view 打磨 / 发布 | 部分 | — |
测试:`cargo test --lib foreign`(11+)、`cargo test --test gold lib_foreign`(12,python 条件跳过)、`tests/notebook/shared.mq.md` 手工 view 验证。
---
## 2. 语言与内核模型
### 2.1 语言预设
| lang | 别名 | 默认命令 | 扩展名 | 版本探测 | 会话 |
|---|---|---|---|---|---|
| `python` | `python3`, `py` | `python3`(Windows `python`) | `.py` | `--version` | ✅ |
| `node` | `javascript`, `js` | `node` | `.js` | `-v` | ✅ |
| `deno` | — | `deno run` | `.ts` | `--version` | ❌ |
| `bun` | — | `bun` | `.js` | `--version` | ❌ |
| `ruby` | — | `ruby` | `.rb` | `--version` | ❌ |
| `perl` | — | `perl` | `.pl` | `--version` | ❌ |
| `php` | — | `php -r {inline}` | `.php` | `--version` | ❌ |
| `lua` | — | `lua` | `.lua` | `-v` | ❌ |
| `r` | `rscript` | `Rscript` | `.R` | `--version` | ❌ |
| `julia` | — | `julia` | `.jl` | `--version` | ❌ |
| `go` | — | `go run {file}` | `.go` | `version` | ❌ |
| `bash` | `sh`, `shell` | `bash` | `.sh` | `--version` | ❌ |
| `powershell` | `pwsh`, `ps1` | `pwsh`(Windows `powershell`) | `.ps1` | `--version` | ❌ |
| `sqlite` | `sqlite3` | `sqlite3` | `.sql` | `--version` | ❌ |
| `tsx` | `typescript` | `tsx` | `.ts` | `--version` | ❌ |
说明:
- 预设只是默认值;注册 / 配置 / 环境变量整体覆盖。
- 会话能力首批只有 Python / Node;其它语言一次性执行。
- `php` 用 `{inline}`,围栏里直接写 PHP,不需要 `<?php`。
- `deno` 默认不给权限;需要时通过配置追加 `--allow-*`。
### 2.2 解析优先级
从高到低:
1. 调用级 `cmd`(整行 argv,shell-like 切分)+ `args`(追加)。
2. 进程内注册:`register` / `set_cmd`。
3. 环境变量 `MARQDO_FOREIGN_<LANG>`(整行或 JSON 数组)。
4. 项目配置 `.marqdo/foreign.toml` / `MARQDO_FOREIGN_CONFIG`。
5. 内置预设。
6. 都没有 → 带修复建议的诊断。
Python 额外发现顺序(在预设层内):
1. `VIRTUAL_ENV/bin/python`(Windows `Scripts/python.exe`);
2. `<cwd>/.venv` / `venv` / `env`;
3. 入口目录与 `fs_root` 向上查找;
4. PATH 的 `python3` / `python`。
`MARQDO_FOREIGN_NO_VENV=1` 关闭 venv 探测;显式 `cmd` / `set_cmd` / `MARQDO_FOREIGN_PYTHON` 优先。
相对路径:配置里的 `cmd` 相对配置目录;注册 / `set_cmd` / 环境变量里的 `cmd` 相对 `cwd`。
### 2.3 注册与模板
`register(lang, cmd?, args?, template?, ext?, env?, version_args?)`。
模板占位符:
| 占位符 | 展开 |
|---|---|
| `{file}` | 临时脚本绝对路径 |
| `{dir}` | 临时目录 |
| `{base}` | 脚本文件名 |
| `{inline}` | 源码作为一个 argv;不写临时文件 |
| `{lang}` | 语言 id |
| `{cwd}` | 实际工作目录 |
规则:
- `cmd` 与 `template` 至少一个;都给 → 报错。
- `{file}` 与 `{inline}` 不能同时出现。
- 都没有时自动追加 `{file}`。
- `{inline}` 超过 60 KiB → 报错并建议 `{file}`。
- 模板不做 shell 转义;需要 shell 时显式写 `bash -c`,路径由引擎生成(安全字符)。
配置示例:
```toml
[python]
cmd = ".venv/bin/python"
args = ["-u"]
[go]
template = ["go", "run", "{file}"]
[rust]
template = ["bash", "-c", "rustc -O {file} -o {dir}/main && {dir}/main"]
[php]
template = ["php", "-r", "{inline}"]
```
---
## 3. 一次性执行
### 3.1 API
| 英文 | 中文 | 形参 | 结果 |
|---|---|---|---|
| `run` | `运行` | `code`, 可选 `stdin` `env` `cwd` `timeout` `args` `max_output` | stdout 文本(v1 兼容) |
| `run_lang` | `按语言运行` | `lang`, `source`, 可选同上 | stdout 文本 |
| `invoke` | `执行` | 可选 `code` / `lang`+`source` / `stdin` / `input` / `env` / `cwd` / `timeout` / `args` / `output` / `max_output` / `cmd` / `keep` / `cache` | 记录 map |
| `call` | `调用` | 可选 `code` / `lang`+`source` / `input` / `stdin` / `env` / `cwd` / `timeout` / `args` | 解析后的 JSON 值 |
| `run_many` | `批量运行` | `runs`, 可选 `concurrency` | 记录列表 |
| `call_many` | `批量调用` | `inputs`, 可选 `code` / `lang`+`source` / `cmd` / `env` / `cwd` / `timeout` / `args` / `max_output` / `concurrency` | 结果值列表 |
### 3.2 记录结构
`invoke` / `run_many` / `session_eval` 共用:
| 键 | 类型 | 含义 |
|---|---|---|
| `ok` | Bool | exit=0 且未超时 |
| `code` | Int | 退出码;未启动 / kill → -1 |
| `stdout` | Text | 原始 stdout(可能截断) |
| `stderr` | Text | 原始 stderr(可能截断) |
| `ms` | Int | 墙钟毫秒 |
| `lang` | Text | 实际语言 |
| `cmd` | Text | 实际 argv |
| `timed_out` | Bool | 是否超时 |
| `truncated` | Bool | stdout/stderr 是否截断 |
| `result` | 任意 / None | 按 `output` 解析 |
| `result_error` | Text | json 解析失败原因 |
| `error` | Text | 启动 / 超时 / 策略原因 |
| `script` | Text | `keep=True` 的脚本路径 |
| `cached` | Bool | 缓存命中(P4) |
`session_eval` 额外:`id`、`alive`。
### 3.3 输出模式
| `output=` | `result` |
|---|---|
| `auto`(默认) | 尝试 JSON;失败 → None |
| `text` | None |
| `json` | 解析;失败 → `result_error` |
| `lines` | 行列表 |
| `bytes` | stdout 原始字节的 base64 |
`call` 固定 JSON:空 stdout → None;非空非法 JSON → 错误。
### 3.4 失败语义
- `run` / `call`:执行失败 → `Err`;错误包含语言、argv、退出码、stderr(截 4 KiB)、stdout 头。
- `invoke` / `run_many`:执行失败 → 记录;只有参数非法 / 策略拒绝 → `Err`。
- 输出过大:截断 + `truncated=true`,不再 OOM / 报错。
---
## 4. JSON 状态桥
### 4.1 值映射
| Marqdo | JSON |
|---|---|
| None | null |
| Bool | bool |
| Int | number |
| Num | number(NaN/Inf → null) |
| Text | string |
| List | array |
| Map | object |
| Formula | 矩阵 → 二维数组;其它 → 数字或字符串 |
| Code | 源码字符串 |
| Secret | JSON 中 `<secret>`;`env` 显式交付时取真实值 |
### 4.2 输入
- `input=` → JSON;写 stdin;同时提供 `MARQDO_INPUT`(≤8 KiB)与 `MARQDO_INPUT_FILE`(任意大小)。
- `stdin=` 文本与 `input=` 互斥。
- 都不给 → stdin EOF。
- 大输入走文件,避免环境变量大小限制。
### 4.3 输出
- `result` 按 `output` 解析。
- 原始 stdout/stderr 始终保留(截断到上限)。
- `call` 返回解析值;`invoke` 返回记录。
### 4.4 类型限制
v2 是**值拷贝**,不是对象引用:
- Python DataFrame / NumPy / Node 对象 → 需要先 `to_dict` / `to_json` / `JSON.stringify`。
- 大对象传输成本高;后续考虑 Arrow / Parquet / 文件句柄。
- Secret 不默认进入 JSON;需要 env 显式交付。
---
## 5. 持久内核与会话
### 5.1 API
| 英文 | 中文 | 形参 | 结果 |
|---|---|---|---|
| `session_open` | `会话开启` | `lang`, 可选 `cmd` `env` `cwd` `timeout` | 会话 id(Text) |
| `session_eval` | `会话求值` | `id`, 可选 `code` / `source` / `input` / `timeout` | 记录(含 id/alive) |
| `session_set` | `会话设值` | `id`, `name`, `value` | None |
| `session_get` | `会话取值` | `id`, `name` | JSON 值 / None |
| `session_names` | `会话变量` | `id` | 名称列表 |
| `session_close` | `会话关闭` | `id` | Bool |
| `session_list` | `会话表` | — | map 列表 |
### 5.2 支持语言
| 语言 | 方式 |
|---|---|
| python | `python3 -u -c <bootstrap>` |
| node | `node -e <bootstrap>` |
| 其它 | 报错:`lang=… has no session bootstrap; use run/invoke` |
### 5.3 线路协议
stdin 每行一个 JSON 请求;原始 stdout 每行一个 JSON 响应:
```json
{"id":1,"code":"x = 41","input":null}
{"id":2,"code":"x + 1","input":null}
```
```json
{"id":1,"ok":true,"stdout":"","stderr":"","result":null,"error":""}
{"id":2,"ok":true,"stdout":"","stderr":"","result":42,"error":""}
```
- 同一会话严格串行:等到匹配响应后才发下一条。
- 响应单行;JSON 转义换行。
- 崩溃 / EOF → `alive=false`,会话移除。
- 超时 → kill 会话(状态不可信)。
### 5.4 Python bootstrap
- 保留原始 `sys.stdout` 写协议;用户输出用 `redirect_stdout/stderr` 捕获。
- `ast.parse`:最后一条是表达式 → 先 exec 前面,再 eval 最后,作为 result。
- 异常 → `traceback.format_exc(limit=8)`,`ok=false`;会话继续。
- `input` → 全局 `marqdo_input`。
- 不可序列化 → `default=str`。
### 5.5 Node bootstrap
- 保存原始 `process.stdout.write` 写协议。
- eval 期间替换 `console.*` 与 `process.stdout/stderr.write`;结束后恢复。
- `vm.runInThisContext` 保留全局状态;`require` 挂到 `globalThis`。
- Promise → await;顶层 await 需用户包 `(async()=>{…})()`。
- 序列化失败 → `String(result)`。
### 5.6 状态桥
- `session_set`:值 → JSON → 请求 `{"set": name, "value": ...}` 或执行一段赋值。
- `session_get`:请求 `{"get": name}` → JSON → Marqdo Value。
- `session_names`:请求变量名列表。
- 与 `session_eval` 同一线路协议;严格串行。
- 名称必须是合法标识符;保留名(`marqdo_input` 等)另行文档。
### 5.7 生命周期
- id 为 `s1`、`s2`…。
- 每会话独立进程、cwd、env。
- `HostContext` drop → 全部 kill + wait。
- `subtask` 不继承会话。
- 不跨文档共享。
---
## 6. 环境契约
| 变量 | 值 |
|---|---|
| `MARQDO_FOREIGN` | `1` |
| `MARQDO_FOREIGN_LANG` | 语言 id |
| `MARQDO_FOREIGN_SCRIPT` | 脚本路径(文件模式) |
| `MARQDO_FOREIGN_DIR` | 脚本目录 |
| `MARQDO_FOREIGN_CWD` | 实际 cwd |
| `MARQDO_ENTRY` | 入口 `.mq.md` 路径 |
| `MARQDO_ENTRY_DIR` | 入口目录 |
| `MARQDO_INPUT` | input JSON(≤8 KiB) |
| `MARQDO_INPUT_FILE` | input JSON 文件(任意大小) |
语言默认:
- Python:`PYTHONUNBUFFERED=1`、`PYTHONIOENCODING=utf-8`、`PYTHONUTF8=1`;`PYTHONPATH` 前插 cwd。
- Node:`NODE_PATH` 前插 cwd(可选)。
`env` 是 map;值 `as_display()`;Secret 取真实值(显式交付)。不主动清空父环境。
---
## 7. 临时文件与 cwd
- 默认 `<cwd>/.marqdo/tmp/foreign-<pid>-<nanos>/`;不可写 → 系统临时目录。
- `MARQDO_FOREIGN_TMPDIR` 覆盖。
- 脚本 `main.<ext>`;Python 加 utf-8 声明。
- 默认 cwd = 入口目录;调用级 cwd 经 `resolve_path` + `fs_root` 校验。
- 成功/失败/超时都清理;`keep=True` 保留并回填 `script`。
- Node 相对 `require('./x')` 相对脚本目录;需要项目相对路径时用 `MARQDO_FOREIGN_CWD` 或 `{inline}` 模板。
---
## 8. 超时、IO、进程组
- `timeout`:秒,可小数;默认 10s;上限 3600s;`<=0` 报错。
- 超时 kill 进程组:
- Unix:`process_group(0)` + `kill(-pid, SIGKILL)`;
- Windows:`taskkill /PID <pid> /T /F`。
- `max_output`:每流默认 1 MiB;范围 1 KiB–64 MiB;保留前 N 字节,余下丢弃并继续排空;`truncated=true`。
- stdin 独立写线程,避免双向管道死锁;EPIPE 忽略。
- stdout/stderr 两个读线程;UTF-8 lossy。
- 记录原始字节(至上限)以支持 `bytes` 输出。
---
## 9. 安全
| 项 | 策略 |
|---|---|
| 能力门禁 | `run` / `invoke` / `probe` / `session_*` 全部检查 `allow_exec()`;沙箱 → 拒绝 |
| shell | 默认不经 shell;模板显式 `bash -c` 才走 |
| cwd | `resolve_path` + `fs_root`;越界拒绝 |
| 输出 | 有界读取 + 丢弃式排空 |
| 时间 | 上限 + 进程组 kill |
| 并发 | 默认 4,上限 32 |
| 会话 | 每文档独立;关闭/drop 清理;超时即杀 |
| Secret | JSON 不默认暴露;env 显式;面板打码 |
| wasm | `exec-host` 关闭时全部返回清晰错误;`langs` 返回 [] |
---
## 10. 兼容性
- `run` / `run_lang` / `set_cmd` / `langs` 既有调用可用。
- `run` 成功仍返回 stdout(去一个尾换行);非 0 仍报错。
- `set_cmd` 增加可选 `args`。
- `langs` 扩展为「预设 ∪ 注册 ∪ 配置」;原集合是子集。
- `subtask` 的 `spawn code=` / `lang=` 仍返回 stdout 文本。
- HostFn id 只追加;字节码参数 < 255。
- 无核心表面 Δ。
---
## 11. 测试矩阵
| 测试 | 依赖 | 断言 |
|---|---|---|
| 既有 `foreign-python` / `run-lang` / `外联-python` | python | 兼容 |
| `foreign-invoke` | node | ok/code/stdout/stderr/ms |
| `foreign-env-cwd` | node | env/cwd/MARQDO_* |
| `foreign-timeout` | node | timed_out, 无遗留进程 |
| `foreign-call-json` | node | 嵌套 list/map 往返 |
| `foreign-call-many` / `run-many` | node | 顺序/隔离/并发 |
| `foreign-session` | node(python 可选) | 跨 eval 状态、异常不杀 |
| `foreign-session-set-get` | node | 变量推拉 |
| `foreign-session-timeout` | node | alive=false |
| `foreign-probe` | node | path/version/ok |
| `foreign-register` | node | 模板 `{inline}` |
| `foreign-config` | node | `MARQDO_FOREIGN_CONFIG` |
| `foreign-caps` | 无 | exec=false 拒绝 |
| 单元测试 | 无 | shell 切分/模板/别名/JSON |
当前环境无 Python:node + bash 为主;python 条件跳过;Windows 用 `python_available()` / `bash_available()` 守卫。
---
## 12. 实现落点
| 文件 | 内容 |
|---|---|
| `src/foreign/registry.rs` | 预设/别名/模板/venv/PATH/配置/shell 切分(纯逻辑) |
| `src/host/foreign.rs` | Job/Execution/ForeignEnv;run/invoke/call/run_many/call_many;probe/register/unset/langs/load_config |
| `src/host/foreign_session.rs` | Python/Node bootstrap;会话生命周期;set/get/names |
| `src/host/dispatch.rs` | HostFn 追加 |
| `src/aliases.rs` | 参数别名 |
| `lib/foreign.mq.md` / `lib/外联.mq.md` | L1 API + 文档 |
| `src/view/mod.rs` / `html.rs` / `debug_page.rs` | Run 诊断;后续接文档会话 |
| `tests/gold.rs` / `tests/lib/foreign-*.mq.md` | 测试 |
---
## 13. 明确不做
- Foreign line-level step。
- Foreign → Marqdo 函数 callback。
- 自动镜像变量。
- 跨语言共享对象引用。
- 全进程快照。
- 自动安装依赖。
- 浏览器 wasm 外联。
+654
View File
@@ -0,0 +1,654 @@
# 外联运行时 v3 — 能力缺口与深化设计(Proposed)
| | |
|---|---|
| 状态 | **Proposed;尚未实现** |
| 日期 | 2026-10-18 |
| 层 | Runtime(foreign)· Document(`foreign.session`)· View(投影) |
| 相关 | [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [foreign-v2.md](../roadmap/foreign-v2.md) · [stdlib-writeback.md](stdlib-writeback.md) · [view-static-interactive.md](view-static-interactive.md) |
| 核心表面 Δ | **无增删**:不新增 Markdown 标记、不新增 notebook CLI |
> 本文只定义设计,不承诺已实现。当前基线是 v1.5.0 之后的本地工作:`foreign.session` 句柄、多内核、values 初始化、view 控制、静态执行与显式 writeback 已可用;本文处理仍然缺失的能力。
---
## 1. 设计约束
v3 必须继续满足以下约束,否则不进入实现:
1. **外联库拥有内核与状态**:`foreign` 管理内核、会话、cell 计划、输入、输出、journal 和生命周期。`view` 只消费句柄,不拥有第二套运行时。
2. **表与围栏是值**:`内核表`、`单元表`、`输入表`、`值表` 都是普通 Marqdo 值;没有保留表名,没有新增标记。
3. **单一执行语义**:`run` 是规范执行;`view` 是同一文档的交互投影;静态导出是同一会话的快照,不另写解释器。
4. **没有 Notebook 模式**:没有 `marqdo notebook`,没有 `In/Out`,没有“普通 view / notebook view”两套布局。
5. **显式 I/O**:Marqdo 值通过 `values` / `session_set` 传递;程序 stdin 是单独概念,不能伪装成 `marqdo_input`。
6. **显式持久化**:默认不改源码;writeback 必须由文档显式调用,或由用户显式选择策略。
7. **安全默认值**:执行受 capability 控制;输入/输出有界;不反序列化任意对象;跨文档共享必须显式开启。
---
## 2. 基线:现在已经有什么
| 能力 | 状态 |
|---|---|
| `foreign.run` / `run_lang` / `invoke` / `probe` | 已实现 |
| `foreign.call` / `call_many` / JSON 进出 / 并行 | 已实现 |
| `session_open` / `eval` / `set` / `get` / `names` / `close` / `list` | 已实现 |
| `foreign.session kernels= cells= values=` | 已实现 |
| 多内核 view 会话、cell 顺序、内核归属 | 已实现 |
| Marqdo 表通过 `values` 传入多个内核 | 已实现 |
| 无 `会话` 时无状态 cells | 已实现 |
| view 每 cell 内核选择 / Clean / Run | 已实现 |
| 静态导出执行 cells 并嵌入真实输出 | 已实现 |
| 静态页 session summary、内核归属、多内核展示 | 已实现 |
| 显式 `writeback.record` | 已实现(库能力) |
| 静态页按钮的“不可执行”提示 | 已实现 |
---
## 2.1 实施状态(2026-10-18)
| ID | 状态 | 备注 |
|---|---|---|
| G1/G2 | ✅ 已实现 | session eval raw stdin;`foreign.session inputs=`;per-cell UI;Python/Node 测试 |
| G5 | ✅ 基本实现 | `session_interrupt` + view Interrupt;Python SIGINT 保留会话;Node 进程可能被终止 |
| G4 | ✅ 已实现(API) | add/remove/set-value + generation;view 尚未提供 add/remove UI |
| G6 | ✅ 已实现(API) | export/import/replay JSON snapshot;view/CLI 尚未做文件封装 |
| G9 | ✅ 已实现(CLI/API 基础) | `view capture` + `view output --snapshot`;source hash 校验 |
| G3 | ✅ 边界已实现 | 顶层 plan;嵌套 plan 诊断 |
| G10 | ✅ 显式 persist | `/api/session/cell/persist` + view Persist;不自动写源码 |
| G7/G8 | 📌 已移出当前目标 | 设计保留,后续版本再开发 |
## 3. 缺口清单
| ID | 缺口 | 优先级 | 当前行为 | 目标 |
|---|---|---|---|---|
| G1 | 持久内核 raw stdin | P0 | 持久内核只有 `marqdo_input` | 程序 stdin 与控制协议分离 |
| G2 | 每 cell 独立 stdin | P0 | 页面级 Cell stdin,Run All 共用一个输入 | cell 级输入表 + UI |
| G3 | 动态 plan | P2 | 只读顶层 `会话` | 明确边界,或受控动态 |
| G4 | 运行时更新 plan | P1 | values 只在打开时初始化 | 显式 session 变更 API |
| G5 | kernel interrupt | P0 | 只能等超时/杀进程组 | 可中断当前 eval |
| G6 | 状态持久化 / replay | P1 | journal/dirty 只在内存 | 导出/恢复/replay |
| G7 | 跨文档内核 | P2 | 每文档独立 | 显式 scope/空间 |
| G8 | 非 Python/Node 持久内核 | P3 | Go 等一次性执行 | LangSpec 会话适配器 |
| G9 | live → static 输入捕获 | P0 | 静态构建不捕获临时 stdin | 显式 snapshot 捕获 |
| G10 | 自动 writeback | P2 | 必须显式调用 | 显式策略下的“运行后写回” |
---
## 4. 统一模型
### 4.1 会话句柄
`foreign.session` 返回的句柄是一个普通 Marqdo 值,建议稳定形状:
```text
{
kind: "foreign-session",
id: "<session-id>",
document: "<entry-source-hash>",
status: "created | ready | running | interrupted | dirty | closed",
kernels: [...],
cells: [...],
inputs: [...],
values: [...],
generation: 1
}
```
`view` 只读这些字段;任何执行操作都通过 `foreign` 的 host API。句柄不是第二套运行时。
### 4.2 三种输入
必须严格区分:
| 输入 | 目标 | 形态 | 当前 |
|---|---|---|---|
| `values` | 内核变量 | Marqdo 值 → JSON copy | 已实现 |
| `input` | `marqdo_input` | JSON 值 | 已实现(低层) |
| `stdin` | 程序 stdin | 原始文本/字节 | 仅无状态 cell 有 |
v3 不允许把 raw stdin 偷偷塞进 `marqdo_input`;两者语义不同。
### 4.3 每 cell 输入表
不新增标记,仍然使用普通表:
```mq.md
`单元输入` =
| 单元 | stdin | input |
|------|-------|-------|
| 计算 | hello | {rate: 0.08} |
| 复核 | | {check: true} |
```
`foreign.session` 增加可选参数:
```text
foreign.session kernels=... cells=... values=... inputs=`单元输入`
```
规则:
- `stdin` 只给该 cell 的程序 stdin;
- `input` 只给该 cell 的 `marqdo_input`;
- 空值表示不提供;
- 输入大小有上限,超限显式报错;
- 静态导出使用同一张表,因此 view 与静态快照可以一致。
### 4.4 执行流水线
```text
evaluate 会话 handle
→ open kernels
→ apply values
→ apply cell inputs
→ run cell
→ record {stdout, stderr, input_echo, result}
→ next cell
```
失败不终止整个 Run All;错误写入 cell record,journal 保留。
---
## 5. G1/G2:持久内核 stdin 与每 cell 输入
### 5.1 问题
当前持久内核的 worker 用 stdin 传输 JSON 控制协议,因此程序自己的 stdin 不可用;`marqdo_input` 只是 JSON 变量,不是 stdin。
### 5.2 方案 A(推荐):控制通道与程序 stdin 分离
- Unix:父进程创建 **socketpair**(或两个 pipe),worker 通过 fd 3/4 读写控制帧;程序 stdin 使用单独的 pipe。
- Windows:named pipe 或可继承的匿名 pipe 作为控制通道;程序 stdin 单独 pipe。
- worker 协议升级为 `protocol: 2`:
- 控制帧:`eval` / `set` / `get` / `interrupt` / `close`
- eval 帧可带 `stdin`(UTF-8)或 `stdin_b64`(二进制,后续)
- Python worker:每次 eval 前把 `sys.stdin` 替换为 `io.TextIOWrapper`/`StringIO`,eval 后恢复控制通道;用户代码读到的是真正的 stdin。
- Node worker:控制 readline 移到控制 pipe;每次 eval 把 `process.stdin` 替换为 `PassThrough`/`Readable`,eval 后恢复。
- 超时/中断关闭该次 stdin,不污染下一次 eval。
### 5.3 方案 B(降级):只支持 `input`
如果控制通道暂不实现,持久内核只支持 `input`,并显式拒绝 raw stdin:
```text
persistent kernel stdin is unavailable; use input= or stateless cells
```
不能静默把 stdin 变成 `marqdo_input`。
### 5.4 方案 C:stdin cell 降级为一次性
持久会话中遇到 raw stdin 时,用一次性进程执行该 cell;明确标记 `state: none`,不假装内核态连续。
### 5.5 UI 与静态
- `view`:每个代码卡提供 **Cell stdin** 小输入框,或者页面级输入表;推荐每 cell,因为它们经常不同。
- 静态:读取 `inputs` 表;没有输入时显示“requires stdin”说明,而不是 traceback。
- Run All 使用每 cell 的输入;不再把一个页面级 stdin 复制给所有 cell。
### 5.6 验收
- Python 与 Node 持久内核都能读取真实 stdin;
- 同一个 cell 连续 eval 不串输入;
- 超时/中断后下一次 eval 仍可读 stdin;
- 无状态 cell 行为不变;
- 静态快照使用相同输入表,结果与 live 一致(在相同输入下)。
---
## 6. G3:动态 plan 的边界
### 6.1 问题
`foreign.session` 目前只识别 entry 顶层的 `会话` 绑定。分支、函数、运行时循环中定义的 plan 不会被 view 发现。
### 6.2 设计决定(建议)
**v3 不支持任意控制流中的 plan。** 这是有意的语义边界:
- plan 是文档的声明,不是程序运行时的副作用;
- view 不应为了找 plan 而执行 `# main`;
- 避免 view 再次长出一套“运行程序再猜计划”的隐式逻辑。
允许的动态形式:
- 顶层赋值右侧的纯表达式,包括引入的纯函数;
- `foreign.session` 的 tables/values 可以由顶层表函数计算;
- 运行时变化通过 G4 的显式 session API 完成。
**不支持**:
- `##` 函数内部的 plan;
- `if`/`while` 分支里的 plan;
- 依赖 `# main` 副作用才能得到的 plan。
### 6.3 诊断
如果源码中出现非顶层 `foreign.session`,给出:
```text
foreign.session: plan must be a top-level binding (会话 = > foreign.session ...)
```
而不是静默降级为无状态。
---
## 7. G4:运行时更新 plan
### 7.1 目标
已打开的 view session 允许用户显式修改 cell 归属、增加/移除 cell、更新内核变量;所有修改都要可追踪。
### 7.2 API
```text
foreign.session_assign session=<handle> cell="计算" kernel="复核"
foreign.session_add_cell session=<handle> cell="新单元" kernel="分析"
foreign.session_remove_cell session=<handle> cell="旧单元"
foreign.session_set_value session=<handle> kernel="分析" name="rate" value=0.08
```
所有操作:
- 校验 cell/kernel 语言;
- 递增 `generation`;
- 写入 journal(kind=plan_change / value_change);
- 标记受影响 cell 为 `dirty`;
- 失败不改变 handle。
### 7.3 View
- 内核下拉复用 `session_assign`;
- 增加/删除 cell 放在显式菜单,不做隐式拖拽写入源码;
- UI 显示 generation / dirty 状态。
### 7.4 静态
静态快照不执行变更;它记录变更后的 plan,或在构建时执行一次并固化。
---
## 8. G5:kernel interrupt
### 8.1 API
```text
foreign.session_interrupt id=<session-id>
```
### 8.2 行为
- 控制通道发送 `interrupt`;
- worker 取消当前 eval,返回 `{ok:false, interrupted:true}`;
- 保留已完成的值和 journal;
- 状态从 `running` → `interrupted`;
- 下一次 eval 可以继续使用内核(除非进程已损坏);
- 超时继续作为最后一道防线。
### 8.3 View
- 工具栏增加 Interrupt;执行中的 cell 显示 interrupted;
- 不自动重跑;
- 静态导出没有 interrupt(快照不执行)。
### 8.4 跨平台
Unix:进程组信号 + 控制帧;Windows:控制帧 + `taskkill /T` fallback。两者都必须有测试。
---
## 9. G6:状态持久化与 replay
### 9.1 不做的事
- 不做 Python pickle / Node 堆快照;
- 不做任意对象反序列化;
- 不把内核内存默认写进 `.mq.md`。
### 9.2 显式快照
```text
foreign.session_export session=<handle> path=".marqdo/sessions/doc-1.json"
foreign.session_import path=".marqdo/sessions/doc-1.json"
```
快照只包含:
```text
{
version: 1,
document_hash: "...",
plan_hash: "...",
kernels: [{name, lang, cmd, values: {...}}],
cells: [{name, kernel, status, last_ok, last_error}],
journal: [...],
inputs: [...]
}
```
值只允许 JSON 可表达的 Marqdo 值;不可序列化的值显式失败。
### 9.3 replay
```text
foreign.session_replay path="..." verify=True
```
按 journal 顺序重放 cell + inputs,比较 stdout/status;差异写入 report。replay 不覆盖原 journal,除非显式 `append`。
### 9.4 存储
- 默认目录 `.marqdo/sessions/`(gitignore 可选);
- 用户可通过 path 放到受控目录;
- 不默认提交,不默认写源码。
---
## 10. G7:跨文档内核(Deferred / future)
> **状态:已移出 v3 当前实现目标。** 本节设计保留,作为后续版本(v4 或独立 session-scope 工作)的输入;当前不承诺 API 或兼容性。
### 10.1 原则
- 默认每文档独立;
- 跨文档必须显式 `scope=` / `space=`;
- 不自动按变量名或路径共享。
### 10.2 API
```text
foreign.session_open lang="python" scope="shared:analytics"
foreign.session_list scope="shared:analytics"
foreign.session_close id=... scope=...
```
- scope 注册表由 foreign runtime 管理;
- 同名冲突报错,不覆盖;
- view 只能打开当前文档声明允许的 scope;
- 生命周期由 owner/refcount 管理,最后一个引用关闭时清理。
### 10.3 安全
- 跨文档共享可能违反文档隔离,必须 capability + 显式配置;
- journal 标记 scope;
- 静态导出默认不打开跨文档 scope。
---
## 11. G8:非 Python/Node 持久内核(Deferred / future)
> **状态:已移出 v3 当前实现目标。** 本节设计保留,等待目标语言与 worker 适配器确定后再实现;当前不承诺 API。
### 11.1 模型
不是所有语言都需要持久内核。`LangSpec` 增加能力标志:
```text
session: none | protocol_v2
```
- `none`:只能 `run` / `invoke` 一次性;
- `protocol_v2`:实现控制通道与 eval 协议,可以 `session_open`。
### 11.2 适配器
Go 等语言通过一个薄 worker 实现:
```text
control frame: eval {code, stdin, input}
result frame: {ok, stdout, stderr, result, error}
```
不允许“看起来像持久内核、实际每次重启”的假实现。
### 11.3 失败语义
- `session_open` 对 `session: none` 的语言明确报错;
- `foreign.session` 的 plan 只能使用支持 session 的语言;
- 静态/无状态仍可使用一次性执行。
---
## 12. G9:live → static 输入捕获
### 12.1 问题
静态构建在构建环境执行,无法知道用户在 live view 中临时输入的 stdin;同一文档的结果可能不同。
### 12.2 设计
增加显式的“捕获快照”:
```text
view → Capture snapshot → .marqdo/snapshots/<doc>.view.json
```
快照内容:
- document source hash;
- session plan(kernels/cells/values);
- 每 cell 的 stdin/input;
- 每 cell 的 stdout/stderr/status;
- journal 摘要、语言/解释器版本;
- 捕获时间。
静态导出:
```text
marqdo view output --snapshot .marqdo/snapshots/doc.view.json
```
优先使用快照中的记录,校验 source hash,不重新执行;若 hash 不匹配,显式失败或 `--execute` 重跑。
### 12.3 安全/隐私
- 快照可能包含 secrets;默认不提交、不发布;
- 提供 `redact` 字段/正则;
- 静态页面只发布脱敏后的快照。
### 12.4 验收
- live 中成功的结果可以在静态页面原样显示;
- 不捕获内核内存,只捕获输入/输出/状态;
- 没有快照时回退到构建时执行,行为明确。
---
## 13. G10:自动 writeback
### 13.1 原则
**“自动”必须是用户显式选择的策略,不是默认副作用。**
### 13.2 API
```text
foreign.session persist=`写回策略`
```
策略表:
```mq.md
`写回策略` =
| 单元 | key |
|------|-----|
| 计算 | total |
| 复核 | check |
```
或 view 的 **Persist results** 按钮:将当前 cell 结果写到 `writeback.record key=...`。
### 13.3 语义
- 默认不写源码;
- 显式策略只在 **用户点击 Persist** 或 `marqdo run --writeback` 时执行;
- 静态构建默认不写回;`--writeback` 必须显式;
- writeback 只支持 JSON 可表达值;
- 写入位置/格式仍由 `writeback` 库决定。
### 13.4 与静态快照的关系
- 静态快照是只读发布;
- writeback 是源码内的活结果;
- 两者可以共存,但不能互相隐式触发。
---
## 14. API / 端点汇总
### 14.1 新增 foreign 函数
```text
foreign.session inputs=
foreign.session_assign
foreign.session_add_cell
foreign.session_remove_cell
foreign.session_set_value
foreign.session_interrupt
foreign.session_export
foreign.session_import
foreign.session_replay
foreign.session_open scope=
foreign.session_list scope=
```
### 14.2 View API
```text
POST /api/session/cell/run { cell, stdin }
POST /api/session/run_all { restart, inputs? }
POST /api/session/cell/clear
POST /api/session/plan/assign
POST /api/session/plan/add
POST /api/session/plan/remove
POST /api/session/plan/value
POST /api/session/interrupt
POST /api/session/snapshot/capture
```
所有端点只操作 foreign 句柄;view 不直接读写内核。
### 14.3 CLI
```text
marqdo view output --snapshot FILE
marqdo view output --execute
marqdo view output --no-exec
marqdo run --writeback
```
不新增 `marqdo notebook`。
---
## 15. 语义矩阵
| 能力 | run | view | static |
|---|---|---|---|
| `foreign.session` plan | 作为普通值执行 | 消费句柄 | 可执行或快照 |
| raw stdin | 支持(一次性/session) | 每 cell | inputs 表/快照 |
| interrupt | 无 UI | 可调用 | 不可用 |
| state export | 可调用 | 可显式导出 | 不导出或快照 |
| cross-doc(deferred) | 设计保留 | 设计保留 | 设计保留 |
| writeback | `--writeback` | 显式按钮 | 默认不写 |
---
## 16. 实施顺序
### P0(先做,直接影响真实使用)
1. **G1/G2 stdin**:控制通道 + 每 cell 输入表 + UI。
2. **G5 interrupt**:避免只能等超时。
3. **G9 snapshot capture**:解决 live/static 不一致。
### P1
4. **G4 runtime plan updates**。
5. **G6 export/replay**。
### P2
6. **G3 dynamic plan 边界**:按第 6 节,只做顶层纯表达式;任意控制流不承诺。
7. **G10 explicit writeback policy**。
### Deferred(不在当前目标)
- **G7 cross-document scope**:设计保留,后续版本再开发。
- **G8 non-Python/Node persistent adapters**:设计保留,等待目标语言与 worker。
---
## 17. 测试设计
### 单元
- `stdin` 协议:空输入、大输入、超时、中断、连续 eval;
- 每 cell 输入隔离;
- 返回值锚定在调用点(已修复的 CallFrame.call_line);
- 表格不产生 call chip(已修复);
- plan top-level 诊断;
- session generation / dirty;
- export/import/replay 校验。
### 集成
- Python 持久内核读 `sys.stdin`;
- Node 持久内核读 `process.stdin`;
- view Run All 使用每 cell 输入;
- interrupt 后下一次 eval 正常;
- static snapshot 与 live 结果一致;
- snapshot hash 不匹配显式失败;
- cross-doc scope 冲突/清理;
- Go 一次性 vs 持久能力诊断;
- writeback 只显式写入。
### 静态
- 输出无 traceback;
- 没有输入时显示说明而非伪造;
- 多内核 controls 显示;
- writeback slot 单块、暗色主题;
- 静态按钮提示。
---
## 18. 兼容与迁移
- 现有 `foreign.session kernels= cells= values=` 保持兼容;
- 新 `inputs=` 可选;
- `session_open` 旧协议继续可用;v2 控制通道通过 handshake 协商;
- 旧页面没有 `inputs` 时仍按空 stdin 执行/显示说明;
- 不修改已发布的 v1.5.0 tag;v3 以新版本发布。
---
## 19. 需要拍板的决策
1. **G1**:是否接受控制通道与程序 stdin 分离的协议改造?否则只能保留 `input`,不能宣称 raw stdin。
2. **G3**:是否接受“plan 必须是顶层声明”的边界?若不接受,需要定义 view 可安全调用的 plan 入口,风险更高。
3. **G6**:状态快照只允许 JSON 值,是否可接受?不做任意对象序列化。
4. **G9**:快照文件是否默认放在 `.marqdo/snapshots/` 且不提交?涉及 secrets。
5. **G10**:自动 writeback 是否只允许显式按钮/flag,而不是每次运行自动写源码?
---
## 20. 当前目标范围
v3 当前实现目标为:**G1、G2、G3、G4、G5、G6、G9、G10**。
**G7、G8 已移出当前目标**,但设计文档保留在本文件第 10、11 节,供后续开发;它们不计入 v3 完成条件,也不影响现有 API 的兼容性承诺。
## 21. 非目标
- 不新增 Markdown 标记;
- 不新增 notebook CLI/模式;
- 不把任意内核内存序列化;
- 不默认修改 `.mq.md`;
- 不自动镜像变量;
- 不把 view 变成第二套解释器;
- 不把“未实现”伪装成支持。
+4 -1
View File
@@ -215,7 +215,9 @@ v0.3:
| 表达式 `[键](集合)` | **取元**(与 foreach 同形;见 [collection-access-link.md](collection-access-link.md)) |
| `修饰… [函数名] 实参…` | **方括号标记调用**(前置修饰 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md)) |
| `` 集合[^键] `` | **过渡**:旧脚注取元(仍可用) |
| ` ```lang ` | 外联(不变) |
| ` ```lang ` | 外联(不变;绑定仍用 `` `名` = `` + 围栏) |
| `$$` 内 `% marqdo: var=名` | 块公式绑定([fence-meta-and-control-prose.md](fence-meta-and-control-prose.md)) |
| `- 对`集`的每一项`项`` / `for each` | foreach 叙述糖;推荐 `- [项](集)` |
| 单独一行 `---` / `***` | **叙述分隔**(跳过;模块顶与函数体内相同) |
| 整行恰 `**` 或 `****` / `*None*` / `*无*` | **空返回**并结束本函数体(见 §7.2) |
@@ -616,3 +618,4 @@ FnDef.params:
| 2026-09-13 | 决议空返回(§7.2)与提及性反引号(§4.4);形参改为「升参」与绑定图分离(§8.2) |
| 2026-09-14 | §7.2:`---` 不再收束;返回语句结束函数体解析;空返回首选 `*None*` |
| 2026-09-14 | 取元主语法改为 `[键](集合)`;脚注取元过渡保留 |
| 2026-09-24 | Artifact Metadata Binding(`${…}` Phase 1,仅 frontmatter):见 [binding.md](binding.md) · ADR 0006 |
+1 -1
View File
@@ -130,7 +130,7 @@ Markdown **标记即语法**。输出**不是**语言架构原语,而是内置
## 5. Frontmatter 与跨文件
文件头 `---` 对为元信息。其中 `import bind:path.mq.md` / `导入` 为**文件导入**;`import bind:lib.member` 为**短名**(废除独立 `use` 与 frontmatter `>` 导入)。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法在独立 `>` 调用须 `` > `var`.method ``(`*…*` 段内接收者裸名)。详见 [module-namespace.md](module-namespace.md)。
文件头 `---` 对为 **Artifact Metadata**。其中 `import bind:path.mq.md` / `导入` 为**文件导入**;`import bind:lib.member` 为**短名**(废除独立 `use` 与 frontmatter `>` 导入)。其它 `key: value` 可为字面量或 **Binding**(`${env.NAME}` 等,加载期解析);见 [binding.md](binding.md)。调用经裸点号路径(`time.parse`、`agent.agent`);实例方法在独立 `>` 调用须 `` > `var`.method ``(`*…*` 段内接收者裸名)。详见 [module-namespace.md](module-namespace.md)。
**函数体内的** `---` / `***` 不解释为 frontmatter(见 §11)。
+531
View File
@@ -0,0 +1,531 @@
# 文档会话(View Cells)
| | |
|---|---|
| 状态 | **D1–D3 首版已实现;D4/D5 待做** |
| 日期 | 2026-10-17 |
| 层 | Runtime + Document(view 服务端 / 交互单元) |
| 相关 | [notebook-syntax.md](notebook-syntax.md) · [foreign-kernel.md](foreign-kernel.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [view.md](view.md) · [view-debug.md](view-debug.md) · [stdlib-subtask.md](stdlib-subtask.md) |
| 核心表面 Δ | 无(读取既有 AST 与表格) |
> 文档会话是 view 背后的交互单元运行时:它记住哪些 cell、在哪个内核、按什么顺序执行、状态是什么、结果是否过期。它不是第二个 CLI 模式——`marqdo view` 是唯一的交互面,`marqdo run` 是规范执行。
---
## 1. 目标
1. **像 Jupyter 一样即时**:点一个 cell 就执行,状态保留。
2. **不像 Jupyter 一样隐藏**:执行顺序、内核归属、状态、过期情况都可查。
3. **不破坏 Marqdo 程序语义**:`marqdo run` 仍是规范执行;view 会话是交互镜头。
4. **Git 友好**:状态/输出不默认写进 `.mq.md`。
5. **多语言**:命名内核 + 显式状态桥。
6. **可复现**:Run All / journal / dirty / stale / replay。
---
## 1.1 实施状态(2026-10-18)
| 能力 | 状态 | 位置 |
|---|---|---|
| `foreign.session` 句柄(kernels/cells 表参数) | ✅ | `lib/foreign.mq.md` · `src/host/foreign_doc.rs` |
| cell plan 求值 | ✅ 解释器求值 `会话` 绑定;不扫描源码行、不认保留表名 | `src/interp.rs` · `src/host/foreign_doc.rs` |
| cell index(绑定名 / 行号 / source hash) | ✅ | 同上 |
| 命名内核 + 默认内核 + 语言校验 | ✅ | 同上 |
| 同内核共享 / 跨内核隔离 | ✅ | Node 金样例 + 单测 |
| `run_cell` / `step` / `run_all(restart)` | ✅ | `DocumentSession` |
| `restart_kernel` / `assign_kernel` | ✅ | 同上 |
| `kernel/interrupt` | 待做 | — |
| 状态桥 `push` / `pull` / `state_list` | ✅ | `DocumentSession` + `foreign_session` |
| journal(记录 + API + Journal 按钮) | ✅ | `DocumentSession::journal_json` · view |
| view 工具栏 / 状态徽标 / 内核下拉 / 状态表单 | ✅ | `src/view/html.rs` |
| `POST /api/session/*` | ✅(含 `reload`) | `src/view/notebook_api.rs` |
| cell step | ✅ | 同上 |
| Marqdo statement step | ✅(view 工具栏 Debug → 同一 view 服务的 `/debug`;`/api/debug/*`) | `src/debug` · `src/view/debug_api.rs` |
| dirty/stale 自动检测 | 部分(reload → dirty;assign → dirty;stale 传播待做) | `src/host/foreign_doc.rs` |
| writeback 集成 | 待做 | `writeback` |
| replay / 持久化 | 待做 | — |
| Python 会话 | ✅(本机无 python,CI/用户机条件测试) | `src/host/foreign_session.rs` |
| Node 会话 | ✅ | 同上 |
首版刻意不做:把状态写进 `.mq.md`、自动镜像变量、foreign 行级 debug、跨文档共享内核。
---
## 2. 两个执行面(不是两个 CLI 模式)
### 2.1 Program execution(规范)
- 入口:`marqdo run doc.mq.md` / CI / `view` 的 `Run document`。
- 执行:`# main` 程序语义;外联通过显式 `foreign.session_open/eval/call` 编排。
- 状态:一次运行内有效;运行结束进程退出(除非显式持久内核)。
- 结果:可复现;是文档的“真理”。
### 2.2 View cells(交互)
- 入口:`marqdo view doc.mq.md` → 文档单元(cell)控制。
- 执行:按 `会话表`(或自动顺序)逐 cell 执行。
- 状态:内核持久;可切换、重启、单步。
- 结果:默认临时显示;可显式 writeback。
- 不是“真理”:是探索界面;需要复现时用 Run All 或把编排写进 `# main`。
### 2.3 两者关系
```text
.mq.md
/ \
Program run View cells
(canonical) (interactive)
\ /
Document Session
├── cell index
├── kernel registry
├── journal
└── state panel
```
- 共享 cell index 与 kernel registry。
- `run` 不消费视图会话;`view` 只在文档绑定 `会话 = > foreign.session ...` 时提供持久 cell 控制;无 `会话` 时 cells 无状态一次性执行。
- 冲突时以 `run` 的程序语义为准;view cells 不改变文档语义。
---
## 3. 文档会话模型
```text
DocumentSession
├── doc_path / doc_hash
├── cells: Vec<Cell>
│ ├── id (name / anon@line)
│ ├── name (binding)
│ ├── lang
│ ├── line_start / line_end
│ ├── source_hash
│ ├── kernel (resolved)
│ └── status: never | clean | dirty | stale | error | running
├── kernels: KernelRegistry
│ ├── name → ForeignSession
│ └── default per language
├── value_store: HashMap<String, Value> // Marqdo 侧会话值
├── journal: Vec<ExecutionRecord>
├── created_ms / last_active_ms
└── surface: program | view
```
### 3.1 Cell
- 只有**绑定名**的代码围栏才是 cell:
```markdown
`加载` =
```python
...
```
```
- 未绑定围栏仍是叙述,不是 cell。
- `id`:优先绑定名;匿名围栏用 `anon@<line>`(不进入会话表)。
- 同名 cell 重复 → 诊断;会话表按名字引用。
- `source_hash` 用于 dirty 判断。
- `line_start/line_end` 用于定位;编辑后重建索引。
### 3.2 Cell index 构建
1. 读取/解析文档(现有 `parse_source` / `load_module`)。
2. 遍历 AST,找 `Stmt::Assign { name, value: Expr::Code(c) }`。
3. 记录 name、lang、source、span、source hash。
4. 通过解释器求值 `会话` 绑定(`foreign.session` 返回的句柄,含简单依赖);不扫描源码行、不认保留表名(见 [notebook-syntax.md](notebook-syntax.md))。
5. 解析 kernel 声明与 cell 归属;校验;生成诊断。
6. 生成执行顺序:
- 有会话表 → 行顺序;
- 无 → 文档顺序。
7. 未入会话的 cell → 状态 `unlisted`,UI 显示徽标。
### 3.3 Kernel registry
- key:`<document_id>:<kernel_name>`。
- 默认:`default:python`、`default:node`,按需启动。
- 命名:来自 `内核表`,首次执行时启动。
- 状态:`idle | starting | ready | busy | dead`。
- 同一 kernel 的 cell 严格串行;不同 kernel 可并行。
- 重启:kill + 清空状态 + 重新启动;cell 状态变 `never`。
- 关闭:kill + 移除。
### 3.4 Value store(Marqdo 侧会话值)
- 保存可从 Marqdo 推入内核的值(来自最近一次 Program run 的 bindings,或用户手动输入)。
- 也保存从内核取回的值(`session_get` / 状态面板 Pull)。
- 不是解释器 Env 的实时镜像;它是会话层的**值缓存**。
- 注入解释器:未来通过 `SessionEnv` 或显式变量赋值;v2 不做隐式注入。
- 用途:
- 状态面板显示;
- Push 到内核;
- 作为 `session_set` 的值来源;
- journal 记录。
### 3.5 Journal
每次执行追加一条:
```json
{
"seq": 3,
"cell": "汇总",
"kernel": "分析",
"lang": "python",
"ok": true,
"code": 0,
"ms": 42,
"source_hash": "…",
"stdout_hash": "…",
"result_hash": "…",
"started_ms": 1760000000000,
"error": ""
}
```
用途:
- 执行序号 / 顺序;
- dirty/stale 判断;
- replay;
- 视图显示;
- 调试(“为什么这个 cell 有值”)。
存储:内存 + 可选 `.marqdo/sessions/<doc-hash>.json`(默认 git 忽略)。
---
## 4. 执行语义
### 4.1 操作
| 操作 | 语义 |
|---|---|
| **Run cell** | 执行选中的 cell;必要时启动/复用 kernel |
| **Run above** | 按会话顺序执行到选中 cell(含) |
| **Run all** | 按会话顺序执行全部;可选 `restart` |
| **Step next cell** | 执行会话顺序中的下一个未执行/选中 cell |
| **Step next statement** | Marqdo 语句级单步(DebugController) |
| **Restart kernel** | kill + 重建;cell 状态 `never` |
| **Interrupt** | kill 当前 cell 进程组;kernel 标记 dead 或重启 |
| **Reset session** | 关闭所有 kernel,清 journal / value store |
### 4.2 执行一个 cell
```text
resolve cell -> resolve kernel
-> ensure kernel ready
-> [送入?] 显式 bridge 由文档代码/UI 负责
-> foreign.session_eval(kernel, source, input?)
-> record -> update cell status
-> [取回?] 由文档代码/UI 负责
-> journal append
-> view update
```
- 默认 cwd = 文档目录;env = kernel env。
- 输出:stdout / stderr / result / ms / truncated。
- 失败:cell 状态 `error`;journal 记录;不自动重试。
- 同一 kernel 串行;UI 禁用并发 Run。
### 4.3 Step 语义
| 类型 | 行为 |
|---|---|
| **Cell step** | 执行下一个会话 cell;状态保留 |
| **Marqdo statement step** | 执行下一条 Marqdo 语句;遇到 `foreign.session_eval` 时整个外联调用原子完成 |
| **Foreign line step** | 不做;未来 DAP |
- Cell step 是 view cells 的主单步。
- Statement step 复用 `DebugController`;需要把 debug session 与 DocumentSession 关联。
- 两者可以互相切换:cell step 到某个 Marqdo cell 后可 statement step;语句执行完回到 cell 边界。
### 4.4 中断
- `Interrupt`:向当前 kernel 进程组发 SIGINT/SIGKILL;记录 `interrupted`。
- 若 kernel 状态不确定 → 标记 dead;建议 restart。
- 不允许“中断后继续用同一 kernel”除非确认状态。
### 4.5 并发
- 同一 kernel:一次一个 cell。
- 不同 kernel:可并行(例如 Python 分析与 Node 前端)。
- `Run all` 默认按会话顺序串行;可配置“按 kernel 并行、按依赖串行”(后续)。
- 并发上限沿用 foreign(32)。
---
## 5. 状态桥(会话层)
### 5.1 显式 API
文档代码:
```markdown
把 `数值表` 送进 `分析` 内核:
**> foreign.session_set id="分析" name="xs" value=`数值表`**
从 `分析` 内核取回 `mean`:
**`均值` = > foreign.session_get id="分析" name="mean"**
```
### 5.2 状态面板
- 左侧:Marqdo 侧值(最近 Program run bindings + value store)。
- 右侧:每个 kernel 的变量(`session_names` + 按需 `session_get`)。
- 操作:
- Push:选 Marqdo 值 → kernel 变量;
- Pull:选 kernel 变量 → value store / 显示;
- Refresh;
- 复制名称/值。
- Secret 打码;大对象显示摘要(类型/长度/repr 截断)。
### 5.3 自动镜像
- v2 不做。
- 后续 `mirror`:`mq_` 前缀、白名单、按值拷贝、默认关。
- 原因见 [decisions](../research/foreign-notebook-decisions.md) §1-F。
### 5.4 类型
- JSON 拷贝;复杂对象需 `to_dict` / JSON。
- 大对象:v2 显示摘要;传输用文件/DB。
- 未来:Arrow / Parquet / 共享文件句柄。
---
## 6. Dirty / Stale / Run All
### 6.1 定义
| 状态 | 条件 |
|---|---|
| `never` | 未执行 |
| `clean` | 上次执行成功后源码未变 |
| `dirty` | 源码 hash 变了 |
| `stale` | 上游 cell 变了(依赖图;v2 先按会话顺序近似) |
| `error` | 上次执行失败 |
| `running` | 正在执行 |
| `unlisted` | 不在会话表 |
### 6.2 依赖
- v2:会话表行顺序 + 简单规则:
- 若上游 cell 的 source_hash 变了,下游标 `stale`;
- 若 kernel 重启,全部 `never`。
- v2.1:变量级依赖图(静态分析 + bridge 表),精确 stale。
- 不假装 Jupyter 的“隐藏顺序”:顺序就是表/文档顺序。
### 6.3 Run All
- 默认:按会话顺序执行;可选 `restart=true`。
- 规范执行:**restart + run all**;UI 明确按钮 `Restart & Run All`。
- 未重启时:显示“当前 kernel 有历史状态”警告。
- 执行后:生成 session summary(ok/fail/耗时/跳过的 cell)。
### 6.4 Replay
- 用 journal 的顺序和输入 hash,在新 kernel 上重放;
- 比较 stdout/result hash;
- 输出 divergence 报告。
- v2 可选;至少保留 journal 以便未来实现。
---
## 7. 输出与文档
### 7.1 默认
- View cells 输出只在 view 中显示;不写 `.mq.md`。
- 关闭/刷新后可通过 journal 恢复最近结果(若 session 持久化)。
- 不写 execution_count 到文档。
### 7.2 显式 writeback
- 复用 `lib/writeback` 的 `<!-- marqdo-out … -->`。
- cell 输出锚点:cell 名 + 行号;写入位置在围栏之后,或文档末尾的“输出”区。
- 可选:
- 单 cell 写回;
- 全部写回;
- 只写回文本/数值,不写复杂对象。
- Git 友好:输出是普通 Markdown 注释块;可 diff、可忽略。
### 7.3 不写回
- 避免 Jupyter 的 `.ipynb` 输出噪声。
- 需要分享结果时,导出 HTML / 静态 view,而不是改源文件。
---
## 8. View 交互
### 8.1 工具栏
```text
[Run All] [Restart & Run All] [Step Cell] [Step Statement]
Kernel: [分析 ▾] Status: ready [Restart] [Interrupt]
[State] [Journal] [Writeback ▾]
```
### 8.2 每个 code card
```text
`加载` python · kernel 分析 · run #3 · 42ms · clean
[Run] [Step] [Kernel ▾] [State] [Copy output]
```
- 状态徽标:`never` / `clean` / `dirty` / `stale` / `error` / `running` / `unlisted`。
- 输出区:stdout / stderr / result / 截断提示。
- 内核下拉:切换归属;不迁移状态;提示需要重跑。
- `Step` = 执行此 cell(cell step)。
### 8.3 状态面板
- Marqdo / kernel 分栏。
- Push/Pull。
- Secret 打码。
- 大对象摘要 + 复制 JSON。
### 8.4 Journal 面板
- 表格:seq / cell / kernel / ok / ms / 时间 / 错误。
- 点击跳转 cell。
- 导出 JSON。
### 8.5 键盘
- `Ctrl/Cmd + Enter`:Run cell。
- `Shift + Enter`:Run cell + 下一个。
- `Alt + Enter`:Run cell + 插入?不做。
- `F10`:Step statement(与 debug 一致)。
- `F5`:Run All。
---
## 9. 服务端 API
所有 API 以文档相对路径 + session id 定位;session 内存驻留,进程退出即失。
| 方法 | 路径 | 作用 |
|---|---|---|
| POST | `/api/session/open` | 打开文档会话,返回 cells / kernels / journal |
| POST | `/api/session/close` | 关闭会话,kill 所有 kernel |
| POST | `/api/session/reload` | 重新解析文档,保留 kernel(标记 dirty) |
| POST | `/api/session/cell/run` | 执行指定 cell |
| POST | `/api/session/cell/step` | 执行下一个 cell |
| POST | `/api/session/run_all` | 按会话顺序执行;`restart` 可选 |
| POST | `/api/session/kernel/restart` | 重启指定 kernel |
| POST | `/api/session/kernel/interrupt` | 中断当前 cell |
| POST | `/api/session/kernel/assign` | 改 cell 的 kernel 归属(会话内) |
| POST | `/api/session/state/list` | Marqdo / kernel 变量列表 |
| POST | `/api/session/state/push` | Marqdo 值 → kernel |
| POST | `/api/session/state/pull` | kernel 变量 → value store |
| POST | `/api/debug/*` + `/debug` | Marqdo 语句单步(Debug 按钮,复用 debugger) |
| POST | `/api/session/writeback` | 显式写回 cell 输出 |
| POST | `/api/session/journal` | 执行日志 |
| GET | `/api/session` | 当前会话摘要 |
响应统一:`{ok, session, ...}`;错误 `{ok:false, error, code?}`。
---
## 10. 生命周期与持久化
- Session key:`<root>/<doc_rel>`;每个文档一个。
- 打开:解析、建 cell index、按需启动 kernel。
- 空闲超时:默认 30 分钟关闭(可配置)。
- 文档关闭 / 服务退出:kill 所有 kernel。
- 文件变更:view 刷新时 `reload`;cell hash 变化 → dirty;kernel 保留。
- 持久化(可选):
- `.marqdo/sessions/<doc-hash>.json`:kernel 名称/语言、cell 归属、journal、value store 摘要;
- 默认 git 忽略;
- 不持久化进程状态 / 大对象。
- 不把 session 状态写进 `.mq.md`。
---
## 11. 安全
| 项 | 策略 |
|---|---|
| exec | 所有 kernel 启动/执行检查 `allow_exec`;沙箱拒绝 |
| 生命周期 | 每文档;关闭/drop kill;不跨文档 |
| cwd | 文档目录 / `fs_root`;越界拒绝 |
| 输出 | 有界;截断标记 |
| 超时 | cell 级;进程组 kill |
| 中断 | 杀进程组;kernel 标记 dead |
| Secret | 状态面板打码;JSON 不默认暴露 |
| 未信任文档 | 不自动打开会话;必须显式 Run |
| 并发 | 同 kernel 串行;不同 kernel 上限 32 |
| writeback | 显式;路径沙箱;不自动改文档 |
---
## 12. 测试
### 12.1 服务端
- cell index:绑定名/行号/lang/source hash;未绑定围栏排除。
- 会话解析:foreign.session 句柄/自动模式/重复/未知/语言不匹配。
- 会话:open/close/reload;kernel 启动/重启/中断。
- cell run:状态机 never→running→clean/error;dirty/stale。
- step:cell step 顺序;statement step 与 debug 联动。
- state:push/pull/list;Secret 打码;大对象摘要。
- journal:顺序、hash、失败。
- 并发:同 kernel 串行;不同 kernel 并行。
- 安全:exec=false 拒绝;cwd 越界;超时。
### 12.2 金样例
- `tests/notebook/kernels.mq.md`:foreign.session 句柄。
- `tests/notebook/shared-state.mq.md`:两个 Python cell 共享 `x`。
- `tests/notebook/step.mq.md`:cell step 顺序。
- `tests/notebook/state-bridge.mq.md`:Marqdo ↔ Python 推拉。
- `tests/notebook/invalid-*.mq.md`:诊断。
- 依赖:node 为主,python 条件跳过。
### 12.3 UI
- 手工冒烟:Run cell / Step / Run All / Restart / State Push/Pull / Journal。
- 不引入前端测试框架;用服务端 API + 静态检查。
---
## 13. 与 Jupyter 对照
| 维度 | Jupyter | Document Session |
|---|---|---|
| 源 | `.ipynb` | `.mq.md` |
| 执行顺序 | 隐藏的 `In[n]` | 会话表 / 文档顺序 / journal |
| 状态 | 隐藏 kernel | kernel + value store + 状态面板 |
| 多语言 | 一文档一 kernel | 命名内核 + 每 cell 归属 |
| 单步 | cell | cell + statement |
| 复现 | 手动 | Restart & Run All + journal + replay |
| Git | 输出/计数噪声 | 源码干净;输出显式 |
| 知识 | 无 | OKF / catalog |
| 调试 | 语言 pdb | Marqdo 断点 + cell 级;行级后续 |
---
## 14. 实现顺序(D 层)
| 阶段 | 内容 |
|---|---|
| D0 | 设计/语法/决策文档(本文件) |
| D1 | `src/host/foreign_doc.rs`:cell index、foreign.session 句柄、session 结构、诊断 |
| D2 | 服务端 API:open/close/cell run/step/run_all/restart/interrupt |
| D3 | view UI:工具栏、cell 徽标、kernel 下拉、状态面板、journal |
| D4 | statement step 接入;dirty/stale;writeback |
| D5 | replay / 持久化 / 并发优化 / 测试补全 |
依赖 F 层:F3 持久内核、F3.5 状态桥先完成,D2 才能工作。
---
## 15. 明确不做(v2)
- Foreign line-level step。
- 自动镜像变量。
- 跨文档共享 kernel。
- 全进程快照。
- 自动执行 cell。
- 把 session 状态写进 `.mq.md`。
- 前端 SPA 框架重写;沿用现有 HTML/JS。
+305
View File
@@ -0,0 +1,305 @@
# 文档原生 view cells 语法
| | |
|---|---|
| 状态 | **Decided;D1 解析已实现** |
| 日期 | 2026-10-17 |
| 层 | Document(读取约定) + Runtime(校验) |
| 相关 | [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [notebook-session.md](notebook-session.md) · [foreign-kernel.md](foreign-kernel.md) · [core-surface.md](core-surface.md) · [layers.md](layers.md) |
| 核心表面 Δ | **无**——不新增标记;只用既有 `# main` / 赋值 / 表格 / 反引号 |
> 目标:让“这段代码在哪个内核里、按什么顺序执行、和谁共享状态”像目录一样可读,而不是像 IDE 配置一样可读。
---
## 1. 为什么不用围栏元数据
Jupyter 的 cell 元数据、VS Code 的 `kernel=`、YAML 的 `kernels:` 都属于**代码/编辑器思维**:
- 读者看到的是一行属性,不是一段知识;
- 属性藏在围栏 info string 或 JSON 里,Markdown 预览看不见意图;
- 一旦加 `kernel=`,它就是 Language 层语法,需要 ADR、core-surface 增行;
- 同一个文档的执行计划被拆散到每个围栏,无法一眼总览。
Marqdo 的选择:
> **执行计划本身是一张表。表是文档的一部分,人先读表,机器再读表。**
这不是新语法。GFM 表已经是集合,`` `名` = `` + 表已经是数据绑定;我们只约定两个**数据表的名字**。
---
## 2. 两个约定数据表
它们放在 `# main`(或唯一入口对象)的体内,和代码单元并列:
```markdown
# main
`内核表` =
| 名称 | 语言 | 命令 | 说明 |
|------|------|------|------|
| 分析 | python | | 读取与清洗数据 |
| 绘图 | python | | 独立环境 |
`会话表` =
| 单元 | 内核 | 说明 |
|------|------|------|
| 加载 | 分析 | 读取原始数据 |
| 清洗 | 分析 | 处理缺失值 |
| 汇总 | 分析 | 按城市聚合 |
| 绘图 | 绘图 | 输出 SVG |
```
为什么是“绑定的表”,不是 `# 外联内核` 对象:
- `#` 是对象/函数;把元数据做成顶层对象会把文档拆成多个作用域,code fence 会被困在对象里。
- 绑定表是入口体内的**数据**,与 cell 同一作用域;不执行、不改变控制流。
- View / 文档会话读取 AST 中的绑定值,不需要执行文档。
- 解析器零改动。
### 2.1 `内核表` / `kernels`
| 列 | 必填 | 含义 |
|---|---|---|
| `名称` / `Name` | ✅ | 内核名,供 `会话表` 引用;建议用领域词(分析/绘图/前端) |
| `语言` / `Language` | ✅ | 预设 id 或已注册语言:`python` / `node` / … |
| `命令` / `Command` | 可选 | 覆盖解释器命令;空白 = 预设 / `set_cmd` / 配置 / 环境变量 |
| `说明` / `Notes` | 可选 | 给人读的一句话;不影响执行 |
规则:
- 名称在文件内唯一;重复 → 诊断。
- 语言不支持会话时,内核仍可声明,但只能执行一次性 cell;`session_*` 报错。
- `命令` 只写可执行文件;参数请用 `.marqdo/foreign.toml` 或 `session_open`。
- 没有 `内核表`:每种语言自动一个 `default` 内核。
- 声明了内核但 `会话表` 没引用:允许,只是没有被使用。
### 2.2 `会话表` / `session`
| 列 | 必填 | 含义 |
|---|---|---|
| `单元` / `Cell` | ✅ | 代码围栏的绑定名(`` `加载` = `` 后面的名字),表格里**不写反引号** |
| `内核` / `Kernel` | ✅ | `内核表` 中的名称,或语言 id(`python` / `node`)表示该语言默认内核 |
| `说明` / `Notes` | 可选 | 给人读的一句话 |
规则:
- **行顺序 = 执行顺序**。这是 `Run All`、`Step`、`Run Above` 的规范顺序。
- 只有列出的 cell 参与会话;未列出的代码围栏仍然显示,但标记为“未入会话”,Run All 不执行。
- 没有 `会话表`:所有绑定名的代码围栏按**文档出现顺序**自动入会话,每种语言用默认内核。
- `单元` 必须对应一个已绑定名的代码围栏;找不到 → 诊断。
- 同名 cell 重复出现 → 诊断;建议一个名字只绑一个围栏。
- `内核` 未声明且不是语言 id → 诊断,列出已声明内核。
- cell 的语言与内核语言不一致 → 诊断;别名等价(`python3`/`py` ↔ `python`)。
- 表可以出现在 `# main` 体内任意位置;读者可以从表一眼看到执行计划。
### 2.3 为什么放在 `# main` 体内
- `# main` 是入口;cell 绑定与元数据表同一作用域。
- `marqdo run` 会正常求值这两个表(得到 `List of Map`),没有副作用。
- 文档会话从 AST / 最近一次运行的 bindings 读取它们;不需要新的解析路径。
- 如果文档没有 `# main` 而是唯一 `#` 对象,同样适用。
---
## 3. 完整示例
````markdown
# main
这份文档演示一个最小 view cells 文档:两个 Python 单元共享 `分析` 内核,
一个绘图单元在隔离的 `绘图` 内核里运行。
`内核表` =
| 名称 | 语言 | 命令 | 说明 |
|------|------|------|------|
| 分析 | python | | 数据读取与聚合 |
| 绘图 | python | | 独立绘图环境 |
`会话表` =
| 单元 | 内核 | 说明 |
|------|------|------|
| 加载 | 分析 | 读取原始数据 |
| 清洗 | 分析 | 处理缺失值 |
| 汇总 | 分析 | 按城市聚合 |
| 绘图 | 绘图 | 输出 SVG |
`加载` =
```python
import json
rows = [
{"city": "上海", "value": 3},
{"city": "北京", "value": 5},
]
print(json.dumps(rows, ensure_ascii=False))
```
`清洗` =
```python
rows = [r for r in rows if r["value"] > 0]
```
`汇总` =
```python
from collections import Counter
counts = Counter(r["city"] for r in rows)
print(dict(counts))
```
`绘图` =
```python
print("plot-ready")
```
`汇总` 和 `绘图` 分属两个内核;`绘图` 看不到 `rows`。
需要共享时,用 Marqdo 显式把值送过去:
**> foreign.session_set id="绘图" name="rows" value=`rows`**
````
读者即使不运行,也能从 `会话表` 读出:先加载、再清洗、再汇总,最后绘图;前三个共享 `分析`,绘图在 `绘图`。
---
## 4. 自动模式(没有表)
### 4.1 没有任何约定表
````markdown
# main
`分析` =
```python
x = 41
```
`结论` =
```python
print(x + 1)
```
````
解释:
- 两个 cell 都是 `python`;
- 自动使用 `default:python` 内核(一个);
- 按文档顺序执行;
- 共享 `x`。
现有文档不需要改一行就能在 view 里 cell-by-cell 运行。
### 4.2 只有内核表
- 所有 cell 按文档顺序;
- 每种语言解析到该语言的 `default` 内核;
- 命名内核只有被 `会话表` 引用时才使用。
### 4.3 只有会话表
- `内核` 列只能写语言 id;
- 每个语言 id 解析到该语言默认内核;
- 未列出的 cell 不入会话。
---
## 5. 可读性规则(语法评审标准)
新增/修改任何 cell 表约定,必须满足:
1. **先读人话**:去掉执行语义后,表格仍像目录/清单。
2. **不使用属性串**:不写 `kernel=…`、`class=…`、JSON/YAML 元数据。
3. **不隐藏意图**:执行顺序、内核归属必须在一处可见。
4. **不引入新标记**:只用 `#` / 表格 / 反引号 / 既有代码面。
5. **默认安全**:表格只声明,不自动执行;只有 Run / Step 触发。
6. **命名用领域词**:`分析`、`绘图`、`前端`,不用 `k1`、`default`、`stage2`(除非确实是默认)。
7. **说明列可选但推荐**:给未来的读者/LLM 一点上下文。
8. **错误可读**:诊断要指出“哪个单元、哪个内核、哪一行、怎么修”。
9. **中英对称**:中文用中文列名,英文用英文列名;语义一一对应。
10. **无表也能跑**:约定表是增强,不是前置条件。
---
## 6. 诊断规范
| 情况 | 诊断(中文示例) | 修复建议 |
|---|---|---|
| 内核名重复 | `内核表: 内核名「分析」重复(第 12、20 行)` | 改名或合并 |
| 会话引用未知内核 | `foreign.session: cell「汇总」引用了未声明的内核「分析」` | 在 kernels 表声明,或改用语言 id |
| 会话引用未知单元 | `会话表: 找不到名为「清洗」的代码单元` | 检查 `` `清洗` = `` 绑定 |
| 单元重复 | `会话表: 单元「汇总」重复出现` | 每个单元只列一次 |
| 语言不匹配 | `会话表: 单元「前端」(node) 不能使用 python 内核「分析」` | 换内核或换语言 |
| 未入会话 | (非错误)view 徽标:`未入会话` | 需要时加一行 |
| 内核表为空 | `内核表: 至少声明一个内核,或删除该表使用默认内核` | 删除表或补行 |
| 会话表为空 | `会话表: 至少列出一个单元,或删除该表使用自动顺序` | 删除表或补行 |
原则:**不静默忽略**。读者必须知道为什么某个 cell 没跑。
---
## 7. 与 program execution 的关系
- `内核表` / `会话表` 只是传递给 `foreign.session` 的普通表变量,不是保留名。
- `marqdo run` 仍然执行 `# main` 的程序语义;这两个表会被求值为普通数据。
- `run` 的外联编排用显式 API(`foreign.session_open` / `session_eval` / `call`);`foreign.session` 句柄服务 `view` 的 cells 与一键 Run All。
- 两者可以并存:
- 文档用表描述“交互时怎么跑”;
- `# main` 用显式调用描述“CI 时怎么跑”。
- 如果两者冲突,以 `run` 的程序语义为准;cell 表只影响 `view`。
这样避免把“执行计划”变成第二套程序语义。
---
## 8. 状态桥的语法边界
v2 **不**为状态交换新增表格/注释。原因:
- “什么时候送、什么时候取、送到哪个内核、赋值给哪个 Marqdo 变量”需要精确语义;
- 若做成隐式表格动作,容易产生隐藏状态与顺序歧义;
- v2 先用显式 API,把时序讲清楚:
```markdown
把 `数值表` 送进 `分析` 内核:
**> foreign.session_set id="分析" name="xs" value=`数值表`**
从 `分析` 内核取回 `mean`:
**`均值` = > foreign.session_get id="分析" name="mean"**
```
- view 提供状态面板与 Push/Pull 按钮,减少手写 API 的需要;
- 声明式 `共享表` 作为 v2.1 提案,等 session value store 与“每次单元执行前后”的时序稳定后再引入。
这不是降级:v2 的功能完整(可读可写、可推可拉),只是不用隐式语法承载时序。
---
## 9. 未来扩展(不承诺进 v2)
1. `共享表`:
`| 内核变量 | Marqdo 变量 | 方向 | 说明 |`,每次单元执行前送入、后取回。
2. 每个 cell 的“运行条件/依赖”列:`依赖` 列声明上游单元。
3. 内核别名:`内核表` 的 `名称` 可被 `use` 或短名引用。
4. 多文件会话:跨 `.mq.md` 的共享内核(默认仍隔离)。
5. 语言特定的“会话能力”列(是否支持持久、是否支持行级调试)。
任何一项都要先过 §5 的可读性规则与 `core-surface` 检查。
---
## 10. 实现落点
| 逻辑 | 位置 |
|---|---|
| 识别 `会话` 的 foreign.session 句柄 | `src/host/foreign_doc.rs` |
| 读取绑定值 | AST `Stmt::Assign` + `Expr::Table` / `Expr::List`;或最近一次 run 的 bindings |
| 校验名称/语言/重复/未入会话 | 同上;错误进入现有 Diagnostic |
| cell index(绑定名/行号/语言/source hash) | 解析后的 `Module` 遍历 |
| 只读展示 | view Structure:表渲染成普通表格 + 徽标 |
| 执行 | Document Session API(见 [notebook-session.md](notebook-session.md)) |
解析器本身**不需要改**。这是本设计最重要的约束:语法是既有标记的组合,不是新构造。
+28 -7
View File
@@ -143,13 +143,18 @@ Marqdo 对齐的判断是:
| `type` | 状态 | 含义 | 主要生产者 |
|--------|------|------|------------|
| `Marqdo Catalog` | **v0 已实现** | 包总览(`catalog.yaml` / `index.md`) | `marqdo catalog` |
| `Marqdo Module` | **v0 已实现** | 一个 `.mq.md` 模块的投影 | `marqdo catalog` |
| `Marqdo Task` | **规范已定;实现待做** | 一项可匹配的任务意图 | `plan` 晋升 |
| `Marqdo Agent Skill` | **规范已定;实现待做** | 指向可执行工作簿的技能 | `plan` 晋升 |
| `Marqdo Catalog` | **已实现** | 包总览(`catalog.yaml` / `index.md`) | `marqdo catalog` |
| `Marqdo Module` | **已实现** | 一个 `.mq.md` 模块的投影 | `marqdo catalog` |
| `Marqdo Task` | **已实现** | 一项可匹配的任务意图 | `plan` 晋升 |
| `Marqdo Agent Skill` | **已实现** | 指向可执行工作簿的技能 | `plan` 晋升 |
| `Capability` / `Function` | **EKC** | 工程能力 / 符号投影 | `marqdo knowledge` |
| `Decision` / `Constraint` / `Failure` / `AntiPattern` / `Pattern` / `Migration` / `Fact` | **EKC** | L4 工程知识 | 源 frontmatter + learn |
| `Marqdo Context Pack` | **EKC** | Agent EFI 上下文制品 | `reuse` / `preflight` |
| `Marqdo Policy` | **EKC** | 复用决议编译 | `marqdo reuse` |
| `Marqdo Engineering Knowledge` | **EKC** | 工程知识总览 | `engineering.yaml` / `index.mq.md` |
| 其他 | 开放 | 第三方/未来扩展 | — |
**不**引入 Google OKF 的 `Metric` / BigQuery 表类型作为 Marqdo 核心词汇;需要时可由用户包自行使用,运行时降级。
完整 EKC 规范见 [engineering-knowledge.md](engineering-knowledge.md)。
---
@@ -309,10 +314,15 @@ type: Marqdo Agent Skill
title: <短名>
sig: <12hex>
resource: ../../resources/<slug>.mq.md
status: stable | candidate
status: stable | candidate | quarantine
llm_free: true | false
quality: <int>
hits: <int>
# O2 optional metadata (from workbook frontmatter; see §7.5):
applies_when: <text condition or tag>
fixtures: <relative .mq.md proof path>
sandbox_profile: default | readonly | <name>
proof: <relative .mq.md> # alias of fixtures for sandbox gate
generated:
by: marqdo-agent/plan
at: <ISO8601>
@@ -326,7 +336,7 @@ verified:
Prefer spawning `resource` over re-planning.
```
`status`:`llm_free` 的 resource 晋升为 **stable**(零父 LLM 快路径);否则为 **candidate**(可复用,但按 `improve_every` 偶发再优化,每轮最多 1 次改进)。失败运行不晋升;质量更差不覆盖。
`status`:`llm_free` 的 resource 晋升为 **stable**(零父 LLM 快路径);否则为 **candidate**(可复用,但按 `improve_every` 偶发再优化,每轮最多 1 次改进)。失败运行不晋升;质量更差不覆盖。**O2:** `agent_kb_promote` 默认要求 sandbox proof(`proof` / `fixtures` / workbook 本身经 `sandbox.run` 成功)才写入;失败返回 `promoted: false` / `reason: sandbox_proof_failed`。传 `require_proof=false` 仅用于明确豁免。
### 7.3 任务签名 → Concept 路径
@@ -396,6 +406,17 @@ Prefer spawning `resource` over re-planning.
| 迭代 | 同 Concept slug/`sig` 覆盖 resource + 刷新 `generated`/`verified` |
| 成长 | 命中快路径;`candidate`/`hits`/`improve_every` 驱动再优化;`log.md` 可审计 |
| 分发 | 整包 `agent-kb/` 可复制(格式即契约) |
| **证明晋升(O2)** | `applies_when` / `fixtures` / `sandbox_profile` / `proof` 写在技能与 workbook frontmatter;promote 前 `sandbox.run` 绿才 `llm_free` |
| **隔离(O5)** | 失败技能 `status: quarantine`;回归 fixture 跟随 slug |
### 7.5a 技能 frontmatter 约定(O2 B1)
| 字段 | 含义 |
|------|------|
| `applies_when` | 适用条件(短文本 / 标签);路由与 harness 可读 |
| `fixtures` | 相对路径:sandbox 证明用 `.mq.md` |
| `sandbox_profile` | `default` / `readonly` / 其它 `sandbox.profile` 名 |
| `proof` | 与 `fixtures` 同义;promote 优先读 `proof` 再 `fixtures`,否则跑 workbook 自身 |
---
+2 -2
View File
@@ -2,9 +2,9 @@
| | |
|---|---|
| 状态 | **已落地(v1)** |
| 状态 | **v1 已落地**;v2 设计见 [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [notebook-syntax.md](notebook-syntax.md) |
| 日期 | 2026-08-06 |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) · [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [roadmap/foreign-v2.md](../roadmap/foreign-v2.md) |
---
+14 -4
View File
@@ -34,7 +34,16 @@
### 2.2 文档中的 `$$` = 公式赋值(与表格同构)
在可执行面用 **空 RHS 赋值** 后跟展示数学块,把公式绑到变量(与 `` `xs` = `` 后跟表格一致):
**推荐(块内元数据)**:在 `$$` 体内用 TeX 注释声明变量(见 [fence-meta-and-control-prose.md](fence-meta-and-control-prose.md)):
````markdown
$$
% marqdo: var=f
sin(x) + x
$$
````
**兼容**:空 RHS 赋值后跟展示数学块(与 `` `xs` = `` 后跟表格一致):
````markdown
# main
@@ -52,13 +61,14 @@ $$
也支持:
- 单行围栏:下一行 `$$x^2 - 2$$`
- 同行 compact:`*`f` = $$x^2 - 2$$ *`
- 同行 compact:`*`f` = $$x^2 - 2$$ *`(历史面)
- 行内:`` `g` = $x+1$ `` 或 `` `g` = $$x+1$$ ``
**废除:** `$$:name` / `$$ name=…` 模块级具名块(不再产生绑定)。
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区若出现未挂在赋值上的裸 `$$` 围栏 → 报错,提示使用 `` `name` = `` + 围栏。
**无名 `$$…$$`:** 仅在成段注释(叙述面)里作展示,**不**进入运行时。可执行区裸 `$$` 若既无空 RHS 又无 `% marqdo: var=` → 报错。
**行内 `$…$`:** v1 不做绑定;需要时用 `> formula text=…` 显式构造。
**行内 `$…$`:** 传统绑定 `` `名` = $…$ `` → `formula`;**不**使用 `$% marqdo:…$`(会破坏 Markdown/TeX 识别)。
### 2.3 从文本构造
+22 -5
View File
@@ -8,9 +8,11 @@
## 定位
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` 的 `<!-- marqdo-out … -->` → `marqdo view` 在对应语句下显示 **output-card**。普通 Markdown 预览不显示该区域。
**Jupyter 输出单元的 Marqdo 等价物**:执行得到结果 → `record` / `写回` 写入入口 `.mq.md` → `marqdo view`(及静态 `view output`)在对应语句下显示 **output-card**,并在源码面用 **writeback** 样式标出块本身。
## 存储格式
## 存储格式(两种,可并存)
### 1. HTML 注释(文本 / 结构化输出)
```markdown
*`n` = > len value=`xs` *
@@ -30,11 +32,26 @@ pending
-->
```
- 注释内为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
### 2. Markdown 图片(生成图 / 审计友好)
当 `value` **看起来像图片引用**(扩展名 `.png` / `.jpg` / `.jpeg` / `.gif` / `.webp` / `.svg` / …,或 `data:image/…`)时,`record` **自动**写成:
```markdown
![marqdo-out](plots/out.svg)
![marqdo-out ok](plots/ok.png)
```
- 普通 Markdown 预览即可看见图;view / 静态站额外加 writeback 标记与 output-card 中的 `<img>`。
- 非图片路径仍走注释块;把非图片硬写成 `![marqdo-out](…)` 时扫描会忽略(校验失败)。
- `list` / `scan_path` 结果带 `kind`: `comment` | `image`。
### 共用规则
- 标记字为 `marqdo-out`,可选后跟槽名(`ok` / `error` 等),**不存行号**
- 默认在**调用行下方**插入或替换紧邻**无键**块
- `at_end=true`:替换文件末尾的**无键**块
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽(智能体单步用父调用行,即 `step` 语句下方);`ensure` 在缺失时写入占位且不覆盖已有正文。命名槽互不覆盖,也不使用文件末尾单块。
- `line=` / `行=`:显式锚点行号。子任务 / 异步写回必须带上,否则会锚到子任务内部调用行。主机侧有全局互斥锁,写前从磁盘重读入口源,避免并发写互相覆盖。
- `key=` / `键=`:在**当前调用锚点下方**创建或替换该命名槽;`ensure` 在缺失时写入占位且不覆盖已有正文
- `line=` / `行=`:显式锚点行号;主机侧有全局互斥锁
### 替换跨度与空行
+1 -1
View File
@@ -4,7 +4,7 @@
|---|---|
| 状态 | 已定 |
| 日期 | 2026-08-04 |
| 相关 | [view.md](view.md) · 源目录 [`public/`](../../public/) |
| 相关 | [view.md](view.md) · [view-static-interactive.md](view-static-interactive.md)(静态交互 / 公式代码视觉 · Proposal) · 源目录 [`public/`](../../public/) |
---
+3 -3
View File
@@ -4,14 +4,14 @@
|---|---|
| 状态 | **v1(独立 debug 页)** |
| 日期 | 2026-08-05 |
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [pipeline-debug.md](pipeline-debug.md) |
| 相关 | [next-phase.md](../roadmap/next-phase.md) P3 · [view.md](view.md) · [view-document-annotations.md](view-document-annotations.md) · [pipeline-debug.md](pipeline-debug.md) |
## 分工
| 命令 | 角色 |
|------|------|
| `marqdo view` | 文档浏览器:Structure + Execution + Source;函数大纲与搜索;**无断点** |
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;**仅 live** |
| `marqdo view` | 文档浏览器:**叙述保真文档面** Structure + Execution + Source;函数大纲与搜索;跑后引出标注;**无断点**(见 [view-document-annotations.md](view-document-annotations.md)) |
| `marqdo debug` | 调试宿主(默认端口 **7430**):IDE 式布局;AST Structure + BP;**仅 live** |
静态 `gh-pages` / `view output` **不能**真断点。
+113
View File
@@ -0,0 +1,113 @@
# View:文档面与结果引出标注
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-10-15 |
| 相关 | [view.md](view.md) · [view-debug.md](view-debug.md) · [view-markup-surface.md](view-markup-surface.md) · [view-execution-trace.md](view-execution-trace.md) · [view-frame-selection.md](view-frame-selection.md) · [view-prose-annot-gaps.md](view-prose-annot-gaps.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
---
## 1. 动机
`.mq.md` 是叙述与程序的同一载体。`marqdo view` 的 Structure 必须**保真叙述**,并在可执行标记旁展示运行结果。
旧 Browse Structure 用 AST 卡片重建语句,并用 `emit_comments` 只插入**语句行之前**的注释。当叙述与 `**…**` / `*…*` / `` `名` `` 在同一行时,该行被 Stmt 占用,叙述被丢弃——信息密度接近 debug,不适合文档浏览。
## 2. 模式分工
| 命令 | Structure | 叙述 | 结果 |
|------|-----------|------|------|
| `marqdo view`(Browse) | **文档面** | 保留并为主 | 跑后引出标注(callout + CSS L-leader) |
| `marqdo debug` | AST 卡片 + BP gutter | 弱化/可折叠 | Variables / 步进;不做文档 callout |
断点与逐步执行**仅**在 debug。静态 `view output` 与 live view **共用** Browse 文档面渲染。
## 3. 视觉语法
```
文本段…… `变量` …… **语句** …… *返回*
━━━━━
│
└──→ 结果标注
```
1. 叙述正文正常排版(Markdown)。
2. 可执行片段高亮,并带底部分割线(underline)。
3. 段落下方 **annotation band** 放结果 callout。
4. **CSS L-leader**(绝对定位小盒 + `border-left` + `border-bottom`)连接锚点与 callout。**不使用 SVG。**
5. 拥挤 / 极窄屏 / `prefers-reduced-motion`:取消长横折,改为编号 keyed 列表。
关联强度(递减):同色 underline + callout 色条 + label → CSS L-leader → keyed 编号。
对齐 [view.md](view.md) HIG:系统字体、无外链、浅色、克制装饰。
## 4. 文档面渲染
实现:`src/view/document.rs`;Browse 入口经 `render_module_structure` 调用。
| 源内容 | 呈现 |
|--------|------|
| 纯叙述段 | Markdown HTML;无 `comment` badge / 厚卡片 |
| 含 `ProseBit` 的行 | 原文保留;Decl / BoldCode / ItalicReturn 包 `mark.mq-anchor`(字节偏移来自 `scan_prose_line`) |
| 整行结构(`#` / `>` / `-` / `1.` / 表) | 表面语法保真(见 [view-markup-surface.md](view-markup-surface.md));整句可作锚点 |
| 函数标题 | 轻量 heading + `id="fn-{line}"`(大纲跳转不变) |
Debug 仍走 `render_module_structure_mode(..., Debug)` 的 AST 卡片路径。
## 5. ViewAnnot
跑后(或 `--no-exec` 时为空)组装标注集,嵌入文档面 `data-*` 与 band HTML。
| 字段 | 含义 |
|------|------|
| `id` | 稳定短 id(页内唯一) |
| `kind` | `bind` · `return` · `call` · `expr` · `branch` · `loop` · `writeback` |
| `anchor_line` | 1-based 源行 |
| `anchor_byte_start` / `anchor_byte_end` | 行内字节范围(可选;整行锚点可省略 end) |
| `label` | 短标题(名 / return / arm / loop) |
| `value` | 截断显示 |
| `detail` | 完整文本(inspect) |
| kind | 数据来源 | 锚点 |
|------|----------|------|
| `bind` | **StmtEvent post-stmt**(赋值执行后的值);禁止用入口终态回填初始化行 | 该赋值行 |
| `return` | 返回事件或入口返回 | ItalicReturn / Return |
| `call` / `expr` / `writeback` | writeback 槽、调用摘要 | 语句行或 BoldCode |
| `branch` | `ViewTrace`:命中 arm、次数 | 条件 / arm |
| `loop` | `ViewTrace`:迭代次数、末次 item | While / ForEach 头 |
标记面、结构块、多调用帧与 AI JSON 见 [view-execution-trace.md](view-execution-trace.md)。
`ViewTrace` 由 tree 解释器在 capture 时静默收集,**不**写入 stderr;与 `trace_eval` 调试轨迹分离。Bytecode 后端可暂无 trace(标注降级为 writeback)。
## 6. 布局与密度
- 每段默认最多 **4** 个常显 callout;其余 hover / 「show more」。
- Leader:按锚点 x 排序 callout,避免交叉;窄屏改为短竖线 + 堆叠。
- 客户端:`ResizeObserver` 重算 leader 盒的 `left/top/width/height`。
- 静态导出:页载 JS 跑一次布局。
右侧 **Variables** 仍为全集绑定;callout 为就地摘要,点击可打开同一 inspect。
## 7. 非目标
- 不在 view 内做断点 / 单步(见 [view-debug.md](view-debug.md))。
- 不新增作者侧标注 DSL / frontmatter 指令。
- 不引入外链字体、npm 组件或 SVG leader。
- 不把 DB/auth 等塞进 view 壳层。
## 8. 验收
1. `inc-prose.mq.md`:叙述「对于输入变量…」完整可见;`n` / `n=n+1` / 返回高亮。
2. 跑完后:值经 underline + CSS L-leader 连到下方标注(无 SVG)。
3. 分支/循环样例:可见命中 arm 与迭代次数(有 ViewTrace 时)。
4. `marqdo debug` 仍为 AST + 断点;叙述不抢主视觉。
5. 无外链字体/新依赖;`view output` 可离线打开。
## 9. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-10-15 | 初稿:文档面、ViewAnnot、CSS L-leader、与 debug 分工 |
| 2026-10-15 | bind = post-stmt;交叉链 view-execution-trace |
+103
View File
@@ -0,0 +1,103 @@
# View:执行轨迹与文档面保真
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-10-15 |
| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-frame-selection.md](view-frame-selection.md) · [view.md](view.md) · [view-markup-surface.md](view-markup-surface.md) |
---
## 1. 目标
`marqdo view` Browse Structure 必须同时做到:
1. **标记面**:变量名 / 可执行语句 / 返回值按表面渲染(无源码定界符字面量)。
2. **结构块**:GFM 表、循环(`-`)、分支(`1.`)有正确 HTML 与缩进。
3. **语句后值**:赋值行标注该语句执行后的值,不用入口终态回填。
4. **执行臂**:高亮实际走的分支臂。
5. **多调用帧**:同函数多次调用可用下拉切换经历。
6. **AI 可读**:与 HTML 同源的 `ViewExecutionReport` JSON。
Debug 仍用 AST 卡片 + 断点;不做文档 callout。
## 2. 标记面
| 源标记 | 显示(无定界符) | class |
|--------|------------------|-------|
| `` `名` `` / `` `名`=默认 `` | `名`(默认次要后缀) | `mq-anchor mq-decl` |
| `**…**`(可执行) | 内层文本 | `mq-anchor mq-code` |
| `*…*`(返回) | 内层文本 | `mq-anchor mq-return` |
`data-byte-start/end` 仍为源码字节偏移(供 CSS L-leader)。软强调不进 anchor。
## 3. 结构块
| 块 | 呈现 |
|----|------|
| GFM 表 | `<table class="doc-table">` |
| `-` 循环 | `<ul class="doc-loop">`,体按源缩进 `--doc-indent` |
| `1.` 分支 | `<ol class="doc-branch">`;命中 `arm-taken`,未走 `arm-miss` |
| 公式 / 外联代码 | 现有 formula-card / code-card |
| `>` 调用 | 表面高亮,非整行灰 code |
## 4. StmtEvent / CallFrame
解释器 capture 时静默采集(非 `trace_eval` stderr):
```text
StmtEvent {
line, kind, // assign | return | call | branch | loop | bind_ref
name?, value_after?, // post-stmt 或求值结果
arm_index?, iter?,
call_id // 当前用户函数调用帧
}
CallFrame {
call_id, fn_name, fn_line, ordinal,
args_brief, // 短摘要供下拉
events[] // 或全局 events 用 call_id 过滤
}
```
- Assign → 写入后的值挂在**该行**。
- 循环内多次写入:UI 默认末次;可带次数。
- Branch → taken `arm_index` + 条件摘要。
- 进入用户函数分配 `call_id`;`# main` 单帧无下拉。
## 5. ViewExecutionReport(AI)
```json
{
"version": 1,
"path": "…",
"ok": true,
"calls": [{ "call_id": 1, "fn": "等级说明", "ordinal": 1, "args_brief": "等级=及格" }],
"events": [{ "line": 24, "kind": "assign", "name": "总分", "value_after": "0", "call_id": 0 }],
"bindings_final": { "均分": "73", "等级": "及格" }
}
```
产出:页内 `#mq-view-trace` JSON;live `GET /api/view-trace?path=`;SSE `done.trace_json`。
## 6. UI
- 函数标题旁 `<select class="call-picker">`(调用数 ≥ 2)。
- 循环头旁 `<select class="loop-picker">`(迭代数 ≥ 2);默认最后一轮;摘要 `分 = 分数表[i] · value`。
- **源码常显**:切换帧只改 chip / 臂高亮,不 `hidden` 结构节点。详见 [view-frame-selection.md](view-frame-selection.md)。
- CSS L-leader(非 SVG);拥挤 keyed 降级。
## 7. 验收
1. 无字面 `**` / 返回定界 `*` / 变量外层 `` ` ``(Source 除外)。
2. 表为真表格;循环/分支有缩进列表;未选中臂源码仍可见。
3. `总分 = 0` 标注 `0`,非终态累加。
4. 命中臂可视化;多调用下只显示当前帧的 taken。
5. 循环可按迭代切换;JSON 含 `loops`;单测覆盖。
## 8. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-10-15 | 初稿:标记面、结构块、StmtEvent、CallFrame、AI 报告 |
| 2026-10-15 | 帧选择保真:call_id 分支、LoopFrame、源码常显 |
+123
View File
@@ -0,0 +1,123 @@
# View:调用帧 / 循环帧选择与结构保真
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-10-15 |
| 相关 | [view-execution-trace.md](view-execution-trace.md) · [view-document-annotations.md](view-document-annotations.md) |
---
## 1. 问题(对照实测)
1. **结构缺失**:切换函数调用下拉时,JS 按 `data-call-id` **隐藏** `.doc-exec`。未在本帧执行的分支臂体(赋值/返回)只有其它帧的 call_id,或仅有执行帧的 id → **未选中臂的源码被藏掉**,看起来像「臂消失 / 代码没渲染」。
2. **调用记录混叠**:`Branch` 标注未带 `call_id`;`taken_arms` 按行号只保留最后一次命中。多帧下同一分支同时出现 `arm 1 taken` 与 `arm 2 taken`。
3. **循环无帧**:循环只有总次数摘要;无法按迭代查看;`` - [分](分数表) `` 不能展示「当前是集合第几个元素」。
## 2. 定稿原则
| 原则 | 含义 |
|------|------|
| **源码常显** | 表 / 列表 / 分支臂 / 语句源码**永不**因帧选择 `hidden` |
| **轨迹随帧** | 标注 chip、臂高亮、变量值随「当前调用帧 / 当前迭代」变化 |
| **默认末帧** | 函数默认最后一次调用;循环默认最后一次迭代 |
| **一帧一真相** | 同时只展示一个 call_id(函数)或一个 (loop_id, iter)(循环)的轨迹 |
## 3. 函数调用帧
### 数据
`BranchHit` / 相关 `StmtEvent` 必须带 `call_id`。`ViewAnnot` 的 branch/bind/return 同样带 `call_id`。
### UI
- 函数标题旁 `<select class="call-picker" data-fn="…" data-scope="fn">`
- 选项:`1: 等级=及格` / `2: 等级=优秀`
- 默认选中最后一次
### 客户端(`applyCallFrame`)
1. 读 `#mq-view-trace` JSON。
2. 过滤 `events` where `call_id == selected`。
3. **不**设置结构节点 `hidden`。
4. 更新该函数作用域内:
- `.annot-chip[data-call-id]`:仅显示匹配帧;无 call_id 的结构说明类可保留
- `.doc-branch[data-line]`:按该帧的 branch 事件设置 `arm-taken` / `arm-miss`(全部臂仍可见)
- 绑定 chip 的 `.annot-value`:用该帧 assign/return 事件刷新(同名同行取末次)
## 4. 循环迭代帧
### 数据
```text
LoopFrame {
loop_id, line,
item_name?, // "分"
collection?, // "分数表"
iterations: [{ index, item_value, call_id }] // index 0-based
}
```
`StmtEvent` 增加可选 `loop_id`;循环体内事件带 `iter`(1-based 或 0-based,JSON 内统一 **0-based index**)。
### UI
- 循环头(`- [分](分数表)`)旁:`<select class="loop-picker" data-loop-id="…">`
- 选项:`迭代 1: 分=92` … `迭代 4: 分=88`
- 默认最后一次
- 头旁摘要 chip:`分 = 分数表[3] · 88`(下标 0-based 显示为 `[i]`)
### 客户端(`applyLoopFrame`)
1. **只显示当前迭代**:带 `data-iter` 的 chip 仅保留选中项;其余 `hidden` + `is-frame-hidden`(SSR 默认已按末轮预隐藏)。
2. 更新头摘要 chip(无 `data-iter`)为当前选项文案。
3. 不隐藏循环体源码。
## 5. 分支臂渲染
- 所有臂(含 else)**始终**渲染完整头 + 体(含 `*返回*` / 赋值)。
- `arm-miss` 仅降低不透明度,**不** `display:none` / `hidden`。
- 高亮仅反映**当前帧**的 taken `arm_index`。
## 6. AI JSON 增量
`ViewExecutionReport` 增加:
```json
"loops": [{
"loop_id": 1,
"line": 27,
"item": "分",
"collection": "分数表",
"iters": [{ "index": 0, "value": "92" }, { "index": 3, "value": "88" }]
}]
```
`events[].call_id` 必填;循环体内事件带 `loop_id` + `iter`(index)。
## 7. 验收
1. 未选中分支臂源码始终可见(含返回句)。
2. 切换「等级说明」调用:只显示该帧的 arm taken;变量/返回值对应该帧。
3. 循环下拉默认最后一轮;`分 = 分数表[3] · 88`;切换迭代后体内累加值变化。
4. `#mq-view-trace` 含 `loops` 与带 `call_id` 的 branch 事件。
5. `cargo test --lib view::` 全绿。
## 8. 开发计划(已执行)
| 阶段 | 内容 | 状态 |
|------|------|------|
| D0 | 本文档 + `view-execution-trace.md` 交叉引用 | ✅ |
| D1 | `BranchHit.call_id`;`LoopFrame` / `LoopIter`;`StmtEvent.loop_id` | ✅ |
| D2 | 解释器:foreach/while 推栈;BindRef `分=分数表[i]`;assign 带 iter | ✅ |
| D3 | `build_view_annots`:分支带 call_id;LoopFrame 选项;报告 JSON `loops` | ✅ |
| D4 | 文档面:源码不贴 `data-call-ids`;call picker `value=call_id`;loop picker;SSR taken=末帧 | ✅ |
| D5 | JS:`applyCallFrame` / `applyLoopFrame` — 只滤 chip + 重算 arm,不 hidden 结构 | ✅ |
| D6 | 单测:多调用不同臂、loop 末项、HTML 三臂返回 + picker | ✅ |
## 9. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-10-15 | 初稿:源码常显、帧过滤、循环迭代 picker |
| 2026-10-15 | 按计划落地 D1–D6 |
+145
View File
@@ -0,0 +1,145 @@
# View:叙述面标注缺口(prose annot gaps)
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-10-15 |
| 相关 | [view-document-annotations.md](view-document-annotations.md) · [view-static-interactive.md](view-static-interactive.md) · [view-frame-selection.md](view-frame-selection.md) · [view-execution-trace.md](view-execution-trace.md) |
> **定位**:对既有文档面设计的**缺口专章**——写清用户可见的四类问题、根因(文件:行)与验收口径。不改写 ADR;不发明作者侧标注 DSL。
---
## 1. 为何「改了却几乎没变化」
| 原因 | 说明 |
|------|------|
| 错二进制 | PATH 上的 `marqdo` 可能仍是旧版(如 1.3.0);改动在源码 / `./target/debug/marqdo`。验收必须用 `cargo build && ./target/debug/marqdo view …` |
| Chip 被溢出藏掉 | 同 band 堆多帧 return/print/who;`MAX_VISIBLE_ANNOTS=4` 把当前帧的 `who` 打成 `annot-chip-overflow`(`display:none`);帧切换不重算溢出 |
| L-leader 几何错位 | `initAnnotLeaders` 里 `y0=0` 只在 `.annot-band` 顶画短折,**连不到**上方 underline;窄屏或 chip>4 时整段关掉 leaders |
| 旧静态快照 | gh-pages / 旧 `view output` 不会自动刷新 |
---
## 2. 目标视觉语法(既有,不新造)
锚定 [view-document-annotations.md](view-document-annotations.md) §3:
```
文本段…… `变量` …… **语句** …… *返回*
━━━━━
│
└──→ 结果标注 chip
```
- underline:`mark.mq-anchor.mq-{decl|code|return}`
- band:段落下方 `.annot-band` → leaders + chips
- L-leader:CSS `border-left` + `border-bottom`(禁止 SVG)
- 公式/代码:[view-static-interactive.md](view-static-interactive.md) G3 **一层主视觉**;卡下不叠 Bind dump
- 帧:[view-frame-selection.md](view-frame-selection.md) **源码常显、只滤 chip**;默认末帧
---
## 3. 管线
```mermaid
flowchart LR
CLI["marqdo view / view output"] --> build["build_file_view"]
build --> cap["run_file_capture"]
cap --> annot["build_view_annots"]
annot --> doc["document::render_module_document"]
doc --> page["html.rs page_file"]
page --> js["initAnnotLeaders + initCallPickers"]
```
| 步骤 | 位置 |
|------|------|
| CLI / 导出 | `src/main.rs` · `src/view/mod.rs` · `src/view/output.rs` |
| Capture + Call 事件 | `src/interp.rs` |
| Annot 组装 | `src/view/annot.rs` `build_view_annots` |
| 文档面 HTML | `src/view/document.rs` |
| 卡片 chrome | `src/view/render.rs` `render_*_assign_card` |
| CSS / leader JS | `src/view/html.rs` |
---
## 4. 四条用户问题 → 根因 → 验收
复现源:`public/00-welcome.mq.md` · `public/00-欢迎.mq.md`
对照金样:`tests/view/document-annot-demo.mq.md` · `tests/markup-v03/inc-prose.mq.md`
### P1 — 叙述与代码同段时信息不显示
| | |
|---|---|
| 现象 | underline 在,chip / 连线弱或无 |
| 根因 | `html.rs` `initAnnotLeaders`:`y0=0` 相对 band;`document.rs` `MAX_VISIBLE_ANNOTS` 把当前帧 chip 溢出;PATH 旧 CLI |
| 目标 | 同 `inc-prose`:underline + L-leader(从锚点底到 chip)+ 可见 chip |
| 验收 | `./target/debug/marqdo view public/00-welcome.mq.md`:主文 `**greet…**` 与 `## greet` 体内均有可见 chip 与接到 underline 的 leader(宽屏) |
### P2 — 函数内变量不显示
| | |
|---|---|
| 现象 | `` `who` `` 有浅蓝 underline,无值 chip |
| 根因 | bind chip 存在但带 `annot-chip-overflow`;`applyCallFrame` 只 `hidden` 非选中帧,不解除当前帧 overflow |
| 目标 | 选中调用帧时常显 `who` · `print` · `return` 各一枚 |
| 验收 | 切换「调用」下拉,三枚 chip 随帧变且默认可见(无需点 +N) |
### P3 — ` ```text ` 渲染不一致
| | |
|---|---|
| 现象 | 变成内联 `text marqdo ext add…`,无卡片 |
| 根因 | Comment 围栏若进 `flush_para` → `join(" ")` → pulldown 当 inline code;应走 `render_narrative_fence` |
| 目标 | 与 bound python 同 `.code-card` chrome(badge + `pre.code-body`),**无** Run/foot |
| 验收 | welcome install 段:`data-lang="text"` + 两行 `marqdo ext add`;无 `<code>text marqdo` |
### P4 — 函数引用 / 代码卡未渲染
| | |
|---|---|
| 现象 | `**greet who=…**` 无结果;或 `hi` python 只见头/Run、不见源码 |
| 根因 | 同行多 Call 未与 BoldCode zip;或 Run 挤在 head;静态假 Run;错看 Debug 路径 |
| 目标 | 主文两 greet 各有 call chip(stdout 摘要);`hi` = `render_code_assign_card` head→body→foot;静态藏 Run |
| 验收 | 两枚 greet mark 均有非空 `data-annot-id`;`code-body` 含 `hello-from-python`;`MARQDO_VIEW_LIVE=false` 无 Run 按钮 |
### call_id 语义(写死)
| 位置 | call_id |
|------|---------|
| 主文 `**greet…**` 的 call chip | 入口帧(`# main` 的 call);结果为 stdout/返回摘要 |
| `## greet` 体内 print / who / return | callee 的 CallFrame id;跟函数标题旁 picker |
---
## 5. 修复约定(实现红线)
1. **帧感知密度**:band 内按选中 `call_id` 计可见 chip;默认末帧;同帧最多 4 枚常显;溢出只藏非当前帧或多余 kind。切换后客户端重算 overflow + `layoutAll()`。
2. **Leader 容器**:提升到 `.doc-block`(prose + band);`y0` = 锚点底相对 block;按锚点 x 排序再画线。
3. **卡片**:只复用 Browse `render_*_assign_card` / `render_narrative_fence` + `html.rs` `.code-*` / `.formula-card`;本波不改 Debug AST 路径(除非回归红)。
4. **静态 Run**:`MARQDO_VIEW_LIVE=false` 时隐藏 Run,不留禁用假按钮(对齐 view-static-interactive D5)。
5. **非目标**:不做 debug 断点;不发明作者标注 DSL;不用 SVG leader;不单独发版/推 gh-pages(除非另嘱)。
---
## 6. 验收命令
```bash
cargo build -q
./target/debug/marqdo version # 须为当前工作树版本
./target/debug/marqdo view public/00-welcome.mq.md --no-open
./target/debug/marqdo view tests/view/document-annot-demo.mq.md --no-open
cargo test -q --lib view::
```
---
## 7. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-10-15 | 初稿:四问题、错二进制/溢出/leader 根因、帧感知密度与 leader 几何约定 |
| 2026-10-15 | L-leader 拥挤/消失:同跨度多帧 chip **共用 annot id**;可见 chip 按锚点 x 重排;leader 挂 doc-block |
| 2026-10-15 | L-leader 黑线碎段:JS `border*: "1.5px solid"` 无色覆盖 class → 改为 kind 色写入 shorthand;chip SSR/DOM 按锚点 L→R |
| 2026-10-15 | L-leader 改为 SVG:描述底边中点 → 轨道 → 短竖线 → 值 chip 顶边中点;chip 间距加宽 |
+239
View File
@@ -0,0 +1,239 @@
# View:静态页交互与公式/代码卡视觉
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-10-15 |
| 相关 | [view.md](view.md) · [user-site.md](user-site.md) · [view-document-annotations.md](view-document-annotations.md) · [view-frame-selection.md](view-frame-selection.md) · [ADR 0002 browser WASM](../adr/0002-browser-marqdo-wasm.md) |
**已确认(2026-10-15)**
| 决策 | 选择 |
|------|------|
| 引擎 | **B**(快照 + S1 帧切换 + 可选懒加载 WASM S2) |
| 体验原则 | 静态页与 live view **尽量同构**;控件形态对齐;无服务端时用 WASM/JS 补齐 |
| 视觉原则 | **一层主视觉**;一眼能懂;公式/代码不与 Bind chip / 源残留叠床架屋 |
| 演示参数条 | **要**(历史实参 select + 可编辑;S1 切帧 / S2 重跑) |
| code-card Run | 有 WASM 时可用;否则隐藏(不对齐「假按钮」) |
| 公式 Bind chip | **卡内不显示**;Variables 可留终值 |
---
## 1. 动机(对照 `public/00-欢迎.mq.md` / gh-pages)
静态导出(`marqdo view output` → `gh-pages`)与 live `marqdo view` 已共用**文档面 Structure** 渲染路径,但用户站实测仍有三类落差:
1. **交互控件缺失 / 偏弱**
- 函数「问候」仅有参数 chip「谁」,没有可切换的调用帧下拉(即便源里 `> 问候` 写了两次)。
- 参数行 `+ 谁` 在文档面呈声明高亮,读者无法在静态页改「谁」并看到新输出。
- 外联 `code-card` 的 Run 在静态模式被禁用(`Run is available in live marqdo view`)。
- 静态 stdin 仅在有 preset 时显示只读提示,**不能**再跑。
2. **无服务端时仍可交互的预期**
用户站是纯静态托管:没有 `/api/run`。合理路径是 **页内 JS** 和/或 **嵌入 Marqdo WASM**,在浏览器里重算 Structure 标注、Execution 区,甚至模拟 `input` / 外联(沙箱约束另定)。
3. **公式 / 代码块视觉凌乱**
同一赋值同时出现多层表象,信息重复、线框错位:
| 层 | 公式 `f = $$…$$` | 外联 `hi = ```python…``` |
|----|------------------|---------------------------|
| A 卡片 | `formula` badge + KaTeX | `code` badge + 高亮源码 + cmd/Run |
| B 标注 chip | `f` → `x^2 - 2` | `hi` → 整段 fence 摘要 |
| C 源残留 | 卡片外/旁再露 `$$` 或 ASCII | 卡片下再露 `python print…` 明文 |
再叠加 CSS L-leader 与卡内边框,首屏显得碎、重复、「坏掉的线」。
**本文件只定问题与方案;确认前不改代码。**
---
## 2. 现状解剖
### 2.1 静态 vs live(同一 `page_file`)
| 能力 | Live | Static(`LinkMode::Static`) |
|------|------|------------------------------|
| 文档面 Structure + annot | ✅(跑后) | ✅(导出时跑后写入) |
| call / loop picker JS | ✅(读 `#mq-view-trace`) | ✅(同源 JS;若轨迹未写入则无控件) |
| `/api/run` · Stream | ✅ | ❌ |
| stdin 表单 | ✅ 可再跑 | 只读 hint(或无) |
| code-card Run | ✅ `POST` 外联 | ❌ 禁用按钮 |
| WASM 重算 | ❌(未接) | ❌(未接) |
结论:**不是「静态另做一套皮肤」**,而是「导出瞬间的快照 + 部分 JS 帧切换」;**没有**浏览器内重执行闭环。
### 2.2 欢迎页结构(问题复现源)
```text
> 问候 谁=marqdo
> 问候 谁=marqdo user
## 问候
+ `谁`
> 打印 内容=欢迎,`谁`!
`f` = $$ x^2 - 2 $$
`hi` = ```python … ```
```
- 期望:`## 问候` 旁 **调用** 下拉(`1: 谁=marqdo` / `2: 谁=marqdo user`),切换时打印行的绑定/输出随帧变。
- 现状风险:若导出时 CallFrame &lt; 2、或 picker 未挂上、或读者期望的是「编辑谁」而非「选历史调用」,都会表现为「没有下拉框」。
- 公式/代码:`SpecialAssign` → formula/code **card**,同时又对同名绑定建 **Bind annot**,文档面还可能保留块源视觉 → 三重展示。
### 2.3 已有红线(方案不得破坏)
- 代码即文档:`.mq.md` 源可读;不发明第二套嵌套 DSL(见 web-artifact / marqdo-dev)。
- Browse ≠ Debug:静态站不做断点。
- `public/**/*.html` 不入库;gh-pages 由 CI/`view output` 生成([user-site.md](user-site.md))。
- 外链字体禁令仍在 [view.md](view.md);WASM/重型资源须 **可选加载**,默认站可降级为纯快照。
---
## 3. 目标(验收口径)
### G1 — 帧与参数交互(静态可读、可拨)
1. 同函数 ≥2 次调用时,静态页 **必有**「调用」下拉;默认末次;切换只改 chip/臂/相关输出,**源码常显**(同 [view-frame-selection.md](view-frame-selection.md))。
2. 导出保证写入完整 `#mq-view-trace`(含 `calls` / `events` / 可选 `loops`)。
3. (增强)演示向参数可提供 **受控输入**:默认值来自末次调用或 FM;改参后可触发页内重算(见 §5 引擎选项)。
### G2 — 无服务端可重算(可选引擎)
| 档位 | 能力 | 依赖 |
|------|------|------|
| **S0 快照**(现状加强) | 导出时跑完;帧 picker;只读 Execution | 无 WASM |
| **S1 页内重放轨迹** | 不重跑程序,只切换已序列化帧/标注 | JSON only |
| **S2 WASM 重跑** | `marqdo_wasm` + bridge:改 stdin/实参后重跑,刷新 Structure/Execution | WASM 包(可 CDN/`public/wasm/`) |
| **S3 外联沙箱** | code-card Run:浏览器内 pyodide **或** 明确标「仅 live」 | 可选;默认可关 |
默认用户站:**S0 + S1 必达**;**S2 为推荐主路径**(与「用 wasm 模拟输出」对齐);S3 单独开关。
### G3 — 公式 / 代码视觉单层真相
对「特殊赋值」块约定 **一层主视觉 + 至多一层结果**:
| 块 | 主视觉 | 允许的结果层 | 禁止 |
|----|--------|--------------|------|
| 公式 | KaTeX(formula-card 精简) | 无 Bind chip,或仅在 Variables | 再渲一份 `$$` 明文;annot 与卡重复同一 TeX |
| 外联代码 | 高亮源码(code-card) | 运行输出区 `code-out`;静态可藏 Run 或接 S2/S3 | annot 再贴整段 fence;卡下重复裸源 |
| 普通赋值 | 标记面语句 | Bind chip + L-leader | — |
Leader:仅连接「主视觉锚点 → 唯一结果 chip」;卡内不用第二套 L 线。
---
## 4. 问题清单(成文)
| ID | 问题 | 严重度 | 根因假设 |
|----|------|--------|----------|
| P1 | 静态页看不到调用/循环下拉 | 高 | 轨迹未导出完整 / picker 条件(≥2)未满足 / 读者要的是编辑参而非选帧 |
| P2 | 不能改参/stdin 再看输出 | 高 | Static 禁用 `/api/run`;无 WASM 闭环 |
| P3 | code-card Run 静态无效 | 中 | `initForeignCards` 显式禁用 |
| P4 | 公式卡 + chip + `$$` 三重 | 高 | card 与 Bind annot 叠加;块源未完全被 SpecialAssign 吞掉 |
| P5 | 代码卡 + chip + 明文三重 | 高 | 同 P4 |
| P6 | 卡内/旁碎线、错位 | 中 | leader 锚到错误节点;卡 CSS 与 annot-band 叠层 |
| P7 | 静态 stdin 体验差 | 中 | 仅有只读 hint |
---
## 5. 解决方案(详案,待选)
### 5.1 引擎策略(三选一,推荐 **B**)
| 方案 | 做法 | 优点 | 代价 |
|------|------|------|------|
| **A. 纯快照 + S1** | 加强导出轨迹与 picker;不引入 WASM | 体积小、离线稳 | 不能改参真重算 |
| **B. 快照默认 + 可选 WASM(S0/S1/S2)** | `view output` 仍嵌入跑后 HTML;页脚/侧栏「在浏览器中重跑」懒加载 WASM;改参后 patch Structure/Execution | 对齐用户预期;无 WASM 时仍可读 | 打包/加载体积;宿主能力子集 |
| **C. 静态页全面 WASM 首屏** | 打开即 WASM 跑 | 交互最强 | 冷启动慢;gh-pages 带宽;与「文档先可读」冲突 |
**推荐 B**:文档先可读(S0),帧切换不依赖 WASM(S1),需要改参/演示时再拉 WASM(S2)。
### 5.2 交互控件(与文档面一致)
1. **调用 / 循环 picker**(已有组件)
- 导出验收:欢迎页「问候」必须出现调用下拉。
- 单测:对 `00-欢迎.mq.md` / `document-annot-demo` 断言 HTML 含 `call-picker` 且 options≥2。
2. **演示参数条(新,窄范围)**
- 仅当函数被标记为「可演示」**或**静态页检测到 ≥1 形参且存在 CallFrame 时,在函数标题旁增加:
`谁 [ text input | select(历史实参) ] [应用]`
- **不**改 `.mq.md` 语法;数据来自 trace 的 `args_brief` / 末次绑定。
- 「应用」:S1 仅切换已有帧;S2 调 WASM `run` 后替换 `#structure` / Execution。
3. **stdin**
- 静态:若源含 `input`,渲染与 live 同形的 textarea +「重跑」(S2)或说明「需 WASM」。
- 无 input 则不显示。
### 5.3 公式 / 代码去重(视觉)
**规则:SpecialAssign 行只走 card,不再为同名同值挂 Bind chip。**
```text
公式赋值行
└─ formula-card(badge + 名 + KaTeX)
└─ ✗ 不再 render_annot_band(Bind f)
└─ ✗ 不再在卡外输出 $$ 源
外联赋值行
└─ code-card(badge + 名 + 高亮体 + 可选 Run)
└─ ✗ 不再 Bind chip 贴 fence 全文
└─ 运行结果只进 .code-out
```
静态 Run 策略(与 §5.1 对齐):
- S0:隐藏 Run,或保留禁用并 tooltip「打开 live view / 启用 WASM」。
- S2:Run → WASM 宿主 `foreign`(若 WASM 支持)或提示不支持。
- S3:可选 Pyodide(默认关)。
CSS:formula-card / code-card 与 `.annot-band` 垂直节奏统一;禁止对 KaTeX 节点拉 L-leader。
### 5.4 导出管线
```text
marqdo view output
→ build_file_view(跑 + annot + trace_json) // 已有
→ page_file(Static)
+ 嵌入 #mq-view-trace
+ (可选)data-wasm-url / 懒加载脚本
+ 公式/代码去重后的 structure_html
→ public/ + gh-pages
```
`--no-exec`:文档面无标注;可提示「本页为结构-only」;S2 仍可尝试 WASM 首跑(可选,默认关以免惊喜执行)。
### 5.5 明确不做(本提案)
- 静态页断点调试(仍属 `marqdo debug`)。
- 在 `public/*.mq.md` 发明新的「交互表」DSL(除非另开设计并获批)。
- 默认全站加载 Pyodide。
- 提交生成 HTML 进 `main`。
---
## 6. 分阶段开发计划(确认后执行)
| 阶段 | 内容 | 交付 | 依赖确认 |
|------|------|------|----------|
| **D0** | 本文定稿;选定引擎 **A/B/C**;是否要「演示参数条」 | 状态 → Active | **本次决策** |
| **D1** | P4/P5/P6:SpecialAssign 与 Bind 互斥;卡 CSS;去掉重复源 | 欢迎页公式/代码干净;单测 | D0 |
| **D2** | P1:导出轨迹验收 + 欢迎页 call-picker 金样;修任何「≥2 调用无下拉」bug | HTML 断言 | D0 |
| **D3** | P2/P7 S1 夯实:静态 stdin UI 形态;无 WASM 时文案清晰 | UX | D0 |
| **D4** | (若选 B)S2:静态页懒加载 WASM;「应用参数 / 重跑」刷新 Structure+Execution | `public/wasm` 或 CDN 策略;体积预算 | D0=B |
| **D5** | P3:code-card 与 S2/S3 策略落地;默认隐藏无效 Run | — | D1+D4 |
| **D6** | `build-public` / pages CI 回归;更新 [user-site.md](user-site.md) · [view.md](view.md) 验收条 | gh-pages 抽检欢迎页 | D1–D5 |
建议默认路径:**D0 选 B → D1 → D2 → D3 → D4 → D5 → D6**。
---
## 7. 决策记录
见文首「已确认」。开发按 §6:D1 → D2 → D3 → D4 → D5 → D6。
---
## 8. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-10-15 | 初稿:静态交互缺口、公式/代码凌乱、S0–S3 与阶段 D0–D6 |
| 2026-10-15 | Active:引擎 B;对齐 live;干净视觉;演示参数条;Run 接 WASM 否则隐藏 |
+6 -4
View File
@@ -4,7 +4,7 @@
|---|---|
| 状态 | 已定(v0.0.2 方向) |
| 日期 | 2026-08-04 |
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [view-markup-surface.md](view-markup-surface.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [view-markup-surface.md](view-markup-surface.md) · [view-document-annotations.md](view-document-annotations.md) · [view-static-interactive.md](view-static-interactive.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
---
@@ -77,7 +77,7 @@ OUT_DIR/
- 用户文档推荐流程:`marqdo view output public -o public`,将生成物发布到 `gh-pages`(见 [user-site.md](user-site.md))。
- **执行权限**:与 `marqdo run` 一致(导入即用);view/导出仅对 `exit`/`sleep` 做软化,避免拖垮进程。详见 [stdlib-modules.md](stdlib-modules.md) §6。
- 金样例浏览仍可用:`marqdo view output tests -o /tmp/mq-tests`(含 errors,勿当对外用户站)。
- 渲染逻辑与实时 `view` **共用**同一套 HTML 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
- 渲染逻辑与实时 `view` **共用**同一路径:`build_file_view` → 文档面 Structure(`document.rs` + annots)→ `page_file`(同一 CSS/JS,含 call/loop picker、`#mq-view-trace`)。禁止第二套皮肤。`--no-exec` 时仍出文档面,但无运行标注。
示例:
@@ -90,14 +90,16 @@ marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
## 4. 信息架构
侧栏文件索引 + 主区:结构(AST+注释)· 执行 · 源码。结构旁**右侧栏**(现有 outline 槽)为:
侧栏文件索引 + 主区:**文档面 Structure** · 执行 · 源码。Structure(Browse)为叙述保真文档面:标记面(变量/语句/返回无源码定界符)、表/列表/分支结构保真,跑后结果经 **CSS L-leader** 引出——见 [view-document-annotations.md](view-document-annotations.md) · [view-execution-trace.md](view-execution-trace.md)。**不是** AST 卡片栈(那是 debug)。
结构旁**右侧栏**(现有 outline 槽)为:
| 区块 | 内容 |
|------|------|
| **Functions** | 原函数大纲 + 搜索;可折叠(默认展开) |
| **Variables** | 跑完后的入口(`# main`)顶层绑定只读快照;List/Map/`@` 行向渲成 HTML 表;可折叠(默认展开) |
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板。
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板;终态亦可刷新 Structure 内标注。
表达式为表面语法。**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
+12 -5
View File
@@ -2,16 +2,23 @@
| | |
|---|---|
| 状态 | **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 项目」所需能力的差距清单与补强路线 |
| 状态 | **Historical capability matrix** — 作者面以 **[ext-web-artifact.md](ext-web-artifact.md)** / ADR [0007](../adr/0007-web-document-endpoint.md) 为准(2026-09-28) |
| 日期 | 2026-08-26(初稿)· 2026-08-28(完结复核)· 2026-09-28(Artifact 标注) |
| 相关 | [ext-web-artifact.md](ext-web-artifact.md) · [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` 现状;**下文 API 名多为 W0–W7 历史面**(`compose_*` / `configure` 已废止) |
> **2026-09-28**:作者面迁移到 Document / Endpoint / Resource。
> - Document/Endpoint:`type: web|endpoint` + `web.serve` / `web.render` / `web.inspect`
> - DB/cache/storage → `ext/data`;auth/oidc/rbac → `ext/security`;ws → `ext/net`
> - 统一 View:`|type|slot|value|attrs|style|`;中间件:`web.use`
> 本文件保留为**原生能力矩阵**对照,勿再按 `compose_*` / `app.configure` 写作。
---
## 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` 作者面**。
**能力层(plugins/web)**:中间件/JSON API、数据层、安全、内容站点、上传下载、sitemap、WebSocket 等仍在原生实现中。
**作者面(2026-09-28)**:改为 Artifact Metadata + facade;`compose_*` / `configure` **已删除**。边界不变:**纯解析进 `lib/net`,HTTP 服务器进 `plugins/web`,作者 API 进 `ext/web` + `ext/data` + `ext/security` + `ext/net`**。
**宿主集成下一刀**(同域 LLM SSE 中继、HTTP→用户 `##`、与 MCP Server 协作)不在本 W 表内,见 [ext-hosting-gaps.md](../research/ext-hosting-gaps.md) · [ext-hosting-fill.md](ext-hosting-fill.md) · [ext-hosting.md](../roadmap/ext-hosting.md)。
+2626
View File
File diff suppressed because it is too large. Load diff
+541
View File
@@ -0,0 +1,541 @@
有时候可能用户不太好接入Jev,所以阶段4应该要允许用户使用小参数的模型代替,你认为呢?
我非常赞同,而且我甚至建议**不要把 Jev 作为阶段 4 的必选组件**。
更准确的设计应该是:
> **Jev 是一种可选的决策器(Decision Engine),小参数模型是另一种可选实现;Marqdo Agent 本身只规定“需要一个 Router/Policy”,而不规定 Router 必须由什么实现。**
这样会让整个框架开放很多。
### 1. 阶段 4 应该改成“Adaptive Routing”
原来的:
```text
Phase 4
↓
Jev Router
```
我建议改成:
```text
Phase 4: Adaptive Routing
│
┌─────────┼─────────┐
↓ ↓ ↓
Marqdo Rule Jev Small LLM
│ │ │
└─────────┼─────────┘
↓
Route Policy
```
甚至还可以允许:
```text
Rule
Small Model
Jev
Full LLM
```
混合使用。
---
# 2. 为什么这个设计更合理
因为用户真正需要的不是:
> “我要接入 Jev。”
而是:
> “我希望 Agent 学会以后,不要每次都调用大模型。”
这两个概念应该分开。
所以 Marqdo 只定义接口:
```text
agent.route(task, candidates)
```
至于内部怎么实现,可以是:
### A. 纯 Marqdo
```text
if task.type == "json":
return json-repair
if task.type == "search":
return corpus-search
```
完全不需要模型。
---
### B. 小参数模型
比如用户已经有:
```text
Qwen 0.5B
Qwen 1.5B
Llama 1B
某个本地模型
```
就可以:
```text
task
↓
small model
↓
"json-repair"
```
甚至可以让用户直接配置:
```yaml
router:
type: llm
provider: openai-compatible
base_url: ...
api_key: ...
model: ...
```
这和你之前设计 AI 斗蛐蛐时提出的 **OpenAI-compatible URL + Key** 思路其实也很契合。
---
### C. Jev
如果用户安装了 Jev:
```text
task
↓
Jev
↓
policy
```
那么就用 Jev。
---
### D. 大模型
甚至最开始没有任何 Router:
```text
task
↓
large LLM
↓
decide
```
也是合法的。
所以:
> **Router 是抽象能力,不是具体模型。**
---
# 3. 更重要的是:Router 本身也可以被学习
这里我觉得还能进一步提升你的设计。
一开始:
```text
Task
↓
Large LLM
↓
选择 skill
```
系统观察:
```text
task A → json-repair
task B → json-repair
task C → json-repair
task D → corpus-search
```
之后可以自动生成:
```text
router.mq.md
```
例如:
```markdown
---
type: policy
status: compiled
---
## route
1. `task.type` == "json"
*"json-repair"*
2. `task.type` == "search"
*"corpus-search"*
3. *
*"llm"*
```
那么你甚至不需要 Jev。
**Marqdo 自己的控制流就是 Router。**
---
# 4. 所以我会重新设计 Cost Ladder
之前的:
```text
L0 deterministic
L1 rule
L2 small model
L3 small LLM
L4 large LLM
L5 exploration
```
我建议改成:
```text
┌────────────────────────┐
│ Adaptive Router │
└───────────┬────────────┘
│
┌─────────────────┼─────────────────┐
↓ ↓ ↓
Deterministic Small Model Large LLM
│ │ │
↓ ↓ ↓
L0/L1 L2/L3 L4
│
↓
Exploration L5
```
这里最关键的是:
> **L2/L3 不应该规定具体模型。**
可以是:
```text
Marqdo rules
OR
Jev
OR
0.5B model
OR
1B model
OR
3B model
```
---
# 5. 我甚至建议用户可以配置多个 Router
例如:
```yaml
router:
candidates:
- name: rules
type: marqdo
- name: local
type: llm
model: qwen-0.5b
- name: jev
type: jev
- name: cloud
type: llm
model: ...
```
然后 Agent 自己选择:
```text
Task
↓
Router Resolver
↓
rules?
↓
confidence insufficient
↓
small model?
↓
confidence insufficient
↓
Jev?
↓
confidence insufficient
↓
large LLM
```
这就形成一个**分级决策系统**。
---
# 6. 最漂亮的地方:Router 也可以被编译
最终甚至可以:
```text
第一次:
LLM
↓
决定调用 Skill A
第二次:
LLM
↓
决定调用 Skill A
第三次:
LLM
↓
决定调用 Skill A
Learning
↓
发现稳定模式
Compile
↓
router.mq.md
```
以后:
```text
Task
↓
router.mq.md
↓
skill A
↓
execute
```
**0 LLM。**
于是整个 Agent 的学习就不只是:
```text
学习如何解决任务
```
而是同时学习:
```text
1. 学习如何解决任务
2. 学习什么时候使用什么技能
3. 学习什么时候需要大模型
```
这三个层次组合起来,我认为比单纯引入 Jev 更有意思。
---
# 7. 最终可以形成三级编译
我现在反而觉得你的 Agent Framework 可以把整个“学习”定义成三个阶段:
```text
Experience
↓
Skill Compilation
↓
Policy Compilation
↓
Execution Compilation
```
### 第一层:Skill Compilation
```text
LLM experience
↓
skill.mq.md
```
解决:
> **怎么做?**
### 第二层:Policy Compilation
```text
many task → skill mappings
↓
policy.mq.md
```
解决:
> **什么时候做什么?**
### 第三层:Execution Compilation
```text
skill + policy
↓
pure Marqdo execution
```
解决:
> **能不能完全不思考直接执行?**
这时候整个 Agent 就变成:
```text
Large LLM
│
Exploration
↓
Experience
↓
┌───────────────┐
│ Skill Compile │
└───────┬───────┘
↓
Skill MQ
│
┌───────┴───────┐
↓ ↓
Policy Compile Direct Execute
↓
Router MQ
│
↓
Skill Selection
│
↓
Execute
```
---
# 8. 因此 Phase 4 我建议正式改名
不要叫:
> Jev Router
而叫:
> **Adaptive Policy / Routing Layer**
然后提供四种 backend:
```text
router.backend = marqdo
router.backend = small-llm
router.backend = jev
router.backend = llm
```
甚至:
```text
router.backend = auto
```
让 Agent 根据可用环境自动选择。
---
## 9. 用户体验也会好很多
用户第一次安装 Marqdo:
```text
marqdo agent run ...
```
没有 Jev,也没有小模型。
完全没问题:
```text
→ 使用配置的大模型
```
用户后来配置:
```yaml
router:
backend: small-llm
provider: openai-compatible
model: qwen-0.5b
```
Agent 就自动变成:
```text
大模型:负责复杂推理 / 学习
小模型:负责日常路由
Marqdo:负责确定性执行
```
如果用户安装 Jev:
```yaml
router:
backend: jev
```
则:
```text
Jev:负责路由
大模型:负责复杂任务
Marqdo:负责执行
```
**用户完全不需要改变 Agent 的上层 API。**
---
我认为这个调整非常重要,因为它让 **Marqdo Agent 的核心创新从“依赖某个新模型”变成“模型无关的认知编译架构”**。
最终可以浓缩成一句话:
> **大模型负责探索,小模型/Jev 负责决策,Marqdo 负责执行;随着经验积累,探索和决策逐渐被编译成可执行的 `.mq.md`。**
这其实比“接入 Jev”本身更符合你最开始提出的 **Think → Execute → Learn → Compile → Reuse** 路线。
+1173
View File
File diff suppressed because it is too large. Load diff
+1335
View File
File diff suppressed because it is too large. Load diff
+2182
View File
File diff suppressed because it is too large. Load diff
+2818
View File
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,58 @@
# 缺陷记录:LLM 传输失败硬中断 Agent Runtime
| | |
|---|---|
| 状态 | **Fixed(2026-10-16)** — 见 §3;金样 `tests/ext/agent-llm-transport-soft.mq.md` |
| 日期 | 2026-10-16 |
| 发现方 | qdagent(接通 `agent.run` live 路径时) |
| 影响面 | `host/net` · `plugins/llm` · `ext/ai/llm` · `ext/ai/llm/openai` · `ext/ai/agent` |
| 相关 | [agent-run-efi-resolve-bugs-2026-10.md](agent-run-efi-resolve-bugs-2026-10.md) · [ext-agent.md](../design/ext-agent.md) |
---
## 0. 一句话
上游 LLM **连接拒绝 / 超时 / 非 200** 时,Runtime 曾以 **硬错误** 终止整个 `marqdo run`;产品(qdagent ASK/BUILD)无法落到结构化 `status=error`。
---
## 1. 复现
```bash
OPENAI_API_KEY=offline OPENAI_BASE_URL=http://127.0.0.1:9 \
marqdo run tests/ext/agent-llm-transport-soft.mq.md
# 修复前:exit≠0,error: http POST …
# 修复后:exit 0,ask/step/run 均带 finish|status=error + error 文本
```
---
## 2. 根因
| 层 | 行为 |
|----|------|
| `host_http_post` / SSE | 传输失败 `Err(...)` → VM abort |
| `plugins/llm` `llm_chat_completions` | 同上 `Err` |
| `ext/ai/llm/openai` | HTTP≠200 → `sys.exit 1` |
| `agent.model_turn` / `step` / `plan` | 无软失败臂 |
---
## 3. 修复清单
| # | 改动 | 文件 |
|---|------|------|
| 1 | 传输失败 → `{status:0, body}` / SSE error event | `src/host/net.rs` |
| 2 | 插件返回 `{finish:error, error, …}` 而非 `Err` | `plugins/llm/src/lib.rs` |
| 3 | openai 非 200 → 结构化 pack,禁止 `sys.exit` | `ext/ai/llm/openai.mq.md` |
| 4 | `llm.ask` 透传 `error` / `finish` | `ext/ai/llm.mq.md` |
| 5 | `model_turn` / `step` / `plan` 收成 `status=error` | `ext/ai/agent.mq.md` |
| 6 | 金样 | `tests/ext/agent-llm-transport-soft.mq.md` |
**契约**:Agent Runtime 对 LLM 传输失败必须可捕获;`status=error` + `error` 字符串;进程退出码 0(程序正常返回错误图)。
---
## 4. 对 qdagent
`ensure_llm` 有 key 但上游不可达时,`ask`/`build` 可走既有 `mode=error` 臂写 workbook,不再整 CLI 崩。
@@ -0,0 +1,117 @@
# 缺陷记录:`agent.run` EFI / resolve 在消费方崩溃(qdagent 复现)
| | |
|---|---|
| 状态 | **Fixed(2026-10-16)** — 见 §3;金样 `tests/ext/agent-run-cold-efi.mq.md` |
| 日期 | 2026-10-16 |
| 发现方 | qdagent(`~/work/qdagent`)接通 Marqdo ≥1.4.2 Agent EFI 全路径时 |
| 影响面 | `ext/ai/agent` · `## run` · `plugins/agent` `agent_resolve` |
| 相关 | [ext-agent.md](../design/ext-agent.md) · [engineering-knowledge.md](../design/engineering-knowledge.md) · [ai-agent-llm-optimize-2026-10.md](ai-agent-llm-optimize-2026-10.md) |
---
## 0. 一句话
`agent.run` 在 **空 OKF / 无 skill 命中** 或 **`efi=True`** 时,会以硬错误退出,而不是降级到 `plan` 探索。
这是 **Agent Runtime 契约不完整**,不是 qdagent 业务写错。
---
## 1. 复现(qdagent)
环境:工作区 Marqdo `1.4.2` + `MARQDO_EXT=~/work/marqdo/ext`;qdagent 调用:
```text
助手 = > agent.agent …
`助手`.run task=… efi=True # 或 efi=False 后仍进 resolve
```
本仓几乎没有 `.marqdo/agent-kb` 编译 skill。
### Bug A — `efi=True` → `unknown function preflight`
**位置**:[`ext/ai/agent.mq.md`](../../ext/ai/agent.mq.md) `## run`
```markdown
1. `efi`
**efi_pf = preflight task=`task`**
```
同文件其它同对象方法一律写 `` `self`.route `` / `` `self`.resolve ``。
裸标识 `preflight` 在导入消费方(如 `cli/求道-构建.mq.md`)里被解析成**全局函数**,找不到 → 硬错。
**期望**:`` **efi_pf = > `self`.preflight task=`task`** ``(或等价 method call)。
### Bug B — miss resolve → `missing map key llm_free`
**位置**:
1. Plugin:[`plugins/agent/src/memory.rs`](../../plugins/agent/src/memory.rs) `resolve_task`
当 `kb_lookup` 返回 null:
```rust
Ok(json!({
"mode": "unknown",
"skill": null,
"resource": null,
"confidence": 0.0,
// 缺 llm_free
}))
```
2. Facade:`## run` 在 resolve 之后:
```markdown
**llm_free = [llm_free](resolved)**
```
脚注式取键在缺键时 **硬失败**,无法落到后面的 `plan` 探索臂。
**期望**:
- miss 结果始终带 `"llm_free": false`(与命中路径字段集对齐)
- facade 侧对可选键用 `json.get`(缺省 `False`),防御其它调用方
---
## 2. 为何金样没拦住
| 金样 | 为何漏网 |
|------|----------|
| `tests/ext/agent-zero-llm.mq.md` | 先编译 skill / policy,再 `run`;resolve **命中** |
| `tests/ext/eng-preflight.mq.md` | 只测 `agent_eng_preflight`,**不**走 `agent.run efi=` |
| 多数 `agent-*-live` | 自带 kb 或 `efi=False` / 不经过 cold miss |
qdagent 是第一个「冷库 + 产品 EFI + `run`」消费方,因此打穿。
---
## 3. 修复清单(本轮)
| # | 改动 | 文件 |
|---|------|------|
| 1 | miss resolve 补 `llm_free: false` | `plugins/agent/src/memory.rs` |
| 2 | `` `self`.preflight ``;`llm_free`/`mode` 用 `json.get` | `ext/ai/agent.mq.md` |
| 3 | 回归金样:冷 kb + `run efi=True` 不崩溃,落到 explore/plan | `tests/ext/agent-run-cold-efi.mq.md` |
| 4 | 重建 `marqdo_plugin_agent` 并跑金样 | `cargo build -p marqdo_plugin_agent --release` |
---
## 4. 对 qdagent 的含义
修复后 qdagent 可恢复:
```text
product preflight → latch → agent.run (efi=True|False) / plan
```
而不必长期绕开 `agent.run`。
在插件未装入新 so 前,qdagent 侧 EFI latch + `step`/`plan` 仍是合法降级。
---
## 5. 非目标
- 不改 EKC / `agent_eng_preflight` 语义
- 不引入第二套 Agent loop
- 不把向量检索升为权威真相
@@ -0,0 +1,136 @@
# 调研:代码即文档 × OKF × 沙盒 下的智能体 / 大模型优化(2026-10)
| | |
|---|---|
| 状态 | **调研 + 问题分析 · 供方案 [ext-ai-optimize.md](../design/ext-ai-optimize.md) 参考** |
| 日期 | 2026-10-16 |
| 前置 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) · [agent-framework-2026-09.md](agent-framework-2026-09.md) · [ai-agent-sandbox.md](ai-agent-sandbox.md) · [okf-and-marqdo.md](okf-and-marqdo.md) |
| 本仓能力 | [ext-agent.md](../design/ext-agent.md) · [okf.md](../design/okf.md) · [engineering-knowledge.md](../design/engineering-knowledge.md) · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) · [ai-stack.md](../roadmap/ai-stack.md) · [ext-agent-optimize.md](../roadmap/ext-agent-optimize.md) |
| 外部抽样 | Anthropic Agent Skills · SoK Agentic Skills (arXiv 2602.20867) · ForgeAgent · ACES / Skill Lift · Switchcraft 路由 · DSPy/GEPA ·「工作流编译进权重」· MalSkillBench |
---
## 0. 一句话
业界正把 Agent 优化从「更好的 chat loop」转向 **可验证、可复用、可隔离执行的技能层**;Marqdo 已具备 **可执行 Markdown(代码即文档)+ OKF/EKC 复用 + CoW 沙盒** 三件套,优化目标应是把这三件套焊成闭环:**试跑 → 证据 → 晋升 → 零/少 LLM 复用**,而不是追平 LangChain 功能清单。
---
## 1. 调研方法
| 动作 | 说明 |
|------|------|
| 扫业界技能层 | Anthropic Skills(渐进披露 `SKILL.md`);SoK Agentic Skills 生命周期;ForgeAgent「能力铸造」;ACES Skill Lift |
| 扫成本/路由 | Switchcraft 工具调用路由;DSPy+GEPA 提示优化;工作流编译进小模型权重 |
| 扫安全 | MalSkillBench 运行时验证恶意技能;沙盒粒度讨论(per-skill / per-session) |
| 对照本仓 | A0–A4 / Wave B 已落地;沙盒 S0–S4 已落地;OKF + EKC + adaptive routing 现状 |
**不修改** `doc/next/*`(手写真相源);本文件只进 `doc/research/`。
---
## 2. 业界态势(与 Marqdo 相关的收敛点)
### 2.1 技能层取代「纯工具调用叙事」
| 来源 | 要点 | 对 Marqdo |
|------|------|-----------|
| Anthropic Agent Skills | 目录 + `SKILL.md`;元数据预载、正文按需;脚本可执行 | 形态近 OKF 任务包,但 Marqdo 技能 **本身可跑** |
| SoK Agentic Skills | 发现→练习→蒸馏→存储→组合→评测→更新;代码技能需沙盒 | 生命周期与 OKF promote / sandbox.run 对齐 |
| ForgeAgent | 生成能力 → 沙盒证明 → 信任复用;失败进回归隔离 | **验证后晋升** 正是 solidify / `llm_free` 缺的硬闸 |
| ACES | 有/无技能配对试验 → Skill Lift | 可作 Marqdo 评测 harness 指标 |
### 2.2 成本:路由 + 编译 + 小模型
| 来源 | 要点 | 对 Marqdo |
|------|------|-----------|
| Switchcraft | 工具调用场景路由到最便宜仍正确的模型;报道大幅降本 | 已有 `marqdo \| small-llm \| llm \| auto`;可加 **工具步/试跑步** 细分 |
| DSPy / GEPA | 用反馈改写指令,小模型追上大模型 | 优化对象应是 **`.mq.md` 提示文档 / standing / 路由策略文件**,不是黑盒字符串 |
| 工作流编译进权重 | 程序化流程进小模型权重,上下文常数级 | 长期对应「高频 OKF 技能 → 专用小模型」;短期优先 **llm_free 源码路径** |
### 2.3 安全:技能不可信 + 沙盒必验
恶意技能基准与 SoK 均强调:**技能说明与代码默认不可信**,须运行时隔离。Marqdo 新沙盒(默认拒 plugin/net/exec)正好是技能晋升前的证明场。
---
## 3. Marqdo 已有资产(优化起点)
| 资产 | 现状 | 优化杠杆 |
|------|------|----------|
| 代码即文档 | `.mq.md` = 程序 = 提示工作面;GFM 表 / 链接取元 | 减少 json 胶水;让模型「看见」结构 |
| 写回 | `marqdo-out` 槽;step 默认写回 | 晋升证据、失败避坑 |
| OKF / agent-kb | 命中 / near / promote / solidify / `llm_free` | 复用率、降本主轴 |
| EKC / EFI | L0–L4 catalog;preflight REUSE/ADAPT/CREATE | 生成前先查工程知识 |
| Adaptive routing | marqdo / small-llm / llm / auto + policy 文件 | 再细分 sandbox 试跑 vs 开放推理 |
| Sandbox | CoW + capped `run`;`ext/ai/sandbox` | **试跑闸门**;未 commit 不污染仓库 |
| MCP / corpus | 证据工具,`authority=workbook` | 保持不升权威 |
---
## 4. 问题分析(差距,不是功能羡慕)
### P1 — 试跑与晋升未焊死
沙盒已能 CoW 试跑,但 **`agent.step` / `plan` 默认仍可直接改真实树**;OKF `llm_free` 晋升不强制「沙盒金样绿」。
→ 风险:未验证技能进入复用池(业界 ForgeAgent / MalSkillBench 已证明此问题)。
### P2 — 技能形态双轨
Anthropic Skills = 文件夹 + 渐进披露;Marqdo = 可执行 `.mq.md` + OKF 类型。
→ 机会:用 **OKF frontmatter + 可执行体** 统一,不必引入第二套 SKILL.md 权威;缺的是 **披露层级与验证元数据**(适用条件、fixture、sandbox profile)。
### P3 — 路由粒度偏粗
现有路由偏「整任务后端」;未区分:查 OKF / 写补丁 / 沙盒 `run` / 对外 HTTP。
→ Switchcraft 启示:按 **步骤类型** 选模型,且「便宜模型推理 token 爆炸」要计入总成本。
### P4 — 评测未锁差异化
Wave B1 仍 Active:缺稳定 **Skill Lift / 沙盒证明率 / llm_free 命中率 / 文档可读性** 指标。
→ 没有指标,优化会滑回「多调几次模型」。
### P5 — 代码即文档在 Agent 产出侧仍易腐化
模型仍可能吐 `json.set` 链、混用 EN/ZH API、跳过表结构。
→ 沙盒可跑通语法,但 **风格门禁**(lint / preflight)未默认卡在 commit 前。
### P6 — 上下文与 EKC 未默认进每步
EFI / catalog 能力在,但 step 默认上下文仍可能偏源码切片,缺少「先 REUSE」硬门槛。
### P7 — LLM 表面与 Agent 成本账未统一
`llm.ask` / `stream` / usage 已有;Agent 侧缺 **按会话/技能的成本仪表盘** 写回文档(可 git 审)。
---
## 5. 优化目标函数(建议)
在固定任务集上最大化:
\[
\begin{align*}
& \text{ReuseRate}(\text{OKF hit} + \text{llm\_free}) \\
&+ \text{SandboxProofRate}(\text{试跑绿再 commit/promote}) \\
&- \lambda_1 \cdot \text{TokenCost} - \lambda_2 \cdot \text{HostMutationsWithoutCommit}
\end{align*}
\]
约束:权威真相仍是 `.mq.md`;不引入隐藏 TOOL 主循环;不改 `doc/next/*`。
---
## 6. 外部资料索引(抽样)
| 类型 | 链接 |
|------|------|
| Skills | [Anthropic engineering: Agent Skills](https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills) · [Claude Code skills](https://code.claude.com/docs/en/skills) · [agentskills / anthropics/skills](https://github.com/anthropics/skills) |
| 论文 | [SoK: Agentic Skills](https://arxiv.org/html/2602.20867) · [Skill Issue (repo SKILL 优化)](https://arxiv.org/html/2609.12742v1) · [ACES Skill Lift](https://arxiv.org/html/2608.20614) · [MalSkillBench](https://arxiv.org/html/2606.07131v3) · [Compiling workflows into weights](https://arxiv.org/html/2605.22502) |
| 开源/产品 | [ForgeAgent](https://github.com/Yashasm18/ForgeAgent) · [DSPy GEPA](https://dspy.ai/current/getting-started/gepa-optimization/) · [Switchcraft](https://www.microsoft.com/en-us/research/publication/switchcraft-ai-model-router-for-agentic-tool-calling/) |
---
## 7. 结语
Marqdo 不缺「再一个 Agent SDK」;缺的是把 **文档真相、知识晋升、沙盒证明、模型路由** 收成可度量闭环。下一篇方案文档按问题编号给出可选方向与推荐波次,**不预设唯一银弹**。
+392
View File
@@ -0,0 +1,392 @@
# 调研:AI 扩展库沙盒设计(执行隔离 × 工作区暂存 × 写回)
| | |
|---|---|
| 状态 | **调研笔记 · 供 `ext/ai/*` 沙盒设计锁定参考**(**2026-10-16 修订**:纳入「AI 只生成 Marqdo」产品约束) |
| 日期 | 2026-10-16 |
| 范围 | 浏览器 WASM / WASI、OS 进程沙盒、容器 / microVM、CoW 叠加工作区、符号链接暂存方案;对照 Marqdo AI 栈 |
| 相关设计 | **[ext-ai-sandbox.md](../design/ext-ai-sandbox.md)** · **[roadmap/ext-ai-sandbox.md](../roadmap/ext-ai-sandbox.md)** · [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [stdlib-writeback.md](../design/stdlib-writeback.md) · [stdlib-subtask.md](../design/stdlib-subtask.md) · [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) · [adr/0002-browser-marqdo-wasm.md](../adr/0002-browser-marqdo-wasm.md) · [ai-stack.md](../roadmap/ai-stack.md) · [ext-abi.md](../design/ext-abi.md) · [stdlib-modules.md](../design/stdlib-modules.md) |
| 姊妹调研 | [agent-frameworks-and-marqdo.md](agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](agent-framework-gaps-after-a4.md) · [ai-agent-llm-optimize-2026-10.md](ai-agent-llm-optimize-2026-10.md) · [ext-ai-optimize.md](../design/ext-ai-optimize.md) |
---
## 0. 一句话结论
**在「Agent 只生成 / 只执行 Marqdo(`.mq.md`)」这一产品约束下,Marqdo AI 沙盒应以 Wasm 为主沙盒——且必须是「内核 + `lib/*` + `ext/*`」可运行的完整运行时沙盒,而不是只跑光秃解释器。**
锁定方向:
1. **执行隔离 = Marqdo Wasm 运行时(与 ADR 0002 同构)** — deny-by-default 能力导入;**默认不授予** shell / 外联 / `dlopen` 原生插件。AI 产出面收窄到 Markdown 程序后,不必为通用 coding Agent 的「任意二进制」付沙盒税。
2. **库完备性是验收线,不是加分项** — 沙盒内须能 `import lib/…` 与受支持的 `ext/…`;缺能力时 **显式失败**,禁止静默空成功(对齐 [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §5)。
3. **工作区突变 = CoW / whiteout / 显式 commit**(应用层 VFS,必要时 overlay)— 「修改短暂不生效 → 确认写回」保留;**禁止以符号链接森林作为隔离边界**。
4. **OS 沙盒 / microVM** — 降为 **逃逸舱 / 托管 Profile**:仅当显式启用 foreign、`subtask` 真子进程、或未来多租户托管时使用;**不是** Marqdo-only Agent 的默认主路径。
初稿曾按「通用 coding Agent 还需 shell」把 Wasm 与 bwrap 并列;在 Marqdo-only 约束下,主结论改为 **Wasm-first + 库完备 + CoW 写回**。
---
## 1. 调研方法与边界
### 1.1 做了什么
| 动作 | 说明 |
|------|------|
| 厂商/产品文档 | Anthropic Claude Code sandbox / `@anthropic-ai/sandbox-runtime`;VS Code Copilot agent sandboxing;Docker AI Sandboxes;Turso AgentFS CoW overlay;OpenSandbox isolation sessions;WASI / jco preview2-shim;VS Code for the Web WASM webshell |
| 工程对比文 | Northflank / Cosmonic 2026 agent sandbox 指南;gVisor vs Firecracker vs Docker 对比;ContainAI security comparison |
| 学术与标准 | USENIX SEC'22 *Provably-Safe Multilingual Software Sandboxing using WebAssembly*;KTH 论文 *Intra-process Fault Isolation Using WebAssembly*(SFI 通信开销);ACM TOSEM *Research on WebAssembly Runtimes: A Survey*(2025);WASI Design Principles(capability / 无 ambient authority) |
| 安全案例 | brig 项目挂载 symlink 逃逸(CVSS 8.2);Anthropic sandbox-runtime 对 bwrap bind 跟随 symlink 的修复;Docker Sandbox「direct mount vs clone」威胁说明 |
| 对照本仓 | `ext/ai/{llm,agent}`、`lib/writeback`、`lib/subtask`、ADR 0002 浏览器 WASM、`RunOptions.allow_fs_write` 默认关 |
### 1.2 不做的
- 不把「发版用的容器镜像」与「Agent 工具沙盒」混为一谈。
- 不宣称某一云厂商托管沙盒(E2B / Modal / Daytona)为 Marqdo 默认依赖。
- 不修改 `doc/next/*`(手写真相源);本文件只进 `doc/research/`。
### 1.3 产品约束(修订要点):AI 只生成 Marqdo
这是相对通用 coding Agent(Claude Code / Codex)的 **结构性好消息**:
| 通用 Agent | Marqdo AI Agent(本调研采纳) |
|------------|------------------------------|
| 模型可产出 shell / Python / 任意仓库补丁 | 模型产出面收束为 **`.mq.md`(文档即程序)** |
| 沙盒必须兼容「整台开发机能力」 | 沙盒只需跑 **同构 Marqdo 运行时** |
| Wasm 往往只能罩住工具子集 | Wasm **可以**成为主执行边界 |
| 标准库 = 语言运行时 + OS 工具链 | 标准库 / 扩展 = **`lib/*.mq.md` + `ext/**`(+ 受控宿主能力)** |
硬规则建议(后续 design 应写死):
1. Agent 工具表 **不提供** 通用 `bash` / 任意语言 `exec`(除非显式 opt-in 逃逸舱,且另套 OS 沙盒)。
2. Agent 改仓库的权威动作是 **写 / 修订 `.mq.md`(含写回块)**,经 CoW 会话再 `commit`。
3. 运行 Agent 生成的程序 = 在沙盒里 `run` 该 `.mq.md`,且其 `import` 的 **lib 与 ext 必须可用或显式报不可用**。
### 1.4 威胁模型(在 Marqdo-only 下收窄)
| 威胁 | 典型路径 | Marqdo-only 下的权重 |
|------|----------|----------------------|
| T1 提示注入 | 诱导读密钥、外泄、破坏 `.mq.md` | 仍高 — 靠能力拒绝 + CoW |
| T2 工具侧信道 | `subtask`/`foreign` 子进程 | **默认关闭**;opt-in 才升权 |
| T3 工作区即时破坏 | 直接写穿源树 | 靠 CoW;commit 闸门 |
| T4 挂载逃逸 | symlink / bind 打穿 | 仍相关 — **勿用 symlink 作 W 层** |
| T5 网络外泄 | `lib/net` / llm 出站 | 能力开关 + 域名策略 |
| T6 Wasm 宿主桥过宽 | `host_fs_*` / 插件桥过宽 | **主威胁** — 桥 = 权限表 |
| T7 库残缺假安全 | 沙盒能跑 `# main` 但 `import lib/fs` 怪崩或静默空 | **产品验收威胁** |
**成功标准:** 失败域止于会话 upper + 已授予能力;真实工作区默认只读直至 commit;**代表性 `lib/*` 与 `ext/*` 金样在沙盒内可跑或得到明确 `unavailable in sandbox` 诊断**。
---
## 2. 先拆三个「沙盒放哪里」(Marqdo-only 版)
业界「Harness / Workspace / Execution」三分法仍成立,但 **Execution 的内容变了**:
```text
┌──────────────────────────────────────────────────────────┐
│ Pattern H — Harness(编排环) │
│ ext/ai/agent · parent Plan-and-Move ·(可选)MCP client │
├──────────────────────────────────────────────────────────┤
│ Pattern W — Workspace mutation(.mq.md 真相如何变) │
│ CoW upper / whiteout / diff / commit → writeback │
├──────────────────────────────────────────────────────────┤
│ Pattern X — 执行 Agent 产出的 Marqdo 程序 │
│ Wasm Marqdo runtime + embedded/packaged lib + sandboxed │
│ ext 能力面(非「任意 shell」) │
└──────────────────────────────────────────────────────────┘
```
| Pattern | Marqdo 落点 | 沙盒要解决什么 |
|---------|-------------|----------------|
| H | `ext/ai/agent` | 编排是否持有过宽宿主权限;模型 I/O 与执行隔离 |
| W | `lib/writeback` · 工作簿 | 编辑是否立刻污染仓库;人审/父裁决后落盘 |
| X | **Wasm 内 `run` `.mq.md`** | 计算隔离;**lib/ext 能力是否完备且受控** |
用户提案在 Marqdo-only 下:**Wasm 作 X 主底层是正确方向**;仍须改掉 symlink,并补上 **库完备性** 这一环。
---
## 3. 方案谱系(横向对比)
> **读法(修订后):** 下表仍保留通用 Agent 对照。对 **Marqdo-only** 产品,请以 §0 / §5 / §6 的 Wasm-first 结论为准;本节 A/B 升权,F/G/H 降为逃逸舱或托管。
评分:● 强 / ◐ 中 / ○ 弱 / — 不适用。维度按「隔离强度」等客观属性;**产品适配**见 §5。
| 方案 | 隔离强度 | 启动成本 | 任意二进制 | 工作区暂存语义 | 与 Marqdo 契合 | 主要风险 |
|------|----------|----------|------------|----------------|----------------|----------|
| **A. 浏览器 WASM + 虚拟 FS** | ●(计算)◐(经桥的 FS) | ● | ○ | ◐(需自建 overlay) | ●(已有 ADR 0002) | 宿主桥过宽;无原生 toolchain |
| **B. WASI / Component Model(非浏览器亦可)** | ● | ● | ○(仅 WASI 目标) | ●(preopens + 自建 VFS) | ● | 工具链不全则需降级 |
| **C. 符号链接映射工作区 + 延迟写回** | ○ | ● | —(本身不是执行沙盒) | ◐(似是而非) | ○ | **symlink 逃逸是已知高危类** |
| **D. 应用层 CoW VFS(upper/lower/whiteout)** | ◐(逻辑) | ● | — | ● | ●● | 必须配合 X 层 OS 隔离 |
| **E. OS overlayfs / FUSE / AgentFS 式 CoW** | ●(配合命名空间) | ◐ | ●(在沙盒内) | ●● | ● | Linux/macOS 实现分叉;运维 |
| **F. bubblewrap / Seatbelt(Anthropic SRT 类)** | ● | ● | ● | ○(默认可写 cwd) | ● | 需另加 CoW 才有「暂不生效」 |
| **G. Docker / 硬化容器 / gVisor** | ◐→● | ◐ | ● | ◐(volume 策略) | ◐ | 共享内核或兼容性;重 |
| **H. microVM(Firecracker / Kata)** | ●● | ◐ | ● | ◐ | ○(本地 CLI 过重) | KVM/运维;适合多租户托管 |
| **I. 纯语言沙盒(RestrictedPython 等)** | ○ | ● | ○ | — | ○ | 对 Agent 工具链几乎无用 |
### 3.1 A — 浏览器 WASM + 虚拟 FS
**机制:** Wasm 线性内存 + 校验 + 仅经 import 碰宿主;FS 多为内存树 / OPFS / 经 JS bridge 的映射。Marqdo 已锁定「解释器进 WASM」(ADR 0002),默认 `allow_fs_write=false`。
**文献支撑:** Wasm 作为 SFI 窄腰(Bosamiya et al., USENIX SEC'22);进程内沙盒跨边界通信可比 IPC 快数量级(KTH Wasm-SFI 论文);WASI 明确 **capability / 无 ambient authority**。
**优点:** 与「代码即文档」浏览器运行同构;deny-by-default;适合跑 `.mq.md`、公式库、受控插件。
**缺点:** 不能原生跑 `cargo test` / `npm` / 任意 shell;安全上限取决于 **bridge 授予了什么**;浏览器场景下「符号链接用户工作区」通常要落到 File System Access API 或服务端中继,**不是** POSIX symlink 语义。
**判定:** 在 **Marqdo-only** 约束下,作为 **Pattern X 主沙盒** 与浏览器内 Marqdo 的正解;完备性取决于 **lib 嵌入 + ext 能力桥**(§4.1),不取决于 shell。通用「任意二进制 Agent」场景下仍不够——但那不是本产品默认。
### 3.2 B — WASI / Component Model(CLI 宿主)
**机制:** preopens 显式挂载;`WASIShim({ sandbox: { preopens, enableNetwork: false } })`(Bytecode Alliance jco);Component imports = 权限表。
**优点:** 与 Wasm 同族,可在 Node/Wasmtime 跑,不绑浏览器;能力模型清晰。
**缺点:** 同 A,任意 Linux 工具链需「宿主机再包一层」或改编译目标。
**判定:** Marqdo **官方扩展 / 插件中可 Wasm 化的部分**应走这条;与 ADR 0002 一条能力谱。
### 3.3 C — 符号链接映射工作区(用户设想的核心)
**设想:** 沙盒根下用 symlink 指向用户文件;写改暂存别处;确认后写回;删除 = 删 symlink。
**表面吸引力:** 零拷贝读、实现「像」有暂存。
**为何行业不把它当隔离原语:**
1. **Bind/mount 跟随 symlink 是经典逃逸。** Anthropic `sandbox-runtime` 明确修复:`allowWrite` 若为指向界外的 symlink,bwrap `--bind` 会把真实目标变成可写(PR #138 类修复)。
2. **项目挂载未解析 symlink 可致高危。** Endor Labs 披露 brig「project mount symlink traversal」(CVSS 8.2):Agent 在可写项目内把子目录换成指向 `/etc` 的 symlink,下一轮宿主机按字符串挂载即打穿。
3. **「删除 = 删 symlink」语义错误。** 删链接只去掉别名,**不等于**对 lower 层文件的 whiteout;若链接指向真实文件且曾被打开写穿,删除链接也救不回。
4. **写穿风险。** 若某路径被解析成真实 inode 且可写,暂存承诺立刻破产。
5. **跨平台。** Windows junction/reparse、浏览器虚拟 FS、容器 bind,行为不一致。
**判定:** **否决作为 Marqdo 默认工作区隔离方案。** 允许在 **只读、已解析、拒绝可写路径上的 symlink 组件** 的前提下作实现细节,但不得当作安全边界叙事。
### 3.4 D — 应用层 CoW VFS(推荐作 W 层默认)
**机制:**
```text
lower = 真实工作区(只读打开 / 只读能力)
upper = 会话 delta(内存 map / 目录树 / SQLite blob)
whiteout = 逻辑删除集合
view(path) = upper ?? (!whiteout && lower)
commit() = 把 upper/whiteout 应用到 lower(可经人审)
discard() = 丢弃会话
diff() = 可审变更集
```
与 Turso AgentFS、OpenSandbox `workspace.mode: overlay` 的 **语义同构**,但不强制 FUSE。
**与 Marqdo 对齐点:**
| VFS 操作 | Marqdo 真相 |
|----------|-------------|
| `diff()` | 父 Agent / 人审材料;可进 view |
| `commit()` 文本结果 | `writeback.record` / 工作簿补丁 |
| `discard()` | 失败回合不污染仓库 |
| 只读 lower | 防止 T3 即时破坏 |
**优点:** 纯用户态、可测、可嵌入 `plugins/agent`;不依赖 root/FUSE;金样可锁。
**缺点:** 对 **沙盒内原生工具**(它们走真实 POSIX)不可见,除非再挂 E 或把工具 I/O 也改走 VFS API。
**判定:** **Pattern W 的默认实现。**
### 3.5 E — OS CoW overlay(AgentFS / overlayfs / OpenSandbox)
**机制(AgentFS 公开设计):** lower=宿主只读;upper=SQLite delta;删除=whiteout;Linux 用 FUSE+user/mount ns;macOS 用 NFS+`sandbox-exec`。OpenSandbox 默认 `overlay`,会话结束可丢 upper。
**优点:** 对 **任意 shell 工具**透明;「改了但宿主机 `git status` 仍干净」体验业界已验证。
**缺点:** 平台依赖;FUSE 权限;与应用层 D 双实现成本。
**判定:** **当 Pattern X 需要真实 shell 且要求暂存对工具透明时**启用(Linux 优先);作为 D 的「native 加速后端」,不是替代 Wasm。
### 3.6 F — OS 进程沙盒(bwrap / Seatbelt / VS Code Copilot)
**机制:** Anthropic:文件系统隔离 + **网络隔离(缺一不可)**;Linux bubblewrap + 代理;macOS Seatbelt。VS Code Copilot:同类依赖;路径分 readwrite / readonly / denied;明确「不是 VM,削弱授权即削弱边界」。
**优点:** 本地编码 Agent 的事实标准;覆盖子进程;启动轻。
**缺点:** 默认可写 cwd → **没有**「暂不生效」;必须与 D/E 组合。Symlink 配置路径需解析与拒绝。
**判定:** **Pattern X(shell/外联/MCP)本地默认。**
### 3.7 G / H — 容器与 microVM
**共识:** 裸 Docker 共享内核,不适合作唯一边界应对不可信代码;gVisor 加强 syscall 拦截;Firecracker/Kata 适合多租户与高威胁(~125ms 级启动)。Docker AI Sandboxes 区分 **direct mount(即时写穿)** vs **clone(只读源 + 私有副本)**——后者才接近「确认后写回」。
**判定:** Marqdo **本地 CLI 默认不强制 microVM**;若未来 `ext` 提供托管执行 / 多租户,再把 H 定为服务端 Profile。G 可作为打包/CI Profile。
### 3.8 I — 语言级沙盒
对「Agent 会跑 shell」场景基本无效;仅作极窄解释器内嵌参考。
---
## 4. 专门评估:用户提案(修订)
> 浏览器 WASM 作沙盒底层 + 符号链接用户工作区 + 修改短暂不生效 + 确认后写回 + 删除变删 symlink。
> **补充约束:** AI 只生成 Marqdo;沙盒须能用标准库与扩展库。
| 子命题 | 评价 | 说明 |
|--------|------|------|
| Wasm 作主执行隔离 | **在 Marqdo-only 下正确** | 与 ADR 0002 同构;不必为 shell 全集付税 |
| 沙盒须含 lib + ext | **正确且关键** | 「能跑 `# main`」≠ 好沙盒;见 §4.1 |
| 「短暂不生效」 | **正确** | CoW / staging(方案 D,必要时 E) |
| 「确认后写回」 | **正确且极契合 Marqdo** | 与 writeback、父裁决、workbook 同一哲学 |
| 「symlink 映射工作区」 | **仍错误** | 与是否只用 Marqdo 无关;换 CoW/whiteout |
| 「删除 = 删 symlink」 | **仍错误** | 应为 whiteout;commit 时再对 lower 删除 |
| 「性能最好且安全性最高」 | **Wasm 主路径下接近成立** | 前提是桥最小权限 + CoW;symlink 仍拉低安全 |
**修订后的正确表述:**
> **以 Wasm Marqdo 运行时为主沙盒,打包/嵌入 `lib/*`,经能力桥提供受支持的 `ext/*`;工作区用 lower 只读 + upper/whiteout;人审/父裁决后 commit。符号链接不作隔离原语。shell/外联/原生 dlopen 默认关闭,仅作显式逃逸舱。**
### 4.1 库完备性:什么叫「标准库和扩展库也能用」
沙盒若只能跑内置算术、却不能 `import lib/json` 或跑 `ext/ai/llm` 的离线金样,对 Agent 开发几乎无用——模型生成的 `.mq.md` **本来就会依赖 lib/ext**。
三类库进沙盒的路径不同:
| 类别 | 今日形态 | 沙盒策略 |
|------|----------|----------|
| **纯 `.mq.md` 库**(多数 `lib/*`、部分 `ext` 门面) | 源码 import | **嵌入或会话导入图**(已有 `embedded_lib` / import map)— 必须默认可用 |
| **需宿主能力的 lib**(`fs` / `net` / `writeback` / `subtask` / `datetime.now`…) | `host_*` | **经能力表桥接**到会话 VFS / 受控 clock / 受控 fetch;默认最小集 |
| **原生 ABI 扩展**(`plugins/web`、`plugins/agent`、quantum 等 `.so`) | `plugin.load` + dlopen | 浏览器/Wasm **无 dlopen**(ADR 0002 N2)。沙盒内应:**纯 mq 门面 + Wasm 插件**、或 **宿主代执行且权限计入会话**、或 **显式 `unavailable`** — 禁止假装成功 |
与 [browser-marqdo-wasm.md](../design/browser-marqdo-wasm.md) §5 对齐并扩展为 **Agent 沙盒能力矩阵(草案)**:
| 能力 | 沙盒默认 | 备注 |
|------|----------|------|
| builtins / 表 / 控制流 / 对象 | ✓ | 内核 |
| `lib/math` `json` `table` `text` `collection`… | ✓ | embedded |
| `lib/fs` | ✓(仅会话 VFS) | 写进 upper;禁越出 root |
| `lib/writeback` | ✓(写会话内 `.mq.md`) | commit 后才进真实树 |
| `lib/net` / llm HTTP | 默认关 / 域名白名单 | 与 T5 |
| `lib/subtask` `fn=` | ✓(同 Wasm 会话) | |
| `lib/subtask` `path=`/`code=`/`lang=` | **默认拒** | 逃逸舱 + OS 沙盒 |
| `lib/plugin` + 原生 `.so` | **默认拒** | 改 Wasm 插件或宿主代执行 |
| `ext/ai/llm` · `ext/ai/agent`(mq 门面) | ✓(能力允许时) | 网络/密钥另授 |
| `ext/web` 服务端 listen/DB | **默认拒或只读 stub** | 完整 axum 不进沙盒;可测「装配/渲染」子集 |
| `ext/quantum` / `ext/linalg` | 目标 ✓ | 优先纯逻辑 / Wasm 插件,避免强依赖宿主机 .so |
**验收金样建议(S 阶段):**
一套「沙盒烟囱」:`import` 常用 lib → 写会话文件 → writeback → `diff` → `commit`;再各挑一个 **纯逻辑 ext** 与一个 **需网络的 ext**(后者验证拒绝/白名单)。缺能力必须诊断含 `unavailable in sandbox`(或同等措辞)。
---
## 5. 综合评分(面向 Marqdo-only 产品)
加权(修订):执行隔离契合 Marqdo-only 30%、**lib/ext 完备** 25%、与 writeback 真相 20%、实现成本 15%、跨端(CLI↔浏览器)10%。
(「任意 shell 工具完备」不再作为主权重。)
| 候选架构 | 分(相对) | 备注 |
|----------|------------|------|
| **A/B Wasm-first + D CoW + 库完备能力表** | **100(推荐)** | 主路径 |
| 同上 + 逃逸舱 F(opt-in shell) | 95 | 兼容少数 foreign 需求 |
| D + E + F(通用 coding 向) | 75 | 过重;非 Marqdo-only 默认 |
| 仅 F(可写 cwd) | 55 | 缺 CoW;且鼓励非 mq 工具 |
| 仅 A 但无 CoW、无 lib 嵌入 | 40 | 「半沙盒」 |
| 仅 C(symlink) | 20 | 否决 |
| 仅 H(人人 microVM) | 50 | 托管可选;本地默认过重 |
**绝对「最硬」单点**仍可以是 microVM(托管 Profile)。
**Marqdo「最合适」:** **Wasm 完整运行时沙盒(内核+lib+受控 ext)+ CoW 工作区 + commit 闸门**。
---
## 6. Marqdo 应采用的沙盒设计(推荐锁定草案 · 修订)
### 6.1 产品形态
| Profile | 场景 | 执行(X) | 工作区(W) |
|---------|------|-----------|------------|
| **`mq-sandbox`(默认)** | Agent 生成并试跑 `.mq.md` | **Wasm Marqdo** + embedded `lib/*` + 能力桥 `ext` | 应用层 CoW;commit→真实树 / writeback |
| **`browser`** | 页内同构运行 | 同左(ADR 0002) | 内存/OPFS;无 POSIX symlink |
| **`escape`(显式)** | foreign / 真子进程 | OS 沙盒包一层 | 仍建议 CoW 可见 |
| **`hosted`(可选)** | 多租户 | Wasm 或 microVM | 会话隔离;凭证外置 |
### 6.2 推荐架构图
```text
┌──────────────────────────────────────┐
│ ext/ai/agent (Harness) │
│ 只产出 / 编排 .mq.md · 人审闸门 │
└──────────────────┬───────────────────┘
│
┌─────────────────────┼─────────────────────┐
▼ ▼
┌────────────────────┐ ┌────────────────────┐
│ Workspace CoW (W) │ │ Marqdo Wasm (X) │
│ lower = RO 工作区 │◄── fs/writeback ───│ 同构解释器/VM │
│ upper / whiteout │ 能力导入 │ + embedded lib/* │
│ diff·commit·discard│ │ + ext 能力面 │
└─────────┬──────────┘ │ 默认: 无 shell/so │
│ └────────────────────┘
▼
真实工作区 / <!-- marqdo-out -->
(代码即文档真相源)
(可选)escape: subtask path|code|lang → OS sandbox
```
### 6.3 API 面建议(设计级,非立即实现)
落点倾向:宿主能力进 `plugins/agent` / Wasm HostContext;作者面经 `ext/ai` 或 `lib`(**禁止** `ext/**` 直调 `host_*`)。
| 概念 | 语义 |
|------|------|
| `sandbox.open(root, mode=cow)` | 打开会话;lower 只读 |
| `sandbox.read/write/list/remove` | 经 view;remove → whiteout |
| `sandbox.diff` / `stat` | 供父 Agent / view |
| `sandbox.commit` / `discard` | 闸门;可要求 HITL |
| `sandbox.run(source\|path, caps=…)` | **Wasm 跑 Marqdo**;caps 声明 fs/net/llm/… |
| `sandbox.caps` / `inspect` | 列出已授能力与 lib/ext 可用性(对齐 `web.inspect` 哲学) |
| `sandbox.exec(...)` | **仅 escape Profile**;默认不存在于作者工具表 |
与现有衔接:
- `lib/*`:优先 embedded;FS/时间/网络走会话 caps。
- `ext/*`:mq 门面可加载;原生插件默认不可用并诊断;长期可 Wasm 化的(linalg/quantum 逻辑)优先进 Wasm。
- `lib/writeback`:写入会话内文件;`commit` 时进入真实树。
- `lib/subtask`:默认仅 `fn=`;`path`/`code`/`lang` 要 escape。
### 6.4 硬禁(写入后续 design 时应保留)
1. **不以 symlink 森林作为隔离或暂存原语。**
2. **不以「能跑空 `# main`」宣称沙盒完成** — 必须过 lib/ext 完备金样或显式 unavailable。
3. **默认工具表不提供通用 shell / 任意语言 exec。**
4. **不默认可写 bind 真实工作区。**
5. **宿主桥 = 权限表**:未授能力不得 ambient 成功。
6. **不静默降级**:缺 Wasm/能力时不得假装已隔离。
7. **`ext/**` 不调 `host_*`**(既有宪法)。
### 6.5 分阶段落地(建议,非 `doc/next`)
| 阶段 | 交付 | 验收线索 |
|------|------|----------|
| S0 | 威胁模型 + 本调研(含 Marqdo-only) | 本文 |
| S1 | Wasm `run` + embedded 核心 `lib/*` + 会话 VFS 读 | 常用 lib 金样在沙盒绿 |
| S2 | CoW upper/whiteout + diff/commit/discard | 未 commit 时宿主机 `git status` 干净 |
| S3 | writeback / 工作簿在会话内可写;commit 对齐 | agent step 金样 |
| S4 | caps:net/llm 白名单;`subtask` 非 fn 默认拒 | 诊断字符串稳定 |
| S5 | 代表性 ext(纯逻辑 + 需网)沙盒金样 | 完备性验收 |
| S6 | (可选)escape OS 沙盒;hosted microVM | 文档标明非默认 |
---
## 7. 外部资料索引(抽样)
| 类型 | 引用 |
|------|------|
| 产品 | [Anthropic: Claude Code sandboxing](https://www.anthropic.com/engineering/claude-code-sandboxing) · [sandbox-runtime](https://github.com/anthropic-experimental/sandbox-runtime) · [VS Code agent sandboxing](https://code.visualstudio.com/docs/agents/run/agent-sandboxing) · [Docker AI Sandboxes security](https://docs.docker.com/ai/sandboxes/security/) · [Turso AgentFS overlay](https://turso.tech/blog/agentfs-overlay) · [OpenSandbox isolation sessions](https://open-sandbox.ai/guides/isolation-sessions) |
| 标准 | [WASI Design Principles](https://github.com/WebAssembly/WASI/blob/main/docs/DesignPrinciples.md) · [jco preview2-shim sandbox](https://github.com/bytecodealliance/jco/blob/main/packages/preview2-shim/README.md) |
| 论文 | Bosamiya et al., *Provably-Safe Multilingual Software Sandboxing using WebAssembly*, USENIX Security 2022 · *Intra-process Fault Isolation Using WebAssembly* (KTH) · *Research on WebAssembly Runtimes: A Survey*, ACM TOSEM 2025 |
| 综述 | [Cosmonic: Choosing an AI agent sandbox (2026)](https://cosmonic.com/ai-sandbox/choosing-an-agent-sandbox/) · [Northflank: MicroVMs, gVisor & isolation](https://northflank.com/blog/how-to-sandbox-ai-agents) |
| 安全案例 | [brig symlink traversal / Endor Labs](https://www.endorlabs.com/learn/project-mount-symlink-traversal-in-brig-how-a-sandbox-reaches-host-directories-it-was-never-given) · Anthropic sandbox-runtime symlink bind 修复 |
---
## 8. 结语
- **产品好消息:** Agent 只生成 Marqdo → **Wasm 主沙盒设计成立**,不必默认扛通用 shell Agent 的复杂度。
- **好沙盒的定义:** 不只跑内核,还要 **`lib/*` 可用、`ext/*` 在能力表内可用或显式不可用**;再加 **CoW + commit** 保护仓库真相。
- **仍要改掉的:** 符号链接当暂存/隔离;默认开放 foreign/dlopen;「空 main 能跑」就算完工。
- **降级为非默认的:** bwrap/microVM — 留给 escape / hosted,而不是 Marqdo-only 主路径。
不急着实现。下一步若继续收敛,再开 `doc/design/ext-ai-sandbox.md` 把 **能力矩阵 + 库完备金样清单** 锁死即可;**仍不要改 `doc/next/*`**。
+290
View File
@@ -0,0 +1,290 @@
# 外联内核 · 文档会话 · 决策记录
| | |
|---|---|
| 状态 | **Decided(由用户授权代为拍板)** |
| 日期 | 2026-10-17 |
| 范围 | 外联库(`lib/foreign`)· 外联内核 · 文档会话 · view notebook 交互 |
| 相关 | [foreign-kernel.md](../design/foreign-kernel.md) · [notebook-session.md](../design/notebook-session.md) · [notebook-syntax.md](../design/notebook-syntax.md) · [foreign-v2.md](../roadmap/foreign-v2.md) · [notebook-session.md](../roadmap/notebook-session.md) |
| 核心表面 Δ | **无**——不新增 Markdown 标记;只使用既有 `#` / `##` / 表格 / 反引号 |
> 本文件记录「为什么这样设计」。实现细节分别落在设计文档与路线图中;本文件不重复 API 表。
---
## 0. 背景与授权
用户的核心诉求:
1. Marqdo 的本质是 **代码即文档、文档即知识库**;`.mq.md` 天生兼容 Markdown / OKF 知识库。
2. 外联库的初衷是**对标 Jupyter**:让文档与代码并行有用;但 Jupyter 有 Git 难跟踪、隐藏状态、execution_count 噪声等问题,Marqdo 要解决并超越。
3. `view` 模式天然适合这种交互(已有执行按钮、结构视图、writeback、trace)。
4. 之前外联库功能太单一;接下来必须支持:
- 多个代码块共享外联状态;
- 单步执行;
- 切换哪些外联内核共享状态;
- Marqdo 的状态/变量被外联使用;
- 外联的状态/变量被 Marqdo 使用。
5. 用户要求:**安全第一、效果最好、功能最强悍、不降级**;充分测试;每份讨论落成详细文档;文档提交并推送后再开发。
6. 用户强调:**设计语法不要用代码思维**,语法要天然可读。
本文档 = 对该授权的决策记录。后续实现若与本文冲突,先改本文并说明理由。
---
## 1. 关键结论
### 结论 A:外联库不是“跑 Python 的函数”,而是多语言内核运行时
`lib/foreign` 的定位升级为:
> **文档运行时与外部语言运行时之间的内核/会话层**:启动内核、执行代码单元、持久化状态、双向类型桥、生命周期与安全。
它不等同于 `subtask`(一次性并发任务),也不等同于 `writeback`(输出持久化)。
### 结论 B:Jupyter 级体验需要两层,不是一层
| 层 | 名称 | 责任 |
|---|---|---|
| **F** | Foreign Kernel Runtime | 内核进程、语言发现/注册、JSON 桥、会话、安全、记录 |
| **D** | Document Session | 文档会话、cell index、kernel 分配、单步、状态面板、执行日志、view 交互 |
上一版 `foreign-v2` 只覆盖 F。共享状态 / 单步 / 切换内核属于 D。两层分开设计、分开验收。
### 结论 C:Hybrid 执行模型
- **Program mode(规范模式)**:`marqdo run` / CI / 可复现执行。文档是程序;外联通过显式 `foreign.session_*` / `call` 编排;结果可重复。
- **View cells(交互面)**:`view` 中按 cell 执行、单步、切换内核、查看状态。适合探索,不默认写入文档;不是第二个 CLI 模式。
- 两者共享同一个内核运行时与同一套 cell 索引;view cells 是 program execution 的**交互镜头**,不是替代品。
理由:如果让 cell 执行取代文档程序语义,Marqdo 就退化成 Jupyter;如果只有 Program mode,就失去 Jupyter 的即时反馈。Hybrid 同时保留两者。
### 结论 D:命名内核;同内核共享,跨内核/跨语言显式传值
- 一个文档可以有多个命名内核:`py:分析`、`py:绘图`、`js:前端`。
- 同一内核的 cell 共享全局状态。
- 不同内核(即使同语言)默认隔离。
- 不同语言不共享进程内存;只能通过 JSON / 文件 / DB 显式交换。
- 默认每个文档、每种语言一个 `default` 内核;命名内核按需开启。
- 跨文档默认隔离;全局内核以后再做。
### 结论 E:三种单步,分阶段实现
| 单步 | 含义 | 版本 |
|---|---|---|
| **Cell step** | 执行下一个代码单元,状态保留 | v2 必做 |
| **Marqdo statement step** | 逐条执行 Marqdo 语句,查看变量 | v2 复用现有 debugger |
| **Foreign line step** | 进入 Python/Node 逐行 | v2 不做;后续接 DAP/pdb/debugpy |
- 外联 cell 在 statement step 中是原子操作。
- “Step into foreign” 是独立项目,不能混入首版。
### 结论 F:显式状态桥优先,不做隐式自动镜像
- 默认通过 `session_set` / `session_get` / `call input` / `call result` 交换,JSON 拷贝。
- 不默认把 Marqdo 变量自动注入 Python,也不默认把 Python 变量自动写回 Marqdo。
- 原因:命名冲突、Secret 泄漏、类型丢失、隐式状态、不可复现、大对象拷贝。
- 后续可选 `mirror=True`:只同步 `mq_` 前缀、白名单类型、按值拷贝,且默认关闭。
### 结论 G:不新增围栏元数据;用文档原生的“内核表 / 会话表”
- 拒绝 ` ```python kernel=分析 `、`name=`、YAML kernel 配置、魔法注释。
- 使用既有绑定表 + GFM 表格(放在 `# main` 体内,与 cell 同作用域):
- `内核表` / `kernels`
- `会话表` / `session`
- 表格是**声明**,不是自动执行;只有 Run / Step 触发。
- 解析器不变,核心表面零增长;view/session 读取这两个约定绑定。
理由:`kernel=` 是 IDE 配置思维,破坏“代码即文档”;绑定表是文档目录/执行计划,人可读、机器可解析,且不把文档拆成多个对象作用域。
### 结论 H:输出默认临时,writeback 显式;状态不写进 `.mq.md`
- View cells 的输出默认只在 view 中显示,不修改文档。
- 需要持久化时显式 writeback(沿用 `<!-- marqdo-out … -->`),可 Git 跟踪、可忽略。
- 执行日志放 `.marqdo/sessions/…`(默认 git 忽略)。
- 不把 execution_count / kernel 状态 / base64 输出写进 `.mq.md`。
### 结论 I:首批会话语言 Python + Node
- Python:Jupyter 的主场景,优先支持。
- Node:v1 已有基础,且当前开发环境可用。
- 15 个语言预设继续用于**一次性执行**;R / Julia / Ruby 等的持久会话通过自定义 bootstrap 逐步加入,不阻塞首版。
### 结论 J:v2 不做“外联回调 Marqdo 函数”
- 状态/值双向:✅
- Marqdo 代码作为源码文本传给外联:✅(外联按自己的语言执行)
- 外联代码调用 Marqdo `##` 函数:❌ v2;后续做 callback RPC(控制通道 + 重入 + 死锁处理)。
- 原因:重入解释器、线程安全、死锁、安全面都远超首版范围;先把数据/状态桥做稳。
### 结论 K:安全与测试是一等公民
- 所有 spawn / probe / session 入口检查 `allow_exec`。
- 进程组超时清理;有界 IO;stdin 写线程;输出上限;并发上限。
- 每文档生命周期,关闭即 kill;跨文档不共享。
- 测试:node + bash 为最小环境主路径;python 条件覆盖;单元测试覆盖切分/模板/JSON;金样例覆盖记录/超时/会话/并行/状态桥。
---
## 2. 逐问逐答(保留原始讨论颗粒度)
### Q1:外联库是做什么的?
**答**:它是文档的多语言执行总线,负责:
1. 内核生命周期(启动/重启/中断/关闭/切换);
2. cell 执行(源码 → kernel → stdout/stderr/result);
3. 状态持久化(同一 kernel 的 cell 共享命名空间);
4. 类型桥(Marqdo Value ↔ JSON ↔ 语言对象);
5. 环境发现与配置(probe/register/venv/config);
6. 记录与安全(耗时、退出码、截断、cap、清理)。
它不负责:文档语法(Language)、UI 布局(Document)、知识目录(Catalog)。这些由相邻层提供。
### Q2:是否支持外联库共享状态?
**答**:支持,但严格分层:
- 同一 kernel:共享全局变量。
- 同一语言不同 kernel:隔离。
- 不同语言:不共享内存,只能显式传值。
- Marqdo ↔ kernel:显式桥。
- 跨文档:默认隔离。
### Q3:能否单步执行?
**答**:能,但要定义清楚:
- cell step:v2 做。
- Marqdo statement step:现有 debugger 已有,v2 接入 view。
- foreign line step:v2 不做;后续 DAP。
### Q4:能否切换哪几个外联库共享状态?
**答**:能,用命名内核:
- `py:分析` 下所有 cell 共享;
- `py:绘图` 隔离;
- 每个 cell 有 kernel 归属;
- 切换归属不迁移状态,需要重跑;
- 跨语言用显式桥。
### Q5:Marqdo 的代码/状态能否被外联使用?外联的状态/变量能否被 Marqdo 使用?
**答**:
- Marqdo 值 → 外联:`session_set` / `call input` / `session_eval input`;JSON 拷贝。
- 外联值 → Marqdo:`session_get` / `call` 返回值;赋值。
- Marqdo 代码 → 外联:作为源码文本传递;外联按自己的语言执行,不是 Marqdo 语义。
- 外联代码 → Marqdo 函数:v2 不做,后续 callback RPC。
- 自动镜像:v2 不做,后续可选。
### Q6:如何超越 Jupyter?
**答**:不是“功能更多”,而是把 Jupyter 的隐藏面变成显式面:
| Jupyter | Marqdo |
|---|---|
| `.ipynb` JSON 混入输出/execution_count | `.mq.md` 源码干净;输出可选 writeback |
| 隐藏 kernel 状态 | 内核 + 文档会话 + 状态面板 + journal |
| 一个 notebook 一个 kernel | 命名内核 + 每 cell 归属 + 显式桥 |
| 只有 cell step | cell step + statement step |
| 手动 Run All | restart & run all + dirty/stale + replay |
| 无知识目录 | OKF / catalog;cell 是可发现知识单元 |
---
## 3. 被拒绝的方案
| 方案 | 为什么拒绝 |
|---|---|
| 围栏元数据 ` ```python kernel=分析 ` | Language 层变更;需 ADR;把文档语法变成 IDE 配置;破坏可读性 |
| YAML `kernels:` 配置 | 代码思维;与“文档即知识”冲突;表格已能表达 |
| 魔法 HTML 注释 `<!-- kernel: 分析 -->` | 不可见、易漂移、读者不可见;违背可读性 |
| 自然语言 prose 解析(“把 xs 送给分析内核”) | 非确定性;误触发;违背“叙述默认安全” |
| 隐式自动镜像变量 | 命名冲突、Secret 泄漏、类型丢失、不可复现 |
| 一个文档一个 kernel | 无法做多语言/隔离实验,正是 Jupyter 的局限 |
| 把状态/输出写进 `.mq.md` | Git 噪声;正是要解决的 Jupyter 问题 |
| cell 自动执行 | 违背“未标记即叙述/未调用即数据”;破坏安全默认 |
| v2 做 foreign→Marqdo callback | 重入/死锁/安全复杂;应先稳定数据桥 |
---
## 4. 已锁定的实现边界
### v2 必做
- F0 安全执行内核 + `invoke` 记录 + `exec` 门禁 + 有界 IO + 进程组超时。
- F1 语言注册/发现:15 预设、`probe`、`register`、`unset`、配置、venv。
- F2 JSON 桥:`call` / `run_many` / `output` / `result`。
- F3 持久内核:Python / Node `session_open/eval/close/list`。
- F3.5 状态桥:`session_set/get/names`。
- D1 文档会话服务端:cell index、kernel registry、journal、open/close。
- D2 view notebook:内核选择、Run/Step/Run All/Restart、状态面板、dirty/stale。
- D3 Marqdo statement step 接入 view。
- D4 语法:`内核表` / `会话表` 解析与校验。
- D5 测试、文档、catalog、CHANGELOG。
### v2 不做(明确记录,避免“降级”误解)
- Foreign line-level step(接 DAP 是后续项目)。
- Foreign → Marqdo 函数 callback。
- 跨语言共享对象引用 / 共享内存。
- 全进程快照(只做变量级 JSON 快照)。
- 跨文档全局内核。
- 自动安装依赖。
- 浏览器 wasm 外联。
这些不是“砍掉”,而是**独立阶段**;v2 先把内核/会话/桥做稳。
---
## 5. 风险与对策
| 风险 | 对策 |
|---|---|
| 会话协议脆弱(原生 fd 输出、缓冲) | bootstrap 用原始 stdout;Python `-u`;Node 保存原始 write;超时 kill;文档标注限制 |
| 状态桥隐式化导致不可复现 | 默认显式;`mirror` 后续且默认关 |
| 多内核进程泄漏 | 每文档生命周期;Drop kill;进程组;session_close;测试 |
| 大对象 JSON 拷贝慢 | v2 明确拷贝语义;后续 Arrow/Parquet/文件句柄 |
| `内核表` / `会话表` 名称冲突 | 文档声明为保留绑定名;后续可用 frontmatter 指针重命名 |
| 表格行/单元不一致 | 明确诊断:未声明内核、重复单元、语言不匹配、未入会话 |
| 交互执行顺序混乱 | journal + dirty/stale + Run All canonical + 执行序号 |
| 安全(Secret/环境) | Secret 不进 JSON;env 显式交付;状态面板打码;exec cap |
| 测试环境无 Python | node/bash 主路径;python 条件测试;协议单测 |
---
## 6. 术语表(统一中英文)
| 中文 | English | 含义 |
|---|---|---|
| 外联内核 | foreign kernel | 外部语言进程 |
| 外联会话 | foreign session | 内核实例 + 命名空间 |
| 文档会话 | document session | Marqdo 状态 + 内核注册表 + journal |
| 代码单元 | cell | 绑定名的代码围栏 |
| 内核归属 | kernel assignment | cell → kernel |
| 状态桥 | state bridge | Marqdo 值 ↔ 内核变量 |
| 执行日志 | execution journal | 执行顺序/耗时/结果/hash |
| 新鲜 | clean | 源码未变且已成功执行 |
| 过期 | dirty | 源码变了,结果可能过期 |
| 失效 | stale | 上游依赖变了,需要重跑 |
| 规范执行 | canonical run | 重启后按会话表顺序 Run All |
---
## 7. 决策时间线
1. 用户提出外联库对标 Jupyter、共享状态、单步、切换、双向使用。
2. Agent 阅读 `src/host/foreign.rs`、`src/view`、`src/debug`、`src/host/subtask.rs`、`lib/foreign`、设计文档。
3. Agent 回答:需要 F + D 两层;单步分三种;共享分三层;显式桥。
4. 用户授权 Agent 拍板:安全、最强、不降级、充分测试、文档先行、提交推送后开发。
5. Agent 锁定本文件 §1 的 A–K 结论,进入文档编写与实现。
---
## 8. 后续变更流程
- 任何与本文冲突的实现,先改本文并写明「变更理由 / 影响 / 迁移」。
- 新增核心语法(任何新标记)必须走 `doc/adr/` + `core-surface.md`;本文所有语法均为既有标记的组合。
- 新增会话语言、跨语言数据平面、callback RPC,各自开独立设计文档,不塞进本文件。
+78
View File
@@ -0,0 +1,78 @@
# Marqdo AI 栈统一开发方案(llm + agent)
| | |
|---|---|
| Status | **Active** |
| Date | 2026-09-24 |
| Source | [doc/next/002–005](../next/) · [ext-llm.md](../design/ext-llm.md) · [ext-agent.md](../design/ext-agent.md) |
## 1. 一句话
> **Document → Prompt → LLM → Agent → Skill → Policy → Executable Knowledge**
大模型负责探索,小模型(`router_model` / 任意 llm 句柄)负责决策,Marqdo 负责执行;经验编译进 `.mq.md` 后推理成本下降。
## 2. 分层(勿混)
| 层 | 职责 | 落点 |
|----|------|------|
| **Intelligence primitive** | `ask` / `stream` / `collect`;结果对象 | `ext/ai/llm` |
| **Agent runtime** | `run` / `step` / `plan` / `route` | `ext/ai/agent` |
| **Sandbox (trial)** | CoW workspace + capped `run` | `ext/ai/sandbox` · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) |
| **Memory / compile** | episode → skill → policy | `plugins/agent`(ABI;**不进** `src/host`) |
| **Transport** | HTTP / SSE / provider | `ext/ai/llm/openai` · `ollama`;用户不可见 |
硬规则:`ext/**` 不调 `host_*`;agent/OKF/路由热路径只进 `plugins/agent`。
## 3. LLM(005)— 已/待
| 项 | 状态 |
|----|------|
| 语义 API:`ask` / `stream` / `collect`(`complete` 降为兼容原语) | **done** |
| `create` 工厂;handle 带 `backend` | **done** |
| LLMResult:`text` / `model` / `finish` / `backend` / `usage` / `tokens` | **done** |
| Named models(`llm.fast` / `llm.reasoning`) | **done** |
| Prompt document:`prompt` / `prompt_load` + `type: prompt` 正文 | **done**(无参 `ask`/`stream` → `sys.module_source` + `prompt_body`) |
| 拆 `ext/ai/llm/openai.mq.md` + `ollama` 后端 | **done** |
| tool_calls 完整 Result | **done**(`openai.tool_calls_from` + `LLMResult.tool_calls`;`llm-tool-calls-offline`) |
| Transport → 可选 ABI 插件 (`plugins/llm`) | **done** |
| Artifact Metadata Binding(`${env.*}` / `secret` · `sys.meta`) | **done**(Phase 1 Metadata-only + Phase 2 scope lift;[binding.md](../design/binding.md)) |
作者面优先:
```marqdo
**answer = > llm.ask prompt="What is Marqdo?"**
**events = > model.stream prompt=`p`**
**text = > llm.collect events=`events`**
**fast = > llm.fast**
**prompt = > llm.prompt path="prompts/task.md"**
```
## 4. Agent(002–004)— 已/待
| 项 | 状态 |
|----|------|
| Skill Compilation:episode → maybe_learn → `llm_free` | **done** |
| Adaptive Routing:`marqdo` \| `small-llm` \| `llm` \| `auto`(`jev`→`small-llm` 别名) | **done** |
| Policy Compilation → `policies/router.mq.md` | **done** |
| `run` 串联 route → execute → record → learn | **done** |
| Agent 默认走 `model.ask` + Result.usage 记成本 | **done**(`model_turn`) |
| Prompt artifact / document-as-prompt | **done**(经 llm `path=` / `prompt`) |
| 零 LLM 执行(policy+skill → `llm_calls=0`) | **done** |
| `plan` 不覆盖已有 `llm_free` resource | **done** |
| 真 MCP client(stdio) / resume checkpoint / 小模型路由请求面 | **done**(live 路由仍可选 skip) |
## 5. 联调顺序
1. **LLM Result → Agent metrics** — **done**
2. **Named handles** — **done**
3. **Prompt document** — **done**(`type: prompt` 剥 frontmatter;无参 `ask`/`stream` 经 `sys.module_source`)
4. **Backend split** — **done**
5. **Execution compilation** — **done**(`agent-zero-llm` 金样 + harness)
6. **Metadata Binding** — **done**(Phase 1 + Phase 2 scope lift;`llm-meta-offline` · `meta-lift`)
## 6. 验收金样
- Agent:`tests/ext/agent-v2-learn.mq.md` · `agent-p4-route.mq.md` · `agent-zero-llm.mq.md` · `agent-plan-preserve.mq.md` · `agent-mcp-client.mq.md` · `agent-resume.mq.md` · `agent-small-llm-route.mq.md` · `scripts/agent-harness.sh`
- LLM:`tests/ext/llm-ask-offline.mq.md` · `llm-stream-offline.mq.md` · `llm-ctor-offline.mq.md` · `llm-named-offline.mq.md` · `llm-meta-offline.mq.md` · `llm-entry-prompt-offline.mq.md` · `llm-tool-calls-offline.mq.md`
- Binding:`tests/structure/meta-binding.mq.md` · `meta-lift.mq.md`
+9 -2
View File
@@ -7,6 +7,7 @@
| 调研 | [agent-frameworks-and-marqdo.md](../research/agent-frameworks-and-marqdo.md) · [agent-framework-gaps-after-a4.md](../research/agent-framework-gaps-after-a4.md) · **[agent-framework-2026-09.md](../research/agent-framework-2026-09.md)** |
| 设计 | [ext-agent.md](../design/ext-agent.md) · [ext-agent-plan.md](../design/ext-agent-plan.md) · [ext-agent-parent.md](../design/ext-agent-parent.md) · [okf.md](../design/okf.md) |
| 邻近 | [agent-streaming.md](agent-streaming.md) · [okf-near-match.md](okf-near-match.md) |
| 后续 | 优化波次 O1–O5 见 [ext-ai-optimize.md](ext-ai-optimize.md)(沙盒证明 · Skill Lift · 路由/成本 · lint · 隔离) |
---
@@ -39,6 +40,12 @@
| **B0** | 官方示例演示 call_site/源码/OKF;Skill/文档;上下文管道可读 | **done** |
| **B0.5** | 本机 live(`.env` → 开发模型)验证「模型用上了文档」 | **done**(`AGENT_LIVE` / `AGENT_HARNESS_LIVE`) |
| **B1** | 评测 harness 锁差异化指标(constitution / dump / writeback 遮蔽) | **Active** |
| **B2–B5** | 真 MCP / resume+HITL / stats / 并行 | 暂缓 |
| **B1.5** | **Skill Compilation v2(Phase 1–3)**:episode → maybe_learn → compile → `llm_free`;`agent.run` / `resolve` / `metrics`;ABI 在 `plugins/agent`(`memory.rs`);金样 `agent-v2-learn` | **done** |
| **B1.6 / P4** | **Adaptive Routing**(原 Jev Router 更名):`route` backends = `marqdo` \| `small-llm` \| `jev?` \| `llm` \| `auto`;Policy Compilation → `policies/router.mq.md`;金样 `agent-p4-route`;设计 [004.md](../next/004.md) | **done** |
| **L0** | **LLM semantic surface(005)**:`ask` / `stream` / `collect` / `create`;`complete` 降为兼容;统一方案 [ai-stack.md](ai-stack.md) | **done** |
| **B2** | 真 MCP stdio client(`agent_mcp_client` + fixture 仍作离线证据) | **done** |
| **B3** | resume checkpoint(`.marqdo/agent-resume/`;HITL view 仍暂缓) | **done**(HITL 暂缓) |
| **B4–B5** | stats / 并行;小模型 live 路由金样(无 key skip) | 部分 |
| — | LLM named models / prompt-document | **done** |
示例:`examples/agent-pong/` · `examples/agent-okf-flywheel/`。
示例:`examples/agent-pong/` · `examples/agent-okf-flywheel/`。v2 设计:[doc/next/002.md](../next/002.md) · [doc/next/003.md](../next/003.md) · P4:[doc/next/004.md](../next/004.md) · LLM:[doc/next/005.md](../next/005.md)。
+29
View File
@@ -0,0 +1,29 @@
# Roadmap: Agent/LLM 优化波次 O1–O5
| | |
|---|---|
| Status | **Active** |
| Date | 2026-10-16 |
| Design | [ext-ai-optimize.md](../design/ext-ai-optimize.md) |
| Research | [ai-agent-llm-optimize-2026-10.md](../research/ai-agent-llm-optimize-2026-10.md) |
| Prior | [ext-agent-optimize.md](ext-agent-optimize.md) (A0–A4 / Wave B) · [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) |
## Principles
1. Executable `.mq.md` remains authority; OKF reuses; sandbox proves; LLM explores.
2. No hidden TOOL: loop; no vector-store memory authority; no default shell Agent.
3. Do not edit `doc/next/*`.
## Waves
| Wave | Scope | Gold / deliverable | Status |
|------|-------|--------------------|--------|
| **O1** | A1 opt-in `sandbox=` · A3 profile table · D1 skill · D4 example | `agent-sandbox-optin` · `examples/agent-sandbox-okf` | **done** |
| **O2** | A2 promote proof · B1 OKF meta · B3/E1 harness Skill Lift | `agent-sandbox-promote` · harness subset | **done** |
| **O3** | C1 step route · C2 cost · B6 EFI default | `agent-step-route` · run usage/efi | **done** |
| **O4** | A4/D2 lint · A5 diff review report | `scripts/mq-style-lint.sh` · `sandbox.report` | **done** |
| **O5** | B4 quarantine · C3 offline policy rewrite | `agent-sandbox-quarantine` · `optimize-standing-policy.sh` | **done** |
## Non-goals
F1–F5 · wasmtime CLI embed · default `sandbox=True` without ADR · edit `doc/next/*`
+28
View File
@@ -0,0 +1,28 @@
# Roadmap: `ext/ai/sandbox` (AI CoW trial runtime)
| | |
|---|---|
| Status | **Active** |
| Date | 2026-10-16 |
| Design | [ext-ai-sandbox.md](../design/ext-ai-sandbox.md) |
| Research | [ai-agent-sandbox.md](../research/ai-agent-sandbox.md) |
## Milestones
| ID | Deliverable | Done when |
|----|-------------|-----------|
| S0 | Design + this roadmap + research cross-links | **done** |
| S1 | CoW open/write/read/remove/diff/commit/discard | **done** (`sandbox-cow`) |
| S2 | `run` + default caps + core lib inside run | **done** (`sandbox-run-lib`) |
| S3 | `inspect` + deny plugin.load | **done** (`sandbox-deny`) |
| S4 | Polish: ai-stack + CHANGELOG | **done** |
## Gold samples (target)
- `tests/ext/sandbox-cow.mq.md`
- `tests/ext/sandbox-run-lib.mq.md`
- `tests/ext/sandbox-deny.mq.md`
## Out of scope this wave
wasmtime CLI embed · Wasm ABI plugins · bwrap/microVM · full web in sandbox · auto-wire agent.step · edit `doc/next/*`
+226
View File
@@ -0,0 +1,226 @@
# 外联内核 v2 路线图(F0–F4)
| | |
|---|---|
| 状态 | **F0–F3.5 已落地;F4 进行中** |
| 日期 | 2026-10-17 |
| 层 | Runtime |
| 相关 | [foreign-kernel.md](../design/foreign-kernel.md) · [notebook-session.md](../design/notebook-session.md) · [notebook-syntax.md](../design/notebook-syntax.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [stdlib-foreign.md](../design/stdlib-foreign.md) · [notebook-session.md](notebook-session.md)(D 层路线) |
| 核心表面 Δ | 无 |
> 本路线图只覆盖 **F:外联内核运行时**。共享状态 / 单步 / 切换内核的文档侧在 [notebook-session.md](notebook-session.md)(D 层)。
---
## 0. 现状与目标
v1:`set_cmd` / `run` / `run_lang` / `langs`;临时文件 + 子进程 + stdout 文本;无状态、无结构化结果、无 exec 门禁、无有界 IO、无进程组清理。
v2 目标:安全、可发现、结构化、可持久、可并行,并成为 D 层文档会话的可靠底座。
---
## 1. 阶段总览
| 阶段 | 内容 | 估算 | 可独立发版 |
|---|---|---|---|
| **F0** | 执行内核与安全:Job/Execution、`exec` 门禁、有界 IO、进程组、`invoke` 记录、view 诊断 | 2–3 天 | 是 |
| **F1** | 语言注册与发现:registry、15 预设、probe、register/unset、配置、venv | 2–3 天 | 是 |
| **F2** | JSON 桥与并行:call/call_many、run_many、output/result | 2–3 天 | 是 |
| **F3** | 持久内核:Python/Node session_open/eval/close/list | 3–4 天 | 是 |
| **F3.5** | 状态桥:session_set/get/names | 1–2 天 | 是 |
| **F4** | 打磨、文档、catalog、CHANGELOG、1.5.0 | 1–2 天 | 1.5.0 |
D 层(文档会话)从 F3.5 完成后开始;不要把 D 层塞进 F 层。
---
## 2. F0 — 执行内核与安全
### 内容
- `src/host/foreign.rs` 重构:
- `Job`:lang/source/stdin/input/env/cwd/timeout/args/output/max_output/cmd/keep。
- `Execution`:stdout/stderr/raw bytes/exit/ms/timed_out/truncated/error。
- `ForeignEnv`:cwd/fs_root/specs/caps 快照(供并行)。
- `exec` 门禁:`run` / `invoke` / `run_many` / `probe` / `session_*` 统一检查。
- 有界 IO:读线程保留前 N 字节、继续排空;`truncated`。
- stdin 写线程;EPIPE 忽略。
- 超时:进程组 kill(Unix `process_group(0)` + `kill(-pid)`;Windows `taskkill /T /F`)。
- shell-like argv 切分(引号/转义)。
- `invoke` + 稳定记录。
- `run` / `run_lang` 增加 `env` / `cwd` / `timeout` / `args` / `max_output`。
- view `/api/foreign-run` 返回完整记录;JS 显示 stderr / exit / ms。
- `set_cmd` L1 补 `args`。
### 验收
- 既有 `lib_foreign_*` / `lib_subtask_foreign` 绿(python 可用时)。
- 新增 node/bash 金样例:非 0 退出、stderr、超时、env/cwd、截断。
- `exec=false` 拒绝。
- `cargo test` 绿;release build;wasm check。
### 主要文件
`src/host/foreign.rs` · `src/host/mod.rs` · `src/host/subtask.rs` · `src/view/mod.rs` · `src/view/html.rs` · `src/view/debug_page.rs` · `Cargo.toml` · `tests/gold.rs` · `tests/lib/foreign-*.mq.md`。
---
## 3. F1 — 语言注册与发现
### 内容
- `src/foreign/registry.rs`(纯逻辑):
- 15 预设、别名、扩展名、版本参数、会话能力。
- 模板占位符 `{file}` / `{dir}` / `{base}` / `{inline}` / `{lang}` / `{cwd}`。
- venv 探测、PATH 查找、shell-like 切分、配置解析。
- `HostContext`:
- `foreign_specs`、`foreign_config_loaded`。
- `probe` 缓存(可选)。
- API:`probe` / `langs` / `register` / `unset` / `load_config`。
- 配置:`.marqdo/foreign.toml` + `MARQDO_FOREIGN_CONFIG`;优先级见设计。
- `MARQDO_FOREIGN_<LANG>` 支持 JSON 数组与引号。
- `subtask` 继承注册/配置。
### 验收
- `probe` 对 node / bash 给出 path + version;缺失语言 `ok=false` 不 panic。
- 配置可把 `python` 指向 venv;模板可跑 `go run`(若本机有 go)。
- `langs` 含预设;`unset` 回退预设。
- 单元测试:切分、模板、别名、扩展名。
---
## 4. F2 — JSON 桥与并行
### 内容
- `call` / `call_many`;`invoke` 的 `input` / `output` / `result` / `result_error`。
- `Value ↔ JSON` 复用 `host::json`;`bytes` base64。
- `run_many` 并行引擎:`ForeignEnv` 快照、线程上限 32、结果同序、单项 panic 隔离。
- `call_many` 全跑完再报错(清理所有子进程)。
- 文档:Python / Node JSON 样板。
### 验收
- `call` 单列表 → map,mean 为 Num;嵌套 list/map 往返。
- `run_many` 顺序稳定;单项失败不影响其它项。
- 大输入(>8 KiB)走 `MARQDO_INPUT_FILE`。
- 并发上限与超时生效。
---
## 5. F3 — 持久内核
### 内容
- `src/host/foreign_session.rs`:
- Python / Node bootstrap(嵌入式常量)。
- 启动、reader/writer、严格串行、超时、崩溃、drop 清理。
- `session_open` / `session_eval` / `session_close` / `session_list`。
- 会话记录:与 invoke 同形 + `id` / `alive`。
- 会话环境:cwd / env / cmd;`MARQDO_*`。
- `HostContext` 字段(cfg exec-host)+ Drop。
### 验收
- Node:`let x=41` → `x+1` → 42;`console.log` 捕获;异常不杀会话。
- Python:同(有 python 时)。
- 超时 → kill + `alive=false`;close/drop 无遗留进程。
- 会话与 `subtask` 边界:不继承。
---
## 6. F3.5 — 状态桥
### 内容
- `session_set` / `session_get` / `session_names`。
- 值:Marqdo → JSON → kernel;kernel → JSON → Marqdo。
- 名称校验;Secret 规则;错误可读。
- 与 `session_eval` 同一线路,严格串行。
- L1 文档 + 金样例。
### 验收
- Node:`session_set xs=[1,2,3]`,`session_eval sum(xs)` → 6;`session_get` 取回。
- 复杂嵌套 map/list 往返。
- 不存在变量 → None + 可读诊断。
- 非 JSON 可序列化 → 错误说明。
---
## 7. F4 — 打磨与发布
- `history`(可选)/ `cache`(可选,默认关)。
- view 命令记忆 / Ctrl+Enter / 错误分块。
- `lib/foreign.mq.md` / `lib/外联.mq.md` 全量。
- `public/stdlib/*` 示例。
- catalog 重新生成;CHANGELOG;版本 1.5.0。
- 性能:空跑、100 次调用、会话 vs 一次性。
### 验收
- 新函数全部有中文/英文文档与示例。
- `marqdo catalog`、`public/` 构建通过。
- 手工 view Run 一个 node 卡片,显示 stdout/stderr/exit/ms。
---
## 8. 测试矩阵
> 当前环境:node / bash / sh / perl 可用,python3 不可用。新金样例以 node + bash 为主;python 用 `python_available()` 条件跳过。
| 测试 | 依赖 | 断言 |
|---|---|---|
| 既有 3 个 foreign 用例 | python | 兼容 |
| `foreign-invoke` | node | 记录字段 |
| `foreign-env-cwd` | node | env/cwd/MARQDO_* |
| `foreign-timeout` | node | timed_out |
| `foreign-call-json` | node | 类型往返 |
| `foreign-call-many` / `run-many` | node | 顺序/隔离 |
| `foreign-session` | node | 跨 eval |
| `foreign-session-set-get` | node | 状态桥 |
| `foreign-session-timeout` | node | alive=false |
| `foreign-probe` | node | path/version |
| `foreign-register` | node | 模板 |
| `foreign-config` | node | 配置 |
| `foreign-stdout-stderr` | bash | 成功也有 stderr |
| `foreign-caps` | 无 | 拒绝 |
| 单元测试 | 无 | 切分/模板/别名/JSON |
Windows:`python_available` / `bash_available` 守卫;进程组 `taskkill` 分支编译通过。
---
## 9. 兼容性
- `run` / `run_lang` / `set_cmd` / `langs` 兼容;只增可选参数。
- `run` 成功仍返回 stdout;非 0 仍报错。
- 大输出从“报错”改为“截断 + truncated”(更安全;CHANGELOG 写明)。
- `langs` 扩展为预设 ∪ 注册 ∪ 配置。
- HostFn id 末尾追加(196+)。
- 无核心表面 Δ。
---
## 10. 风险
| 风险 | 缓解 |
|---|---|
| 会话协议脆弱 | 原始 stdout;`-u`;超时 kill;测试;文档限制 |
| 并行进程过多 | 默认 4 / 上限 32;超时;输出上限 |
| 配置优先级难记 | 设计文档固定表;`probe` 显示实际 path |
| 模板 shell 注入 | 默认不 shell;路径引擎生成;文档警示 |
| 大输出截断改变 v1 行为 | CHANGELOG;`truncated` 可检测 |
| wasm 编译 | 新字段 cfg 隔离;registry 纯逻辑 |
---
## 11. 完成定义
- F0–F3.5 全部验收。
- `cargo test` 绿;release build;wasm check。
- 文档/CHANGELOG/catalog 更新。
- 提交并推送。
- 进入 D 层([notebook-session.md](notebook-session.md))。
+177
View File
@@ -0,0 +1,177 @@
# 文档会话路线图(D0–D5)
| | |
|---|---|
| 状态 | **D1–D3 已落地(首版);D4–D5 待做** |
| 日期 | 2026-10-17 |
| 层 | Runtime + Document(view 服务端 / 前端) |
| 相关 | [notebook-session.md](../design/notebook-session.md) · [notebook-syntax.md](../design/notebook-syntax.md) · [foreign-kernel.md](../design/foreign-kernel.md) · [foreign-v2.md](foreign-v2.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) |
| 核心表面 Δ | 无 |
> F 层让“外部语言能持久运行”;D 层让“文档里的多个 cell 像 notebook 一样共享状态、单步、切换内核”。两层分开验收。
---
## 0. 依赖
- **F3**:Python / Node 持久内核。
- **F3.5**:`session_set/get/names`。
- 现有 `DebugController`(Marqdo 语句单步)。
- 现有 `writeback` / `annot` / view 结构。
没有 F3/F3.5,D2 只能做一次性 Run,不是共享状态。
---
## 1. 阶段总览
| 阶段 | 内容 | 估算 |
|---|---|---|
| **D0** | 设计/语法/决策文档 | 已完成 |
| **D1** | `src/notebook/`:cell index、表解析、session 结构、诊断 | 2–3 天 |
| **D2** | 服务端 API:open/close/cell run/step/run_all/restart/interrupt | 3–4 天 |
| **D3** | view UI:工具栏、cell 徽标、kernel 下拉、状态面板、journal | 3–4 天 |
| **D4** | statement step、dirty/stale、writeback | 2–3 天 |
| **D5** | replay、持久化、并发优化、测试补全、发布 | 2–3 天 |
---
## 2. D1 — Cell index 与表解析
### 内容
- 新模块 `src/notebook/`:
- `cell.rs`:从 AST 提取绑定名代码围栏;id/name/lang/line/source hash。
- `syntax.rs`:读取 `内核表` / `会话表`;中英列名。
- `session.rs`:`DocumentSession` 结构、kernel registry、value store、journal。
- `diag.rs`:重复/未知/语言不匹配/未入会话诊断。
- 自动模式:无表 → 文档顺序 + 默认内核。
- 解析器不改;只遍历 `Module.functions` + `Stmt::Assign { value: Expr::Code }`。
- 测试:单元 + `tests/notebook/*.mq.md`。
### 验收
- 两个 Python cell + 一个会话表 → cells 顺序、kernel 归属正确。
- 无表 → 自动顺序。
- 未知内核/未知单元/重复/语言不匹配 → 可读诊断。
- 未绑定围栏不进入 cell index。
---
## 3. D2 — 服务端 API
### 内容
- `src/view/notebook_api.rs`(或 `view/session_api.rs`):
- open / close / reload
- cell run / step / run_all
- kernel restart / interrupt / assign
- state list / push / pull
- journal
- Session 存储:`OnceLock<Mutex<HashMap<String, Arc<DocumentSession>>>>`(类似 debug sessions)。
- 每个文档一个 session;key = 相对路径。
- 执行线程:cell 执行不阻塞 HTTP;响应返回记录;SSE/EventBus 可选。
- 错误统一 JSON。
### 验收
- open 返回 cells/kernels/journal。
- cell run:never→running→clean/error;状态更新。
- step:按会话顺序执行下一个。
- run_all:按顺序;restart 选项。
- 同 kernel 串行;不同 kernel 可并行。
- close/drop kill 所有 kernel。
- API 单测/集成测试。
---
## 4. D3 — View UI
### 内容
- 工具栏:Run All / Restart & Run All / Step Cell / Step Statement / Kernel 状态 / Restart / Interrupt / State / Journal。
- Code card:
- 状态徽标(never/clean/dirty/stale/error/running/unlisted)
- kernel 下拉
- Run / Step
- 输出区(stdout/stderr/result/truncated)
- 执行序号 / 耗时
- 状态面板:
- Marqdo 值 / kernel 变量分栏
- Push / Pull / Refresh
- Secret 打码、大对象摘要
- Journal 面板:表格 + 跳转 + 导出。
- 键盘:Ctrl/Cmd+Enter、Shift+Enter、F5、F10。
- 静态导出的 Run 仍隐藏。
### 验收
- 手工冒烟:两个 Python cell 共享 `x`;切换 kernel 后隔离;Restart 清状态。
- 状态面板 Push/Pull。
- 错误 cell 红色徽标 + stderr。
- 页面刷新后 session 仍在(服务端内存)。
---
## 5. D4 — Statement step / dirty / writeback
### 内容
- Statement step:复用 `DebugController`,与 DocumentSession 关联;暂停点显示变量。
- dirty:reload 后 source hash 变化。
- stale:按会话顺序,上游变更 → 下游 stale(v2 近似)。
- writeback:单 cell / 全部;`<!-- marqdo-out -->`;不自动。
- 运行历史 / 执行序号。
### 验收
- Statement step 在 view 中可用;外联调用原子完成。
- 编辑 cell → dirty;Run All 后 clean。
- 上游变更 → 下游 stale。
- 显式 writeback 写入文档;不自动改文件。
---
## 6. D5 — Replay / 持久化 / 发布
### 内容
- Journal replay:新 kernel,按 journal 顺序/输入 hash 重放;比较 stdout/result hash;divergence 报告。
- 可选持久化 `.marqdo/sessions/<doc-hash>.json`(kernel/cell 归属/journal/value store 摘要;默认 git 忽略)。
- 并发优化:不同 kernel 并行;同 kernel 串行。
- 测试补全;文档;catalog;CHANGELOG。
- 版本:D 层随 1.5.x。
### 验收
- Replay 能复现 clean 会话;dirty 输入给出 divergence。
- 关闭/重启服务无进程泄漏。
- 文档完整;金样例绿。
---
## 7. 测试矩阵
| 测试 | 断言 |
|---|---|
| `notebook/kernels.mq.md` | 内核表/会话表解析 |
| `notebook/auto-session.mq.md` | 无表自动顺序 |
| `notebook/shared-state.mq.md` | 同 kernel 共享变量 |
| `notebook/isolated-kernels.mq.md` | 不同 kernel 隔离 |
| `notebook/step.mq.md` | cell step 顺序 |
| `notebook/state-bridge.mq.md` | Marqdo ↔ kernel 推拉 |
| `notebook/dirty.mq.md` | 编辑 → dirty/stale |
| `notebook/invalid-*.mq.md` | 诊断 |
| API 集成 | open/run/step/run_all/restart/interrupt/close |
| 安全 | exec=false、cwd 越界、超时、Secret 打码 |
依赖 node 为主;python 条件跳过。
---
## 8. 完成定义
- D1–D4 验收;D5 可选(replay/持久化)。
- 文档会话与 F 层联调通过。
- 手工 view 冒烟:共享状态 / 单步 / 切换 / 状态面板 / journal。
- 测试绿;文档更新;提交推送。
+85 -78
View File
@@ -1,19 +1,22 @@
# 第 14 章:网络与 Web 扩展
Marqdo 的网络能力分两层:**标准库 `lib/net`**(HTTP 客户端、cookie / multipart 解析)与**官方扩展 `ext/web`**(网页应用、数据库、表单、登录鉴权、WebSocket)。分层的依据是「代码即文档」的可读性——基础、通用、低依赖的进标准库;领域性强、依赖重、只在 Web 场景才用的进扩展。
> **现行作者面(2026-09-28 · ADR 0007)**:Document / Endpoint / Resource —— 见 [ext-web-artifact.md](../design/ext-web-artifact.md)。
> 下文若仍出现 `compose_*` / `app.configure` / `web.db` 同文件混写,视为**历史示例**;DB → `ext/data`,鉴权 → `ext/security`,实时 → `ext/net`。
Marqdo 的网络能力分两层:**标准库 `lib/net`**(HTTP 客户端、cookie / multipart 解析)与**官方扩展 `ext/web`**(Document/Endpoint facade + 拆分后的 data/security/net)。分层的依据是「代码即文档」。
## 14.1 概览
| 能力 | 位置 | 典型函数 |
| 能力 | 位置 | 典型 API |
|------|------|----------|
| 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` |
| Cookie / multipart | `lib/net` | `cookie_parse` / `multipart_parse` |
| Document / Endpoint | `ext/web` | `type: web\|endpoint` · `web.serve` · `web.render` · `web.inspect` |
| View 装配 | `ext/web` | `|type|slot|value|attrs|style|` → `web.render` |
| 数据库 | `ext/data` | `db` CRUD / txn |
| 表单 | `ext/data` | `form` |
| 鉴权 / RBAC / OIDC | `ext/security` | `auth` · `rbac` · `oidc` |
| WebSocket | `ext/net` | `websocket` |
```bash
# 运行使用 ext/web 的程序前,先安装扩展
@@ -67,107 +70,111 @@ import net:lib/net.mq.md
> print text=[name](`field`)
```
## 14.3 网页应用(`ext/web`)
## 14.3 网页应用(Artifact · ADR 0007)
`ext/web` 用类 + 方法装配页面。导入 `web:ext/web/web.mq.md`(中文 `网页:ext/web/网页.mq.md`)。
站点是一堆 `.mq.md`:**Document**(`type: web`)与 **Endpoint**(`type: endpoint`)。入口调用 `web.serve` 扫描目录并监听。完整设计见 [ext-web-artifact.md](../design/ext-web-artifact.md);示例 [marqdo-blog](../../examples/marqdo-blog/)。
### 页面、组件、主体
### Document 首页
```markdown
---
type: web
title: 我的站点
route: /
method: GET
data_source: posts
data_order: -created_at
import web:ext/web/web.mq.md
---
# 我的站点
欢迎。下方卡片列表由 `data_source` 在服务时从数据库加载。
```
### Endpoint
```markdown
---
type: endpoint
method: GET
path: /api/ping
request: none
response: json
---
# main
`首页` =
`out` =
| 组件 | 样式 |
|------|------|
| nav.`导航` | shell.`顶栏` |
| ok | service |
|----|---------|
| True | demo |
**page = > web.page title="我的站点" intro="<h1>你好</h1>"**
**page = > `page`.compose_components components=`首页`**
**html = > `page`.render**
*out*
```
### 服务入口
```markdown
---
import web:ext/web/web.mq.md
import posts:db/posts.mq.md
---
# main
**store = > posts.open url="sqlite:data/site.db"**
> web.serve root="." host="127.0.0.1" port=18081 db=`store` static_dir="public"
```
离线预览可用 View 表 + `web.render`:
```markdown
`nodes` =
| type | slot | value | attrs | style |
|------|------|-------|-------|-------|
| title | title | Marqdo | | title |
**html = > web.render nodes=`nodes` title="preview"**
> print text=`html`
```
### 应用 + 路由 + 监听
### 数据库(`ext/data`)
```markdown
**app = > web.app page=`page` host=127.0.0.1 port=18081**
**app = > `app`.route path="/about" page=`关于`**
> web_listen app=`app`
```
---
import data:ext/data/db.mq.md
---
`listen` 提供 `/`、路由页、表单端点 `/_form/{id}`、可选静态目录与 `/admin`。
# main
### 数据库(SQLite)
```markdown
**store = > web.db url="sqlite:site.db"**
**store = > data.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)
## 14.4 鉴权(`ext/security`)
给 `/admin*` 加登录门禁:`app.auth` 挂用户表,未登录重定向到 `/admin/login`。
HTTP 门禁与登录走 `ext/security`(`auth` / `rbac` / `oidc`),再用 `web.use` 挂中间件表;勿再写 `app.configure`。独立脚本可用:
```markdown
`管理员` =
---
import rbac:ext/security/rbac.mq.md
---
| 行 | 用户名 | 密码 |
|----|--------|------|
| 1 | admin | secret |
| 2 | 站长 | pw123 |
# main
**app = > web.app page=`page` admin=True**
**app = > `app`.auth users=`管理员` session_ttl=3600**
> web_listen app=`app`
**gate = > rbac.rbac**
**r = > `gate`.can permissions="desk:access" needed="desk:access"**
> print text=[allowed](`r`)
```
`session_ttl` 是会话有效期(秒),过期后重新登录。
## 14.5 WebSocket(`ext/net`)
**独立鉴权工具** `web.auth`:登录、校验、登出(不依赖页面),返回 `{ok, session_id, username}`:
```markdown
**auth = > web.auth users=`管理员` session_ttl=3600**
**login = > `auth`.login username="admin" password="secret"**
1. [ok](`login`)
> print text=登录成功:[username](`login`)
2. *
> print text=登录失败
**sid = [session_id](login)**
**check = > `auth`.check session_id=`sid`**
> print text=[username](`check`)
> `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. [ok](`echo`)
> print text=[messages](`echo`)
2. *
> print text=连接失败:[error](`echo`)
```
实时能力在 `ext/net`(如 `websocket`),与 Document 站点并列导入,不再挂在 `web.app` 的 junk drawer 上。
## 14.6 字典操作:用表格与取元,不用 `json.get`/`json.set`
+13
View File
@@ -0,0 +1,13 @@
# agent-sandbox-okf(O1)
演示 **opt-in 沙盒试跑 + 表风格**(少 json 胶水):`agent.trial` 写入先落 upper,`commit=False` 时宿主不变,成功后再 `commit=True`。
```bash
cargo build --release -p marqdo -p marqdo_plugin_agent
export MARQDO_EXT="$PWD/ext"
./target/release/marqdo run examples/agent-sandbox-okf/index.mq.md
```
期望:`dry-ok` · `host-clean` · `wet-ok` · `proof-visible` · `profile-default`。
见 [ext-ai-optimize.md](../../doc/roadmap/ext-ai-optimize.md) · 金样 [agent-sandbox-optin.mq.md](../../tests/ext/agent-sandbox-optin.mq.md)。
+59
View File
@@ -0,0 +1,59 @@
---
title: agent-sandbox-okf — trial then commit
description: >
O1 example: opt-in sandbox trial with GFM-table returns and link-index reads.
import agent:ext/ai/agent.mq.md
import fs:lib/fs.mq.md
---
# main
Short demo: write via `agent.trial`, prove the host is clean until commit.
**had = fs.exists path="_example_sbx"**
1. `had`
> fs.remove path="_example_sbx"
2. *
**_ = 0**
> fs.make_dir path="_example_sbx"
**dry = agent.trial root="_example_sbx" write_path="note.txt" text=sandbox-okf commit=False**
**dry_ok = [ok](dry)**
**dry_committed = [committed](dry)**
1. `dry_ok`
1. not `dry_committed`
> print text=dry-ok
2. *
> print text=dry-bad-commit
2. *
> print text=dry-fail
**leaked = fs.exists path="_example_sbx/note.txt"**
1. `leaked`
> print text=host-leaked
2. *
> print text=host-clean
**wet = agent.trial root="_example_sbx" write_path="note.txt" text=sandbox-okf commit=True**
**wet_ok = [ok](wet)**
**wet_committed = [committed](wet)**
1. `wet_ok`
1. `wet_committed`
> print text=wet-ok
2. *
> print text=wet-no-commit
2. *
> print text=wet-fail
**body = fs.read_text path="_example_sbx/note.txt"**
1. `body` == "sandbox-okf"
> print text=proof-visible
2. *
> print text=proof-missing
**pname = [name]([profile](wet))**
1. `pname` == "default"
> print text=profile-default
2. *
> print text=profile-other
@@ -0,0 +1,20 @@
---
title: resolve_config
capability: config.resolve
status: stable
---
Use when: final normalized configuration is required.
# config
## resolve_config
+ `path`
`defaults` =
| host | port |
|------|------|
| localhost | 8080 |
* defaults
@@ -0,0 +1,21 @@
---
title: Engineering Knowledge demo
description: Tiny project demonstrating Capability Catalog + reuse + decisions.
---
# Engineering Knowledge demo
This folder is a miniature “large engineering” slice: config resolution already exists.
Before generating a new loader, run:
```bash
marqdo knowledge examples/engineering-knowledge -o examples/engineering-knowledge/.marqdo
marqdo reuse "load and resolve configuration" examples/engineering-knowledge -o examples/engineering-knowledge/.marqdo
marqdo duplicate examples/engineering-knowledge -o examples/engineering-knowledge/.marqdo
```
Expected: **REUSE config.resolve**, not a new `load_configuration`.
# main
* "see README via catalog/reuse CLI"
@@ -0,0 +1,18 @@
---
type: Decision
id: ADR-022
title: Cache is not persistence
status: accepted
applies_to:
- config.resolve
---
# Cache is not persistence
## Decision
Redis is only used for ephemeral cache.
## Reason
The application must remain correct when Redis is unavailable.
@@ -0,0 +1,12 @@
---
type: Constraint
id: C-014
title: Centralized config resolution
status: stable
applies_to:
- config.resolve
---
# Centralized config resolution
All configuration resolution must go through `resolve_config`.
@@ -0,0 +1,20 @@
---
type: Failure
id: F-008
title: Do not invent a second config loader
status: resolved
---
# Do not invent a second config loader
## Failed approach
Added `load_configuration` beside `resolve_config`.
## Failure
Divergent defaults and error handling.
## Correct approach
Call `resolve_config`.
+27 -42
View File
@@ -1,54 +1,39 @@
# examples/marqdo-blog
一个用 Marqdo 的 `ext/web` 网络扩展库搭建的博客系统示例:美观大气的现代化主题、
SQLite 驱动的文章/标签、动态路由、WebSocket 实时终端、以及受会话门禁保护的后台 CRUD。
Marqdo **Web Artifact** blog (ADR 0007).
## 运行
## Layout
```bash
cargo build -p marqdo_plugin_web
cargo run -- examples/marqdo-blog/index.mq.md
```text
index.mq.md # type: web · / · data_source: posts
pages/about.mq.md # 类型: 网页 · /about
pages/post.mq.md # type: web · /post/{slug} · data_where
api/ping.mq.md # type: endpoint · GET /api/ping
api/echo.mq.md # type: endpoint · POST /api/echo
db/posts.mq.md # ext/data schema + seed + open
public/ # static (mounted at /static)
serve.mq.md # web.serve + db open
smoke.sh # curl checks against a running serve
```
打开 http://127.0.0.1:18085/:
- `/` — 首页:文章卡片网格 + 实时 WebSocket 终端
- `/post/{slug}` — 动态路由渲染单篇文章(标题/日期/标签/正文)
- `/tags` — 标签归档;`/tag/{slug}` 查看某标签下的文章
- `/about` — 关于页
- `/admin` — 会话门禁后台,登录 `admin` / `marqdo`,可增删改文章与标签
- `/live` — WebSocket 回显端点
- `/static/*` — 静态资源(`public/` 下的 `live.js`、favicon、logo)
- `/favicon.ico` — 站点图标(`应用.图标` 表装配)
## 设计亮点(文档即代码)
- **样式即数据表格,装配即函数**(`styles/theme.mq.md`):
主题不再是一大段手写 CSS 字符串,而是由一张张 GFM 样式表组成 ——
`|选择器|属性|值|` 规则行(同一选择器多行自动合并成一条规则),
响应式用 `|媒体|选择器|属性|值|` 分组进 `@media` 块。
每个 `## 段`(基础/顶栏/侧栏/主体/卡片/页脚/表单/响应式)导出一张样式表,
`## 全局` 用 `网页.样式装配` 函数把每张表装配成 CSS 文本,再 `text.str_join` 拼成完整样式表,
最后经 `页面.样式` 注入页面。样式保持可读的数据表格,不写胶水代码。
- **图标 / 头资源 / 图片装配**(W8):`应用.图标` 表挂 `/favicon.ico` 与 SVG;
`页面.头装配` 写 apple-touch-icon;`页面.图片装配` 把 logo 表注入主区(`mq-images`)。
含 `/` 的路径与 MIME 单元格需加引号(如 `"/static/logo.svg"`、`"image/png"`)。
- **页面 = 组件装配 + 主体绑定**(`index.mq.md`):
导航/侧栏/页脚用 `|组件|样式|` 表装配,文章列表用 `|属性|值|` 绑定 SQLite 字段。
- **动态路由**:`/post/{slug}` 的 `slug` 注入查询条件,`页面.详情` 把首行渲染成文章。
- **数据模型**(`db/`):`schema.mq.md` 定义 `posts`/`tags`/`post_tags` 三张表,
`seed.mq.md` 提供种子数据,`index.mq.md` 幂等建表 + 灌数据。
## 冒烟测试
服务器启动后(端口 18085),运行:
## Run
```bash
bash scripts/build-web-plugin.sh
export MARQDO_EXT=$PWD/ext # if ~/.marqdo/ext is stale
export MARQDO_WEB_PLUGIN=$PWD/plugins/web/build/libweb.so
cd examples/marqdo-blog && marqdo run serve.mq.md
# other terminal:
bash examples/marqdo-blog/smoke.sh
```
覆盖:首页/卡片/主题 CSS/媒体查询、静态资源、动态路由详情、标签归档、鉴权门禁、
登录会话、后台表单、WebSocket 回显。全部通过时输出 `通过 N / N`。
| Path | Artifact |
|------|----------|
| `/` | Document home + post cards |
| `/about` | ZH Document |
| `/post/{slug}` | Document detail |
| `/api/ping` | Endpoint JSON |
| `/api/echo` | Endpoint JSON echo |
| `/static/*` | public assets |
可从仓库根目录或本目录运行:相对 `static_dir`(`public`)与相对数据库路径
(`data/marqdo-blog.db`)都按**入口脚本所在目录**解析,不依赖终端工作目录。
Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md).
+25
View File
@@ -0,0 +1,25 @@
---
type: endpoint
method: POST
path: /api/echo
request: json
response: json
auth: none
---
# main
Echo request fields bound via Artifact Metadata (`arg` overlays).
**msg = message**
1. not `msg`
**msg = ""**
2. *
`out` =
| ok | message |
|----|---------|
| True | `msg` |
*out*
+19
View File
@@ -0,0 +1,19 @@
---
type: endpoint
method: GET
path: /api/ping
request: none
response: json
auth: none
description: Health ping — documentation is the API (ADR 0007).
---
# main
`out` =
| ok | service |
|----|---------|
| True | marqdo-blog |
*out*
-28
View File
@@ -1,28 +0,0 @@
---
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*
+44
View File
@@ -0,0 +1,44 @@
---
title: blog posts schema
import data:ext/data/db.mq.md
---
## schema
`fields` =
| 字段 | 类型 | 可空 |
|------|------|------|
| title | text | False |
| slug | text | False |
| summary | text | True |
| content | text | True |
| tag | text | True |
| created_at | text | True |
*fields*
## seed
`rows` =
| title | slug | summary | content | tag | created_at |
|-------|------|---------|---------|-----|------------|
| Hello Marqdo | hello | Welcome | # Hello\n\nExecutable documents. | intro | 2026-09-01 |
| Artifact Web | artifact-web | Document first | Pages are mq.md files. | design | 2026-09-28 |
*rows*
## open
+ `url`="sqlite:data/blog.db"
**store = > data.db url=`url`**
**fields = > schema**
> `store`.init name=posts fields=`fields`
**existing = > `store`.select table="posts" limit=1**
1. `existing`
*store*
2. *
**seed = > seed**
> `store`.insert table=posts rows=`seed`
*store*
+9 -125
View File
@@ -1,131 +1,15 @@
---
type: web
title: Marqdo 博客
description: 用 web 扩展库搭建的博客系统示例:首页列表、动态文章详情、标签归档、登录门禁后台。
route: /
method: GET
data_source: posts
data_order: -created_at
description: >-
Document Artifact 首页(ADR 0007):正文即文档,列表来自 data_source。
导入 网页: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
# Marqdo 博客
`首页` =
| 组件 | 样式 |
|------|------|
| 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 |
`站点图标` =
| 路径 | 关系 | 类型 | 尺寸 | 地址 |
|------|------|------|------|------|
| "public/favicon.png" | icon | "image/png" | 32x32 | "/favicon.ico" |
| "public/favicon.svg" | icon | "image/svg+xml" | any | "/static/favicon.svg" |
`头资源` =
| 关系 | 地址 | 类型 |
|------|------|------|
| apple-touch-icon | "/static/favicon.png" | "image/png" |
`品牌图` =
| 源 | 替代 | 类 | 链接 | 宽度 | 加载 |
|----|------|----|------|------|------|
| "/static/logo.svg" | Marqdo | brand-logo | "/" | 40 | eager |
**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`**
**page = > page.头装配 表=`头资源`**
**page = > page.图片装配 表=`品牌图`**
**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.图标 表=`站点图标`**
**app = > app.路由实时 路径="/live" 回显=True**
**app = > app.鉴权 用户表=`管理员` 会话时长=3600**
> `app`.监听
可执行文档即网页。本站用 Artifact Metadata 声明路由;文章列表由 `data_source: posts` 在服务时加载。
+10
View File
@@ -0,0 +1,10 @@
---
类型: 网页
路由: /about
方法: GET
标题: 关于
---
# 关于 Marqdo
Marqdo 是可执行文档语言:文档即程序,程序即知识。
+13
View File
@@ -0,0 +1,13 @@
---
type: web
title: Post
route: /post/{slug}
method: GET
data_source: posts
data_where: slug={slug}
description: Dynamic Document route — body is the article shell; data from Resource.
---
# Post
Article page for `{slug}`. List and detail data are provided by `ext/data` at serve time when `data_source` is set on the Artifact.
+11
View File
@@ -0,0 +1,11 @@
---
title: marqdo-blog serve
description: Scan Artifact documents/endpoints and listen (ADR 0007).
import web:ext/web/web.mq.md
import posts:db/posts.mq.md
---
# main
**store = > posts.open url="sqlite:data/blog.db"**
> web.serve root="." host="127.0.0.1" port=18081 db=`store` static_dir="public"
+23 -53
View File
@@ -1,71 +1,41 @@
#!/usr/bin/env bash
# 冒烟测试:marqdo-blog 全功能验证。
# 用法:bash examples/marqdo-blog/smoke.sh
# Artifact blog smoke (ADR 0007). Usage: bash examples/marqdo-blog/smoke.sh
# Expects serve.mq.md already listening on BASE (default 18081).
set -uo pipefail
BASE="http://127.0.0.1:18085"
BASE="${BASE:-http://127.0.0.1:18081}"
PASS=0; FAIL=0
ok() { echo " ok: $1"; PASS=$((PASS+1)); }
bad() { echo " FAIL: $1"; FAIL=$((FAIL+1)); }
echo "== 首页 =="
echo "== Document home =="
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 "媒体查询缺失"
curl -s "$BASE/" | grep -q 'class="card"' && ok "data_source cards" || bad "cards missing"
curl -s "$BASE/" | grep -q 'Hello Marqdo' && ok "seed title" || bad "seed title missing"
echo "== 静态 =="
echo "== Static =="
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/static/live.js")
[ "$code" = "200" ] && ok "GET /static/live.js -> $code" || bad "static -> $code"
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/favicon.ico")
[ "$code" = "200" ] && ok "GET /favicon.ico -> $code" || bad "favicon -> $code"
curl -s "$BASE/" | grep -q 'rel="icon"' && ok "head icon link" || bad "head icon 缺失"
curl -s "$BASE/" | grep -q 'mq-images' && ok "图片装配 logo" || bad "mq-images 缺失"
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 "== Dynamic Document =="
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/post/hello")
[ "$code" = "200" ] && ok "GET /post/hello -> $code" || bad "post detail -> $code"
curl -s "$BASE/post/hello" | grep -q 'article-title' && ok "article title" || bad "article title missing"
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 "== ZH Document =="
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/about")
[ "$code" = "200" ] && ok "GET /about -> $code" || bad "about -> $code"
curl -s "$BASE/about" | grep -q '关于 Marqdo' && ok "about body" || bad "about body missing"
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 "== Endpoint =="
code=$(curl -s -o /dev/null -w "%{http_code}" "$BASE/api/ping")
[ "$code" = "200" ] && ok "GET /api/ping -> $code" || bad "ping -> $code"
curl -s "$BASE/api/ping" | grep -q 'marqdo-blog' && ok "ping json" || bad "ping json missing"
code=$(curl -s -o /tmp/mq_blog_echo.json -w "%{http_code}" \
-H 'Content-Type: application/json' -d '{"message":"hi"}' "$BASE/api/echo")
[ "$code" = "200" ] && ok "POST /api/echo -> $code" || bad "echo -> $code"
grep -q '"message":"hi"' /tmp/mq_blog_echo.json && ok "echo body" || bad "echo body missing"
echo
echo "通过 $PASS / $((PASS+FAIL))"
+9 -15
View File
@@ -1,20 +1,14 @@
# web-client-site(路线 D)
# examples/web-client-site
服务端 `ext/web` + 浏览器 WASM 会话;**作者零业务 JS**。
SSR **Document Artifact** + `web.client_embed` auto-mount(零作者 JS)。ADR 0007。
```bash
# 仓库根
cargo build -p marqdo --release
cargo build --release -p marqdo_plugin_web
./target/release/marqdo ext add web
# 构建 WASM + bridge 到本示例 static/
./target/release/marqdo wasm build -o examples/web-client-site/static
# 保留 client.mq.md(wasm build 只写入 wasm/bridge)
cd examples/web-client-site
marqdo run index.mq.md
# 打开 http://127.0.0.1:18090/
bash scripts/build-web-plugin.sh
export MARQDO_EXT=$PWD/ext # 若本机 ~/.marqdo/ext 未同步
marqdo wasm build -o examples/web-client-site/static
cargo run -- run examples/web-client-site/serve.mq.md
```
`index.mq.md` 用 `web.client_embed source="/static/client.mq.md"` 注入自启脚本;交互在 `static/client.mq.md`。
- `index.mq.md` — `type: web` 文档页
- `serve.mq.md` — `web.serve` + `static_dir`
- `static/client.mq.md` — `lib/browser` wire(不变)
+8 -13
View File
@@ -1,19 +1,14 @@
---
title: web-client-site
description: SSR shell + client_embed auto-mount; author zero JS (route D)
type: web
title: Marqdo client site
route: /
method: GET
description: SSR Document + client_embed auto-mount; author zero JS (ADR 0007).
import web:ext/web/web.mq.md
---
# main
# Marqdo client site
Server page with a counter UI. Client logic lives in `static/client.mq.md`
(loaded by official bridge via `client_embed`).
SSR shell with WASM session. Client logic lives in `static/client.mq.md`.
**`embed` = > web.client_embed bridge="/static/marqdo-bridge.js" wasm="/static/marqdo_wasm.wasm" source="/static/client.mq.md" boot=True**
**`intro` = "<h1>Marqdo client site</h1><p>SSR + WASM session. No author JS.</p><div id=\"count\">0</div><p><button id=\"bump\" type=\"button\" disabled>Bump</button> <button id=\"reset\" type=\"button\" disabled>Reset</button></p><pre id=\"log\">booting…</pre>" + embed**
**page = > web.page title="Marqdo client site" intro=intro**
**app = > web.app page=page host="127.0.0.1" port=18090**
**app = > app.static dir="static" mount="/static"**
> `app`.listen
To serve with static assets, run `serve.mq.md` in this directory.
+10
View File
@@ -0,0 +1,10 @@
---
title: web-client-site serve
import web:ext/web/web.mq.md
---
# main
**`embed` = > web.client_embed source="/static/client.mq.md"**
> print text=embed-ready
> web.serve root="." host="127.0.0.1" port=18090 static_dir="static"
+1 -1
View File
@@ -1 +1 @@
1.1.0
1.5.2
+1156 -281
View File
File diff suppressed because it is too large. Load diff
+333 -70
View File
@@ -1,124 +1,387 @@
---
title: ext/ai/llm
description: OpenAI-compatible LLM object (English). Import ext/ai/llm.mq.md.
description: >-
Marqdo LLM intelligence primitive — ask / stream / collect / named handles.
OpenAI-compatible and Ollama HTTP stay behind the semantic surface.
import sys:lib/sys.mq.md
import net:lib/net.mq.md
import json:lib/json.mq.md
import table:lib/table.mq.md
import fs:lib/fs.mq.md
import text:lib/text.mq.md
import openai:ext/ai/llm/openai.mq.md
---
## load_env
+ `path`=None
Load `.env` from cwd (optional named arg `path=`). Does not override existing variables.
Load `.env` from cwd (optional `path=`). Does not override existing variables.
*> sys.load_dotenv path=`path`*
## stream_result
## collect
+ `events`
Reduce a `complete stream=True` event list to the final `done.result` text (or `error.message`). Unknown types (e.g. `reasoning`) are ignored.
Collapse a stream event list to final answer text (`done.result` or `error.message`). Prefer this over raw SSE fields. Alias: `stream_result`.
**answer = ""**
- [ev](events)
**t = [type](ev)**
**t = > json.get value=`ev` key="type"**
1. `t` == "done"
**answer = [result](ev)**
**answer = > json.get value=`ev` key="result"**
2. `t` == "error"
**answer = [message](ev)**
**answer = > json.get value=`ev` key="message"**
3. `t` == "delta"
4. *
4. `t` == "text"
**chunk = > json.get value=`ev` key="text"**
1. `chunk`
**answer = answer + chunk**
2. *
**_ = 1**
5. *
**_ = 1**
*answer*
# llm
## stream_result
+ `events`
Construct an LLM handle from `OPENAI_*` / `MARQDO_LLM_*`.
Compatibility alias for `collect`.
**api_key = > sys.env_get name="OPENAI_API_KEY"**
1. not `api_key`
**api_key = > sys.env_get name="MARQDO_LLM_API_KEY"**
*> collect events=`events`*
1. not `api_key`
> print text=ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY
## usage_from
+ `data`
Extract `{prompt_tokens,completion_tokens,total_tokens}` from an OpenAI-shaped response map (or empty zeros).
*> openai.usage_from data=`data`*
## create
+ `model`=None
+ `base_url`=None
+ `api_key`=None
+ `backend`=openai-compatible
+ `name`=None
Factory for an LLM handle (same as constructing `# llm`). Env fallbacks apply inside the constructor. Optional `name=` tags the handle (`fast` / `reasoning`).
**h = > llm model=`model` base_url=`base_url` api_key=`api_key` backend=`backend` name=`name`**
*h*
## fast
+ `model`=None
+ `base_url`=None
+ `api_key`=None
Named small/fast handle. Model from arg, else `MARQDO_LLM_FAST_MODEL`, else default create model.
1. `model`
**mdl = model**
2. *
**mdl = > sys.env_get name="MARQDO_LLM_FAST_MODEL"**
*> create model=`mdl` base_url=`base_url` api_key=`api_key` name="fast" backend="openai-compatible"*
## reasoning
+ `model`=None
+ `base_url`=None
+ `api_key`=None
Named strong/reasoning handle. Model from arg, else `MARQDO_LLM_REASONING_MODEL`, else default create model.
1. `model`
**mdl = model**
2. *
**mdl = > sys.env_get name="MARQDO_LLM_REASONING_MODEL"**
*> create model=`mdl` base_url=`base_url` api_key=`api_key` name="reasoning" backend="openai-compatible"*
## prompt_body
+ `src`
If `src` starts with YAML frontmatter declaring `type: prompt` / `类型: 提示`, return the body after the closing `---`; otherwise return `src` unchanged.
**sw = > text.starts_with text=`src` prefix="---"**
1. not `sw`
*src*
2. *
**parts = > split value=`src` sep="\n---\n"**
**n = > len value=`parts`**
1. `n` < 2
*src*
2. *
**fm = > at value=`parts` index=0**
**is_p = > text.contains text=`fm` sub="type: prompt"**
1. not `is_p`
**is_p = > text.contains text=`fm` sub="类型: 提示"**
2. *
**_ = 1**
1. `is_p`
**body = > at value=`parts` index=1**
*> text.str_trim s=`body`*
2. *
*src*
## prompt_load
+ `path`
Load a prompt artifact (`.mq.md` / `.md`) from disk for `ask`.
**raw = > fs.read_text path=`path`**
*> prompt_body src=`raw`*
## prompt
+ `path`=None
+ `text`=None
Prompt artifact helper: `path=` loads a file; `text=` strips `type: prompt` frontmatter from an in-memory string.
1. `path`
*> prompt_load path=`path`*
2. `text`
*> prompt_body src=`text`*
3. *
> print text=ext/ai/llm.prompt: pass path= or text=
> sys.exit code=1
**base_url = > sys.env_get name="OPENAI_BASE_URL"**
1. not `base_url`
**base_url = > sys.env_get name="MARQDO_LLM_BASE_URL"**
1. not `base_url`
**base_url = "https://api.openai.com/v1"**
## ask
+ `prompt`=None
+ `path`=None
+ `model`=None
+ `base_url`=None
+ `api_key`=None
**model = > sys.env_get name="OPENAI_MODEL"**
1. not `model`
**model = > sys.env_get name="MARQDO_LLM_MODEL"**
1. not `model`
**model = "gpt-4o-mini"**
Module convenience: create a default handle and return **answer text**. Pass `path=` to load a prompt document, `prompt=` text, or omit both to use the entry `.mq.md` as a prompt artifact (`type: prompt` body via `sys.module_source`).
1. `path`
**p = > prompt_load path=`path`**
2. `prompt`
**p = prompt**
3. *
**raw = > sys.module_source**
1. not `raw`
> print text=ext/ai/llm.ask: pass prompt= or path= (or run a prompt document as entry)
> sys.exit code=1
2. *
**p = > prompt_body src=`raw`**
**m = > create model=`model` base_url=`base_url` api_key=`api_key`**
**r = > m.ask prompt=`p`**
**_ret = > json.get value=`r` key="text"**
*_ret*
# llm
+ `model`=None
+ `base_url`=None
+ `api_key`=None
+ `backend`=openai-compatible
+ `name`=None
LLM handle — intelligence primitive, not an HTTP client.
Resolution: explicit args → entry-scope / Artifact Metadata (`sys.meta_get`) → `sys.env_get` → defaults.
Prefer declaring `model` / `api_key` / `base_url` in frontmatter Binding, then use the lifted names.
1. `api_key`
**key = api_key**
2. *
**key = > sys.meta_get key="api_key"**
1. not `key`
**key = > sys.env_get name="OPENAI_API_KEY"**
1. not `key`
**key = > sys.env_get name="MARQDO_LLM_API_KEY"**
2. *
**_ = 1**
2. *
**_ = 1**
1. `backend` == ollama
1. not `key`
**key = "ollama"**
2. *
**_ = 1**
2. not `key`
> print text=ext/ai/llm: set OPENAI_API_KEY or MARQDO_LLM_API_KEY (or pass api_key= / metadata api_key)
> sys.exit code=1
3. *
**_ = 1**
1. `base_url`
**url = base_url**
2. *
**url = > sys.meta_get key="base_url"**
1. `url`
**_ = 1**
2. `backend` == ollama
**url = > sys.env_get name="OLLAMA_HOST"**
1. not `url`
**url = "http://127.0.0.1:11434/v1"**
2. *
**_ = 1**
3. *
**url = > sys.env_get name="OPENAI_BASE_URL"**
1. not `url`
**url = > sys.env_get name="MARQDO_LLM_BASE_URL"**
2. *
**_ = 1**
1. not `url`
**url = "https://api.openai.com/v1"**
2. *
**_ = 1**
1. `model`
**mdl = model**
2. *
**mdl = > sys.meta_get key="model"**
1. `mdl`
**_ = 1**
2. *
**mdl = > sys.env_get name="OPENAI_MODEL"**
1. not `mdl`
**mdl = > sys.env_get name="MARQDO_LLM_MODEL"**
2. *
**_ = 1**
1. not `mdl`
1. `backend` == ollama
**mdl = "llama3.2"**
2. *
**mdl = "gpt-4o-mini"**
2. *
**_ = 1**
1. `name`
**nm = name**
2. *
**nm = None**
`h` =
| api_key | base_url | model | suffix | bearer |
|---------|----------|-------|--------|--------|
| `api_key` | `base_url` | `model` | /chat/completions | "Bearer " |
| _type | backend | api_key | base_url | model | suffix | bearer | name |
|-------|---------|---------|----------|-------|--------|--------|------|
| llm | `backend` | `key` | `url` | `mdl` | /chat/completions | "Bearer " | `nm` |
*h*
## ask
+ `prompt`=None
+ `path`=None
Semantic ask → **LLMResult** (`text`, `model`, `finish`, `backend`, `usage`, `name`, `tool_calls`). Prefer `[text](result)` for the answer string. Omit `prompt=` / `path=` to use the entry document (`sys.module_source` + `prompt_body`).
1. `path`
**p = > prompt_load path=`path`**
2. `prompt`
**p = prompt**
3. *
**raw = > sys.module_source**
1. not `raw`
> print text=ext/ai/llm: ask needs prompt= or path= (or entry prompt document)
> sys.exit code=1
2. *
**p = > prompt_body src=`raw`**
**pack = > self.complete_result prompt=`p` stream=False echo=False**
**text = > json.get value=`pack` key="text"**
**usage = > json.get value=`pack` key="usage"**
**finish = > json.get value=`pack` key="finish"**
**err = > json.get value=`pack` key="error"**
**tc = > json.get value=`pack` key="tool_calls"**
1. not `tc`
**tc = > table.empty_list**
2. *
**_ = 1**
1. not `text`
**text = ""**
2. *
**_ = 1**
1. not `finish`
1. `err`
**finish = "error"**
2. *
**finish = "stop"**
2. *
**_ = 1**
Hoist receiver fields before the result table — table cells can shadow `self` /
column names (`model`, `usage`), so `[model](self)` / `[total_tokens](usage)`
inside the table is unsafe.
**mdl = > json.get value=`self` key="model"**
**b = > json.get value=`self` key="backend"**
**nm = > json.get value=`self` key="name"**
1. `usage`
**tt = > json.get value=`usage` key="total_tokens"**
2. *
**tt = 0**
1. not `tt`
**tt = 0**
2. *
**_ = 1**
1. `err`
**calls = 0**
2. *
**calls = 1**
`result` =
| text | model | finish | backend | usage | name | llm_calls | tokens | tool_calls | error |
|------|-------|--------|---------|-------|------|-----------|--------|------------|-------|
| `text` | `mdl` | `finish` | `b` | `usage` | `nm` | `calls` | `tt` | `tc` | `err` |
*result*
## stream
+ `prompt`=None
+ `path`=None
+ `echo`=False
Semantic stream: return the event list (use `llm.collect` to reduce to text). Omit `prompt=` / `path=` to use the entry document.
1. `path`
**p = > prompt_load path=`path`**
2. `prompt`
**p = prompt**
3. *
**raw = > sys.module_source**
1. not `raw`
> print text=ext/ai/llm: stream needs prompt= or path= (or entry prompt document)
> sys.exit code=1
2. *
**p = > prompt_body src=`raw`**
*> self.complete prompt=`p` stream=True echo=`echo`*
## complete_result
+ `prompt`
+ `stream`=False
+ `echo`=False
Transport pack via `ext/ai/llm/openai` (Ollama uses the same OpenAI-compatible path). Non-stream → `{text,usage,finish}`; stream → `{events}`.
*> openai.chat_completions base_url=[base_url](self) api_key=[api_key](self) model=[model](self) prompt=`prompt` stream=`stream` echo=`echo` suffix=[suffix](self) bearer=[bearer](self)*
## complete
+ `prompt`
+ `stream`=False
+ `echo`=False
Chat completion using `self` handle fields.
Wire body is `{model, messages:[{role,content}], stream?}`. Messages are an `@` row table; headers and optional `stream` use `table.put`. `json` is only for stringify/parse.
**url = [base_url](self) + [suffix](self)**
**auth = [bearer](self) + [api_key](self)**
**headers = > table.put in=None at="Authorization" value=`auth`**
`messages` =
| @ | role | content |
|---|------|---------|
| 1 | user | `prompt` |
`req` =
| model | messages |
|-------|----------|
| [model](self) | `messages` |
Internal / compatibility primitive. Prefer `ask` / `stream` in new code.
1. `stream`
**req = > table.put in=`req` at="stream" value=True**
**body = > json.stringify value=`req`**
**resp = > net.http_post_sse url=`url` body=`body` headers=`headers` echo=`echo`**
1. [status](resp) == 200
*[events](resp)*
2. *
> print text=ext/ai/llm: HTTP error (stream)
> print text=[status](resp)
> sys.exit code=1
**pack = > self.complete_result prompt=`prompt` stream=True echo=`echo`**
**_ret = > json.get value=`pack` key="events"**
*_ret*
2. *
**body = > json.stringify value=`req`**
**resp = > net.http_post url=`url` body=`body` headers=`headers`**
1. [status](resp) == 200
**data = > json.parse text=[body](resp)**
*[content]([message]([1]([choices](data))))*
2. *
> print text=ext/ai/llm: HTTP error
> print text=[status](resp)
> print text=[body](resp)
> sys.exit code=1
---
**pack = > self.complete_result prompt=`prompt` stream=False echo=`echo`**
**_ret = > json.get value=`pack` key="text"**
*_ret*
## chat
+ `prompt`
+ `stream`=False
+ `echo`=False
Alias for `complete`.
Alias for `complete` (compat).
*> self.complete prompt=`prompt` stream=`stream` echo=`echo`*
+55
View File
@@ -0,0 +1,55 @@
---
title: ext/ai/llm/ollama
description: >-
Ollama backend defaults. Transport reuses openai-compatible /v1 chat completions.
import openai:ext/ai/llm/openai.mq.md
import sys:lib/sys.mq.md
---
## resolve
+ `model`=None
+ `base_url`=None
+ `api_key`=None
Resolve Ollama handle fields: default host `http://127.0.0.1:11434/v1`, key `ollama`, model `llama3.2`.
1. `api_key`
**key = api_key**
2. *
**key = "ollama"**
1. `base_url`
**url = base_url**
2. *
**url = > sys.env_get name="OLLAMA_HOST"**
1. not `url`
**url = "http://127.0.0.1:11434/v1"**
2. *
**_ = 1**
1. `model`
**mdl = model**
2. *
**mdl = > sys.env_get name="MARQDO_LLM_MODEL"**
1. not `mdl`
**mdl = "llama3.2"**
2. *
**_ = 1**
`cfg` =
| backend | api_key | base_url | model |
|---------|---------|----------|-------|
| ollama | `key` | `url` | `mdl` |
*cfg*
## chat_completions
+ `base_url`
+ `api_key`
+ `model`
+ `prompt`
+ `stream`=False
+ `echo`=False
*> openai.chat_completions base_url=`base_url` api_key=`api_key` model=`model` prompt=`prompt` stream=`stream` echo=`echo`*
+184
View File
@@ -0,0 +1,184 @@
---
title: ext/ai/llm/openai
description: >-
OpenAI-compatible chat completions transport (HTTP + SSE).
Prefers optional plugins/llm ABI when present; falls back to lib/net.
Used by ext/ai/llm; authors should prefer llm.ask / llm.stream.
Result packs are GFM tables / table.put (code-as-documentation).
import net:lib/net.mq.md
import json:lib/json.mq.md
import table:lib/table.mq.md
import sys:lib/sys.mq.md
import plugin:lib/plugin.mq.md
---
## usage_from
+ `data`
Extract `{prompt_tokens,completion_tokens,total_tokens}` from an OpenAI-shaped response map.
**u = > json.get value=`data` key="usage"**
1. `u`
**pt = > json.get value=`u` key="prompt_tokens"**
**ct = > json.get value=`u` key="completion_tokens"**
**tt = > json.get value=`u` key="total_tokens"**
1. not `pt`
**pt = 0**
2. *
**_ = 1**
1. not `ct`
**ct = 0**
2. *
**_ = 1**
1. not `tt`
**tt = pt + ct**
2. *
**_ = 1**
2. *
**pt = 0**
**ct = 0**
**tt = 0**
`usage` =
| prompt_tokens | completion_tokens | total_tokens |
|---------------|-------------------|--------------|
| `pt` | `ct` | `tt` |
*usage*
## tool_calls_from
+ `data`
Extract OpenAI-shaped `choices[0].message.tool_calls` as a list (or empty list).
**choices = > json.get value=`data` key="choices"**
1. not `choices`
*> table.empty_list*
2. *
**c0 = [1](choices)**
**msg = > json.get value=`c0` key="message"**
1. not `msg`
*> table.empty_list*
2. *
**tc = > json.get value=`msg` key="tool_calls"**
1. `tc`
*tc*
2. *
*> table.empty_list*
## chat_completions
+ `base_url`
+ `api_key`
+ `model`
+ `prompt`
+ `stream`=False
+ `echo`=False
+ `suffix`=/chat/completions
+ `bearer`="Bearer "
POST `/chat/completions` (or stream SSE). Prefers `plugins/llm` ABI (`llm_chat_completions`) when the native plugin is resolvable; otherwise `lib/net` HTTP/SSE. Non-stream → `{text,usage,finish,tool_calls}`; stream → `{events,finish}`. Soft transport / HTTP failures return `finish=error` packs (never abort the VM).
**p = > plugin.native_path name="llm"**
1. `p`
> plugin.load path=`p`
*> llm_chat_completions base_url=`base_url` api_key=`api_key` model=`model` prompt=`prompt` stream=`stream` echo=`echo` suffix=`suffix` bearer=`bearer`*
2. *
**url = base_url + suffix**
**auth = bearer + api_key**
**headers = > table.put in=None at="Authorization" value=`auth`**
`messages` =
| @ | role | content |
|---|------|---------|
| 1 | user | `prompt` |
`req` =
| model | messages |
|-------|----------|
| `model` | `messages` |
1. `stream`
**req = > table.put in=`req` at="stream" value=True**
**body = > json.stringify value=`req`**
**resp = > net.http_post_sse url=`url` body=`body` headers=`headers` echo=`echo`**
**st = > json.get value=`resp` key="status"**
1. `st` == 200
**evs = > json.get value=`resp` key="events"**
`pack` =
| finish | events |
|--------|--------|
| stop | `evs` |
*pack*
2. *
Soft transport / HTTP failure — structured pack, never abort the VM.
**msg = "HTTP " + `st`**
**evs = > json.get value=`resp` key="events"**
1. `evs`
**e0 = > at value=`evs` index=0**
**m2 = > json.get value=`e0` key="message"**
1. `m2`
**msg = `m2`**
`pack` =
| finish | text | error | events |
|--------|------|-------|--------|
| error | "" | `msg` | `evs` |
*pack*
2. *
**body = > json.stringify value=`req`**
**resp = > net.http_post url=`url` body=`body` headers=`headers`**
**st = > json.get value=`resp` key="status"**
1. `st` == 200
**raw = > json.get value=`resp` key="body"**
**data = > json.parse text=`raw`**
**choices = > json.get value=`data` key="choices"**
**choice0 = > at value=`choices` index=0**
**msg = > json.get value=`choice0` key="message"**
**text = > json.get value=`msg` key="content"**
1. not `text`
**text = ""**
2. *
**_ = 1**
**usage = > usage_from data=`data`**
**fr = > json.get value=`choice0` key="finish_reason"**
1. not `fr`
**fr = "stop"**
2. *
**_ = 1**
**tc = > tool_calls_from data=`data`**
`pack` =
| finish | text | usage | tool_calls |
|--------|------|-------|------------|
| `fr` | `text` | `usage` | `tc` |
*pack*
2. *
Soft transport / HTTP failure — structured pack, never abort the VM.
**raw = > json.get value=`resp` key="body"**
**msg = "HTTP " + `st`**
1. `raw`
**msg = `msg` + ": " + `raw`**
`usage0` =
| prompt_tokens | completion_tokens | total_tokens |
|---------------|-------------------|--------------|
| 0 | 0 | 0 |
**empty_tc = > table.empty_list**
`pack` =
| finish | text | error | usage | tool_calls |
|--------|------|-------|-------|------------|
| error | "" | `msg` | `usage0` | `empty_tc` |
*pack*
+25
View File
@@ -0,0 +1,25 @@
---
title: step-route policy (O3)
description: >
Table-driven map from step class → Adaptive Routing backend.
Readable authority for agent.step_route; do not invent a second dialect.
---
# Step class → backend
Authors and `agent.step_route` read this table. Backends match Adaptive Routing:
`marqdo` | `small-llm` | `llm` | `auto`.
**routes = **
| kind | backend | note |
|------|---------|------|
| lookup | marqdo | OKF / kb skill hit — no parent LLM |
| patch | small-llm | Local patch / soft match |
| sandbox_run | marqdo | CoW trial of `.mq.md` |
| net | llm | Needs network / toolful turn |
| default | auto | Cascade policy → kb → small-llm |
# main
*routes*
+191
View File
@@ -0,0 +1,191 @@
---
title: ext/ai/sandbox
description: >-
CoW trial workspace for AI-generated Marqdo: open / run / diff / commit.
Native work lives in plugins/agent (`sandbox_*` → host_query).
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
import table:lib/table.mq.md
import fs:lib/fs.mq.md
---
Load the agent plugin once per call (same pattern as other `ext/ai` helpers).
Capability profiles are GFM tables under `## profile` (readable authority; `open` / `inspect` echo them). Do not invent a second table dialect.
## ensure_plugin
**p = plugin.native_path name="agent"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/ai/sandbox: native agent plugin not found (build marqdo_plugin_agent or marqdo ext add agent)
> sys.exit code=1
## profile
+ `name`=default
Named caps row as a map table (`name`, `fs_write`, `exec`, `net`, `plugin`). Unknown names → `default`.
Catalog (documentation + authority):
| name | fs_write | exec | net | plugin |
|------|----------|------|-----|--------|
| default | true | false | false | false |
| readonly | false | false | false | false |
1. `name` == "readonly"
**row = **
| name | fs_write | exec | net | plugin |
|------|----------|------|-----|--------|
| readonly | false | false | false | false |
2. *
**row = **
| name | fs_write | exec | net | plugin |
|------|----------|------|-----|--------|
| default | true | false | false | false |
*row*
## open_native
+ `root`=None
Native CoW open (plugin ABI italic return). Prefer `## open` for the profile-aware facade.
> ensure_plugin
1. `root`
*> sandbox_open root=`root`*
2. *
*> sandbox_open*
## open
+ `root`=None
+ `profile`=default
Open a CoW session. Optional `root=` (directory). Default: entry file directory.
`profile=` selects the caps row from `## profile` (echoed by `inspect`).
**sess = open_native root=`root`**
**prof = profile name=`profile`**
**sess = table.put in=`sess` at="profile" value=`prof`**
*sess*
## write
+ `id`
+ `path`
+ `text`
Write text into the session upper layer (host tree unchanged until `commit`).
> ensure_plugin
*> sandbox_write id=`id` path=`path` text=`text`*
## read
+ `id`
+ `path`
Read through CoW (upper, else lower; whiteout misses).
> ensure_plugin
*> sandbox_read id=`id` path=`path`*
## remove
+ `id`
+ `path`
Logical delete (whiteout).
> ensure_plugin
*> sandbox_remove id=`id` path=`path`*
## diff
+ `id`
List of `{ path, kind }` pending changes (`write` | `remove`).
> ensure_plugin
*> sandbox_diff id=`id`*
## commit
+ `id`
Apply upper / whiteout to the real workspace root.
> ensure_plugin
*> sandbox_commit id=`id`*
## discard
+ `id`
Drop the session without writing the host tree.
> ensure_plugin
*> sandbox_discard id=`id`*
## run
+ `id`
+ `source`=None
+ `path`=None
Run Marqdo under sandbox caps (`exec` / `net` / `plugin` off; fs via CoW).
Pass `source=` or `path=` (relative to session root).
> ensure_plugin
1. `source`
*> sandbox_run id=`id` source=`source`*
2. `path`
*> sandbox_run id=`id` path=`path`*
3. *
> print text=ext/ai/sandbox.run: need source= or path=
> sys.exit code=1
## inspect_native
+ `id`
> ensure_plugin
*> sandbox_inspect id=`id`*
## inspect
+ `id`
+ `profile`=default
Native caps / change counts, plus the GFM `## profile` row under key `profile`.
**raw = inspect_native id=`id`**
**prof = profile name=`profile`**
**out = table.put in=`raw` at="profile" value=`prof`**
*out*
## report
+ `id`
+ `path`=sandbox-diff.md
O4: write a markdown review of `## diff` for `marqdo view` / HITL (static report file, not a UI rewrite).
**pending = diff id=`id`**
**n = len value=`pending`**
**body = "# Sandbox diff report\n\nPending changes: "**
**body = body + n**
**body = body + "\n\n| path | kind |\n|------|------|\n"**
- [row](pending)
**p = [path](row)**
**k = [kind](row)**
**body = body + "| "**
**body = body + p**
**body = body + " | "**
**body = body + k**
**body = body + " |\n"**
> fs.write_text path=`path` text=`body`
**out = **
| path | count |
|------|-------|
| `path` | `n` |
*out*
+245 -72
View File
@@ -1,24 +1,23 @@
---
title: ext/ai/大模型
description: OpenAI 兼容大模型对象(中文)。导入 ext/ai/大模型.mq.md。
description: >-
Marqdo 大模型智能原语 — 提问 / 流式 / 收集 / 命名句柄。
OpenAI 兼容与 Ollama HTTP 藏在语义面之后。
导入 系统:lib/系统.mq.md
导入 网络:lib/网络.mq.md
import json:lib/json.mq.md
导入 表:lib/表.mq.md
导入 文件:lib/文件.mq.md
导入 文本:lib/文本.mq.md
import openai:ext/ai/llm/openai.mq.md
---
## 加载环境
+ `路径`=None
从工作目录加载 `.env`(可选命名实参 `路径=`)。不覆盖已有变量。
*> 系统.加载环境 路径=`路径`*
## 流式结果
## 收集
+ `事件`
把 `运行 流式=真` 的事件列表收成最终 `done.result`(或 `error.message`)。未知类型(如 `reasoning`)忽略。
**answer = ""**
- [ev](事件)
@@ -28,97 +27,271 @@ import json:lib/json.mq.md
2. `t` == "error"
**answer = [message](ev)**
3. `t` == "delta"
4. *
4. `t` == "text"
**chunk = [text](ev)**
1. `chunk`
**answer = answer + chunk**
2. *
**_ = 1**
5. *
**_ = 1**
*answer*
# 大模型
## 流式结果
+ `事件`
从 `OPENAI_*` / `MARQDO_LLM_*` 构造句柄。
*> 收集 事件=`事件`*
**api_key = > 系统.取环境 名="OPENAI_API_KEY"**
1. 非 `api_key`
**api_key = > 系统.取环境 名="MARQDO_LLM_API_KEY"**
## 用量
+ `数据`
1. 非 `api_key`
> 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY
*> openai.usage_from data=`数据`*
## 创建
+ `模型`=None
+ `基址`=None
+ `密钥`=None
+ `后端`=openai-compatible
+ `名`=None
**h = > 大模型 模型=`模型` 基址=`基址` 密钥=`密钥` 后端=`后端` 名=`名`**
*h*
## 快速
+ `模型`=None
+ `基址`=None
+ `密钥`=None
1. `模型`
**mdl = 模型**
2. *
**mdl = > 系统.取环境 名="MARQDO_LLM_FAST_MODEL"**
*> 创建 模型=`mdl` 基址=`基址` 密钥=`密钥` 名="fast" 后端="openai-compatible"*
## 推理
+ `模型`=None
+ `基址`=None
+ `密钥`=None
1. `模型`
**mdl = 模型**
2. *
**mdl = > 系统.取环境 名="MARQDO_LLM_REASONING_MODEL"**
*> 创建 模型=`mdl` 基址=`基址` 密钥=`密钥` 名="reasoning" 后端="openai-compatible"*
## 提示正文
+ `源`
**sw = > 文本.开头是 内容=`源` 前缀="---"**
1. 非 `sw`
*源*
2. *
**parts = > split value=`源` sep="\n---\n"**
**n = > len value=`parts`**
1. `n` < 2
*源*
2. *
**fm = > at value=`parts` index=0**
**is_p = > 文本.包含 内容=`fm` 子串="type: prompt"**
1. 非 `is_p`
**is_p = > 文本.包含 内容=`fm` 子串="类型: 提示"**
2. *
**_ = 1**
1. `is_p`
**body = > at value=`parts` index=1**
*> 文本.去空白 s=`body`*
2. *
*源*
## 加载提示
+ `路径`
**raw = > 文件.读文本 路径=`路径`**
*> 提示正文 源=`raw`*
## 提示
+ `路径`=None
+ `文本`=None
1. `路径`
*> 加载提示 路径=`路径`*
2. `文本`
*> 提示正文 源=`文本`*
3. *
> 打印 内容=ext/ai/大模型.提示: 请传 路径= 或 文本=
> 系统.退出 码=1
**base_url = > 系统.取环境 名="OPENAI_BASE_URL"**
1. 非 `base_url`
**base_url = > 系统.取环境 名="MARQDO_LLM_BASE_URL"**
1. 非 `base_url`
**base_url = "https://api.openai.com/v1"**
## 提问
+ `提示`=None
+ `路径`=None
+ `模型`=None
+ `基址`=None
+ `密钥`=None
**model = > 系统.取环境 名="OPENAI_MODEL"**
1. 非 `model`
**model = > 系统.取环境 名="MARQDO_LLM_MODEL"**
1. 非 `model`
**model = "gpt-4o-mini"**
1. `路径`
**p = > 加载提示 路径=`路径`**
2. `提示`
**p = 提示**
3. *
> 打印 内容=ext/ai/大模型.提问: 请传 提示= 或 路径=
> 系统.退出 码=1
**m = > 创建 模型=`模型` 基址=`基址` 密钥=`密钥`**
**r = > m.提问 提示=`p`**
*[text](r)*
# 大模型
+ `模型`=None
+ `基址`=None
+ `密钥`=None
+ `后端`=openai-compatible
+ `名`=None
1. `密钥`
**key = 密钥**
2. *
**key = > 系统.取环境 名="OPENAI_API_KEY"**
1. 非 `key`
**key = > 系统.取环境 名="MARQDO_LLM_API_KEY"**
2. *
**_ = 1**
1. `后端` == ollama
1. 非 `key`
**key = "ollama"**
2. *
**_ = 1**
2. 非 `key`
> 打印 内容=ext/ai/大模型: 请设置 OPENAI_API_KEY 或 MARQDO_LLM_API_KEY
> 系统.退出 码=1
3. *
**_ = 1**
1. `基址`
**url = 基址**
2. `后端` == ollama
**url = > 系统.取环境 名="OLLAMA_HOST"**
1. 非 `url`
**url = "http://127.0.0.1:11434/v1"**
2. *
**_ = 1**
3. *
**url = > 系统.取环境 名="OPENAI_BASE_URL"**
1. 非 `url`
**url = > 系统.取环境 名="MARQDO_LLM_BASE_URL"**
2. *
**_ = 1**
1. 非 `url`
**url = "https://api.openai.com/v1"**
2. *
**_ = 1**
1. `模型`
**mdl = 模型**
2. *
**mdl = > 系统.取环境 名="OPENAI_MODEL"**
1. 非 `mdl`
**mdl = > 系统.取环境 名="MARQDO_LLM_MODEL"**
2. *
**_ = 1**
1. 非 `mdl`
1. `后端` == ollama
**mdl = "llama3.2"**
2. *
**mdl = "gpt-4o-mini"**
2. *
**_ = 1**
1. `名`
**nm = 名**
2. *
**nm = None**
`h` =
| api_key | base_url | model | suffix | bearer |
|---------|----------|-------|--------|--------|
| `api_key` | `base_url` | `model` | /chat/completions | "Bearer " |
| _type | backend | api_key | base_url | model | suffix | bearer | name |
|-------|---------|---------|----------|-------|--------|--------|------|
| 大模型 | `后端` | `key` | `url` | `mdl` | /chat/completions | "Bearer " | `nm` |
*h*
## 提问
+ `提示`=None
+ `路径`=None
1. `路径`
**p = > 加载提示 路径=`路径`**
2. `提示`
**p = 提示**
3. *
> 打印 内容=ext/ai/大模型: 提问需要 提示= 或 路径=
> 系统.退出 码=1
**pack = > 自.完整结果 提示=`p` 流式=False 打印增量=False**
**text = > json.get value=`pack` key="text"**
**usage = > json.get value=`pack` key="usage"**
**finish = > json.get value=`pack` key="finish"**
**tc = > json.get value=`pack` key="tool_calls"**
1. not `tc`
**tc = > json.parse text=[]**
2. *
**_ = 1**
表单元格会遮蔽 `自` / 列名,先取出字段再组结果表。
**mdl = [model](自)**
**b = [backend](自)**
**nm = [name](自)**
**tt = [total_tokens](usage)**
`result` =
| text | model | finish | backend | usage | name | llm_calls | tokens | tool_calls |
|------|-------|--------|---------|-------|------|-----------|--------|------------|
| `text` | `mdl` | `finish` | `b` | `usage` | `nm` | 1 | `tt` | `tc` |
*result*
## 流式
+ `提示`=None
+ `路径`=None
+ `打印增量`=False
1. `路径`
**p = > 加载提示 路径=`路径`**
2. `提示`
**p = 提示**
3. *
> 打印 内容=ext/ai/大模型: 流式需要 提示= 或 路径=
> 系统.退出 码=1
*> 自.运行 提示=`p` 流式=True 打印增量=`打印增量`*
## 完整结果
+ `提示`
+ `流式`=False
+ `打印增量`=False
*> openai.chat_completions base_url=[base_url](自) api_key=[api_key](自) model=[model](自) prompt=`提示` stream=`流式` echo=`打印增量` suffix=[suffix](自) bearer=[bearer](自)*
## 运行
+ `提示`
+ `流式`=False
+ `打印增量`=False
使用 `自` 句柄字段做聊天补全。
线上 body 为 `{model, messages:[{role,content}], stream?}`。消息用 `@` 行向表;headers 与可选 `stream` 用 `表.改`。`json` 只做 stringify/parse。
**url = [base_url](自) + [suffix](自)**
**auth = [bearer](自) + [api_key](自)**
**headers = > 表.改 入=None 于="Authorization" 值=`auth`**
`messages` =
| @ | role | content |
|---|------|---------|
| 1 | user | `提示` |
`req` =
| model | messages |
|-------|----------|
| [model](自) | `messages` |
1. `流式`
**req = > 表.改 入=`req` 于="stream" 值=True**
**body = > json.stringify value=`req`**
**resp = > 网络.提交流式 地址=`url` 内容=`body` headers=`headers` 打印增量=`打印增量`**
1. [status](resp) == 200
*[events](resp)*
2. *
> 打印 内容=ext/ai/大模型: HTTP 错误(流式)
> 打印 内容=[status](resp)
> 系统.退出 码=1
**pack = > 自.完整结果 提示=`提示` 流式=True 打印增量=`打印增量`**
*[events](pack)*
2. *
**body = > json.stringify value=`req`**
**resp = > 网络.提交 地址=`url` 内容=`body` headers=`headers`**
1. [status](resp) == 200
**data = > json.parse text=[body](resp)**
*[content]([message]([1]([choices](data))))*
2. *
> 打印 内容=ext/ai/大模型: HTTP 错误
> 打印 内容=[status](resp)
> 打印 内容=[body](resp)
> 系统.退出 码=1
---
**pack = > 自.完整结果 提示=`提示` 流式=False 打印增量=`打印增量`**
*[text](pack)*
## 聊天
+ `提示`
+ `流式`=False
+ `打印增量`=False
运行 的别名。
*> 自.运行 提示=`提示` 流式=`流式` 打印增量=`打印增量`*
+178 -22
View File
@@ -1,8 +1,10 @@
---
title: ext/ai/智能体
description: 文档驱动智能体 — 单步 / 多步;工具经 lib/子任务;运行时经 ABI v2 agent 插件。
description: 文档驱动智能体 v2 — 单步 / 多步 / 运行;技能编译经 ABI v2 agent 插件(情景 → 学习 → llm_free)。
导入 大模型:ext/ai/大模型.mq.md
import agent:ext/ai/agent.mq.md
import sandbox:ext/ai/sandbox.mq.md
import table:lib/table.mq.md
import json:lib/json.mq.md
导入 系统:lib/系统.mq.md
导入 自写回:lib/自写回.mq.md
@@ -86,13 +88,14 @@ import json:lib/json.mq.md
> 系统.退出 码=1
**id = > agent_alloc**
**h = > json.parse text={"_type":"智能体"}**
**h = > json.set map=`h` key="id" value=`id`**
**h = > json.set map=`h` key="model" value=`大模型`**
**h = > json.set map=`h` key="tools" value=`工具`**
`h` =
| _type | id | model | tools |
|-------|-----|-------|-------|
| 智能体 | `id` | `大模型` | `工具` |
1. `站立提示`
**h = > json.set map=`h` key="standing" value=`站立提示`**
**h = table.put in=`h` at="standing" value=`站立提示`**
2. *
**_ = 1**
@@ -106,23 +109,42 @@ import json:lib/json.mq.md
> agent_history_clear id=`id`
****
## 试跑
+ `路径`=None
+ `源码`=None
+ `根目录`=None
+ `写入路径`=None
+ `文本`=None
+ `提交`=真
+ `配置`=default
O1 可选沙盒试跑。转发 `agent.trial`(表风格返回;宿主树在成功 `提交` 前不变)。
*> agent.trial path=`路径` source=`源码` root=`根目录` write_path=`写入路径` text=`文本` commit=`提交` profile=`配置`*
## 单步
+ `任务`
+ `写回`=真
+ `流式`=假
+ `打印增量`=假
+ `沙盒`=假
+ `沙盒配置`=default
原子一轮:上下文 → 大模型 → 可选子任务调工具。返回 *map*(`status`、`task`、`decision`;成功含 `result`,可选 `tool` / `tool_result`;失败含 `error`)。默认(`写回=真`)将结果写入调用行下的命名槽 `ok` / `error`;传 `写回=假` 可关闭。
流式=真 时走 SSE;打印增量=真 边读边打印。返回 map 仍是最终 result 文本。
流式=真 时走 SSE;打印增量=真 边读边打印。返回 map 仍是最终 result 文本。`沙盒=真` 时结果附带沙盒配置行。
**ctx = > 构建单步上下文 智能体=`自` 任务=`任务`**
**id = > json.get value=`自` key="id"**
**model = > json.get value=`自` key="model"**
**tools = > json.get value=`自` key="tools"**
**user_turn = > json.parse text={"role":"user"}**
**user_turn = > json.set map=`user_turn` key="content" value=`任务`**
`user_turn` =
| role | content |
|------|---------|
| user | `任务` |
> agent_history_append id=`id` item=`user_turn`
1. `流式`
@@ -134,9 +156,11 @@ import json:lib/json.mq.md
**reply = > trim value=`reply`**
**decision = reply**
**tool_name = > 提取工具名 回复=`reply`**
**out = > json.parse text={"status":"ok"}**
**out = > json.set map=`out` key="task" value=`任务`**
**out = > json.set map=`out` key="decision" value=`decision`**
`out` =
| status | task | decision |
|--------|------|----------|
| ok | `任务` | `decision` |
1. `tool_name`
**tool_out = > 运行工具 工具=`tools` 名=`tool_name`**
@@ -144,8 +168,8 @@ import json:lib/json.mq.md
**deny = > split value=`tool_s` sep="Tool not allowed"**
**deny_n = > len value=`deny`**
1. `deny_n` > 1
**out = > json.set map=`out` key="status" value="error"**
**out = > json.set map=`out` key="error" value=`tool_s`**
**out = table.put in=`out` at="status" value="error"**
**out = table.put in=`out` at="error" value=`tool_s`**
**reply = tool_s**
2. *
**task_s = > json.stringify value=`任务`**
@@ -161,16 +185,25 @@ import json:lib/json.mq.md
**reply = > 大模型.流式结果 事件=`evs2`**
2. *
**reply = > model.运行 提示=`fp`**
**out = > json.set map=`out` key="tool" value=`tool_name`**
**out = > json.set map=`out` key="tool_result" value=`tool_s`**
**out = > json.set map=`out` key="result" value=`reply`**
**out = table.put in=`out` at="tool" value=`tool_name`**
**out = table.put in=`out` at="tool_result" value=`tool_s`**
**out = table.put in=`out` at="result" value=`reply`**
2. *
**out = > json.set map=`out` key="result" value=`reply`**
**out = table.put in=`out` at="result" value=`reply`**
**as_turn = > json.parse text={"role":"assistant"}**
**as_turn = > json.set map=`as_turn` key="content" value=`reply`**
`as_turn` =
| role | content |
|------|---------|
| assistant | `reply` |
> agent_history_append id=`id` item=`as_turn`
1. `沙盒`
**配置行 = sandbox.profile name=`沙盒配置`**
**out = table.put in=`out` at="sandbox_profile" value=`配置行`**
2. *
**_ = 1**
1. `写回`
**body = > json.stringify value=`out`**
**st = > json.get value=`out` key="status"**
@@ -183,6 +216,15 @@ import json:lib/json.mq.md
*out*
## 工程预检
+ `任务`
+ `根目录`="."
+ `知识目录`=None
Engineering First Information 门闩。转发 `agent.preflight`。
*> agent.preflight task=`任务` root=`根目录` marqdo_dir=`知识目录`*
## 多步
+ `目标`
+ `工作簿目录`=None
@@ -204,11 +246,125 @@ import json:lib/json.mq.md
+ `流式`=False
+ `打印增量`=False
+ `轨迹`=False
+ `工程预检`=False
+ `工程知识目录`=.marqdo
多步工作簿默认写入 OKF `知识库目录/resources/<slug>.mq.md`;仅当传入 `工作簿目录` 时才用临时 runs。转发至英文 `agent.plan`。`流式` / `打印增量` / `轨迹` 对应 `stream` / `echo` / `trace`;`软命中` → `soft_match`;`近义命中` / `近义阈值` → `near_match` / `near_threshold`。
多步工作簿默认写入 OKF `知识库目录/resources/<slug>.mq.md`;仅当传入 `工作簿目录` 时才用临时 runs。转发至英文 `agent.plan`。`流式` / `打印增量` / `轨迹` 对应 `stream` / `echo` / `trace`;`软命中` → `soft_match`;`近义命中` / `近义阈值` → `near_match` / `near_threshold`。`工程预检` → `eng_preflight`。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.plan goal=`目标` workbook_dir=`工作簿目录` workbook=`工作簿` max_rounds=`最大轮次` confirm=`确认分解` writeback=`写回` skeleton=`骨架` reuse=`复用` optimize=`优化` force=`强制` soft_match=`软命中` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` kb_dir=`知识库目录` improve_every=`改进周期` explore_n=`探索次数` stream=`流式` echo=`打印增量` trace=`轨迹`*
*> en.plan goal=`目标` workbook_dir=`工作簿目录` workbook=`工作簿` max_rounds=`最大轮次` confirm=`确认分解` writeback=`写回` skeleton=`骨架` reuse=`复用` optimize=`优化` force=`强制` soft_match=`软命中` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` kb_dir=`知识库目录` improve_every=`改进周期` explore_n=`探索次数` stream=`流式` echo=`打印增量` trace=`轨迹` eng_preflight=`工程预检` marqdo_dir=`工程知识目录`*
## 解析
+ `任务`
+ `知识库目录`=.marqdo/agent-kb
+ `近义命中`=True
+ `近义阈值`=0.78
技能解析(v2):exact → alias → canonical → near。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.resolve task=`任务` kb_dir=`知识库目录` near_match=`近义命中` near_threshold=`近义阈值`*
## 记录情景
+ `任务`
+ `状态`=ok
+ `结果`=None
+ `模式`=explore
+ `技能`=none
+ `观察`=None
+ `工作簿`=None
+ `缓存`=None
+ `匹配`=None
+ `大模型次数`=0
+ `工具次数`=0
+ `错误`=None
+ `记忆目录`=.marqdo/agent-memory
将一次执行沉淀为 `.mq.md` 情景记忆。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.record_episode task=`任务` status=`状态` result=`结果` mode=`模式` skill=`技能` observation=`观察` workbook=`工作簿` cache=`缓存` match=`匹配` llm_calls=`大模型次数` tool_calls=`工具次数` error=`错误` memory_dir=`记忆目录`*
## 尝试学习
+ `任务`
+ `知识库目录`=.marqdo/agent-kb
+ `记忆目录`=.marqdo/agent-memory
+ `改进周期`=3
+ `晋升`=True
情景足够时:归纳 → 合成候选 → 编译 → 可选晋升为 `llm_free` 技能。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.maybe_learn task=`任务` kb_dir=`知识库目录` memory_dir=`记忆目录` improve_every=`改进周期` promote=`晋升`*
## 运行
+ `任务`
+ `知识库目录`=.marqdo/agent-kb
+ `记忆目录`=.marqdo/agent-memory
+ `学习`=True
+ `校验`=True
+ `写回`=True
+ `复用`=True
+ `近义命中`=True
+ `近义阈值`=0.78
+ `晋升`=True
+ `改进周期`=3
+ `探索次数`=3
+ `最大轮次`=4
+ `流式`=False
+ `打印增量`=False
+ `轨迹`=False
+ `强制`=False
+ `路由`=auto
+ `路由模型`=None
+ `沙盒`=False
+ `沙盒配置`=default
+ `工程预检`=True
v2+P4 主入口:自适应路由 → 执行 → 记录情景 → 尝试学习(技能 + 策略)。`路由`=`auto`|`marqdo`|`small-llm`|`llm`(`jev` 为 `small-llm` 兼容别名);决策器用 `路由模型`(任意 llm 句柄)。`沙盒=真` 走 CoW 试跑;`工程预检` 对应 `efi`。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.run task=`任务` kb_dir=`知识库目录` memory_dir=`记忆目录` learn=`学习` verify=`校验` writeback=`写回` reuse=`复用` near_match=`近义命中` near_threshold=`近义阈值` promote=`晋升` improve_every=`改进周期` explore_n=`探索次数` max_rounds=`最大轮次` stream=`流式` echo=`打印增量` trace=`轨迹` force=`强制` router=`路由` router_model=`路由模型` sandbox=`沙盒` sandbox_profile=`沙盒配置` efi=`工程预检`*
## 路由
+ `任务`
+ `后端`=auto
+ `知识库目录`=.marqdo/agent-kb
+ `记忆目录`=.marqdo/agent-memory
+ `阈值`=0.78
自适应路由(阶段 4):`marqdo` / `small-llm` / `llm` / `auto`(`jev`→别名)。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.route task=`任务` backend=`后端` kb_dir=`知识库目录` memory_dir=`记忆目录` threshold=`阈值`*
## 编译策略
+ `记忆目录`=.marqdo/agent-memory
+ `最少证据`=3
+ `强制`=False
策略编译:稳定的 task→skill 映射 → `policies/router.mq.md`。
**model = > json.get value=`self` key="model"**
**tools = > json.get value=`self` key="tools"**
**standing = > json.get value=`self` key="standing"**
**en = > agent.agent model=`model` tools=`tools` standing=`standing`**
*> en.compile_policy memory_dir=`记忆目录` min_evidence=`最少证据` force=`强制`*
+63
View File
@@ -0,0 +1,63 @@
---
title: ext/ai/沙盒
description: >-
AI 试跑 CoW 工作区:打开 / 运行 / 差异 / 提交(中文面,委托英文 sandbox 模块)。
import sandbox:ext/ai/sandbox.mq.md
---
## 打开
+ `根`=None
*> sandbox.open root=`根`*
## 写入
+ `id`
+ `路径`
+ `文本`
*> sandbox.write id=`id` path=`路径` text=`文本`*
## 读取
+ `id`
+ `路径`
*> sandbox.read id=`id` path=`路径`*
## 删除
+ `id`
+ `路径`
*> sandbox.remove id=`id` path=`路径`*
## 差异
+ `id`
*> sandbox.diff id=`id`*
## 提交
+ `id`
*> sandbox.commit id=`id`*
## 丢弃
+ `id`
*> sandbox.discard id=`id`*
## 运行
+ `id`
+ `源码`=None
+ `路径`=None
1. `源码`
*> sandbox.run id=`id` source=`源码`*
2. `路径`
*> sandbox.run id=`id` path=`路径`*
3. *
> print text=沙盒.运行: 需要 源码= 或 路径=
> sys.exit code=1
## 检查
+ `id`
*> sandbox.inspect id=`id`*
+60
View File
@@ -0,0 +1,60 @@
---
title: ext/data/cache
description: Cache Resource (ADR 0007).
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
import table:lib/table.mq.md
---
## _load
**p = > plugin.native_path name="web"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/data: native web plugin not found
> sys.exit code=1
****
# cache
+ `url`="memory:"
Key–value cache. Use `memory:` for in-process (tests / single process) or `redis://host:6379/0` for Redis.
> _load
*> web_cache_new url=`url`*
## get
+ `key`
**url = [url](self)**
*> web_cache_get url=`url` key=`key`*
## set
+ `key`
+ `value`
+ `ttl`=None
Optional `ttl` is seconds until expiry.
**url = [url](self)**
*> web_cache_set url=`url` key=`key` value=`value` ttl=`ttl`*
## del
+ `key`
**url = [url](self)**
*> web_cache_del url=`url` key=`key`*
## exists
+ `key`
**url = [url](self)**
*> web_cache_exists url=`url` key=`key`*
## ttl
+ `key`
**url = [url](self)**
*> web_cache_ttl url=`url` key=`key`*
+238
View File
@@ -0,0 +1,238 @@
---
title: ext/data/db
description: Database Resource — CRUD, txn, migrate, FTS (ADR 0007).
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
import table:lib/table.mq.md
---
## _load
**p = > plugin.native_path name="web"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/data: native web plugin not found
> sys.exit code=1
****
# db
+ `url`="sqlite:site.db"
Open a database handle. URL schemes: `sqlite:path` (default), `postgres://…` / `postgresql://…` (same CRUD methods).
> _load
*> web_db_new url=`url`*
## init
+ `name`
+ `fields`
Create a table from a schema table. Optional columns: `唯一`/`unique`, `索引`/`index` (creates UNIQUE / INDEX), `外键`/`fk`/`references` (e.g. `posts.id` or `posts(id)`). Columns named `created_at` / `updated_at` are filled automatically on insert/update when present.
**url = [url](self)**
*> web_db_init url=`url` name=`name` fields=`fields`*
## insert
+ `table`
+ `rows`
+ `txn`=None
**url = [url](self)**
*> web_db_insert url=`url` table=`table` rows=`rows` txn=`txn`*
## select
+ `table`
+ `where`=None
+ `limit`=200
+ `order`=None
+ `txn`=None
Simple filters: one-row map of column→value (AND `=`), or rows `|字段|操作|值|` (`=` `!=` `>` `>=` `<` `<=` `like` `in` `between` `is null`; add `|或|` = `是` to join a row with `OR`). `order` is a column name with optional `-` prefix for descending (`"created_at"`, `"-created_at"`), comma-separated for multiple keys. Pass `txn` to read inside an open transaction. For pages (with a total), use `paginate`.
**url = [url](self)**
**r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`**
*[rows](r)*
## paginate
+ `table`
+ `where`=None
+ `limit`=200
+ `order`=None
+ `跳过`=0
+ `txn`=None
Like `select` but returns `{ rows, total }` — the total counts rows matching `where` regardless of `limit`/`跳过`, so you can render `上一页 / 下一页`. Set `跳过` to the number of rows to skip (e.g. page 2 with 10 per page ⇒ `跳过`=10).
**url = [url](self)**
*> web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=`跳过` txn=`txn`*
## get
+ `table`
+ `id`
+ `txn`=None
**url = [url](self)**
*> web_db_get url=`url` table=`table` id=`id` txn=`txn`*
## update
+ `table`
+ `id`
+ `row`
+ `txn`=None
**url = [url](self)**
*> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`*
## delete
+ `table`
+ `id`
+ `txn`=None
**url = [url](self)**
*> web_db_delete url=`url` table=`table` id=`id` txn=`txn`*
## exec
+ `sql`
+ `args`=None
+ `txn`=None
**url = [url](self)**
*> web_db_exec url=`url` sql=`sql` args=`args` txn=`txn`*
## query
+ `sql`
+ `args`=None
+ `txn`=None
Run bare SQL and return the result set — count / join / group / subqueries. Returns `{ rows, count }`.
**url = [url](self)**
*> web_db_query url=`url` sql=`sql` args=`args` txn=`txn`*
## count
+ `table`
+ `where`=None
+ `txn`=None
Count rows matching a `where` filter (same syntax as `select`). Returns a number.
**url = [url](self)**
**r = > web_db_count url=`url` table=`table` where=`where` txn=`txn`**
*[count](r)*
## migrate
+ `steps`
Apply versioned SQL migrations. `steps` is a `|version|sql|` / `|版本|SQL|` table. Applied versions are recorded in `_marqdo_migrations`. Re-running is a no-op for already-applied versions. SQLite only.
**url = [url](self)**
*> web_db_migrate url=`url` steps=`steps`*
## fts
+ `table`
+ `columns`
+ `name`=None
Create an FTS5 index on `table` for the listed content columns (CSV string or list). Default FTS name is `{table}_fts`. Keeps the index in sync via triggers. Requires integer `id` PK. SQLite only.
**url = [url](self)**
*> web_db_fts_create url=`url` table=`table` columns=`columns` name=`name`*
## search
+ `table`
+ `q`
+ `limit`=20
+ `name`=None
Full-text search (`MATCH`) against the FTS5 index from `fts`. Returns `{ rows, count }` with a `rank` column (bm25). SQLite only.
**url = [url](self)**
*> web_db_search url=`url` table=`table` q=`q` limit=`limit` name=`name`*
## 事务
Begin a transaction: borrows the pooled connection exclusively and returns a
`txn` handle. Write inside it, then `提交` (commit) or `回滚` (roll back).
Every statement runs on the same connection, so a batch is atomic.
**url = [url](self)**
*> web_db_begin url=`url`*
# txn
+ `txn`
+ `url`
A transaction handle from `db.事务`. All CRUD here runs on the transaction's
connection; finish with `提交` or `回滚`.
*self*
## insert
+ `table`
+ `rows`
**url = [url](self)**
**txn = [txn](self)**
*> web_db_insert url=`url` table=`table` rows=`rows` txn=`txn`*
## select
+ `table`
+ `where`=None
+ `limit`=200
+ `order`=None
Same filters as `db.select`; runs inside the transaction.
**url = [url](self)**
**txn = [txn](self)**
**r = > web_db_select url=`url` table=`table` where=`where` limit=`limit` order=`order` offset=None txn=`txn`**
*[rows](r)*
## get
+ `table`
+ `id`
**url = [url](self)**
**txn = [txn](self)**
*> web_db_get url=`url` table=`table` id=`id` txn=`txn`*
## update
+ `table`
+ `id`
+ `row`
**url = [url](self)**
**txn = [txn](self)**
*> web_db_update url=`url` table=`table` id=`id` row=`row` txn=`txn`*
## delete
+ `table`
+ `id`
**url = [url](self)**
**txn = [txn](self)**
*> web_db_delete url=`url` table=`table` id=`id` txn=`txn`*
## exec
+ `sql`
+ `args`=None
**url = [url](self)**
**txn = [txn](self)**
*> web_db_exec url=`url` sql=`sql` args=`args` txn=`txn`*
## 提交
Commit the transaction and return its connection to the pool.
**txn = [txn](self)**
*> web_db_commit txn=`txn`*
## 回滚
Roll the transaction back (undo every write) and return its connection.
**txn = [txn](self)**
*> web_db_rollback txn=`txn`*
+67
View File
@@ -0,0 +1,67 @@
---
title: ext/data/form
description: Form Resource — fields, validate, submit (ADR 0007).
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
import table:lib/table.mq.md
---
## _load
**p = > plugin.native_path name="web"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/data: native web plugin not found
> sys.exit code=1
****
# form
+ `table`=None
+ `action`=insert
+ `id`=None
Field table + rules table; submit writes through `# db`.
> _load
*> web_form_new table=`table` action=`action` id=`id`*
## fields
+ `fields`
*> web_form_fields form=`self` fields=`fields`*
## rules
+ `rules`
*> web_form_rules form=`self` rules=`rules`*
## labels
+ `submit`="Submit"
+ `cancel`="cancel"
+ `cancel_href`=""
Localized submit / cancel copy for rendered forms.
*> web_form_labels form=`self` submit=`submit` cancel=`cancel` cancel_href=`cancel_href`*
## validate
+ `rules`=None
+ `data`
*> web_form_validate form=`self` rules=`rules` data=`data`*
## render
+ `id`=form
+ `data`=None
+ `errors`=None
*> web_form_render form=`self` id=`id` data=`data` errors=`errors`*
## submit
+ `data`
+ `db`
**url = [url](db)**
*> web_form_submit form=`self` data=`data` url=`url`*
+86
View File
@@ -0,0 +1,86 @@
---
title: ext/data/storage
description: Object storage Resource (ADR 0007).
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
import table:lib/table.mq.md
---
## _load
**p = > plugin.native_path name="web"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/data: native web plugin not found
> sys.exit code=1
****
# storage
+ `url`="file:data/blobs"
Object storage. `file:dir` stores blobs on disk (offline / gold). `s3://bucket?endpoint=http://127.0.0.1:9000&access_key=…&secret_key=…` talks to MinIO / S3.
> _load
*> web_storage_new url=`url`*
## put
+ `key`
+ `body`=None
+ `path`=None
+ `content_type`="application/octet-stream"
Provide either `body` (text) or `path` (local file to upload).
**url = [url](self)**
*> web_storage_put url=`url` key=`key` body=`body` path=`path` content_type=`content_type`*
## get
+ `key`
**url = [url](self)**
*> web_storage_get url=`url` key=`key`*
## delete
+ `key`
**url = [url](self)**
*> web_storage_delete url=`url` key=`key`*
## list
+ `prefix`=""
**url = [url](self)**
*> web_storage_list url=`url` prefix=`prefix`*
# media
+ `storage`=None
Offline helpers for upload validation and saving into `# storage` (also used by HTTP `app.upload`).
> _load
*> web_media_new storage=`storage`*
## validate
+ `filename`
+ `content_type`="application/octet-stream"
+ `size`
+ `max_bytes`=5242880
+ `types`=None
*> web_upload_validate filename=`filename` content_type=`content_type` size=`size` max_bytes=`max_bytes` types=`types`*
## save
+ `path`
+ `key`=None
+ `content_type`="application/octet-stream"
+ `prefix`=uploads/
+ `storage`=None
**st = storage**
1. `st` == None
**st = [storage](self)**
2. *
*> web_upload_save storage=`st` path=`path` key=`key` content_type=`content_type` prefix=`prefix`*
+31
View File
@@ -0,0 +1,31 @@
---
title: ext/net/http
description: HTTP primitives surface for Web Runtime (ADR 0007). Prefer Document/Endpoint Artifacts over raw calls.
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
---
## _load
**p = > plugin.native_path name="web"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/net: native web plugin not found
> sys.exit code=1
****
## result
+ `ok`
+ `value`=None
+ `error`=None
Unified Result map `{ok, value, error}`.
`out` =
| ok | value | error |
|----|-------|-------|
| `ok` | `value` | `error` |
*out*
+10
View File
@@ -0,0 +1,10 @@
---
title: ext/net/url
description: URL helpers (stdlib wrappers). ADR 0007.
import net:lib/net.mq.md
---
## encode
+ `text`
*> net.url_encode text=`text`*
+41
View File
@@ -0,0 +1,41 @@
---
title: ext/net/websocket
description: WebSocket client Resource (ADR 0007).
import plugin:lib/plugin.mq.md
import sys:lib/sys.mq.md
import table:lib/table.mq.md
---
## _load
**p = > plugin.native_path name="web"**
1. `p`
> plugin.load path=`p`
2. *
> print text=ext/net: native web plugin not found
> sys.exit code=1
****
# ws
+ `timeout_sec`=30
WebSocket client helper.
> _load
`out` =
| timeout_sec | _type |
|-------------|-------|
| `timeout_sec` | ws |
*out*
## connect
+ `url`
+ `message`=""
+ `headers`=None
Single request–response: connect to `url`, send `message`, collect up to 256 server text replies (each up to 1 MiB), close. Transport errors and timeouts return `{ok:false, error}` instead of looking like an empty successful reply.
**timeout = [timeout_sec](self)**
*> web_ws_connect url=`url` message=`message` headers=`headers` timeout_sec=`timeout`*
Loaded 100 of 350 files, more files were not shown because too many files have changed in this diff. Show more