Compare commits

..
147 Commits
Author SHA1 Message Date
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
cflmyandCursor 5272acaea0 release: v1.1.0 —— 核心表面守卫 + 渐进式契约 + MLSP for AI
- Cargo.toml / marqdo-wasm / ext/VERSION → 1.1.0(CLI 与扩展同步)
- CHANGELOG v1.1.0(含核心表面 Δ = 无增删;诚实标注 P4(b) 盲测未达标)
- README 现状/安装/示例更新(新命令 check / --json / mlsp)
- debian/changelog 1.1.0-1ppa1;release.yml Highlights stub 更新
- 核心表面 Δ:无增删(19 构造不变;本版为 Runtime/Document 层变更)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 13:31:27 +08:00
cflmyandCursor cba51238b6 doc/next/002: 智能体框架「认知编译」构想(Learning → Compilation)
用户维护文档归档:每次执行沉淀 mq.md;>3 次调用自动总结优化出记忆文档;
完全学会后降能耗运行(少 LLM 思考 / Jev 决策模型 / 纯分支控制)。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 13:19:56 +08:00
cflmyandCursor 5fffb800f9 P4(b) 收口:mimo-v2.6-pro 两跑均端点 infra 不可评估,判据以 deepseek-flash 为准
- perf-validation-report §3 记录重跑终局(12/12→11/12 infra),(b) 判据判定不改
- three-problems-plan Phase 4 落地记录同步

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 13:10:28 +08:00
cflmyandCursor 1a729eb9ec P4 验证执行:(a)锚点消融✅/(c)契约消融✅/(d)防漂移✅/(e)守卫演练✅;(b)盲测 deepseek-flash 完成未达标、mimo-v2.6-pro 重跑中
- perf-validation.md:五实验协议/判据/材料(2026-09-23 自设计)
- perf-validation-report-2026-09-23.md:汇总报告(判据逐项对照 + 诚实结论)
- tests/blind_experiment.rs + tests/blind/:盲测 harness(查询通道/修复回路/usage 计量)+ 冻结材料(6 任务书 + docs-bundle)
- tests/contract_ablation.rs:四边界×三情形消融(拦截 100%/误报 0%/零回归)
- tests/drift_drill.rs:9 漂移必报 + 2 负对照
- src/mlsp.rs:syntax 卡片自持化(semantics/rule/sample/doc_quote)
- three-problems.md §5.1 判据矩阵逐行判定(问题 1✅ 2✅ 3❌);three-problems-plan.md Phase 4 落地记录
- 全量干净回归零失败

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 05:06:30 +08:00
cflmyandCursor 00c763300e test(repair): mimo-v2.6-flash cross-check + measurement-side hardening
mimo-v2.6-flash 终测:anchor 臂一轮 20/20=100%、plain 90%(最终 95%);
三轮双臂一轮修复率全部 >=85%(目标 >=80%),护栏 0 越界。

'测试不稳定'定性为三类测量端问题并全部加固(与 Marqdo 语义无关):
- 网关空体抖动 -> curl --retry + 5s 退避(加固后 0 次失败)
- 推理模型 reasoning_content 吃光 token 预算 -> max_tokens 2000->8000
- 模型输出格式畸形 -> parse_edits 容错(数组/单对象/NDJSON 多对象流/
  字符串化元素/字符串型行号/围栏/数字后多余引号的确定性修补 unquote_line_nums)

报告按模型分文件(repair-experiment-<date>-<model>.md),cflmy/mimo 双报告并存;
计划记录更新为三轮对照表。干净环境 cargo test 444/444 全绿(零回归);
ext_llm_*/ext_agent_*_live 为环境开关型实况测试,与本期无关。

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-23 01:27:01 +08:00
cflmyandCursor 224b3d4a66 test(repair): §5.2(a) 模型在环修复实验 —— 锚点消融:anchor 100%(20/20) vs plain 85%,≥80% 目标达成
- tests/repair_experiment.rs:真实消费 validate → repair_targets → 模型行编辑 → repair_apply(越界必拒)
  → 复验 的完整闭环(≤2 轮;容错重试;cflmy @ llm.cflmy.cn,.env 读取,#[ignore] 不进常规回归)
- 双臂消融:anchor(诊断带 doc_anchor/doc_quote/suggestion)vs plain(剥掉)——
  anchor 一轮修复 20/20=100%;plain 17/20=85%(3 例失败均为网络空体抖动)
- tests/common/mod.rs:golden 20 例与诊断/应用共享件抽出(repair_loop + experiment 同源)
- parse_edits 容错(数组/单对象/字符串化元素/围栏);越界必拒/abstain 由 repair_loop 硬断言覆盖
- 报告:doc/roadmap/repair-experiment-2026-09-22.md;.gitignore 补 .env(密钥不入库)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 21:10:03 +08:00
cflmyandCursor 81d26a265a docs(roadmap): 落地记录 —— T3.4 修复回路工程项完成(护栏 + golden 20 例);T3.3 编号归位
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 20:14:32 +08:00
cflmyandCursor 5b599125d1 feat(repair): T3.3 修复护栏 + golden 20 例 —— 机械护栏(有界行编辑·越界必拒·abstain)+ mlsp repair_apply
- src/repair.rs:行编辑有界应用(replace/delete/insert;触碰行必须落在靶点范围内,
  越界 ⇒ 整体拒绝 + 越界清单,源零字节不改 = abstain;表尾追加允许 end+1)
- mlsp repair_apply:护栏的 MLSP 出口(ranges + edits → 新源;越界报 mlsp.repair_out_of_scope)
- tests/repair_loop.rs:golden 20 例(10 骨架 × 2)走完整修复循环
  (诊断 → 靶点 → 金修复行编辑自动推导 → 范围自检 = 「易锚定」机器验证 → 应用 → 复验)
  + 护栏负例(越界必拒 + 源零字节不改 + 部分越界全拒)
- 待做:模型修复实验(把金修复换成模型编辑,测 ≥80% 修复率)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 20:13:41 +08:00
cflmyandCursor 18d89d6cf2 docs(roadmap): 落地记录更新 —— T3.4 完成;T3.3 golden 实验待做
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:47:19 +08:00
cflmyandCursor 199b5c532f docs(skill): T3.4 AI Skill 换骨 —— 背语法 → 查 MLSP;渐进式契约入语法面
- marqdo/SKILL.md: 置顶「查 MLSP」查询式工作流(五方法 + 行分隔 JSON 协议 + 修复护栏);
  渐进式契约三种表格形状/位置/四边界;工作流与 checklist 增加 validate/check 环节
- marqdo-dev/SKILL.md: 契约/MLSP/三层准入/错误出口唯一的开发戒律

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:46:25 +08:00
cflmyandCursor db5f0e830b feat(mlsp): Phase 3 MLSP for AI —— locate/syntax/validate/repair_targets/schema(T3.1/T3.2 + T2.6)
- src/mlsp.rs: 行分隔 JSON 协议 + 五 handler;语法唯一事实来源 = CORE_CONSTRUCTS(只加检索别名)
- repair_targets 带有界护栏策略(anchored-local / 越界必拒 abstain / max_attempts=2)
- schema 契约导出(T2.6):形参/返回/字段契约 + 升参清单 + 锚点
- marqdo mlsp 子命令:stdio 行分隔 JSON 服务
- tests/mlsp.rs 7 例全绿;全量回归零失败(含 262 gold)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:44:35 +08:00
cflmyandCursor 7a449c40b1 feat(contract): Phase 2 渐进式契约层 —— 契约表提取 + 四边界校验 + marqdo check 防漂移(T2.1–T2.5)
- src/contract.rs: 类型词汇(渐进标注)、参数/返回/字段三形状契约表解析、合并、四边界校验诊断
- src/parse/mod.rs: extract_function_contract —— 位置+形状双重判定,在升参推断之前提取;
  绑定表/普通文档表绝不吃(P1 零回归),契约表从 body 移除(元数据永不执行)
- src/interp.rs: 四边界校验 —— 调用实参(3 条调用路径)/返回/表绑定/字段访问
- src/check.rs + marqdo check [--json]: 漂移双向互查、未知类型名(附建议)、错位契约
- src/load.rs: label_error 保留结构化诊断(错误出口唯一,不拍平成字符串)
- T2.4: 全部契约诊断带 doc_anchor/doc_quote/contract_ref
- tests/contracts.rs 12 例全绿;全量回归零失败(含 262 gold)

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:40:08 +08:00
cflmyandCursor 97fda7aa10 feat(core): Phase 1 —— 核心收口 + 诊断地基(core-surface 守卫 · 三层准入 · Diagnostic JSON)
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 19:03:03 +08:00
cflmyandCursor a49592a3ba docs: 三大问题设计移出 doc/next/ → roadmap/three-problems.md;新增落地计划 three-problems-plan.md
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 17:46:09 +08:00
cflmyandCursor ed9ac03c0c docs: README 前置核心优势与愿景(Executable Knowledge 定位);doc/next 交流笔记入库
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 17:07:33 +08:00
cflmyandCursor cb46ad7abe fix(ppa): trim bundled Rust to build essentials; clean extract on failure
Launchpad builds only need rustc + cargo + rust-std (debian/rules PATH),
but install.sh was still shipping rust-docs-json-preview / rustfmt /
rls (~1G). Also drop the 1.5G extract dir via EXIT trap when install
fails — the leftover is what filled /tmp last run.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 16:40:39 +08:00
cflmyandCursor 586975090b release: v1.0.7 — WS/网络边界加固
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 15:40:48 +08:00
cflmyandCursor 544805266b fix(wasm): mark marqdo-bridge.js as ESM for Node consumers
The canonical bridge uses ESM exports but, with no package.json in scope,
Node loads untyped .js as CommonJS — tests/wasm/smoke.mjs could not see
applyDomPatch et al (Named export not found). Scope type=module to the js
dir only; marqdo wasm build copies just the single .js file, so nothing
ships differently.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 15:27:09 +08:00
cflmyandCursor f3051fb536 fix(test): align P3 gold with quiet-admin gate semantics
b752cd4 stopped auto-gating admin_prefix when admin=false but did not
update the P3 gold, which still expected the removed /admin auto gate
(ng >= 2). Assert the new intent instead: exactly one explicit gate
registered with the declared path.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 15:20:48 +08:00
cflmyandCursor 86b183e2d7 fix(web): harden WebSocket and net host boundaries
- WS handshake: same-origin CheckOrigin instead of allow-all
- route_ws require_auth/需要登录: broadcast/room need a session by default,
  explicit opt-out for public feeds; unauthenticated handshakes get 401
- WS limits: 1 MiB per message, 256 replies per connect; transport errors
  return {ok:false, error} instead of an empty success; empty rooms GC'd
- net host: enforce the 8 MiB response cap while reading (incl. error and
  SSE error paths) so a peer cannot exhaust memory
- url_encode: %20 for space (URL segment semantics, not form +)
- docs: sync 网页 (route_ws 需要登录, connect caps) and CHANGELOG
- tests: gold expectations, live fixture opt-out, hub GC, ws auth gate

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-22 15:14:35 +08:00
cflmyandCursor 8e23a5395a release: ext pack 1.0.6 — OIDC, form delete, quiet admin
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 16:46:01 +08:00
cflmyandCursor cab609ee91 fix(web): logout to home instead of OIDC login bounce
Clear the session and land on / when logout_redirect is an OIDC entry
path; also exclude */logout from RBAC gates so exit always runs locally.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 16:13:06 +08:00
cflmyandCursor b752cd49b7 fix(web): keep admin and RBAC desk quiet until opted in
Skip auto-gating admin_prefix when admin=false, and mount /_rbac/* only
when enable_rbac sets desk/管理台 so custom desks are not interfered with.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 16:01:40 +08:00
cflmyandCursor 2c91b5cc7b feat(web): OIDC login, form delete, and route-param intros
Add authorization-code OIDC for site auth, treat form action delete as a
generic CRUD primitive, and resolve {param} placeholders in page intros so
custom admin desks can stay in .mq.md without site-specific plugin patches.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 15:57:33 +08:00
cflmyandCursor 453321c8c2 perf(web): cache static assets and defer wasm boot
Add long Cache-Control for /static, version client embed URLs from
asset_version, and delay WASM mount until after load so LCP images win.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 15:07:54 +08:00
cflmyandCursor 981d754133 feat(web): allow Redis session URL separate from app DB
Wire session_url through app.auth/listen so sites can store sessions in
Redis while keeping Postgres/SQLite for application data.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 14:59:50 +08:00
cflmyandCursor 410f36f719 feat(web): Postgres CRUD and fix stale-session CSRF login
Wire pgx for postgres:// DB URLs, dialect-aware RBAC/sessions, and replace dead marqdo_sid cookies so login forms always get a fresh CSRF token.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 14:53:16 +08:00
cflmyandCursor bd06aedb90 fix(browser): pass optional then= through store_set
Theme toggle wrote localStorage but never chained to apply_theme because store_set dropped then.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 14:22:54 +08:00
cflmyandCursor 42ddeb14e7 fix(wasm): custom getrandom so browser wasm loads without wbindgen
The js feature pulled __wbindgen_* imports that marqdo-bridge cannot satisfy, breaking theme toggle and all client WASM.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 13:46:49 +08:00
cflmyandCursor 6bd127a313 feat(web): live markdown preview via POST /_md host glue
Markdown form fields render a dual-pane shell; official boot posts textarea input to /_md for GFM HTML without author business JS.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 13:01:43 +08:00
cflmyandCursor 4b7643d833 fix(web): prefer form redirect and soft-default now_if_empty
Desk 文案 cancel links stamp redirect so POST leaves the compose page; empty date fields can opt into 空则现在 without blocking custom values.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 12:58:24 +08:00
cflmyandCursor 3f96592c99 feat(web): form_load SSR prefill and safe {id} desk routes
Edit pages can stamp compose_form_load to hydrate forms from DB by route id without author JS. Part slots use {part} so pathParamNames can inject {id} again.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 12:50:59 +08:00
cflmyandCursor 98018fc63b feat(web): SSR nav brand/client embed and form markdown labels
Replace author theme.js with framework chrome (nav brand, theme boot,
client mount) plus bridge scroll/observe helpers; add form submit copy
and type=markdown textareas so sites can drop business JS.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 12:42:50 +08:00
cflmyandCursor aeac4d6d20 feat(web): SSR news rail via list target=rail and KaTeX boot glue
List binds with 插槽=rail render aside.side-rail and set has-rail; cards honor pinned; pages that load KaTeX auto-render get an official deferred math boot so authors need no volume.js.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 11:41:52 +08:00
cflmyandCursor 9e9a80df31 feat(web): progressive-enhancement auth forms for branded login pages
Custom /login and /desk/login can POST natively: CSRF/next are injected server-side, failures re-render the same site page with localized flash, and compose_auth_form / 鉴权表单 removes the need for author JS.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 11:30:33 +08:00
cflmyandCursor 5f07b1c3b1 fix(web): preserve absolute URLs in card hrefs
News and other cards with http(s) or root-relative links were incorrectly prefixed with link_prefix, breaking SSR /news.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 11:03:15 +08:00
cflmyandCursor bfea2204eb fix(web): inject CSRF meta on custom login pages
Site-owned GET /login no longer serves the framework form; stamp
csrf-token + session cookie on page render so JS can still POST /login.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 10:49:56 +08:00
cflmyandCursor fb30cd3db3 release: ext pack 1.0.5 — request context and list binds
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 10:24:34 +08:00
cflmyandCursor 584cb9ac9d feat(web): request-context field sources and page list binds
Replace domain comment hacks with generic session/route/now stamps,
server-only form fields, compose_list for detail+child lists, and a live gold.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-18 10:17:39 +08:00
cflmy 428ee141e1 fix(ppa): keep vendor checksums and reuse published orig on debian bumps
dh_clean was stripping Cargo.toml.orig and breaking Launchpad offline
builds; debian-only uploads now reuse the PPA orig with debuild -sd.
2026-09-18 09:02:53 +08:00
cflmyandCursor ec9718466d release: ext pack 1.0.4 — RBAC, tenant, WS hooks, SPA, collab
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 21:10:50 +08:00
cflmyandCursor c5bb08022a feat(web): collaborative notepad MVP over WS rooms
Add LWW text sync demo (DOC\\t protocol + presence) on route_ws rooms,
with design note and bag smoke.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 21:00:10 +08:00
cflmyandCursor b710745e88 feat(web): native SPA helpers, memory store, and demo
Add bridge scope=memory, lib/browser store_set/spa_goto, web-spa-app
list/detail/edit client routes demo, and helper smoke.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 20:58:21 +08:00
cflmyandCursor 5cf84fe9b7 feat(web): RBAC, tenant scope, and WS room hooks
Add configurable role⊥permission (five tables, gate permissions, register,
/_rbac desk), multi-tenant path/header resolution with JSON tenant_scope,
and route_ws on_message/presence/dynamic room_key — with author surfaces,
demos, and smokes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 20:54:02 +08:00
cflmyandCursor 27991a7822 docs(release): fold unbound-table fix into v1.0.3 notes
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 10:31:41 +08:00
cflmyandCursor d1e2f0ced0 fix(parse): allow unbound GFM tables as discarded values
Bare tables in a function body evaluate as collections without requiring
a name bind; restores welcome-page install tables.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 10:29:13 +08:00
cflmyandCursor e848306187 fix(public): drop bare GFM tables from welcome # main
Tables are collections in Marqdo; bare rows aborted pages CI.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 10:26:12 +08:00
cflmyandCursor 2ee9d7e66d release: v1.0.3 — PPA, ext CDN, synced CLI+ext packs
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 10:20:37 +08:00
cflmyandCursor e31585842d fix(ppa): bundle Rust toolchain for noble Cargo.lock v4 builds
Document install channels (PPA/GitHub/CDN); release skill supports
full/cli/ext modes with R2+GitHub ext uploads and manual PPA commands.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 10:18:50 +08:00
cflmyandCursor f068b4ab75 fix(packaging): skip cp when orig tarball already in build-area
Same-inode copy aborted ppa-build under set -e before dput.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 10:05:23 +08:00
cflmyandCursor 26e29409a9 docs(changelog): mention ppa-ship one-shot script
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 10:01:33 +08:00
cflmyandCursor 4923129d10 feat(packaging): add ppa-ship.sh one-shot build and dput
Installs apt deps with sudo, then builds/signs/uploads as the real user.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 10:01:22 +08:00
cflmyandCursor 8ab55e2193 docs(changelog): note Ubuntu PPA packaging scaffold
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 09:58:12 +08:00
cflmyandCursor 9bc7ef3b5a feat(packaging): scaffold Ubuntu PPA debian/ for marqdo CLI
Add control/rules/changelog and ppa-build-source.sh (cargo vendor + debuild -S).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 09:57:11 +08:00
cflmyandCursor 9431ad835c docs: link ext-cdn in doc/README
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 09:31:06 +08:00
cflmyandCursor 2984d7d4f8 feat(ext): prefer Cloudflare R2 CDN and allow separate ext pack versions
Download order is CDN (ext.marqdo.com) → GitHub → proxy; pack SemVer from
ext/VERSION / CDN latest; add upload-ext-r2.py and release-skill notes.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 09:28:28 +08:00
cflmyandCursor 6324036e41 fix(ext): mirror fallback for Release downloads and default ~/.marqdo/ext
Try proxy.cflmy.top when github.com fails; honor MARQDO_EXT_DOWNLOAD_BASE;
resolve ext imports from the ext-add install root without exporting MARQDO_EXT.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-17 08:57:24 +08:00
cflmyandCursor 3287799959 docs(skill): note table-bound page.compose_intro for v1.0.2
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-16 21:06:30 +08:00
cflmyandCursor f95e5d3339 release: v1.0.2 — table-bound page intro (compose_intro)
Ship web_compose_intro / 引言装配 and web-site demo polish; bump Cargo and docs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-16 21:05:49 +08:00
cflmyandCursor 52b4bae423 feat(web-site): harden sample desk, auth login, and form layout
Align nav/side/foot slots and shell CSS with table-driven admin desk;
add session login/logout mount and widen form fields for usable create UX.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-16 19:44:12 +08:00
cflmyandCursor 037592087c feat(web): table-bound intro and demo-grade web-site sample
Add compose_intro (属性/值/样式) so page heroes are not HTML strings, and polish examples/web-site for WWW Demo: literary shell, card→detail routes, richer seeds, particle atmosphere without author JS.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-09 13:58:02 +08:00
cflmyandCursor 68c4f8c822 release: v0.3.8 — Mid2 stdlib M7–M10
Ship calendar/URL/TOML/HTML/fs/stats plus GLOBAL_HOST restore;
bump Cargo, README, CHANGELOG, and release workflow highlights.

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

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

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

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

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

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

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-08 10:40:27 +08:00
888 changed files with 75405 additions and 12334 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.
+34 -9
View File
@@ -63,22 +63,22 @@ Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = tex
**Single dynamic key** — one `table.put` (or a helper), not a json chain:
```markdown
*`set_text` = > table.put in=None at="#log" value=msg*
**> table.put in=None at="set_text" value=set_text**
**`set_text` = table.put in=None at="#log" value=msg**
**table.put in=None at="set_text" value=set_text**
```
Better still — call a named helper:
```markdown
**> browser.set_text sel="#log" text=msg**
**browser.set_text sel="#log" text=msg**
```
### 3. Bad pattern (do not write)
```markdown
*`ret` = > json.set map=None key="set_text" value=…*
*`ret` = > json.set map=ret key="canvas" value=…*
*`cmds` = > json.append list=cmds item=c0*
**`ret` = json.set map=None key="set_text" value=…**
**`ret` = json.set map=ret key="canvas" value=…**
**`cmds` = json.append list=cmds item=c0**
```
## Writing application `.mq.md`
@@ -88,23 +88,31 @@ Better still — call a named helper:
3. `##` handlers: short prose OK; data as tables; return via `browser.*` / `web.*` / one `table.put`.
4. Blank line between comment paragraphs and code.
5. Run `marqdo run path.mq.md` from repo root.
6. **Calls in narrative:** prefer `**结果 = 某函数 名=`x`**` (no `>` on the RHS). Bracket form `礼貌 [问候] "x"` / `**出 = [put] …**` is fine when modifiers help. Use `> …` for standalone step lists. See `examples/code-as-docs/`.
7. **Do not use `##` inside `# main` for document sectioning** — those become nested functions. Use paragraphs / `---` breaks instead.
8. **Index:** prefer `[键](集合)` / `` [`名`](集合) `` over footnote `` m[^k] ``.
Browser client programs: prefer `import browser:lib/browser.mq.md` (no native plugin). Server sites: `ext/web` + GFM page/style tables.
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/*`)
Canonical thin-template + waves: [lib-code-as-docs.md](../../doc/design/lib-code-as-docs.md) · [roadmap/lib-ext-code-as-docs.md](../../doc/roadmap/lib-ext-code-as-docs.md).
### Goals
- **Authors** see tables and short calls; **library** may hide `table.put` / host calls.
- One concern per helper; name the effect (`set_text`, `canvas`, …), do not expose bag surgery.
- EN + ZH pair when shipping user-facing libs (`lib/browser.mq.md` ↔ `lib/浏览器.mq.md`, `ext/web` ↔ `ext/web/网页.mq.md`).
- `ext/**` never calls `host_*` — use plugins / public lib only (`doc/design/ext-agent.md`).
- Collection get: **`[key](coll)`** (no new footnote indexes). Calls in examples may use `修饰 [fn] …` or classic `>` / bold.
### Library checklist
- [ ] Purpose sentence + prose params + one example + short body
- [ ] Public examples use **tables + helpers**, not json glue
- [ ] Index with `[k](c)`; foreach `- [item](coll)`
- [ ] Helpers documented with a one-line purpose above `##`
- [ ] Defaults on `+` params; omit `None` fields in merged maps
- [ ] Defaults on params; omit `None` fields in merged maps
- [ ] No `json.set` chains in new code — use `table.put` / `table.merge` / GFM
- [ ] `marqdo run` on a tiny demo under `examples/` or inline smoke
@@ -113,7 +121,9 @@ Browser client programs: prefer `import browser:lib/browser.mq.md` (no native pl
| 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 |
@@ -142,3 +152,18 @@ When editing a file full of `json.set`:
- Tables: `doc/design/stdlib-table.md` · `doc/design/table-cell-expressions.md`
- Browser effects: `doc/roadmap/browser-wasm-e.md` · `doc/roadmap/browser-wasm-f.md`
- Release: [marqdo-release](../marqdo-release/SKILL.md)
## 渐进式契约 + MLSP(Phase 2/3 落地后的开发戒律)
- **契约实现**:`src/contract.rs`(类型词汇 / 三形状契约表解析 / 合并 / 四边界校验诊断);
`src/parse/mod.rs::extract_function_contract`(位置 + 形状双重判定,**在升参推断之前**执行;
绑定表与普通文档表绝不吃 ⇒ 无契约文件零回归)。契约表从 body 移除——元数据永不执行。
- **静态互查**:`src/check.rs`(`marqdo check [--json]`)——契约行 vs 升参推断形参双向漂移、
未知类型名、错位契约;Error ⇒ 非零退出。
- **AI 工具面**:`src/mlsp.rs`(`marqdo mlsp`,行分隔 JSON)——`locate` / `syntax` / `validate` /
`repair_targets` / `schema`。语法唯一事实来源 = `parse::CORE_CONSTRUCTS`(CI 守卫与
`doc/design/core-surface.md` 同步);MLSP 只加检索别名,**不定义语法**。
- **准入戒律**:新特性先过 `doc/design/layers.md` 三层归属(Language 层改动须 ADR + core-surface);
新契约形状/类型词汇 = 文档层扩展,进 `src/contract.rs`,不进词法/语法。
- **错误出口唯一**:`src/load.rs::label_error` 已示范——装载层/任何新代码都**不许**把
`Diagnostic` 拍平成字符串;错误链里必须能 `Diagnostic::find` 找回结构化诊断(AI/MLSP 面)。
+144 -101
View File
@@ -1,13 +1,14 @@
---
name: marqdo-release
description: >-
Run a full Marqdo product release: detect latest version and ask the user for
the next tag, update CHANGELOG/README/skills/public docs, bump Cargo versions,
sync VS Code extension on branch vscode-extension when needed, build or
trigger install assets (CLI, stdlib, ext, public zip, VSIX, wasm notes), push
tag, publish GitHub Release with detailed notes, and recover from network
failures via proxy. Use when the user asks to release, cut a version, publish
vX.Y.Z, ship a GitHub release, 发版, 发布新版本, or tag marqdo.
Run a Marqdo product release: detect latest version and ask the user for the
next tag (or confirm mode), update CHANGELOG/README/skills/public docs, bump
Cargo and/or ext/VERSION, sync VS Code extension when needed, publish GitHub
Release assets, upload extension packs to Cloudflare R2 (ext.marqdo.com) and
GitHub, ship Ubuntu CLI via PPA (scripts/ppa-ship.sh), and print manual
commands when sudo/GPG/network steps need the user. Use when the user asks to
release, cut a version, publish vX.Y.Z, ext-only pack, PPA, 发版, 发布新版本,
or tag marqdo.
---
# Marqdo release
@@ -16,151 +17,193 @@ Canonical release playbook for **cflmy/marqdo**. Read this skill **before** tagg
## Hard rules
1. **Never invent the next version.** Detect current versions → **stop and ask the user** for the next SemVer (`X.Y.Z`). Do not proceed until they confirm.
1. **Never invent the next version.** Detect current versions → **stop and ask the user** for the next SemVer (`X.Y.Z`) and **release mode** if unclear. Do not proceed until they confirm (unless they already stated both in the same message).
2. **Never force-push** `main` / tags. **Never** `--no-verify` unless the user explicitly orders it.
3. **Never commit `vscode-extension/` on `main`** (gitignored). Extension source lives only on branch **`vscode-extension`**. See `doc/design/vscode-extension-commit.md`.
4. **Do not release from a dirty tree** (except intentional release commits you create in this flow).
5. **Tag format** is always `vX.Y.Z` matching root `Cargo.toml` `version = "X.Y.Z"`.
6. Prefer **tag push → GitHub Actions** (`.github/workflows/release.yml`) for Windows CLI + VSIX + zips. Local packaging is fallback / verification.
7. After network errors: apply [reference.md § Proxy](reference.md); retry; do not silently skip uploads.
5. **Tag format:** CLI/full → `vX.Y.Z` matching root `Cargo.toml`. Ext-only → `ext-vX.Y.Z` matching `ext/VERSION` (Cargo may stay unchanged).
6. Prefer **tag push → GitHub Actions** (`.github/workflows/release.yml`) for Windows/Linux install assets. Local packaging is fallback / verification.
7. After network errors: apply [reference.md § Proxy](reference.md). **First try** `https://proxy.cflmy.top/github.com/cflmy/marqdo.git`. Retry; do not silently skip uploads. If needed: **HK jump** (`scripts/push-via-hk-jump.py`).
8. **Do not ship a full GitHub Release without the Linux extension/native zip** when the mode includes ext packs. Missing Linux packages = incomplete for that mode.
9. **Extension packs always publish to both** Cloudflare R2 (`https://ext.marqdo.com` via `scripts/upload-ext-r2.py`) **and** GitHub (Release assets / `ext-v*` tag). Credentials only in `~/.marqdo/r2.env` / CI — **never** commit. See [ext-cdn.md](../../../doc/design/ext-cdn.md).
10. **CLI Ubuntu package = PPA** (`ppa:cflmy/marqdo`) via `./scripts/ppa-ship.sh` / `ppa-build-source.sh`. GitHub zips remain for Windows and non-apt Linux.
11. **When a step needs the user** (sudo password, GPG passphrase, Launchpad UI, interactive `dput`): **stop, state what failed, and give the exact commands** to run in their terminal. Do not pretend the step succeeded.
## Defaults (after version is confirmed)
## Release modes
Unless the user overrides, apply these automatically — **do not re-ask**:
Ask (or take from user message) which mode:
| Mode | Bumps | Git tag | GitHub assets | R2 CDN | Ubuntu PPA |
|------|-------|---------|---------------|--------|------------|
| **full** (default) | `Cargo.toml` + `ext/VERSION` (same SemVer) | `vX.Y.Z` | CLI + ext + native + VSIX + … | yes | yes |
| **cli** | `Cargo.toml` only | `vX.Y.Z` | CLI (+ optional attach prior ext) | no (unless user asks) | yes |
| **ext** | `ext/VERSION` only | `ext-vX.Y.Z` (or attach to latest CLI release) | ext.zip + native-*.zip | **required** | no |
Defaults after version+mode confirmed — **do not re-ask**:
| Setting | Default |
|---------|---------|
| Sync / bump `vscode-extension` to same `VER` | **yes** |
| Push `main`, create annotated tag, push tag immediately (trigger CI) | **yes** |
| Release notes language | **中英双语** (Chinese first, then English section, or paired ZH/EN under each heading) |
| Skip VSIX | **no** |
| Docs-only release | **no** (full asset pipeline via CI) |
| Sync / bump `vscode-extension` to same `VER` | **yes** for full/cli; **no** for ext-only |
| Push `main`, create annotated tag, push tag (trigger CI) | **yes** for full/cli |
| Ext packs → R2 **and** GitHub | **yes** whenever ext ships |
| Ubuntu PPA upload after CLI tag | **yes** for full/cli |
| Release notes language | **中英双语** |
| Deploy gh-pages after release | **no** (only if user asks) |
Phase 0 asks **only** for the next version (and optional overrides). Example ask:
Phase 0 ask example:
> 当前最新是 **vA.B.C**。请指定下一个版本号(如 `0.3.2`)。其余按默认:同步扩展、立刻打 tag 发布、中英双语说明。
> 当前最新 CLI **vA.B.C**,扩展包 **E.F.G**。请指定下一个版本号与模式(`full` / `cli` / `ext`,如 `1.0.3 full`)。
## Phase 0 — Detect versions (mandatory stop)
Run in repo root (parallel OK):
```bash
python3 .cursor/skills/marqdo-release/scripts/detect_version.py
# or: rg / git tag / gh release list — see reference.md
```
Report briefly, then **ask only for the next SemVer** (defaults above). Wait for confirmation. Normalize to `VER=X.Y.Z` and `TAG=vX.Y.Z`.
Report briefly, then **ask for SemVer + mode** (unless already given). Normalize `VER` / `TAG`.
## Phase 1 — Preflight
Copy and track:
```
Release progress:
- [ ] Phase 0: version confirmed by user (TAG=…)
- [ ] Phase 0: version + mode confirmed
- [ ] Phase 1: preflight green
- [ ] Phase 2: docs + version bumps committed
- [ ] Phase 3: extension branch (if needed)
- [ ] Phase 3: extension branch (full/cli)
- [ ] Phase 4: main pushed; tag created & pushed
- [ ] Phase 5: CI / assets / release notes verified
- [ ] Phase 6: post-release checks
- [ ] Phase 5: CI / GitHub assets / notes
- [ ] Phase 6: R2 upload (if ext ships)
- [ ] Phase 7: Ubuntu PPA (full/cli)
- [ ] Phase 8: post-release checks
```
Checks:
1. `git status` clean or only release WIP you control.
2. `git checkout main && git pull --ff-only origin main`.
3. Quick gate: `cargo test --test gold structure_hello` (and any release-critical tests the user named). Full gold suite if time allows.
4. `CHANGELOG.md` has meaningful **Unreleased** notes; if empty, draft from `git log vLAST..HEAD --oneline` and confirm with user.
5. Confirm no secrets in the commit (`*.env`, credentials).
Checks: clean tree; `main` ff-only; smoke tests; CHANGELOG Unreleased; no secrets.
## Phase 2 — Docs & version bumps (main)
Bump **in lockstep**:
| File | Change |
|------|--------|
| `Cargo.toml` | `version = "VER"` |
| `crates/marqdo-wasm/Cargo.toml` | same `VER` |
| `CHANGELOG.md` | Move `## Unreleased` → `## vVER — YYYY-MM-DD`; leave fresh empty `## Unreleased` |
| `README.md` | 「现状 / 如何使用最新」version strings, checkout tag, release URL |
| `.cursor/skills/marqdo/SKILL.md` | Version-sensitive bullets if any (WASM/web status); keep rules accurate |
| `public/**` | User-facing tutorials if features shipped (welcome, features/*, extensions). Prefer small factual updates over rewrites |
| `doc/roadmap/*.md` | Mark shipped waves done if this release closes them |
| `.github/workflows/release.yml` | Update **Highlights** body template to this release (CI still uses hardcoded blurb—keep in sync) |
Public HTML: regenerate before packaging / pages deploy:
| File | full | cli | ext |
|------|------|-----|-----|
| `Cargo.toml` + `crates/marqdo-wasm/Cargo.toml` | bump | bump | — |
| `ext/VERSION` | bump | — | bump |
| `CHANGELOG.md` | `## vVER`(含**核心表面 Δ**,见 `doc/design/layers.md`) | same | `## Ext pack vVER` |
| `README.md` / `public/**` install + download table | update | update | update ext notes |
| `.cursor/skills/marqdo/SKILL.md` | if surface changed | same | rare |
| `.github/workflows/release.yml` Highlights stub | yes | yes | — |
```bash
./scripts/build-public.sh
# outputs under public/ (gitignored HTML); used by release zip / gh-pages
./scripts/build-public.sh # when public/ sources changed
```
Commit on `main` (HEREDOC message), e.g.:
```text
release: vVER — <one-line highlight>
EOF
```
Push `main`: `git push origin main` (with proxy/`all` perms if needed).
## Phase 3 — VS Code / Cursor extension
**Default: always** bump extension to `VER` on branch `vscode-extension` (skip only if user said so).
1. `git fetch origin vscode-extension`
2. Work on `vscode-extension` branch (not main):
- Bump `vscode-extension/package.json` `version` to `VER`.
- Update `engines` / CLI version hints in extension README if present.
- `npm ci && npm run compile`
3. Commit & `git push origin vscode-extension`.
4. Return to `main`. **Do not** add `vscode-extension/` to main.
## Phase 4 — Tag & trigger CI
Commit + push `main` (proxy origin). On push failure → reference § Proxy; if still blocked, **print** for the user:
```bash
git tag -a "TAG" -m "TAG"
git push origin "TAG"
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git HEAD:main
# or: python3 scripts/push-via-hk-jump.py
```
This runs `.github/workflows/release.yml` (Windows): CLI exe/zip, stdlib zip, ext zip, source zip, public zip, VSIX.
## Phase 3 — VS Code / Cursor extension (full/cli only)
If tag push fails: [reference.md § Proxy](reference.md), retry once; then report.
Default: bump `vscode-extension` package.json to `VER`, compile, push branch `vscode-extension`, return to `main`.
## Phase 5 — Release notes & assets
## Phase 4 — Tag & trigger CI (full/cli)
1. Wait for Actions success: `gh run list --workflow=Release --limit 3` / open the run URL.
2. Ensure GitHub Release for `TAG` exists with assets (workflow uses `softprops/action-gh-release`).
3. **Rewrite release body** (workflow body is a stub) with **中英双语** — see [reference.md § Notes template](reference.md). `gh release edit TAG --notes-file …`.
4. Include: Highlights, Breaking, Install (`ext add`, plugins build), Downloads table, WASM (`marqdo wasm build`), links to CHANGELOG/README, extension branch note.
5. Optional Linux local extras (not required if CI green): `marqdo wasm build` smoke; document in notes that wasm is built from source via CLI.
```bash
git tag -a "vVER" -m "vVER"
git push origin "vVER"
```
Local Windows fallback: `scripts/release-full.ps1 -Tag TAG -Upload` (see script header).
Ext-only:
## Phase 6 — Post-release
```bash
git tag -a "ext-vVER" -m "ext-vVER"
git push origin "ext-vVER"
```
1. `gh release view TAG` — confirm assets + notes.
2. `git status` clean; `main` synced.
3. Tell user: release URL `https://github.com/cflmy/marqdo/releases/tag/TAG`.
4. Optional: `./scripts/deploy-public.ps1` / pages workflow if user wants user-site refresh.
5. Open fresh `## Unreleased` already done in Phase 2.
(or build zips locally / via workflow and `gh release upload`).
If tag push needs the user:
```bash
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git vVER
```
## Phase 5 — GitHub Release notes & assets
1. Wait for Actions (full/cli): both `windows` and `linux` green when ext natives required.
2. Rewrite release body 中英双语 — [reference.md § Notes](reference.md).
3. Confirm Linux `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` when mode ships ext.
## Phase 6 — Extension CDN (R2) — required when ext ships
```bash
# credentials: ~/.marqdo/r2.env (never commit)
python3 scripts/upload-ext-r2.py --version VER --from-dir dist/
curl -fsS https://ext.marqdo.com/latest/VERSION
```
Also ensure the **same** zips are on GitHub (`vVER` or `ext-vVER`). If R2 credentials missing, **tell the user**:
```bash
# put keys in ~/.marqdo/r2.env then:
python3 scripts/upload-ext-r2.py --version VER --from-dir dist/
```
## Phase 7 — Ubuntu PPA (full/cli)
Linux CLI for apt users. After `Cargo.toml` is at `VER` and `debian/changelog` has a matching `VER-1ppaN` stanza:
```bash
./scripts/ppa-ship.sh noble
```
Packaging notes / noble Cargo.lock v4: [ubuntu-ppa.md](../../../doc/design/ubuntu-ppa.md).
**If the agent cannot sudo / sign / dput**, print exactly:
```bash
cd ~/work/marqdo
./scripts/ppa-ship.sh noble
# or build then upload:
./scripts/ppa-build-source.sh noble
dput ppa:cflmy/marqdo ../build-area/marqdo_*~noble_source.changes
```
Watch: https://launchpad.net/~cflmy/+archive/ubuntu/marqdo/+builds
On Launchpad failure: read the build log, fix `debian/` or bundle script, bump `1ppaN`, re-upload. Tell the user the new `dput` command.
## Phase 8 — Post-release
1. `gh release view TAG` — assets + notes.
2. CDN `https://ext.marqdo.com/vVER/` (if ext shipped).
3. PPA build green (if cli shipped).
4. Tell user URLs: GitHub release, CDN, PPA install one-liner.
5. Optional gh-pages only if asked.
## Extension-only release (mode=ext)
1. User confirms **ext** SemVer (may differ from CLI).
2. Bump `ext/VERSION`; CHANGELOG → `## Ext pack vVER`.
3. Build/package `marqdo-VER-ext.zip` + `marqdo-VER-native-*.zip` (CI or local).
4. Upload to **R2 and GitHub** (required both).
5. Do **not** retag CLI / do **not** PPA unless user also asked for cli.
## Failure matrix (short)
| Failure | Action |
|---------|--------|
| `gh` / git TLS or proxy `7890` refused | Unset bad proxy; use working `HTTP(S)_PROXY` or `required_permissions: ["all"]`; see reference |
| Tag exists | Stop; ask user to bump or delete tag (no force on shared tags without explicit order) |
| CI red | Fix on main, move tag only if user explicitly allows delete+re-push tag |
| VSIX missing | Fetch `vscode-extension`, build locally, `gh release upload TAG dist/*.vsix` |
| Partial assets | Re-run workflow or upload missing files only |
| `gh` / git TLS or Clash `7890` refused | Unset bad proxy; see [reference § Proxy](reference.md) |
| GitHub blocked | proxy.cflmy.top, then HK jump; **print commands** if agent cannot push |
| Tag exists | Stop; ask user |
| CI red | Fix on main; retag only if user allows |
| R2 upload fails | Print `upload-ext-r2.py` command; do not skip silently |
| PPA / sudo / GPG | Print `./scripts/ppa-ship.sh noble` (or `dput …`); do not skip silently |
| Launchpad `Cargo.lock` v4 / old cargo | Ensure bundled `third_party/rust` via current `ppa-build-source.sh`; bump `1ppaN` |
| Linux native zip missing (full/ext) | Incomplete — fix linux job or upload |
## Do not
- Ship without user-confirmed version.
- Hardcode release highlights only in Actions YAML and forget CHANGELOG.
- Commit `target/`, `dist/`, `*.wasm`, or `public/**/*.html` unless project policy changes.
- Ship without user-confirmed version (and mode when ambiguous).
- Ship ext packs to only one of R2 / GitHub.
- Call a full/cli release done without attempting PPA **or** giving the user the PPA commands.
- Commit `target/`, `dist/`, `*.wasm`, `third_party/rust/`, or `public/**/*.html` unless policy changes.
- Merge extension tree into `main`.
+108 -18
View File
@@ -25,21 +25,24 @@ gh release list --limit 3 2>/dev/null || true
## Asset matrix (CI tag `v*`)
Produced by `.github/workflows/release.yml` on **windows-latest**:
Produced by `.github/workflows/release.yml` on **windows-latest** (`windows` job) and **ubuntu-latest** (`linux` job, **required**, `needs: windows`):
| Asset | Role |
|-------|------|
| `marqdo-VER-x86_64-pc-windows-msvc.exe` | CLI (stdlib embedded) |
| `marqdo-VER-x86_64-pc-windows-msvc.zip` | `marqdo.exe` + `lib/` |
| `marqdo-VER-stdlib.zip` | `lib/` only |
| `marqdo-VER-ext.zip` | Official `ext/` L1 |
| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Prebuilt Windows plugins (`native/*.dll`) |
| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Prebuilt Linux plugins (`native/lib*.so`) |
| `marqdo-VER-source.zip` | `git archive` of tagged commit |
| `marqdo-VER.vsix` | VS Code / Cursor (from branch `vscode-extension`) |
| `marqdo-VER-public.zip` | Static user docs (`marqdo view output public`) |
| Asset | Role | Job |
|-------|------|-----|
| `marqdo-VER-x86_64-pc-windows-msvc.exe` | CLI (stdlib embedded) | windows |
| `marqdo-VER-x86_64-pc-windows-msvc.zip` | `marqdo.exe` + `lib/` + `ext/` + native DLL | windows |
| `marqdo-VER-stdlib.zip` | `lib/` only | windows |
| `marqdo-VER-ext.zip` | Official `ext/` L1 | windows |
| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Prebuilt Windows plugins (`native/*.dll`) | windows |
| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Prebuilt Linux plugins (`native/lib*.so`) — **must ship** | linux |
| `marqdo-VER-x86_64-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + native `.so` — **must ship** | linux |
| `marqdo-VER-source.zip` | `git archive` of tagged commit | windows |
| `marqdo-VER.vsix` | VS Code / Cursor (from branch `vscode-extension`) | windows |
| `marqdo-VER-public.zip` | Static user docs (`marqdo view output public`) | windows |
Not CI-uploaded (document in notes): Linux/macOS build from source; WASM via `marqdo wasm build` → `dist/wasm/`.
Not CI-uploaded (document in notes): macOS build from source; WASM via `marqdo wasm build` → `dist/wasm/`.
A release **without** the Linux native zip is incomplete (`marqdo ext add` on Linux cannot download prebuilts).
## Doc sync checklist (Phase 2 detail)
@@ -189,7 +192,9 @@ marqdo wasm build
| Asset | 内容 / Contents |
|-------|-----------------|
| `marqdo-*-windows-msvc.exe` | CLI(内置 stdlib) |
| `marqdo-*-windows-msvc.zip` | exe + `lib/` |
| `marqdo-*-windows-msvc.zip` | exe + `lib/` + `ext/`(含 native) |
| `marqdo-*-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + `.so` |
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`(Win + **Linux 必出**) |
| `marqdo-*-stdlib.zip` | 仅 `lib/` |
| `marqdo-*-ext.zip` | 官方 `ext/` |
| `marqdo-*-source.zip` | 源码快照 |
@@ -206,14 +211,59 @@ marqdo wasm build
## Proxy & auth (network recovery)
Symptoms seen in this project: broken local proxy on `127.0.0.1:7890`, TLS failures, `gh` needing token, Cursor sandbox blocking git/gh.
Symptoms seen in this project: broken local Clash on `127.0.0.1:7890`, flaky GitHub TLS, `gh` needing token, Cursor agent sandbox with only `lo`.
### `proxy.cflmy.top` (try this first)
This machine’s `origin` is typically:
```
https://proxy.cflmy.top/github.com/cflmy/marqdo.git
```
Push / fetch / tag through that remote (HTTPS reverse proxy to GitHub):
```bash
git remote -v # confirm origin uses proxy.cflmy.top
git push origin main
git push origin vVER
git push origin vscode-extension
# one-shot if origin still points at github.com:
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git HEAD:main
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git vVER
```
Short GETs via the proxy often work; **long `git push` may still time out**. If push hangs or drops, skip Clash retries and go to **HK SSH jump** below.
`gh` / Release API can use the same path reverse-proxy:
| Path prefix | Upstream |
|-------------|----------|
| `/github.com/` | `https://github.com/` |
| `/api.github.com/` | `https://api.github.com/` |
| `/uploads.github.com/` | `https://uploads.github.com/` (Release asset POST; OpenResty on HK) |
```bash
# Upload a Release asset through proxy.cflmy.top (Content-Type: application/octet-stream)
curl -X POST \
-H "Authorization: Bearer $GH_TOKEN" \
-H "Accept: application/vnd.github+json" \
-H "Content-Type: application/octet-stream" \
--data-binary @dist/FILE.zip \
"https://proxy.cflmy.top/uploads.github.com/repos/cflmy/marqdo/releases/RELEASE_ID/assets?name=FILE.zip"
```
Do **not** rewrite `Host: uploads.github.com` against `proxy.cflmy.top` without the `/uploads.github.com/` path prefix — that returns 404.
### Diagnose
```bash
env | grep -iE 'proxy|PROXY' || true
curl -sI https://github.com | head -5
curl -sI --max-time 15 https://github.com | head -5
curl -sS --max-time 15 -o /dev/null -w 'proxy=%{http_code}\n' https://proxy.cflmy.top/ || true
gh auth status
ip -br addr | head -5 # agent may lack enp*; use required_permissions: ["all"]
```
### Fix order
@@ -222,6 +272,7 @@ gh auth status
```bash
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy
# also clear for one git call: git -c http.proxy= -c https.proxy= …
```
2. **Set a working proxy** only if the user provides one (or known working):
@@ -237,13 +288,15 @@ export HTTP_PROXY=http://HOST:PORT
5. **Git remote**: prefer `https://github.com/cflmy/marqdo.git`; SSH needs keys.
6. **Partial upload**:
6. **HK SSH jump (preferred when GitHub is blocked but HK is reachable)** — see next subsection.
7. **Partial upload**:
```bash
gh release upload "vVER" dist/FILE --clobber
```
7. **Re-run CI** without retagging (if tag already correct):
8. **Re-run CI** without retagging (if tag already correct):
```bash
gh workflow run Release --ref "vVER" # only if workflow_dispatch exists; else fix + new patch tag
@@ -251,6 +304,43 @@ gh workflow run Release --ref "vVER" # only if workflow_dispatch exists; else f
Current Release workflow is **tag-push only**. Red CI after tag → fix on `main`, then either new patch tag or **user-approved** delete+recreate tag (dangerous; prefer patch).
### HK SSH jump (Paramiko CONNECT)
**When to use:** local → GitHub fails (timeout / TLS / Clash flaky / reverse-proxy `proxy.cflmy.top` connect drops), but this host can reach an overseas box that has stable GitHub (default `hk.cflmy.de`). Proven path for v0.3.9 push/tag/`gh`.
**Do not** rely on OpenSSH + `sshpass` here — password auth has hung; use **Paramiko** (`python3-paramiko`).
**Never** commit the HK root password or tokens. Ask the user for the password (or a key), put it in env / a `600` temp file, scrub after.
```bash
# one-shot password file (example — use the secret the user gave this session)
printf '%s' "$HK_PASSWORD_FROM_USER" > /tmp/.hk_ssh_pw && chmod 600 /tmp/.hk_ssh_pw
export HK_SSH_HOST=hk.cflmy.de # or 83.229.126.119
export HK_SSH_USER=root
export HK_SSH_PASSWORD_FILE=/tmp/.hk_ssh_pw
# optional: HK_JUMP_PORT=18081
SCRIPT=.cursor/skills/marqdo-release/scripts/push-via-hk-jump.py
# push / tag / extension (git gets CONNECT proxy + github.com askpass)
python3 "$SCRIPT" -- git push origin main
python3 "$SCRIPT" -- git push origin vscode-extension
python3 "$SCRIPT" -- git push origin vVER
# gh (sets GH_TOKEN from git credential fill if unset)
python3 "$SCRIPT" -- gh release edit vVER --notes-file /tmp/notes.md
python3 "$SCRIPT" -- gh run list --workflow=Release --limit 3
# leave proxy up for manual commands
python3 "$SCRIPT" --serve # then: export https_proxy=http://127.0.0.1:18081
rm -f /tmp/.hk_ssh_pw
```
Script behavior: SSH to HK → local `http://127.0.0.1:$HK_JUMP_PORT` HTTP CONNECT via `direct-tcpip` → run `git`/`gh`/`curl` with that proxy. Git auth uses local `git credential` via `http.extraHeader` (Basic) — **not** `GIT_ASKPASS` (askpass has hung under agent/no TTY). Tokens never go to the jump host disk.
Optional path reverse-proxy (`https://proxy.cflmy.top/github.com/…` `insteadOf`) may work for short GETs; treat long `git push` failures as a signal to use the HK jump instead of retrying Clash forever.
## Local Windows fallback
```powershell
+284
View File
@@ -0,0 +1,284 @@
#!/usr/bin/env python3
"""Push / run git|gh through an HK SSH jump host (Paramiko HTTP CONNECT).
When this machine cannot reach GitHub reliably but can SSH to a host that can
(e.g. hk.cflmy.de), open a local HTTP CONNECT proxy over Paramiko and run the
remaining command with http(s).proxy pointed at it.
Why Paramiko: OpenSSH/`sshpass` has hung on password auth in this environment;
Paramiko password + direct-tcpip works.
Credentials (never commit):
HK_SSH_PASSWORD password string
HK_SSH_PASSWORD_FILE file containing password (mode 600 recommended)
or SSH key via Paramiko agent/keys if password unset and key works
Optional env:
HK_SSH_HOST default hk.cflmy.de
HK_SSH_USER default root
HK_JUMP_PORT default 18081 (local CONNECT listen)
Usage:
HK_SSH_PASSWORD_FILE=/tmp/hk.pw \\
python3 .cursor/skills/marqdo-release/scripts/push-via-hk-jump.py -- \\
git push origin main
# keep proxy only (Ctrl+C to stop)
... push-via-hk-jump.py --serve
# wrap gh
... push-via-hk-jump.py -- gh release view v0.3.9
"""
from __future__ import annotations
import os
import select
import socket
import socketserver
import subprocess
import sys
import threading
import time
from pathlib import Path
try:
import paramiko
except ImportError as e: # pragma: no cover
raise SystemExit(
"paramiko required: apt install python3-paramiko (or pip install paramiko)"
) from e
ROOT = Path(__file__).resolve().parents[4]
class _Server(socketserver.ThreadingMixIn, socketserver.TCPServer):
allow_reuse_address = True
daemon_threads = True
def load_password() -> str | None:
path = os.environ.get("HK_SSH_PASSWORD_FILE")
if path:
return Path(path).read_text(encoding="utf-8").strip()
pw = os.environ.get("HK_SSH_PASSWORD")
return pw.strip() if pw else None
def connect_hk() -> paramiko.SSHClient:
host = os.environ.get("HK_SSH_HOST", "hk.cflmy.de")
user = os.environ.get("HK_SSH_USER", "root")
pw = load_password()
client = paramiko.SSHClient()
client.set_missing_host_key_policy(paramiko.AutoAddPolicy())
kwargs: dict = {
"hostname": host,
"username": user,
"timeout": 20,
"auth_timeout": 25,
"banner_timeout": 25,
}
if pw:
kwargs.update(password=pw, allow_agent=False, look_for_keys=False)
else:
kwargs.update(allow_agent=True, look_for_keys=True)
print(f"== HK jump {user}@{host} ==", flush=True)
client.connect(**kwargs)
_, stdout, stderr = client.exec_command(
"hostname; curl -sS --max-time 20 -o /dev/null -w gh=%{http_code} https://github.com/; echo"
)
out = stdout.read().decode()
err = stderr.read().decode()
print(out, end="" if out.endswith("\n") else "\n", flush=True)
if err.strip():
print(err, file=sys.stderr, flush=True)
return client
def make_proxy(transport: paramiko.Transport, port: int) -> _Server:
class Handler(socketserver.StreamRequestHandler):
def handle(self) -> None:
try:
first = self.rfile.readline(65536)
if not first:
return
parts = first.decode("latin1", "replace").split()
if len(parts) < 2 or parts[0].upper() != "CONNECT":
self.wfile.write(b"HTTP/1.1 405 Method Not Allowed\r\n\r\n")
return
while True:
line = self.rfile.readline(65536)
if line in (b"\r\n", b"\n", b""):
break
host, _, port_s = parts[1].partition(":")
chan = transport.open_channel(
"direct-tcpip",
(host, int(port_s or "443")),
self.connection.getpeername(),
)
self.wfile.write(b"HTTP/1.1 200 Connection Established\r\n\r\n")
sock = self.connection
sock.setblocking(False)
chan.setblocking(False)
try:
while True:
r, _, x = select.select([sock, chan], [], [sock, chan], 120)
if x:
break
if sock in r:
data = sock.recv(65536)
if not data:
break
chan.sendall(data)
if chan in r:
data = chan.recv(65536)
if not data:
break
sock.sendall(data)
finally:
try:
chan.close()
except Exception:
pass
except Exception:
pass
return _Server(("127.0.0.1", port), Handler)
def github_basic_auth_header() -> str:
"""Authorization: Basic … from local git credential store (no askpass; askpass can hang)."""
import base64
out = subprocess.check_output(
["git", "credential", "fill"],
input=b"protocol=https\nhost=github.com\n\n",
).decode()
data = dict(line.split("=", 1) for line in out.splitlines() if "=" in line)
user = data.get("username") or "x-access-token"
password = data.get("password") or ""
if not password:
raise SystemExit("no github.com credential in git credential store")
token = base64.b64encode(f"{user}:{password}".encode()).decode()
return f"Authorization: Basic {token}"
def github_token() -> str | None:
out = subprocess.check_output(
["git", "credential", "fill"],
input=b"protocol=https\nhost=github.com\n\n",
).decode()
data = dict(line.split("=", 1) for line in out.splitlines() if "=" in line)
return data.get("password") or None
def run_with_proxy(proxy: str, argv: list[str]) -> int:
env = os.environ.copy()
for k in (
"http_proxy",
"https_proxy",
"HTTP_PROXY",
"HTTPS_PROXY",
"ALL_PROXY",
"all_proxy",
):
env.pop(k, None)
cmd = list(argv)
if cmd and cmd[0] == "git":
# Prefer http.extraHeader over GIT_ASKPASS (askpass has hung under agent/no TTY).
# Do not also set env http_proxy for git — only -c (avoids double-proxy quirks).
auth = github_basic_auth_header()
cmd = [
"git",
"-c",
f"http.proxy={proxy}",
"-c",
f"https.proxy={proxy}",
"-c",
"credential.helper=",
"-c",
f"http.extraHeader={auth}",
"-c",
"http.version=HTTP/1.1",
"-c",
"http.postBuffer=524288000",
*cmd[1:],
]
print(
"+",
" ".join(
c if not str(c).startswith("http.extraHeader=") else "http.extraHeader=<redacted>"
for c in cmd
),
flush=True,
)
return subprocess.call(cmd, cwd=ROOT, env=env)
env["http_proxy"] = proxy
env["https_proxy"] = proxy
env["HTTP_PROXY"] = proxy
env["HTTPS_PROXY"] = proxy
if cmd and cmd[0] == "gh" and not env.get("GH_TOKEN"):
tok = github_token()
if tok:
env["GH_TOKEN"] = tok
print("+", " ".join(cmd), flush=True)
return subprocess.call(cmd, cwd=ROOT, env=env)
def main(argv: list[str]) -> int:
args = argv[1:]
if not args or args[0] in ("-h", "--help"):
print(__doc__)
return 0 if args else 1
serve_only = args == ["--serve"]
if args[0] == "--":
args = args[1:]
if not serve_only and not args:
print("missing command after --", file=sys.stderr)
return 2
port = int(os.environ.get("HK_JUMP_PORT", "18081"))
client = connect_hk()
transport = client.get_transport()
assert transport is not None
server = make_proxy(transport, port)
threading.Thread(target=server.serve_forever, daemon=True).start()
proxy = f"http://127.0.0.1:{port}"
print(f"== CONNECT proxy {proxy} ==", flush=True)
# smoke
subprocess.call(
[
"curl",
"-sS",
"--connect-timeout",
"10",
"--max-time",
"25",
"--proxy",
proxy,
"-o",
"/dev/null",
"-w",
"github=%{http_code}\\n",
"https://github.com/",
]
)
try:
if serve_only:
print("serving; Ctrl+C to stop", flush=True)
while transport.is_active():
time.sleep(5)
return 1
return run_with_proxy(proxy, args)
finally:
server.shutdown()
client.close()
if __name__ == "__main__":
raise SystemExit(main(sys.argv))
+134 -59
View File
@@ -15,28 +15,84 @@ description: >-
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
Canonical design (repo): [`markdown-mapping-v0.3.md`](../../doc/design/markdown-mapping-v0.3.md) (**v0.3 · runtime**), `doc/design/keywords.md`. Legacy v0.2 notes: `doc/design/markdown-mapping.md` (historical). Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number.
**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.
## Hard rules (do not violate)
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are **variables** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division.
8. Prefer ending side-effect-only function bodies with a lone `---` or `***` line (or `****` empty return) so later siblings are not swallowed.
2. **`**…**` = code** (assign / call). **`*…*` = return value**. Output is **not** either marker — use `> print text=…` / `**print text="…"**` / `> 打印 内容=…`.
3. **Prose:** unmarked narrative may contain `` `名` `` (declare/ref), inline `**code**`, and `*return*`. Soft Markdown emphasis that is **not** code-shaped (`**说明**`, mid-line `*only*`) is ignored — see [code-as-docs-gaps.md](../../doc/design/code-as-docs-gaps.md). Dead `` `名` `` (never read) is OK and does not become a param.
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**. Params: prefer prose `` `名` `` / `` `名`=默认 `` (inferred); `` + `名` `` still accepted.
5. **Identifiers:** `` `名` `` in prose; inside `*…*` / `**…**`, bare ids are **variables**. **Text literals must be quoted** in bold/italic: `**print text="hi"**`. Standalone `>` calls: bare words = text; vars need ticks: `` > str `n` ``.
6. **Structure lines** (`#` `>` `+` `-` `|` `1.`) need not be wrapped in bold.
7. **Paths:** In bare expressions `/` is division. In call args / defaults / table cells, unspaced `a/b` and quoted paths are text.
8. Prefer ending side-effect-only bodies with `*None*` / `*无*` / whole-line `**` / `****` when the next lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped everywhere), not function end.
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug.
12. **Bracket-marked calls:** Function name may be marked with `[函数名]`; bare words before `[` are boolean modifiers (`礼貌 [问候] x` → `礼貌=True`). `]` immediately followed by `(` is **index** `[key](coll)`, not a call. Prefer `[k](c)` over footnote index in new code. See [bracket-call-modifiers.md](../../doc/design/bracket-call-modifiers.md).
## 记不住语法细节?查 MLSP(AI 必读)
## Markup → meaning (v0.2)
**不必背 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)
| Marker | Meaning |
|--------|---------|
@@ -47,15 +103,17 @@ Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
| Line `N. *` | Else arm |
| `> fn args` | Call (named `k=v` or positional) |
| `修饰 [fn] args` | Bracket-marked call; leading words → `名=True` |
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
| `****` or `**` + spaces + `**` | Return `None` and end function body |
| Lone `---` / `***` in function body | End function body (no value) |
| GFM table after empty RHS bind | Collection (1-col list / ≥2-col map / `@`·`行`·`row` → list of maps); `` `x`[^1] `` / `` `m`[^key] `` |
| `**…**` | **Code** (assign / call) — closing `**` touches last token; bare ids are variables; quote text literals |
| `*…*` | **Return value** — closing `*` touches last token; bare ids are variables |
| `****` / whole-line `**` / `*None*` | Return `None` and end function body |
| Lone `---` / `***` | Markdown thematic break (skip; not function end) |
| GFM table after empty RHS bind | Collection; get with `[key](coll)` (preferred) or legacy `` `m`[^key] `` |
| `- [item](coll)` | Foreach (unchanged) |
| `` ```lang `` | Foreign code block (via `lib/foreign`) |
| `` `"text"` `` | Quoted string (`\n` `\t` `\\` `\"`; `` `var` `` inside); bare tokens unescaped |
| Unmarked prose | Comment |
@@ -90,27 +148,28 @@ Chinese builtins (same functions, no import):
> print text=Hello, `who`!
---
*None*
```
- Call: `> name key=value` or `> name value`.
- Nested helpers use deeper `#` (`##`, `###`, …).
- After a helper with only side effects, end with `---` / `***`.
- After a helper with only side effects, end with `*None*` / whole-line `**` / `****` when later lines must stay in the outer function. Lone `---` is only a thematic break (skipped).
- In bold assigns, prefer bare calls: `**摘要 = 结账摘要 …**` (omit `>`).
## Statements, returns, branches
```markdown
*x = 1*
*y = x + 2*
**x = 1**
**y = x + 2**
## add_one
+ `n`
**n + 1**
*n + 1*
```
```markdown
*n = 0*
**n = 0**
1. `n` > 0
> print text=positive
@@ -133,16 +192,16 @@ import clock:lib/time.mq.md
# main
*xs = > text.split value="a,b,c" sep=","*
**xs = > text.str_split s="a,b,c" sep=","**
> print text=`xs`
*t = > clock.now_unix*
**t = > clock.now_unix**
```
- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages).
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum|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|linalg` (see `doc/design/ext-cli.md`). **`ext/llm`** — intelligence primitive (`ask` / `stream` / `collect`; `complete` is compat); **`ext/agent`** — document-driven agents (see **ext/agent** below); **`ext/web`** — dynamic sites (see below); **`ext/quantum`** — circuits + Q7/Q8 (see below); **`ext/linalg`** — formula-first linear algebra (see below).
- Native plugins: `lib/plugin` — `## load` / `unload` / `list`. C ABI: `include/marqdo_abi.h`.
- Prefer `table.put` / `表.改` for list/map element updates; keep `json` for parse/stringify/quote (see `doc/design/stdlib-table.md`).
- Builtins (no import): `print`/`打印`, `input`/`输入`, `len`/`长度`, `str`/`文本`, `int`/`整数`; literals `True`/`真`, `False`/`假`, `None`/`空`; logic `and`/`且`, `or`/`或`, `not`/`非`.
@@ -158,49 +217,60 @@ Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --releas
1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag.
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only.
4. **Skill Compilation (v2)** — successful runs become `.mq.md` episodes; after enough evidence, `maybe_learn` compiles an executable skill (`llm_free`). Prefer `## run` over bare `## plan` when you want learning.
5. **Adaptive Routing (P4)** — router is abstract (`marqdo` / `small-llm` / `llm` / `auto`); `jev` is a compat alias of `small-llm`. Decision via `router_model` (any llm handle). Policy Compilation writes `policies/router.mq.md`.
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` / `# 智能体` → `## run` / `## route` / `## step` / `## plan` (+ `resolve` / `record_episode` / `maybe_learn` / `compile` / `compile_policy` / `metrics`). Context: standing + task + **call site** + tools + budgeted source/skill + act protocol (`CALL:` / `READ:`). Inspect without LLM: `dump_step_context`. Inside `writeback=` / `写回=` branches use `host_writeback_record` (param name shadows the writeback import).
Examples: [agent-pong](../../examples/agent-pong/) · [agent-okf-flywheel](../../examples/agent-okf-flywheel/). Harness: `scripts/agent-harness.sh`. Design: [ext-agent.md](../../doc/design/ext-agent.md) · Wave B: [agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
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) · v2: [doc/next/003.md](../../doc/next/003.md) · P4: [doc/next/004.md](../../doc/next/004.md). Dev LLM: copy [.env.example](../../.env.example) → `.env` (gitignored).
## Official extension: `ext/web` (dynamic sites)
## Official extension: `ext/web` (Document / Endpoint / Resource)
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin first: `cargo build --release -p marqdo_plugin_web`.
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin: `scripts/build-web-plugin.sh` / `marqdo ext add web`.
Import **one language file** — never mix EN/ZH API names in the same `.mq.md`:
**Constitution (ADR 0007 — do not degrade):**
- EN: `import web:ext/web/web.mq.md`
1. **Document / Endpoint / Resource** — `.mq.md` with `type: web|endpoint` (ZH `类型: 网页|端点`) is the site surface; not a Flask-style class pile.
2. **Code is documentation** — the file is docs + route + handler.
3. **Table = data** — View schema only `|type|slot|value|attrs|style|`. No `compose_*` dialects, no `json.set` glue.
4. **Facade only** — `web.page` · `web.route` · `web.serve` · `web.render` · `web.inspect`. DB → `ext/data`; auth → `ext/security`; ws/http → `ext/net`.
5. **No author `ensure_plugin` / `host_*`**; import web = capability (plugin auto-load).
6. **Declared vs system routes**; `web.inspect` lists both. No silent user routes.
Import **one language** per file:
- EN: `import web:ext/web/web.mq.md` (+ `import data:ext/data/db.mq.md` as needed)
- ZH: `导入 网页:ext/web/网页.mq.md`
**Hard rules (web):**
```markdown
---
type: web
route: /
title: Hello
import web:ext/web/web.mq.md
---
- Authors use **GFM tables + `#` classes** — no `json.parse` / `json.set` glue, no hand-built part JSON.
- Table cells stay **literal strings**; path text like `` `posts`.`title` `` is resolved by web classes.
- **Quote path/MIME cells** that contain `/` (T5 cell expressions treat bare `/` as division): `"/static/logo.svg"`, `"image/png"`.
- **`ext/**` never calls `host_*`** — hot path is native `plugins/web` ABI.
- HTTPS: terminate at reverse proxy; set `cookie_secure=True` on auth (no in-process TLS).
# Hello
**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)
Executable document as a page.
```
**Core objects (EN / ZH):** `# page`/`页面`, `# style`/`样式`, `# db`/`数据库`, `# form`/`表单`, `# app`/`应用`, `# auth`/`鉴权`, `# cache`/`缓存`, `# storage`/`存储`.
```markdown
---
type: endpoint
method: POST
path: /api/ping
response: json
---
**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/)).
*{"ok": true}*
```
**Shipped surface (W0–W7 + P3 + W8 + route D mount):** middleware + JSON API (`app.configure`); transactions, pagination, FTS search (`db.migrate`, `db.fts`, `db.search`); security (argon2, CSRF, SQLite sessions, login rate limit); SEO / RSS / Markdown (`page.meta`, `route_rss`, `lib/net.markdown_parse`); upload / download / gallery; sitemap / robots / error pages / redirects; RBAC (`app.gate`, user `role`); audit timestamps + FK in `db.init`; ETag on downloads; **W8** site icons (`app.icons` → `/favicon.ico`), head resource tables (`page.head`), image assembly (`make_images` / `page.images`); **D** `client_embed` auto-mount + DOM effect helpers (`text_patch` / `dom_patch`).
Site entry may `# main` → `web.serve root="."`. Client WASM: `ext/web/client.mq.md` / `lib/browser` — no author JS.
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/).
Design: [ext-web-artifact.md](../../doc/design/ext-web-artifact.md) · ADR [0007](../../doc/adr/0007-web-document-endpoint.md) · rule: `.cursor/rules/web-artifact-no-degrade.mdc` · example: [examples/marqdo-blog/](../../examples/marqdo-blog/).
Web patterns: [examples.md](examples.md) §13 · API index: [reference.md](reference.md).
Web patterns: [examples.md](examples.md) · API index: [reference.md](reference.md).
## Official extension: `ext/quantum` (circuits + Q7/Q8)
@@ -241,11 +311,14 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
## AI authoring workflow
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
2. Write `.mq.md` with `# main`, blank lines around prose, correct markers.
3. Run: `marqdo run path/to/file.mq.md` (cwd = project root so `lib/` resolves).
4. On `path:line:col: message`, fix that span; re-run until exit 0.
5. Optional: `marqdo view .` / `marqdo debug .` for structure and breakpoints.
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.
## Anti-patterns (common model mistakes)
@@ -257,11 +330,11 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
| `* > print text=hi *` | `> print text=hi` |
| `` *`a` = 1 * `` (trailing space + backticks) | `*a = 1*` — bare bind, no trailing space before `*` / `**` |
| `*xs = > text.split value=a,b sep=,*` (bare text args) | `*xs = > text.split value="a,b" sep=","*` — quote text literals; bare words are variables |
| Forgetting `---` after nested `##` helper | Add `---` / `***` / `****` |
| Forgetting empty return after nested `##` helper when outer continues | Add `*None*` / `**` / `****` (not `---`) |
| Import `lib/text` then call bare `split` | `> text.split …` (qualified) |
| Import `lib/text` then call `拆分` | Match file language (`text.split`, not 文本) |
| `json.set` / `json.append` to build maps or lists | GFM tables; sparse `table.put`; named helpers (`browser.*`, `web.*`) |
| `json.set` to build page parts | GFM tables + `page.compose_*` / `web.page` methods |
| `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 |
@@ -277,10 +350,12 @@ Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../
- [ ] Print via `print` / `打印`, not bold
- [ ] Blank lines separate comment paragraphs from code
- [ ] `# main` exists when the file is an entry program
- [ ] Nested functions ended with `---` / `***` / `****` when needed
- [ ] Nested side-effect helpers ended with `*None*` / `**` / `****` when the outer function continues
- [ ] Imports and call names share the same language file
- [ ] Data shaped as **GFM tables** (or short helpers) — no `json.set` / `json.append` glue
- [ ] Web sites: tables + web classes only (no JSON glue); `data/` gitignored
- [ ] Browser client: `lib/browser` + tables when returning effects
- [ ] Quantum draw: quote `kind=` / `theme=`; rebuild plugin → `ext add quantum` before view
- [ ] `marqdo run` succeeds (or errors addressed)
- [ ] 语法拿不准的地方已查 MLSP(`syntax`/`locate`),而不是凭记忆发明
- [ ] 契约(如有)与升参一致:`marqdo check` 零 Error
+94 -64
View File
@@ -1,5 +1,7 @@
# Marqdo examples (AI)
v0.3: `**…**` = code (assign / call); `*…*` = return. Prefer `[key](coll)` over footnote get. Bracket calls: `礼貌 [问候] x`.
## 1. Hello (English)
```markdown
@@ -16,7 +18,7 @@
> 打印 内容=你好,世界!
```
## 3. Function + named call + body end
## 3. Function + named call + empty return
```markdown
# main
@@ -30,22 +32,24 @@ Greeting via a nested function:
> print text=Hello, `who`!
---
*None*
```
Or end with a whole-line empty bold return: `**` / `****`. Lone `---` is a thematic break (skipped), not function end.
## 4. Bindings and return
```markdown
# main
*a = 2*
*b = > add_one n=`a`*
> print text=`b`
**a = 2**
**b = add_one n=`a`**
**打印 内容=`b`**
## add_one
+ `n`
**n + 1**
*n + 1*
```
## 5. Branch with else
@@ -53,7 +57,7 @@ Greeting via a nested function:
```markdown
# main
*n = 0*
**n = 0**
1. `n` > 0
> print text=positive
@@ -78,8 +82,7 @@ Greeting via a nested function:
> print text=`果`
```
## 6b. Map table + footnote get
## 6b. Map table + link-index get
```markdown
# main
@@ -90,13 +93,20 @@ Greeting via a nested function:
|------|------|
| 水果 | 蔬菜 |
*种 = 分类[^苹果]*
> print text=`种`
**种 = [苹果](分类)**
**打印 内容=`种`**
*第一 = 篮子[^1]*
`篮子` =
| 果 |
|----|
| 苹果 |
**第一 = [1](篮子)**
**打印 内容=`第一`**
```
One column → list; ≥2 columns + one data row → map; ≥2 columns + many rows → map of lists. Data cells are expressions (same as call-arg values): bare words, numbers, `` `var` ``, quoted strings; URLs and `gpt-4o-mini` stay text via path/hyphen folding. Footnotes: lists use 1-based digit indices; maps use key text (including digit keys like `[^00]`). Foreach on a map walks **keys**.
One column → list; ≥2 columns + one data row → map; ≥2 columns + many rows → map of lists. Prefer `[key](coll)` (lists are 1-based). Legacy `` coll[^key] `` still parses. Foreach on a map walks **keys**.
Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of maps (marker column excluded):
@@ -107,10 +117,27 @@ Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of ma
|----|------|------|
| 1 | 苹果 | 2 |
*名 = 订单[^1][^品名]*
**名 = [品名]([1](订单))**
```
## 6c. Browser effects — tables + lib/browser (not json.set)
## 6c. Bracket-marked call + modifiers
```markdown
# main
**打印 内容=(礼貌 [问候] "Marqdo")**
## 问候
+ `谁`
+ `礼貌`=False
**出 = `礼貌` + ", " + `谁` + "!"**
*出*
```
`礼貌 [问候] …` → `礼貌=True`. `]` immediately followed by `(` is index, not a call.
## 6d. Browser effects — tables + lib/browser (not json.set)
```markdown
---
@@ -128,8 +155,8 @@ import browser:lib/browser.mq.md
**`wire`**
## bump
*`count` = count + 1*
*`label` = > str count*
**count = count + 1**
**label = str count**
**> browser.set_text sel="#count" text=label**
```
@@ -145,8 +172,8 @@ import text:lib/text.mq.md
# main
*parts = > split value=a,b,c sep=,*
> print text=`parts`
**parts = [text.str_split] s="a,b,c" sep=","**
**打印 内容=`parts`**
```
## 7b. Mid M1 — regex + encoding (no plugin)
@@ -159,10 +186,10 @@ import enc:lib/encoding.mq.md
# main
*`ok` = > re.is_match text="a@b.c" pattern="@"*
*`b64` = > enc.base64_encode text="hi"*
> print text=`ok`
> print text=`b64`
**`ok` = [re.is_match] text="a@b.c" pattern="@"**
**`b64` = [enc.base64_encode] text="hi"**
**打印 内容=`ok`**
**打印 内容=`b64`**
```
## 7c. Mid M6 — log + uuid
@@ -178,8 +205,8 @@ import uuid:lib/uuid.mq.md
> log.info text="start"
> log.set_level level="debug"
> log.debug text="detail"
*id = > uuid.v4*
> print text=`id`
**id = [uuid.v4]**
**打印 内容=`id`**
```
## 8. Comment paragraphs (blank-line rule)
@@ -188,7 +215,7 @@ import uuid:lib/uuid.mq.md
# main
This whole paragraph is a comment, including lines that look like code:
*not_executed = 1*
**not_executed = 1**
> print text=also still comment
After a blank line, code runs:
@@ -206,13 +233,13 @@ import math:lib/math.mq.md
# main
*t = > num value=3.5*
> print text=`t`
**t = > num value=3.5**
**打印 内容=`t`**
```
## 10. Object handle + method
See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` constructs a map with `_type`; methods use `` > `obj`.method `` and read `self` / `自`.
See `tests/structure/object-handle.mq.md` and `ext/ai/llm.mq.md`: `# Type` constructs a map with `_type`; methods use `` > `obj`.method `` and read `self` / `自`.
## 10b. Object inheritance
@@ -222,16 +249,16 @@ See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` construc
## hello
+ `who`
*msg = "Hello, `who`!"*
**msg**
**msg = "Hello, `who`!"**
*msg*
# Loud = > Greeter
## hello
+ `who`
*msg = "HELLO, `who`!"*
**msg**
**msg = "HELLO, `who`!"**
*msg*
```
`_type` stays the most specific name (`Loud`). Methods walk the base chain; same-name `##` on the child overrides. **No implicit super** — if the child needs parent fields, call the parent explicitly:
@@ -240,9 +267,9 @@ See `tests/structure/object-handle.mq.md` and `ext/llm.mq.md`: `# Type` construc
# Child = > Parent
+ `name`
*self = > Parent name=`name`*
*self = > json.set map=`self` key=extra value=1*
**self**
**self = > Parent name=`name`**
**self = [table.put] in=`self` at="extra" value=1**
*self*
```
## 11. Agent layout (ABI)
@@ -256,9 +283,9 @@ import agent:ext/agent.mq.md
> load_native
*ws = > agent*
*n = > `ws`.ensure_layout*
> print text=`n`
**ws = > agent**
**n = > `ws`.ensure_layout**
**打印 内容=`n`**
```
Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see `doc/design/ext-agent.md`).
@@ -266,14 +293,14 @@ Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see
## 12. What not to emit
```markdown
# BAD — bold is return, not print
# BAD — bare bold that is not code-shaped (decorative OK); do not use bold/italic as print
**Hello**
# BAD — Python control keywords
if x > 0:
print(x)
# BAD — wrapping a call in italics
# BAD — wrapping a call in italics as if it were a statement
*> print text=hi*
# BAD — old branch syntax (removed)
@@ -290,6 +317,10 @@ if x > 0:
> print text=y-pos
2. *
> print text=y-other
# GOOD — print / return
**打印 内容="hi"**
*n + 1*
```
## 13. Dynamic site (ext/web, minimal)
@@ -316,14 +347,14 @@ import db:db/index.mq.md
| title | posts.title | |
| body | posts.summary | |
*store = > db.open*
*css = "body{font-family:sans-serif}"*
*page = > web.page title="Hello"*
*page = > page.compose_components components=`shell`*
*page = > page.compose_main main=`main`*
*page = > page.css css=`css`*
*app = > web.app page=`page` port=8080*
*app = > app.static prefix="/static" dir="static"*
**store = > db.open**
**css = "body{font-family:sans-serif}"**
**page = > web.page title="Hello"**
**page = > page.compose_components components=`shell`**
**page = > page.compose_main main=`main`**
**page = > page.css css=`css`**
**app = > web.app page=`page` port=8080**
**app = > app.static prefix="/static" dir="static"**
> listen app=`app`
```
@@ -347,13 +378,13 @@ import quantum:ext/quantum/quantum.mq.md
| 1 | H | 0 |
| 2 | CX | 0,1 |
*qc = > quantum.circuit qubits=2 steps=`steps`*
*rho = > `qc`.density*
*red = > `rho`.partial_trace keep=0*
*sch = > `qc`.schmidt cut=1*
*_ = > `qc`.draw kind="circuit" theme="dark"*
*_ = > `qc`.draw kind="hinton"*
> print text=`red`
**qc = > quantum.circuit qubits=2 steps=`steps`**
**rho = > `qc`.density**
**red = > `rho`.partial_trace keep=0**
**sch = > `qc`.schmidt cut=1**
**_ = > `qc`.draw kind="circuit" theme="dark"**
**_ = > `qc`.draw kind="hinton"**
**打印 内容=`red`**
```
- Full lab: `examples/quantum-entanglement/`. Bell-only: `examples/quantum-bell/`.
@@ -369,19 +400,18 @@ import la:ext/linalg/linalg.mq.md
# main
*`A` = > la.symbol name="A" rows=2 cols=2*
*`B` = > la.symbol name="B" rows=2 cols=2*
*`C` = `A` + `B`*
*`P` = `A` * `B`*
*`s` = > `P`.T.simplify* <!-- prefer: *`Pt` = > `P`.T* then simplify -->
**`A` = > la.symbol name="A" rows=2 cols=2**
**`B` = > la.symbol name="B" rows=2 cols=2**
**`C` = `A` + `B`**
**`P` = `A` * `B`**
```
Prefer:
```markdown
*`env` = > la.declare table=`shapes`*
*`P` = env[^A] * env[^B]*
*`t` = > `P`.T_ascii*
**`env` = > la.declare table=`shapes`**
**`P` = [A](env) * [B](env)**
**`t` = > `P`.T_ascii**
```
- Infix `+` / `-` / `*`;`ascii` / `T_ascii` 默认化简(`raw=True` 可关)。
+3 -2
View File
@@ -18,7 +18,7 @@ marqdo ext remove llm|agent|web|quantum|linalg
Diagnostics look like `path:line:col: message` (1-based line/col).
**v0.2 surface:** parameters `` + `name` ``; branches `` 1. `cond` `` / `` 2. * `` (same-indent restart at `1.` = **new** branch statement); loops `` - [item](coll) `` or `` - [`item`](`coll`) ``; identifiers in backticks (foreach header may omit ticks). See `doc/design/markdown-mapping.md`.
**v0.3 surface:** `**…**` = code; `*…*` = return; parameters `` + `name` `` (or prose-inferred); branches `` 1. `cond` `` / `` 2. * `` (same-indent restart at `1.` = **new** branch statement); loops `` - [item](coll) ``; get `` [key](coll) ``; bracket calls `` mod [fn] args ``. See `doc/design/markdown-mapping-v0.3.md`.
Stdlib search order for `lib/…` imports: `MARQDO_LIB`, `./lib`, directory of the `marqdo` executable (and a few parents). Prefer the **bundle zip** (`marqdo.exe` + `lib/`) over a bare exe.
@@ -183,7 +183,8 @@ See `doc/design/call-arguments.md`.
| Doc | Topic |
|-----|--------|
| `doc/design/markdown-mapping.md` | Syntax constitution |
| `doc/design/markdown-mapping-v0.3.md` | Syntax constitution (runtime) |
| `doc/design/markdown-mapping.md` | Legacy v0.2 notes |
| `doc/design/objects.md` | `#` objects / `##` methods |
| `doc/design/keywords.md` | Builtins / keywords |
| `doc/design/return-hr-and-code-surface.md` | Function end / surfaces |
+9
View File
@@ -0,0 +1,9 @@
# Ext CDN / R2 (Cloudflare) — copy to ~/.marqdo/r2.env and chmod 600
# Never commit real keys. Public downloads: https://ext.marqdo.com
R2_ACCOUNT_ID=
R2_BUCKET=marqdo
R2_ENDPOINT=https://<accountid>.r2.cloudflarestorage.com
R2_ACCESS_KEY_ID=
R2_SECRET_ACCESS_KEY=
R2_PUBLIC_BASE=https://ext.marqdo.com
+15
View File
@@ -0,0 +1,15 @@
## 层归属(必填,见 doc/design/layers.md)
- [ ] Language(`src/lex` `src/parse` `src/ast` `src/interp` `src/diagnostics` / 契约)
- [ ] Runtime(`lib/` `plugins/` `crates/` catalog / view / debug / builtin)
- [ ] Document(`*.mq.md` `skills/` `ext/` `public/` `examples/`)
## 核心表面(见 doc/design/core-surface.md)
- [ ] 不涉及核心标记
- [ ] 涉及核心标记:ADR 编号 ______;core-surface.md 与 `CORE_CONSTRUCTS` 已同步(CI 守卫)
## 验收
- [ ] 相关验收(机器可验证)全绿
- [ ] 全量回归绿(`cargo test` / `go test ./...` 视触及面)
+67 -15
View File
@@ -20,15 +20,26 @@ jobs:
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
- name: Install Go (web plugin)
uses: actions/setup-go@v5
with:
go-version: "1.23.x"
- name: Install Node (VS Code extension)
uses: actions/setup-node@v4
with:
node-version: "20"
- name: Install MinGW for cgo (web.dll)
run: choco install mingw -y
- name: Build release CLI + official plugins
shell: bash
run: |
export PATH="/c/ProgramData/mingw64/mingw64/bin:/c/ProgramData/chocolatey/lib/mingw/tools/install/mingw64/bin:$PATH"
cargo build --release
cargo build --release -p marqdo_plugin_web -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)
run: git fetch origin vscode-extension && git checkout origin/vscode-extension -- vscode-extension
@@ -76,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"
@@ -89,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"
@@ -113,9 +126,14 @@ jobs:
## Marqdo ${{ github.ref_name }}
### 亮点 / Highlights
- **宿主 H1–H4**:`app.proxy` 同域 SSE 中继 · `app.invoke` HTTP→`##` · MCP Server stdio · 跨模块 db
- **Hosting H1–H4**: same-origin SSE proxy, HTTP→user `##`, MCP stdio server, cross-module db methods
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [ext-hosting.md](https://github.com/cflmy/marqdo/blob/main/doc/roadmap/ext-hosting.md)
- **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
- **v1.1.1**:AI 栈收口——llm `ask`/`stream`/`collect` · Metadata Binding · Skill Compilation + Adaptive Routing · MCP 客户端 + resume · 可选 `plugins/llm`
- **v1.1.1**: AI stack — llm ask/stream/collect, Metadata Binding, Skill Compilation + Adaptive Routing, MCP client + resume, optional plugins/llm
- **v1.0.7**:WS/网络边界加固;`url_encode` `%20`
- **v1.0.3**:Ubuntu PPA + 扩展 CDN(ext.marqdo.com)
- **Linux 包必出**:`*-native-x86_64-unknown-linux-gnu.zip` + Linux CLI bundle
- Details: [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md) · [mapping v0.3](https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping-v0.3.md)
### Downloads
@@ -123,7 +141,8 @@ 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` 插件 |
| `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 |
| `marqdo-*-source.zip` | Source snapshot (`git archive`) |
@@ -144,34 +163,67 @@ jobs:
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
linux-native:
linux:
runs-on: ubuntu-latest
# Wait until Windows has created the GitHub Release, then attach Linux zips
# (required: native plugins for `marqdo ext add` on Linux + CLI bundle).
needs: windows
steps:
- uses: actions/checkout@v4
- name: Install Rust
uses: dtolnay/rust-toolchain@stable
- name: Build official plugins (release)
run: cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
- name: Install Go (web plugin)
uses: actions/setup-go@v5
with:
go-version: "1.23.x"
- name: Package native zip
- name: Install zip + cgo toolchain
run: sudo apt-get update && sudo apt-get install -y zip gcc libc6-dev
- name: Build Linux CLI + official plugins
run: |
set -euo pipefail
cargo build --release
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm
bash ./scripts/build-web-plugin.sh
- name: Package Linux native zip + CLI bundle
run: |
set -euo pipefail
VER="${GITHUB_REF_NAME#v}"
TARGET="x86_64-unknown-linux-gnu"
mkdir -p dist/stage-native/native
cp target/release/libweb.so dist/stage-native/native/libweb.so
cp target/release/libagent.so dist/stage-native/native/libagent.so
cp target/release/libquantum.so dist/stage-native/native/libquantum.so
cp target/release/liblinalg.so dist/stage-native/native/liblinalg.so
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"
fi
test -f "$src" || { echo "missing $src" >&2; exit 1; }
cp "$src" "dist/stage-native/native/${lib}"
done
(cd dist/stage-native && zip -r "../marqdo-${VER}-native-${TARGET}.zip" .)
echo "NATIVE=marqdo-${VER}-native-${TARGET}.zip" >> "$GITHUB_ENV"
- name: Upload Linux native plugins
stage="dist/stage-linux"
rm -rf "$stage"
mkdir -p "$stage/ext/native" "$stage/lib"
cp target/release/marqdo "$stage/marqdo"
chmod +x "$stage/marqdo"
cp -a lib/. "$stage/lib/"
cp -a ext/. "$stage/ext/"
cp dist/stage-native/native/*.so "$stage/ext/native/"
linux_zip="marqdo-${VER}-${TARGET}.zip"
(cd "$stage" && zip -r "../${linux_zip}" .)
echo "LINUX_ZIP=${linux_zip}" >> "$GITHUB_ENV"
- name: Upload Linux packages
uses: softprops/action-gh-release@v2
with:
files: dist/${{ env.NATIVE }}
files: |
dist/${{ env.NATIVE }}
dist/${{ env.LINUX_ZIP }}
fail_on_unmatched_files: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+16 -1
View File
@@ -24,7 +24,8 @@
.marqdo/
**/.marqdo/
.marqdo-ext/
.env
/vendor/
/.cargo/config.toml
# Generated HTML beside tracked public/*.mq.md (sources stay in git)
/public/index.html
@@ -60,6 +61,7 @@ plugins/*/tmp/
/examples/web-net-site/data/
/examples/web-net-site-zh/data/
/examples/marqdo-blog/data/
/examples/anlian-mq/data/
# Quantum draw/SVG runtime outputs (sources & gold .mq.md stay tracked)
/tests/ext/quantum-*.svg
@@ -72,3 +74,16 @@ plugins/*/tmp/
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
/ext/native/
# Go web plugin c-shared build output (./scripts/build-web-plugin.sh)
/plugins/web/build/
# PPA build: bundled Rust toolchain (packed into .orig by ppa-build-source.sh only)
/third_party/rust/
/third_party/
# ephemeral sqlite / test artifacts
tests/ext/:memory:
# local secrets
.env
+392
View File
@@ -8,6 +8,398 @@
### Changed
## 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
**AI 原生闭环三件套落地**:核心表面守卫(问题一)· 渐进式契约(问题二)· MLSP for AI(问题三)。
`marqdo check` 静态契约防漂移、`marqdo mlsp` 让 AI **按需查询**语法而非背诵、`run --json` 统一结构化诊断(错误即数据,供 AI 直接消费)。
本版 CLI 与扩展包 **同步为 1.1.0**。
- **核心要小(问题一)**:`doc/design/core-surface.md` 列出 19 个核心构造 + `CORE_CONSTRUCTS` 守卫测试——任一侧(清单/文档/金样)单边改动 CI 必红;三层架构(Core / Runtime / Document)入 `doc/design/layers.md`。
- **语义校验(问题二)**:渐进式契约表(`参数`/`返回`/`字段`/集合)嵌入文档叙述;四边界校验(调用实参 / 返回值 / 表绑定 / 键访问);`marqdo check` 静态防漂移(类型 typo / 参数名漂移 / 重复契约必报)。
- **AI 可靠反馈 + 不必学语法(问题三)**:`marqdo mlsp`(MLSP,行分隔 JSON over stdio)提供 `locate` / `syntax` / `validate` / `repair_targets` / `repair_apply` / `schema`;`syntax` 卡片机械携带戒律原文 / 样例 / 文档锚点,AI 无需预学语法。修复护栏:有界行编辑、越界必拒(abstain)。
- **验证(P4)**:锚点消融 anchor 一轮修复率 **100%**(双模型,plain 85%/90%);契约消融拦截 100% / 误报 0%;防漂移必报 9/9;核心守卫演练 3/3 必红。详见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)。
```bash
# Ubuntu PPA / 源码
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
git checkout v1.1.0 && cargo build --release
marqdo ext add web
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造(`heading` / `bold-code` / `italic-return` / `param-list` / `call-quote` / `branch-list` / `loop-list` / `table-bind` / `footnote-index` / `link-index` / …)与 v1.0.7 完全一致,未新增标记。本版为 **Runtime 层(契约校验 / MLSP / 诊断 JSON)** 与 **Document 层(core-surface / layers)** 变更,不触碰语言核心。
### Added
- **MLSP(`marqdo mlsp`)**:面向 AI 的语言服务协议(行分隔 JSON over stdio)——`locate` / `syntax` / `validate` / `repair_targets` / `repair_apply` / `schema`;`syntax` 卡片含 `semantics` / `rule` / `sample` / `doc_quote`(自持,机器可读戒律原文)。
- **`marqdo check`**:静态契约漂移检查(未知类型词 / 参数名漂移 / 返回越约 / 重复契约表 / 错位契约表)。
- **渐进式契约(Progressive contracts)**:文档叙述内嵌契约表(`参数`/`返回`/`字段` + 集合 `字段`),四边界校验(调用实参 / 返回值 / 表绑定 / 键访问);被绑定的 `字段|类型` 表是**数据**、永不误判为契约。
- **`marqdo run --json`**:统一结构化诊断(`code` / `severity` / `suggestion` / `doc_anchor` / `doc_quote` / `contract_ref`),错误即数据。
- **修复护栏**:`mlsp repair_apply` 有界行编辑——只允许落在 `doc_anchor` 指定范围内的编辑,越界整体拒绝(all-or-nothing / abstain)。
- **守卫与文档**:`doc/design/core-surface.md`(19 构造)、`doc/design/layers.md`(三层架构)、`tests/core_surface.rs`(守卫生效验证)。
### Fixed
- **错误链不再扁平化**:`src/load.rs` 以 `label_error` 保留结构化 `Diagnostic`("Error Exit Only" 原则),修复契约类错误被降级为字符串的回归。
- **契约 parse 边界**:`interp.rs` 键访问优先给出 `index_diag`(索引/键诊断先于取值),空字段 vs 缺字段语义消歧。
### Changed
- **`.cursor/skills/marqdo`**:由「背诵式压缩操作手册」改为**查询式工作流**——写码前 `mlsp syntax` / `locate`,提交前 `mlsp validate` + `marqdo check`,修复照 `doc_anchor` 局部改。
- **契约表一经出现即为完整声明**(新推断的升参未覆盖 ⇒ `contract.param_drift` 警告,不静默)。
- 取元**主推** `[键](集合)`(`link-index`);`` `集合`[^键] ``(`footnote-index`)保留兼容。
### 已知未决(诚实标注)
- **P4 实验 (b) 盲测未达标**:「查询式 vs 全文档背诵」四判据未全立(`deepseek-flash`:docs 4/6 vs query 0/3;端点 infra 削样本)。查询机制本身已验证无缺陷,瓶颈在**模型自查纪律**(不知道自己不知道 ⇒ 不查询)——协议改进(写码前强制自检 / 陌生构造强制查询)列入下一阶段。见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md) §3。
## Unreleased
## v1.0.7 — 2026-09-22
### Highlights
**WS / 网络边界加固**:WebSocket 握手同源校验、broadcast/room 默认需登录(`require_auth`/`需要登录` 可显式关闭)、消息 1 MiB × 256 条上限、空 room 回收;HTTP 响应 8 MiB 在读流时截断;`url_encode` 空格 `%20`。本版 CLI 与扩展包 **同步为 1.0.7**。
- **安全默认**:浏览器 WS 握手仅同源;有状态 fan-out 端点未登录 401 / 公开直播流显式 `require_auth=False`
- **资源上限**:WS 单条 1 MiB、单连接 256 条;HTTP/SSE 8 MiB 读流截断——对端无法借大响应耗尽内存
- **测试**:P3 金样对齐 quiet-admin 门禁语义;wasm smoke 以 ESM 加载官方 bridge
```bash
# Ubuntu PPA / 源码
sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo
git checkout v1.0.7 && cargo build --release
marqdo ext add web
```
### Fixed
- **WS 安全默认**:握手改为同源校验(不再放行任意 Origin);`route_ws` 新增 `require_auth`/`需要登录`,broadcast/room 默认要求登录会话,公开直播流需显式设假,未认证握手 401。
- **WS 资源上限**:单条消息 1 MiB、单连接最多收集 256 条回复;传输错误/超时返回 `{ok:false, error}`,不再伪装空成功;空 room 自动回收(防 URL 派生 room 名耗尽内存)。
- **HTTP 响应上限**:8 MiB 上限在读流时截断(含错误路径与 SSE 错误路径),上游无法借超大响应耗尽内存。
### Changed
- `net.url_encode`:空格编码为 `%20`(原 `+`),URL 段语义下与字面 `+` 消歧义。
- `web`/`网页` 文档同步:`route_ws` 的 `require_auth`/`需要登录` 与 `ws.connect` 的收集上限语义。
## Unreleased
### Added
### Fixed
### Changed
## Ext pack v1.0.6 — 2026-09-18
### Highlights
**ext/web OIDC、表单删除与安静管理台(CLI 仍为 v1.0.3)**:OIDC 登录/登出回首页、表单 `删除` 动作、默认关闭内置 admin/RBAC desk、独立 Redis 会话 URL、Postgres CRUD。安装:
```bash
marqdo ext add web # CDN latest → 1.0.6
```
### Added
- **OIDC**:`auth.oidc` / 网页鉴权 OIDC;登录入口与 `next` 回跳。
- **表单删除**:`form` 动作 `删除`/`delete`(通用 CRUD,无站点特判)。
- **列表/路由**:请求上下文、列表装配延续;注销默认回 `/` 避免 IdP 再登录环。
### Fixed
- 内置 admin / RBAC desk 默认安静,直至显式 `admin` / `enable_rbac`。
- 静态资源缓存与 WASM 启动延迟;会话 CSRF 与 Postgres 方言。
### Changed
- 扩展包 SemVer **1.0.6**(`ext/VERSION`);与 CLI **v1.0.3** 可独立安装。
## Ext pack v1.0.5 — 2026-09-18
### Highlights
**ext/web 请求上下文与表单来源(CLI 仍为 v1.0.3)**:字段 `来源`/`source`(session / route / now)、server-only 盖戳、页面 `列表装配`/`compose_list`;禁止按业务表特判。安装:
```bash
marqdo ext add web # CDN latest → 1.0.5
```
### Added
- **Request context**:表单提交携带 `_mq_params` / `_mq_return`;`ApplySources` 从 session/route/now 写入。
- **字段来源列**:`client`(默认)/ `session.username` / `route.NAME` / `now`;非 client 不渲染且覆盖客户端伪造。
- **列表装配**:`compose_list` / `列表装配`(副绑定 + 条件/排序/插槽),详情页可同页渲染子列表。
- 设计文:[ext-web-request-context.md](doc/design/ext-web-request-context.md);金样 `ext_web_form_source_live`。
### Changed
- 扩展包 SemVer **1.0.5**(`ext/VERSION`);与 CLI **v1.0.3** 可独立安装。
- 移除评论表名特判(`enrichCommentSubmit`)。
## Ext pack v1.0.4 — 2026-09-17
### Highlights
**ext/web 能力面扩展(CLI 仍为 v1.0.3)**:可配置 RBAC、租户作用域、WS `on_message`/presence、原生 SPA 内存路由、协同记事本 MVP。安装:
```bash
marqdo ext add web # CDN latest → 1.0.4
```
### Added
- **RBAC**:五表(`web_permissions` / `web_roles` / `web_role_permissions` / `web_users` / `web_user_roles`);`app.enable_rbac`、`app.gate permissions=`、`rbac.can`、注册页、`/_rbac/*` 管理 API/desk。
- **Tenant**:`app.tenant`(path/header/subdomain)+ `tenant_scope` 自动过滤/盖戳。
- **WebSocket G-WS2**:`route_ws` 支持 `on_message` 钩子、动态 room、`presence` 通道。
- **Native SPA**:内存 `store_set` / `spa_goto` 与全页 WASM SPA 样站。
- **Collab MVP**:LWW 文档协议(`DOC\t`)双端协同记事本样站。
### Changed
- 扩展包 SemVer **1.0.4**(`ext/VERSION`);与 CLI **v1.0.3** 可独立安装。
## v1.0.3 — 2026-09-17
### Highlights
**分发渠道齐备**:Ubuntu PPA 装 CLI;扩展包走 CDN(`ext.marqdo.com`)与 GitHub;CLI 与扩展可分开发版。本版 CLI 与扩展包 **同步为 1.0.3**。
**语法**:未绑定的 GFM 表格是可丢弃的集合值,不再报 `unrecognized statement`(文档页可直接写安装表)。
```bash
# Ubuntu
sudo add-apt-repository ppa:cflmy/marqdo
sudo apt update && sudo apt install marqdo
marqdo ext add web
# 或源码 / Releases
git checkout v1.0.3 && cargo build --release
```
### Added
- Ubuntu PPA packaging: `debian/` + `scripts/ppa-ship.sh` (一键装工具/打包/dput) + `ppa-build-source.sh` + [ubuntu-ppa.md](doc/design/ubuntu-ppa.md).
- **Extension CDN** (`https://ext.marqdo.com` / Cloudflare R2):`ext add` 下载顺序改为 CDN → GitHub → proxy;独立包版本见 `ext/VERSION` 与 CDN `latest/VERSION`;上传脚本 `scripts/upload-ext-r2.py`(凭据 `~/.marqdo/r2.env`)。设计见 [ext-cdn.md](doc/design/ext-cdn.md)。
- `ext add` 下载:GitHub 失败后自动回退 `https://proxy.cflmy.top/github.com/…`;可用 `MARQDO_EXT_DOWNLOAD_BASE` 指定首选镜像;加长读写超时。
- 用户文档(README / `public/00-欢迎` / `features/05-扩展`)标明安装渠道:Ubuntu PPA、GitHub Releases、源码;扩展走 CDN。
### Fixed
- `ext/` 导入默认搜索 `~/.marqdo/ext`(与 `marqdo ext add` 安装根一致),无需再手动 `export MARQDO_EXT`。
- PPA/noble:捆绑 `third_party/rust`(现代 cargo)以构建 Cargo.lock v4;修复首次 Launchpad 构建失败(distro cargo 1.75)。
- 未绑定的 GFM 表格不再报 `unrecognized statement`:作为集合值求值后丢弃(文档中可写表)。
### Changed
- 允许 **CLI 与扩展包分开发版**:扩展包 SemVer 可与 `Cargo.toml` 不同(`MARQDO_EXT_VERSION` / `ext/VERSION` / CDN latest)。
- 发版 skill:支持 `full` / `cli` / `ext`;扩展必传 R2+GitHub;CLI 走 PPA;需用户操作时打印确切命令。
## v1.0.2 — 2026-09-16
### Highlights
**表驱动页面引言(`compose_intro` / `引言装配`)**:英雄区用 GFM「属性 / 值 / 样式」表声明,不再手写 HTML 字符串;WWW Demo 样站与后台门禁一并加固。
```bash
git checkout v1.0.2
cargo build --release
bash ./scripts/build-web-plugin.sh
# 或:解压 Release 的 marqdo-1.0.2-*-native-*.zip / Linux CLI zip
marqdo run examples/web-site-zh/index.mq.md
```
### Added
- Go `libweb`:`web_compose_intro` — 将引言表装配为 `.main-intro` HTML;中英 API `页面.引言装配` / `page.compose_intro`(`ext/web`)。
- 验收样例:`tests/ext/web-intro-compose.mq.md`;`examples/web-site` / `web-site-zh` 升级为表驱动引言 + 文学风壳层 + 卡片→详情路由。
### Fixed
- 后台样站:导航/侧栏/页脚槽位与门禁登录挂载对齐;表单字段加宽便于创建。
### Changed
- Demo 叙述与种子数据面向 WWW Industry / 可复现演示;作者仍零业务 JS、零手写 `.css`。
## v1.0.1 — 2026-09-15
### Highlights
**ext/web(Go libweb)回归修复**:动态路由查询条件恢复 `{param}` 代入;详情 SSR + Markdown;样式表数字不再误报。
```bash
git checkout v1.0.1
cargo build --release
bash ./scripts/build-web-plugin.sh
# 或:解压 Release 的 marqdo-1.0.1-*-native-*.zip / Linux CLI zip
marqdo run examples/marqdo-blog/index.mq.md
```
### Added
- Go web plugin:详情页正文 Markdown(goldmark GFM),对齐 Rust `pulldown-cmark` 路径。
### Fixed
- **动态路由 `{param}` 未代入查询条件**(`ext/web` Go):`selectPageData` 递归展开 `query` 全部字符串叶子;`data-slot-src` / `_route` 同步替换。`examples/marqdo-blog` `/post/{slug}` 详情 SSR 恢复。
- **样式表数字单元格误报「可疑 `/` 除法」**:`cssValueSuspicious` 不再把合法 `z-index`/`opacity` 等 number 当警告。
- Go 1.22+ ServeMux:`/static/` 与 `/static/favicon.svg` 的 GET/HEAD 注册冲突导致博客启动 panic。
- Rust archive 同步:`resolve_placeholders` 递归 + CSS number 误报收窄(非默认构建路径)。
## v1.0.0 — 2026-09-14
### Highlights
**Markdown 语法映射 v0.3 成为 1.0 宪法**:`**粗体**` = 代码,`*斜体*` = 返回,叙述里的 `` `名` `` 声明并推断形参。这是相对 v0.4 / 旧 `*语句*`/`**返回**` 的破坏性对调。Linux 预编译拓展包与 CLI bundle 为 Release 必出资产。
```bash
git checkout v1.0.0
cargo build --release
# Linux:也可直接解压 Release 的 marqdo-1.0.0-x86_64-unknown-linux-gnu.zip
marqdo run tests/markup-v03/inc-prose.mq.md
```
### Added
- **Markup v0.3 运行时闭环**:粗体=`代码`、斜体=`返回`、叙述 `` `名` `` 声明与形参推断为唯一映射;金样 `tests/markup-v03/`。
- **方括号标记调用**与前置修饰语:`礼貌 [问候] x`;取元主语法 `[键](集合)`(脚注取元过渡保留)。
- **代码即文档叙述面 G1–G4**:模块级 `---` 跳过、装饰性强调、浮点面量、动态键。
- **粗体表达式语句** `**n + 1**`;`--dump-lines` 标注 `[decl]/[bold]/[italic]`;`--dump-ast` 显示 inferred 形参与死绑定。
- **Release Linux 包必出**:`linux` job 上传 `*-native-x86_64-unknown-linux-gnu.zip` 与 Linux CLI bundle。
### Fixed
- 行首 `` `名`… `` 叙述不再当语句(修复 pages CI:`public/features/16-fs-mid2.mq.md`)。
- 句中斜体强调(`*very important*` / `*foo.bar*`)不再误收束函数;Decl 名须为标识符;残缺粗体保持 GAP 恢复。
- 胶合 `` `名`=default …prose `` 为 Decl 而非赋值。
### Changed
- 教程 / Skill / `lib` / `ext` / `public` 对齐 v0.3 标记;view 推断形参 `chip inferred`。
## v0.4.0 — 2026-09-13
### Highlights
**Go `libweb` 默认落地(W-G0–W-G14)**:官方网页原生插件改为 Go C ABI;CLI / gold / Release 走 `scripts/build-web-plugin.sh`;Rust 源码归档。另附 **anlian-mq** 验收站与表单插槽 / `MARQDO_EXT` 提示修复。
```bash
git checkout v0.4.0
# 构建 web 原生插件(需 Go + cgo):
bash ./scripts/build-web-plugin.sh
marqdo ext add web
marqdo run examples/anlian-mq/index.mq.md
```
### Added
- **`plugins/web` Go 全量重写(W-G0–W-G13)**:C ABI 对等装配/DB/表单/listen/鉴权/上传/SEO/WS/驱动/proxy·invoke/定制壳;`scripts/build-web-plugin.sh` → `libweb.so` / `web.dll`;ADR [0004](doc/adr/0004-web-plugin-go.md) · 施工 [ext-web-go-rewrite.md](doc/design/ext-web-go-rewrite.md)。
- **W-G14 验收**:`examples/anlian-mq/`(暗恋见君风格论坛:路由/登录/粉玻璃主题/片段 API;SQLite 本地可跑)。
- **GAP-11**:`compose_form` / `表单装配` 支持 `target` / `表单插槽`(如 `#id`),把表单注入引言 HTML 内的挂载点。
### Fixed
- **GAP-12**:`ext/…` import 解析失败且未设置 `MARQDO_EXT` 时,错误附带 `hint: set MARQDO_EXT to the directory that contains web/`。
- **listen 会话 / CSRF**:登录后 `IssueCookie` 不再误设 `Max-Age=0`;页面 ABIs(`query`/`order`/`link_prefix`/`css`/`detail`)与 `web_page_chrome`、`invoke return=html` 对齐 anlian 需求。
### Changed
- **默认 `libweb` 为 Go**:Release / gold / `ext add web` 不再构建 Rust `marqdo_plugin_web`;旧 Rust 树移至 `plugins/web-rust-archive/`(非 workspace 成员)。作者面 `ext/web` ABI 名保持兼容。
## v0.3.9 — 2026-09-09
### Highlights
**业务联调缺口 GAP-06–10**:解析器不再吞掉嵌套反引号/`text=[…]` 后的函数体;`invoke` 的 `Null` 不再伪装成功;`sys.exec capture=` 可取 stdout;流式 proxy 反缓冲头。
```bash
git checkout v0.3.9
```
### Added
- **`sys.exec` / `系统.执行`**:可选 `capture=` / `捕获=`;为真时返回 `{code, stdout, stderr}`(GAP-09)。
### Fixed
- **GAP-06/07**:`*…*` 分类对反引号/字符串内的 `*` 不再误判;错误收尾的赋值行不再吞掉后续 `##` 体(`>` / 合法 `*…*` 可脱出注释段);命名参数边界尊重 `[…]`/`{…}`。
- **GAP-08**:`app.invoke` 对 `Null`/`None` 返回不再伪装成 `{"ok":true}`,改为 500 + `{"ok":false,"error":"null result"}`。
- **GAP-10**:`app.proxy` `stream=true` 响应补齐 `Cache-Control: no-cache, no-transform` 与 `X-Accel-Buffering: no`。
### Changed
## v0.3.8 — 2026-09-09
### Highlights
**中层标准库 Mid2(M7–M10)收口**:日历/时区、URL、TOML、HTML 转义、base32、实用 fs、薄统计与日志字段——日常脚本与工具配置不再依赖外联或插件。另修复嵌套插件调用后 `GLOBAL_HOST` 被清空导致 `invoke` 失败。
```bash
git checkout v0.3.8
# 或下载 Release 的 exe / zip
marqdo run public/features/14-datetime-url.mq.md
marqdo run public/features/17-stats-log.mq.md
```
### Added
- **中层标准库 Mid2 M10**:`lib/stats` / `统计`(mean/median/stdev)与 `log`/`日志` 可选 `fields=`;金样与 public `17-stats-log`。**Mid2 M7–M10 收口**(zip 跳过)。设计 [stdlib-stats-log.md](doc/design/stdlib-stats-log.md)。
- **中层标准库 Mid2 M9**:`fs.make_dirs` / `remove_tree` / `stat` / `walk`(中英);金样与 public `16-fs-mid2`。设计 [stdlib-fs-mid2.md](doc/design/stdlib-fs-mid2.md)。
- **中层标准库 Mid2 M8**:`lib/toml` / `配置表`(只读子集)、`lib/html` / `超文本`(escape/unescape)、`encoding` base32;金样与 public `15-toml-html-encoding`。设计 [stdlib-toml.md](doc/design/stdlib-toml.md) · [stdlib-html.md](doc/design/stdlib-html.md)。
- **中层标准库 Mid2 M7**:`lib/datetime` / `日期时间`(`{unix,zone,iso}` · parse/format/add/in_zone)与 `lib/url` / `地址`(parse · query_parse/stringify);金样与 public `14-datetime-url`。设计 [stdlib-datetime.md](doc/design/stdlib-datetime.md) · [stdlib-url.md](doc/design/stdlib-url.md)。
- **文档**:中层标准库 Mid 之后缺口盘点与 Mid2(M7–M10)设计/路线——[stdlib-gaps-after-mid.md](doc/research/stdlib-gaps-after-mid.md) · [stdlib-mid2.md](doc/design/stdlib-mid2.md) · [stdlib-mid2.md](doc/roadmap/stdlib-mid2.md)。
### Fixed
- **`host_query` / GLOBAL_HOST**:嵌套 `call_registered` 结束后恢复外层宿主指针,不再清空;`web_listen` 多轮 `invoke`(中间再调插件)不再报 `no active host context`。
### Changed
## v0.3.7 — 2026-09-07
### Highlights
Generated
+41 -1386
View File
File diff suppressed because it is too large. Load diff
+6 -3
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "0.3.7"
version = "1.2.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -50,18 +50,21 @@ include_dir = "0.7"
libc = { version = "0.2", optional = true }
[target.'cfg(target_arch = "wasm32")'.dependencies]
# No `wasmbind`: keeps cdylib free of wasm-bindgen imports (raw mq_* ABI).
# Custom entropy — no `js`/wasm-bindgen imports (raw mq_* ABI + marqdo-bridge.js).
chrono = { version = "0.4", default-features = false, features = ["alloc", "std"] }
getrandom = { version = "=0.2.17", default-features = false, features = ["custom"] }
[workspace]
members = [
"plugins/demo",
"plugins/agent",
"plugins/web",
"plugins/llm",
"plugins/quantum",
"plugins/linalg",
"crates/marqdo-wasm",
]
# Official web plugin is Go (`plugins/web/`); Rust sources kept as
# `plugins/web-rust-archive/` for reference (not a workspace member).
resolver = "2"
[dev-dependencies]
+100 -36
View File
@@ -1,8 +1,8 @@
# Marqdo
**代码即文档。文档即代码。文档即知识库。**
**代码即文档。文档即知识库。知识即可执行。**
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。它不是「又一个 Markdown 编程语言」,而是**文档原生的编程运行时(Document-native runtime)**——一门关于**可执行知识(Executable Knowledge)**的语言。
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
@@ -10,6 +10,47 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
---
## 核心优势:可执行知识(Executable Knowledge)
> **Knowledge That Can Run —— 知识即可执行。**
> Marqdo 不是「用 Markdown 写程序」这么简单:它让一个 `.mq.md` 文档**同时**是文稿、知识与程序——同一份结构,同时服务于人、解释器、工具与 AI。
```text
.mq.md(同一份文件)
┌─────────┼─────────┐
文稿 知识 程序
└─────────┼─────────┘
▼
Marqdo 运行时
▼
可执行知识(Executable Knowledge)
```
| 真正的核心优势 | 说明 |
|------|------|
| **知识-代码一致性**<br>Knowledge-Code Coherence | 说明、数据、示例与实现**同一份源文件**:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的**知识不一致**——知识陈述本身可以被测试。 |
| **默认安全,AI 友好** | 无标记文字默认是叙述(注释),只有显式标记才进入执行。AI 自由发挥**不会污染**文档与代码的边界——这比「自然语言编程」安全得多,是 AI 原生语言的重要前提。 |
| **multi-view artifact**<br>`.mq.md` 双后缀即开放接口 | `.mq` 告诉解释器「可执行」,`.md` 告诉整个 Markdown 生态「仍是文档」。GitHub 直接读、VS Code 直接改、搜索引擎直接索引、LLM 直接理解、Marqdo 直接运行。**Marqdo 不占有知识,只是给 Markdown 增加执行语义。** |
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元 `[键](集合)` 也是 Markdown 链接形。这是 literate programming 的下一步。 |
| **语义干净** | **返回是架构,打印只是函数**:`*…*` 改变控制流,`print` 只是副作用函数;分支与循环长在 Markdown 结构上(`1.` `2.` 递增 = 分支,`-` = 循环),不是所有列表都被粗暴当成 if。 |
| **AI 的可靠上下文与长期记忆** | 一个 `.mq.md` 同时是 documentation + schema + code + examples + knowledge + executable behavior;AI 不必再拼装 README + OpenAPI + JSON Schema + prompt。整个工程天然就是 AI 的**世界模型**——比 RAG 更接近 Executable RAG。 |
| **完整工程,不是玩具** | Rust 正经解释器(词法 / 语法 / 语义 / 树遍历 + 字节码后端)、stdlib、模块与对象、debugger、viewer、catalog、WASM、原生插件 ABI、VS Code 扩展、agent / LLM / MCP。 |
---
## 愿景与期许
不把「AI 能写 Marqdo」当终点,而是 **「AI 能可靠地生成可验证的 Marqdo」**:
1. **AI 可验证语言**:`LLM → Marqdo AST → 语义检查 → 结构化诊断 → LLM 修复 → 合格程序`。让类型与语义检查成为 AI 编程闭环里的强约束,堵住「语义看似合理、类型实则不对」的生成。
2. **Marqdo Schema / Language Server for AI**:机器可读的语言 Schema(`get_syntax` / `validate` / `repair` …),AI 不必读千行文档猜语法,而是 discover → construct → validate → execute → inspect。
3. **程序即 AI 长期记忆**:`.mq.md` 工程 = 可执行知识库 = AI 的世界模型(Executable Knowledge Representation)。
4. **可执行知识图**:`.mq.md` 之间的 Markdown 链接天然长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
5. **知识可测试**:文档中的示例表自动执行;知识与执行结果不一致会被机器报告——Knowledge-Code Coherence 从理念变为日常。
6. **可靠性基准**:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成真实任务,测量生成长度、语法 / 语义错误率、修复轮次、token 消耗与人类阅读 / 修改成本——用实验数据证明「文档型语法降低 LLM 生成熵」。
---
## 为什么重要
| 痛点 | Marqdo 的答案 |
@@ -23,23 +64,23 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
---
## 语法速览(v0.2)
## 语法速览(v0.3)
| 标记 | 含义 |
|------|------|
| 无标记行 | 注释(空行分段) |
| `*…*` | 程序语句 |
| `**…**` | **返回值**(架构) |
| `****` / `**` + 空白 + `**` | **空返回**(`None`),并结束本函数体 |
| 无标记行 | 叙述(注释);行内 `` `名` `` 可声明 |
| `**…**` | **代码**(赋值 / 调用 / 表达式) |
| `*…*` | **返回值**(整行、`返回*n*`、或表达式形) |
| `****` / 整行 `**` / `*None*` | **空返回**(`None`),并结束本函数体 |
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
| `##` … | 函数 / 方法(按标题深度嵌套) |
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
| `+` / `1.` … | 函数头下 `` + `名` `` = 形参;体内 `1.` `2.` … = 分支(`N. *` = else) |
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) `` / `` - [`项`](`集合`) ``) |
| 表格 | 集合 |
| 函数体内单独一行 `---` / `***` | **结束本函数体**(无返回值收束;见 mapping §11) |
| 文件开头成对 `---` … `---` | Frontmatter(元信息 / 导入),与函数结束符消歧 |
| 叙述 `` `名` `` / `` `名`=默认 `` | 形参由体推断(`` + `名` `` 仍可用) |
| `1.` … | 体内 `1.` `2.` … = 分支(`N. *` = else) |
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) ``) |
| 表格 | 集合(几何即类型,见下);取元优先 `[键](集合)` |
| 单独一行 `---` / `***` | **叙述分隔**(跳过;不是函数收束) |
```markdown
# main
@@ -47,19 +88,20 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
> 问候 谁=World
## 问候
+ `谁`
> print text=Hello `谁`!
向`谁`问好。
---
**print text="Hello " + 谁**
*None*
## 加一
+ `n`
**`n` + 1**
对于输入变量`n`,执行**n=n+1**接着返回*n*。
```
完整约定:[markdown-mapping.md](doc/design/markdown-mapping.md)。
**表格几何即类型**:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。详见 [tables-maps-footnotes.md](doc/roadmap/tables-maps-footnotes.md)。
完整约定:[markdown-mapping-v0.3.md](doc/design/markdown-mapping-v0.3.md)。
---
@@ -69,7 +111,8 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
2. **返回是架构;打印只是函数。**
3. **代码即文档即知识库**:文稿可执行,执行可回看结构,结构可导航与调试。
4. **对齐 [OKF](https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md)(Open Knowledge Format)方向**:清单由工具从 `.mq.md` **自动生成**,不是手填配置——见下节与 [catalog-cli.md](doc/design/catalog-cli.md)。
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
5. **正经解释器(Rust)**:词法/行分类 → 语法 → 语义 → 树遍历(及字节码);**不用 Flex/Bison**。见 [路线图](doc/roadmap/interpreter.md)。
6. **语言核心保持小**:Language(标记映射 / AST / 语义 / 类型)、Runtime(stdlib / 插件 ABI / WASM / agent)、Document(知识 + 代码 + UI + AI)三层分明——生态功能不淹没语言身份。
---
@@ -99,34 +142,47 @@ marqdo catalog public -o .marqdo
---
## 现状(v0.3.7)
## 现状(v1.2.0)
- 映射与解释器:Phase I 树遍历 + 字节码后端可用;金样例在 `tests/`
- **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 debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页
- **`marqdo version --check`**:与 GitHub 最新 release 对比
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**;**中层 Mid M1–M6**(`re`/`encoding`/`path`/`hash`/`secrets`/`csv`/`cli`/`log`/`uuid` 及中英对称库,见 [stdlib-mid.md](doc/design/stdlib-mid.md))
- 标准库:**内置于二进制**(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));示例 [marqdo-blog](examples/marqdo-blog/);生产路径见 [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** + Skill Compilation + Adaptive Routing + resume;宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.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}`
- **原生插件 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(v0.3.7)
### 如何使用最新 Marqdo(v1.2.0)
**安装解释器(任选其一)**
| 方式 | 适用 | 命令 / 链接 |
|------|------|-------------|
| **Ubuntu PPA** | Ubuntu 24.04+(`noble` 等) | `sudo add-apt-repository ppa:cflmy/marqdo && sudo apt update && sudo apt install marqdo` |
| **GitHub Releases** | Windows / Linux 预编译 zip | https://github.com/cflmy/marqdo/releases |
| **源码** | 需本机 Rust | 见下方 `git clone` + `cargo build --release` |
**安装官方扩展**(与 CLI 可分开发版):`marqdo ext add …` 默认下载顺序为 **CDN** [`https://ext.marqdo.com`](https://ext.marqdo.com) → GitHub Releases → [`proxy.cflmy.top`](https://proxy.cflmy.top) 镜像。
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v0.3.7 # 或留在 main
git checkout v1.2.0 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
@@ -139,25 +195,33 @@ marqdo view public --no-open
marqdo debug public --no-open
marqdo catalog public -o .marqdo
# 3) 安装官方扩展(Release 用户:无需本机 Rust)
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native
# 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
# 3) 安装官方扩展(Release / CDN 用户:无需本机 Rust/Go)
marqdo ext add web # 或:网页 — 自动下载 L1 + 预编译 native(Go libweb)
marqdo ext add agent # 或:智能体
marqdo ext add quantum # 或:量子
marqdo ext add linalg # 或:线性代数
marqdo ext add llm # 或:大模型(纯 .mq.md)
# 开发者也可:cargo build --release -p marqdo_plugin_* 后在本机 target/ 安装
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/marqdo-blog/index.mq.md
marqdo run examples/web-site-zh/index.mq.md # 表驱动引言 Demo
marqdo run examples/marqdo-blog/serve.mq.md
marqdo run examples/anlian-mq/index.mq.md # W-G14 验收站
# 浏览器打开终端打印的 listen 地址;/favicon.ico 与 logo 装配见 W8
# 5) 浏览器 WASM(可选)
marqdo wasm build
# → dist/wasm/ … 见 examples/browser-hello/
# 6) Windows:也可从 GitHub Releases 下载 exe / zip / vsix
# https://github.com/cflmy/marqdo/releases/tag/v0.3.7
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
# https://github.com/cflmy/marqdo/releases/tag/v1.2.0
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
@@ -169,7 +233,7 @@ cargo run -- view output public -o public
powershell -File ./scripts/build-public.ps1
```
**发布包(GitHub Releases)**:单独二进制 **已内置**官方 `lib/`(`import …:lib/…` 可直接导入)。仍提供带 `lib/` 的 zip 便于覆盖或离线分发。**扩展库**用 `marqdo ext add …` 安装(见 [CHANGELOG](CHANGELOG.md) 与 [ext-cli.md](doc/design/ext-cli.md));原生 `.so`/`.dll` 需本地编译或从带 `native/` 的安装目录解析。
**发布包**:GitHub Releases 的单独二进制 **已内置**官方 `lib/`。Ubuntu 用户优先 **PPA** 装 CLI。**扩展库**用 `marqdo ext add …`(CDN → GitHub);设计见 [ext-cdn.md](doc/design/ext-cdn.md) · [ubuntu-ppa.md](doc/design/ubuntu-ppa.md) · [ext-cli.md](doc/design/ext-cli.md)。
文档:用户站 [public/](public/) · 设计 [doc/](doc/) · OKF / catalog [catalog-cli.md](doc/design/catalog-cli.md) · 调试 [view-debug.md](doc/design/view-debug.md) · 变更 [CHANGELOG.md](CHANGELOG.md)
---
+1 -1
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo-wasm"
version = "0.3.7"
version = "1.2.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
+118 -64
View File
@@ -197,6 +197,20 @@ export function eventArgsFromDom(ev, valueFromSel) {
args.fields = fields;
}
}
if (ev && (ev.type === "scroll" || ev.type === "resize")) {
try {
const doc = typeof document !== "undefined" ? document.documentElement : null;
const body = typeof document !== "undefined" ? document.body : null;
const scrollTop = (doc && (doc.scrollTop || 0)) || (body && body.scrollTop) || 0;
const height = doc ? (doc.scrollHeight - doc.clientHeight) || 1 : 1;
const ratio = Math.max(0, Math.min(1, scrollTop / height));
args.scroll_top = scrollTop;
args.scroll_max = height;
args.scroll_ratio = ratio;
} catch (_) {
/* ignore */
}
}
return args;
}
@@ -721,75 +735,88 @@ function runObserveEffect(exports, spec, onError) {
const kind = String(spec.kind || spec.type || "intersect").toLowerCase();
const sel = String(spec.sel || "");
const thenFn = spec.then;
const id = String(spec.id || `obs${++observeSeq}`);
const el = qsOne(sel);
if (!el || !thenFn) return;
const baseId = String(spec.id || `obs${++observeSeq}`);
const nodes = qsAll(sel);
if (!nodes.length || (!thenFn && !spec.add_class)) return;
const prev = observeHandles.get(id);
if (prev) {
try {
prev.disconnect();
} catch (_) {
/* ignore */
}
}
const fire = (payload) => {
try {
const result = call(exports, thenFn, payload);
if (!result.ok) {
if (onError) onError(result.error);
return;
nodes.forEach((el, idx) => {
const id = nodes.length === 1 ? baseId : `${baseId}_${idx}`;
const prev = observeHandles.get(id);
if (prev) {
try {
prev.disconnect();
} catch (_) {
/* ignore */
}
applyEffects(exports, result.value, { onError });
} catch (e) {
if (onError) onError(String(e));
}
};
if (kind === "resize" && typeof ResizeObserver !== "undefined") {
const ro = new ResizeObserver((entries) => {
const en = entries[0];
const cr = en?.contentRect;
fire({
ok: true,
kind: "resize",
id,
width: cr ? cr.width : 0,
height: cr ? cr.height : 0,
});
});
ro.observe(el);
observeHandles.set(id, ro);
return;
}
const fire = (payload) => {
try {
const result = call(exports, thenFn, payload);
if (!result.ok) {
if (onError) onError(result.error);
return;
}
applyEffects(exports, result.value, { onError });
} catch (e) {
if (onError) onError(String(e));
}
};
if (typeof IntersectionObserver !== "undefined") {
const io = new IntersectionObserver(
(entries) => {
if (kind === "resize" && typeof ResizeObserver !== "undefined") {
const ro = new ResizeObserver((entries) => {
const en = entries[0];
if (!en) return;
const cr = en?.contentRect;
fire({
ok: true,
kind: "intersect",
kind: "resize",
id,
intersecting: !!en.isIntersecting,
ratio: en.intersectionRatio,
width: cr ? cr.width : 0,
height: cr ? cr.height : 0,
});
if (spec.once && en.isIntersecting) {
try {
io.disconnect();
} catch (_) {
/* ignore */
});
ro.observe(el);
observeHandles.set(id, ro);
return;
}
if (typeof IntersectionObserver !== "undefined") {
const opts = { threshold: spec.threshold != null ? Number(spec.threshold) : 0.1 };
if (spec.rootMargin != null) opts.rootMargin = String(spec.rootMargin);
const io = new IntersectionObserver(
(entries) => {
const en = entries[0];
if (!en) return;
if (en.isIntersecting && spec.add_class) {
for (const c of String(spec.add_class).split(/\s+/).filter(Boolean)) {
el.classList.add(c);
}
}
observeHandles.delete(id);
}
},
{ threshold: spec.threshold != null ? Number(spec.threshold) : 0.1 },
);
io.observe(el);
observeHandles.set(id, io);
}
if (thenFn) {
fire({
ok: true,
kind: "intersect",
id,
intersecting: !!en.isIntersecting,
ratio: en.intersectionRatio,
target_id: el.id || "",
});
}
if (spec.once && en.isIntersecting) {
try {
io.disconnect();
} catch (_) {
/* ignore */
}
observeHandles.delete(id);
}
},
opts,
);
io.observe(el);
observeHandles.set(id, io);
}
});
}
function buildFetchInit(spec) {
@@ -921,8 +948,23 @@ function runIntervalEffect(exports, spec, onError) {
intervalHandles.set(id, handle);
}
const memoryKV = new Map();
function storageStore(scope) {
if (scope === "cookie") return null;
if (scope === "memory" || scope === "mem" || scope === "内存") {
return {
getItem(key) {
return memoryKV.has(key) ? memoryKV.get(key) : null;
},
setItem(key, value) {
memoryKV.set(key, String(value));
},
removeItem(key) {
memoryKV.delete(key);
},
};
}
if (typeof localStorage === "undefined") return null;
return scope === "session" ? sessionStorage : localStorage;
}
@@ -1371,12 +1413,24 @@ export async function autoMount(doc) {
const g = typeof globalThis !== "undefined" ? globalThis : undefined;
if (g && g.document) {
// Defer WASM boot until after first paint / load so LCP images are not
// contending with a ~1.6MB wasm download on the critical path.
const start = () => {
autoMount(g.document).catch((e) => console.error("marqdo autoMount:", e));
const run = () => {
autoMount(g.document).catch((e) => console.error("marqdo autoMount:", e));
};
const schedule = () => {
if (typeof g.requestIdleCallback === "function") {
g.requestIdleCallback(() => run(), { timeout: 1500 });
} else {
g.setTimeout(run, 0);
}
};
if (g.document.readyState === "complete") {
schedule();
} else {
g.addEventListener("load", schedule, { once: true });
}
};
if (g.document.readyState === "loading") {
g.document.addEventListener("DOMContentLoaded", start);
} else {
queueMicrotask(start);
}
start();
}
+5
View File
@@ -0,0 +1,5 @@
{
"name": "marqdo-bridge",
"private": true,
"type": "module"
}
+32 -1
View File
@@ -185,7 +185,38 @@ fn pack_json(v: &serde_json::Value) -> *mut u8 {
ptr::copy_nonoverlapping(len.to_le_bytes().as_ptr(), out, 4);
ptr::copy_nonoverlapping(bytes.as_ptr(), out.add(4), bytes.len());
}
out
out
}
/// getrandom `custom` backend for wasm32 — no wasm-bindgen / JS glue imports.
/// Preferable to the `js` feature which pulls `__wbindgen_*` and breaks raw mq_* ABI.
#[cfg(target_arch = "wasm32")]
#[no_mangle]
unsafe extern "Rust" fn __getrandom_custom(dest: *mut u8, len: usize) -> u32 {
// xorshift64* seeded once; fine for uuid/non-crypto browser host helpers.
use std::cell::Cell;
thread_local! {
static STATE: Cell<u64> = const { Cell::new(0x4d51_5241_4e44_4f21) };
}
if dest.is_null() || len == 0 {
return 0;
}
let mut s = STATE.with(|c| {
let mut v = c.get();
if v == 0 {
v = 0x4d51_5241_4e44_4f21;
}
v
});
let buf = unsafe { std::slice::from_raw_parts_mut(dest, len) };
for b in buf.iter_mut() {
s ^= s << 13;
s ^= s >> 7;
s ^= s << 17;
*b = (s >> 8) as u8;
}
STATE.with(|c| c.set(s));
0
}
#[cfg(test)]
+22
View File
@@ -0,0 +1,22 @@
Marqdo for Ubuntu (PPA)
=======================
This package installs the marqdo CLI (/usr/bin/marqdo).
Official language extensions are not bundled. After install:
marqdo ext add web
marqdo ext add quantum
Extension packs download from https://ext.marqdo.com (then GitHub / proxy).
Install this package from:
sudo add-apt-repository ppa:cflmy/marqdo
sudo apt update
sudo apt install marqdo
Also available: GitHub Releases (Windows/Linux zips) and building from source.
Documentation: https://github.com/cflmy/marqdo
PPA notes: doc/design/ubuntu-ppa.md in the upstream repository.
+62
View File
@@ -0,0 +1,62 @@
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.
New `marqdo check` (static contract drift) and `marqdo mlsp` (language
server for AI: locate/syntax/validate/repair_targets/schema/repair_apply);
`run --json` unified structured diagnostics; contract tables
(参数/返回/字段/集合) with four validation boundaries; anchored repair
guardrails (bounded line edits, out-of-scope refused).
-- cflmy <pingan@cflmy.cn> Wed, 23 Sep 2026 13:30:00 +0800
marqdo (1.0.7-1ppa1) noble; urgency=medium
* Marqdo 1.0.7: WS/net boundary hardening (same-origin handshake,
require_auth/需要登录, message caps, empty-room GC); HTTP 8 MiB cap
enforced while reading; url_encode space -> %20.
-- cflmy <pingan@cflmy.cn> Tue, 22 Sep 2026 15:40:00 +0800
marqdo (1.0.3-1ppa2) noble; urgency=medium
* Fix Launchpad build: dh_clean -Xvendor/ so cargo vendor checksums keep
Cargo.toml.orig (debian-only; reuse published 1.0.3.orig.tar.xz).
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 21:28:00 +0800
marqdo (1.0.3-1ppa1) noble; urgency=medium
* Marqdo 1.0.3: PPA + ext CDN; unbound GFM tables; bundled Rust for noble.
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 10:35:00 +0800
marqdo (1.0.2-1ppa2) noble; urgency=medium
* Bundle Rust toolchain in orig (third_party/rust) so noble can build
Cargo.lock v4 offline; drop distro cargo/rustc Build-Depends.
* Architecture: amd64 (bundled toolchain is x86_64).
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 10:20:00 +0800
marqdo (1.0.2-1ppa1) noble; urgency=medium
* Initial Ubuntu PPA packaging for Marqdo 1.0.2.
* CLI only; extensions via "marqdo ext add" / ext.marqdo.com.
-- cflmy <pingan@cflmy.cn> Thu, 17 Sep 2026 09:55:00 +0800
+29
View File
@@ -0,0 +1,29 @@
Source: marqdo
Section: devel
Priority: optional
Maintainer: cflmy <pingan@cflmy.cn>
Build-Depends:
debhelper-compat (= 13),
build-essential,
pkg-config,
libssl-dev,
ca-certificates
Standards-Version: 4.7.0
Homepage: https://github.com/cflmy/marqdo
Vcs-Git: https://github.com/cflmy/marqdo.git
Vcs-Browser: https://github.com/cflmy/marqdo
Rules-Requires-Root: no
Package: marqdo
Architecture: amd64
Depends: ${shlibs:Depends}, ${misc:Depends}, ca-certificates
Description: Markdown markers as an interpreted programming language
Marqdo treats Markdown markers as executable syntax (code / return /
control flow). This package installs the marqdo CLI.
.
Official extensions (web, quantum, …) are installed separately via
"marqdo ext add" and download from https://ext.marqdo.com .
.
Launchpad builds use a bundled Rust toolchain under third_party/rust
(Ubuntu noble cargo is too old for Cargo.lock v4). Rebuilds on newer
series may use distro rustc if cargo ≥ 1.78.
+24
View File
@@ -0,0 +1,24 @@
Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/
Upstream-Name: marqdo
Upstream-Contact: cflmy <pingan@cflmy.cn>
Source: https://github.com/cflmy/marqdo
Files: *
Copyright: 2024-2026 cflmy
License: Apache-2.0
License: Apache-2.0
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
.
http://www.apache.org/licenses/LICENSE-2.0
.
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
.
On Debian systems, the complete text of the Apache License version 2
can be found in "/usr/share/common-licenses/Apache-2.0".
Vendored Executable
+58
View File
@@ -0,0 +1,58 @@
#!/usr/bin/make -f
export DH_VERBOSE = 1
# Offline builds on Launchpad: vendored crates + optional bundled Rust toolchain.
export CARGO_HOME = $(CURDIR)/debian/cargo_home
export CARGO_NET_OFFLINE = true
# Noble (and older) distro cargo cannot read Cargo.lock v4 / modern crates.
# Prefer third_party/rust from the orig tarball when present (see ppa-build-source.sh).
BUNDLED_RUST = $(CURDIR)/third_party/rust
ifneq ($(wildcard $(BUNDLED_RUST)/bin/cargo),)
export PATH := $(BUNDLED_RUST)/bin:$(PATH)
endif
%:
dh $@
override_dh_auto_configure:
mkdir -p debian/cargo_home
@if [ -x "$(BUNDLED_RUST)/bin/cargo" ]; then \
echo "Using bundled Rust: $$($(BUNDLED_RUST)/bin/rustc --version)"; \
else \
echo "Using system Rust: $$(rustc --version 2>/dev/null || echo missing)"; \
fi
@if [ -f "$(CURDIR)/.cargo/config.toml" ] || [ -d "$(CURDIR)/vendor" ]; then \
echo "Using vendored Cargo dependencies"; \
else \
echo "WARNING: no vendor/ — online cargo fetch required (not for Launchpad)"; \
fi
override_dh_auto_build:
mkdir -p debian/cargo_home
@command -v cargo >/dev/null || { echo "error: cargo not found (bundle third_party/rust or install rustc/cargo)" >&2; exit 1; }
if [ -d "$(CURDIR)/vendor" ]; then \
CARGO_NET_OFFLINE=true cargo build --release --locked --offline \
-p marqdo; \
else \
cargo build --release --locked -p marqdo; \
fi
override_dh_auto_test:
@echo "Skipping full test suite on package build (run cargo test in CI)."
override_dh_auto_install:
install -d $(CURDIR)/debian/marqdo/usr/bin
install -m 0755 $(CURDIR)/target/release/marqdo \
$(CURDIR)/debian/marqdo/usr/bin/marqdo
# dh_clean deletes *.orig by default; cargo vendor checksums require
# vendor/**/Cargo.toml.orig. Exclude the vendored tree from that purge.
override_dh_clean:
dh_clean -Xvendor/
override_dh_auto_clean:
dh_auto_clean
rm -rf debian/cargo_home
# keep vendor/ and third_party/rust (part of source package)
-cargo clean
+1
View File
@@ -0,0 +1 @@
3.0 (quilt)
+2
View File
@@ -0,0 +1,2 @@
# Ignore temporary files while editing patches
extend-diff-ignore = "^vendor/"
+19 -1
View File
@@ -15,7 +15,10 @@
| 文档 | 摘要 |
|------|------|
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.1 语法宪法** |
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.2 语法宪法(现行运行时)** |
| [design/markdown-mapping-v0.3.md](design/markdown-mapping-v0.3.md) | **v0.3 草案:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断** |
| [adr/0005-prose-unified-markup.md](adr/0005-prose-unified-markup.md) | **Proposed:采纳 mapping v0.3** |
| [roadmap/markup-v0.3.md](roadmap/markup-v0.3.md) | **Markup v0.3 实现路线(M0–M5)** |
| [design/objects.md](design/objects.md) | **`#` 对象 / `##` 函数与方法** |
| [design/ai-skill.md](design/ai-skill.md) | **AI 接入 Skill**([`skills/marqdo/`](../skills/marqdo/)) |
| [design/code-vs-comment.md](design/code-vs-comment.md) | 叙述 / 可执行 / 外联 |
@@ -32,6 +35,17 @@
| [design/stdlib.md](design/stdlib.md) | **标准库:内置 + `lib/` + 错误约定** |
| [design/stdlib-i18n.md](design/stdlib-i18n.md) | **标准库中英命名:靠库文件名区分,无 lang 开关** |
| [design/stdlib-modules.md](design/stdlib-modules.md) | **L1:文件/系统/时间/JSON/网络/数学/外联/插件** |
| [design/stdlib-mid.md](design/stdlib-mid.md) | **中层 Mid M1–M6(已落地)** |
| [design/stdlib-mid2.md](design/stdlib-mid2.md) | **中层 Mid2:datetime / url / toml / html / fs++** |
| [design/stdlib-datetime.md](design/stdlib-datetime.md) | **`lib/datetime`(Mid2 M7)** |
| [design/stdlib-url.md](design/stdlib-url.md) | **`lib/url`(Mid2 M7)** |
| [design/stdlib-toml.md](design/stdlib-toml.md) | **`lib/toml`(Mid2 M8)** |
| [design/stdlib-html.md](design/stdlib-html.md) | **`lib/html`(Mid2 M8)** |
| [design/stdlib-fs-mid2.md](design/stdlib-fs-mid2.md) | **`lib/fs` Mid2 M9 加厚** |
| [design/stdlib-stats-log.md](design/stdlib-stats-log.md) | **`lib/stats` + log.fields(Mid2 M10)** |
| [research/stdlib-gaps-after-mid.md](research/stdlib-gaps-after-mid.md) | **Mid 之后缺口盘点**(对照 Python/Go) |
| [roadmap/stdlib-mid.md](roadmap/stdlib-mid.md) | **Mid M1–M6 路线(done)** |
| [roadmap/stdlib-mid2.md](roadmap/stdlib-mid2.md) | **Mid2 M7–M10 路线(规划)** |
| [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** |
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** |
| [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) |
@@ -39,7 +53,11 @@
| [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(文档驱动:单步 / 多步工作簿 + 自写回;废弃 thin TOOL 循环)** |
| [design/ext-agent-plan.md](design/ext-agent-plan.md) | **`## 多步` / `## plan` 锁定设计**(工作簿文件、subtask 执行、修订循环、`step` 默认写回) |
| [design/ext-cli.md](design/ext-cli.md) | **`marqdo ext list/add/remove` 官方扩展安装器** |
| [design/ext-cdn.md](design/ext-cdn.md) | **扩展 CDN(R2 / ext.marqdo.com)与分开发版** |
| [design/ubuntu-ppa.md](design/ubuntu-ppa.md) | **Ubuntu PPA 打包与上传** |
| [design/ext-web.md](design/ext-web.md) | **官方扩展 `ext/web`(页面/库表/绑定/后台;ABI + CLI;设计锁定)** |
| [design/ext-web-go-rewrite.md](design/ext-web-go-rewrite.md) | **`plugins/web` Go 全量重写**(多语言 ABI · 网页制备完备 · anlian 验收) |
| [adr/0004-web-plugin-go.md](adr/0004-web-plugin-go.md) | **Accepted:web 原生插件实现语言为 Go** |
| [research/ext-web-customization-limits.md](research/ext-web-customization-limits.md) | **`ext/web` 定制限制踩坑盘点**(路由/壳 CSS/鉴权/样式/部署) |
| [design/ext-web-customization/](design/ext-web-customization/) | **对应解决设计**(C0–C4:前缀可让出、shell_css、gate、布局…) |
| [design/web-assets-and-images.md](design/web-assets-and-images.md) | **W8:favicon / Head 资源表 / 图片装配**(一次补齐) |
+28
View File
@@ -0,0 +1,28 @@
# ADR 0004:网络拓展库原生实现改为 Go
| | |
|---|---|
| Status | **Accepted** |
| Date | 2026-09-10 |
| Related | [ext-web-go-rewrite.md](../design/ext-web-go-rewrite.md) · [ext-abi.md](../design/ext-abi.md) · [0001-implementation-language.md](0001-implementation-language.md) |
## Context
- Marqdo **宿主/解释器**仍为 Rust(ADR 0001 不变)。
- 官方插件契约是稳定 **C ABI**(`include/marqdo_abi.h`),不绑定 Rust ABI。
- `plugins/web`(Rust/axum)已具备 W0–W8 等能力,但迭代成本高;且需验证多语言插件生态。
- 产品目标:网络拓展库支撑完整网页制备,并以暗恋见君(外接 PostgreSQL + Redis)验收;应用层前后端均为 Marqdo 脚本。
## Decision
1. **重写** `plugins/web` 为 **Go** 共享库(`-buildmode=c-shared`),产物名仍为 `libweb.so` / `web.dll` / `libweb.dylib`。
2. **ABI 全量兼容**(函数名、参数、语义);`ext/web` 作者面默认不动。
3. 施工图:[ext-web-go-rewrite.md](../design/ext-web-go-rewrite.md)。禁止在旧 Rust 插件上继续打补丁演进(ext-web C5)。
4. 其它官方插件(agent / quantum / linalg)**暂不**强制改语言;Go web 作为多语言样板。
## Consequences
- 构建与发版需安装 Go;CI/`marqdo ext add web` 增加 `go build` 回退。
- 根 Cargo workspace 不再包含 `plugins/web` Rust crate(切换完成后)。
- cgo/共享库生命周期与 `shutdown` 需严格测试。
- 金样例 `tests/ext/web-*` 为门禁。
+53
View File
@@ -0,0 +1,53 @@
# ADR 0005:叙述统一的 Markup 映射(粗体即代码 · 斜体即返回 · 形参体推断)
| | |
|---|---|
| Status | **Accepted** |
| Date | 2026-09-13 |
| Related | [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) · [markdown-mapping.md](../design/markdown-mapping.md) · [return-hr-and-code-surface.md](../design/return-hr-and-code-surface.md) · [roadmap/markup-v0.3.md](../roadmap/markup-v0.3.md) |
## Context
- Marqdo 的产品承诺是「代码即文档 / 文档即代码」:`.mq.md` 打开是文章,运行是程序。
- v0.2([markdown-mapping.md](../design/markdown-mapping.md))为消歧做了硬隔离:无标记 = 注释;`*…*` = 语句;`**…**` = 返回;调用必须 `>`;形参必须 `` + `名` ``。
- 该隔离使叙述与程序**视觉割裂**;且与 AI/Markdown 习惯相反(模型偏好用 `**` 强调「要做的事」)。
- 产品方重新审视后,希望合法化如下写法:
```markdown
## 加一函数
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
# main
> 加一函数 37
或者可以直接这么调用**加一函数 37**
```
## Decision
1. 采纳 **Markup 映射 v0.3** 为下一版语言宪法草案,全文见 [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md)。
2. **角色对调**:`**…**` = 代码段(含可省略 `>` 的调用);`*…*` = 返回值。
3. **叙述中的** `` `名` ``:**首次未赋值 = 声明变量**;未使用不报错;**仅当可执行面读取时升为形参**(见设计 §4.4 · §8.2)。不设「提及性」专用语法。
4. **形参默认由函数体/叙述推断**(升参);`` + `名` `` 仅作迁移兼容。
5. **`>` 调用面保留**(可选)。
6. **空返回**用标记而非关键字:推荐 `---` / `***`;显式 `*None*` / `*无*`;整行 `**`;兼容 `****`(设计 §7.2)。
7. **不做 v0.2 双模式兼容**(摸索阶段允许破坏性变更);旧 `.mq.md` 须改写。
8. 金样例门禁:`tests/markup-v03/`;存量 suite 随后迁移。
## Consequences
### Positive
- 叙述与代码共用 Markdown 习惯,文档可读性上升。
- 更贴合 AI 生成粗体「操作」的偏好,降低错用标记。
- 去掉形参表仪式,函数更像「带名字的说明段落」。
### Negative / Risks
- **破坏性**:与 v0.2 金样例、Skill、教程、大量 `lib/`/`ext/` 源码不兼容,必须分波迁移或双模式。
- 段内扫描与形参推断增加解析/语义复杂度——空返回与升参规则已在设计 §7.2 / §8.2 钉死;其余 §12 项用金样例收口。
- view/catalog/LSP 高亮规则需同步。
### Neutral
- `#` / `##` 对象体系、标准库、插件 ABI、关键字最小集不变。
- 输出仍是 `print` / `打印`,不是粗体/斜体。
+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`
+54
View File
@@ -0,0 +1,54 @@
# 方括号标记调用与前置修饰语
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-09-14 |
| 相关 | [call-arguments.md](call-arguments.md) · [collection-access-link.md](collection-access-link.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) |
---
## 1. 动机
无标记时,修饰语+函数名与函数名+实参都是词列,**无法消歧**。消歧标记必须来自 Marqdo 语法,**不能**依赖任一自然语言词法(「的」、形容词位置等)。
## 2. 形状
```text
修饰语… [函数名] 实参…
```
| 例子 | 含义 |
|------|------|
| `[问候] marqdo` | 调用 `问候`,位置实参 |
| `礼貌 [问候] marqdo` | 另加 `礼貌=True` |
| `正式 礼貌 [问候] marqdo` | `正式=True` `礼貌=True` |
| `[结账摘要] 品名="拿铁" 杯数=2` | 仅具名实参 |
| `[问候] ([格式化] `名字`)` | 嵌套:内层整段用 `()` |
旧形保留:`> 问候 …`、`**问候 …**`、`礼貌=True` 显式具名。
## 3. 与取元 / foreach
| 形状 | 语义 |
|------|------|
| `[X](Y)`(`]` 后**紧邻** `(`) | 取元 |
| `[X]`(`]` 后不是 `(`) | 函数名标记 |
| `- [X](Y)` | foreach |
## 4. 修饰语绑定
- `[` 前按空白切开;每段为标识(可 `` `名` ``)。
- 降为 `Named(名, Bool(true))`,再与 `]` 后实参合并。
- 与显式同名具名冲突 → 诊断。
- **核心不剥语言词缀**;形参叫 `礼貌` 则写 `礼貌 [问候]`。
## 5. AST
`CallExpr.pre_modifiers: Vec<String>`;求值/字节码在绑参前展开。
## 6. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿并落地 |
+17 -10
View File
@@ -2,9 +2,9 @@
| | |
|---|---|
| 状态 | 已定(v0.1 增补) |
| 状态 | 已定(v0.1 增补;2026-09-14:方括号标记调用) |
| 日期 | 2026-08-07 |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) |
| 相关 | [markdown-mapping.md](markdown-mapping.md) · [keywords.md](keywords.md) · [module-namespace.md](module-namespace.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md) |
---
@@ -16,20 +16,26 @@
|------|------|------|
| **具名**(保留) | `> 问候 谁=Marqdo` | `名=值`;值可含空格(至下一 `名=`) |
| **位置**(新增) | `> 问候 Marqdo` | 按形参声明顺序绑定 |
| **方括号标记**(增补) | `礼貌 [问候] Marqdo` | `[函数名]` 消歧;`[` 前裸词 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md) |
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。具名不可绑定同一形参两次;位置实参不得出现在「已出现具名实参」之后(对齐常见「位置在前、关键字在后」习惯)。
二者可混用:位置实参按「尚未被具名绑定的形参」从左到右填充。具名不可绑定同一形参两次;位置实参不得出现在「已出现具名实参」之后(对齐常见「位置在前、关键字在后」习惯)。前置修饰语与显式同名具名冲突则报错。
---
## 2. 文法(调用尾部)
```
call_tail ::= callee arg*
call_tail ::= bracket_call | classic_call
bracket_call ::= modifier* '[' callee ']' arg*
classic_call ::= callee arg*
arg ::= named | positional
named ::= ident '=' value
positional ::= value_token
positional ::= value_token | '(' call_tail ')'
modifier ::= ident # 展开为 ident=True;核心不剥语言词缀
```
- `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记(见 [collection-access-link.md](collection-access-link.md))。
- 嵌套调用:把内层整段放进 `()`,例如 `[问候] ([格式化] "x")`。
- `value`(具名右侧):可含空格与 `` `var` `` 插值,直到下一个 `ident=` 边界。
- `value_token`(位置):空白分隔的一个词法单元——数字、`` `名` ``、标识/文本词;**不含空格**。多词字符串请用具名,例如 `> print text=Hello World!`。
- 实参值中 `` `变量` `` 后**紧跟** `[^…]` 时按**脚注取元**解析(可链式),而非文本:`> print text=苹果单价:`水果价格`[^苹果]`、`> print text=`订单`[^2][^品名]`。
@@ -44,13 +50,14 @@ positional ::= value_token
## 3. 绑定算法
1. 收集具名 → 映射;冲突则报错。
2. 按函数形参表顺序:若具名已提供则用之,否则取下一个位置实参。
3. 位置实参有余、或必填形参仍缺 → 报错(内置 `input` 的 `prompt` 可缺省)。
4. 用户函数:额外具名键仍写入调用环境(便于扩展);位置实参不可超过形参数目。
1. 将前置修饰语展开为 `名=True` 具名(与显式具名冲突则报错)。
2. 收集具名 → 映射;冲突则报错。
3. 按函数形参表顺序:若具名已提供则用之,否则取下一个位置实参。
4. 位置实参有余、或必填形参仍缺 → 报错(内置 `input` 的 `prompt` 可缺省)。
5. 用户函数:额外具名键仍写入调用环境(便于扩展);位置实参不可超过形参数目。
---
## 4. 金样例
见 `tests/structure/positional-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。
见 `tests/structure/positional-call.mq.md`、`tests/structure/bracket-call.mq.md`、`tests/structure/ns/`(点号路径 / `use`)与 `tests/structure/import/`(导入解析)。
+119
View File
@@ -0,0 +1,119 @@
# 代码即文档 · 叙述面摩擦(v0.3 实测)
| | |
|---|---|
| 状态 | **Done** |
| 日期 | 2026-09-14 |
| 触发 | `examples/code-as-docs/index.mq.md` 试跑 |
| 宪法 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) |
| 路线 | [code-as-docs-gaps.md](../roadmap/code-as-docs-gaps.md) |
---
## 0. 原则
修复必须同时服务:
1. **代码即文档**:人读 Markdown 时自然段落、分隔线、强调不应被误伤。
2. **适配 LLM 输出**:模型习惯写 `---` 分段、`**加粗强调**`、`0.85` 小数、`` map[^`key`] `` 动态键——运行时应尽量「写出来就能跑」。
3. **可执行标记仍清晰**:真正的赋值 / 调用 / 返回不被误判成装饰。
---
## 1. 四个问题(实测)
### G1 — 模块级 `---` 被当成结构错误
| | |
|---|---|
| 现象 | 文件标题段落后写 Markdown 分隔线 `---`,报 `expected heading … got: ---` |
| 根因 | 词法上整行 `-`/`*` 为 Code;旧实现把函数体内 `---` 当收束,模块顶却当非法。现统一为叙述跳过 |
| 人/LLM 期望 | 任意处 `---` = GFM thematic break = **叙述噪音** |
| 决议 | **处处** frame 行 skip;副作用收束用 `*None*` / `**` / `****`(返回即结束函数体解析) |
### G2 — 叙述里的 `**强调**` / `*斜体强调*` 被当成代码/返回
| | |
|---|---|
| 现象 | 「本文件既是**说明**也是**程序**」→ 粗体 `说明` 不是赋值/调用,解析失败;`*only*` 类英文强调升成返回/`only` 变量 |
| 根因 | v0.3 叙述扫描凡 `**…**` / `*…*` 一律可执行([prose.rs](../../src/parse/prose.rs));Skill 曾禁止强调,但与 LLM/Markdown 习惯冲突 |
| 人/LLM 期望 | 装饰性强调可出现;**像代码的**粗体/斜体仍执行 |
| 决议 | **形状启发式**(见 §2):像代码则执行,否则当作叙述装饰(不产生 Stmt,不升参) |
### G3 — 小数面量 `0.85` 不可用
| | |
|---|---|
| 现象 | `**x = 0.85**` → `trailing input: ".85"`;`28 * 0.85` 解析错乱;即便进到求值,`*` 仍只接受 int |
| 根因 | 表达式主词只吃整数字面量(`Literal` 无 `Num`);运行时已有 `Value::Num`,二元运算未接浮点 |
| 人/LLM 期望 | `0.85`、`3.14`、`折扣=0.85` 可写可算 |
| 决议 | 解析 `数字.数字` → `Literal::Num`;`*` `/` `+` `-` 及比较在 `Int`/`Num` 间提升(与已有 `cmp_ord` 一致) |
### G4 — 动态脚注键 `` 菜单[^`名`] ``
| | |
|---|---|
| 现象 | `` 菜单[^`名`] `` → `missing map key ``名`` `(把字面 `` `名` `` 当键,或解析失败) |
| 根因 | `[^label]` 的 label 仅为**静态字符串**;AST `Expr::Index { label: String }` 无变量槽 |
| 人/LLM 期望 | 表/映射按变量取键:`` `菜单`[^`品名`] `` 或 `菜单[^`品名`]` |
| 决议 | 支持 `` [^`ident`] `` → 运行时用变量值作键(文本化后走现有 footnote get);静态 `[^拿铁]` 不变 |
---
## 2. 粗体/斜体「像代码」启发式
### 粗体 `**inner**` → 可执行,当且仅当
满足任一:
- 含 `=`(赋值 / 命名参数调用);或
- 以 `>` 开头(显式调用);或
- 含运算符 / 索引 / 调用形:`+ - * / ( ) [ ]`;或
- 空白分词 ≥2 段,且其后段含数字面量、引号串、或 `=`(如 `**加一 37**`、`**print text="hi"**`)
否则(如 `**说明**`、`**代码即文档**`)→ **装饰,忽略**。
### 斜体 `*inner*` → 返回,当且仅当
满足任一:
- 空 / `None` / `无` / `空` / bool 字面;或
- 以 `>` 开头;或
- 含 `=` 或运算符 / 索引;或
- **整行**仅为 `*…*`(含缩进)——整行返回 `*总额*` / `*n*`;或
- 行内且前方紧邻「返回」二字(叙述「接着返回*n*」)
否则行内简单词(如 `*only*`、`*named*`)→ **装饰,忽略**。
> 整行 `*n*` 仍是返回;行内「返回*n*。」仍是返回。英文强调词在句中被忽略。
---
## 3. 非目标
- 不恢复 v0.2 双模式
- 不引入 `if`/`return` 关键字
- 不把任意 `**任意自然语言句子**` 都当代码(必须过 §2)
- 动态键第一期只做 `` [^`ident`] ``,不做完整表达式 `[^a+b]`
---
## 4. 验收
| 用例 | 期望 |
|------|------|
| 顶层段落之间的 `---` | 可解析、可运行 |
| 「既是**说明**也是**程序**」 | 可解析;无 Stmt |
| `**应付 = 原价 * 0.85**` / `折扣`=0.85 | 数值正确(浮点) |
| `` **价 = 菜单[^`名`]** ``(`名` 已绑定) | 取到对应价 |
| `examples/code-as-docs/index.mq.md` | 用回浮点折扣与动态键后仍绿 |
| 既有 `tests/markup-v03/*` 与 gold | 不回归 |
---
## 5. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿:四缝 + 启发式 + 验收 |
| 2026-09-14 | 落地:G1–G4 实现 + 金样;顶层 Comment 引言 skip |
+16 -13
View File
@@ -2,8 +2,12 @@
| | |
|---|---|
| 状态 | 与 mapping v0.1 / keywords 对齐(成段注释) |
| 日期 | 2026-08-04 |
| 状态 | 与 mapping **v0.3** 对齐(现行运行时) |
| 日期 | 2026-09-14 |
| 取代 | 本文曾按 v0.2(`*语句*` / `**返回**`)叙述;旧对照见 [markdown-mapping.md](markdown-mapping.md) |
| 相关 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) §4 |
「Markup」在此仓库 = Marqdo **把 Markdown 标记映射成语法** 的那一层,不是另一个语言。
---
@@ -11,19 +15,18 @@
| 层 | 形态 | 角色 |
|----|------|------|
| **叙述面** | 成段注释(空行分段) | 注释;段内任意标记无语义 |
| **Marqdo 可执行面** | 结构标记 + `*语句*` + `**返回**` | 本语言程序 |
| **叙述面** | 普通段落 | 注释;行内 `` `名` `` 可声明/引用;装饰性 `**强调**` / `*斜体*` 不执行 |
| **Marqdo 可执行面** | 结构标记 + **`**代码**`** + **`*返回*`** | 本语言程序 |
| **外联面** | ` ```lang ` | 其它语言(FFI) |
输出属于可执行面里的**函数调用**(`> print …`),见 [keywords.md](keywords.md)。
输出属于可执行面里的**函数调用**(`> print …` / `**print …**`),见 [keywords.md](keywords.md)。
### 成段注释
- 以**空行**划分段落。
- 段首行:首字符非标记 → 注释。
- 段内续行:一律注释(即使以 `` ` `` / `-` / `**` 等开头)。
- **例外**:整行仅为 `**expr**`(或 `****`)→ Marqdo **返回**;`**强调**` 后还有文字 → 仍是叙述注释。
- 叙述段与可执行代码之间**必须空一行**,否则 `> print` 等会被吞进注释段。
- 段首行:首字符非标记 → 注释段;段内续行一律叙述(即使以 `` ` `` / `-` 开头)。
- 段内仍扫描行内可执行位:`` `名` ``、代码形 `**…**`、返回形 `*…*`。
- 叙述段与独立结构行(`>` `#`)之间**建议空一行**,否则 `> print` 可能被吞进注释段。
---
@@ -31,8 +34,8 @@
| 标记/形式 | 角色 | 是否架构级 |
|-----------|------|------------|
| `*…*` | 程序语句 | 是 |
| `**…**` | 返回值 | 是 |
| `****` / 空粗体 | 空返回 + 结束函数体 | 是 |
| `**…**` | 代码(赋值 / 调用 / 表达式语句) | 是 |
| `*…*` | 返回值(整行、`返回*n*`、或表达式形) | 是 |
| `****` / 整行 `**` / `*None*` | 空返回 + 结束函数体 | 是 |
| `> print …` | 打印副作用 | 否(内置函数) |
| 函数体 `---` / `***` | 结束函数体 | 是(边界) |
| 函数体 `---` / `***` | 叙述分隔(跳过,**不**结束函数体) | 否 |
+64
View File
@@ -0,0 +1,64 @@
# 集合取元:GFM 链接形
| | |
|---|---|
| 状态 | **Active(运行时)** |
| 日期 | 2026-09-14 |
| 相关 | [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [code-as-docs-gaps.md](code-as-docs-gaps.md) |
---
## 1. 决议
表达式取元的**主语法**为 Markdown 链接外形,与 foreach 同构:
| 角色 | 写法 |
|------|------|
| **取元(表达式)** | `[键](集合)` |
| **遍历(语句)** | `- [项](集合)`(不变) |
| **脚注取元(过渡)** | `` 集合[^键] `` 仍解析,新代码勿写 |
心智:**方括号 = 取出的名字,圆括号 = 从哪取。**
```markdown
**价 = [拿铁](菜单)**
**价 = [`名`](菜单)**
**第一 = [1](篮子)**
- [行](今日订单)
**名 = [品名](行)**
```
## 2. 细则
| 写法 | 语义 |
|------|------|
| `[拿铁](菜单)` | 静态键;`菜单` 为变量(粗体/斜体内) |
| `` [`名`](菜单) `` | 动态键(求值 `名` 再作键) |
| `[1](篮子)` | List **1-based** 下标(同脚注约定) |
| `[1]([苹果](货架))` | 嵌套链式 |
与 `- [项](集合)` 消歧:仅 **表达式位置** 的 `[…](…)` 为取元;`-` 行头仍为 foreach。
## 3. 迁移
`` `菜单`[^拿铁] `` / `菜单[^拿铁]` → `[拿铁](菜单)`(**基与键左右对调**)。
| 区域 | 约定 |
|------|------|
| 新代码 / examples / public | **只用**链接形 |
| `tests/structure/footnote*` · `interp-footnote*` | 脚注兼容门禁(保留) |
| 其余 structure / ext / lib 金样 | 已迁链接形 |
脚注路径保留至另行决定移除之日;Skill / 教程 / 新示例只用链接形。
## 4. 非目标
- 点号 map 访问、`在`、箭头取元、`(键)[集合]`
- 循环语法糖(`←` / `in` / 自然语言)
## 5. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿并落地主语法 |
+47
View File
@@ -0,0 +1,47 @@
# 核心表面清单(core-surface)
| | |
|---|---|
| 状态 | **Accepted · 核心语法封闭集合(CI 守卫锁定)** |
| 日期 | 2026-09-22 |
| 守卫 | `tests/core_surface.rs` ⇄ `src/parse/mod.rs` `CORE_CONSTRUCTS`(改动任一侧不同步 → CI 红) |
| 相关 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)(语义宪法)· [layers.md](layers.md)(准入戒律)· [three-problems.md](../roadmap/three-problems.md) 问题一 · [three-problems-plan.md](../roadmap/three-problems-plan.md) T1.1/T1.3 |
> **戒律总纲**:核心标记是**封闭集合**(约 19 个构造)。新增任何一行必须走 ADR(见 [layers.md](layers.md) 准入戒律)并回答「为什么现有标记不够」;生态需求的默认答案是**进 ext**。本表 id 列与守卫测试强一致:改表不同步 `CORE_CONSTRUCTS`(或反之)、样例文件缺失,一律 CI 红。
## 1. 行构造
| id | 外形 | 语义 | 戒律 | 样例 |
|----|------|------|------|------|
| `narrative` | 无标记文字 | 叙述(注释) | 段落内延续到空行;**默认安全**——永远不存在「叙述被执行」的路径 | `tests/markup-v03/soft-emphasis.mq.md` |
| `blank` | 空行 | 段落边界 | 叙述分段的唯一手段;不得被赋予其它语义 | `tests/markup-v03/inc-prose.mq.md` |
| `heading-unit` | `#` / `##` | 对象 / 函数单元 | 标题即单元边界,按深度嵌套;正文禁止用 `##` 做版式(会变成函数) | `tests/markup-v03/decl-ident-only.mq.md` |
| `call-line` | `>` | 调用行 | 输出等副作用 = **普通函数**,不是架构标记 | `tests/markup-v03/dual-call.mq.md` |
| `branch-list` | 体内 `1.` 递增 | 分支 | 自 `1.` 起序号递增构成一个判断;重出 `1.` 开新判断;`N. *` = else;**不是所有有序列表都是 if** | `tests/markup-v03/greet-default.mq.md` |
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [项](集合)` | `tests/structure/loop.mq.md` |
| `param` | `` + `名` `` | 形参(兼容形) | 首选叙述 `` `名` `` 升参(宪法 §8);`+` 形仅兼容保留 | `tests/markup-v03/greet-default.mq.md` |
| `table` | GFM 表 | 集合 | 几何即类型([tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md));**绑定 = 数据,未绑定 = 文档表** | `tests/structure/collection.mq.md` |
| `fence` | ` ```lang ` | 外联 | 语言块原样外联,不进 Marqdo 语义 | `tests/lib/foreign-python.mq.md` |
| `hr` | 单行 `---` 或 `***` | 叙述分隔 | **不收束函数**(返回才收束) | `tests/markup-v03/module-hr.mq.md` |
| `writeback` | `<!-- marqdo-out … -->` | 持久化输出 | 只读回放,不执行 | `tests/lib/writeback-get.mq.md` |
## 2. 内联标记
| id | 外形 | 语义 | 戒律 | 样例 |
|----|------|------|------|------|
| `ident` | `` `名` `` | 声明 / 引用 | 首次未赋值 = 声明;叙述与程序共用同一视觉习惯 | `tests/markup-v03/decl-ident-only.mq.md` |
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 只有粗体进入执行;判别序:赋值 → 调用 → 表达式 | `tests/markup-v03/multi-bold.mq.md` |
| `italic-return` | `*…*` | 返回 | 改变控制流(**返回是架构**);返回即结束函数体 | `tests/markup-v03/inc-prose.mq.md` |
| `empty-return` | `*None*` / `****` | 空返回 | 返回 `None` 并结束函数体 | `tests/markup-v03/empty-return-none.mq.md` |
| `link-index` | `[键](集合)` | 取元 / foreach | **主取元语法**;与 bracket-call 靠 `]` 后是否紧邻 `(` 消歧 | `tests/lib/table-collections.mq.md` |
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;与 link-index 消歧同上 | `tests/structure/bracket-call.mq.md` |
| `footnote-index` | `集合[^键]` | 过渡取元 | **仅兼容**;新代码一律写 link-index | `tests/structure/footnote-index.mq.md` |
| `soft-emphasis` | `*仅*` / `**说明**` | 忽略 | 非代码形强调**不执行**——默认安全的关键消歧规则 | `tests/markup-v03/soft-emphasis.mq.md` |
## 3. 词法大类(LineKind,`src/lex/mod.rs`)
行级入口只有四个大类:`Blank` / `Comment`(叙述段落,含软强调与行内 `` `名` ``)/ `Writeback` / `Code`(`# * > + - | ~ $` 或数字开头)。本清单第 1 节的行构造是在 `Code`(及 `Comment`/`Writeback`)内部的**语义细分**;第 2 节内联标记由 `src/parse/prose.rs` 行内扫描产出。两层合起来 = 核心表面全集。
## 4. 范围外(进 Language 层,但不在本守卫)
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 扩表。
+9 -18
View File
@@ -16,27 +16,17 @@
tests/
README.md
gold.rs # 集成测试入口
structure/ # 代码基础结构(Markup 架构)
hello.mq.md
nested-call.mq.md
positional-call.mq.md
branch.mq.md
loop.mq.md
collection.mq.md
import/
main.mq.md
utils.mq.md
ns/
helpers.mq.md
path3.mq.md
use.mq.md
structure/ # 代码基础结构(Markup 架构 · v0.2)
…
keywords/ # 关键字与内置名
print.mq.md
bool-logic.mq.md
…
markup-v03/ # Markup 映射 v0.3 草案金样例(实现前 ignore)
README.md
inc-prose.mq.md
…
ext/
agent-run-live.mq.md
…
errors/ # 期望失败(诊断文案稳定后再加金样例)
ns-instance-method.mq.md
…
```
@@ -51,6 +41,7 @@ tests/
|------|--------|----------|
| **structure** | `#`/`##`、形参 `+`、`1.` 分支、`-` 循环、表、导入、点号路径 / `use`、位置/具名实参 | 关键字边角 |
| **keywords** | `True`/`False`/`None`、`and`/`or`/`not`、`print`/`input` 约定 | 复杂控制流(可极简) |
| **markup-v03** | v0.3:叙述声明、粗体代码、斜体返回、升参、空返回、双调用面(见 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)) | 在 `--markup v0.3` 落地前 `#[ignore]` |
| **errors** | 未定义名、实参错误、语法错误的诊断 | 成功路径 |
未单独建夹、但应覆盖的其它测试(`src/**` 单测或日后 `tests/runtime/`):
+1 -1
View File
@@ -85,7 +85,7 @@ cargo build -p marqdo_plugin_agent
- Demo (ABI v1): `demo_add`, `demo_echo` — [`tests/lib/plugin-demo.mq.md`](../../tests/lib/plugin-demo.mq.md).
- Agent (ABI v2): … **OKF agent-kb** …
- Web (ABI v2): HTTP listen + SQLite + page render (`web_listen`, `web_render`, `web_db_*`) — [`plugins/web`](../../plugins/web); used by [`ext/web/web.mq.md`](../../ext/web/web.mq.md). Lookup: `plugin.native_path name=web` / `MARQDO_WEB_PLUGIN` / `marqdo ext add web`.
- Web (ABI v2): HTTP listen + SQLite/Postgres + page render (`web_listen`, `web_render`, `web_db_*`, …) — [`plugins/web`](../../plugins/web)(**Go 全量重写**,见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md) · [ADR 0004](../adr/0004-web-plugin-go.md));作者面 [`ext/web/web.mq.md`](../../ext/web/web.mq.md)。Lookup: `plugin.native_path name=web` / `MARQDO_WEB_PLUGIN` / `marqdo ext add web`.
## Layering
+15
View File
@@ -180,11 +180,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):
| 参数 | 说明 |
+66
View File
@@ -0,0 +1,66 @@
# Extension CDN (Cloudflare R2 → https://ext.marqdo.com)
| | |
|---|---|
| Status | **Accepted** — download prefer CDN; upload via `scripts/upload-ext-r2.py` |
| Date | 2026-09-17 |
| Related | [ext-cli.md](ext-cli.md) · [marqdo-release](../../.cursor/skills/marqdo-release/SKILL.md) |
## Why
CLI (语法解释器) and official **extension packs** (`ext/` L1 + native plugins) update on different cadences. Users behind unstable GitHub links should get packs from a stable object store first.
## Public URL layout
Bucket: `marqdo` · Custom domain: **https://ext.marqdo.com**
| Key | Meaning |
|-----|---------|
| `v{VER}/marqdo-{VER}-ext.zip` | L1 sources |
| `v{VER}/marqdo-{VER}-native-{triple}.zip` | Prebuilt plugins |
| `v{VER}/VERSION` | Pack SemVer echo |
| `latest/VERSION` | Recommended pack SemVer (plain text) |
| `latest/marqdo-…zip` | Same assets mirrored for convenience |
`{VER}` is the **extension pack** version (`ext/VERSION`), which **may differ** from CLI `Cargo.toml` version.
## Client download order (`marqdo ext add`)
1. `MARQDO_EXT_DOWNLOAD_BASE` (optional override)
2. **CDN** `https://ext.marqdo.com/v{VER}/…` (override host with `MARQDO_EXT_CDN`)
3. GitHub Releases
4. `https://proxy.cflmy.top/github.com/…`
Pack SemVer resolution (`release_version()`):
1. `MARQDO_EXT_VERSION`
2. CDN `GET …/latest/VERSION` (short timeout)
3. Embedded `ext/VERSION` at build time
4. CLI `CARGO_PKG_VERSION`
## Separate ext release (no CLI bump)
1. Bump `ext/VERSION` (e.g. `1.0.3`) — leave root `Cargo.toml` alone if CLI unchanged.
2. Build native zips (CI Linux/Windows jobs or local `scripts/build-web-plugin.sh` + cargo plugins).
3. Package `marqdo-{VER}-ext.zip` and `marqdo-{VER}-native-*.zip`.
4. Upload **both**:
- R2: `python3 scripts/upload-ext-r2.py --version VER --from-dir dist/`
- GitHub: attach to a GitHub Release (tag `ext-vVER` **or** reuse latest CLI release assets)
5. Confirm `https://ext.marqdo.com/latest/VERSION` and a sample zip URL return 200.
## Full product release (CLI + ext)
Keep `ext/VERSION` equal to (or compatible with) CLI SemVer unless documenting a deliberate skew. CI still publishes GitHub assets; **after** CI green, run `upload-ext-r2.py` so CDN is populated (or add a CI step with R2 secrets).
## Credentials
| Where | What |
|-------|------|
| Local | `~/.marqdo/r2.env` (`chmod 600`) — see `.env.r2.example` |
| CI (optional) | GitHub Actions secrets: `R2_ACCESS_KEY_ID`, `R2_SECRET_ACCESS_KEY`, `R2_ENDPOINT`, `R2_BUCKET` |
**Never** commit Account API tokens or S3 secret keys. If a token was pasted into chat, **rotate** it in the Cloudflare dashboard.
## Object ACL
Custom domain public reads require the bucket/objects to be publicly readable (R2 public bucket / r2.dev / custom domain). Uploads use S3 API credentials; downloads by `ext add` are anonymous HTTPS GETs.
+11 -3
View File
@@ -35,9 +35,11 @@ and get both L1 `.mq.md` **and** the matching native plugin (`.dll` / `.so`) **w
### Resolution order (`add` with native crate)
1. Local artifact (`MARQDO_*_PLUGIN`, `target/{debug,release}`, beside `marqdo`, `MARQDO_EXT_SOURCE/native`, …)
1. Local artifact (`MARQDO_*_PLUGIN`, `plugins/web/build` for **web**, `target/{debug,release}`, beside `marqdo`, `MARQDO_EXT_SOURCE/native`, …)
2. **Download** `marqdo-{VER}-native-{target}.zip` from the GitHub Release for this CLI version → cache under `~/.marqdo/cache/`
3. If Rust/`cargo` is available → `cargo build -p marqdo_plugin_*` (developers)
3. Local rebuild fallback:
- **web** → `./scripts/build-web-plugin.sh` (Go c-shared `libweb`; requires Go 1.22+ / cgo)
- other plugins → `cargo build -p marqdo_plugin_*` when Rust/`cargo` is available
4. Else fail with a clear message pointing at the Release assets
L1 sources:
@@ -49,10 +51,16 @@ L1 sources:
| Variable | Meaning |
|----------|---------|
| `MARQDO_EXT_VERSION` | Override SemVer used for Release asset names (default: CLI `CARGO_PKG_VERSION`) |
| `MARQDO_EXT_VERSION` | Override **extension pack** SemVer (default: CDN `latest/VERSION` → embedded `ext/VERSION` → CLI version) |
| `MARQDO_EXT_CDN` | Public CDN base (default `https://ext.marqdo.com`) |
| `MARQDO_EXT_NO_DOWNLOAD=1` | Never hit the network (CI / air-gap); local/cargo only |
| `MARQDO_EXT_DOWNLOAD_BASE` | Optional extra base tried **before** CDN |
| `MARQDO_WEB_PLUGIN` / `MARQDO_AGENT_PLUGIN` / `MARQDO_QUANTUM_PLUGIN` | Explicit native path |
Download order for each Release asset: `MARQDO_EXT_DOWNLOAD_BASE` → **CDN `ext.marqdo.com`** → `github.com` → **`proxy.cflmy.top`**. Connect timeout 20s; read timeout 10min.
See [ext-cdn.md](ext-cdn.md) for R2 layout, separate ext releases, and `scripts/upload-ext-r2.py`.
Windows Release **zip** also ships `ext/` + `ext/native/*.dll` next to `marqdo.exe` so a portable unzip works offline after one download.
## Source for `add` (developers)
+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` |
| `auth` | `鉴权` | 角色名或 `none` |
正文在请求时执行;返回值按 `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 为准。
+19
View File
@@ -0,0 +1,19 @@
# Collaborative document MVP
| | |
|---|---|
| 状态 | **Accepted · MVP (LWW)** |
| 日期 | 2026-09-17 |
## Approach
Not a full CRDT. Peers sync plain text over `route_ws mode=room` with:
- Client → server: `DOC\\t<body>`
- Server fan-out (existing G-WS1/2)
- Apply remote if body ≠ local; `applying` flag suppresses echo
- Presence JSON on `room.presence` (`presence=True`)
## Demo
`examples/web-collab-doc/` — open two browsers on the same room.
+454
View File
@@ -0,0 +1,454 @@
# `plugins/web` Go 全量重写(多语言 ABI 生态 · 网页制备完备)
| | |
|---|---|
| 状态 | **Completed(W-G0…W-G14 · v0.4.0)** |
| 日期 | 2026-09-10 |
| 相关 | [ext-web.md](ext-web.md) · [ext-web-net.md](ext-web-net.md) · [web-net-capabilities.md](web-net-capabilities.md) · [ext-web-drivers.md](ext-web-drivers.md) · [web-assets-and-images.md](web-assets-and-images.md) · [ext-hosting-fill.md](ext-hosting-fill.md) · [ext-abi.md](ext-abi.md) · [ext-cli.md](ext-cli.md) · [web-asgi-servers-and-marqdo.md](web-asgi-servers-and-marqdo.md) |
| 实现目录 | `plugins/web/`(**Go module**;产物仍为 `libweb.so` / `web.dll` / `libweb.dylib`) |
| 作者面 | `ext/web/web.mq.md` · `ext/web/网页.mq.md`(**ABI 名与方法面保持兼容**;非另起一套 API) |
| 验收应用 | 工作区 `anlian`(暗恋见君):用 Marqdo 前后端脚本完整重写;**PostgreSQL + Redis 外接** |
---
## 0. 一句话
用 **Go** 重写官方网络拓展库原生层(`plugins/web`),在 **C ABI v2 全量兼容** 前提下提供「网页制备」所需的全部服务端能力;`ext/web` 继续用 GFM 表 + `#` 类做作者面;应用(含暗恋见君)的前后端脚本全部用 Marqdo 书写。此举同时验证 **多语言 ABI 插件生态**(首个非 Rust 官方插件)。
**不是**最小 hello 插件;**不是**在旧 Rust 代码上打补丁(对齐 [ext-web.md](ext-web.md) **C5**)。
---
## 1. 动机与目标
### 1.1 为何重写
| 动机 | 说明 |
|------|------|
| 开发/编译节奏 | Rust 插件迭代慢,网络域能力长期「半成品感」来自堆叠依赖与慢反馈,而非语言绝对性能 |
| 多语言生态 | ABI 已是稳定 C 契约;需要第一个 **Go** 官方插件证明「宿主 Rust ≠ 插件必须 Rust」 |
| 网页制备完备 | 目标是支持 **完整动态站点制备**(装配、CRUD、鉴权、实时、上传、SEO、代理、驱动…),并以真实论坛项目验收 |
| 性能与拉起 | Go `net/http` 生态成熟、单二进制友好;论坛级 IO 密集负载下足够「极致可用」 |
### 1.2 成功标准(全部满足才算完成)
1. **ABI 全量对等**:下文 §5 列出的每一个已注册 `web_*` 符号,参数 CSV、JSON 形、语义与现网 gold 一致(中英参数别名保留)。
2. **作者面可用**:现有 `ext/web` 示例与 `tests/ext/web-*`(含 live-server)在换 Go `.so` 后通过;无需作者改业务脚本(除非文档标明的 **G 增强**)。
3. **网页制备完备**:单站点可完成页面装配、样式/头/图、库表、表单、路由、中间件、鉴权/RBAC、上传下载、SEO/RSS/sitemap、WS、缓存、对象存储、反代、invoke——即 W0–W8 + P3 + C0–C4 + H1/H2 能力面。
4. **驱动外接**:`postgres://`、`redis://`、`s3://` 为正式一等能力(与 [ext-web-drivers.md](ext-web-drivers.md) 一致);SQLite / memory / file 仍支持本地与测试。
5. **暗恋见君可写完**:用 Marqdo 后端脚本 + 浏览器 WASM 前端脚本重写 anlian 核心模块(见 §8);运行时仅依赖 `marqdo` + `libweb` + **外接 PostgreSQL + Redis**(可选 S3/RustFS)。
6. **安装路径不变**:`marqdo ext add web`、`plugin.native_path name=web`、`MARQDO_WEB_PLUGIN`、产物文件名 `libweb.so` 等与 [ext-cli.md](ext-cli.md) 兼容。
### 1.3 非目标
| 非目标 | 说明 |
|--------|------|
| 改 Marqdo 核心语法 | 仍遵守 ext-web **C1** |
| 把服务器搬进浏览器 WASM | 仍遵守 ADR 0002 |
| 进程内 TLS | HTTPS 由反代;`cookie_secure` 保留 |
| 第三方插件市场 | 仍无 registry |
| 把论坛业务写进 Go 插件 | 帖子/新闻/聊天室规则在 `.mq.md`;插件只提供原语 |
| 强制嵌入式替代 PG/Redis | 本项目明确 **允许并依赖外接** PG/Redis |
---
## 2. 分层架构(锁定)
```text
┌──────────────────────────────────────────────────────────────────┐
│ 应用(anlian / 任意站点) │
│ · 后端 .mq.md:路由、业务、装配、invoke 处理函数 │
│ · 前端 .mq.md:WASM + lib/browser(作者零业务 JS) │
└────────────────────────────┬─────────────────────────────────────┘
│ import web / 网页
┌────────────────────────────▼─────────────────────────────────────┐
│ ext/web(L1 · Marqdo) │
│ # page # db # app # form # auth # cache # storage # media # ws │
│ make_style / make_head / make_images / client_embed … │
└────────────────────────────┬─────────────────────────────────────┘
│ lib/plugin → dlopen
┌────────────────────────────▼─────────────────────────────────────┐
│ plugins/web(L0 · Go · C ABI v2) ← 本文件重写对象 │
│ net/http + 驱动适配 + HTML 装配 + WS hub + 中间件 … │
└──────────┬─────────────────┬─────────────────┬───────────────────┘
│ │ │
PostgreSQL Redis S3/MinIO/RustFS
(外接) (外接) (可选外接)
```
| 层 | 语言 | 职责 |
|----|------|------|
| 应用脚本 | Marqdo | 前后端业务、页面表、领域模型 |
| `ext/web` | Marqdo | 双语作者 API;禁止直接 `host_*` |
| `plugins/web` | **Go** | 全部 `web_*` ABI;高性能网络与驱动 |
| `lib/net` | Marqdo + Rust host | **仅**客户端 HTTP / cookie / multipart / markdown **解析**;不进本重写范围(边界不变) |
| 宿主 | Rust | `dlopen`、JSON Value、`host_query`(`entry_dir` / `call_lib_path` …) |
---
## 3. 硬约束(继承 + 本重写追加)
### 3.1 继承 ext-web C1–C7
| ID | 约束 |
|----|------|
| C1 | 不为 web 改核心语法 |
| C2 | 作者面禁止 json 袋胶水拼装页面 |
| C3 | 中英 API 分文件;禁止混排 |
| C4 | 首页 `index.mq.md`;组件可拆 |
| C5 | **禁止在旧 Rust 插件上打补丁演进**;清空/替换后用 Go 重写 |
| C6 | `# db` 完整 CRUD;`select`/`查询`;admin 与表单共用写库 API |
| C7 | 表单字段+规则;**写库前服务端校验** |
### 3.2 本重写追加(G 系列)
| ID | 约束 |
|----|------|
| **G1** | 产物仍为 C ABI v2;`MARQDO_ABI_VERSION = 2`;导出符号名与 [include/marqdo_abi.h](../../include/marqdo_abi.h) 一致 |
| **G2** | **ABI 函数名与参数名向后兼容**:§5 清单中每个 `web_*` 必须注册;参数 CSV 与现 Rust 插件一致(含中文别名) |
| **G3** | Go 使用 `-buildmode=c-shared`;**禁止**把 Go runtime 假设成唯一线程——跨 FFI 调用必须可重入或明确串行化文档 |
| **G4** | `marqdo_plugin_shutdown` 必须停止 HTTP/WS、关闭 DB/Redis 连接、释放 hub |
| **G5** | 字符串跨界:成功时 `*out_json` / 失败时 `*err_msg` 必须用 **host `alloc`** 分配(与现插件相同),由宿主 `free` |
| **G6** | 相对路径(sqlite 文件、静态目录、上传根)一律相对 `host_query("entry_dir")` |
| **G7** | 多语言样板:仓库内保留可复用的 Go ABI 脚手架注释/包结构,供后续其它语言插件参考 |
| **G8** | 金样例不过 = 未完成;切换默认 `libweb` 到 Go 后,既有 `tests/ext/web-*` 必须绿 |
---
## 4. 技术选型(Go)
| 能力 | 选型 | 备注 |
|------|------|------|
| HTTP 服务器 | 标准库 `net/http` | 路由可用轻量自研 mux 或 `chi`/`http.ServeMux`(Go 1.22+ 模式) |
| 中间件 | 自研链式 `func(http.Handler) http.Handler` | 对等 CORS / 安全头 / gzip / body limit / access_log / cache-control |
| WebSocket | `gorilla/websocket` 或 `coder/websocket` | 对等 echo / broadcast / drain;**G 增强**:命名房间(§7) |
| SQLite | `modernc.org/sqlite`(纯 Go)或 `mattn/go-sqlite3`(cgo) | 优先纯 Go 以便交叉编译;FTS5/migrate 行为对齐 |
| PostgreSQL | `jackc/pgx/v5` | `postgres://` / `postgresql://` |
| Redis | `redis/go-redis/v9` | `# cache`;**G 增强**:可选 session/WS 后端 |
| S3 | `aws-sdk-go-v2` 或 MinIO SDK | `s3://`;兼容 RustFS |
| 密码 | `golang.org/x/crypto/argon2` | argon2id 参数对齐现实现 |
| Markdown | `goldmark`(GFM 扩展) | 对等 `pulldown-cmark` 用途(正文 HTML) |
| JSON | `encoding/json` | ABI 边界 |
| 构建 | `go build -buildmode=c-shared -o libweb.so` | 见 §9 |
**不引入**完整 Web 框架(Gin/Echo 业务层)以免作者面旁路;框架能力用 Marqdo `# app` 表达。
---
## 5. ABI 全量清单(必须注册 · 兼容)
> 参数列为注册时 `params` CSV(英;实现须同时接受设计中已有的中文键别名,与现 `lib.rs` 一致)。
> 状态列:`P0` = 首波必须与 gold 对齐;实现顺序见 §10。
### 5.1 Page / compose / assets / render
| ABI | params(摘要) | 域 |
|-----|----------------|-----|
| `web_page_new` | (空或 title 等,对齐现实现) | page |
| `web_compose_components` | page, components, … | compose |
| `web_compose_main` | page, main, … | compose |
| `web_page_query` | page, query | page |
| `web_page_order` | page, order | page |
| `web_page_link_prefix` | page, prefix | page |
| `web_page_css` | page, css | page |
| `web_page_detail` | page, … | page |
| `web_page_meta` | page, meta | SEO |
| `web_page_head` | page, head | W8 |
| `web_page_images` | page, images | W8 |
| `web_page_paginate` | page, … | content |
| `web_head` | table / … | W8 |
| `web_images` | table / … | W8 |
| `web_app_icons` | app, icons | W8 |
| `web_style` | table, strict? | CSS |
| `web_compose_form` | page, form, target? | form embed |
| `web_render` | page | HTML |
### 5.2 SEO / ops routes
| ABI | 域 |
|-----|-----|
| `web_rss_build` | RSS |
| `web_app_route_rss` | app |
| `web_app_redirect` | app |
| `web_app_error_page` | app |
| `web_app_sitemap` | app |
| `web_app_robots` | app |
| `web_sitemap_build` | sitemap |
### 5.3 Upload / media
| ABI | 域 |
|-----|-----|
| `web_app_upload` | app |
| `web_app_download` | app |
| `web_upload_validate` | media |
| `web_upload_save` | media |
| `web_media_new` | media |
| `web_app_gallery` | app |
### 5.4 Database
| ABI | 备注 |
|-----|------|
| `web_db_new` | `sqlite:` / `postgres://` |
| `web_db_init` | unique / index / fk / 审计时间戳 |
| `web_db_insert` / `select` / `get` / `update` / `delete` / `exec` | CRUD |
| `web_db_query` / `count` | 原生 / 计数 |
| `web_db_migrate` | **SQLite only**(对等) |
| `web_db_fts_create` / `web_db_search` | **SQLite only** |
| `web_db_begin` / `commit` / `rollback` | 事务句柄 |
| `web_db_list_tables` / `web_db_table_info` | admin 内部 |
Where 语义:等值 map、filter 表、OR / IN / BETWEEN、分页 offset/limit——行为对齐现 `db.rs` / `db_pg.rs`。
### 5.5 Cache / storage
| ABI | URL |
|-----|-----|
| `web_cache_new` / `get` / `set` / `del` / `exists` / `ttl` | `memory:` / `redis://` |
| `web_storage_new` / `put` / `get` / `delete` / `list` | `file:` / `s3://` |
### 5.6 App / HTTP / hosting
| ABI | 域 |
|-----|-----|
| `web_app_new` | app |
| `web_app_route` | 动态 `{param}` + `/_part` |
| `web_app_mount_form` | `/_form` |
| `web_app_static` | 静态目录 |
| `web_app_middleware` | `configure`:CORS、安全头、gzip、body_limit、JSON API、access_log、cache_control |
| `web_app_proxy` | 流式反代 / SSE(H1) |
| `web_app_invoke` | HTTP → `lib.member`(H2;经 `host_query call_lib_path`) |
| `web_listen` | 阻塞监听;组装全部路由 |
| `web_app_route_ws` | WS 端点 |
| `web_ws_connect` | 客户端单次请求-响应式 |
| `web_app_auth` | `/admin` 门禁 |
| `web_app_gate` | RBAC 段前缀 |
### 5.7 Form
| ABI |
|-----|
| `web_form_new` / `fields` / `rules` / `validate` / `render` / `submit` / `from_schema` |
规则:`required`、`min:N`、`max:N`、`email`、`url`、`match:field`、`in:a,b,c`。
### 5.8 Session / auth
| ABI |
|-----|
| `web_session_new` / `set` / `get` / `del` / `destroy` |
| `web_auth_new` / `login` / `check` / `logout` |
| `web_password_hash` |
安全对等:argon2id、CSRF、登录限速、CSPRNG session id、cookie Secure(配置)、滑动 TTL、持久化会话(默认 SQLite 会话表;见 §7 Redis 可选)。
### 5.9 HTTP 挂载面(`web_listen` 必须复现)
- `GET /`,`GET /_part/{id}`,`GET|POST /_form/{id}`
- 可选 admin:`{prefix}/`、`/login`、`/logout`、`/{table}`、`/new`、`/{id}/edit`、`/{id}/delete`(C0:`admin=False` 让出 `/admin`)
- 作者 `route` 页 + `{path}/_part/{id}`;动态路径参数
- WS;RSS;upload POST;download GET;gallery;sitemap;`/robots.txt`
- 301/307 重定向;自定义 404/500;proxy;invoke
- 静态与 icons;约定 `/favicon.ico`
- 保留名:`/_form`、`/_part`、静态挂载冲突检测
### 5.10 `host_query` 依赖
| name | 用途 |
|------|------|
| `entry_dir` | 路径沙箱根 |
| `call_lib_path` | invoke / 嵌套 lib 调用(含 `args`) |
| (其它已允许项) | 与 ABI v2 allowlist 一致;不得扩展任意 HostFn |
---
## 6. 作者面(保持 · 不另起炉灶)
英文 `ext/web/web.mq.md` / 中文 `ext/web/网页.mq.md` 现有 `#` 类与 `##` 方法 **保持**:
| 类 | 职责 |
|----|------|
| `# page` / `# 页面` | 装配、meta、head、images、paginate、render |
| `# db` / `# 数据库` + `# txn` | CRUD、事务、migrate/FTS(SQLite) |
| `# form` / `# 表单` | 字段、规则、校验、渲染、提交 |
| `# app` / `# 应用` | route、configure、listen、auth、gate、upload… |
| `# auth` / `# 鉴权` | login/check/logout/hash |
| `# cache` / `# 缓存` | memory/redis |
| `# storage` / `# 存储` | file/s3 |
| `# media` / `# 媒体` | validate/save |
| `# ws` / `# 实时` | connect |
| 模块函数 | `ensure_plugin`、`make_style`、`make_head`、`make_images`、`client_embed`、`text_patch`、`dom_patch`、`list_html` |
**重写默认策略**:先 **只换原生 `.so`**,L1 不动;仅当 §7 G 增强需要新方法时,再 **追加**(不破坏旧方法)。
---
## 7. G 增强(完备网页制备 + anlian;兼容之上增量)
> 以下为 **新增能力**,不替代 §5。作者面用新方法/新 configure 键;旧脚本不受影响。
| ID | 能力 | 动机 | 作者面草案 |
|----|------|------|------------|
| **G-WS1** | **命名房间** WS:`join`/`leave`/`publish`;组名 ASCII(如 `chat.room.{id}`) | anlian 公聊/私聊 | `app.route_ws` 增 `mode=room` + `room_key`;或 `ws.room_*` ABI |
| **G-WS2** | 房间消息钩子:先 `invoke`/落库再广播 | 「先写 PG 再推送」 | configure 或 route 表 `on_message=lib.member` |
| **G-SESS1** | Session 后端可选 `redis://` | 多进程/多实例 | `web_session_new` url 或 auth 配置 `session=redis://` |
| **G-CACHE1** | Redis pub/sub 可选作 WS 扇出后端 | 多进程 WS | `configure ws_backend=redis` |
| **G-API1** | Bearer API Key 校验原语(hash+pepper+scopes) | anlian `apikeys` | `web_api_key_check` + `# auth` 或独立小类;**业务 scopes 仍在 .mq.md** |
| **G-MAIL0** | (可选后续)SMTP 发送原语 | 邮箱验证码 | 不阻塞首版对等;列入 anlian 二期 |
**明确仍属应用层(不进插件)**:反垃圾策略、草稿定时发布约定、好友关系、专题 `topic_bundles` 静态交互内容(静态挂载 + 前端 Marqdo/既有 JS 资产)。
---
## 8. 暗恋见君验收矩阵(检测「能不能写完」)
外部依赖(允许):**PostgreSQL**、**Redis**;可选对象存储。
| 模块 | Marqdo 后端 | Marqdo 前端 | 插件依赖 | 验收 |
|------|-------------|-------------|----------|------|
| 站点壳 / 首页 | `# page` + db | 局部刷新可选 WASM | listen、static、cache | 首页可开 |
| posts 帖子/评论/板块 | route + form + db | 发帖表单 WASM 可选 | CRUD、CSRF、upload | CRUD+列表详情 |
| news | 同上 | 同上 | 同上 | 列表详情 |
| accounts | auth + session +(二期 mail) | 登录表单 | argon2、session、gate | 注册登录 |
| profiles | db + storage | 头像上传 | storage/upload | 资料页 |
| search | db.search 或 PG 查询 + cache | — | db/cache | 关键词搜索 |
| chat | route_ws + G-WS1/2 + db | WS 客户端脚本 | Redis + WS rooms | 公聊+私聊实时 |
| apikeys | G-API1 + db | 管理页 | — | Bearer 调 API |
| webmaster | sitemap/robots | — | 已有 ABI | `/sitemap.xml` |
| topics | `app.static` → bundles | 既有静态交互 | static | 专题可访问 |
**「写完」定义**:上述模块在 Marqdo 仓库或 `anlian` 旁路目录有可运行 `.mq.md` 站点;gold/手工脚本能走通主路径;不依赖 Django/Channels/Daphne/gunicorn。
---
## 9. 仓库布局与构建
### 9.1 目录(目标)
```text
plugins/web/ # Go module(替换原 Rust crate)
go.mod
go.sum
README.md
abi/
marqdo_abi.h # 从 include/ 拷贝或 cgo 引用
bridge.go # //export marqdo_plugin_* ;register;alloc/free
internal/
page/ compose/ render/ form/
db/ # sqlite + postgres driver
cache/ storage/ upload/
session/ auth/ password/ ratelimit/
httpx/ # listen、router、middleware、admin、proxy、invoke
ws/ # hub、rooms、client connect
assets/ rss/ sitemap/ markdown/
table/ # GFM 表 JSON 形态辅助
cmd/ # 可选:非 c-shared 的本地自测
scripts/build-web-plugin.sh # go build -buildmode=c-shared -o …/libweb.so
```
原 Rust 源码:`plugins/web-rust-archive/`(**已移出 Cargo workspace**;参考用,默认不构建)。
### 9.2 产物与解析
| 平台 | 文件名 |
|------|--------|
| Linux | `libweb.so` |
| macOS | `libweb.dylib` |
| Windows | `web.dll` |
解析顺序仍走 `installed_native_path` / `MARQDO_WEB_PLUGIN`;`find_native_plugin` 增加查找:
- `plugins/web/build/libweb.so`(Go 构建输出)
- `target/{debug,release}/libweb.so`(兼容旧路径,可选 copy)
### 9.3 宿主 / CI 变更要点
| 组件 | 变更 |
|------|------|
| 根 `Cargo.toml` workspace | 移除 `plugins/web` / `web-rust-archive` Rust member |
| `tests/gold.rs` | `ensure_web_plugin_built()` → `scripts/build-web-plugin.sh` |
| `marqdo ext add web` | 构建回退:`scripts/build-web-plugin.sh`(Go);Release 仍下发预编译 native zip |
| Release 脚本 | Go:`scripts/build-web-plugin.sh`;其它插件仍 `cargo build -p …` |
| [ext-cli.md](ext-cli.md) / [ext-abi.md](ext-abi.md) | 注明 web 插件实现语言为 Go |
### 9.4 cgo / runtime 注意
- `marqdo_plugin_init` 内 `register_fn` 注册全部符号;保存 host `alloc`/`free`/`host_query`。
- 长时间 `web_listen`:在独立 goroutine 跑 `http.Server`,ABI 调用阻塞至 shutdown 或按现语义阻塞(**对齐现 Rust:listen 阻塞当前插件调用**)。
- 禁止在 FFI 回调里长时间持有阻碍 GC 的错误模式;JSON 尽快拷贝到 Go string。
- Windows 导出需 `.def` 或 `//export` 完整三个符号。
---
## 10. 实现波次(按文档开发顺序)
| 波次 | 内容 | 退出条件 |
|------|------|----------|
| **W-G0** | 文档(本文)+ ADR + 目录骨架 + ABI bridge 能 `plugin.load` + `demo` 注册探测 | ✅ `tests/ext/web-go-abi-smoke.mq.md`;`web_go_ready` + `web_page_new`;`scripts/build-web-plugin.sh` → `libweb.so` |
| **W-G1** | table 辅助 + `web_style` + page new/compose/render(无 listen) | ✅ `web-smoke` / `web-zh-smoke`(含 compose_form / app_new / app_route 袋) |
| **W-G2** | SQLite db CRUD + where + txn + init | ✅ `web-db-w2-smoke` / `web-db-w6-smoke`(txn·migrate·FTS) |
| **W-G3** | form + mount_form + CSRF 基础 | ✅ `web-form-smoke`(validate/submit/render;CSRF 字段已接,listen 侧硬化见 W-G4/G5) |
| **W-G4** | `web_listen` + route + static + part + middleware + JSON API | ✅ offline:`web-route` / `web-static` / `web-middleware` / `web-part`;`web_listen` 已接线(live 随 W-G5+ hardening) |
| **W-G5** | session/auth/password/rate limit/gate/admin | ✅ offline:`web-security` / `web-c0` / `web-c1`;login rate limit 包已就位(HTTP 接线随 listen hardening) |
| **W-G6** | upload/download/gallery/ETag + assets W8 | ✅ `web-upload` / `web-assets` / `web-p3` |
| **W-G7** | SEO RSS sitemap robots redirect error paginate markdown | ✅ `web-content` / `web-w7-*` |
| **W-G8** | WS echo/broadcast + access_log | ✅ `web-ws-broadcast-*` |
| **W-G9** | Postgres + Redis cache + file/S3 storage | ✅ `web-drivers-smoke` |
| **W-G10** | proxy + invoke + nested plugin | ✅ `web-proxy-invoke` / hosting live |
| **W-G11** | 定制 C2–C4 shell/layout/style/nav | ✅ `web-c2`–`c4` |
| **W-G12** | G 增强 WS rooms + Redis session/pubsub + API key 原语 | ✅ 单测 + `web-g12-api-key-smoke` |
| **W-G13** | 默认切换 Go `libweb`;归档 Rust;更新发版与 ext CLI | ✅ 离线+live gold(7 个 `*_live`)对 Go 全绿;`ext add`/`gold`/`release` 走 `scripts/build-web-plugin.sh`;Rust 移出 workspace;gold 强制 `MARQDO_WEB_PLUGIN` 避免 `~/.marqdo` 旧 so |
| **W-G14** | anlian Marqdo 重写主路径(可分仓或 `examples/anlian-mq/`) | ✅ `examples/anlian-mq/`(本地 SQLite + 粉玻璃主题 + 主路由/登录/片段;外接 PG/Redis 仍为增强路径) |
每波次:**先补 Go 实现 → 跑对应 gold → 再进入下一波**。禁止跨波次留下「注册了但返回 stub 错误」的 ABI(除 W-G0 明确的未实现探测)。
---
## 11. 测试策略
| 类型 | 做法 |
|------|------|
| 单元 | Go `go test ./internal/...`(db where、form rules、middleware) |
| 金样例 | 现有 `tests/ext/web-*.mq.md`;构建脚本产出 `libweb.so` 后跑 |
| Live | 现有 `*-live-server.mq.md` + curl |
| 回归门禁 | CI:安装 Go → `scripts/build-web-plugin.sh` → `cargo test` 相关 web 项 |
| anlian | 独立 smoke:登录、发帖、WS 发言、API key |
---
## 12. 风险与缓解
| 风险 | 缓解 |
|------|------|
| cgo/共享库与宿主线程 | 文档化;listen 独立 goroutine;shutdown 明确 |
| JSON ABI 开销 | 热路径减少往返;装配结果缓存;不在此用「换语言」幻想消除 |
| 行为微差异(HTML/Markdown) | 用同一批 gold HTML 片段断言;差异列 changelog |
| 交叉编译 | 优先 `modernc.org/sqlite`;Release 矩阵 Linux/Windows 先 |
| 双实现并存混乱 | W-G13 前用 `MARQDO_WEB_PLUGIN` 显式指向;文档写清默认 |
---
## 13. 文档与索引更新清单
实现推进时同步:
- [x] 本文状态行随波次更新
- [x] [ext-abi.md](ext-abi.md) Demo/Web 节:实现语言 Go
- [x] [ext-cli.md](ext-cli.md):构建回退含 `go build` / `scripts/build-web-plugin.sh`
- [x] [ext-web.md](ext-web.md):链到本文;C5 落实说明
- [ ] [web-asgi-servers-and-marqdo.md](web-asgi-servers-and-marqdo.md):axum → Go `net/http`
- [ ] [doc/README.md](../README.md) 索引行(若尚未链到本文)
- [x] ADR:`doc/adr/0004-web-plugin-go.md`(Accepted)
- [x] `plugins/web/README.md` 开发者构建说明
---
## 14. 决议摘要
1. **全量重写** `plugins/web` 为 Go,**不是**最小闭环。
2. **既有网络拓展能力(§5)重写后必须仍可用**;作者面默认兼容。
3. **PostgreSQL / Redis 外接** 为一等公民;Marqdo 承担应用前后端脚本。
4. **暗恋见君** 为完备性验收,不是缩小插件范围的借口。
5. **多语言 ABI 生态** 以本插件为样板(G7)。
6. 开发严格按 **§10 波次** 推进;本文件为唯一施工图。
+81
View File
@@ -0,0 +1,81 @@
# `ext/web` 可配置 RBAC(角色 ⊥ 权限)
| | |
|---|---|
| 验收 | qdqc:门禁 `desk:access` + 评论权限;`tests/ext/web-rbac-*-smoke.mq.md` |
| 状态 | **Accepted · 已落地核心**(gate permissions;`/_rbac/*` 管理台 **opt-in** `管理台=真`) |
---
## 0. 一句话
权限是原子能力(`resource:action`);角色是权限包;用户通过 `user_roles` 获得角色。门禁与业务都问 `can(user, permission)`。管理员可在后台新建角色、勾选权限、赋给用户——**禁止**只靠写死的 `role=admin|user` 字符串作为唯一模型(兼容期仍可读旧 `roles=` gate)。
---
## 1. 表结构(SQLite / Postgres 同构)
| 表 | 列 |
|----|-----|
| `web_permissions` | `code` PK, `resource`, `action`, `description` |
| `web_roles` | `id` PK, `name` UNIQUE, `is_system` INT, `tenant_id` TEXT NULL |
| `web_role_permissions` | `role_id`, `permission_code` PK(role_id, permission_code) |
| `web_user_roles` | `user_id`, `role_id`, `tenant_id` TEXT NULL, PK(user_id, role_id, tenant_id) |
| `web_users` | `id` PK, `username` UNIQUE, `password_hash`, `created_at` |
命名带 `web_` 前缀,避免与业务表冲突。站点也可映射自定义表名(后期);首版固定。
---
## 2. 权限码约定
形如 `comments:create`、`desk:access`、`roles:manage`。内置种子见 `DefaultCatalog`。`*` 或角色名 `superadmin` / 兼容 `admin`:登录时展开为目录全集。
---
## 3. 作者 API
```markdown
**`应用` = > `应用`.权限 确保结构=真 目录=`权限目录`**
**`应用` = > `应用`.门禁 路径="/desk" 权限="desk:access" 匹配="prefix" 拒绝="redirect"**
**`应用` = > `应用`.鉴权 用户表=`管理员` 注册=真 注册路径="/register" …**
```
| 方法 | ABI | 说明 |
|------|-----|------|
| `app.rbac` / `启用权限` | `web_app_rbac` | ensure schema;可选 `目录`;`管理台=真` 才挂 `/_rbac/*` |
| `app.gate` | `web_app_gate` | 新增 `permissions`/`权限`(CSV);与 `roles` 可并存:有 permissions 时按权限判定 |
| `rbac.can` | `web_rbac_can` | `{ok, allowed}` |
| `rbac.assign_role` | `web_rbac_assign_role` | 用户←角色 |
| `rbac.set_role_permissions` | `web_rbac_set_role_permissions` | 角色←权限列表 |
防提权:`set_role_permissions` / `assign_role` 在 HTTP 管理面检查操作者 `roles:manage` 且不能授予自身没有的 permission。
---
## 4. 运行时
1. `listen`:若 `auth.rbac=true` 或调用过 `app.rbac`,对 `db` URL `EnsureSchema` + 种子。
2. 仅当 `auth.rbac_desk=true`(`启用权限 管理台=真`)时挂载 `/_rbac/*` API 与 desk。
3. 登录成功:解析角色 → DB `user_roles` ∪ GFM 角色展开 → session `permissions`(CSV)+ 兼容 `role`。
4. `withRBAC`:gate 含 `permissions` 则 `PermissionAllowed`;否则旧 `RoleAllowed`。
5. 注册:`POST /register` 写入 `web_users`,默认赋 `member` 角色。
---
## 5. qdqc 映射
| 产品 | 权限码 |
|------|--------|
| 发评论 | `comments:create` |
| 删任意评论 | `comments:delete` |
| 进 desk | `desk:access` |
| 管角色 | `roles:manage` |
首个 GFM `admin` 用户登录后视为 `superadmin`(全权限);DB 迁移后绑定 `superadmin` 角色。
---
## 6. 非目标(本切片)
对象级 ACL 全图、ABAC;租户列先可空,多租户波次再启用。
+91
View File
@@ -0,0 +1,91 @@
# ext/web:请求上下文与表单字段来源
| | |
|---|---|
| 状态 | **Accepted** |
| 日期 | 2026-09-18 |
| 相关 | [ext-web.md](ext-web.md) §5.5 · 对照 Django `request.user` / URL kwargs |
| 动机 | 禁止扩展库按业务表名(如 `comments`)特判填字段;身份与路由键属于请求上下文 |
---
## 0. 原则
1. **扩展库提供机制,站点表达领域** — 不得出现 `if table == "comments"`。
2. **身份只从 session 来,且服务端盖戳** — 客户端提交的 `author` 等不可信。
3. **资源键从路由参数来** — 页面已在 `/post/{slug}` 时,表单继承该页 `params`,不解析 Referer 猜 slug。
4. **非 `client` 来源的字段默认不渲染** — 服务端在校验前写入;若 POST 带同名键,一律覆盖丢弃。
---
## 1. 请求上下文(Request)
每次处理 HTTP 请求时,框架逻辑上持有:
| 键 | 含义 |
|----|------|
| `user` / `username` | 登录名;访客为空 |
| `params` | 动态路由捕获(如 `{slug}`) |
| `path` | 请求路径 |
| `method` | GET / POST / … |
| `query` | URL 查询(可选) |
与 Django 对应:`request.user`、`request.resolver_match.kwargs`、`request.path`。
页面渲染时已有 `page.params`(`injectParams`)。表单提交时通过隐藏字段 `_mq_params`(JSON)与 `_mq_return`(回跳路径)把**渲染该表单时的页上下文**带回 POST,避免依赖 Referer。
---
## 2. 字段表「来源」列
字段表增加可选列 `来源` / `source`(缺省 = `client`):
```markdown
| 字段 | 标签 | 类型 | 必填 | 默认 | 来源 |
|------|------|------|------|------|------|
| body | 写下你的想法 | textarea | true | | client |
| author | | | true | | session.username |
| post_slug | | | true | | route.slug |
| created_at | | | false | | now |
```
| 来源值 | 含义 | 渲染 |
|--------|------|------|
| `client` / 空 | 用户填写 | 正常控件 |
| `session.username` / `session.user` / `user` | 当前登录用户名 | 不渲染 |
| `route.NAME` / `param.NAME` / `params.NAME` | `params[NAME]` | 不渲染 |
| `now` / `utc.now` / `server.now` | UTC `YYYY-MM-DD HH:MM:SS` | 不渲染 |
`类型=hidden` 仍可显式使用;与 `来源≠client` 叠加时仍不依赖客户端值(服务端覆盖)。
---
## 3. 提交管线
```
ParseForm → 去掉来源≠client 的 POST 键
→ 按字段来源从 Request 写入
→ validate → insert/update
→ 回跳:优先 _mq_return(同站路径),否则 form.redirect
```
伪造 `author` / `post_slug` 无效。
---
## 4. 页面列表装配(副绑定)
详情页可附加与主主体**不同查询条件**的列表绑定(如评论):
```markdown
**post = > post.列表装配 主体=`评论卡片` 条件=`评论条件` 排序="-created_at"**
```
条件值同样支持 `{slug}`。渲染在主文章/卡片区之后,无需为子资源单独写 JSON API + 前端过滤。
---
## 5. 非目标
- 不在扩展库内实现「评论」领域类型。
- 不把 Referer 解析当作正式 params 来源(仅兼容期可作 `_mq_params` 缺失时的弱回退,金样不依赖)。
+24
View File
@@ -0,0 +1,24 @@
# Native SPA(Marqdo WASM 全页客户端)
| | |
|---|---|
| 状态 | **Accepted · MVP** |
| 日期 | 2026-09-17 |
| 相关 | [browser-marqdo-wasm.md](browser-marqdo-wasm.md) · route D/E |
## 约定
| 表 | 列 | 用途 |
|----|-----|------|
| 客户端路由 | `路径` / `面板` / `标题` | 文档化视图;运行时用 `path` + `set_attr(hidden)` 切换 |
| 客户端状态 | `browser.store_set` / `store_get` `scope=memory` | 页内状态(列表 JSON、当前 id) |
作者零业务 JS:`web.client_embed` + `static/client.mq.md` + `lib/browser`。
## Bridge
`storage` effect 支持 `scope=memory`(进程内 `Map`),与 `local` / `session` / `cookie` 并列。
## Demo
`examples/web-spa-app/` — 列表 → 详情 → 编辑,全客户端路由。
+23
View File
@@ -0,0 +1,23 @@
# ext/web multi-tenant (path / subdomain / header)
| | |
|---|---|
| 状态 | **Accepted · MVP** |
| 日期 | 2026-09-17 |
| 相关 | [ext-web-rbac.md](ext-web-rbac.md) · full-ambition plan |
## Author API
```markdown
**应用 = > `应用`.tenant mode="path" param="t" column="tenant_id" default_scope=False**
```
JSON route table may set `tenant_scope` / `租户作用域` = true so `GET /api/items?t=acme` only returns rows with `tenant_id=acme`.
## Runtime
1. `withTenant` resolves id into request context.
2. Scoped JSON selects `AND tenant_id=?`; missing tenant → 400.
3. `default_scope=True` also stamps form POST bodies.
Demo: `examples/web-tenant-saas/`.
+23 -15
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) |
| 相关 | [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) |
| 状态 | **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 者)评审通过后**删除或清空后重写**;禁止在旧代码上打补丁演进 |
| 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 |
---
@@ -247,6 +251,7 @@ import db:db/index.mq.md
|------|------|
| compose_components / 组件装配 | 解析组件·样式路径 → 填 nav/sidebar/footer → CSS → 登记 part |
| compose_main / 主体装配 | 解析库字段与样式路径 → 填 main → 登记 part(如 id=`index`) |
| compose_list / 列表装配 | 副绑定(独立 query/order);可选 target 注入引言元素;见 [ext-web-request-context.md](ext-web-request-context.md) |
**槽位推断:** 由组件导出名决定(`nav`→顶栏,`side`→侧栏,`foot`→底栏;其余→main)。
@@ -423,6 +428,7 @@ import db:db/index.mq.md
| `类型` | 控件/值类型:`text` `textarea` `number` `email` `url` `checkbox` `select` … |
| `必填` | 是否必填 |
| `默认` | 可选默认值 |
| `来源` / `source` | 可选;见 [ext-web-request-context.md](ext-web-request-context.md):`client`(默认)/ `session.username` / `route.NAME` / `now`;非 client 不渲染且服务端盖戳 |
#### 5.5.2 校验表(作者面)
@@ -541,7 +547,7 @@ submit → action=insert → db.insert;action=update → db.update
|----|----|------|
| Marqdo 核心 | 表→Value、类/方法、import | 不识别 web 路径语法 |
| `ext/web/*.mq.md` | 作者 API、中英面、委托插件 | 不直接 `host_*` |
| `plugins/web` | 路径解析辅助、装配结果、listen、SQL、渲染 | 不要求作者写袋 |
| `plugins/web` | **Go** `libweb`(HTTP / SQL / HTML 壳;见 [ext-web-go-rewrite.md](ext-web-go-rewrite.md)) | 不要求作者写袋 |
**实现要点(评审通过后再做):**
@@ -580,7 +586,9 @@ submit → action=insert → db.insert;action=update → db.update
## 9. 非本波次(可记入路线图)
- Postgres / Redis / S3 驱动细节(SQLite 已落地);
- 复杂权限与多租户;
- ~~复杂权限与多租户~~ → **可配置 RBAC** 见 [ext-web-rbac.md](ext-web-rbac.md);**多租户** 见 [ext-web-tenant.md](ext-web-tenant.md)(path/subdomain/header + `tenant_scope`);
- ~~重客户端 SPA~~ → **Native SPA** 见 [ext-web-spa.md](ext-web-spa.md)(WASM + 路由表 + `store_set` memory);
- ~~实时协同编辑~~ → **Collab MVP** 见 [ext-web-collab.md](ext-web-collab.md)(WS room LWW 文本 + presence);
- 子页路由糖的更多约定(`# 应用.route` 已够用)。
---
+29
View File
@@ -0,0 +1,29 @@
# 三层归属与准入戒律(layers)
| | |
|---|---|
| 状态 | **Accepted · 准入制度(问题一落地)** |
| 日期 | 2026-09-22 |
| 相关 | [core-surface.md](core-surface.md)(核心表面守卫)· [three-problems.md](../roadmap/three-problems.md) 问题一 · [three-problems-plan.md](../roadmap/three-problems-plan.md) T1.2 |
> **目的**:语言核心保持小——**Language / Runtime / Document 三层分明,生态功能不淹没语言身份**。本制度是机制不是宣言:违反即 CI 红 / PR 不评审。
## 1. 三层归属表
| 层 | 内容 | 仓库位置 |
|----|------|----------|
| **Language** | 标记映射、词法/行分类、AST、语义、升参、契约检查器、诊断 | `src/lex/` `src/parse/` `src/ast.rs` `src/interp.rs` `src/diagnostics.rs`(及 `contract`/`check`)· 宪法 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [core-surface.md](core-surface.md) |
| **Runtime** | stdlib、插件 ABI、WASM、debugger、view、catalog / schema / mcp CLI、字节码后端 | `lib/` `plugins/` `crates/` `src/catalog.rs` `src/view/` `src/debug/` `src/builtin.rs` `src/bytecode/` |
| **Document** | 知识单元、AI skills、示例、官方扩展、用户站 | `*.mq.md` `skills/` `ext/` `public/` `examples/` `doc/` |
## 2. 准入戒律
1. **先填层归属**:任何新特性提案(issue / PR / 设计文档)必须先声明进哪层;未填 = 不评审。
2. **Language 层变更 = ADR**:新增核心标记必须有 `doc/adr/` 编号 + 「为什么现有标记不够」+ [core-surface.md](core-surface.md) 增行 + 样例 + `CORE_CONSTRUCTS` 同步(缺任一 → CI 守卫红)。
3. **核心计数只许持平或下降**:每个 release 的核心标记计数不得增长;确需增长即触发 Language 层复盘(ADR 里写明不可替代理由)。
4. **默认进 ext**:能用扩展、stdlib、插件解决的,一律不进核心。
5. **CHANGELOG 单列「核心表面 Δ」**:每个 release 写明增删(无 Δ 写「无」);发版 checklist(`.cursor/skills/marqdo-release/SKILL.md`)含此步。
## 3. PR 模板
`.github/PULL_REQUEST_TEMPLATE.md` 含「层归属」必填项与「核心表面」勾选——与本制度一一对应。
+55
View File
@@ -0,0 +1,55 @@
# 标准库 / 扩展库:代码即文档
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-09-14 |
| 相关 | [code-as-docs-gaps.md](code-as-docs-gaps.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md) · [collection-access-link.md](collection-access-link.md) · [stdlib.md](stdlib.md) · [marqdo-dev skill](../../.cursor/skills/marqdo-dev/SKILL.md) · [roadmap](../roadmap/lib-ext-code-as-docs.md) |
---
## 1. 目标
`lib/*` 与 `ext/*` 的 `.mq.md` 应**可当说明书读、可当程序跑**。薄库不写长文;厚领域库(web / quantum / …)仍用叙述承载意图,但数据与调用面与用户程序同一套标记。
## 2. 薄库模板(默认)
每个导出函数 / 方法尽量按此骨架(中英分文件锁步):
1. **目的句**(一句人话,无标记即可)。
2. **叙述形参**:正文里出现 `` `名` `` / `` `名`=默认 ``(推断签名);过渡期可保留 `` + `名` ``。
3. **一例**:粗体或 `>` 调用;优先可读表面。
4. **实现**:短;取元用 `[键](集合)`,**禁止新增**脚注取元 `` `m`[^k] ``(旧解析仍可用)。
调用示例(三种等价,试点期任选;新叙述优先括号标记或粗体):
```markdown
**出 = [put] 入=`表` 键="a" 值=1**
**出 = put 入=`表` 键="a" 值=1**
> put 入=`表` 键="a" 值=1
```
带布尔开关时可用前置修饰:`严格 [parse] text=`源`` → `严格=True`(形参名与修饰语字面一致;核心不剥「的」等词缀)。
## 3. 硬约束
| 要 | 不要 |
|----|------|
| GFM 表作数据;`table.put` / 具名助手 | `json.set` 链当字典构造器 |
| 作者程序用 `[k](c)` 取元;`- [项](集合)` foreach | 新代码写 `` m[^k] `` |
| 中英 API 对称(见 [stdlib-i18n.md](stdlib-i18n.md)) | 只改一侧 |
| 一例跑通即文档(public/stdlib 或 examples) | 另开第二套「文档站」手写说明 |
**库函数体内的叙述坑:** 函数体里的链接形 `[k](c)`、以及单独的 `**强调**` 会被当成可执行代码。库内说明用「链接取元 / link-index」等字面描述;可执行示例放在 `public/stdlib` 或 `examples/`,不要写在 `##` 体内当叙述。
## 4. 波次
见 [roadmap/lib-ext-code-as-docs.md](../roadmap/lib-ext-code-as-docs.md):先稳定调用表面,再 M1 试点 table/text/json,其后批次 lib → ext。
## 5. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿(随括号调用落地) |
+619
View File
@@ -0,0 +1,619 @@
# Marqdo 语法映射 v0.3(叙述统一 · 粗体即代码)
| | |
|---|---|
| 状态 | **Accepted · 现行运行时目标(实现中)** |
| 日期 | 2026-09-13 |
| 取代 | [markdown-mapping.md](markdown-mapping.md) **v0.2(已废止为运行时宪法)** |
| ADR | [0005-prose-unified-markup.md](../adr/0005-prose-unified-markup.md) |
| 路线 | [markup-v0.3.md](../roadmap/markup-v0.3.md) |
| 相关 | [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) · [call-arguments.md](call-arguments.md) · [objects.md](objects.md) · [keywords.md](keywords.md) |
> **名词:** 本文「Markup」指 Marqdo **如何把 Markdown 标记映射成语法**(`**` 代码、`*` 返回、`` `名` `` 声明),不是另一个语言。产品仍是 Marqdo。
> **v0.3 为唯一映射。** 不做 v0.2 双模式 / `--markup` 版本身份。摸索阶段允许破坏性变更;旧 `.mq.md`(`*语句*` / `**返回**`)须改写。金样例见 `tests/markup-v03/`。
---
## 0. 一句话
让 **Markdown 叙述本身成为程序的一部分**:普通文字里用 `` `名` `` 出现变量(首次未赋值 = 声明);用 **`**…**` 粗体** 包裹可执行代码(含调用,不必再写 `>`);用 **`*…*` 斜体** 表示返回值。函数形参**不再手写 `+` 列表**,由函数体内的声明/赋值自行推断。
---
## 1. 动机(为何推翻 v0.2 的部分定论)
v0.2 为了「标记即语法」的清晰边界,做了这些硬隔离:
| v0.2 | 代价 |
|------|------|
| 无标记行 = 纯注释;变量只能写在 `*…*` / 结构行里 | 叙述与代码割裂,「文档即代码」读起来像两套语言叠在一起 |
| `*…*` = 语句,`**…**` = 返回 | 与常见 Markdown/AI 习惯相反:模型更爱用 `**` 强调「要执行的东西」,读者也更易看见粗体 |
| 调用必须 `>` | 行间调用要另起结构行,叙述中夹调用不自然 |
| 形参必须 `` + `名` `` | 仪式感强;函数头像「另一套签名语言」,与正文脱节 |
古早示例(当时不能跑,正是本文要合法化的目标面):
```markdown
## 加一函数
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
# main
我要调用加一函数可以采用这样的办法:
> 加一函数 37
或者可以直接这么调用**加一函数 37**
```
目标:上述文件在 v0.3 下应能解析、求值,且**读起来仍是一篇正常中文说明**。
---
## 2. 哲学(设计原则)
### P1 — 叙述统一(Prose-unified)
- Marqdo 注释采用 **Markdown 叙述**(段落、列表中的说明文字),不是第二种注释语法。
- **变量可以出现在正常文字之间**:用 Markdown 行内代码 `` `n` `` 标识标识符。
- **第一次出现且未赋值 = 声明变量**;之后的出现 = 引用。赋值发生在粗体代码段内(或兼容的结构赋值形)。
- **未使用的变量无害**(不报错、不升参);真正的输入由「可执行面读取」升为形参(§8)。
- 这样「说明文字」与「程序名字」共用同一套 Markdown 视觉习惯,整体更和谐。
### P2 — 粗体即代码(Bold-as-code)
- **`**…**` = 代码段**(可执行):赋值、表达式、函数/方法调用、可内联的短语句。
- 选择粗体的原因:
1. **AI 输出偏好**:模型天然爱用 `**` 强调「重要操作」;把粗体定为可执行,降低「模型写了强调却被当成返回」的错配。
2. **行间显眼**:在长段落里,粗体比斜体更容易被扫到。
- 粗体代码段内的调用 **允许不写 `>`**:`**加一函数 37**` 与 `> 加一函数 37` 语义等价(见 §6)。
- **`>` 保留为可选调用面**(blockquote 风格、独立行、兼容 v0.2 迁移与 AI 已学会的形态)。
### P3 — 斜体即返回(Italic-as-return)
- **`*…*` = 返回值**(架构级),与粗体代码形成对立、易读的一对:
- 做了什么 → 粗体
- 结果是什么 → 斜体
- **空返回 / 无值收束**(已决议,见 §7.2):推荐 `*None*` / `*无*`;整行 `**`;兼容 `****`。`---` / `***` 仅为叙述分隔(跳过),**不再**结束函数体。
- **输出仍不是返回**:打印继续用内置 `print` / `打印`(副作用函数),不把粗体或斜体当成「打印到终端」的语法。
### P4 — 形参由体推断(Body-inferred params)
- **不再要求**作者手写 `` + `名` `` 形参表(v0.3 默认关闭;过渡期可兼容,见 §8)。
- 函数体内:
- **只声明、未赋默认** → **必选形参**(调用时必须提供)。
- **声明同时赋值**(含默认值字面量)→ **可选形参**(带默认值)。
- 推断顺序与绑定规则见 §8;与位置/具名实参规则对齐 [call-arguments.md](call-arguments.md) 的精神(可修订附录)。
### P5 — 标记仍承载控制流(不变)
- **不引入** `if` / `else` / `while` / `for` / `def` / `return` 关键字。
- `#` = 对象/类型,`##`+ = 函数/方法([objects.md](objects.md) 不变)。
- 分支仍用 `1.` `2.` …;循环仍用 `-`;结构行不必再包粗体(见 §5)。
### P6 — 其它「代码即文档」补强(本版一并采纳)
| 思路 | 说明 |
|------|------|
| **渐进披露** | 读者可只读叙述;运行时只执行标记与推断出的声明。同一文件服务人与机器。 |
| **最小仪式** | 能从正文看出的签名,就不在函数头重复写一遍。 |
| **双调用面** | 独立行 `>` 适合「步骤清单」;行间 `**f …**` 适合「嵌在句子里的动作」。 |
| **标识符视觉统一** | 叙述、代码、形参一律优先 `` `名` ``;粗体/斜体内部允许裸名(与 v0.2 斜体/粗体内规则同类)。 |
| **段落仍可整段注释** | 不含任何可执行标记、且无「声明性 `` `名` ``」义务的纯说明段,行为与注释相同(见 §4 消歧)。 |
| **迁移可观测** | `--dump-lines` / `--dump-ast` 必须能区分「叙述中的声明」与「粗体代码」与「斜体返回」。 |
---
## 3. 与 v0.2 对照(角色对调摘要)
| 概念 | v0.2 | v0.3 |
|------|------|------|
| 程序语句 / 代码段 | `*…*` | `**…**` |
| 返回值 | `**…**` | `*…*` |
| 独立调用 | 必须 `>` | `>` **或** `**callee …**` |
| 形参 | 标题下 `` + `名` `` | **体推断**(`+` 过渡兼容) |
| 叙述中的变量 | 一般为注释,不可声明 | `` `名` `` 可声明/引用 |
| 无标记纯文字 | 成段注释 | 仍为叙述;**若含声明性反引号则参与绑定图**(见 §4) |
这是一次 **架构级标记对调**,不是局部糖。金样例、教程、Skill、扩展库需按路线图分波迁移。
---
## 4. 叙述、声明与注释
### 4.1 三层模型(修订)
| 层 | 形态 | 角色 |
|----|------|------|
| **叙述面** | 普通 Markdown 段落、列表说明 | 给人读;其中的 `` `名` `` 可进入**绑定图** |
| **可执行面** | 结构标记(`#` `>` `+` `-` `1.` 表…)+ **`**代码**`** + **`*返回*`** | 求值 |
| **外联面** | ` ```lang ` | FFI(不变) |
### 4.2 变量在叙述中的出现
语法:Markdown **行内代码** `` `标识符` ``。
| 出现形态 | 语义 |
|----------|------|
| 全文(当前函数/对象作用域)**首次**出现 `` `n` ``,且此前/同句无对 `n` 的赋值 | **声明变量**(进入绑定图;是否升为形参见 §8) |
| 已声明之后再次 `` `n` `` | **引用**(不生成新绑定) |
| 粗体内 `**n = …**` / `**n=n+1**` | **赋值**(若首次赋值且未见声明,则声明+赋值一并发生) |
| 叙述中 `` `n`=1 ``(反引号名紧贴 `=`,无粗体) | **带初值的声明**(形参默认或局部初值;见 §8) |
推荐作者写法(与动机示例一致):
```markdown
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
```
- `` `n` `` → 声明变量;因随后在代码中**读取**未先由局部独力定义 → 升为必选形参(§8)
- `**n=n+1**` → 代码段(赋值)
- `*n*` → 返回
### 4.3 何为「纯注释」
满足下列**全部**条件的段落,不产生绑定、不求值:
1. 不含结构标记行;
2. 不含 `**…**` / 作为返回的 `*…*`(见 §7);
3. 不含任何 `` `标识符` ``。
仍建议:**叙述段与独立结构代码行之间空一行**,降低人读与差分时的视觉粘连(解析器在 v0.3 下不再依赖「空行分段注释升级」作为唯一边界,但空行仍是作者卫生习惯)。
### 4.4 提及性反引号:一律视作变量(已决议)
**不另设「仅提及、不声明」语法。** 叙述里凡出现合法标识符 code span `` `名` ``,一律按 **变量** 处理(首次 = 声明,其后 = 引用)。
| 情况 | 处理 |
|------|------|
| 谈到某名但可执行代码**从未读写**它 | 仍是绑定图中的变量;**对求值无影响**(死绑定) |
| 与其它语言对照 | 类似 Python 写了未用局部、JS 未用 `let`——默认可忽略;实现可对「从未读写」发**可选 lint**,**不得**因此报错或拒绝运行 |
| 是否变成函数形参 | **否**(仅声明、从未在可执行面被读取)——见 §8.2「升参条件」 |
| 是否需要 `` 提及`n` `` 等前缀 | **不需要**;避免第二套反引号方言 |
例(合法、无副作用):
```markdown
## 说明性函数
本文顺便提到`Markdown`与`GFM`,但真正的输入只有`题干`。
**print text=题干**
---
```
- `` `Markdown` `` / `` `GFM` `` → 变量声明,未使用 → 不进形参表、不改行为
- `` `题干` `` → 声明且在粗体中读取 → 必选形参
**否决**:为「提及」单独做转义/前缀(曾列于开放点);若将来作者强烈需要「叙述中的等宽字但不进绑定图」,另开增强案,不阻塞 v0.3 核心。
### 4.5 成段规则相对 v0.2 的变化
v0.2:「段首无标记 → 整段注释,续行永不升级」。
v0.3:
- 叙述段落**可以**内含可执行粗体/斜体返回;解析器做**段内扫描**,抽出 `` `名` ``、`**…**`、`*…*`。
- 独立结构行(行首 `#` `>` `-` `1.` `|` 等)仍整行分类为代码。
- **否决维持**:「整行无标记 = 默认可执行代码」。无标记且无反引号声明的文字永不单独变成语句。
---
## 5. 映射总表(v0.3)
| 标记 | 语义 |
|------|------|
| `#` … `######` | `#` = 对象/类型;`##`+ = 函数/方法(同 [objects.md](objects.md)) |
| 叙述中 `` `名` `` | 声明或引用(§4) |
| `**…**` | **代码段**(赋值、表达式、调用) |
| `*…*` | **返回值**(含显式空值,见 §7.2) |
| `>` 行 | **调用**(可选面,与粗体内调用等价) |
| `` + `名` `` | **过渡兼容**:显式形参;新代码不推荐 |
| 体内 `1.` `2.` … | 分支 |
| 体内 `-` | 循环 |
| `N. *` | else 臂(此处 `*` 仍是「空条件」标记,**不是**返回值;见 §7.3) |
| GFM 表格 | 集合;`` `名` = `` 后绑定,或**未绑定**时求值后丢弃(文档中可写表) |
| 表达式 `[键](集合)` | **取元**(与 foreach 同形;见 [collection-access-link.md](collection-access-link.md)) |
| `修饰… [函数名] 实参…` | **方括号标记调用**(前置修饰 → `名=True`;见 [bracket-call-modifiers.md](bracket-call-modifiers.md)) |
| `` 集合[^键] `` | **过渡**:旧脚注取元(仍可用) |
| ` ```lang ` | 外联(不变) |
| 单独一行 `---` / `***` | **叙述分隔**(跳过;模块顶与函数体内相同) |
| 整行恰 `**` 或 `****` / `*None*` / `*无*` | **空返回**并结束本函数体(见 §7.2) |
### 结构行与粗体
行首已是结构标记的构造(`#` `>` `+` `-` `|`、`1.`)**不必**再包 `**…**`。
粗体用于:**嵌在叙述中的代码**,以及「我想把这一小段标成可执行」的行间片段。
---
## 6. 调用
### 6.1 调用表面
```markdown
> 加一函数 37
**加一函数 37**
礼貌 [问候] marqdo
```
前两种解析为对 `加一函数` 的调用;第三种为**方括号标记调用**(`[` `]` 标出函数名,前置裸词展开为 `名=True`)。实参位置或具名绑定;详见 [call-arguments.md](call-arguments.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md)。
| 形式 | 典型用途 |
|------|----------|
| `> …` | 步骤列表、独立可执行行、与 v0.2/AI 习惯兼容 |
| `**…**` | 嵌在句子中:「或者可以直接这么调用**加一函数 37**」 |
| `**x = 加一 37**` | 粗体赋值右侧为调用时**可省略 `>`**(代码即文档首选;`> 加一 37` 仍合法) |
| `修饰… [函数] 实参…` | 叙述里需要「形容词 + 动词」时消歧;与 `[键](集合)` 取元靠 `]` 后是否紧邻 `(` 区分 |
### 6.2 粗体内调用的判别
粗体内容在去掉外层 `**` 后,按下列优先级分类:
1. 含 `=` 且左侧为可赋值目标(标识符 / 脚注左值等)→ **赋值语句**(可含右侧调用)。
2. 否则,若首词为已知函数/方法/内置/导入成员(Pass 名表可见)→ **调用**。
3. 否则 → **表达式语句**(求值后丢弃,或在语句位置非法则诊断)。
示例:
| 粗体内容 | 分类 |
|----------|------|
| `n=n+1` | 赋值 |
| `加一函数 37` | 调用 |
| `加一函数 n=37` | 调用(具名) |
| `n + 1` | 表达式(单独出现时;作返回应写 `*n + 1*`) |
| `print text=hi` / `打印 内容=你好` | 调用(内置) |
### 6.3 方法调用
- 独立行:`` > `对象`.方法 … ``(兼容)或 `> 对象.方法 …`(若接收者规则允许)。
- 粗体内:`**对象.方法 …**` / `**p = page.主体装配 组件=home**`。
- 粗体/斜体内裸名 = 变量(延续 v0.2「段内统一命名空间」精神)。
### 6.4 实参
具名 + 位置混用规则继承 [call-arguments.md](call-arguments.md);v0.3 仅把「形参列表来源」从 `+` 行改为**推断签名**(§8)。独立 `>` 行上裸词仍为文本字面量;粗体内调用的裸词为变量(与 v0.2「段内调用」一致)。
---
## 7. 返回
### 7.1 斜体返回
```markdown
*n*
*n + 1*
*"ok"*
```
斜体内部值语法与 v0.2 粗体返回内部相同(裸词 = 变量;文本须引号)。
### 7.2 空返回与收束(已决议)
Marqdo **不引入** `return` 关键字;「无值结束」用标记表达。对照常见语言:
| 语言 | 无值 / 空返回 | Marqdo v0.3 对应 |
|------|----------------|------------------|
| Python | `return` / `return None` | 显式 `*None*`·`*无*` |
| Go | 无结果函数里的 `return` | `*None*` / 整行 `**` / `****` |
| Rust | `()` 或函数末尾隐式 unit | 同上;或下一标题 / EOF 自然结束 |
| JavaScript | `return;` → `undefined` | 同上 → 运行时 `None` |
| Marqdo 历史 | `---` 收束;`****` | `---` 已改为叙述跳过;`****` 仍兼容 |
#### 形式层级(推荐自上而下)
| 优先级 | 形式 | 语义 | 说明 |
|--------|------|------|------|
| **1. 显式空值** | `*None*` 或 `*无*`(整段或行内返回位) | 返回 `None` **并结束本函数体解析** | 对齐 Python `return None`;副作用函数首选;外层续写依赖此收束 |
| **2. 空斜体标记** | **整行** trim 后恰为两个星号:`**` | 同上 | 词法钉死:`^\s*\*\*\s*$` → **空斜体返回**,**不得**当成粗体开闭 |
| **3. 兼容** | 整行 `****`(四个星号) | 同空返回 | 迁移期识别 |
| **(非收束)** | 整行 `---` / `***` | **仅叙述分隔**,跳过 | 不再结束函数;见 [code-as-docs-gaps.md](code-as-docs-gaps.md) |
```markdown
## 只打印
**print text=hi**
*None*
## 空斜体行
**print text=hi**
**
## 分割线不收束(下一标题才结束)
**print text=hi**
---
```
#### 词法消歧(空斜体 vs 粗体)
1. **整行恰好 `**`(两个 `*`)** → 空返回(规则 2),不是未闭合粗体。
2. **粗体代码**至少包住一个非空内容:`**x**`、`**n=1**`;不允许「空粗体代码段」作为语句。
3. **四个星号整行 `****`** → 兼容空返回(规则 3),不解释为「空粗体代码」。
4. 行内出现的 `**…**`(两侧还有叙述文字)按正常粗体代码扫描,不走「整行空返回」。
#### 与「有返回值」的关系
- 需要把值交回调用方 → 用非空斜体:`*n*`、`*n + 1*`(返回即结束本函数体解析)。
- 只做副作用、不要值 → 优先 `*None*` / `*无*` / 整行 `**`。
- 下一标题或 EOF 也可结束体;**不要**再靠 `---` 收束。
### 7.3 与 else 臂 `N. *` 的消歧
有序列表臂头 `2. *` 中的 `*` 表示 **else**,不是返回。判别:行匹配 `^\s*\d+\.\s+\*\s*$`(可带尾注)→ 分支 else;不进入返回扫描。
### 7.4 输出
```markdown
**print text=Hello**
> print text=Hello
```
打印是调用,不是返回。禁止把 `*Hello*` / `**Hello**` 解释为「打印 Hello」(延续 v0.2 决议精神,仅对调标记)。
---
## 8. 形参推断
### 8.1 目标签名
对每个 `## 函数`(及方法),在 Pass1 收集体之后得到:
```text
params: Vec<{ name, default: Option<Expr>, span }>
```
### 8.2 收集规则(函数作用域)
扫描该函数标题之下、下一同级/更高级标题之前的所有节点,维护**绑定图**与**形参表**(二者分离):
#### A. 绑定图(所有变量)
1. **声明事件**:叙述或代码中的首次 `` `名` ``,或粗体内首次对 `名` 的赋值左值。
2. **默认/初值事件**:叙述 `` `名`=默认表达式 ``;或符合 §8.3 的「形参默认」赋值。
3. **排除出绑定图**(不建变量):
- 循环变量 `` - [项](集合) `` 中的 `项`(循环自有绑定);
- `self` / `自`(方法自动注入)。
凡进入绑定图的名字都是**变量**——包括「只在叙述里出现、可执行代码从未读写」的名字(§4.4)。未使用 → **不报错**。
#### B. 升为形参的条件(升参)
名字已在绑定图中,且满足下列之一,才进入 `params`:
| 升参种类 | 条件 |
|----------|------|
| **必选形参** | 在可执行面(`**…**` / `*…*` / `>` / 结构语句)中存在对 `名` 的**读取**,且该读取无法单靠「不依赖外部输入的局部赋值」满足——典型:先声明、后 `n=n+1` / `*n*` / `**print text=n**` 等读到未先行赋成纯局部常量 |
| **可选形参** | 有默认/初值事件(`` `名`=… `` 或 §8.3 默认赋值),供调用方覆盖 |
**不升参**:仅叙述声明、可执行面零读取(死绑定)→ 留在绑定图,**不进** `params`,调用签名不变。
**顺序**:按升参名字的**首次声明事件**在源码中的出现序。
**仍排除**:分支/块内纯局部(金样例钉启发式);显式 `+` 合并见 §8.4。
### 8.3 「形参默认」与「函数体赋值」的区分
```markdown
## 问候
对`谁`打招呼,默认`礼貌`=False。
**print text=谁**
```
- `` `谁` `` → 必选
- `` `礼貌`=False `` → 可选,默认 `False`
- 体里的 `**print …**` 不是给 `谁` 赋默认值
```markdown
## 加一函数
输入`n`。**n=n+1**返回*n*。
```
- `` `n` `` 先声明 → 必选
- `**n=n+1**` 是**体语句**(对已声明形参赋值),**不是**默认值
判别启发式(实现契约):
- 若赋值右值**依赖同名左值**(如 `n=n+1`)→ 体语句。
- 若赋值出现在「该名被当作输入读取」之前,且右值不依赖未绑定的同名 → 可作为默认值候选。
- 叙述形 `` `名`=字面量 `` 优先视为默认值声明。
### 8.4 显式 `+` 形参(过渡)
- 若函数标题下仍有 `` + `名` `` 行:与推断结果**合并**;冲突时 **显式 `+` 胜出**并诊断警告。
- 迁移完成后(路线图 M4)可改为:存在 `+` 则关闭推断,或直接废弃 `+`。
### 8.5 调用绑定
与现有一致:具名优先,位置按「尚未绑定的形参」从左到右填充。缺必选形参 → 语义错误。
---
## 9. 完整示例(规范金样意向)
### 9.1 加一(动机例)
```markdown
## 加一函数
对于输入变量`n`,我们执行操作**n=n+1**接着返回*n*。
# main
我要调用加一函数可以采用这样的办法:
> 加一函数 37
或者可以直接这么调用**加一函数 37**
```
期望:
- 签名:`加一函数(n)`
- `# main` 两次调用均返回 `38`(第二次若未绑定到打印,至少 AST/求值结果为 38;可用 `**print text=…**` 观测)。
### 9.2 带默认值
```markdown
## 问候
向`谁`问好;`礼貌`=False 时用短句。
1. 礼貌
**print text=您好,**
**print text=谁**
2. *
**print text=嗨,**
**print text=谁**
---
# main
**问候 谁=Marqdo 礼貌=True**
> 问候 Marqdo
```
### 9.3 对象方法(不变骨架)
```markdown
# 计数器
## 加
将`self`的`值`增加`delta`(`delta`=1)。
**值 = 值 + delta**
*self*
# main
*c = > 计数器*
**c.加 3**
```
(方法形参推断含 `delta`;`self` 自动。)
---
## 10. AST / 管线变更要点(设计约束)
详细里程碑见 [markup-v0.3.md](../roadmap/markup-v0.3.md)。此处只钉**语义 → 树**的约束,供实现对照:
### 10.1 行分类(lex / line-class)
新增或调整类别:
| 类别 | 说明 |
|------|------|
| `Prose` | 叙述行;需**内联扫描** |
| `BoldCode` | 整行或片段 `**…**` |
| `ItalicReturn` | 整行或片段 `*…*`(非 else 臂) |
| `CallLine` | `>` 调用(保留) |
| … | 原有 Heading / List / Table / Fence / Hr |
**内联扫描**产出 `InlineBit`:`Text` | `IdentDecl/Ref` | `BoldCode` | `ItalicReturn`。
### 10.2 AST 节点调整(建议)
```text
Param { name, default?, inferred: bool, span } // inferred=true 表示来自体推断
Stmt::
Assign { … } // 多由 BoldCode 解析
Call { … } // CallLine 或 BoldCode 判别为调用
Return { value } // 由 ItalicReturn 解析(原由 Bold)
ExprStmt { … } // 可选:纯表达式粗体
Prose { bits } // 可选:保留叙述结构供 view/catalog;求值阶段只消费 Decl
FnDef.params:
由 InferParams(body + prose bits) 填充,再合并显式 +
```
`Stmt::Return` 的**语法来源**从粗体改为斜体;dump 文本应写 `return←italic`。
### 10.3 Pass1 / Pass2
- Pass1:收集 `#`/`##` 结构;建绑定图;跑 **ParamInfer(升参)**;登记名表。
- Pass2:粗体内调用名解析;叙述 Decl 不重复建参。
- 诊断:**必选缺失**、`+` 与推断冲突、空返回词法歧义(非整行 `**` 的残缺粗体)。
- Lint(可选、默认关或降级为 hint):绑定图中「从未读写」的死变量——**不得**当错误。
### 10.4 双后端
树遍历与字节码均消费同一 AST;字节码发射仅跟随 `Stmt`/`Expr` 变化,不感知 Markdown 标记。
---
## 11. 破坏性切换(无双模式)
**产品决定(2026-09-13):** 直接以 v0.3 为唯一运行时映射;**不**保留 `--markup v0.2` / 双 edition。旧语法金样例与库文件在迁移完成前可能失败——可接受。
| 阶段 | 行为 |
|------|------|
| 现在 | 解析器切到 v0.3;`tests/markup-v03/` 为门禁 |
| 随后 | 批量改写 `tests/structure|keywords`、`lib/`、`ext/`、Skill、`public/` |
| 文档 | `markdown-mapping.md` 改为指向本文;ADR 0005 → Accepted |
**机械改写:**
- 语句 `*a = 1*` → `**a = 1**`
- 返回 `**x**` → `*x*`
- 粗体内文本字面量须引号:`**print text="hi"**`(裸词 = 变量)
- 调用可保留 `>` 或改为粗体
- `` + `n` `` 可删,改为叙述 `` `n` `` + 升参
---
## 12. 开放问题 / 已决议
| # | 议题 | 状态 | 决议摘要 |
|---|------|------|----------|
| 1 | 空返回词法 | **已决议** | §7.2:推荐 `*None*`/`*无*`;整行 `**`;兼容 `****`;`---` 仅叙述跳过 |
| 2 | 提及性反引号 | **已决议** | §4.4:一律视作变量;未使用不报错、不升参;不设提及前缀 |
| 3 | 粗体内调用 vs 赋值 | **已落地** | §6.2:可赋值左值 → 赋值;否则表达式优先、再裸调用;`**n + 1**` = ExprStmt |
| 4 | `` `n`+1 `` 误声明 | **已落地** | Decl 名须为标识符;`` `n+1` `` 不升 Decl |
| 5 | 叙述强调斜体 vs 返回 | **已落地** | 整行 / `返回*…*` / 表达式形才当返回;`*only*` `*very important*` `*foo.bar*` 为叙述 |
| 6 | 一行多 `**…**` | **已落地** | 允许,按出现序执行(`tests/markup-v03/multi-bold.mq.md`) |
| 7 | view 展示 prose Decl | **已落地** | Structure / Functions 大纲:`inferred` 形参标注(`chip inferred`) |
---
## 13. 非目标
- 不把整篇无标记 Markdown 变成可执行程序。
- 不引入 `def` / `return` 关键字(空返回用标记,见 §7.2)。
- 不改变 `#` / `##` 对象体系与 ext 插件 ABI。
- 不在本文阶段修改解释器代码(见路线图)。
- 不为「提及」另发明一套反引号方言(§4.4)。
---
## 14. 验收标准(设计完成 ≠ 实现完成)
设计稿验收:
- [x] 哲学 P1–P6 成文
- [x] 与 v0.2 对照表
- [x] 形参推断规则可实现(含升参 vs 死绑定)
- [x] 动机示例在语义上闭合
- [x] AST/管线约束与路线图挂接
- [x] ADR 记录决策意向
- [x] **空返回**对照其它语言并钉死词法
- [x] **提及/未使用变量**政策钉死
实现验收:
- [x] 金样例夹具 `tests/markup-v03/`(`gold.rs` `markup_v03_*`)
- [x] 动机示例金样例通过(`inc-prose.mq.md`)
- [x] `--dump-ast` 可见 inferred params 与死绑定;`--dump-lines` 标注 `[decl]` / `[bold]` / `[italic]`
- [x] 空返回四种形式金样例通过
- [x] 无 v0.2 双模式(默认即 v0.3)
---
## 15. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-13 | 初稿:叙述统一、粗体代码、斜体返回、形参体推断;Proposed |
| 2026-09-13 | 决议空返回(§7.2)与提及性反引号(§4.4);形参改为「升参」与绑定图分离(§8.2) |
| 2026-09-14 | §7.2:`---` 不再收束;返回语句结束函数体解析;空返回首选 `*None*` |
| 2026-09-14 | 取元主语法改为 `[键](集合)`;脚注取元过渡保留 |
| 2026-09-24 | Artifact Metadata Binding(`${…}` Phase 1,仅 frontmatter):见 [binding.md](binding.md) · ADR 0006 |
+3 -2
View File
@@ -2,9 +2,10 @@
| | |
|---|---|
| 状态 | 已定论(修订:形参 `+`、分支 `1.`、同级再 `1.` 为新分支、标识符反引号、`-` 专用于循环) |
| 状态 | **历史文档(v0.2 · 已废止为运行时)** — 现行见 **[markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)** |
| 日期 | 2026-08-07 |
| 取代 | v0.1 中「函数头 `-` 形参 / 裸名形参与遍历变量 / `+` 分支」 |
| 被取代 | **[markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)**(粗体即代码 · 斜体即返回 · 无双模式兼容) |
| 相关 | [objects.md](objects.md) · [code-vs-comment.md](code-vs-comment.md) · [return-hr-and-code-surface.md](return-hr-and-code-surface.md) · [module-namespace.md](module-namespace.md) |
Markdown **标记即语法**。输出**不是**语言架构原语,而是内置函数 **`print`**(英文;见 [keywords.md](keywords.md))。
@@ -129,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)。
+2 -2
View File
@@ -23,9 +23,9 @@ marqdo dump FILE --stage lines|tokens|ast|sema|all
| 标志 | 阶段 | 输出内容 |
|------|------|----------|
| `--dump-lines` | 行分类 | 每行:`LINE kind=Comment\|Code\|Blank` + 原文预览 |
| `--dump-lines` | 行分类 | 每行:`kind=Comment\|Code\|Blank` + 原文;v0.3 行内位 `[decl n]` / `[bold …]` / `[italic …]` |
| `--dump-tokens` | 词法 | Token 流:`type lexeme line:col` |
| `--dump-ast` | 语法 | S 表达式或缩进树(模块/函数/语句) |
| `--dump-ast` | 语法 | 模块/函数/语句;形参带 `inferred`;叙述死绑定 `dead=[…]` |
| `--dump-sema` | 语义 | 作用域、导入图、提升后的符号表 |
| `--trace-eval` | 求值 | **JSON 行**(stderr):语句级事件,含 `path` / `span`(`line:col`) |
| `--dump-bytecode` | 字节码 | 反汇编 `Program`(指令旁带 `@line:col`;见 [bytecode.md](bytecode.md)) |
+21 -3
View File
@@ -2,18 +2,36 @@
| | |
|---|---|
| 状态 | 已决议(并入 mapping v0.1 + keywords;2026-08-04 修订函数收束) |
| 状态 | **v0.2 已决议**(现行实现);**v0.3 拟对调 `*` / `**` 角色**(见下) |
| 日期 | 2026-08-04 |
| 修订 | 2026-09-13:挂接 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) |
---
## 决议
## 决议(v0.2 · 现行)
1. **`*…*` = 程序语句**。
2. **`**…**` = 返回值**(架构级);空粗体 `****` / `** **` = 空返回(`None`)并结束函数体。
3. **输出**用内置函数 **`print`**(英文),不是粗体,不是中文名。
4. **`---` / `***`(函数体顶层)**:结束本函数体(无返回值函数收束);**不是**分支/循环装饰框。
4. **`---` / `***`**:Markdown 叙述分隔(跳过);**不再**结束函数体。无值收束用 `*None*` / 整行 `**` / `****`(见 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) §7.2)。
5. **成段注释**:空行分段;段内续行不因首字符升级为代码。
6. **否决**:无标记行 = 默认代码。
详见 [keywords.md](keywords.md)、[markdown-mapping.md](markdown-mapping.md)、[code-vs-comment.md](code-vs-comment.md)。
---
## v0.3 意向(Proposed · 未实现)
产品方重新审视后,拟在 [ADR 0005](../adr/0005-prose-unified-markup.md) 下**对调**架构标记,并放宽叙述面:
| 概念 | v0.2 | v0.3 草案 |
|------|------|-----------|
| 代码段 / 语句 | `*…*` | `**…**` |
| 返回值 | `**…**` | `*…*` |
| 空返回 | `****` / 空粗体;或 `---` | **推荐 `*None*`/`*无*`**;整行 `**`;兼容 `****`;`---` 仅叙述 |
| 输出 | 仍为 `print` / `打印` | 不变 |
| 无标记 = 默认代码 | 否决 | **仍否决** |
| 叙述中 `` `名` `` | 通常无绑定义 | 一律变量;未使用 OK;升参需可执行面读取 |
完整规则与迁移见 [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)。**v0.3 已为运行时;本文件历史决议中「`---` 收束」已废止。**
+40
View File
@@ -0,0 +1,40 @@
# 设计:`lib/datetime` / `lib/日期时间`(Mid2 M7)
| | |
|---|---|
| 状态 | **已落地** |
| 日期 | 2026-09-09 |
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §2.1 |
| 宿主 | `src/host/datetime.rs` · `host_datetime_*` |
---
## 1. 时刻形状
每次返回 **map**:
| 键 | 含义 |
|----|------|
| `unix` | 秒级 Unix 戳(int) |
| `zone` | 固定偏移文本,如 `+08:00` / `+00:00` |
| `iso` | RFC3339(秒精度) |
`to_unix` 也接受裸 int 或 ISO 文本。
## 2. API
| EN | ZH | 说明 |
|----|-----|------|
| `now` | `现在` | UTC 此刻(wasm 无时钟桥则失败) |
| `from_unix` | `自戳` | `unix` + 可选 `zone` |
| `to_unix` | `成戳` | |
| `parse` | `解析` | 默认 RFC3339 / `YYYY-MM-DD[ HH:MM:SS]`;`pattern=` |
| `format` | `格式化` | `rfc3339`/`date`/`time` 或 strftime |
| `add` | `加` | `days`/`hours`/`minutes`/`seconds` |
| `in_zone` | `时区` | 同瞬间换区 |
**区名**:`+HH:MM` / `UTC` / `Z`,以及少量固定偏移别名(如 `Asia/Shanghai`)。**不做**完整 tzdb / DST。
## 3. 与 `lib/time`
`lib/time` 保留极简 unix/format/parse/sleep。日历语义用本库。
+25
View File
@@ -0,0 +1,25 @@
# 设计:`lib/fs` Mid2 加厚(M9)
| | |
|---|---|
| 状态 | **已落地** |
| 日期 | 2026-09-09 |
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §4 · [stdlib-fs-mid.md](stdlib-fs-mid.md)(M2) |
| 宿主 | `src/host/fs.rs` · `host_make_dirs` / `host_remove_tree` / `host_stat` / `host_walk` |
---
## API
| EN | ZH | 行为 |
|----|-----|------|
| `make_dirs` | `建目录树` | 递归创建(与既有 `make_dir` 同为 `create_dir_all`;显式命名) |
| `remove_tree` | `删目录树` | 仅删目录树;路径为文件则报错 |
| `stat` | `状态` | `{size, mtime_unix, is_file, is_dir}` |
| `walk` | `遍历` | **深度优先**;相对路径列表(正斜杠);含目录项;同级按名排序 |
既有 `remove` 对目录仍递归删除;`remove_tree` 拒绝文件,语义更窄。
## 刻意不做
ACL、watch、硬链接、`copy_tree`、惰性迭代器协议。
+19
View File
@@ -0,0 +1,19 @@
# 设计:`lib/html` / `lib/超文本`(Mid2 M8)
| | |
|---|---|
| 状态 | **已落地** |
| 日期 | 2026-09-09 |
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §3.2 |
| 宿主 | `src/host/html_ops.rs` · `host_html_escape` / `host_html_unescape` |
---
## API
| EN | ZH | 行为 |
|----|-----|------|
| `escape` | `转义` | `& < > " '` → 实体(`'` → `&#x27;`) |
| `unescape` | `还原` | 上述实体(含 `&#39;` / `&apos;`) |
**不做** DOM / 模板引擎。
+6 -4
View File
@@ -4,7 +4,7 @@
|---|---|
| 状态 | **M1–M6 已落地** |
| 日期 | 2026-09-07 |
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-abi.md](ext-abi.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
| 相关 | [stdlib.md](stdlib.md) · [stdlib-modules.md](stdlib-modules.md) · [ext-abi.md](ext-abi.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) · **后续** [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) |
| 目标 | 在接下来数个发版周期内,把「通用编程」能力沉到 **L0.5 宿主 + L1 `.mq.md`**,减少「凡是稍有能力就必须 ABI 插件」的路径依赖 |
---
@@ -123,10 +123,12 @@ OS / 算法库(精选 crate,默认 features 最小化)
| **M3** | `hash` / `哈希` · `secrets` / `机密` | sha256 / hmac;token | **done** |
| **M4** | `csv` / `逗号表` · `text` 加厚 | parse / stringify;contains / replace | **done** |
| **M5** | `table` 加厚 · `cli` / `命令行` | sort / zip;flags | **done** |
| **M6** | `log` / `日志` · `uuid` / `标识` | level 日志;v4 | 薄 host 或纯 mq |
| **可选** | `yaml` / `Toml` | 仅当 public/catalog 强需求 | 慎入 |
| **M6** | `log` / `日志` · `uuid` / `标识` | level 日志;v4 | **done** |
| **可选(Mid1)** | `yaml` | 默认 **不做** | 见 Mid2:优先 TOML |
**刻意延后:** 完整 `datetime` 时区库、连接池、异步 runtime、模板引擎、完整 `collections` 类型系统——等中层前几波用起来再议。
**Mid1 刻意延后、现已升格到 Mid2:** 日历/时区、URL 解析 —— 见 [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md)。
**仍不准入 Mid:** 连接池、异步 runtime、模板引擎、完整 `collections` 类型系统、HTTP 服务端 / SQLite(`ext/`)。
---
+139
View File
@@ -0,0 +1,139 @@
# 设计:中层标准库第二波(Mid2 · M7–M10)
| | |
|---|---|
| 状态 | **Accepted · M7–M10 已落地(zip 跳过)** |
| 日期 | 2026-09-09 |
| 缺口盘点 | [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) |
| 路线图 | [stdlib-mid2.md](../roadmap/stdlib-mid2.md) |
| 宪法 | [stdlib-mid.md](stdlib-mid.md) §3(准入 / 不准入 **不变**) |
| 目标 | 在 M1–M6 之上补「日历 · URL · 配置 · HTML 安全 · fs 再厚」,仍保持宿主面积极小 |
---
## 0. 一句话
**Mid2 = 第二档通用原语,不是第二套 stdlib。** 仍落在 `lib/` + 薄 `host_*`;禁止借机引入 YAML 全家桶、HTTP 服务端、数据库。
---
## 1. 分层与禁止
| 允许 | 禁止 |
|------|------|
| 新 `lib/*.mq.md` 中英对偶 | 新开 `lib-mid2/` 目录树 |
| 少数 `host_datetime_*` / `host_url_*` / `host_toml_parse` | 为 Mid 新增 ABI 插件 |
| 加厚既有 `fs` / `encoding` / `net` / `text` | 把 `ext/web` 能力下沉进 `lib/net` 服务端 |
| TOML **只读** | 完整 YAML 1.2、任意对象反序列化 |
| HTML **转义** | 模板引擎 / CSS 选择器引擎 |
---
## 2. M7 — `datetime` + `url`
### 2.1 `lib/datetime.mq.md` / `lib/日期时间.mq.md`
| 函数(英) | 中文建议 | 行为 |
|------------|----------|------|
| `now` | `现在` | 返回结构化时刻(见下)或 ISO 文本(二选一,实现时锁定) |
| `from_unix` / `to_unix` | `自戳` / `成戳` | 秒级;可选 `ms` |
| `parse` | `解析` | 支持 RFC3339 / 常见 `YYYY-MM-DD[ HH:MM:SS]` |
| `format` | `格式化` | strftime 子集或命名样式 `rfc3339`/`date`/`time` |
| `add` | `加` | `days`/`hours`/`minutes`/`seconds` 具名 |
| `in_zone` | `时区` | IANA 名或 `+08:00`;失败 → 诊断 |
**结构化时刻(建议 map)**:`{unix, zone, iso}` 或宿主不透明柄 + `_type=datetime`。优先 **map + 稳定字段**,便于 GFM/table 协作。
**刻意不做**:农历、营业日、完整 tzdb 热更新 UI、闰秒政治。
### 2.2 `lib/url.mq.md` / `lib/地址.mq.md`(或并入 `net`)
| 函数 | 行为 |
|------|------|
| `parse` | → `{scheme, userinfo, host, port, path, query, fragment}` |
| `query_parse` | `a=1&b=2` → map(多值用列表) |
| `query_stringify` | map → query |
| `join` | base + relative(可选,可二期) |
既有 `net.url_encode` **保留**;文档写清:编码单段用 `net`/`encoding`,解析整 URL 用 `url`。
**验收**:金样解析带 query 的 HTTPS URL;往返 query。
---
## 3. M8 — `toml` + `html` + `encoding` 加厚
### 3.1 `lib/toml.mq.md` / `lib/Toml.mq.md`(或 `配置表`)
| 函数 | 行为 |
|------|------|
| `parse` | TOML 文本 → Marqdo map/list(只读) |
**不做** `stringify`(首版);需要写出时继续用 JSON。动机对齐 PEP 680:配置引导,而非通用文档格式战争。
### 3.2 HTML 转义
二选一(实现时定一):
- A:`lib/html.mq.md` · `escape` / `unescape`
- B:`text.html_escape` / `text.html_unescape`
推荐 **A**(安全语义独立可见)。
### 3.3 `encoding` 加厚
| 函数 | 行为 |
|------|------|
| `base32_encode` / `base32_decode` | RFC 4648 |
| (可选)`percent_decode` | 与 `url` 协作 |
---
## 4. M9 — `fs` 加厚
| 函数 | 行为 |
|------|------|
| `make_dirs` | 递归创建 |
| `remove_tree` | 递归删除(目录) |
| `stat` | `{size, mtime_unix, is_file, is_dir}` |
| `walk` | 返回路径列表(深度优先或广度;文档锁定) |
**不做**:权限 ACL、watch/inotify、硬链接全家桶。
---
## 5. M10 — 收口糖(可选)
| 项 | 说明 |
|----|------|
| `lib/stats` 或 `math.mean`/`median`/`stdev` | 极薄;非 pandas |
| `log` 结构化字段 | 可选 `fields=` map;非完整 slog 生态 |
| `zip` 读写 | **默认跳过**;有明确 Release 需求再开 |
---
## 6. 宿主与 WASM
| Host | WASM |
|------|------|
| `datetime` / `url` / `toml` / `html` / `fs.stat` | 尽量可进;IANA tz 数据体积需评估(可 host-only + 文档标注) |
| `fs.walk` / `remove_tree` | host-only 可接受 |
新 crate 写进 [dependencies.md](dependencies.md);禁止顺手拉大型框架。
---
## 7. 作者面风格
- 中英分文件;形参表声明全部可选并转发 `host_*`。
- 数据优先 GFM / `table`;`json` 仍只 parse/stringify/quote。
- 每波:设计短文 → host → lib → `tests/lib/*` → `public/features` 短页。
---
## 8. 完成定义(Mid2 整包)
1. 作者可用 `datetime` + `url` + `toml.parse` + `html.escape` 写配置驱动脚本,无需 foreign。
2. `fs.stat` / `make_dirs` 金样绿。
3. 研究文高优先级缺口标 closed;YAML/模板/sqlite 仍标明 won't。
4. [stdlib-modules.md](stdlib-modules.md) 总表更新;`stdlib.md` 状态改为 Mid2 进行中/完成。
+13 -6
View File
@@ -2,10 +2,10 @@
| | |
|---|---|
| 状态 | **核心已落地**;**中层 Mid:M1–M6 已落地** · [stdlib-mid.md](stdlib-mid.md) / [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
| 日期 | 2026-09-07 |
| 状态 | **核心已落地**;**Mid M1–M6 已落地**;**Mid2 规划中** · [stdlib-mid2.md](stdlib-mid2.md) / [roadmap/stdlib-mid2.md](../roadmap/stdlib-mid2.md) |
| 日期 | 2026-09-08 |
| 原则 | 全部经 frontmatter **导入**;除 JSON 外中英分文件;内核保持少而精;**通用能力优先 Mid,插件留给领域核** |
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-mid.md](stdlib-mid.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
| 相关 | [stdlib.md](stdlib.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-mid.md](stdlib-mid.md) · [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) · [ext-abi.md](ext-abi.md) · [ext-llm.md](ext-llm.md) · [ext-agent.md](ext-agent.md) · [**module-namespace.md**](module-namespace.md)(导入命名空间;**M1/M2 已落地**:`库.成员` / `库.对象.成员` / `use`) |
---
@@ -17,17 +17,22 @@
|--------|--------|--------|------|
| 文本 | `lib/text.mq.md` | `lib/文本.mq.md` | 已有 + **Mid M4** 加厚 |
| **正则** | `lib/re.mq.md` | `lib/正则.mq.md` | **Mid M1** |
| **编解码** | `lib/encoding.mq.md` | `lib/编码.mq.md` | **Mid M1** |
| **编解码** | `lib/encoding.mq.md` | `lib/编码.mq.md` | **Mid M1** + Mid2 M8 base32 |
| **路径** | `lib/path.mq.md` | `lib/路径.mq.md` | **Mid M2** |
| **哈希** | `lib/hash.mq.md` | `lib/哈希.mq.md` | **Mid M3** |
| **机密** | `lib/secrets.mq.md` | `lib/机密.mq.md` | **Mid M3** |
| **逗号表** | `lib/csv.mq.md` | `lib/逗号表.mq.md` | **Mid M4** |
| 表 | `lib/table.mq.md` | `lib/表.mq.md` | 已有 + Mid M4/M5:`sort`/`unique`/`zip`/… |
| **命令行** | `lib/cli.mq.md` | `lib/命令行.mq.md` | **Mid M5** |
| **日志** | `lib/log.mq.md` | `lib/日志.mq.md` | **Mid M6** |
| **日志** | `lib/log.mq.md` | `lib/日志.mq.md` | **Mid M6** + Mid2 M10 `fields=` |
| **标识** | `lib/uuid.mq.md` | `lib/标识.mq.md` | **Mid M6** |
| **日期时间** | `lib/datetime.mq.md` | `lib/日期时间.mq.md` | **Mid2 M7** |
| **地址** | `lib/url.mq.md` | `lib/地址.mq.md` | **Mid2 M7** |
| **配置表** | `lib/toml.mq.md` | `lib/配置表.mq.md` | **Mid2 M8** |
| **超文本** | `lib/html.mq.md` | `lib/超文本.mq.md` | **Mid2 M8** |
| **统计** | `lib/stats.mq.md` | `lib/统计.mq.md` | **Mid2 M10** |
| 浏览器效应 | `lib/browser.mq.md` | `lib/浏览器.mq.md` | WASM 客户端效应助手(GFM + helpers;勿用 `json.set` 链) |
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 + Mid M2:`copy_file` / `move` / `make_temp` |
| 文件 | `lib/fs.mq.md` | `lib/文件.mq.md` | 已有 + Mid M2 + **Mid2 M9**:`make_dirs` / `remove_tree` / `stat` / `walk` |
| 系统 | `lib/sys.mq.md` | `lib/系统.mq.md` | 已有(含 `load_dotenv`) |
| 时间 | `lib/time.mq.md` | `lib/时间.mq.md` | 已有 |
| JSON | `lib/json.mq.md` | **同文件** | **仅** parse / stringify / quote;集合请用 table / GFM |
@@ -42,6 +47,8 @@
**中层已落地:** M1–M6(含 log / uuid)— 见 [stdlib-mid.md](stdlib-mid.md) · [stdlib-log-uuid.md](stdlib-log-uuid.md)。
**Mid2:** **M7–M10 done**(datetime / url / toml / html / base32 / fs++ / stats / log.fields;zip 跳过)— [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-stats-log.md](stdlib-stats-log.md)。
设计细节:[stdlib-writeback.md](stdlib-writeback.md) · [stdlib-subtask.md](stdlib-subtask.md)。
---
+30
View File
@@ -0,0 +1,30 @@
# 设计:`lib/stats` / `lib/统计` 与 `log.fields`(Mid2 M10)
| | |
|---|---|
| 状态 | **已落地** |
| 日期 | 2026-09-09 |
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §5 |
| 宿主 | `src/host/stats.rs` · `host_stats_*`;`log::line` 可选 `fields` |
---
## 1. `lib/stats`
| EN | ZH | 行为 |
|----|-----|------|
| `mean` | `均值` | 算术平均 → Num |
| `median` | `中位数` | 排序后中位;偶数取两中点平均 |
| `stdev` | `标准差` | **样本**标准差(n≥2) |
**不做** dataframe、分位数全家桶、加权统计。
## 2. `log` `fields=`
各级别函数可选 `fields`(map)。宿主拼到行尾:`INFO msg key=val …`(map 插入序)。
**不做** 远程 sink、结构化 JSON 日志协议。
## 3. zip
按路线图 **默认跳过**。
+5 -4
View File
@@ -11,9 +11,9 @@
| 读 | 写 |
|----|----|
| 脚注 `` `xs`[^1] `` / `` `m`[^key] `` / 嵌套 `` `m`[^a][^1] `` | **`table.put` / `表.改`** |
| 链接取元 `[key](xs)` / `[key](m)` / 嵌套 `[1]([a](m))`(脚注 `` `m`[^k] `` 仍兼容) | **`table.put` / `表.改`** |
`put` / `改` 的 `at=`(`于=`)与脚注同构:文本键、**1-based** 整数下标,或键/下标组成的路径列表。
`put` / `改` 的 `at=`(`于=`)与取元同构:文本键、**1-based** 整数下标,或键/下标组成的路径列表。
```markdown
---
@@ -22,7 +22,7 @@ import table:lib/table.mq.md
# main
*`h` = > table.put in=None at=Authorization value=Bearer-x*
**`h` = [table.put] in=None at="Authorization" value="Bearer-x"**
`xs` =
@@ -31,7 +31,8 @@ import table:lib/table.mq.md
| a |
| b |
*`xs` = > table.put in=`xs` at=1 value=A*
**`xs` = [table.put] in=`xs` at=1 value="A"**
**打印 内容=[Authorization](h)**
```
`in=None` 且 `at=` 为单个文本键 → 新建单键字典。值一律不可变更新(返回新集合)。
+24
View File
@@ -0,0 +1,24 @@
# 设计:`lib/toml` / `lib/配置表`(Mid2 M8)
| | |
|---|---|
| 状态 | **已落地** |
| 日期 | 2026-09-09 |
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §3.1 |
| 宿主 | `src/host/toml_ops.rs` · `host_toml_parse`(手写子集,无 `toml` crate) |
---
## 1. API
| EN | ZH | 行为 |
|----|-----|------|
| `parse` | `解析` | TOML 文本 → map/list |
**不做** `stringify`;写出继续用 JSON。
## 2. 子集
支持:`#` 注释、基本/字面字符串、int/float/bool、标量数组、`[table]` 与 dotted key。
**不支持:** `[[array of tables]]`、内联表、TOML datetime、多行字符串。
+24
View File
@@ -0,0 +1,24 @@
# 设计:`lib/url` / `lib/地址`(Mid2 M7)
| | |
|---|---|
| 状态 | **已落地** |
| 日期 | 2026-09-09 |
| 父设计 | [stdlib-mid2.md](stdlib-mid2.md) §2.2 |
| 宿主 | `src/host/url_ops.rs` · `host_url_*`(手写子集,无 `url` crate) |
---
## 1. 与 `net.url_encode`
| API | 用途 |
|-----|------|
| `net.url_encode` | **单段** form 编码(空格→`+`) |
| `url.parse` | 整 URL → `{scheme,userinfo,host,port,path,query,fragment}` |
| `url.query_parse` / `query_stringify` | 查询串 ↔ map(重复键→列表;空格→`%20`) |
## 2. 解析子集
`scheme://[userinfo@]host[:port]/path[?query][#fragment]`,含 IPv6 `[addr]`。缺 path 时规范为 `/`。
**不做**:相对 URL join、完整 WHATWG 边角、IDNA 规范化(host 原样保留)。
+8 -5
View File
@@ -2,13 +2,15 @@
| | |
|---|---|
| 状态 | **S0–S3 + 核心 L1 已落地 · 中层 L1(Mid)规划中** |
| 日期 | 2026-09-07 |
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [**stdlib-mid.md**](stdlib-mid.md) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) |
| 状态 | **S0–S3 + 核心 L1 + Mid M1–M6 + Mid2 M7–M10 已落地** |
| 日期 | 2026-09-09 |
| 相关 | [keywords.md](keywords.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [lib-code-as-docs.md](lib-code-as-docs.md) · [stdlib-i18n.md](stdlib-i18n.md) · [stdlib-modules.md](stdlib-modules.md) · [**stdlib-mid.md**](stdlib-mid.md) · [**stdlib-mid2.md**](stdlib-mid2.md) · [module-namespace.md](module-namespace.md) · [ext-abi.md](ext-abi.md) |
> **库写法(代码即文档)**:[lib-code-as-docs.md](lib-code-as-docs.md) · [roadmap/lib-ext-code-as-docs.md](../roadmap/lib-ext-code-as-docs.md)。
> **多语言库命名**:见 [stdlib-i18n.md](stdlib-i18n.md)(不设 `lang:`;中英分文件)。
> **L1 模块清单**(含 math/foreign/plugin):见 [stdlib-modules.md](stdlib-modules.md)。
> **中层标准库(数个版本)**:通用原语沉 `lib/`、减少「事事插件」——设计 [stdlib-mid.md](stdlib-mid.md) · 路线 [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md)。
> **中层标准库 Mid(M1–M6)**:已落地——[stdlib-mid.md](stdlib-mid.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md)。
> **中层第二波 Mid2(M7–M10)**:已落地——[stdlib-mid2.md](stdlib-mid2.md) · [roadmap/stdlib-mid2.md](../roadmap/stdlib-mid2.md) · 缺口 [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md)。
> **`ext/` 不是 stdlib**:官方可选扩展见 [ext-llm.md](ext-llm.md) / [ext-agent.md](ext-agent.md)。
---
@@ -19,7 +21,8 @@
|----|------|
| **L0 内置** | 解释器内:`print` `input` `len` `str` `int` `type` `trim` `split` `join` `at`(`type` 可含 `map`) |
| **L1 核心** | 已有 [`lib/`](../../lib/):fs/sys/time/json/net/math/foreign/plugin/table/text/… |
| **L1 中层(Mid)** | 规划中:re / encoding / path / hash / csv / … — 仍在 `lib/`,见 [stdlib-mid.md](stdlib-mid.md) |
| **L1 中层(Mid)** | **已落地** re / encoding / path / hash / secrets / csv / text++ / table++ / cli / log / uuid — [stdlib-mid.md](stdlib-mid.md) |
| **L1 Mid2** | **已落地** datetime / url / toml / html / fs++ / stats / log.fields — [stdlib-mid2.md](stdlib-mid2.md) |
| **官方 ext** | [`ext/`](../../ext/)(`.mq.md` + 可选原生插件);`MARQDO_EXT`;**不属于** L1;插件仅领域热路径 |
| **L2** | catalog / 用户站收录(随发版);应主要靠核心+中层、默认无插件 |
+85
View File
@@ -0,0 +1,85 @@
# Ubuntu PPA packaging (Marqdo)
| | |
|---|---|
| Status | **Active** — `ppa:cflmy/marqdo`; noble builds need bundled Rust (Cargo.lock v4) |
| Maintainer | cflmy \<pingan@cflmy.cn\> |
| GPG | `505943294D04C803` (fingerprint `52A1…C803`) |
| PPA | `ppa:cflmy/marqdo` |
## Goal
Users install with:
```bash
sudo add-apt-repository ppa:cflmy/marqdo
sudo apt update
sudo apt install marqdo
```
CLI and extension packs stay independent: the `.deb` ships the **interpreter**; `marqdo ext add …` still pulls from **https://ext.marqdo.com** (then GitHub / proxy).
## Why bundled Rust?
Ubuntu **noble** ships cargo/rustc **1.75**, which cannot parse **Cargo.lock version 4** (`lock file version 4 requires -Znext-lockfile-bump`). Launchpad builders also have **no network**, so `ppa-build-source.sh` vendors crates **and** installs a modern toolchain into `third_party/rust` inside the `.orig.tar.xz`. `debian/rules` prefers that toolchain over distro cargo.
## One-time Launchpad setup
1. Create PPA: https://launchpad.net/~cflmy/+activate-ppa → name e.g. `marqdo`
2. OpenPGP key already on Launchpad (done)
3. Sign Ubuntu Code of Conduct if Launchpad asks
4. Enable the Ubuntu **series** you upload for (e.g. noble) under PPA → Change details
5. On the build machine:
```bash
sudo apt install build-essential debhelper devscripts dput lintian \
dpkg-dev quilt cargo rustc pkg-config curl xz-utils
```
## Package layout
| File | Role |
|------|------|
| `debian/control` | Metadata (amd64; no distro cargo BD) |
| `debian/changelog` | Upload revisions (`1ppaN`) |
| `debian/rules` | `dh` + bundled/system cargo build |
| `scripts/ppa-build-source.sh` | Vendor + bundle Rust + `debuild -S` |
| `scripts/ppa-ship.sh` | apt deps + build + `dput` |
## Versioning
- Upstream SemVer: `Cargo.toml` / git tag `vX.Y.Z`
- Debian revision: `X.Y.Z-1ppaN~SERIES` (SERIES = `noble`, …) — bump `1ppaN` on packaging-only reuploads
- **Ext pack** SemVer (`ext/VERSION`) is **not** the deb version
## One-shot (recommended)
```bash
cd ~/work/marqdo
./scripts/ppa-ship.sh noble # tools → debuild -S → dput
./scripts/ppa-ship.sh noble -n # build only
```
If automation cannot enter sudo/GPG, tell the user these commands (do not invent alternatives):
```bash
./scripts/ppa-build-source.sh noble
dput ppa:cflmy/marqdo ../build-area/marqdo_*~noble_source.changes
```
Watch: https://launchpad.net/~cflmy/+archive/ubuntu/marqdo/+builds
## Failure notes
| Symptom | Fix |
|---------|-----|
| `lock file version 4 requires -Znext-lockfile-bump` | Rebuild with current `ppa-build-source.sh` (bundles Rust); bump `1ppaN` |
| `failed to calculate checksum of: …/vendor/…/Cargo.toml.orig` | `dh_clean` purged `*.orig`; fixed via `dh_clean -Xvendor/` (+ strip `.orig` only when **creating a new** orig); bump `1ppaN` with **`-sd`** |
| `orig.tar.xz already exists … different contents` | Never rewrite an uploaded upstream `.orig`; reuse PPA file (`ppa-build-source.sh` downloads it) and `debuild -S -sd` |
| Same version rejected by Launchpad | Bump `debian/changelog` (`1ppa2`, …) |
| Wrong series | Enable series on PPA; rebuild with that series name |
## Out of scope (v1 deb)
- Shipping `ext/native/*.so` inside the deb (use CDN `ext add`)
- WASM / VSIX / non-amd64
+35
View File
@@ -0,0 +1,35 @@
# View:Markup 表面保真
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-09-14 |
| 相关 | [view.md](view.md) · [bracket-call-modifiers.md](bracket-call-modifiers.md) · [collection-access-link.md](collection-access-link.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) |
---
## 1. 目标
`marqdo view` 的 Structure / 表达式展示应**贴近作者写出的 Markup**,而不是内部 AST 的旧拼法。读者从 view 抄回源文件时,应仍是合法、推荐的表面。
## 2. 表面对照
| AST / 概念 | View 优先显示 | 备注 |
|------------|---------------|------|
| `Expr::Index` | `[键](基)` | 嵌套 `[k2]([k1](base))` |
| `InterpPart::Index` | 同上嵌套链接形 | 不再默认 `` `base`[^k] `` |
| `CallExpr` + `bracket_marked` / `pre_modifiers` | `修饰 [callee] 实参…` 或 `[callee] 实参…` | 仅经典 `>` 解析时仍显示 `> callee …` |
| 赋值 / 返回 | 粗体 / 斜体语义即可 | 不强制还原整句叙述 |
| foreach | `- [项](集合)` | 不变 |
## 3. 非目标
- 不把 view 做成第二语法;解析真相仍在 mapping / call-arguments。
- 不删除对脚注取元、旧 `>` 调用的兼容显示需求时,可用次要提示,但默认推荐面优先。
## 4. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿;Index 链接形 + 括号调用修饰表面 |
| 2026-09-14 | `bracket_marked`:无修饰的 `[callee]` 也保真显示 |
+1 -1
View File
@@ -4,7 +4,7 @@
|---|---|
| 状态 | 已定(v0.0.2 方向) |
| 日期 | 2026-08-04 |
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [view-markup-surface.md](view-markup-surface.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
---
+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)。
+1373
View File
File diff suppressed because it is too large. Load diff
+933
View File
@@ -0,0 +1,933 @@
这是marqdo的智能体框架,我一直都不满意,我认为marqdo的智能体框架应该更好才对,因为marqdo本身就是一门极好的AI原生语言,针对这个智能体框架,我的构想是,每次执行,智能体都会沉淀mq.md文档,超过三次的调用就会自动总结优化出一份类似与记忆的mq.md文档,把每一步都拆解的非常好,类似与人类的某些学习过程,当完全学习到了一些内容,实际上后续就可以不再每次都聚精会神,而是用一种较低能耗运行,就像是我们沉淀下来的mq.md代码,其中可以使用非常少的大模型思考,或者使用类似Jev的决策模型,或者干脆只使用分支控制,之后调用即可,你觉得呢?
对,而且我现在觉得你这个构想**很可能比目前的 Agent 框架本身更接近 Marqdo 真正应该成为的东西**。
我仔细看了你上传的 `ext/ai/agent`。其实你已经无意中铺好了不少基础:现在的 `plan` 已经有 `reuse`、`near_match`、`soft_match`、`promote`、`improve_every=3` 和 `kb_dir=.marqdo/agent-kb`;命中已有 skill 后甚至可以走 `llm_free` 路径。 而且现有逻辑已经会把成功的 workbook promote 到 agent KB。
**所以我觉得你现在缺的不是“memory”,而是一个更深的概念:Learning → Compilation。**
---
# 1. 我会把你想做的东西定义成:Agent 的“认知编译”
你描述的人类学习过程非常准确:
```text
第一次:
仔细思考
↓
尝试
↓
犯错
↓
修正
第二次:
仍然需要思考
↓
但已经有经验
第三次:
开始形成套路
多次之后:
“我知道怎么做了”
↓
不再重新思考
↓
直接执行
```
传统 Agent:
```text
User
↓
LLM
↓
Tool
↓
LLM
↓
Tool
↓
LLM
```
每次任务都重新付出推理成本。
你想让 Marqdo 变成:
```text
新任务
│
▼
是否已经学会?
/ \
是 否
│ │
▼ ▼
已编译 mq.md LLM 推理
│ │
▼ ▼
低成本执行 执行 + 观察
│
▼
沉淀 mq.md
│
▼
验证 / 优化
│
▼
编译成 Skill
```
我认为这个想法**非常漂亮**。
---
# 2. 而且这和 Marqdo 的语言设计天然吻合
这可能是你整个项目最重要的一次“闭环”。
你前面定义:
> `.mq.md` = Markdown + 可执行程序 + 知识。
现在 Agent 又产生:
> `.mq.md` = Agent 学会的经验。
于是:
```text
Agent
│
│ 学习
▼
.mq.md
│
┌───────┼────────┐
↓ ↓ ↓
知识 策略 程序
│ │ │
└───────┼────────┘
▼
Agent Skill
│
▼
低成本执行
```
这就非常有意思了。
**Agent 的 memory 不再是一段向量 embedding,也不只是聊天历史。**
它是:
> **可阅读、可修改、可验证、可执行的知识程序。**
这才是真正的 **Marqdo-native Agent**。
---
# 3. 你现在的 Agent 已经有这个雏形,但还没有真正“学习”
从你现在的代码看,已经存在:
```text
reuse
near_match
soft_match
promote
improve_every = 3
llm_free
```
这些机制实际上已经在做:
> **经验复用。**
例如当前逻辑会查找已有 KB,如果命中 `llm_free` skill,就可以直接运行 resource,而不是再让父 Agent 做一轮 LLM 推理。
这是很好的基础。
但我认为:
> **Reuse ≠ Learning。**
现在更像:
```text
成功任务
↓
保存
↓
以后查找
↓
复用
```
而你现在构想的是:
```text
成功任务
↓
观察多次执行
↓
抽象共同结构
↓
去掉偶然信息
↓
形成一般策略
↓
验证
↓
编译
↓
以后低成本执行
```
这两者差距非常大。
---
# 4. 我甚至建议你不要叫它 Memory
我会给它一个更有 Marqdo 味道的名字:
## **Skill Compilation**
或者:
## **Experience Compilation**
甚至:
## **Cognitive Compilation**
整个过程:
```text
Experience
↓
Episodic Trace
↓
Pattern Extraction
↓
Generalization
↓
Marqdo Skill
↓
Validation
↓
Compiled Skill
```
然后 Agent 不再只是:
> “记住我以前做过什么。”
而是:
> **“把以前的思考编译成以后不需要思考的程序。”**
我觉得这是一个非常强的概念。
---
# 5. 例如真的可以这样工作
第一次:
用户:
> 把这个 CSV 中年龄大于 18 的用户筛出来,并按照年龄排序。
Agent:
```text
LLM reasoning
↓
读取 CSV
↓
分析结构
↓
过滤
↓
排序
↓
输出
```
产生:
```text
.marqdo/agent-runs/xxx.mq.md
```
第二次用户:
> 把另一个 CSV 中年龄大于 18 的用户筛出来,并按照年龄排序。
Agent 发现:
```text
intent similarity = 0.94
```
于是:
```text
REUSE
```
直接调用之前的程序。
---
第三、第四、第五次:
Agent 发现:
```text
same structure
different file
different column names
```
这时候不应该继续保存五个:
```text
task1.mq.md
task2.mq.md
task3.mq.md
task4.mq.md
task5.mq.md
```
而应该让 LLM 总结:
```markdown
# Filter and Sort CSV Users
## Preconditions
- Input contains user records.
- An age field exists.
## Procedure
1. Read the input table.
2. Keep rows where `age > 18`.
3. Sort by `age` ascending.
## Variables
- `input`
- `age_field`
- `output`
## Exceptions
- Missing age field
- Invalid age
## Examples
| Input | Output |
|---|---|
| ... | ... |
```
然后:
```text
skill_status = compiled
```
---
# 6. 更关键的是:这个 mq.md 可以逐渐“去 LLM 化”
这是你刚才说的:
> “其中可以使用非常少的大模型思考,或者使用类似 Jev 的决策模型,或者干脆只使用分支控制。”
**我非常赞同。**
我甚至认为这应该成为 Marqdo Agent 的核心架构。
可以设计成一个:
# Cognitive Cost Ladder
```text
Level 0
Deterministic Marqdo
│
▼
Level 1
Rule / Branch
│
▼
Level 2
Small decision model
│
▼
Level 3
Small LLM
│
▼
Level 4
Full LLM reasoning
│
▼
Level 5
Multi-agent exploration
```
新问题:
```text
Full LLM
↓
learn
↓
Marqdo Skill
↓
validation
↓
Level 2/1
```
于是 Agent 会越来越“便宜”。
---
# 7. 这甚至给你提供了一个极漂亮的学习曲线
假设一个任务第一次需要:
```text
8 次 LLM calls
```
第二次:
```text
5 次
```
第三次:
```text
3 次
```
学习完成:
```text
0 次
```
或者:
```text
1 次 small model
```
这时候你就有一个非常漂亮的指标:
## Reasoning Amortization
定义:
$$
C_n =
\frac{
\text{LLM inference cost over first } n \text{ executions}
}{n}
$$
随着执行次数增加:
```text
Cost
│\
│ \
│ \
│ \
│ \____
│ ─────────
└───────────────────
executions
```
**这甚至解决了你之前担心的 Marqdo 性能难以证明的问题。**
你之前不知道怎么证明:
> Marqdo 比 Python 更适合 AI。
但现在你可以研究:
> **Marqdo Agent 能否把高成本 LLM reasoning 逐渐编译成低成本 executable knowledge?**
这个是一个非常明确、可测量、而且很有研究价值的问题。
---
# 8. 但是这里有一个非常重要的危险
你说:
> “超过三次调用就自动总结。”
我建议:
**不要真的这么简单。**
三次可以作为:
> **触发学习候选**
但不能作为:
> **自动认为已经学会。**
否则会发生:
```text
第一次:特殊情况
第二次:特殊情况
第三次:特殊情况
```
LLM 总结:
```text
General rule:
...
```
然后把偶然性错误“编译”进 Skill。
这会非常危险。
---
# 9. 我建议建立“经验 → 技能”的四阶段
## Stage 1 — Episode
每次任务产生:
```text
task
context
actions
tool calls
observations
errors
result
cost
```
例如:
```text
episode-001.mq.md
episode-002.mq.md
episode-003.mq.md
```
---
## Stage 2 — Candidate Skill
达到阈值之后:
```text
3+ similar episodes
```
让 LLM 总结:
```text
candidate.mq.md
```
但它还是:
> **candidate**
而不是正式 skill。
---
## Stage 3 — Verification
用历史任务重新运行:
```text
episode 1
episode 2
episode 3
```
测试:
```text
candidate skill
```
如果:
```text
3 / 3 success
```
再加新的 held-out task:
```text
episode 4
```
如果:
```text
4 / 4
```
才提高 confidence。
---
## Stage 4 — Compilation
最后:
```text
candidate
↓
verified
↓
compiled
```
此时才允许:
```text
llm_free = true
```
你目前的系统已经有 `llm_free` 命中后直接运行 resource 的机制。
我认为未来这个 flag **不应该是人工/静态指定的属性,而应该成为学习系统的产物。**
---
# 10. 甚至可以让 mq.md 自己记录“学习程度”
比如:
```yaml
---
type: skill
status: compiled
confidence: 0.97
evidence: 17
success_rate: 0.941
llm_free: true
created_from: 6c8...
last_validated: 2026-09-23
avg_reasoning_cost: 0.2
---
```
然后正文:
```markdown
# CSV 成人用户筛选
## Intent
筛选年龄大于 18 岁的用户。
## Procedure
- 读取 CSV
- 判断 age
- 过滤
- 排序
## Fallback
如果无法确定 age 字段:
> ask_llm
## Verification
| Case | Result |
|---|---|
| case-001 | ✓ |
| case-002 | ✓ |
| case-003 | ✓ |
| case-004 | ✓ |
```
注意这个设计里非常重要的一点:
> **Skill 本身可以包含一个 fallback 到 LLM 的路径。**
所以不是:
```text
学会 / 不会
```
而是:
```text
确定部分 → deterministic
不确定部分 → small model
真正未知 → full LLM
```
这就非常接近人类的实际认知过程。
---
# 11. 我甚至会把 Agent 的运行模型改成这样
```text
User Task
│
▼
┌─────────────────┐
│ Skill Resolver │
└────────┬────────┘
│
┌────────────┼────────────┐
▼ ▼ ▼
Exact Near Unknown
Hit Hit
│ │ │
▼ ▼ ▼
mq.md execute small model Full LLM
│ │ │
└────────────┼────────────┘
▼
Result
│
▼
Episode
│
▼
Experience Store
│
┌────────┴────────┐
│ │
repeated? novel?
│
▼
Skill synthesis
│
▼
Verification
│
▼
Compilation
│
▼
mq.md Skill
```
**这就已经不是普通 Agent framework 了。**
它是一个:
> **Self-compiling Agent**
---
# 12. 而 Marqdo 在这里有一个其他 Agent framework 很难天然拥有的优势
因为“学习结果”不是:
```json
{
"memory": "..."
}
```
也不是:
```text
embedding vector
```
而是:
```text
learned_skill.mq.md
```
这意味着用户可以:
```text
打开
阅读
修改
运行
测试
分享
Git commit
diff
fork
```
甚至:
```text
Agent A
↓
learned_skill.mq.md
↓
Agent B
```
**Agent 的经验第一次成为一种真正可移植的软件 artifact。**
我认为这是你整个 Marqdo 项目里非常值得深入挖掘的东西。
---
# 13. 而且它和你前面说的“Executable Knowledge”完全闭环
你之前提出:
```text
Executable Document
↓
Executable Knowledge Base
```
现在再往前一步:
```text
Executable Knowledge
↓
Agent Experience
↓
Agent Learning
↓
Compiled Knowledge
↓
Executable Skill
```
于是整个 Marqdo 可以形成:
```text
┌───────────────┐
│ Human │
└───────┬───────┘
│
▼
Natural Task
│
▼
AI Reasoning
│
▼
Executable Work
│
▼
.mq.md
│
┌───────┴───────┐
▼ ▼
Knowledge Skill
│ │
└───────┬───────┘
▼
Future Agent
│
▼
Less Reasoning
│
▼
More Execution
```
这就是我现在最喜欢 Marqdo 的地方:
> **Agent 不只是使用知识库;Agent 会把自己的经验沉淀成知识库,然后知识库反过来改变 Agent 的计算方式。**
这是一个真正的闭环。
---
## 最后,我会建议你对现有 Agent 做一个非常明确的架构升级
你现在已经有:
```text
reuse
near_match
soft_match
promote
improve_every=3
llm_free
```
所以**完全没必要推倒重来**。
我会把它演化成:
```text
Current Agent
│
┌────────┴────────┐
│ │
Execution Experience
│ │
│ ▼
│ Episode Store
│ │
│ ≥ N similar
│ │
│ ▼
│ Skill Synthesis
│ │
│ ▼
│ Skill Validation
│ │
│ ▼
│ Skill Compilation
│ │
└─────────────┬───┘
▼
.mq.md Skill
│
┌────────┼────────┐
▼ ▼ ▼
Branch Small LLM Full LLM
```
而且你当前已经有一个非常好的“终点”:**当 child 返回 value 时,可以 deterministic 地 solidify,而不是再次让父 LLM 发明 patch。** 当前代码已经明确这么处理。
所以我会把你的下一版 Agent 的核心 slogan 直接定成:
> **Think → Execute → Learn → Compile → Reuse**
或者更 Marqdo 一点:
> **Every successful thought can become executable knowledge.**
这比“Marqdo 有一个 Agent framework”强得多。
而且这件事**非常适合做你前面说的论文实验**:你甚至可以测一个 Agent 在重复任务上的 **LLM calls / tokens / latency / success rate 随经验次数变化的曲线**,直接验证“推理成本被 mq.md 技能逐渐摊销”的假设。这样 Marqdo 的 Agent、Executable Knowledge 和你之前苦恼的“性能怎么证明”三个问题,反而被同一个实验串起来了。
+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
+144
View File
@@ -0,0 +1,144 @@
# 调研:Mid M1–M6 之后标准库还缺什么
| | |
|---|---|
| 状态 | **调研笔记 · 缺口盘点(M1–M6 闭环之后)** |
| 日期 | 2026-09-08 |
| 基线 | **v0.3.7+** · Mid M1–M6 **done** |
| 已落地设计 | [stdlib-mid.md](../design/stdlib-mid.md) · [stdlib-modules.md](../design/stdlib-modules.md) · [roadmap/stdlib-mid.md](../roadmap/stdlib-mid.md) |
| 补齐设计 | [stdlib-mid2.md](../design/stdlib-mid2.md) |
| 实现路线 | [stdlib-mid2.md](../roadmap/stdlib-mid2.md) |
| 外部对照 | Python stdlib([use-case 索引](https://www.socratopia.app/library/python-programming-ai-era-en/chapter-15) · [PEP 680 tomllib](https://peps.python.org/pep-0680/))· Go `strings`/`regexp`/`encoding/*`/`crypto`/`path`/`time`/`net/url` · Node 内置 vs userland |
---
## 0. 一句话结论
**M1–M6 已把「写日常脚本 / 多数扩展库不再事事插件」的硬缺口补齐。** 相对 Python / Go 的「通用原语层」,Marqdo **不再缺** 正则、编解码、路径、哈希、CSV、集合糖、CLI、日志、UUID。
仍缺的是 **第二档通用能力**:日历与时区、URL/查询串、配置格式(优先 TOML)、HTML 安全转义、文件系统再厚一点(`mkdir -p` / 元数据 / 递归删除)、轻量统计。这些**值得开 Mid2(M7+)**,但**不应**再开一轮「事事插件」;也**不要**把 YAML 全家桶、HTTP 服务端、SQLite、图像/ML 塞进 `lib/`。
---
## 1. 已有基线(不是缺口)
| 族 | Marqdo | 对标 |
|----|--------|------|
| 文本 / 正则 | `text`++ · `re` | Python `str`/`re` · Go `strings`/`regexp` |
| 编解码 | `encoding`(base64/hex)· `net.url_encode` | Go `encoding/base64`/`hex` · Python `base64`/`binascii` |
| 路径 / 文件 | `path` · `fs`(含 copy/move/temp) | Go `path/filepath` · Python `pathlib`(子集) |
| 完整性 / 机密 | `hash` · `secrets` | Go `crypto` 子集 · Python `hashlib`/`secrets` |
| 表数据 | `csv` · `table`++ · `json` | Go `encoding/csv`/`json` · Python `csv`/`json` |
| CLI / 可观测 | `cli` · `log` · `uuid` | Python `argparse`/`logging`/`uuid`(窄) |
| 时间(极简) | `time`:unix/ms · format · parse · sleep | **远薄于** Python `datetime`/`zoneinfo` · Go `time` |
| 网络客户端 | `net`:HTTP/SSE/cookie/multipart/markdown | Go `net/http` **客户端**侧;服务端在 `ext/web` |
| 数学 | `math`(含公式/作图) | Python `math` + 教学向扩展 |
准入宪法仍见 [stdlib-mid.md](../design/stdlib-mid.md) §3:跨领域、难写对、解锁无插件写库、宿主面积极小。
---
## 2. 对照总表(按「脚本作者是否还要 foreign / 自造轮子」)
| 能力 | Python / Go 常态 | Marqdo 现状 | 缺口级别 | Mid2 建议 |
|------|------------------|-------------|----------|-----------|
| 日历日期 / 时区 / timedelta | `datetime`+`zoneinfo` · `time` | 仅 unix 戳 + 简单 format/parse | **高** | **M7** `datetime` |
| URL 解析 / 查询串 | `urllib.parse` · `net/url` | 仅 `url_encode` | **高** | **M7** `url`(或并入 `net`) |
| 配置 TOML 只读 | `tomllib`(PEP 680) | 无 | **中高** | **M8** `toml`(只读优先) |
| 配置 YAML | 第三方;**故意不进** CPython | 无 | **低 / 慎入** | 默认 **不做**;与 Python 同理(复杂度/安全) |
| HTML / XML 转义 | `html` · `html/template` 转义 | 无(`markdown_parse` ≠ 转义) | **中** | **M8** `html` 或 `text.html_escape` |
| `mkdir -p` / 递归删 / stat | `pathlib`/`shutil` | `make_dir`/`remove` 偏浅 | **中** | **M9** `fs` 加厚 |
| 文件元数据(size/mtime) | `os.stat` · `Path.stat` | 无一等 API | **中** | **M9** |
| base32 / percent 完整 | `base64.b32*` · `url` | 无 base32 | **低–中** | **M8** `encoding` 加厚 |
| 轻量统计 | `statistics` | `math` 无 mean/median | **低–中** | **M10** `stats` 或 `math` 薄加 |
| 计数 / 默认字典 / deque | `collections` | `table` 可凑 | **低** | 优先用 `table`;必要时 M10 `collections` 极薄 |
| 组合迭代 | `itertools` | 无 | **低** | 多数可用 `table`;**延后** |
| 模板引擎 | Jinja / Go `text/template` | 无 | **不准入 Mid** | 应用层 / 未来 ext |
| SQLite 客户端 | `sqlite3` · `database/sql` | **`ext/web` `# db`** | **不准入** | 保持扩展 |
| HTTP 服务端 | — | **`ext/web`** | **不准入** | 已关闭(宿主波次另文) |
| 密码哈希 Argon2 | 第三方 / 框架 | `ext/web` 已有 | **不准入 Mid** | 安全产品面 |
| 完整 TLS/证书 API | `ssl` · `crypto/tls` | 客户端 HTTPS 由 ureq | **不准入** | 宿主实现细节即可 |
| 压缩 zip/tar | `zipfile` · `archive/zip` | 无 | **低** | 可选 M10;体积敏感 |
| 环境 `.env` | 第三方;Go 常自写 | **`sys.load_dotenv` 已有** | 无 | — |
---
## 3. 分项说明(高优先级)
### 3.1 日历 / 时区(M7 候选之首)
**问题**
脚本与站点大量需要「今天」「本地日界」「RFC3339」「时区换算」。现有 `time.parse`/`format` 够演示,不够「难写对」的日历语义(闰秒除外,但 DST / offset 已够劝退字符串拼接)。
**对照**
Python 强调 **aware datetime + zoneinfo**;Go `time.Location` 是日常依赖。Mid 原文已把「完整 datetime 时区库」标为刻意延后——M1–M6 完成后应升格。
**建议窄 API(设计文锁定)**
`now` / `parse` / `format` / `add`(天/时)/ `to_unix` / `from_unix` / 可选 `in_zone`(IANA 或固定 offset)。**不做**完整历法 UI、农历、业务假期库。
### 3.2 URL 与查询串
**问题**
`url_encode` 只解决「编码一段」;解析 `https://a/b?x=1&y=2#frag`、合并 query、取 path 仍靠 `re` 自造。浏览器代理 / `invoke` / webhook 场景高频。
**建议**
`url.parse` → `{scheme,host,path,query,fragment}`;`url.query_parse` / `query_stringify`;与 `url_encode` 边界写进 `net` vs 新 `lib/url`。
### 3.3 TOML vs YAML
**外部事实**
Python 因 **打包引导**(`pyproject.toml`)接受只读 `tomllib`([PEP 680](https://peps.python.org/pep-0680/));YAML 多次被拒:规范复杂、实现难维护、安全面大。
**对 Marqdo**
catalog / 工具配置若走向 TOML,只读 `toml.parse` 性价比高。YAML:**默认不准入 Mid**;若 public 强需求,单独 ADR,且优先「JSON 超集子集」而非完整 1.2。
### 3.4 HTML 转义
**问题**
`ext/web` 与浏览器 WASM 拼 HTML 时,缺 `escape` 易 XSS。这是「难写对 / 安全相关」的经典 stdlib 项(Python `html.escape`)。
**建议**
极薄:`html.escape` / `unescape`(或挂 `text`)。**不做** DOM / 模板语言。
### 3.5 文件系统再厚
**问题**
`make_dir` 是否递归、`remove` 是否递归、无 `stat`(size/mtime)、无 `walk`——脚本仍会 `foreign` 或脆弱字符串。
**建议**
`fs.make_dirs` · `fs.remove_tree` · `fs.stat` · 可选 `fs.walk`(返回路径列表,非惰性迭代器协议)。
---
## 4. 明确「不是缺口」
| 项 | 说明 |
|----|------|
| Mid M1–M6 清单本身 | 已收口;不要用本表重开 base64/re |
| HTTP 服务 / DB / Agent | `ext/*`;见 [ext-hosting](ext-hosting-gaps.md) |
| Dense embedding / 向量库默认化 | OKF 路线不变 |
| 完整 `collections` / `itertools` 类型系统 | 语言没有泛型迭代协议;用 `table` |
| 「对齐 Python 模块个数」 | 反模式;对齐**用例与难写对** |
---
## 5. 优先级建议(转入 Mid2)
| 优先级 | 波次草案 | 内容 |
|--------|----------|------|
| **高** | **M7** | `datetime` + `url` — **done** |
| **高** | **M8** | `toml` 只读 + `html.escape` + `encoding` base32 — **done** |
| **中** | **M9** | `fs` 加厚(dirs/stat/walk) — **done** |
| **低** | **M10** | `stats` 薄 · log 字段 · (zip 默认跳过) — **done**(zip 仍跳过) |
| **won't** | — | 完整 YAML · 模板引擎 · sqlite 进 `lib/` |
---
## 6. 与其它文档
| 文档 | 关系 |
|------|------|
| [stdlib-mid2.md](../design/stdlib-mid2.md) | **补齐设计(作者 API + 边界)** |
| [stdlib-mid2.md](../roadmap/stdlib-mid2.md) | 实现波次 M7–M10 |
| [stdlib-mid.md](../design/stdlib-mid.md) | Mid1 宪法;本调研不改准入原则 |
| [web-net-capabilities.md](../design/web-net-capabilities.md) | 网络服务端能力在 ext,不进 Mid2 |
+77
View File
@@ -0,0 +1,77 @@
# 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` |
| **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`
@@ -0,0 +1,34 @@
# 盲测实验(§5.2(b) 查询式 vs 全文档背诵)—— 2026-09-23
| | |
|---|---|
| 模型 | `deepseek-flash` @ `https://llm.cflmy.cn/v1` |
| 样本 | 6 任务(业务 3 + QuixBugs 改写 3),oracle = stdout 精确匹配 |
| 协议 | 系统提示词 = 硬规则 12 条 + 契约表三形状(两臂同文);**唯一变量 = 语法来源**:`query` 臂 MLSP 查询通道(≤3 次)vs `docs` 臂完整 markup 参考(背诵) |
| 修复 | validate 诊断 + stderr 回喂,≤2 次修复;temperature=0,max_tokens=8000 |
## 汇总(判据:Q 通过率不劣于 D;首轮语法错误率 Q≤D;token Q≤70%%D;轮次不升)
| 臂 | 通过(一轮) | 通过(最终≤3) | 首轮语法错误 | 首轮契约诊断 | 平均修复轮(过例) | token 合计(prompt+completion) | 弃权/基础设施 |
|---|---|---|---|---|---|---|---|
| query | 0/3 | 0/3 | 2/3 | 1/3 | 0.00 | 69771(42478+27293) | 3 |
| docs | 3/6 | 4/6 | 2/6 | 0/6 | 0.50 | 57276(33346+23930) | 0 |
## 逐例
| 例 | 臂 | 结果 | 修复轮 | 首轮语法错 | 首轮契约诊断 | token(p+c) | 查询 | 备注 |
|---|---|---|---|---|---|---|---|---|
| claims_reserve_settle | query | load-fail | 0 | 是 | 否 | 11987+8177 | 3 | {"error":{"code":"mlsp.parse_error","message":"<memory>: trailing input in expression: \"(claim - deductible, 0)\""},"id":1,"ok":false} \| stderr=error: /tmp/marqdo_blind_1694593_query_claims_reserve_settle.mq.md: trailing input in expression: "(claim - deductible, 0)" |
| contract_milestone_pay | query | infra | 0 | 否 | 否 | 3970+4718 | 3 | 非 JSON / 空体: |
| vendor_po_gate | query | load-fail | 0 | 是 | 否 | 9552+3686 | 3 | 回复中无程序 \| 开头: QUERY: 条件分支 写法 |
| qb_gcd | query | run-fail | 0 | 否 | 是 | 9700+8488 | 3 | \| stderr=error: /tmp/marqdo_blind_1694593_query_qb_gcd.mq.md:26:1: unknown function `gcd(48` |
| qb_max_sublist_sum | query | infra | 0 | 否 | 否 | 1253+134 | 3 | 非 JSON / 空体: |
| qb_get_factors | query | infra | 0 | 否 | 否 | 6016+2090 | 3 | 非 JSON / 空体: |
| claims_reserve_settle | docs | pass | 0 | 否 | 否 | 2699+2987 | 0 | queries=0 |
| contract_milestone_pay | docs | pass | 0 | 否 | 否 | 2800+3202 | 0 | queries=0 |
| vendor_po_gate | docs | pass | 0 | 否 | 否 | 2690+1264 | 0 | queries=0 |
| qb_gcd | docs | pass | 2 | 否 | 否 | 8147+6970 | 0 | queries=0 |
| qb_max_sublist_sum | docs | run-fail | 0 | 是 | 否 | 8518+3609 | 0 | \| stderr=error: /tmp/marqdo_blind_1694593_docs_qb_max_sublist_sum.mq.md:3:1: unknown function `[-2,` |
| qb_get_factors | docs | run-fail | 0 | 是 | 否 | 8492+5898 | 0 | \| stderr=error: /tmp/marqdo_blind_1694593_docs_qb_get_factors.mq.md:20:1: missing argument for parameter `value` |
报告由 `tests/blind_experiment.rs` 生成;材料冻结于 `tests/blind/`(任务书 + docs-bundle),判据见 `doc/roadmap/perf-validation.md` §2。
@@ -0,0 +1,34 @@
# 盲测实验(§5.2(b) 查询式 vs 全文档背诵)—— 2026-09-23
| | |
|---|---|
| 模型 | `mimo-v2.6-pro` @ `https://llm.cflmy.cn/v1` |
| 样本 | 6 任务(业务 3 + QuixBugs 改写 3),oracle = stdout 精确匹配 |
| 协议 | 系统提示词 = 硬规则 12 条 + 契约表三形状(两臂同文);**唯一变量 = 语法来源**:`query` 臂 MLSP 查询通道(≤3 次)vs `docs` 臂完整 markup 参考(背诵) |
| 修复 | validate 诊断 + stderr 回喂,≤2 次修复;temperature=0,max_tokens=8000 |
## 汇总(判据:Q 通过率不劣于 D;首轮语法错误率 Q≤D;token Q≤70%%D;轮次不升)
| 臂 | 通过(一轮) | 通过(最终≤3) | 首轮语法错误 | 首轮契约诊断 | 平均修复轮(过例) | token 合计(prompt+completion) | 弃权/基础设施 |
|---|---|---|---|---|---|---|---|
| query | 0/1 | 0/1 | 1/1 | 0/1 | 0.00 | 12428(10255+2173) | 5 |
| docs | 0/0 | 0/0 | 0/0 | 0/0 | 0.00 | 0(0+0) | 6 |
## 逐例
| 例 | 臂 | 结果 | 修复轮 | 首轮语法错 | 首轮契约诊断 | token(p+c) | 查询 | 备注 |
|---|---|---|---|---|---|---|---|---|
| claims_reserve_settle | query | infra | 0 | 否 | 否 | 1424+324 | 3 | 非 JSON / 空体: |
| contract_milestone_pay | query | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
| vendor_po_gate | query | infra | 0 | 否 | 否 | 1417+213 | 3 | 非 JSON / 空体: |
| qb_gcd | query | load-fail | 0 | 是 | 否 | 5011+1265 | 0 | {"error":{"code":"mlsp.parse_error","message":"<memory>: unexpected expression input: \"**y**\""},"id":1,"ok":false} \| stderr=error: /tmp/marqdo_blind_1710203_query_qb_gcd.mq.md: unexpected expression input: "**y**" |
| qb_max_sublist_sum | query | infra | 0 | 否 | 否 | 1216+172 | 3 | 非 JSON / 空体: |
| qb_get_factors | query | infra | 0 | 否 | 否 | 1187+199 | 3 | 非 JSON / 空体: |
| claims_reserve_settle | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
| contract_milestone_pay | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
| vendor_po_gate | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
| qb_gcd | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
| qb_max_sublist_sum | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: |
| qb_get_factors | docs | infra | 0 | 否 | 否 | 0+0 | 0 | 非 JSON / 空体: {"error":{"message":"upstream connection failed","type":"server_error","param":n… |
报告由 `tests/blind_experiment.rs` 生成;材料冻结于 `tests/blind/`(任务书 + docs-bundle),判据见 `doc/roadmap/perf-validation.md` §2。
+66
View File
@@ -0,0 +1,66 @@
# 路线图:代码即文档叙述面摩擦(G1–G4)
| | |
|---|---|
| 状态 | **Done**(实现已合入工作树;金样绿) |
| 日期 | 2026-09-14 |
| 设计 | [code-as-docs-gaps.md](../design/code-as-docs-gaps.md) |
| 样例 | `examples/code-as-docs/index.mq.md` |
---
## 里程碑
### M1 — 文档与金样夹具
- [x] 设计文档记录 G1–G4 与启发式
- [x] 本路线图
- [x] `tests/markup-v03/` 四缝金样 + `gold.rs` `markup_v03_*`
### M2 — G1 模块级 `---`
- [x] `parse_classified`:顶层 frame 行 skip;顶层 Comment 引言 skip
- [x] 函数体内 `---` / `***` 改为叙述跳过(不再收束;空返回收束)
- [x] 金样:`module-hr.mq.md`
### M3 — G3 浮点面量与运算
- [x] `Literal::Num(f64)`
- [x] `parse_primary` 识别 `digits.digits`(及 `.5` / `3.` 形态)
- [x] `eval_binary` + bytecode Int/Num 提升(Int/Int `/` 仍为整除)
- [x] 金样:`float-discount.mq.md`
### M4 — G2 叙述强调启发式
- [x] `scan_prose_line`:非代码形粗体、非返回形行内斜体 → 丢弃
- [x] 保持 `**n=n+1**`、`**加一 37**`、整行 `*n*`、「返回*n*」
- [x] 更新 Skill:允许装饰性强调;可执行仍看形状
- [x] 金样:`soft-emphasis.mq.md`
### M5 — G4 动态脚注键
- [x] AST:`IndexKey::{Lit,Var}`(`` [^`ident`] ``)
- [x] 解析、求值、bytecode
- [x] 金样:`dynamic-footnote.mq.md`
- [x] 回写 `examples/code-as-docs`(浮点折扣 + 动态键)
### M6 — 出门
- [x] `examples/code-as-docs` 展示四缝修复后的写法
- [x] `cargo test --test gold` 绿
- [x] 设计验收覆盖(见金样)
---
## 顺序建议
G1(小)→ G3(中,Literal/运算)→ G2(启发式,依赖金样钉行为)→ G4(AST 面)→ 回写样例。
---
## 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿 |
| 2026-09-14 | 实现完成并勾选 |
+8 -2
View File
@@ -39,6 +39,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)。
+59
View File
@@ -0,0 +1,59 @@
# Roadmap:lib / ext 代码即文档
| | |
|---|---|
| 状态 | **Active** |
| 日期 | 2026-09-14 |
| 相关 | [lib-code-as-docs.md](../design/lib-code-as-docs.md) · [view-markup-surface.md](../design/view-markup-surface.md) · [bracket-call-modifiers.md](../design/bracket-call-modifiers.md) · [collection-access-link.md](../design/collection-access-link.md) |
---
## 0. 总序(防返工)
1. **方括号标记调用**(设计 + AST + 金样)— **已落地**
2. lib / view 设计文档 — **已写**
3. View 表面(Index 链接形、括号调用)— **已落地**
4. 分波改造 `lib/*` → `ext/*`
旧 `>` / 粗体调用、脚注取元解析均保留。
## 1. 里程碑
| 波 | 内容 | 状态 |
|----|------|------|
| **Call** | `pre_modifiers`;`tests/structure/bracket-call.mq.md`;mapping / call-arguments | **done** |
| **M0 View** | `InterpPart::Index` → `[k](base)`;`call_display` 修饰表面 | **done** |
| **M1** | 试点 `lib/table` · `lib/text` · `lib/json`(中英)+ public/stdlib | **done** |
| **M2** | 其余 `lib/*` 叙述化;禁新脚注取元 | **done** |
| **M3–M4** | `ext/web`、`ext/ai`:脚注→链接取元;叙述;示例可逐步换括号调用 | **done**(取元迁移) |
| **M5** | quantum / linalg + full gold | **done** |
| **M6** | examples + public/structure + tests/ext·lib 链接取元;cafe 括号调用例 | **done** |
| **M7** | structure collection 金样改链接形;public/stdlib 括号调用例 | **done** |
| **M8** | 教程第 9 章 + Skill examples → 链接取元 / v0.3 标记 | **done** |
| **M9** | 教程其余章节(1–8、10–12、14)全面对齐 v0.3 + 链接取元 | **done** |
| **M10** | public/stdlib 剩余演示统一括号调用;public import 返回面修到 v0.3 | **done** |
| **M11** | View:`bracket_marked` 使无修饰 `[callee]` 也显示括号形 | **done** |
## 2. 验收(出门)
- 括号调用与 `[k](c)` 取元金样并存、不回归。
- 试点库可读:目的句 + 叙述形参 + 一例 + 短实现。
- `cargo test --test gold` 绿。
- 脚注取元金样(`tests/structure/footnote*`)仍保留作兼容门禁。
- 教程与 Skill 示例以链接取元 / `**` 代码 / `*` 返回为准。
## 3. 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-14 | 初稿;Call + M0 标 done |
| 2026-09-14 | M1 试点 table/text/json + public/stdlib 标 done |
| 2026-09-14 | M2 其余 lib 叙述化标 done |
| 2026-09-14 | M3–M4 ext/web+ai 脚注→链接取元 |
| 2026-09-14 | M5 quantum/linalg 叙述 + public/features 取元 |
| 2026-09-14 | M6 examples/public/tests 批量链接取元 + cafe 括号调用 |
| 2026-09-14 | M7 structure collection 金样 + stdlib 括号调用例 |
| 2026-09-14 | M8 教程 + Skill examples 同步 |
| 2026-09-14 | M9 教程全书对齐 v0.3 标记与链接取元 |
| 2026-09-14 | M10 public/stdlib 括号调用扫尾 + import 返回面 |
| 2026-09-14 | M11 View `bracket_marked` 无修饰括号调用表面 |
+111
View File
@@ -0,0 +1,111 @@
# 路线图:Marqdo Markdown 语法映射 v0.3(叙述统一)
「Markup」= Marqdo 把 Markdown 标记当成语法的那一层(不是另一个产品)。v0.3 = 现行映射:粗体代码、斜体返回。
| | |
|---|---|
| 状态 | **Done(v1.0.0)** |
| 日期 | 2026-09-13 |
| 设计 | [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) |
| ADR | [0005-prose-unified-markup.md](../adr/0005-prose-unified-markup.md) |
| 依赖 | 现有管线 [interpreter.md](interpreter.md) · [pipeline-debug.md](../design/pipeline-debug.md) |
---
## 目标
把 v0.3 宪法落到词法 → AST → 语义 → 双后端,使动机示例(加一函数)成为金样例,并安全迁移存量代码。
---
## 里程碑
### M0 — 设计冻结与双模式骨架(文档 ✅ / 代码 ⏳)
- [x] 设计文档 + ADR Proposed + 本路线图
- [x] **钉死**:空返回词法(设计 §7.2);提及/未使用变量(§4.4);升参 vs 绑定图(§8.2)
- [x] **钉死**:一行多 `**…**` 按序执行(设计 §12 #6)
- [x] **不做双模式** — 直接 v0.3 默认
**出门:** 设计评审通过;旗标可切换;无行为默认变化。
### M1 — 内联扫描与 AST
- [x] 金样例目录 `tests/markup-v03/`(夹具 + `gold.rs` `#[ignore]`;见目录 README)
- [x] `Prose` 行内联扫描:`` `ident` `` / `**…**` / `*…*`
- [x] `Stmt::Return` ← italic;`Stmt` ← bold Assign/Call
- [x] `Param.inferred` + 升参
- [x] `tests/markup-v03/` 金样通过(默认运行时)
**出门:** `cargo test markup_v03`(无 ignore)绿。
### M2 — 形参推断
- [x] `InferParams`:首次 `` `名` `` = 必选;`` `名`=默认 `` = 可选
- [x] 体赋值 `n=n+1` 不误判为默认
- [x] 与显式 `+` 合并规则 + 警告
- [x] 方法 `self`/`自` 排除
- [x] 金样例:默认实参、位置/具名调用、粗体内调用
**出门:** 推断签名与 `+` 兼容套件绿。
### M3 — 调用面与消歧
- [x] `**callee args**` ≡ `> callee args`
- [x] else 臂 `N. *` 与返回斜体消歧
- [x] 一行多 `**…**` 按序执行
- [x] 金样例:`---` / `*None*` / 整行 `**` / 兼容 `****`;叙述死绑定不升参
- [x] 诊断:必选缺失、未知 callee(已有 errors 金样);死变量不报错
- [x] 残缺粗体:与 GAP-06/07「未闭合后恢复」冲突,保持 Comment 跳过恢复,不硬报错
- [x] 粗体内表达式语句:`**n + 1**` 求值后丢弃(非误判为调用)
- [x] 叙述斜体:仅整行 / `返回*…*` / 表达式形当返回(`*very important*` 不收束函数)
**出门:** `tests/markup-v03/*` 覆盖设计 §9 示例。
### M4 — 双后端与工具
- [x] 字节码发射跟随新 Stmt 源
- [x] `view` / Structure:推断形参 `chip inferred` + Functions 大纲标注
- [ ] (可选)`marqdo migrate markup-v03` 机械改写提示/工具
**出门:** tree 与 bytecode 后端对 `markup-v03` 金样一致。
### M5 — 默认切换与存量迁移
- [x] 默认 `MarkupEdition::V03`
- [x] 迁移 `tests/**`、`lib/**`、`ext/**`、`public/**`、教程
- [x] 更新 `.cursor/skills/marqdo/SKILL.md` 硬规则
- [x] 修订 [markdown-mapping.md](../design/markdown-mapping.md) 为 v0.3 正式正文(或声明由 v0.3 文件接任)
- [x] ADR 0005 → **Accepted**
- [x] CHANGELOG / 发版说明(破坏性:标记对调)— **v1.0.0**
**出门:** 全量 gold 默认绿(live LLM 无钥跳过);无 v0.2 双模式。
---
## 非目标(本路线)
- 不改插件 ABI / Go libweb
- 不引入 `def`/`return` 关键字
- M0–M4 不强制改生产 `.mq.md`
---
## 风险
| 风险 | 缓解 |
|------|------|
| 标记对调导致海量假失败 | 双模式 + 分目录金样;默认晚切换 |
| 形参推断误伤局部变量 | 金样例钉启发式;允许过渡期写 `+` |
| 空返回 vs `**` 词法 | §7.2 已钉:整行 `**` = 空返回;推荐优先 `---` |
| 叙述反引号误升参 | §8.2 升参需可执行面读取;死绑定不进 params |
| Skill/AI 仍按 v0.2 生成 | M5 同步 Skill;过渡期文档标明版本 |
---
## 修订历史
| 日期 | 说明 |
|------|------|
| 2026-09-13 | 初稿与设计/ADR 同步 |
| 2026-09-13 | 空返回与提及性反引号决议合入;M0 文档项勾选 |
+1 -1
View File
@@ -18,7 +18,7 @@
| **诊断** | 语句级 `path:line:col: message`;字节码指令带 `spans`;errors 金样例双后端断言位置 | **P0 完成** |
| **view** | 结构 + 执行 + 源码 + 函数大纲/搜索;无断点 | 文档浏览器 |
| **debug** | 独立 `marqdo debug`:断点 / 单步 / locals(树遍历) | **P3-D3 v1** |
| **标准库** | 核心 L1 已完成([stdlib-modules.md](../design/stdlib-modules.md));下一主线 = **中层 Mid**([stdlib-mid.md](../design/stdlib-mid.md) · [stdlib-mid 路线](stdlib-mid.md)) | **P2 完成;Mid M1–M6 规划中** |
| **标准库** | 核心 L1 + Mid M1–M6 + Mid2 M7–M10 已完成([stdlib-modules.md](../design/stdlib-modules.md) · [stdlib-mid2.md](../design/stdlib-mid2.md)) | **P2 + Mid1 + Mid2 完成** |
| **模块** | [module-namespace.md](../design/module-namespace.md):**M1+M2 已落地**(库名绑定、`库.成员` / `use`;无扁平合并) | — |
用户点名的三件事都对,但**不能并行硬开**:断点调试依赖「可信位置 + 可暂停执行」;标准库依赖稳定运行时与 I/O;`input` 在 CLI 与 view 是两条路径。
@@ -0,0 +1,118 @@
# P4 验证汇总报告 — 2026-09-23
> 执行 [perf-validation.md](perf-validation.md)(自设计性能验证协议)的结果汇总。
> 覆盖 three-problems.md 三大问题的**验证矩阵**(§5.2 a–e)。逐例明细见各实验原始报告(文末索引)。
| | |
|---|---|
| 协议 | [perf-validation.md](perf-validation.md)(实验 (a)–(e)) |
| 判据源 | [three-problems.md](three-problems.md) §3.7 / 各问题 §2.4 |
| 构建 | marqdo v1.0.7(本仓库工作树;金 20 + 全量回归通过后采样) |
| 端点 | `llm.cflmy.cn/v1`(OpenAI 兼容;temperature=0) |
| 模型 | 修复实验:`cflmy`、`mimo-v2.6-flash`;盲测:`deepseek-flash`、`mimo-v2.6-pro`(按用户指定) |
| 回归 | 全量干净回归(无 API key 基线)**零失败** |
## 1. 五实验结果与判据对照
| 实验 | 判据 | 结果 | 判定 |
|---|---|---|---|
| **(a) 锚点消融**(T3.3,双模型×20例×双臂,三轮) | anchor 臂一轮修复率 ≥ 80%;护栏 0 次越界应用 | cflmy anchor **20/20=100%**(plain 17/20=85%);mimo-v2.6-flash anchor **20/20=100%**(plain 18/20=90%;容错加固中的第二轮 anchor 18/20=90% 亦 ≥80%);越界拒/越界应用 0/0 | ✅ 过 |
| **(b) 盲测**(查询式 vs 全文档背诵,6任务×2臂) | 四判据:最终通过率 Q 不劣于 D(允许 −0 例);首轮语法错误率 Q ≤ D;平均修复轮次 Q ≤ D;token ≤ 70% of D(首轮契约诊断率为观测项) | deepseek-flash:docs 4/6 vs query 0/3(3 例端点 infra 剔除);首轮语法错 2/3 vs 2/6;token 69,771 vs 57,276。mimo-v2.6-pro:两跑均端点 infra(12/12、11/12),**不可评估** | ❌ 四判据未全立 ⇒ 按 §3.7 继续改协议 |
| **(c) 契约消融**(四边界×三情形) | 带契约错值拦截 = 100%;带契约对值误报 = 0%;无契约路径零回归 | 拦截 4/4=**100%**;误报 0/4=**0%**;无契约 4/4 动态语义保持(含 `missing map key` 基线) | ✅ 过 |
| **(d) 防漂移演练**(9 漂移 + 2 负对照) | 故意写错必报 = 100%;对照组误报 = 0% | 必报 9/9=**100%**(`unknown_type`×2、`param_drift`×2、`return_mismatch`、`arg_mismatch`、`unknown_key`、`contract.duplicate`、`contract.unknown_table`);负对照误报 0/2 | ✅ 过 |
| **(e) 核心守卫演练**(3 种变异注入) | 单边改动必红;还原必绿 | 3/3 必红(`CORE_CONSTRUCTS` 私增、`core-surface.md` 私增、金样删除);还原全绿 | ✅ 过 |
**可复制结论(a/c/d/e 全过)**:锚点臂一轮修复率双模型 100%(判据 ≥80%,增量 +15pp/+10pp——易锚定样本近天花板,区分性留难样本扩展);契约系统"只在声明处拦截、零误报、不碰动态路径"成立;契约/实现互查防漂移 100% 必报;核心面单边膨胀被 CI 守卫机械阻断。
## 2. 实验 (c)(d)(e) 明细
### (c) 契约消融(tests/contract_ablation.rs,确定性)
四边界(调用实参 / 返回值 / 表绑定 / 键访问)各测三情形:
| 情形 | 口径 | 结果 |
|---|---|---|
| ① 带契约 + 错值 | 必须拦截(`contract.arg_mismatch` / `contract.return_mismatch` / `contract.field_mismatch` / `contract.unknown_key`) | 4/4 |
| ② 带契约 + 对值 | 不得报契约错(同路径同形状) | 0/4 误报 |
| ③ 无契约 + 错值 | 保持动态语义(不得出现 `contract.*`;走经典动态错误如 `missing map key`) | 4/4 |
取元一律用主推的 `[]()` 形(`[键](`集合`)`)验证;`集合[^键]` 过渡形保留兼容金样覆盖。
### (d) 防漂移演练(tests/drift_drill.rs,确定性)
9 个"故意写错"全部必报:类型词拼错、参数名漂移、升参未覆盖、返回越约、实参越约、未知键、重复契约表、错列表头契约表、运行时值越约。负对照 2 例(被绑定的数据表、纯动态程序)零误报。同时验证"契约表一经出现即为完整声明"(新升参未覆盖 ⇒ `contract.param_drift` warning)被按设计触发。
### (e) 核心守卫演练(人工变异,tests/core_surface.rs 必红验证)
| 变异 | 注入点 | 结果 |
|---|---|---|
| 私增 `ghost-construct` | `src/parse/mod.rs` `CORE_CONSTRUCTS` | 🔴 必红 |
| 私增 `ghost-construct` 行 | `doc/design/core-surface.md` | 🔴 必红 |
| 删除金样文件 | `tests/markup-v03/soft-emphasis.mq.md` | 🔴 必红 |
三次还原后 🟢 全绿。CI 守卫强制"清单与文档双改 + 全部金样存在"。
## 3. 实验 (b) 盲测:详况与诚实结论
### 协议
两臂系统提示词同文 = 硬规则 12 条 + 契约表三形状;**唯一变量 = 语法知识获取**:
- `query` 臂:MLSP 查询通道(`QUERY: <关键字>` ⇒ `mlsp syntax` 卡片,含戒律原文/样例/文档锚点;≤3 次)
- `docs` 臂:完整 markup 参考背诵(`tests/blind/docs-bundle.md`,背诵式全语法表 + 中文内建面)
任务 6 例(`tests/blind/tasks/`):业务 3(保险理赔准备金 / 工程进度款 / 采购付款门槛,均出自律所实测任务集)+ QuixBugs 改写 3(gcd / 最大子段和 / 质因数分解);oracle = stdout 精确匹配(任务书自带期望输出,把推理难度控制掉,失败归因于**语言能力**)。修复回路 ≤2 次(validate 结构化诊断 + stderr 回喂)。
### deepseek-flash(完成)
| 臂 | 通过(一轮) | 通过(最终) | 首轮语法错 | 平均修复轮(过例) | token(p+c) | infra 剔除 |
|---|---|---|---|---|---|---|
| query | 0/3 | 0/3 | 2/3 | – | 69,771(42,478+27,293) | 3/6 |
| docs | 3/6 | **4/6** | 2/6 | 0.50 | 57,276(33,346+23,930) | 0/6 |
- **docs 臂**:业务题 3/3 全部一轮通过(各 ~3k token);`qb_gcd` 修复 2 轮过;`qb_max_sublist_sum`、`qb_get_factors` 暴露真语法滑倒(列表字面量被当调用 `unknown function [-2,`;参数名漂移 `missing argument for parameter value`)。
- **query 臂**:查询通道**被积极使用**(5/6 例用满 3 次,多词查询如 `条件分支 写法` 也能正确命中卡片——已单独验证查询匹配无缺陷);但 3 例被端点空体吃掉,其余 3 例败于真语法错(Python 式元组 `(a, b)` ⇒ `trailing input in expression`;Python 式调用 `gcd(48, 18)` ⇒ `unknown function gcd(48`)与 1 例查询后未交程序。
### mimo-v2.6-pro(两跑均不可评估)
首跑 **12/12** 全部"非 JSON / 空体"(与 deepseek 并行时段)。三向探针(小提示词×12000/4000、大提示词×12000)证实**网关随机空体**、与 `max_tokens`/提示词体量无稳定关系。加重试(8→12 次、退避 10→15 秒)并**单独**重跑后仍为 **11/12** 端点 infra(含两臂首聊即 `tok=(0,0)` 的空体);唯一执行到的 `qb_gcd` 例暴露真语法错(`**y**` 作语句 ⇒ `unexpected expression input`)。**结论:`mimo-v2.6-pro` 经本网关不可评估**,(b) 判据以 `deepseek-flash` 数据为准。原始报告:[blind-experiment-2026-09-23-mimo-v2.6-pro.md](blind-experiment-2026-09-23-mimo-v2.6-pro.md)。
### 判据对照(截至 deepseek-flash)
| 判据(协议 §2.4 原文口径) | 目标 | 实测(deepseek-flash,非 infra 口径) | 判定 |
|---|---|---|---|
| 最终通过率(≤3 轮)Q 不劣于 D(允许 −0 例) | ≥ D | 0/3 vs 4/6 | ❌ |
| 首轮语法错误率 Q ≤ D | ≤ | 2/3 vs 2/6 | ❌ |
| 平均修复轮次 Q ≤ D | ≤ | query 臂无通过例,不可比 | ⚠️ |
| token 用量 Q ≤ 70% of D | ≤ 40,093 | 69,771(D 的 121.8%) | ❌ |
| (观测项)首轮契约诊断率 Q ≤ D | – | 1/3 vs 0/6 | ➖ 观测 |
**诚实结论:在 deepseek-flash 上,"查询式"没有跑赢"全背诵"**——三项可判量化判据未达,按协议 §3.7 判定:**四判据未全成立 ⇒「AI 不必学语法」本轮未获实证,继续改协议**(不是证伪——infra 吞掉 query 臂一半样本,非 infra n=3)。要点:
1. **统计力被端点削弱**:query 臂 6 例中 3 例被空体吃掉(协议无从执行),非 infra 样本 n=3;mimo-v2.6-pro 整组不可用。判据是"有方向的强声明",当前证据**不足以支持也未证伪**其普适性,只能定格为"deepseek-flash × 本任务集 × 本协议版本"下的一次未达标观测。
2. **失败模式是真发现**:查询臂的败例是**跨语言习惯泄漏**(元组表达式、Python 调用形)——查询卡片能回答"条件分支怎么写",但模型不查询"这里能不能用元组"。说明"AI 不必学语法"的瓶颈不在**查询机制**,而在**模型的自查纪律**(不知道自己不知道)。
3. **token 判据方向存疑**:查询式省的是**系统提示词常驻**(背诵包),花的是**多轮往返**。6 例短程序任务里往返开销 > 常驻节省;该判据更适用于**长会话多文件**场景(一次背诵包 × N 轮 vs 每轮均摊查询),本轮任务形态低估了查询式的收益面。
4. **docs 臂的 4/6 说明任务集有区分度**(不是全过/全不过的退化测量)。
## 4. 测量端基础设施记录(方法学附注)
- **LLM 端点不稳定**是本轮最大的干扰源:随机空体、reasoning 模型 `finish=length` 截断(思考吃满额度、正文为空)。对策:空体重试 5→12 次 + 退避 5→15 秒、截断自适应(`max_tokens` 加倍重试,封顶 32k)、infra 例从判据比率中剔除并单列。
- **harness 缺陷两处**(已修,未污染最终数据):查询额度用满后的续篇被当最终回复(⇒ 假"无程序");程序提取失败不进修复回路(⇒ 少给模型一次标准修复机会)。修复后的协议对两臂完全一致。
- **模型口径变化留痕**:原定 `cflmy`/`mimo-v2.6-flash` 组合按用户指示弃用,改 `mimo-v2.6-pro`/`deepseek-flash`;修复实验 (a) 的双模型数据仍是原组合(金 20 协议已完成,不重跑)。
## 5. 材料与复现
```bash
# (a) 锚点消融(需要 API key)
cargo test --test repair_experiment -- --ignored --nocapture # anchor/plain 双臂×20例
# (b) 盲测(每模型一次;建议单独跑避免并发)
OPENAI_MODEL=deepseek-flash MARQDO_EXP_DATE=2026-09-23 cargo test --test blind_experiment -- --ignored --nocapture
# (c)(d) 确定性
cargo test --test contract_ablation --test drift_drill
# (e) 核心守卫(变异注入→必红→还原必绿,按 perf-validation.md §5 手法)
cargo test --test core_surface
```
- 任务书 / 背诵包(冻结,勿改):`tests/blind/`
- 原始报告:[blind-experiment-2026-09-23-deepseek-flash.md](blind-experiment-2026-09-23-deepseek-flash.md) · [blind-experiment-2026-09-23-mimo-v2.6-pro.md](blind-experiment-2026-09-23-mimo-v2.6-pro.md)(首跑全 infra)· [repair-experiment-2026-09-22.md](repair-experiment-2026-09-22.md) · [repair-experiment-2026-09-22-mimo-v2.6-flash.md](repair-experiment-2026-09-22-mimo-v2.6-flash.md)
- 判据协议:[perf-validation.md](perf-validation.md)(版本化于本仓库,实验前冻结)
+125
View File
@@ -0,0 +1,125 @@
# P4 性能验证设计(实验协议与判据)
| | |
|---|---|
| 状态 | **Accepted · P4 执行依据** |
| 日期 | 2026-09-23 |
| 授权 | 用户授权**自行设计**本性能验证设计(P4 不再等待外部文档导入;`doc/next/002.md` 与性能验证无关) |
| 上位判据 | [three-problems.md](three-problems.md) §5.1 判据矩阵 + §5.2 实验 (a)–(e);「判据矩阵全绿 + 实验数字可复现之前,三大问题一律视为未解决」 |
| 工程任务 | [three-problems-plan.md](three-problems-plan.md) Phase 1–3(已完成);本文只负责**验证它们** |
> **本文定位**:把 three-problems.md §5.2 的五个实验操作化——每个实验给出**材料、协议、指标、判据**,全部机器可执行、数字可复现。实验产物 = 报告 [perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)。**只认行为与数字,不认宣言。**
## 0. 总览
| 实验 | 验证对象 | 判据(全过 = 该问题的实证成立) | 执行方式 | 状态 |
|------|----------|-------------------------------|----------|------|
| (a) 锚点修复消融 | 问题三 · 可靠反馈 | 一轮修复率 ≥ 80%(anchor 臂),护栏 0 越界 | 模型在环 `tests/repair_experiment.rs` | ✅ 已完成(三轮双模型) |
| (b) 盲测 | 问题三 · 不必学语法 | 查询组错误率 ≤ 全文档组;token 显著更少;修复轮次不升 | 模型在环 `tests/blind_experiment.rs` | 见报告 |
| (c) 契约消融 | 问题二 · 语义校验 | 拦截率 = 100%;误报率 = 0%;无契约路径零回归 | 确定性 `tests/contract_ablation.rs` | 见报告 |
| (d) 防漂移演练 | 问题二 · 契约可信 | 故意写错契约必报率 = 100% | 确定性 `tests/drift_drill.rs` | 见报告 |
| (e) 核心守卫演练 | 问题一 · 核心要小 | 三种变异注入各必红 → 还原必绿 | 变异脚本(见 §4) | 见报告 |
判定口径([three-problems.md](three-problems.md) §5.1):**任何一项判据不成立,对应问题即「未解决」**——不许用文档宣言充数。
---
## 1. 实验 (a):锚点修复消融(问题三 · 可靠反馈)
**假设**:诊断带 `doc_anchor`/`doc_quote`/`suggestion`(锚点诊断)比裸诊断显著提高一轮修复率。
- **对照**:`anchor` 臂(全量诊断字段)vs `plain` 臂(剥掉 doc_anchor/doc_quote/suggestion)。
- **材料**:golden 20 例(10 骨架 × 2 变体:arg/ret/field/key/typo/drift/dup),易锚定错误。
- **协议**:`validate` → `repair_targets` → 模型行编辑 → `repair_apply`(越界必拒/abstain)→ 复验;≤2 轮。
- **指标**:一轮修复率、最终修复率、平均尝试、越界拒、弃权。
- **判据**:anchor 臂一轮修复率 ≥ 80%;护栏 0 次越界应用(越界必拒由 `tests/repair_loop.rs` 硬断言兜底)。
- **执行**:`OPENAI_MODEL=… cargo test --test repair_experiment -- --ignored --nocapture`。
- **结果**:三轮双模型全过(cflmy anchor 100% / mimo 90%→100%,plain 85%–100%,护栏 0 越界)——
详见 [repair-experiment-2026-09-22.md](repair-experiment-2026-09-22.md) 与
[repair-experiment-2026-09-22-mimo-v2.6-flash.md](repair-experiment-2026-09-22-mimo-v2.6-flash.md)。**✅ PASS**。
- **诚实注记**:样本为易锚定错误(两臂近天花板),锚点增量的区分性证据留待难样本扩展;不影响本判据达标。
## 2. 实验 (b):盲测——查询式 vs 全文档背诵(问题三 · 超级核心)
**假设**:「零语法文档 + MLSP 查询」组(Q)成绩**不劣于**「全文档背诵」组(D),且 prompt token 显著更少、修复轮次不升([three-problems.md](three-problems.md) §3.7 最终判据)。
### 2.1 对照(唯一变量 = 语法知识的获取方式)
| 臂 | 系统提示词内容 | 语法知识来源 |
|----|----------------|--------------|
| **Q 查询组** | 硬规则(12 条)+ 契约表三形状 + MLSP 查询通道说明 | 按需 `QUERY: <关键字>`(≤3 次,harness 代答 `mlsp syntax` 卡片) |
| **D 全文档组** | 硬规则(12 条)+ 契约表三形状 + **完整 markup 参考**(`tests/blind/docs-bundle.md`:v0.3 全语法表 + 中文内建面) | 上下文预载(背诵) |
两臂共同点:硬规则与契约表形状**同文**(受控变量,不测契约知识差异);修复回路相同(`mlsp validate` 诊断回喂,≤2 轮);模型 / 温度 / 任务 / 提示词模板相同。
### 2.2 材料:任务集(6 例,业务 3 + 算法 3)
| id | 类型 | 任务 | 功能 oracle(stdout 精确匹配) |
|----|------|------|-------------------------------|
| `claims_reserve_settle` | 业务 | 保险准备金(免赔/共保/分项限额/追偿/地板) | `28000` |
| `contract_milestone_pay` | 业务 | 工程里程碑应付款(保留金/逾期罚/变更/税/地板) | `37354` |
| `vendor_po_gate` | 业务 | 采购 PO 准付闸(折扣/加急/预算帽/合规费/地板) | `814` |
| `qb_gcd` | 算法 | 最大公约数;打印 gcd(48,18) gcd(1071,462) gcd(0,5) gcd(17,5) 各一行 | `6` `21` `5` `1` |
| `qb_max_sublist_sum` | 算法 | 最大子段和;三组输入各打印一行 | `6` `6` `-1` |
| `qb_get_factors` | 算法 | 质因数分解,因数以 `*` 连接;12 / 13 / 60 各一行 | `2*2*3` `13` `2*2*3*5` |
业务任务书复用 MarqdoThesis `formal/exp3-bizreq/data/tasks/`(权威规则文本原样进入提示词);算法任务书为 QuixBugs 改写(从「修 bug」改「实现 + 固定输出」,消除参考源码变量)。
### 2.3 协议(每例)
1. 提示词 = 任务书 + 「输出完整 `.mq.md` 源码于单个 ```markdown 围栏」;
2. **查询阶段**(仅 Q 臂):模型可输出 `QUERY: <关键字>` 行,harness 以 `mlsp syntax` 卡片作答并继续;累计 ≤3 次;
3. **执行阶段**:`marqdo run` → stdout == oracle 即通过;失败则回喂 `mlsp validate` 结构化诊断 + stderr,允许 ≤2 次修复;
4. 记录每轮 token(API `usage.prompt_tokens + completion_tokens` 累计)。
### 2.4 指标与判据
| 指标 | 口径 | 判据 |
|------|------|------|
| 功能通过率(一轮 / 最终≤3 轮) | stdout 与 oracle 精确匹配 | Q 最终通过率**不劣于** D(允许 −0 例) |
| 首轮语法错误率 | 首轮 `validate`/run 出现 parse 类失败的例数占比 | Q ≤ D |
| 首轮契约诊断率 | 首轮出现 `contract.*` 诊断的例数占比 | Q ≤ D(观测项) |
| 平均修复轮次 | 通过前的修复次数(含首轮生成记 0) | Q ≤ D |
| token 用量 | 逐例累计 prompt+completion | Q **显著更少**(≤ 70% of D) |
**判定**:四条判据全成立 ⇒ 「AI 不必学语法」实证成立;否则按 §3.7「继续改协议」,不得以改进文档充数。
- **执行**:`OPENAI_MODEL=… cargo test --test blind_experiment -- --ignored --nocapture`(每模型一轮)。
## 3. 实验 (c):契约消融(问题二 · 语义校验)
**假设**:契约只在**有契约处**拦截错误值(P1:无契约 = 全动态),且不误报。
- **材料**:`tests/contract_ablation.rs` 内联四边界用例(调用实参 / 返回 / 表绑定 / 字段访问)×三形态:
① 带契约 + 错值 → **必拦**(`contract.*` 诊断);② 带契约 + 对值 → **零误报**(正常产出);③ 同程序**删契约表** + 错值 → **零契约诊断**(动态语义原样)。
- **指标与判据**:
- 拦截率 = ①被拦 / ①总数 = **100%**;
- 误报率 = ②误报 / ②总数 = **0%**;
- 无契约零回归 = ③零 `contract.*` 诊断且输出 = 动态语义基线;且全量 `cargo test` 绿(441+ 既有测试是无契约路径的主回归面)。
- **执行**:`cargo test --test contract_ablation`。
## 4. 实验 (d):防漂移演练(问题二 · 契约可信)
**假设**:契约写错**必**被机器抓(不静默信任契约)——three-problems.md §2.8「故意写错契约的金样必红」。
- **材料**:`tests/drift_drill.rs`——故意写错契约的 N 例(类型 typo `nubmer`、未知对象类型、契约参数名 ≠ 升参名 ×2、返回契约明显不符、重复契约表、错位契约表)+ **负对照**(被绑定的 `字段|类型` 数据表 = web_db_migration 式,必须**不**被当契约吃掉)。
- **指标与判据**:
- 必报率 = 漂移例被诊断(`check` 报错/警告或运行时 `contract.*`)/ 漂移例总数 = **100%**;
- 负对照误报 = **0**。
- **执行**:`cargo test --test drift_drill`。
## 5. 实验 (e):核心守卫演练(问题一 · 核心要小)
**假设**:核心表面任何**单侧**变更(代码/文档/金样不同步)→ CI 必红——three-problems.md §1.5「新增标记不更新清单时 CI 必须红」。
- **材料**:`tests/core_surface.rs` 守卫 + 三种变异注入(脚本化,`git checkout` 还原):
1. `src/parse/mod.rs` `CORE_CONSTRUCTS` 增一行、不改文档 → **必红**;
2. `doc/design/core-surface.md` 表增一行、不改代码 → **必红**;
3. 金样文件改名(路径失效)→ **必红**。
- **指标与判据**:3/3 变异注入后守卫测试红;还原后全绿。**必红率 = 100%**。
- **执行**:报告内嵌演练记录(命令 + 测试输出摘录)。
## 6. 报告与复现
- 报告:[perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)((a) 引用既有两份实验报告;(b)–(e) 本次产出)。
- 复现命令全部写入报告各节;模型在环实验记录模型名与端点,判据数字允许 ±1 例波动(模型非确定性),**判据线本身不放宽**。
- 汇总结论回填 [three-problems-plan.md](three-problems-plan.md) 落地记录;§5.1 判据矩阵逐行标注 ✅/❌。
@@ -0,0 +1,64 @@
# 修复实验(§5.2(a) 锚点消融)—— 2026-09-22
| | |
|---|---|
| 模型 | `mimo-v2.6-flash` @ `https://llm.cflmy.cn/v1` |
| 样本 | golden 20 例(易锚定错误) |
| 协议 | `validate` → `repair_targets` → 模型行编辑 → `repair_apply`(越界必拒/abstain)→ 复验;≤2 轮 |
| 对照 | `anchor` = 诊断带 `doc_anchor`/`doc_quote`/`suggestion`;`plain` = 全部剥掉 |
## 汇总(设计目标:一轮修复率 ≥ 80%)
| 臂 | 一轮修复率 | 最终修复率(≤2轮) | 平均尝试 | 越界拒(护栏) | 弃权 |
|---|---|---|---|---|---|
| anchor | 20/20(100%) | 20/20(100%) | 1.00 | 0 | 0 |
| plain | 18/20(90%) | 19/20(95%) | 1.05 | 0 | 1 |
## 逐例
| 例 | 臂 | 结果 | 轮次 | 越界拒 | 备注 |
|---|---|---|---|---|---|
| arg-num-a | anchor | 一轮修复 | 1 | 0 | |
| arg-num-a | plain | 一轮修复 | 1 | 0 | |
| arg-num-b | anchor | 一轮修复 | 1 | 0 | |
| arg-num-b | plain | 一轮修复 | 1 | 0 | |
| arg-text-a | anchor | 一轮修复 | 1 | 0 | |
| arg-text-a | plain | 一轮修复 | 1 | 0 | |
| arg-text-b | anchor | 一轮修复 | 1 | 0 | |
| arg-text-b | plain | 一轮修复 | 1 | 0 | |
| drift-cover-a | anchor | 一轮修复 | 1 | 0 | |
| drift-cover-a | plain | 一轮修复 | 1 | 0 | |
| drift-cover-b | anchor | 一轮修复 | 1 | 0 | |
| drift-cover-b | plain | 一轮修复 | 1 | 0 | |
| drift-rename-a | anchor | 一轮修复 | 1 | 0 | |
| drift-rename-a | plain | 一轮修复 | 1 | 0 | |
| drift-rename-b | anchor | 一轮修复 | 1 | 0 | |
| drift-rename-b | plain | 一轮修复 | 1 | 0 | |
| dup-delete-a | anchor | 一轮修复 | 1 | 0 | |
| dup-delete-a | plain | 一轮修复 | 1 | 0 | |
| dup-delete-b | anchor | 一轮修复 | 1 | 0 | |
| dup-delete-b | plain | 一轮修复 | 1 | 0 | |
| field-nullable-a | anchor | 一轮修复 | 1 | 0 | |
| field-nullable-a | plain | 一轮修复 | 1 | 0 | |
| field-nullable-b | anchor | 一轮修复 | 1 | 0 | |
| field-nullable-b | plain | 一轮修复 | 1 | 0 | |
| field-type-a | anchor | 一轮修复 | 1 | 0 | |
| field-type-a | plain | 一轮修复 | 1 | 0 | |
| field-type-b | anchor | 一轮修复 | 1 | 0 | |
| field-type-b | plain | 一轮修复 | 1 | 0 | |
| key-fix-a | anchor | 一轮修复 | 1 | 0 | |
| key-fix-a | plain | 未修复 | 1 | 0 | 模型弃权/输出不可解析: [{"op":"replace","line":13","text":"*`用户`[^name]*"}] |
| key-fix-b | anchor | 一轮修复 | 1 | 0 | |
| key-fix-b | plain | 二轮修复 | 2 | 0 | 修复后仍有诊断: {"code":"marqdo.error","contract_ref":null,"doc_anchor":null,"doc_quote":null,"message":"missing map key `phone`","severity":"error","span":{"col":1,"file":"/tmp/marqdo_repair_1666049_plain_key-fix-b.mq.md","line":14},"suggestion":null} |
| ret-type-a | anchor | 一轮修复 | 1 | 0 | |
| ret-type-a | plain | 一轮修复 | 1 | 0 | |
| ret-type-b | anchor | 一轮修复 | 1 | 0 | |
| ret-type-b | plain | 一轮修复 | 1 | 0 | |
| type-typo-a | anchor | 一轮修复 | 1 | 0 | |
| type-typo-a | plain | 一轮修复 | 1 | 0 | |
| type-typo-b | anchor | 一轮修复 | 1 | 0 | |
| type-typo-b | plain | 一轮修复 | 1 | 0 | |
## 护栏核对
- 每次越界编辑都以 `mlsp.repair_out_of_scope` + `abstain` 被拒,且 `repair_apply` 全有或全无(源零字节不改)——由 `tests/repair_loop.rs` 的确定性断言覆盖;本实验计数仅作记录。
@@ -0,0 +1,64 @@
# 修复实验(§5.2(a) 锚点消融)—— 2026-09-22
| | |
|---|---|
| 模型 | `cflmy` @ `https://llm.cflmy.cn/v1` |
| 样本 | golden 20 例(易锚定错误) |
| 协议 | `validate` → `repair_targets` → 模型行编辑 → `repair_apply`(越界必拒/abstain)→ 复验;≤2 轮 |
| 对照 | `anchor` = 诊断带 `doc_anchor`/`doc_quote`/`suggestion`;`plain` = 全部剥掉 |
## 汇总(设计目标:一轮修复率 ≥ 80%)
| 臂 | 一轮修复率 | 最终修复率(≤2轮) | 平均尝试 | 越界拒(护栏) | 弃权 |
|---|---|---|---|---|---|
| anchor | 20/20(100%) | 20/20(100%) | 1.00 | 0 | 0 |
| plain | 17/20(85%) | 17/20(85%) | 0.85 | 0 | 0 |
## 逐例
| 例 | 臂 | 结果 | 轮次 | 越界拒 | 备注 |
|---|---|---|---|---|---|
| arg-num-a | anchor | 一轮修复 | 1 | 0 | |
| arg-num-a | plain | 一轮修复 | 1 | 0 | |
| arg-num-b | anchor | 一轮修复 | 1 | 0 | |
| arg-num-b | plain | 一轮修复 | 1 | 0 | |
| arg-text-a | anchor | 一轮修复 | 1 | 0 | |
| arg-text-a | plain | 一轮修复 | 1 | 0 | |
| arg-text-b | anchor | 一轮修复 | 1 | 0 | |
| arg-text-b | plain | 一轮修复 | 1 | 0 | |
| drift-cover-a | anchor | 一轮修复 | 1 | 0 | |
| drift-cover-a | plain | 一轮修复 | 1 | 0 | |
| drift-cover-b | anchor | 一轮修复 | 1 | 0 | |
| drift-cover-b | plain | 一轮修复 | 1 | 0 | |
| drift-rename-a | anchor | 一轮修复 | 1 | 0 | |
| drift-rename-a | plain | 一轮修复 | 1 | 0 | |
| drift-rename-b | anchor | 一轮修复 | 1 | 0 | |
| drift-rename-b | plain | 一轮修复 | 1 | 0 | |
| dup-delete-a | anchor | 一轮修复 | 1 | 0 | |
| dup-delete-a | plain | 一轮修复 | 1 | 0 | |
| dup-delete-b | anchor | 一轮修复 | 1 | 0 | |
| dup-delete-b | plain | 一轮修复 | 1 | 0 | |
| field-nullable-a | anchor | 一轮修复 | 1 | 0 | |
| field-nullable-a | plain | 未修复 | 0 | 0 | LLM 调用失败(重试后): 非 JSON / 空体: |
| field-nullable-b | anchor | 一轮修复 | 1 | 0 | |
| field-nullable-b | plain | 未修复 | 0 | 0 | LLM 调用失败(重试后): 非 JSON / 空体: |
| field-type-a | anchor | 一轮修复 | 1 | 0 | |
| field-type-a | plain | 一轮修复 | 1 | 0 | |
| field-type-b | anchor | 一轮修复 | 1 | 0 | |
| field-type-b | plain | 一轮修复 | 1 | 0 | |
| key-fix-a | anchor | 一轮修复 | 1 | 0 | |
| key-fix-a | plain | 一轮修复 | 1 | 0 | |
| key-fix-b | anchor | 一轮修复 | 1 | 0 | |
| key-fix-b | plain | 未修复 | 0 | 0 | LLM 调用失败(重试后): 非 JSON / 空体: |
| ret-type-a | anchor | 一轮修复 | 1 | 0 | |
| ret-type-a | plain | 一轮修复 | 1 | 0 | |
| ret-type-b | anchor | 一轮修复 | 1 | 0 | |
| ret-type-b | plain | 一轮修复 | 1 | 0 | |
| type-typo-a | anchor | 一轮修复 | 1 | 0 | |
| type-typo-a | plain | 一轮修复 | 1 | 0 | |
| type-typo-b | anchor | 一轮修复 | 1 | 0 | |
| type-typo-b | plain | 一轮修复 | 1 | 0 | |
## 护栏核对
- 每次越界编辑都以 `mlsp.repair_out_of_scope` + `abstain` 被拒,且 `repair_apply` 全有或全无(源零字节不改)——由 `tests/repair_loop.rs` 的确定性断言覆盖;本实验计数仅作记录。
+2 -1
View File
@@ -2,9 +2,10 @@
| | |
|---|---|
| 状态 | **M1–M6 已落地** |
| 状态 | **M1–M6 已落地**(收口) |
| 日期 | 2026-09-07 |
| 设计 | [stdlib-mid.md](../design/stdlib-mid.md) |
| 后续 | [stdlib-mid2.md](stdlib-mid2.md) · [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) |
| 相关 | [stdlib-modules.md](../design/stdlib-modules.md) · [next-phase.md](next-phase.md) · [ext-cli.md](../design/ext-cli.md) |
> **不预标 SemVer。** 每一波随当时产品发版合入;下文用 **M1…M6** 波次名。每波须可单独演示、可回滚。
+91
View File
@@ -0,0 +1,91 @@
# 路线图:中层标准库第二波(M7–M10)
| | |
|---|---|
| 状态 | **Completed · M7–M10 已落地(zip 跳过)** |
| 日期 | 2026-09-09 |
| 设计 | [stdlib-mid2.md](../design/stdlib-mid2.md) |
| 缺口 | [stdlib-gaps-after-mid.md](../research/stdlib-gaps-after-mid.md) |
| 前序 | [stdlib-mid.md](stdlib-mid.md)(**M1–M6 done**) |
| 基线 | v0.3.7+ |
> **不预标 SemVer。** 波次名 **M7…M10**;每波可单独演示、可回滚。
---
## 0. 总序
```text
M7 时间与地址 datetime + url
M8 配置与安全字面 toml(只读) + html.escape + encoding/base32
M9 文件再厚 fs make_dirs / remove_tree / stat / walk
M10 收口糖(可选) stats 薄 · log 字段 · (zip 默认跳过)
```
原则:
1. 继承 Mid1 宪法:通用、难写对、小宿主、可冻 API。
2. **TOML 优先于 YAML**(对齐 PEP 680 教训)。
3. 不阻塞宿主 / ext 产品线;但新「通用」ABI 插件默认拒绝。
---
## 1. 波次明细
### M7 — datetime + url — **done**
| 交付 | 说明 |
|------|------|
| `lib/datetime` · `日期时间` | now/parse/format/add/unix/zone 子集 |
| `lib/url` · `地址` | parse · query_parse/stringify(手写;无 `url` crate) |
| Host | `host_datetime_*` · `host_url_*` |
| 金样 | `tests/lib/datetime-smoke` · `url-smoke`(中英) |
| public | `14-datetime-url` · `14-日期时间地址` |
| 设计 | [stdlib-datetime.md](../design/stdlib-datetime.md) · [stdlib-url.md](../design/stdlib-url.md) |
### M8 — toml + html + encoding — **done**
| 交付 | 说明 |
|------|------|
| `lib/toml` · `配置表` | 只读子集 `parse` |
| `lib/html` · `超文本` | `escape` / `unescape` |
| `encoding` base32 | RFC 4648 |
| 金样 | `toml-html-encoding-smoke`(中英) |
| public | `15-toml-html-encoding` · `15-配置表超文本编码` |
| 设计 | [stdlib-toml.md](../design/stdlib-toml.md) · [stdlib-html.md](../design/stdlib-html.md) |
### M9 — fs 加厚 — **done**
| 交付 | 说明 |
|------|------|
| `make_dirs` / `remove_tree` / `stat` / `walk` | 见 [stdlib-fs-mid2.md](../design/stdlib-fs-mid2.md) |
| 金样 | `fs-mid2-smoke`(中英) |
| public | `16-fs-mid2` · `16-文件mid2` |
### M10 — 可选收口 — **done**(zip 跳过)
| 交付 | 说明 |
|------|------|
| `lib/stats` · `统计` | mean / median / sample stdev |
| `log` `fields=` | 行尾 `key=val` |
| zip | **跳过** |
| 金样 | `stats-log-smoke`(中英) |
| public | `17-stats-log` · `17-统计日志` |
| 设计 | [stdlib-stats-log.md](../design/stdlib-stats-log.md) |
---
## 2. 进度勾选
- [x] M7 datetime + url
- [x] M8 toml + html + base32
- [x] M9 fs 加厚
- [x] M10 可选(zip 跳过)
- [x] 研究文高优先级缺口 → closed(M7–M9;M10 为收口糖)
- [x] `stdlib-modules.md` / `stdlib.md` 状态同步
---
## 3. 成功标准
对外可宣称:在 Mid1(文本/路径/哈希/CSV/CLI/日志)之上,**日历、URL、TOML 配置、HTML 转义、实用 fs** 无需外联即可完成常见脚本与 catalog 工具——领域能力仍在 `ext/`。
+5 -2
View File
@@ -167,9 +167,12 @@
---
## 4. 脚注取元(提案)
## 4. 脚注取元(历史 · 过渡保留)
### 4.1 为何用脚注外形
> **主语法已切换为链接形** `[键](集合)`,见 [collection-access-link.md](../design/collection-access-link.md)。
> 本节 `` 集合[^键] `` 仍由运行时接受;**新代码请写链接形**。
### 4.1 为何曾用脚注外形
- Markdown 已有 `[^…]` 引用形态,读者不陌生。
- 避免 `篮子[0]` 与链接 / 图片语法纠缠。
+225
View File
@@ -0,0 +1,225 @@
# 三大问题落地计划(core 收口 · 渐进式契约 · MLSP)
| | |
|---|---|
| 状态 | **本期开发依据 · 执行中** |
| 日期 | 2026-09-22 |
| 设计 | [three-problems.md](three-problems.md)(解决方向与验证设计;判据矩阵 §5.1) |
| 范围 | **工程任务 = Phase 1–3**;验证实验(three-problems.md §5.2)协议见 [perf-validation.md](perf-validation.md)(2026-09-23 用户授权自行设计并执行) |
| 约定 | 每任务带机器可验证验收;**任务完成 = 验收全绿 + 全量回归绿**;只改宣言不改行为 = 未完成 |
## 0. 本期范围与依赖
| 阶段 | 定位 | 本期 |
|------|------|------|
| **Phase 1** 核心收口 + 诊断地基 | 一切的地基 | ✅ 启动 |
| **Phase 2** 渐进式契约层 | 校验层(schema 源头 = 表格/段落) | ✅ 本期主目标 |
| **Phase 3** MLSP(AI 语言服务) | **下一步的超级核心**(AI 不必学语法 + 可靠反馈闭环) | ⏭ 下期启动,本期只留接口 |
| **Phase 4** 验证实验 | 性能验证(非开发任务) | ❌ 不认领 |
依赖链(**跳步会倒逼「另造一套错误 / 另写一套 schema」的遮盖式捷径**):
```text
T1.4 Diagnostic ──是──> T2.x 契约诊断的唯一出口
T2.x 契约 ───────是──> T3.1 schema 注册表的主数据源
T1.1 core-surface ─是─> T3.1 语言面 + T1.3 守卫
```
---
## Phase 1 · 核心收口 + 诊断地基(本期启动)
### T1.1 核心表面清单
- **产出**:`doc/design/core-surface.md`
- **实现要点**:
- 两张表:**行构造**(heading-unit `#`/`##`、call-line `>`、branch-list `1.`、loop-list `-`、param `+ 名`、table、fence、hr、writeback、narrative、blank)与**内联标记**(ident `` `名` ``、bold-code `**…**`、italic-return `*…*`、empty-return、link-index `[键](集合)`、bracket-call `[函数]`、footnote-index `[^键]` 过渡);
- 每行含:**id**(英文 kebab,守卫用)、Markdown 外形、语义、**戒律**(边界 + 为什么不能是普通 Markdown)、**金样**(`tests/markup-v03/…` 路径);
- 与 [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md) §5 / §10 对齐;词法大类(`src/lex/mod.rs` `LineKind`)另列一节说明与构造表的关系。
- **验收**:每行金样文件真实存在(T1.3 断言);id 全集 = T1.3 `CORE_CONSTRUCTS` 全集。
### T1.2 三层归属与准入戒律
- **产出**:`doc/design/layers.md` + `.github/PULL_REQUEST_TEMPLATE.md`(无则新建)
- **实现要点**:
- 归属表(含仓库路径):Language = `src/lex` `src/parse` `src/ast` `src/interp` `src/diagnostics` + 契约检查器;Runtime = `lib/` `plugins/` `crates/` `src/catalog.rs` `src/view` `src/debug` + 未来的 check/schema/mcp;Document = `*.mq.md` `skills/` `ext/` `public/` `examples/`;
- 准入戒律:新特性先填层归属;进 Language 必答「为什么现有标记不够」;默认进 ext;核心标记计数每 release 只许持平或下降;
- 发布 checklist:CHANGELOG 增「核心表面 Δ」栏(写入 `skills/marqdo-release/SKILL.md` 一步)。
- **验收**:PR 模板含「层归属」必填项;layers.md 与 core-surface.md 互相引用闭合。
### T1.3 核心表面守卫(CI)
- **产出**:`tests/core_surface.rs` + `src/parse/mod.rs` 增 `pub const CORE_CONSTRUCTS: &[(&str, &str)]`(id、外形;**紧邻分类代码维护**)
- **实现要点**:`include_str!` 解析 core-surface.md 表格 id 列 ↔ `CORE_CONSTRUCTS` **双向集合相等**;每行「金样」路径 `Path::exists()` 断言。
- **验收(反遮盖核心)**:
- 新增 `CORE_CONSTRUCTS` 条目不改文档 → **红**;
- 文档加行不改代码 → **红**;
- 删除/改名金样文件 → **红**。
### T1.4 诊断对象扩展(Phase 2/3 的唯一出口)
- **产出**:`src/diagnostics.rs` 扩展 + `src/main.rs` `run --json`
- **实现要点**:
- `Diagnostic` 增 `code`(如 `parse.*` / `contract.*` / `runtime.*`)、`severity`、`suggestion`、`doc_anchor`、`doc_quote`、`contract_ref`(Phase 2 起填值);`::new/at` 签名不变(全仓调用零改动),新增 builder 方法;
- `serde::Serialize` + `to_json()`;**Display 保持 `path:line:col: message`**(人类输出零回归);
- `run --json`:顶层错误路径把 Diagnostic 序列化输出(stderr JSON 行)。
- **验收**:现有错误金样文本输出**零变化**;新金样断言 JSON `code`/`span` 非空;`cargo test` 全绿。
---
## Phase 2 · 渐进式契约层(本期主目标)
### T2.1 契约 AST + 提取器
- **产出**:`src/contract.rs`(`Contract` / `ParamContract` / `FieldContract` + 类型词汇 `text/number/bool/list/map/any/对象名`);`src/parse/`(提取);`src/ast.rs`(挂载,带 span)
- **实现要点**:按 [three-problems.md](three-problems.md) §2.3/§2.4——**未绑定文档表** + 列头关键字(`参数/返回/字段/类型/说明`)+ 允许位置(函数体首个可执行行前 / 绑定前 / 对象体首成员前);**被绑定的表永不视为契约表**。
- **验收**:三附着面金样 + 「绑定表不吃」反例金样(web_db_migration 式 `字段|类型|可空` 绑定数据表必须原样是数据);未知类型名(`nubmer`)必产诊断。
### T2.2 四边界运行时校验
- **产出**:`src/interp.rs` 接入四边界——调用实参 / 字段访问(`[键](集合)`、`.field`)/ 表绑定 / `*…*` 返回
- **实现要点**:只在**该边界有契约**时校验(无契约 = 全动态,P1);诊断一律走 T1.4 出口(`code=contract.*`)。
- **验收**:有契约 + 错值 → 必产诊断;**无契约路径全量回归零变化**;three-problems.md §5.2(c) 消融材料可产。
### T2.3 `marqdo check` + `--json`
- **产出**:`src/check.rs` + `src/main.rs` `Commands::Check`
- **实现要点**:静态**按需**校验(只查有契约处);不做全局推导。
- **验收**:契约样例工程 `check` 退出码非 0 且 JSON 合协议;干净工程 0 退出零输出。
### T2.4 锚点诊断
- **产出**:契约诊断填 `doc_anchor`(契约表行段 `file#Lx-Ly`)+ `doc_quote`(表行原文)
- **验收**:金样断言锚点非空且行号回读命中契约表;three-problems.md §5.2(a) 材料就绪。
### T2.5 契约 vs 实现互查(防漂移)
- **产出**:check + 运行时提示——契约参数名 ≠ 升参名 / 未知类型 / 返回契约明显不符 → 诊断
- **验收**:故意写错契约的金样**必红**(three-problems.md §5.2(d) 材料就绪)。
### T2.6 运行时内省 `get_schema`(可延后,P3)
- **产出**:`src/builtin.rs` 内省 builtin(契约是数据,P3)
- **验收**:demo 运行中取回自身函数契约并打印。
---
## Phase 3 · MLSP(下一步的超级核心;本期只留接口)
### T3.1 `marqdo schema`(schema 注册表,三来源零手写)
- **产出**:`src/schema.rs` + `Commands::Schema`——语言面(core-surface 机械转 JSON)+ 函数/类型面(**契约** + stdlib/ext 签名)+ 项目面(`catalog.yaml`)
- **验收**:两次生成 byte-identical;stdlib 主函数覆盖率 ≥ 90%。
### T3.2 `marqdo mcp`(AI 工具面)
- **产出**:MCP server(参考 `plugins/agent/src/mcp_server.rs`)——`syntax_list` / `syntax_get` / `fn_schema` / `type_schema` / `validate` / `repair` / `run`
- **验收**:MCP 客户端冒烟:`fn_schema` → `validate` → `repair` 全链路。
### T3.3 查询式 AI Skill
- **产出**:`skills/marqdo/` 改写——十条硬规则 + 查询工作流(construct → validate → 修 → run);细节一律走 `syntax_get` / `fn_schema`
- **验收**:skill 体积减半以上;金样全绿。
### T3.4 修复回路
- **产出**:repair 规则库 + 语句级 patch(AST span 对齐;预算 N=3;防循环)
- **验收**:注入 bug 金样一轮修复率可测(three-problems.md §5.2(a) 执行就绪)。
---
## Phase 4 · 验证实验(**协议 = [perf-validation.md](perf-validation.md)**)
- 2026-09-23 用户授权**自行设计**性能验证设计并执行验证;`doc/next/002.md` 与性能验证无关(此前「待导入」表述已纠正)。
- five 实验 (a)–(e) 的**材料由 Phase 1–3 的验收金样直接供给**;协议 / 指标 / 判据见 [perf-validation.md](perf-validation.md) §1–§5;
实验产物 = [perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)。
---
## 完成定义
| 阶段 | 完成定义 |
|------|----------|
| Phase 1 | T1.1–T1.4 验收全绿 |
| Phase 2 | T2.1–T2.5 验收全绿(T2.6 可延后) |
| Phase 3 | T3.1–T3.4 验收全绿 |
| 三大问题「已解决」 | [three-problems.md](three-problems.md) §5.1 判据矩阵全绿 + 实验数字可复现(Phase 4) |
## 落地记录
### Phase 2 · 渐进式契约层(2026-09-22 完成 T2.1–T2.5;T2.6 按计划延后至 Phase 3)
- **T2.1** `src/contract.rs`(类型词汇/三形状契约表解析/合并/四边界校验诊断)+
`src/parse/mod.rs::extract_function_contract`(位置 + 形状双重判定,**在升参推断之前**执行——
契约表的单元不会被误升参;契约表从 body 移除,元数据永不执行)。
反例守住:**绑定**的 `字段|类型` 数据表(web_db_migration 风格)绝不视为契约。
- **T2.2** 四边界全接:调用实参(普通/库路径/方法三条调用路径)、返回、表绑定、字段访问
(键存在性**先于**取值,契约诊断优先于 `missing map key`)。列语义按「几何即类型」:标量或全匹配列向量。
- **T2.3/T2.5** `marqdo check [FILE] [--json]`:契约行 vs 升参推断形参双向互查
(错行 ⇒ Error;新升参未覆盖 ⇒ Warning)、未知类型名(附最近建议)、错位契约;Error ⇒ 非零退出。
- **T2.4** 全部契约诊断带 `doc_anchor`(`file.mq.md#L7-L13`)+ `doc_quote`(契约表原文)+
`contract_ref`(`declared` = 契约声明摘要);`run --json` / `check --json` 同源输出。
- **附带修复(错误出口唯一)**:`src/load.rs` 原来把 parse 错误 `anyhow!("{label}: {e}")` 拍平成字符串,
结构化诊断在 import 装载链路丢失;改为 `label_error` 保留 Diagnostic(补文件标签),任何装载层都不许拍平错误。
- 验收:`tests/contracts.rs` 12 例(提取 4 + 四边界 4 + check 3 + 正向对照 1)全绿;
全量回归零失败(含 262 gold)。
- **T2.6(契约导出 `get_schema`)**:按计划延后至 Phase 3 与 MLSP `schema` 一并实现。
### Phase 3 · MLSP(2026-09-22 完成 T3.1–T3.4 全部工程项 + T2.6)
- **T3.1** `marqdo mlsp` 子命令:行分隔 JSON over stdio,请求 `{"id","method","params"}` →
响应 `{"id","ok","result"|"error"}`(永不 panic,错误也是结构化 JSON)。
- **T3.2** 五个 handler 全部实现(`src/mlsp.rs`):
`locate`(构造卡片 / 符号定位 + 契约)、`syntax`(关键字/别名 → 卡片;语法唯一事实来源 =
`parse::CORE_CONSTRUCTS`,MLSP 只加检索别名不定义语法)、`validate`(parse + 契约 check → 结构化诊断数组)、
`repair_targets`(有界修复靶点:`strategy=anchored-local`、`on_violation=abstain`——越界必拒护栏先行)、
`schema`(**T2.6 完成**:单元名 → 形参/返回/字段契约 + 升参清单 + 锚点)。
- 验收:`tests/mlsp.rs` 7 例全绿(语法问答/未知查询/符号定位/漂移校验/schema 导出/有界修复/结构化错误);
stdio 冒烟通过;全量回归零失败。
- **T3.4(修复回路)**(2026-09-22 完成工程项)——`src/repair.rs` **机械护栏**(有界行编辑
replace/delete/insert:触碰行必须落在靶点范围内,越界 ⇒ 整体拒绝 + 越界清单 + abstain,源零字节不改;
表尾追加允许 end+1)+ `mlsp repair_apply` 出口(护栏的 MLSP 面)+ **golden 20 例**
(10 骨架 × 2 变体:arg/ret/field/key/typo/drift/dup;金修复经完整修复循环复现——诊断 → 靶点 →
行编辑自动推导 → 范围自检(「易锚定」的机器验证)→ 应用 → 复验)+ 护栏负例(越界必拒/部分越界全拒)。
**模型实验完成(2026-09-22 · `tests/repair_experiment.rs` · 双模型三轮 @ llm.cflmy.cn)**:
§5.2(a) 锚点消融——`anchor` 臂(诊断带 `doc_anchor`/`doc_quote`/`suggestion`)**一轮修复率最高 20/20 = 100%**(目标 ≥80% ✅);
`plain` 臂(去锚)85%–100%。三轮汇总:
| 轮 | 模型 | anchor 一轮 | anchor 最终 | plain 一轮 | plain 最终 | 护栏越界 |
|---|---|---|---|---|---|---|
| 1 | `cflmy`(Qwen3.8-Flash-Next) | **20/20(100%)** | 100% | 17/20(85%) | 17/20 | 0 |
| 2 | `mimo-v2.6-flash`(容错加固中) | 18/20(90%) | 19/20(95%) | 19/20(95%) | 19/20 | 0 |
| 3 | `mimo-v2.6-flash`(容错补齐后) | **20/20(100%)** | 100% | 18/20(90%) | 19/20(95%) | 0 |
**"≥80% 一轮修复率"三轮双臂全部达标(最低 85%)**;护栏 0 越界(越界必拒/abstain 由确定性测试
`tests/repair_loop.rs` 硬断言覆盖)。实验同时是 `validate`→`repair_targets`→`repair_apply` 功能面的真实消费者。
**"不稳定"定性为三类测量端问题,均已加固**(与 Marqdo 语义无关):① 网关空体抖动 → curl `--retry` + 5s 退避;
② 推理模型 token 预算被 `reasoning_content` 吃光 → `max_tokens` 2000→8000;③ 模型输出格式畸形 → 解析容错
(数组/单对象/NDJSON 多对象流/字符串化元素/字符串型行号/围栏/数字后多余引号的确定性修补)。
锚点增量观察:易锚定样本两臂都高(天花板效应),cflmy 上 anchor +20pp 明显、mimo 上持平——
**锚点价值的区分性验证留 Phase 4**(难样本/信息受限消融)。
报告:[repair-experiment-2026-09-22.md](repair-experiment-2026-09-22.md)(cflmy)、
[repair-experiment-2026-09-22-mimo-v2.6-flash.md](repair-experiment-2026-09-22-mimo-v2.6-flash.md)(mimo 终测)。
- **T3.3(AI Skill 换骨:背语法 → 查 MLSP)**(2026-09-22 完成)——`marqdo` / `marqdo-dev` 两件套改为
查询式工作流:写码前 `mlsp syntax/locate`、提交前 `mlsp validate` + `marqdo check`;
渐进式契约三种表格形状入语法面;错误修复照 `doc_anchor` 局部改(越界必弃权)。
## Phase 4 · 验证执行记录(2026-09-23,协议 [perf-validation.md](perf-validation.md))
- **(a) 锚点修复消融** ✅ PASS——判据「anchor 一轮 ≥80% + 护栏 0 越界」:cflmy anchor 20/20=100%(plain 85%)、
mimo-v2.6-flash anchor 20/20=100%(plain 90%),越界拒/越界应用 0/0。易锚定样本近天花板,
增量区分性留难样本扩展(协议 §1 诚实注记)。
- **(b) 盲测(查询式 vs 全文档背诵)** ❌ 四判据未全立 ⇒ 按 three-problems.md §3.7 **继续改协议**——
deepseek-flash:docs 4/6 vs query 0/3(端点 infra 剔除 3/6);首轮语法错 2/3 vs 2/6;token 69,771 vs 57,276。
mimo-v2.6-pro 两跑均端点 infra(12/12、11/12,**不可评估**;结果回填 [perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md) §3)。
**真发现**:查询机制本身无缺陷(多词查询亦正确命中卡片),败例是**跨语言习惯泄漏**(元组表达式/Python 调用形)
——模型"不知道自己不知道"而不去查。协议改进主攻方向:**自查触发机制**(validate 前置自检、
陌生构造强制查询),而非继续改进卡片。
- **(c) 契约消融** ✅ PASS——拦截率 4/4=100%、误报率 0/4=0%、无契约零回归 4/4(四边界:调用实参/返回/表绑定/键访问)。
- **(d) 防漂移演练** ✅ PASS——必报率 9/9=100%(9 类故意写错全数诊断)、负对照误报 0/2。
- **(e) 核心守卫演练** ✅ PASS——3/3 变异注入必红(清单私增/文档私增/金样删除)、还原必绿。
- **判据矩阵回填**:three-problems.md §5.1 逐行标注——问题 1 ✅、问题 2 ✅、**问题 3 ❌(未解决)**。
- **测量端记录**:LLM 网关随机空体为最大干扰(重试 5→12 次、退避 5→15 秒、截断自适应 max_tokens);
harness 修复两处协议性 bug(查询额度用满误判、提取失败不进修复回路)后采样;
模型口径按用户指示由 `cflmy`/`mimo-v2.6-flash` 改 `mimo-v2.6-pro`/`deepseek-flash`(实验 (a) 数据为原组合,不重跑)。
- **全量干净回归**(无 API key 基线)零失败。
+393
View File
@@ -0,0 +1,393 @@
# Marqdo 三大问题:解决方向与验证设计
——证明「被解决」,而不是「被遮盖」
| | |
|---|---|
| 状态 | **设计 · 已导出本期开发任务:[three-problems-plan.md](three-problems-plan.md);验证实验不属于开发任务** |
| 日期 | 2026-09-22 |
| 来源 | [001.md](../next/001.md) 评审讨论提炼的三大问题;用户决议:**问题二走「渐进式契约 / 标注类型」**(拒绝照搬静态类型,也拒绝放弃语义校验);**问题三(AI 可靠反馈 + AI 不必学语法)是下一步的超级核心** |
| 相关 | [markdown-mapping-v0.3.md](../design/markdown-mapping-v0.3.md)(语法宪法)· [tables-maps-footnotes.md](tables-maps-footnotes.md)(表格几何)· [catalog-cli.md](../design/catalog-cli.md) · [ai-skill.md](../design/ai-skill.md) · [objects.md](../design/objects.md) · [interpreter.md](interpreter.md) |
> **本文定位:三大问题的解决方向与验证设计。** 给三大问题定义「什么算被解决」(机器可验证判据,见 §5.1)与验证实验(修复率 / 盲测 / 消融 / 防漂移演练,见 §5.2),把「真正解决」与「遮盖过去」区分开。文中的解决步骤(各节 S 表)是**设计方向**;本期开发任务、排期与验收以 [three-problems-plan.md](three-problems-plan.md) 为准。**验证实验(§5.2)协议见 [perf-validation.md](perf-validation.md)**(2026-09-23 用户授权自行设计并执行)。
>
> **一句话:语言核心收口是地基;渐进式契约是校验层,schema 直接长在表格与说明段落里;AI 语言服务消费这两者形成可靠闭环。** 三个问题必须一起解——契约是 AI 接口的数据源,核心收口是契约语法不膨胀的前提。
**贯穿戒律(防止「遮盖式解决」):每个阶段的验收必须是机器可验证的行为变化。只产出宣言文档、不改变工具行为的,一律视为未完成。**
---
## 0. 问题清单与依赖
| # | 问题 | 定位 | 一句话方案 |
|---|------|------|-----------|
| 1 | 语言核心正在被生态功能淹没,identity 不清 | **地基** | 三层归属表 + 准入戒律 + 核心表面守卫(CI 断言) |
| 2 | 「静态类型列为非目标」被误读为「不需要语义校验」;但照搬 Java/TS 静态类型会毁掉低摩擦 | **校验层** | **渐进式契约**:schema 写在表格 / 说明段落里;按需契约校验;诊断带文档锚点 |
| 3 | AI 反馈不可靠(只有给人看的文本);AI 还在背千行语法文档 | **超级核心** | **Marqdo Language Server for AI(MLSP)**:结构化诊断协议 + 可查询 schema + 修复回路 |
依赖链:
```text
问题 1(核心收口:契约语法不许越界进核心)
└─→ 问题 2(契约层:schema 源头 = 表格 / 说明段落)
└─→ 问题 3(schema 注册表 = 契约 + 核心表面 + catalog)
└─→ 实证(修复实验 + 消融基准 → README 愿景 6)
```
共享地基先行项:**统一诊断协议(Diagnostic)**——问题 2 的契约校验与问题 3 的 AI 反馈都以它为出口,因此它排在最前(见 §3.3 与 §4)。
---
## 1. 问题一:语言核心必须小
### 1.1 诊断
Marqdo 现在同时是:Markdown 语言 + literate programming + 知识库 + catalog + web + WASM + 浏览器 + LLM + agent + MCP + 量子 + 线代 + 插件 ABI。工程上这很酷;语言设计上的危险是:
> **核心语言的 identity 被生态功能淹没;新功能随手进核心 → 语法面暗中膨胀。**
真正缺的不是「收敛宣言」,而是**三样机制**:
1. 一份穷举的**核心表面清单**——现在「什么算核心」没有唯一明文;
2. 一张**三层归属表**——新提案无处登记,默认哪儿都塞;
3. 一条**越界即可见的守卫**——核心语法暗增长没有任何机器报警。
### 1.2 目标 / 非目标
**目标**:Language / Runtime / Document 三层分离;核心标记维持**约 15 个**的封闭集合,生态增长不再增加语言面。
**非目标**:删掉 web/quantum/agent 等功能(它们不是错,层次混放才是错);重写解释器;给核心加模块可见性等系统编程特性。
### 1.3 三层归属表(S1 产出物,此处先锁定语义)
| 层 | 内容 | 仓库位置 |
|----|------|----------|
| **Language** | 标记映射、词法/行分类、AST、语义、升参、**契约检查器**、诊断 | `src/`(解释器核心)· `doc/design/markdown-mapping-v0.3.md` |
| **Runtime** | stdlib、插件 ABI、WASM、debugger、view、catalog / schema CLI、MCP | `lib/` · `plugins/` · `crates/` · `src/bin` |
| **Document** | 知识单元、skills、示例、public 站、agent 工作流、官方扩展 | `*.mq.md` · `skills/` · `ext/` · `public/` · `examples/` |
核心表面清单(S1 的枚举基线,来自宪法 §5,逐项进 `core-surface.md`):
叙述(含 `` `名` `` 声明/引用)· `**…**` 代码 · `*…*` 返回 · 空返回形(`*None*` 等)· `>` 调用 · `#` / `##` 标题单元 · 体内 `1.` 分支 · `-` 循环 · GFM 表格 = 集合 · `[键](集合)` 取元 · `修饰… [函数名]` 方括号调用 · 脚注取元(过渡)· ` ```lang ` 外联 · `---` 叙述分隔 · `` + `名` `` 形参(兼容形)。
### 1.4 解决方向(设计 · 任务化见 plan)
| 步 | 动作 | 产出 | 验收(机器可验证) |
|----|------|------|--------------------|
| S1 | 写 `doc/design/core-surface.md`:穷举核心标记,每个标记一行「戒律」(语义、边界、**为什么不能是普通 Markdown**) | 核心表面唯一清单 | 清单项 ↔ `tests/markup-v03/` 金样逐项有例;缺项即测试红 |
| S2 | 写 `doc/design/layers.md`:§1.3 归属表 + **准入戒律**——任何新特性提案必须先填「进哪层」;进 Language 层必须答「为什么现有标记不够」,默认答案是「进 ext」 | 归属与准入制度 | 仓库 PR 模板加「层归属」必填项 |
| S3 | 核心表面守卫:Rust 测试断言「词法分类枚举 ↔ core-surface.md 表格」一致(脚本解析 markdown 表格比对枚举名) | `tests/core_surface.rs` | 故意加一个新标记不更新清单 → CI 红 |
| S4 | 核心变更强制走 ADR:新增核心标记必须有 `doc/adr/` 编号 + 反例说明;每个 release 的 CHANGELOG 单列「核心表面 Δ」 | ADR 戒律 | 发版 checklist 含「核心表面 Δ」栏 |
| S5 | 文档收口:README/doc 目录按三层重排;`doc/design/` 只收 Language 层决策,Runtime 进 `doc/roadmap/`,生态面进各自 ext 文档 | 重排后的文档树 | README 目录树与三层表一一对应 |
**观测指标**(不是 KPI,是体检):核心标记计数每个 release 只许持平或下降;连续 3 个版本增长即触发 Language 层复盘。
### 1.5 遮盖 vs 解决
| 遮盖式做法(禁止) | 本方案的做法 | 判据 |
|--------------------|--------------|------|
| 写一篇「语言核心很重要」的宣言 | 清单 + 归属表 + **CI 守卫** | 新增标记不更新清单时 CI 必须红 |
| 「以后尽量不加语法」的口头约定 | ADR 强制 + CHANGELOG 核心表面 Δ | 没有 ADR 编号的核心变更不允许合并 |
| 把 ext 功能砍掉显得小 | 不砍功能,只**归层** | web/quantum/agent 全部保留且测试通过 |
---
## 2. 问题二:渐进式契约 / 标注类型
### 2.1 分歧点澄清(本方案的立场)
GPT 一侧强调「AI 可验证语言需要强语义校验」,容易被听成「上静态类型」。**这两件事不一样**:
> 「放弃全程序静态编译类型」**≠** 「放弃语义检查、字段解析、契约校验」。
照搬 Java/TS 式静态类型会破坏「自然叙述优先、低摩擦」的体验——Marqdo 会变得笨重,丢掉对业务人员 / agent 即兴脚本的友好性。**目标不是变成静态语言,而是一套附着在文档单元上的可查询契约系统,作为 AI 闭环里的校验层。**
渐进式契约的四条特征:
1. **动态默认**——不强制任何标注,保持动态,适合快速原型与 agent 即兴脚本;
2. **契约即文档**——schema 可选地写在**表格、文档段落**里,不引入第二套标注语言;
3. **按需校验**——不做全局类型推导;在调用边界 / 字段访问时校验「当前值 vs 契约」;
4. **诊断即文档链接**——错误不只报类型错,还定位到文档里对应的说明段落,给 AI 的诊断自带文档上下文。
**独有优势(TS/Python 做不到)**:契约的 schema 源头就是表格与函数说明段落本身——不是额外写一套 JSON Schema。知识、契约、数据、代码在同一份 `.mq.md` 里,**契约即知识**。这是 Knowledge-Code Coherence 的第一个可落地实证:契约说 `int` 实际来了 `text` 时,被机器抓住的不是「文档过期」,而是**知识不一致**。
### 2.2 设计原则
| # | 原则 | 含义 |
|---|------|------|
| P1 | 无契约 = 全动态 | 没写契约的单元行为**一字不变**(零回归是硬验收) |
| P2 | 不新增核心标记 | 契约语法全部骑在现有 Markdown 外形上(问题一戒律直接约束本节) |
| P3 | 契约是数据 | 契约表本身就是 Marqdo 集合,运行时可内省(`get_schema` 一类的 lib 函数免费获得) |
| P4 | 双向防漂移 | 不只「值 vs 契约」,还查「契约 vs 实现」(§2.7-S5) |
| P5 | 诊断带锚点 | 凡契约诊断必含:契约表所在文件 + 行段 + 原文引用 |
### 2.3 契约的三个附着面
**A. 函数契约** —— `##` 函数体内、首个可执行行之前的**未绑定文档表**:
```markdown
## 加一
加一函数:把输入加一。
| 参数 | 类型 | 说明 |
|------|------|------|
| `n` | number | 输入值 |
| 返回 | 类型 | 说明 |
|------|------|------|
| — | number | n+1 |
对于输入变量`n`,执行**n=n+1**接着返回*n*。
```
参数仍由 v0.3 升参推断(宪法 §8),契约**不改变**形参机制,只在存在时校验——零摩擦兼容存量代码。
**B. 集合 / 表格契约** —— 紧邻 `` `名` = `` 绑定之前的未绑定文档表:
```markdown
| 字段 | 类型 | 可空 |
|------|------|------|
| id | number | 否 |
| name | text | 否 |
`用户` =
| 行 | id | name |
|----|----|------|
| 1 | 1 | 甲 |
```
**C. 对象契约** —— `# 对象` 体内首个成员之前的 `| 字段 | 类型 |` 表;同时被 catalog 提取为条目 schema(见 §3.5 项目面)。
**先例**:schema 长在表格里今天已经发生——`web_db_migration` 的 `| 字段 | 类型 | 可空 |` 列就是以数据形式传递的 DDL schema。契约系统把这个模式升格为**通用约定**。
### 2.4 形态选型(为什么是「契约表」)
| 候选 | 形态 | 判决 |
|------|------|------|
| **P-A 契约表**(选定) | 列头关键字(`参数`/`返回`/`字段`/`类型`/`说明`)的未绑定文档表 | ✅ 与「GFM 表格即数据」哲学一致;catalog 可提取;人读无负担 |
| P-B 叙述内标注 | `` `n`: int `` 写在散文里 | ❌ **否决**:改动行内 `` `名` `` 词法 = 核心标记变更,违反问题一戒律与 P2 |
| P-C frontmatter | YAML 声明契约 | ⚠️ 仅作文件级汇总的可选补充(serde_yaml 已在解析元信息);函数粒度不够,不作主形态 |
**消歧规则(防「契约表」误吃数据表)**:
1. **被绑定的表永不视为契约表**——`名` = 后的表是数据(宪法 §5:未绑定才「求值后丢弃」,即文档表)。`web_db_migration` 的列头恰好叫 `字段|类型|可空` 但它是绑定数据,不受影响;
2. 契约表必须是**未绑定文档表** + 列头命中关键字集,且出现在允许位置(§2.3 A/B/C);
3. 同一位置出现多张契约表:参数表与返回表各认各的列头;其余重复 → 诊断(防两份契约打架)。
### 2.5 类型词汇(刻意做小)
`text` · `number` · `bool` · `list` · `map` · `any` · 对象名(与 `# 对象` / `_type` 对齐)。
- 词汇表**只有这一行**;扩展类型词汇 = Language 层变更,走 ADR(问题一 S4)。
- 类型名拼错(如 `nubmer`)→ **必须报诊断**(§2.7 验收),否则契约本身成为新的漂移源。
### 2.6 校验时机(按需四边界,不做全局推导)
| 边界 | 校验什么 | 时机 |
|------|----------|------|
| 调用实参 | 实参值 vs 参数契约(类型 + 可选 required) | 运行时调用瞬间;`check` 静态可查处一并查 |
| 字段访问 | `[键](集合)` / `obj.field` vs 字段契约(键存在性 + 类型) | 访问瞬间 |
| 表绑定 | `` `名` = `` 表的几何/单元格 vs 集合契约 | 绑定瞬间 |
| 返回 | `*…*` 值 vs 返回契约 | 返回瞬间 |
无契约 → 该边界直接跳过(P1)。校验器**不是**编译器:不做跨函数全局推导、不要求全程序一致。
### 2.7 解决方向(设计 · 任务化见 plan)
| 步 | 动作 | 产出 | 验收(机器可验证) |
|----|------|------|--------------------|
| S1 | 契约提取器:按 §2.3/§2.4 规则解析未绑定文档表 → `Contract` 对象,挂入 AST 单元(`Param` 已有 `span`,契约同级带 `span`) | AST + 提取器 | 金样:三附着面各一份提取断言(含「绑定表不吃」反例) |
| S2 | 运行时边界校验:§2.6 四边界接入 `Contract` | 运行时校验 | 有契约 + 错值 → **必**产出 §3.3 诊断;无契约金样**全绿零回归** |
| S3 | `marqdo check`:静态按需校验(只查有契约处),`--json` 输出诊断 | CLI | 契约样例工程 `check` 退出码非 0 且诊断 JSON 合协议 |
| S4 | 诊断锚点:契约错误必带 `doc_anchor` + `doc_quote`(契约表原文行) | 诊断增强 | 金样断言诊断 JSON 里锚点字段非空、行号可回读原文 |
| S5 | **契约 vs 实现互查**(P4):契约参数名 ≠ 升参推断名、契约类型名未知、契约返回 vs 语句结构明显不符 → 诊断 | 防漂移检查 | 故意写错契约的金样**必须**红(而不是静默信任契约) |
| S6 | 运行时内省:`lib` 提供 `get_schema 单元=…`(P3:契约是数据) | lib 函数 | demo:运行中取回自身函数契约表并打印 |
### 2.8 遮盖 vs 解决
| 遮盖式做法(禁止) | 本方案的做法 | 判据 |
|--------------------|--------------|------|
| 把「静态类型」继续列为非目标就收工 | 明确「≠ 放弃语义校验」,落**边界校验器** | 运行时行为变化可测(§2.7-S2) |
| 照搬 Java/TS 全程序静态类型 | 渐进式:无标注零摩擦,按需四边界 | 无契约金样零回归 |
| 另写一套 JSON Schema 文件 | schema = 表格 / 说明段落本身 | 仓库里**不允许**出现手写的第二份 schema;契约只能从 `.mq.md` 提取 |
| 契约写了就永远正确 | 契约 vs 升参互查 + 未知类型名必报 | 故意写错契约的金样必红 |
| 错误只报 `type mismatch` 文本 | 诊断带文档锚点 + 原文引用 | 金样断言锚点字段 |
---
## 3. 问题三(超级核心):AI 可靠反馈 + AI 不必学语法细节
### 3.1 两个子问题
**A. 可靠反馈**:今天解释器诊断是给人看的文本(`path:line:col` + message,见 ai-skill「按诊断迭代」)。AI 拿到它要「猜」哪里错、对应文档哪句话、怎么改。GPT 设想的闭环——
```text
LLM → Marqdo → 语义校验 → 结构化 Error → LLM 修复 → 合格程序
```
——的第一块砖就是**结构化诊断**,而且诊断必须自带文档上下文(问题二 §2.1-4 的锚点在这里被 AI 消费)。
**B. 不必学语法**:今天 `skills/marqdo` 是「面向模型的压缩操作手册」= **背诵式**。正确形态是**查询式**:
```text
AI ── discover ─→ construct ─→ validate ─→ execute ─→ inspect
```
AI 不阅读一千行文档然后猜,而是按需调 `get_syntax("branch")`、`fn_schema("print")`、`validate(program)`。**这才是 Marqdo 与普通 DSL 拉开距离的地方。**
### 3.2 总形态:Marqdo Language Server for AI(MLSP)
一套机器可读的语言服务协议。工具面(首版最小集):
| 工具 | 入参 | 返回 | 数据源 |
|------|------|------|--------|
| `syntax_list` / `syntax_get` | — / 构造名 | 核心构造表 / 单构造戒律 | core-surface(问题一 S1,机械转 JSON) |
| `fn_schema` | 函数名 | 参数/返回契约 + 说明 + 锚点 | 契约(问题二)+ stdlib/ext 签名 |
| `type_schema` | 对象名 | 字段契约 + 方法表 | `# 对象` 契约 + catalog |
| `validate` | 程序文本/文件 | `Diagnostic[]` | 契约校验器 + 语义检查 |
| `repair` | 程序 + 诊断 | 建议 patch(限定行级) | 诊断规则库 |
| `run` | 入口 | 结果或结构化错误 | 运行时 |
交付通道(按序):**`marqdo mcp`**(MCP server,复用 agent ext 的 MCP 经验)→ CLI `--json`(任何宿主可用)→ `skills/marqdo` 改造成「教 AI 查询」(§3.6)。
### 3.3 先决:统一诊断协议(可靠反馈的地基)
所有层(解释器、check、契约、插件错误)统一产出:
```json
{
"code": "contract.arg_mismatch",
"severity": "error",
"message": "参数 `n` 期望 number,实际 text",
"span": { "file": "demo.mq.md", "line": 12, "col": 3, "heading": ["加一"] },
"doc_anchor": "demo.mq.md#L4-L7",
"doc_quote": "| `n` | number | 输入值 |",
"contract_ref": { "unit": "加一", "kind": "param", "name": "n", "declared": "number" },
"suggestion": "把实参改为数字;若契约有误,改契约表的类型列"
}
```
规则:
1. 凡可定位必带 `span`(AST 已有 span,宪法 §10.2);
2. 凡契约错误必带 `doc_anchor` + `doc_quote`——**错误直接定位到文档里对应的说明段落**;
3. 凡可修复建议必带 `suggestion`(给修复回路的原料);
4. 人类文本输出保持现状,`--json` 并行提供——人机同读同写,诊断也一样。
### 3.4 修复回路(repair loop)
```text
validate(p) → diagnose → patch(p, diag) → validate(p') → … (预算 N=3 轮)
```
- **限定行级 patch**,不允许整文件重写(防止 AI「修复」时破坏叙述);
- 尝试预算与重复诊断去重,防循环;
- 实验指标:**一轮修复率**(带锚点 vs 不带锚点两组对比)——这是「可靠反馈」的直接证据。
### 3.5 Schema 注册表(三来源,零手写第二份)
| 面 | 来源 | 说明 |
|----|------|------|
| 语言面 | `core-surface.md` 机械转 JSON | 构造戒律原文进 `description` |
| 函数 / 类型面 | **契约**(问题二产物)+ stdlib/ext 签名 | schema 源头 = 表格与说明段落(§2.1 独有优势) |
| 项目面 | `catalog.yaml`(catalog 自动生成) | 知识单元、链接关系(知识图的边) |
格式 `marqdo-schema.json`(示意):
```json
{
"language": "marqdo",
"version": "0.3",
"constructs": [{ "name": "branch", "syntax": "1. … 2. … N. *", "rule": "自 1. 递增;重出 1. 开新判断" }],
"functions": [{ "name": "加一", "params": [{ "name": "n", "type": "number", "desc": "输入值", "anchor": "#L4" }], "returns": { "type": "number" } }]
}
```
命令:`marqdo schema [PATH]`(catalog 的兄弟命令,同样**只生成不手改**)。
### 3.6 AI Skill:从「背诵」改「查询」
`skills/marqdo` 改造原则:
- `SKILL.md` 只留**十条不可违反的硬规则**(叙述默认安全、`**` 代码 `*` 返回、表格几何、命名/双语约定等)+ MLSP 工具用法;
- 语法细节、API 明细**一律走 `syntax_get` / `fn_schema`**,不再进上下文;
- 工作流改为:construct(凭硬规则写)→ `validate` → 按诊断修 → `run`。
### 3.7 解决方向(设计 · 任务化见 plan)
| 步 | 动作 | 验收(机器可验证) |
|----|------|--------------------|
| S1 | Diagnostic 结构落地(Rust)+ 解释器诊断改造 + `run --json` / `check --json` | 现有错误金样转 JSON 后 `code`/`span` 全非空 |
| S2 | 契约诊断接入(消费 §2.7-S4 的锚点) | §2.8 判据全部成立 |
| S3 | `marqdo schema` 生成器(三来源汇聚) | 生成物 diff 稳定(两次生成 byte-identical);stdlib 主函数覆盖率 ≥ 90% |
| S4 | `marqdo mcp`:暴露 §3.2 工具面 | 用 MCP 客户端冒烟:`fn_schema` → `validate` → `repair` 全链路 |
| S5 | `skills/marqdo` 改造为查询式(保留硬规则十条) | skill 体积减半以上;既有 `marqdo run` 金样仍全绿 |
| S6 | 修复回路 + 实验执行(实验设计见 §5.2) | 实验报告(进 MarqdoThesis,对接 README 愿景 6) |
**「解决而不是遮盖」的最终判据(问题三)**:盲测组(零语法文档 + 工具)的成绩**不劣于**全文档背诵组,且 token 显著更少、修复轮次不升——达不到就继续改协议,**不许**用「再写一篇更好的文档」充数。
### 3.8 遮盖 vs 解决
| 遮盖式做法(禁止) | 本方案的做法 | 判据 |
|--------------------|--------------|------|
| 再写一份更全的 AI 语法文档 | 查询协议 + schema 注册表 | 盲测实验成立 |
| 让 AI「多读 reference.md」 | `syntax_get` / `fn_schema` 按需取 | skill 体积减半且成绩不降 |
| 报错文本润色一下 | 统一 Diagnostic JSON + 文档锚点 | 诊断金样断言锚点字段 |
| 主观感觉「AI 好用了」 | 一轮修复率 / 盲测 / token 三组数字 | 实验报告可复现(MarqdoThesis) |
---
## 4. 路线顺序(依赖序 · 排期见 [three-problems-plan.md](three-problems-plan.md))
> 本表是**依赖顺序**,不是排期表——任务化与本期范围见 [three-problems-plan.md](three-problems-plan.md)。
| 顺序 | 内容 | 产出 | 依赖 |
|------|------|------|------|
| **M0 核心收口** | 问题一 S1–S5 | core-surface.md · layers.md · CI 守卫 | — |
| **M1 诊断地基** | 问题三 S1(Diagnostic + `--json`) | 统一诊断协议 | M0 |
| **M2 契约层** | 问题二 S1–S6 | 提取器 · 四边界校验 · `check` · 锚点 · 防漂移 | M1 |
| **M3 AI 语言服务** | 问题三 S2–S5 | schema 生成 · `marqdo mcp` · 查询式 skill · 修复回路 | M2 |
| **M4 实证** | 问题三 S6 | 修复实验 + 盲测 + 消融(对接 README 愿景 6) | M3 |
顺序理由:Diagnostic 先于契约(契约诊断是它的第一个消费者);契约先于 MLSP(契约是 schema 注册表的主数据源)——**任何一个跳步都会倒逼「另写一套 schema / 另造一套错误」的遮盖式捷径**。
---
## 5. 验证矩阵与实验设计(本文核心)
### 5.1 判据矩阵:什么算「已解决」
| 问题 | 解决的定义(机器可验证) | 遮盖式收场(一句话就能写完的,禁止) | 验证手段 | 判定(2026-09-23) |
|------|--------------------------|--------------------------------------|----------|--------------------|
| 1 核心要小 | 新标记不更新 core-surface → **CI 红** | 「我们重视语言核心」 | CI 守卫演练:故意加标记不更新清单,必须红 | ✅ (e) 3/3 必红→还原必绿 |
| 2 语义校验 | 四边界校验器上线;契约写错**必**被机器抓;无契约路径零回归 | 「静态类型是非目标」/照搬 TS 类型/另写 JSON Schema | 契约金样 + 防漂移金样 + 全量回归 | ✅ (c) 拦截 100%/误报 0%/零回归;(d) 必报 9/9 |
| 3 AI 反馈 / 语法 | 盲测组错误率 ≤ 全文档组且 token 显著更少;一轮修复率可复现 | 「再写更好的文档」 | §5.2 实验 (a)(b)(d) | ❌ (a) 过(双模型 100%);**(b) 四判据未全立** ⇒ 按 §3.7 继续改协议 |
> 2026-09-23 实测数字与判据对照:[perf-validation-report-2026-09-23.md](perf-validation-report-2026-09-23.md)。
> 按本矩阵口径:**问题 1、2 实证成立;问题 3 未解决**(查询式盲测未跑赢全背诵——详见报告 §3 的四条要点,
> 其中「模型不查自己不知道的语法」是协议改进的主攻方向)。
### 5.2 实验设计(性能 / 可靠性验证)
| 实验 | 对照组 | 指标 | 材料 |
|------|--------|------|------|
| (a) 锚点修复 | 诊断带 `doc_anchor` vs 不带 | 一轮修复率、平均修复轮次 | 注入已知 bug 的金样集 |
| (b) 盲测(零语法文档) | 只给 MLSP 工具 vs 给全文档背诵(现 `skills/marqdo`) | 语法错误率、契约违规率、token 消耗 | 任务集(QuixBugs 类 + 业务逻辑类) |
| (c) 契约消融 | 契约开 / 关 | 契约拦截率、误报率、无契约路径零回归 | 同上 |
| (d) 防漂移演练 | 契约故意写错(类型 typo / 参数名与升参不符) | 必报率 = 100% | 契约金样 |
| (e) 核心守卫演练 | 故意加新标记不更新清单 | CI 红 = 必须 | — |
实验基建:复用 MarqdoThesis `formal/exp1–3` 的 runner / oracle / 容错重试;报告即 README 愿景 6 的「可靠性基准」材料。**判据矩阵全绿 + 实验数字可复现之前,三大问题一律视为未解决**——这是「不遮盖」的最终保险。
---
## 6. 未决问题(进 M0/M2 的 ADR 逐条锁定)
1. 契约表消歧的边界案例:紧邻绑定的未绑定表(注释表)紧贴数据表时的归属规则要不要「隔空行才算分离」?(M2-S1 金样定夺)
2. 参数表与返回表合并成单表(首列 `参数`/`返回` 混排)是否更可读?(M2-S1 对比样例后定)
3. 对象字段契约:与 [objects.md](../design/objects.md) 「不把表当对象定义语言」的非目标如何划界——契约是**可选校验元数据**,不定义对象布局(对象仍是运行时 map);需 ADR 明文,避免与 [tables-maps-footnotes.md](tables-maps-footnotes.md) 非目标条目互相打架。
4. 类型词汇是否收 `对象名` 之外的复合形(如 `list<number>`)?——默认**不收**,需要时走 ADR(P2 + 问题一 S4)。
5. `marqdo check` 独立子命令 vs `run --check` 并存?(M2-S3 定,倾向独立 + `run` 默认轻查)
6. `repair` 的 patch 边界:行级 patch 的具体格式(unified diff vs 语句级替换)?(M3-S4 定,倾向语句级——与 AST span 对齐)
+1 -1
View File
@@ -13,7 +13,7 @@
| 传统语言 | Marqdo |
|----------|--------|
| 代码在 `.py`,文档在 `.md` | 代码与文档同在 `.mq.md` |
| `def` / `if` / `for` / `return` 是关键字 | 用 Markdown 标记 `##` / `1.` / `-` / `**…**` 表达 |
| `def` / `if` / `for` / `return` 是关键字 | 用 Markdown 标记 `##` / `1.` / `-` / `**代码**` / `*返回*` 表达 |
| 注释用 `#` 或 `//` | **无标记的叙述就是注释** |
| 大括号 `{}` 或缩进界定代码块 | 标题层级 `#` / `##` 界定作用域 |
Loaded 100 of 888 files, more files were not shown because too many files have changed in this diff. Show more