Compare commits

...
Author SHA1 Message Date
cflmy ffe06d7afa release(2.9.1): keep knowledge in the core compiler
sema::ir always emits proof-index.json and proof-obligations.json through
knowledge, so gating that module on the cli feature broke library consumers
built with --no-default-features (E0433). knowledge is now part of the core
compiler; the CLI binary keeps required-features = ["cli"].

Add a feature-matrix CI gate for the no-feature, cli-only and default
configurations, retire the completed one-time v2.9.0 promotion workflow, and
record the reviewed bilingual 2.9.1 notes and version metadata.
2026-11-18 18:48:47 +08:00
cflmy 180a111799 feat: Marqdo v2.9.0 Verified Knowledge Compiler (full release candidate)
Unified source-verified contracts, accurate evidence grades and independently replayable Lean certificates; version sync, bilingual notes and guarded full release CI. Preserve native AI extension updates from main.
2026-11-18 17:12:07 +08:00
cflmy a3948dbe0d ci: remove temporary extension validation trigger 2026-11-18 14:53:54 +08:00
cflmy 24959a0ba8 fix: validate Windows extension packs with 7-Zip 2026-11-18 14:40:07 +08:00
cflmyandCursor afbb9f191c ci: retrigger EK for ext-v2.8.1 release gate
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-18 13:41:29 +08:00
cflmy 8db699191e release(ext-2.8.1): AI durable workflow pack with Windows packaging fixes 2026-11-18 13:37:02 +08:00
cflmy e5580d9640 release(ext-2.8.3): use Windows System32 tar for pack ZIP encoding 2026-11-18 13:25:09 +08:00
cflmy 9ce2ae1037 release(ext-2.8.2): fix Windows packs.ci root and ship AI durable workflow 2026-11-18 13:08:59 +08:00
cflmy 166b01c86b release(ext-2.8.1): AI native durable workflow pack notes and VERSION 2026-11-18 12:41:57 +08:00
cflmyandCursor 87cfe05095 docs(next): add 014 knowledge-anchor compilation direction
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-18 12:40:41 +08:00
cflmy b37387e6da Merge native AI flow workflow into main
Integrate the v2.8.0-based native agent workflow branch:
- durable open/next/inspect/list/commit/cancel step state with resume_dir isolation
- verified small-model choices, scoped context and bounded parallel recovery
- failed-only read-only retry through the Agent ABI plugin
- offline interpreter fixtures, contract checks and focused CI gates
2026-11-18 12:33:54 +08:00
cflmy 895752a1fd Merge v2.8.0 into native AI flow branch
- take the 2.8.0 crate versions, Cargo.lock dependency graph and release workflows
- keep the native workflow inspect/list, resume_dir isolation and repeatable fixtures
- satisfy the 2.8.0 library narrative gate for workflow.tick
- resolve CHANGELOG ordering with the v2.8.0 release entry
2026-11-18 12:14:03 +08:00
cflmy 38c07d9a0e feat(agent): add workflow inspection and durable isolation
- add agent_workflow_inspect/list primitives and ext/ai wrappers
- expose host-relative resume_dir on every workflow operation
- make offline workflow fixture repeatable with a timestamped run id
- fix flow.choose branch scoping contract diagnostic
- build the agent cdylib and drop the removed run --effects flag in CI
2026-11-18 11:57:12 +08:00
cflmy a7a5554c0f ci(proof): elan 钉 v4.35.0——lean-action 已移除 lean4-version,安装改走 elan-init
proof job 在 2.8.0 HEAD 因 Unexpected input lean4-version 立刻失败;
判定流水线只需 lean 二进制(底座内嵌),与 skill-proof/lean-toolchain 对齐。
2026-11-18 10:57:28 +08:00
cflmy 343504c7a8 release(2.8.0): local.bump — wasm 包版本与 debian/changelog 2.8.0 stanza,Cargo check 更新锁文件
按发版手册 cli 模式:两个 Cargo 包版本一致(marqdo/marqdo-wasm 2.8.0),
ext/VERSION 保持 2.7.0 不动;PPA stanza 保留原维护者、Asia/Shanghai 时间。
2026-11-18 10:29:26 +08:00
cflmy 3d9fa0da96 docs(public): 新增 23-prove 特性页——页面自身定理表经 Lean 全 proved
- 英文特性页(public/features/23-prove.mq.md):六段管线/状态阶梯/
  反例见证/单调性护栏/可证片段边界,示例即页面内的台账.记一笔;
- import result 模块使 result.ok 内联(轨迹语义与定理匹配:大额必经复核
  + 大额单次外呼 + 必有回执);
- 实测 marqdo prove 23-prove.mq.md → status proved,3 定理全部
  decided_by=lean;公开文档重建后 23-prove 页面入站。
2026-11-18 10:29:26 +08:00
cflmy bb8960c5eb fix(env): 重放测试可移植 shebang + dev-env 工具箱目录——全量 1105 测试零失败
- notebook_api.rs:replay 包装脚本 shebang /usr/bin/python3 →
  /usr/bin/env python3(本机 /usr/bin 只读无 python3,CI 与工具链均兼容);
- scripts/dev-env.sh:PATH 预置 target/toolchain/bin(本机 zip shim
  所在,gitignored;CI 用真实 zip),修复 release_handbook packs
  边界 cannot start zip 环境缺口;
- 全量 cargo test:1105 通过 / 0 失败(此前 2 个记录在案的环境基线
  失败——replay python 包装与 packs zip——均已消除)。
2026-11-18 10:29:26 +08:00
cflmy 9331af78e2 release(2.8.0): 合入 CHANGELOG/README/发版说明/skills prove 任务;CI 链接指向 doc/releases
- CHANGELOG.md:v2.8.0 条目(中英双语);
- README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明);
- doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制);
- skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/
  require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过);
- 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
2026-11-18 10:29:26 +08:00
cflmy 73bf574a55 ci: proof.yml Full sweep 接真任务——40 夹具单调性 + T4 一致性 + 分歧注入红线
- corpus monotonicity(offline_checked ⊆ lean_proved)与 T4 差分一致性
  进 CI(MARQDO_PROOF_REQUIRE_LEAN=1);
- Full sweep 改为分歧注入红线:--fault-inject offline-claim 必须触发
  error[proof.divergence] 且退 1,护栏失灵(静默落绿)即 CI 失败;
  本地实测 exit=1 + proof.divergence 诊断。
2026-11-18 10:28:18 +08:00
cflmy 4fae71342d prove: P3 — --all 目录模式、T4 差分一致性、库语义对齐、2.8.0 收口
- main.rs:prove --all/--max-files(递归收集,目录不带 --all 拒绝;
  聚合 JSON kind=prove-all,整体状态差者胜);--fault-inject offline-claim
  (调试分歧注入,A3 护栏验证入口)
- tests/conformance.rs:T4 差分一致性——5 例纯函数语料(算术/中文标识符/
  分支比较/字符串拼接/i64 边界)解释器求值 == Lean example(simp+try rfl);
  B4 result.ok 结构字段 access 两侧一致
- MarqdoProof.lean:mqAdd 补文本拼接与 num 混合(与解释器 eval_binary(Add)
  对齐——T4 实测抓出的真分歧);mqDisplay 显示串(标量精确,容器一层,
  有意简化并记录)
- 文档:design §12 P3 落地 + §12.4 延期理由(foreach/assume-guarantee/T3
  → 2.9)+ §12.5 权限受限待合入清单;roadmap 状态 → 已实施;
  教程 §13.8 prove 章节;skills/marqdo/reference.md 定理表;
  doc/verification/skill-proof-theory.md(库形式化说明);
  doc/roadmap/prove-release-2.8.0.md(双语发版说明 + CHANGELOG/README/
  skills/marqdo-dev prove 任务待合入原文)
- Cargo.toml/Cargo.lock:2.7.1 → 2.8.0

实测:全量 516 通过(仅 2 个已记录环境基线失败);prove 23 + prove_lean 10
+ corpus 40 夹具 + conformance 6 例全绿;biz 定理 proved、假定理反例、
--all 聚合与护栏目录模式同样生效。
2026-11-18 10:28:18 +08:00
cflmy 63d60e3ba1 prove: P2 — 离线符号执行(F1–F5)+ 单调性护栏 + 语料库
- offline.rs:SymVal 符号执行(Const/Struct/OpResult/Param/Unknown);
  If 分支克隆状态并接续后续语句(修复 Return-in-outer 编排丢结果);
  可行性检查(前提∩路径条件为空 → 空真关闭,Lean 假设矛盾同构);
  F2 轨迹包含/长度、F3 构造器结构求值、F4 自由原子二分、
  F5 区间:字面重述关闭 + 区间违反反例(区间端点见证,如 金额 = 10001);
  区间蕴含保守 unverified(当前 Lean 脚本无 Val 传递引理,先于 Lean
  关闭即触发 divergence——诚实优先)
- 判定编排:离线先行(毫秒级 checked ≠ proved)→ Lean 复核升级 proved;
  分歧护栏:checked 但 Lean 关不掉 / 反例被 Lean 证出 ⇒
  error[proof.divergence] 退 1 永不落绿;MARQDO_PROOF_INJECT_DIVERGENCE 验证
- emit:try split 按 if 嵌套深度重复(三路分支可达);simp 清单补
  mqResultError/mqValueOr/mqAnd/mqOr/mqNot(分歧护栏暴露)
- tests/prove_corpus.rs:8 类 × 5 = 40 夹具语料库,
  offline_checked ⊆ lean_proved 强制 + 无 Lean 禁 proved;
  f5_interval_closure_scope 单测锁定 F5 诚实范围
- 设计文档 §12 记录 P2 落地、修复与文法限制

实测:biz 3 定理离线 checked→Lean proved;假定理反例 金额 = 10001
指回定理表行;注入分歧 → error/divergence 退 1;全量 516 通过
(仅剩 2 个已记录环境基线失败)。
2026-11-18 10:28:18 +08:00
cflmy 44d2928c06 prove: P1 — Lean 判定接入 CLI(driver + 证书缓存 + CI)
- driver.rs:工具链发现(--lean → MARQDO_PROOF_LEAN → PATH;显式坏路径
  error[proof.lean_missing] 不回退);MarqdoProof 库内嵌进二进制,按内容
  哈希缓存、lean -o 直接构建(运行时零 lake/elan 依赖);lean 调用带超时
  (--timeout/--heartbeats);unsolved→unproved、error→error、
  sorry→unverified;-- mq: 注释 + 定理头注释 → 证据映射指回源行
- cache.rs:复合键证书(源码⊕plan⊕库sha256⊕lean版本⊕版本),
  命中跳判定(lean.cache: hit),--no-cache/MARQDO_PROOF_NO_CACHE 绕过
- mod.rs:per-claim 判定面(status/decided_by/evidence/source_line)、
  lean JSON 对象、proof.claim_failed 诊断;文件状态只聚合有定理与被拒函数
- main.rs:--lean/--timeout/--no-cache/--heartbeats 旗标;prove emit
  子命令只生成不判定;策略 none → sorry(绝不冒充 proved)
- tests/prove_lean.rs:A1/E1/E4/F2/F3/F4/G1/G2/G2b 矩阵,无工具链 SKIP、
  MARQDO_PROOF_REQUIRE_LEAN=1 硬性要求;实测抓出并修复错误行/列解析、
  逐定理记录缺失、含点函数名归因三处判定缺陷
- CI proof.yml:装 Lean 4.35.0 → 底座校验 → 判定矩阵(CI 不许静默降级)
- 设计文档 §12 记录 P1 落地与偏差(直接 lean -o,不经 lake)

实测:业务样例 3 定理 proved;假定理 unproved 退 1 指回定理表行;
缓存命中后跳判定(假 lean 计数器验证);全量 Rust 测试 508 通过
(仅剩 2 个已记录环境基线失败)。
2026-11-18 10:28:18 +08:00
cflmy fa832268b3 prove: fix issues found in Lean verification round
- p2_len fixture claim corrected: pure function's trace is always empty,
  so '长度(轨迹) = 2' was an authoring mistake -> '长度(轨迹) = 0'
  (Nat-path coverage unchanged); all 7 claim-bearing files now prove
- generated Lean headers set linter.unusedVariables/unusedSimpArgs off:
  machine-emitted artifacts should not trigger human-authoring lints
  (0 warnings now)
- verification driver script + updated results in design doc 12 and
  library README
2026-11-18 10:28:18 +08:00
cflmy 9576188a2e prove: real Lean 4.35.0 verification round
- MarqdoProof semantic base (Val + mq* helpers + branch-contradiction
  lemmas, no axiom/opaque), lake-built; sources under doc/verification/
- emitter: ASCII-only namespaces (uXXXX encoding), guillemet wrapping
  for all non-ASCII identifiers, ':' -> '_' inside op ctor names,
  ctor pattern arg binding, ASCII-safe rename forms, placeholder ctor
  via op_ctor, flipped run equation (outputs on the left), try-split
  for branchless bodies, validated proof script (simp_all + .elim
  contradiction + omega)
- business example: 3/3 theorems proved by real Lean; 5/6 claim
  fixtures proved, p2_len honestly unproved (false claim)
- design doc section 12: Lean round findings + results
2026-11-18 10:28:18 +08:00
cflmy 528a1f0dbc prove: fix 4 review defects (honesty + compilability) + business validation
Code review after the initial prove commit found and fixed:

1. Calls inside table/list literals were silently dropped — a function
   with side-effectful cells lowered to "no ops" and claimed purity in
   Lean. lower_expr's fallback now rejects with proof.unsupported
   (author must bind the call to a variable first).
2. Same-callee call sites with different arities (optional params)
   shared one Op whose ctor declared the first-seen arity, emitting
   uncompilable Lean. register_op now suffixes `/N` per arity.
3. proof.name_shadow fired once per walked function (N functions → N
   duplicates) and checked params of claim-free functions. Predicate
   check runs once per module; param check only for functions that
   carry claims.
4. 长度(轨迹) = 2 emitted mqEq (Nat) (Val) — type-mismatched Lean.
   Nat-context detection renders trace-length comparisons natively;
   untranslatable shapes become comments instead of broken Lean.

Hardening: lean_ident reserves 轨迹₀ / h_前提 (theorem binder
collision); emit_theorems dedups repeated claim ids.

Tests: +4 integration regressions (p2_a..p2_d), 23 prove tests total;
full suite green except the documented env-limited failures (one
host::foreign_session flake passes standalone).

Business validation (doc §12): e-commerce order-approval SKILL with 3
theorems cross-checked against the real interpreter — 5000 → auto
(1-step trace), 20000/60000 → manual ticket T-20000/T-60000
(需人工→创建, exactly 2 steps); corrupted claim tables hit
check --proof codes while staying default-off; double emit
byte-identical.
2026-11-18 10:28:18 +08:00
cflmy a11b347659 prove: add marqdo prove (P0 emit/audit + P1 claim tables & check --proof)
Language layer (ADR 0010):
- claim tables (定理|结论|前提|策略) parsed before first executable
  statement, extracted into Function.claims, removed from body
- check --proof (default off): proof.claim_malformed / claim_ambiguous /
  claim_misplaced / claim_duplicate / claim_unknown_symbol /
  claim_unsupported / name_shadow

Runtime layer (src/prove/):
- ir.rs: Plan IR with stable hand-rolled JSON (schema 1)
- lower.rs: subset acceptance (proof.while / proof.recursion /
  proof.dynamic_call), inlining for straight-line pure callees, opaque
  ops with effect labels, --allow-opaque whole-function downgrade
- types.rs: literal-driven inference + branch confluence
  (proof.type_mismatch, exit 1)
- emit.rs: deterministic Lean emission (Val × List Op, continuation
  style, -- mq: line:col anchors, «…» for dotted idents, theorem
  scaffolds from claims with unfold/split script)
- mod.rs: prove/emit/audit/clean commands, Verdict taxonomy
  (error > unproved > rejected > unverified > checked > proved),
  exit codes 0/1/2 per design §3.3

Tests: tests/prove.rs 19 integration cases (no Lean required) + module
unit tests; full suite stays green except the 3 documented
env-limited failures.

Docs: doc/design/prove-cli.md (§12 records deviations: result.ok/error
vs drafted success/failure, Val-based run at P1, op arity, opaque
effect label), doc/roadmap/prove.md, doc/adr/0010.

Env fixes carried in: scratch dirs in test helpers honor
CARGO_TARGET_DIR (needed on this machine's read-only target/debug).
2026-11-18 10:28:18 +08:00
cflmy 8e437e2cd3 ci(agent): permit native ABI loading in offline Agent integration tests 2026-11-18 10:17:47 +08:00
cflmy 23229a6ac9 ci(agent): permit native ABI loading in offline Agent integration tests 2026-11-18 10:17:44 +08:00
cflmy 58b65215a1 test(agent): show the failed native choice result in interpreter smoke diagnostics 2026-11-18 10:16:43 +08:00
cflmy 92c3f80055 fix(agent): compare branch labels using explicit text conversion 2026-11-18 09:59:27 +08:00
cflmy 8a66f803cb feat(agent): add validated forward-only branching from model choices to registered SKILL steps 2026-11-18 09:59:16 +08:00
cflmy 3ce59a4da8 test(ai): verify JSON-formatted small-model option parsing from Marqdo 2026-11-18 09:57:47 +08:00
cflmy 90688741c5 feat(agent): parse bounded JSON choice envelopes without relaxing skill allowlist 2026-11-18 09:57:37 +08:00
cflmy 70b88b3767 security(agent): require explicit read-only classification before automatic SKILL/parallel dispatch 2026-11-18 09:57:06 +08:00
cflmy f859e6eeea test(ai): include required short model prompt in workflow fixture 2026-11-18 09:56:55 +08:00
cflmy 6705e2e6b7 fix(agent): require explicit local prompt for model workflow steps 2026-11-18 09:56:49 +08:00
cflmy 6e8a62928b test(ai): verify plugin-only tick returns waiting input and commits final step 2026-11-18 09:56:39 +08:00
cflmy 398a0b7222 ci(agent): introduce focused plugin-only native workflow gate separate from long EK suite 2026-11-18 09:56:28 +08:00
cflmy e8f1a3e126 fix(agent): deduplicate equivalent numbered and labeled user replies 2026-11-18 09:56:16 +08:00
cflmy 8ea56cbe30 test(ai): exercise ABI failed-only recovery without executing already successful children 2026-11-18 09:55:42 +08:00
cflmy 8085d06124 feat(ai): expose failed-only read-only child recovery as a short Marqdo workflow 2026-11-18 09:55:30 +08:00
cflmy 6f929dc2da feat(agent): publish safe partial fan-out recovery through Agent ABI 2026-11-18 09:55:19 +08:00
cflmy dd22180269 feat(agent): recover failed read-only children only, preserving successful subtask results 2026-11-18 09:55:11 +08:00
cflmy cc48bf6d05 docs(agent): document plugin-only durable step state engine and safety boundaries 2026-11-18 09:54:45 +08:00
cflmy 19f986953a test(ai): prove successful parallel child outputs survive failed sibling and checkpoint reload 2026-11-18 09:54:21 +08:00
cflmy 770dee5199 fix(agent): prevent EffectLedger atomic temp collisions under parallel operations 2026-11-18 09:54:06 +08:00
cflmy f6612813e3 fix(agent): remove resume test global cwd races and make atomic temp names unique 2026-11-18 09:53:58 +08:00
cflmy 643ea06340 feat(ai): add one-step native workflow driver for model input and bounded child tasks 2026-11-18 09:53:17 +08:00
cflmy 0cd64a7450 fix(agent): persist partial child outcomes and require verified process success before workflow commit 2026-11-18 09:53:02 +08:00
cflmy 981faac022 ci(ai): test native workflow plugin through actual Marqdo interpreter 2026-11-18 09:52:42 +08:00
cflmy f818834ec1 test(ai): exercise ABI-only durable workflow in actual Marqdo interpreter 2026-11-18 09:52:35 +08:00
cflmy 8d47507d15 feat(ai): expose a concise ABI-backed durable workflow library 2026-11-18 09:52:13 +08:00
cflmy 1e1f05c087 feat(agent): register ABI workflow state transitions and cancellation 2026-11-18 09:51:59 +08:00
cflmy 06e61efc51 feat(agent): implement plugin-only durable step workflow with deterministic next/commit/cancel and tests 2026-11-18 09:51:51 +08:00
cflmy 2dfa0b2a5b fix(ai): do not mistake LLM transport errors for choices or trigger format repair 2026-11-18 09:46:24 +08:00
cflmy 629ad8ed39 feat(agent): tolerate short deterministic small-model selection phrases 2026-11-18 09:43:59 +08:00
cflmy ee677478be test(ai): verify file/class/function context composition in Marqdo interpreter 2026-11-18 09:43:30 +08:00
cflmy edbf241d99 feat(ai): compose current user and scoped file/class/function source into a bounded context pack 2026-11-18 09:43:24 +08:00
cflmy add6a7d32c docs(agent): record implemented contracts and precise VM/runtime completion gates 2026-11-18 09:42:07 +08:00
cflmy c64ec99115 feat(ai): expose minimal ask/start/wait on top of native LLM and subtask APIs 2026-11-18 09:41:28 +08:00
cflmy 60a3b84a84 test(ai): exercise durable input and reply from a real Marqdo program 2026-11-18 09:41:08 +08:00
cflmy 02a4f2d20d fix(agent): skip YAML setext lookalikes in document-scope parser 2026-11-18 09:40:50 +08:00
cflmy 88490e3092 ci(ai): execute real native choice and scoped-context Marqdo smoke 2026-11-18 09:40:15 +08:00
cflmy 9031c106a1 test(ai): add offline Marqdo interpreter smoke for native choice and scoped context 2026-11-18 09:40:08 +08:00
cflmy 633436e40f fix(agent): compare owned JSON values with dereferenced optional identity values 2026-11-18 09:39:53 +08:00
cflmy cf73fcf1ef feat(ai): add allowlisted SKILL enter via standard Marqdo subtasks 2026-11-18 09:39:37 +08:00
cflmy e48fd5b0f4 feat(ai): aggregate concurrent child status without losing successful siblings 2026-11-18 09:39:06 +08:00
cflmy b2f97e72c3 build(agent): lock pulldown-cmark dependency for native scoped context 2026-11-18 09:38:58 +08:00
cflmy c7c0f66d1f feat(agent): register typed concurrent task result aggregator 2026-11-18 09:38:33 +08:00
cflmy d5ab9daebb feat(agent): classify parallel child successes, failures and unknown outcomes 2026-11-18 09:38:26 +08:00
cflmy 5795236d1f feat(ai): expose durable step-boundary input/reply in flow SKILL 2026-11-18 09:37:56 +08:00
cflmy e8d6dc92fc feat(agent): register user-input pause/reply gate primitives 2026-11-18 09:37:44 +08:00
cflmy afe31cb2a8 feat(agent): durable user-input gate with idempotent reply, revision and session checks 2026-11-18 09:37:35 +08:00
cflmy 905a67df32 feat(ai): expose native Markdown scope selection to Marqdo authors 2026-11-18 09:37:18 +08:00
cflmy f63b7ef48d feat(agent): register scoped context projection in native plugin 2026-11-18 09:37:02 +08:00
cflmy 393558ca97 feat(agent): register scoped context projection in native plugin 2026-11-18 09:36:59 +08:00
cflmy 0d9bd99fc0 feat(agent): add Markdown heading-scoped bounded file/class/function prompt projection with tests 2026-11-18 09:36:52 +08:00
cflmy a0c779e022 fix(ai): declare function parameters in Marqdo prose syntax 2026-11-18 09:36:31 +08:00
cflmy a82b6fdde1 fix(ai): declare function parameters in Marqdo prose syntax 2026-11-18 09:36:28 +08:00
cflmy 3613ed7c4e fix(ai): declare function parameters in Marqdo prose syntax 2026-11-18 09:36:26 +08:00
cflmy 9564dff777 docs(ai): link the new native flow, context and recovery modules 2026-11-18 09:34:13 +08:00
cflmy f56deffefe test(agent): isolate EffectLedger tests without process-global cwd races 2026-11-18 09:33:28 +08:00
cflmy bdedf3ecd8 ci(ai): include scoped context pack in syntax gates 2026-11-18 09:32:55 +08:00
cflmy b0ee958fcf feat(ai): add explicit small-model file/class/function context pack 2026-11-18 09:32:48 +08:00
cflmy e64f6b23b4 fix(ai): use valid Marqdo branch expressions and literal main reference 2026-11-18 09:32:04 +08:00
cflmy eed4f05ea4 ci(agent): test native parser and check the new Marqdo flow modules 2026-11-18 09:31:14 +08:00
cflmy d88ed274ed feat(ai): expose short checkpoint and bounded recovery functions 2026-11-18 09:30:49 +08:00
cflmy 7fdd97f675 feat(agent): classify invalid model output and bound local recovery 2026-11-18 09:30:33 +08:00
cflmy c299efe589 feat(ai): add thin model-choice and parallel-document flow library 2026-11-18 09:30:22 +08:00
cflmy b3867c46db feat(agent): register native choice parser in plugin ABI 2026-11-18 09:30:10 +08:00
cflmy 1a39a53d93 feat(agent): add fail-closed small-model choice parser and tests 2026-11-18 09:30:03 +08:00
cflmy 6d6f580d24 docs: lead with Markdown-to-execution film and original View imagery 2026-11-13 12:06:30 +08:00
github-actions[bot] af05f19301 docs: publish cinematic Markdown-to-execution promotional film 2026-11-13 04:05:04 +00:00
cflmy 3201369470 docs: build cinematic 3-view Markdown execution promotion from original screenshots 2026-11-13 12:04:18 +08:00
cflmy 05197378b3 assets: add original procurement View screenshot and Markdown three-view concept art 2026-11-13 12:01:22 +08:00
github-actions[bot] f3b3152f07 docs: render Marqdo 2.7.1 promotional video from existing assets 2026-11-13 03:35:16 +00:00
cflmy 22364f2f1b feat(docs): add reproducible Marqdo v2.7.1 promotional video editor 2026-11-13 11:34:12 +08:00
cflmy b69a90501d docs: feature verified procurement GIF and real Marqdo View screenshot 2026-11-13 11:19:51 +08:00
github-actions[bot] 7ff881f506 docs: capture live procurement CLI GIF and View screenshot 2026-11-13 03:19:13 +00:00
cflmy 9acbe10986 build(docs): reproducibly capture real procurement CLI and View assets 2026-11-13 11:18:41 +08:00
cflmy 81989a26d7 fix(demo): bind numeric quote validity explicitly for contract checks 2026-11-13 11:08:48 +08:00
cflmy cf0ba6dccd docs: launch executable skills with procurement showcase and animated assets 2026-11-13 11:07:57 +08:00
cflmy 0de703f86a debian: include cached orig until its publication is confirmed 2026-11-11 01:04:18 +08:00
cflmy 4907f92d84 debian: stop reapplying the upstream engineering compatibility fix 2026-11-11 00:57:16 +08:00
cflmy eac6921524 view: preserve disclosure state and release CLI 2.7.1 2026-11-11 00:44:32 +08:00
cflmy c0dc18433b Fix 2.7.0 engineering release compatibility and preserve accepted Ubuntu orig 2026-11-10 17:53:08 +08:00
cflmy 7d9af11398 Release 2.7.0: invoke source packaging through its declared Bash runtime 2026-11-10 17:12:51 +08:00
cflmy d9aef957f7 Release 2.7.0: executable handbooks and native user-site workflows 2026-11-10 17:03:06 +08:00
cflmy aa0c4d0f55 release: v2.6.0 — executable library handbooks and readable actions 2026-11-08 23:30:17 +08:00
cflmy c50c515c4a Refactor executable library handbooks and improve document reading 2026-11-08 22:19:11 +08:00
cflmy 16c44588d5 Fix replay policy wire commands and register the agent smoke tool
Send complete op/steps/value records to the Lean decoder for every operation. Preserve companion exit status and a bounded stderr tail on transport failure. Register the smoke fixture read tool explicitly without weakening the allowlist or changing its output assertion.

Validation: 462 library tests and 312 gold tests passed. The repository regression run passed 946 tests with two existing ignored experiments; the previously passed 1000-document scale test was not repeated.
2026-11-08 21:50:01 +08:00
cflmy 5080136d65 Make Web an executable handbook with recursive Markdown layouts 2026-11-08 21:50:01 +08:00
cflmy cc5277d2b5 Make Quantum an executable handbook with verified experiments 2026-11-08 21:50:01 +08:00
cflmyandCursor bb06dad134 Start web skill=tools migration with in-package layout law.
Add root/index and layout skills that force file-partitioned pages and ban
HTML/CSS injection as the default path; wire ext add, docs, and call coverage.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-08 21:50:01 +08:00
cflmyandCursor 24dcb97354 Document the ext skill=tools development paradigm.
Capture the quantum pilot as a checklist-driven guide: layout, root skill
paths, call/session, narration, i18n, install hygiene, and rollout order.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-08 21:50:01 +08:00
cflmyandCursor 76aa02846a Clarify quantum agent paths for Bell preparation.
Root skills get a choose-a-path table; circuit modules spell the simulate
handoff; call_cli covers ZH bell and stepwise session probabilities.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-08 21:50:01 +08:00
cflmyandCursor 0e389f34ec Ship quantum skill=tools tree with call session and ZH package.
Split ext/quantum into index + modules, add marqdo call --effects/--session/--toget,
narrative-ratio checks, and a same-package 量子/ tree so agents can follow a
decision path for Bell demos without inventing a second API.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-08 21:50:01 +08:00
cflmy 492790e985 release: v2.5.1 — flowing source annotations and labeled toolbar 2026-11-07 13:08:09 +08:00
cflmy ca434a8bab docs: keep 2.5.0 reader version prose out of branch syntax 2026-11-07 10:11:36 +08:00
cflmy 6195ad1d5d release: v2.5.0 — document reader redesign 2026-11-07 10:06:58 +08:00
cflmyandCursor a87c2154ff release: v2.4.0 oracle journal language values
Expose foreign.oracle_journal/replay_check as values, bump CLI/ext/wasm to
2.4.0, and fix notebook OnceLock wait for MSRV 1.81 so EK can compile.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-06 15:09:34 +08:00
cflmyandCursor 8f1010f967 Ship oracle journal values, bytecode/frontend hardening, and replay-policy Lean.
Host exposes oracle journals as language values with refuse/copy gates; bytecode and foreign session paths get modularized; applications and verification replay-policy sources land with Lake builds ignored.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-06 15:04:27 +08:00
cflmyandCursor e3d9021bb6 docs: align foreign Strong correspondence with mechanized Thm. corr
Record corr_fresh_functional and host discharge (foreign gold + R1–R3)
for the closed/fresh/functional fragment instead of conformance-only wording.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-01 20:03:44 +08:00
cflmyandCursor 142ab523d6 release: v2.3.0 Foreign Strong session/handle/replay/arity
Opaque session handles, affine close, replay_check vs oracle journal,
table arity refuse, and Ω∈V_safe gate for the Strong foreign narrative.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-01 14:46:08 +08:00
cflmyandCursor 82c8d78fd3 release: v2.2.2 V_safe JSON integer refuse on foreign bridge
Align host json encode/decode with Lean ForeignJSON: refuse OOD integers
instead of silent Node distortion; keep decimal-string BigInt author path.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-11-01 09:43:51 +08:00
cflmyandCursor 58791fc7d9 release: v2.2.1 fix view outline rail under document
Occlusion left .doc-block open and mid-width CSS stacked the Functions/Variables rail below Structure; close the block and stack by panel container width instead.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-30 11:41:49 +08:00
cflmyandCursor 1730f26fc7 release: v2.2.0 call one function in any .mq.md
The same page is the document, the knowledge and the program. marqdo call runs that function with arguments, so reuse, tools and tests do not need a second skill system.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-30 09:07:23 +08:00
cflmyandCursor 4018e9928a fix(ai): stream usage events and accept free-form plan replies
Request stream_options.include_usage, emit usage SSE events for collect_usage,
propagate plan tokens through run, and treat unknown prose decisions as DONE.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-28 11:56:51 +08:00
cflmyandCursor 628e3b6e5d chore(ppa): bump 2.1.5 to 1ppa2 after Launchpad no-log failure
Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 17:38:04 +08:00
cflmyandCursor 5c6c612edd fix(test): coerce MARQDO_SITE_PORT for MR-01 isolated execute
Env port strings must be json.parsed to int; pin main site to 18220 so
inherited MARQDO_SITE_PORT cannot steal the fixture bind.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 16:05:24 +08:00
cflmyandCursor 41587f319e release: v2.1.5 agent reliability workbench
Bump CLI/wasm/ext to 2.1.5; document ResourceView, ToolSpec, CheckpointV2,
EffectLedger, EKC warm-load, and web short/read lane isolation.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 15:39:36 +08:00
cflmyandCursor 298fbd51ea feat(workbench): expose CSV preview text for TablePreview
ResourceView csv render now includes bounded text alongside sanitized
HTML so clients can build interactive tables without re-parsing HTML.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 14:45:05 +08:00
cflmyandCursor 265dfdbcc4 feat(workbench): emit JSON source text and code line locators
ResourceView now carries render.text for JsonPreview/CodePreview and
honors locator.line with capped line locators for navigation.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 14:23:00 +08:00
cflmyandCursor 42a43f5ffd feat(workbench): honor ResourceView locator.page as focus_locator
PDF blob views echo the requested page for client navigation without
claiming text extract or OCR.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 14:18:38 +08:00
cflmyandCursor 037a963547 feat(workbench): emit blob_ref for PDF and image ResourceView
Client visual preview consumes the blob; extract/OCR capabilities stay
false so QA-10 honesty holds without cutting the preview path.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 14:14:17 +08:00
cflmyandCursor a32638e935 fix(workbench): drop trailing blank lines from CSV ResourceView
Avoid an empty last table row when files end with a newline.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 14:03:40 +08:00
cflmyandCursor 43eebe5671 feat(workbench): add bounded JSON and CSV ResourceView renderers
Serve static application/json and text/csv previews with outline/table
limits and flip extract_formats availability for those media types.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 13:55:35 +08:00
cflmyandCursor e833dc05e2 feat(agent): attach effect ledger watermark on CheckpointV2 save
Persist effects_watermark with resume checkpoints and pass resume_id into
step tool calls so mutating tools share a stable logical_run scope.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 13:48:45 +08:00
cflmyandCursor 11bb7ef277 feat(agent): wire EffectLedger through mutating run_tool
Prepare/start/commit write and execute tools with idempotent dedupe, and refuse
blind retry while ledger state is unknown or interrupted mid-flight (MA-T03).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 13:44:45 +08:00
cflmyandCursor 6bd90bb2d0 feat(agent): ship output channels, ContextPackV2, and effect ledger
Open AgentOutputV1/ContextPackV2 capability bits and add EffectLedgerRecordV1
so CheckpointV2 write auto-resume only unlocks on a safe watermark.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 13:28:03 +08:00
cflmyandCursor 4683f2e067 feat(agent): ToolSpec registry with authorize-before-call
Add ToolSpecV1 register/search/describe/prepare so CALL and native paths share one schema gate; unauthorized and invalid-arg prepares fail with zero executions.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 13:18:55 +08:00
cflmyandCursor 5912164039 feat(agent): CheckpointV2 atomic resume and AgentErrorV1
Replace bare resume writes with temp/fsync/rename, mark legacy loads as manual_review, and expose bounded read-only retry decisions while keeping write auto-resume closed without a ledger.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 11:03:39 +08:00
cflmyandCursor 303c06f773 feat(workbench): freeze agent protocols and ship ResourceView v1
Lock M-A0 Error/Tool/Checkpoint/Output/Context fixtures with capability bits off, and land M-A3 static md/txt/code ResourceView (no-exec) behind resource.view.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 10:59:59 +08:00
cflmyandCursor a1086fd6c3 docs: plan cross-repo agent reliability delivery
Lock M-A*/Q-A* sequencing, F01–F20 mapping, and first-slice gates on top of the 2026-10-27 designs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 10:49:20 +08:00
cflmy 6ffe5ceb19 docs: expand executable knowledge design notes 2026-10-27 02:10:54 +00:00
cflmy 6b568aff3d docs: design reliable agent capabilities 2026-10-27 02:10:25 +00:00
cflmyandCursor 16f26d7d60 fix(knowledge): warm-load IR for preflight/find/reuse queries
Stop full recompile on every knowledge preflight by writing ekc/graph/ir.json
and loading it unless --refresh or missing projections, cutting chat预检 wall time.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 09:18:27 +08:00
cflmyandCursor b8265a92aa fix(web): stop short/read/control from filling execute slots
Isolating every short invoke on the 2-slot worker pool caused no_slot under
normal traffic; keep short paths on parent (execute already off-process) and
background-reap after observer disconnect so zombies release slots.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 08:56:56 +08:00
cflmyandCursor 9af929971c fix(web): disconnect≠cancel and isolate short/read/control lanes
Observer SSE close no longer cancels execute by default; short/read/control
bypass parent INVOKE_LOCK via isolated admission, with read_lane=1 and gold samples.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-27 08:44:07 +08:00
cflmyandCursor 2c4fa4bb05 fix(ppa): install only rustc/cargo/std and use disk TMPDIR
Repeated --without flags were ignored by install.sh (last wins), so
rust-docs still filled /tmp and hit quota; prefer --components= and
a home-cache work dir instead of tmpfs.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-26 19:13:48 +08:00
cflmyandCursor 3cabe53da2 release: v2.1.4 isolated HTTP execute (ADR 0009)
Default execute/sse-live/stream to Supervisor worker pool; MR-01 gold;
/_runtime/*; bump CLI/wasm/ext to 2.1.4.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-26 18:33:33 +08:00
cflmy 58e13ee6d3 docs: add isolated web runtime development design 2026-10-26 05:53:02 +00:00
cflmyandCursor 1b11fe063a fix(web): fail-fast when invoke lock is busy; document single-interp limit
Long sse-live chats held INVOKE_LOCK indefinitely and starved short routes
(UI freeze). Timed try-lock returns interpreter busy → HTTP 503; ADR 0008
records that HTTP is multi-goroutine while Marqdo evaluation stays single-flight.
Also lands plan/delta streaming and soft map guards used by qdagent chat.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-26 13:27:53 +08:00
cflmyandCursor b792f44556 feat(web): auto sse-live when chat body has stream:true
Upgrade json invoke routes to the M02 EventBus forwarder for OpenAI-compatible
stream requests, and normalize LLM delta frames to message.delta.payload.delta
so tokens flush before run.completed.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-26 09:47:05 +08:00
cflmyandCursor 9ea5bebfc3 chore(release): bump to 2.1.3 (workbench M00–M06)
Ship ModelSelection/RunContext/DocumentView contracts, LLM selection,
view document CLI, and live/F02 evidence. CLI, wasm, and ext pack aligned.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-25 23:13:27 +08:00
cflmyandCursor c7c329341b feat(workbench): live selection smoke, F02 agent e2e, DocumentView CLI
Hoist llm.ask prompt binding to avoid elevated `p`; prefer reasoning_content
when content is empty; point live/tests at in-tree MARQDO_EXT; add USTC live
gates and mock agent.step selection+resume evidence; view document --out for
read-only browser embed checks. Design stays Partial (not Verified).

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-25 23:05:28 +08:00
cflmyandCursor 8cf5288481 feat(workbench): F14 coalesce, snapshot manifest, and sse drain evidence
Hold analysis locks across compile for concurrent same-snapshot reads,
emit SnapshotManifestV1 for app retention, and add Go drainForward tests.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-25 11:13:53 +08:00
cflmyandCursor 69c4e74872 feat(view): project KnowledgeStep kinds into DocumentView nodes
Strengthen F09 read-model coverage so observe/derive/call/iterate steps
appear alongside artifact cards without executing the document.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-25 11:03:01 +08:00
cflmyandCursor af0bda2e40 test(workbench): add F02 subtask/agent skeleton and cancel bridge evidence
Cover selection env propagation, agent skeleton without llm.llm, step-kinds
DocumentView read purity, and Go cancel-token bridge smoke.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-25 11:02:25 +08:00
cflmyandCursor 090b026547 test(workbench): harden F-matrix evidence and demote Verified claim
Add dual-endpoint LLM isolation, usage revision replace, cancel/F08/F11
asserts, and mark the design status Partial until remaining F gaps close.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-25 11:01:02 +08:00
cflmyandCursor 03396afd02 feat(workbench): land M00–M06 runtime contracts and read-only view
Add capabilities/selection/usage/DocumentView/locator/RunContext with
honest probes, LLM messages+cancel, sse-live cancel bridge, and CI
workbench_contracts gate; record design evidence for verified slices.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-25 10:55:08 +08:00
cflmy 663a8ba2c0 docs: specify runtime and view workbench support 2026-10-24 16:27:08 +00:00
cflmyandCursor dc853fb580 release: bump to 2.1.2 (EK production chain + View V0–V3 bar)
Ship evidence/closure invalidation, verify/adjudicate, reuse_execute and
agent bind/publish gates, document.extract, KnowledgePresentation + SSE
page_token, and upload max_bytes with the 45-test offline gate.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-24 22:52:03 +08:00
cflmy 0b80ff8e50 docs: redesign view knowledge reading experience 2026-10-24 02:51:03 +00:00
cflmyandCursor b8a4ddd38f release: bump to 2.1.1 (executable-knowledge spine)
Ship BoundCall/NarrativeRef/generation CURRENT notes with Cargo, ext pack, README, debian, and release Highlights.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 23:40:35 +08:00
cflmyandCursor 352bc0d2c5 feat: finish remaining EK plan — bookstore chain, closure, 100-unit corpus
Make examples/executable-knowledge runnable on both backends, bind same-module
Type.member paths, add closure digests to locks/impact, and gate 100 corpus
units plus CLI smoke so S4–S6 leftover items have reviewable evidence.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 23:34:21 +08:00
cflmyandCursor 8a6d09d582 feat: pure extract, bookstore story subset, and project scan caps
Add artifact.extract_pure for restricted expression lifting, a runnable
bookstore tax story fixture, and G12 discovery limits so oversized or deep
trees fail with explicit diagnostics instead of hanging.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 23:27:05 +08:00
cflmyandCursor dcd3d329d4 feat: land S1–S6 executable-knowledge slices (NarrativeRef through CI)
Add comment-line NarrativeRef steps, generation CURRENT snapshots, frontmatter
sources/applicability, digest-guarded artifact.patch, lock change classes, and
an offline CI gate so the documented S0–S6 path has reviewable evidence.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 23:24:18 +08:00
cflmyandCursor 0e1bfb3359 feat: complete BoundCall dual-backend and reuse bind gate (G02)
Share resolve_for_exec across Tree/Bytecode and semantic projections,
emit bound_calls/dynamic_calls, and require eng_reuse bind_targets before
execute so discovery scores cannot be treated as handles.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 23:06:34 +08:00
cflmyandCursor e9ae7ff1ae fix: isolate bytecode bare-name resolve to module scope (G02)
Imported functions shared the flat call table, so bare same-named calls
could silently bind across imports. Scope tags keep path calls working
while rejecting ambiguous bare names on both backends.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 22:54:52 +08:00
cflmyandCursor ecbdd18303 feat: executable-knowledge S0–S1 gate plus effect and MLSP reuse subset
Establish author baseline fixtures and offline tests, make SemanticProject
the sole authority for graph edges, classify named steps, and tighten
local reuse so unknown effects are not pure and MLSP binds by SymbolId.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 22:52:06 +08:00
cflmy bedd53e212 docs: align executable knowledge roadmap with native workflow 2026-10-23 14:25:12 +00:00
cflmy 7674ebb869 docs: audit executable knowledge planning gaps 2026-10-23 13:54:08 +00:00
cflmy 434be9fd52 chore: ignore local release secrets 2026-10-23 13:37:54 +00:00
cflmy ae97891266 release: v2.1.0 — file-scoped occlusion 2026-10-23 12:59:28 +00:00
cflmy aea86746e7 feat: migrate corpus to file-scoped occlusion 2026-10-23 12:45:01 +00:00
cflmy c773503938 Merge branch 'main' of https://github.com/cflmy/marqdo
# Conflicts:
#	tests/migrate.rs
#	tests/occlusion/classic-index.mq.md
2026-10-23 12:11:58 +00:00
cflmy 939e23ee88 refactor: scope markup compatibility per invocation 2026-10-23 12:11:26 +00:00
cflmyandCursor 687c168014 feat(parse): use nested YAML import: maps instead of one-liner binds
Frontmatter imports are now valid YAML (`import:` / `导入:` with bind→target
entries), removing spaced keys. Add `marqdo migrate imports`, hard-error the
old one-liner form, and migrate lib/ext/examples/tests/docs accordingly.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-23 19:33:58 +08:00
cflmy eac9b45263 feat: compile executable knowledge semantic artifacts 2026-10-23 09:16:52 +00:00
cflmy 74b298e80d build: add portable development toolchain setup 2026-10-23 09:00:56 +00:00
cflmy fc7097bae4 test: validate executable knowledge syntax across libraries 2026-10-23 08:47:49 +00:00
cflmy b624084745 feat: classify associated and instance symbols 2026-10-23 08:26:33 +00:00
cflmy 0bbe735c3c feat: add stable executable knowledge symbols 2026-10-23 08:24:10 +00:00
cflmy 92de46aca4 docs: define executable knowledge implementation baseline 2026-10-23 08:06:38 +00:00
cflmy 8bbe017a5e docs: define executable knowledge step architecture 2026-10-23 15:46:02 +08:00
cflmy 1a13989230 fix(ext/ai): 变量引用补反引号;prompt 缺失回退空串
- llm/agent 模板中的变量引用统一加反引号
- ask/stream 在 prompt/path 均缺失时回退空串,避免直接退出
- 修正 stream 分支返回缩进;agent workbook 模板改用 ** 代码块
2026-10-23 14:52:26 +08:00
cflmy 5ad1a07f5c docs(language): 链接语法与知识分层设计声明 + 示例
- []() 零新语法:描述 + 已有类/函数调用,不引入 ref/别名/开关
- # 是类、## 是函数;类.函数 是类调用;跨文档用项目类索引
- 知识分层:原始语料 / 本体 / 单体知识类 / 调用面;出处与还原验证
- 新增 link-syntax、knowledge-layers 设计声明与两组可运行/目标示例
2026-10-23 14:52:23 +08:00
cflmy bcfc763ba4 fix(parse): 孤立 * 行不再 panic(exit 101 → 干净诊断)
qdagent 全仓 labels 扫描期间实测:任何 .mq.md 里有一行只含单个 `*`
(markdown 强调残留)时,`*…* = 返回` 分支同时满足 starts_with/ends_with('*'),
切片 &trimmed[1..0] 越界,整条 labels 扫描被一个文件打死(exit 101)。

修复:斜体返回分支要求 len >= 2,裸 `*` 落回 "unrecognized statement"
干净错误而非崩溃。

实测:
- tests/errors/lone-asterisk.mq.md → check 报 "unrecognized statement: *",
  exit 1(不再 101)
- gold 回归 error_lone_asterisk_line 通过
- cargo test --release 全套件 0 failed
2026-10-22 19:04:25 +08:00
cflmy bf76e069ee release: v2.0.0 — 遮蔽语法落地([描述](实现) / 标签欠据 / 全仓迁移)
Bump CLI, wasm and plugin SDK to 2.0.0; sync ext/VERSION, Cargo.lock,
CHANGELOG (Highlights + 核心表面 Δ), README, release highlights stub,
skills and debian/changelog.
2026-10-22 16:26:29 +08:00
cflmy 9015de26e5 feat(view): M8 遮蔽呈现 — 描述为正文、实现为代码片、桩有徽章;并修复 view 解析模式回归
一、先修回归(用户看到"没渲染"的真因)
view 多处直接用 crate::parse::parse_source 重新解析文件,而 per-file markup:
是在 load 层生效的(M7)。于是任何带 markup: occlusion 的文档在结构区报
"parse/load error: expected ')' after link-index collection",退化成源码视图。
→ 新增 load::parse_source_auto(source):先读 frontmatter 的 markup:,用
  with_markup 包住解析;view 的 4 处解析点全部改用。

二、遮蔽呈现
浏览视图(document.rs / /file):
  <div class="doc-line doc-occl">
    <span class="occl-pre">留存 =</span>              ← 变量名 灰 等宽
    <span class="occl-label">客户留存率,模拟数据</span> ← 描述 正文
    <code class="occl-code">0.42</code>              ← 实现 代码片
  </div>
空载荷换成 <span class="occl-stub">桩</span> 琥珀徽章(title 说明未接通/待补返回值);
前缀的反引号与 ** 都剥掉,与其它行的 mq-anchor 一致。

卡片视图(render.rs / /debug):按 AST 匹配 Expr::Occluded(Assign/Expr/Return),
渲染 card occl-card:徽章「遮蔽」+ 变量名 + 描述 + 代码片/桩。

样式刻意不加虚线下划线(易读成链接):描述即正文,靠代码片边框区分。

验证:
- /file 页面 0 处 parse/load error;7 个遮蔽行全部渲染
  (6 代码片 + 1 桩),文本抽取为「留存 = 客户留存率,模拟数据 [0.42]」
- 4 个单测(裸赋值/粗体赋值/空载荷+嵌套/非遮蔽不误判)
- 全量 cargo test --release 613 passed / 0 failed

未能截图:本机无任何浏览器,puppeteer 的 Chromium 下载被网络阻断;
改为 DOM 断言 + /.preview/occlusion.html 方案对照页由作者目视确认。

文档:doc/design/change-m8-view-occlusion.md
2026-10-22 16:16:32 +08:00
cflmy 8c24d96626 docs(examples): 遮蔽改用裸赋值 名 = [描述](实现),不再包进粗体
用户指出:`**留存 = [客户留存率,模拟数据](0.42)**` 在阅读器/高亮里
描述被粗体吞成"代码味",人话反而不显眼。

改为裸赋值形式(与粗体形式语义完全等价,实测四项一致):
  `留存` = [客户留存率,模拟数据](0.42)
  `待接` = [搜索接入,接口未接,待开发]()
  `取第一` = [第一颗](access(`篮子`, "1"))
  `个数` = [篮子有几颗](table.len(`篮子`))
  `表取` = [用 table.get 读同一个键](table.get(`饮品价`, "美式"))
  `长度` = [名字长度](len(`名`))

等价性实测(b.mq.md):留存=0.42 / 待接=None / 取第一=苹果 / 个数=2,
check 只报同一条 label.empty_payload,labels 命中同样两处。

并在第 5 节补一句为什么这样写:粗体是给"表达式赋值"用的紧凑写法,
而遮蔽的前提是"描述给人读",所以描述不该被强调形式包住。

顺带说明(不是本次改动):view 的代码区展示的是**高亮后的源码**,
不是 Markdown 渲染,所以 `[..](..)` 在两种写法下都不是可点链接;
真正的呈现改进(描述为正文、实现为代码块)属于 M8 未做部分。
2026-10-22 16:03:59 +08:00
cflmy 4a2f5bf226 docs(examples): 新增 examples/syntax-tour — 一页跑通全部现行语法
十个板块,全部可执行(marqdo run 实测通过):
1 变量与插值  2 函数与契约  3 调用四种形态(> 前缀 / 括号位置 / 逗号 /
  嵌套 / 带空格函数名)  4 取值 access / table.len / table.get
5 遮蔽(普通 + 空载荷桩)  6 循环(遮蔽循环 + while 式递减)
7 分支  8 表格三态(竖表 List / 横表 Map / 行向 List[Map])
9 值类型  10 收尾

写作过程中踩到的真实约束(都已按现行语义修正):
- `##` 是函数定义,正文分节不能用 `##`(改用散文分隔行)
- 函数内看不到模块级变量,`计税` 改为自包含的分支查表
- 反引号插值只接受变量名,不能写 `len(`名`)`,需先算出变量
- `()` 内的 payload 是表达式,空格形调用要写成括号形
  (`table.get(表, 键)` 而非 `table.get map=… key=…`)

实测:run 输出 25 行符合预期;check 仅 1 条有意保留的
label.empty_payload(正是第 5 节要演示的空载荷规则);
labels 命中 2 个已申报桩。
2026-10-22 15:57:48 +08:00
cflmy 86e921e959 feat(migrate): 支持多路径;docs: 体量审计修正两条不成立的判断
- migrate labels 接受多个 PATH(与 labels 一致);全仓干跑幂等:
  lib/ext/cli/examples/public 均为 0,tests 仅剩刻意保留的 classic 样例 1 处
- 审计修正:
  * html.rs 皮肤"重复声明基础 CSS" —— 实测 312 vs 128 条规则、选择器零重叠,不成立
  * debug_page "复刻 shell" —— 仅 head/favicon 约 10 行相似,它没有 nav/topbar,不成立
  * HostFn 五表合一标记为已完成(−404 行)
- 结论:可机械消除的重复已清完;剩余体量全是特性实现

全仓校验:63 个文件 check 零诊断(label.* 全 0);
cargo test --release 609 passed / 0 failed。" && timeout 300 git push origin main 2>&1 | tail -1
2026-10-22 15:52:22 +08:00
cflmy b196a44685 refactor(host): HostFn 五张表合一 — HOST_FN_TABLE 单一来源(−404 行)
202 个宿主函数的元数据原本分散在 from_u16 / from_name / name /
required_params / optional_params 五个手写 match 里,必须同步维护,
审计已记录过 from_name 与 name() 的漂移。

改动:
- 新增 HostFnDef + HOST_FN_TABLE(203 项:id, 变体, 规范名, 必填, 可选)
- from_u16 按 id 查表;name / required_params / optional_params 按判别值查表
- call_host 的 202 个一行臂保持不变(只集中元数据,不动分派逻辑)
- from_name 保留:它是别名注册表(http_get/中文别名…),语义与规范名不同

等价性证明(快照比对):
1. 先在旧实现导出全部 203 项的 (id,name,required,optional) 到 TSV
2. 合并后用同一段代码再导出
3. diff 两份 → 完全一致;快照测试用后即删

长期守护(4 个不变量测试,上一轮已加):
id↔as_u16 往返、name→from_name 往返、规范名唯一、required/optional 不重叠。

验证:cargo build 零警告;cargo test --release 609 passed / 0 failed。
行数:dispatch.rs 2052 → 1648;src 合计 53,040 → 52,668。

文档:doc/design/change-hostfn-table.md
2026-10-22 15:51:26 +08:00
cflmy c8ed5bffb7 docs: 体量审计更新 — 插件 SDK 完成(净减 674 行),合计 67,786 2026-10-22 15:49:26 +08:00
cflmy fb135ae2f8 refactor(plugins): 抽出 marqdo-plugin-sdk — ABI 前言从 5 份变 1 份
新增工作区成员 crates/marqdo-plugin-sdk:ABI 类型、HOST_* 静态回调、
host_strdup/set_out/set_err/parse_args/reply/host_query_json(_with)/
take_host_string/init_plugin,以及生成四个 #[no_mangle] 导出的
marqdo_plugin! 宏。ABI 常量、符号名、结构体布局一律未变。

5 个插件改为依赖 SDK + 一行宏调用:
  agent  1237 → 929  (-308)
  quantum 1045 → 835 (-210)
  linalg  688 → 524  (-164)
  llm     405 → 278  (-127)
  demo    170 → 73   (-97)
  SDK 新增 232 行 → 净减约 674 行

迁移中发现并修正三次"编译通过但语义已变":
1. 注册项抽取漏 11 项 —— 正则 [a-z_0-9]+ 匹配不到 mcp_server::agent_mcp_serve、
   sandbox::* 这类路径限定函数名;改为允许 :: 后重抽。
   已用脚本逐项比对 (名称, 参数串, 函数) 三元组:agent 63/63、quantum 41/41、
   linalg 31/31、llm 2/2、demo 2/2,全部 0 差异。
2. mcp_client 被误判死模块(删 327 行后才发现 agent_mcp_client 正注册它)→ 恢复。
3. 量子插件两个"未使用"函数删除时连带吃掉 density_from_amps/flat_to_nested
   → 恢复原文件并改为 #[allow(dead_code)]。

验证:cargo build --release(含 5 个插件)零警告;
cargo test --release 609 passed / 0 failed;
量子金样实跑 p00-ok / p11-ok / ping-ok。

文档:doc/design/change-plugin-sdk.md
2026-10-22 15:49:13 +08:00
cflmy 69fcdd6227 docs: 代码体量审计 — 53k 行构成、已清 14.5k 冗余、剩余为特性面
把账算清楚,避免行数多=冗余多的误判:
- src 53,072(其中 5,220 是内联测试)+ plugins/crates 15,423
- 最大的 10 个文件逐一标注性质(html.rs 4,451 行里 3,861 是页面皮肤字符串)
- 已清除 14,235 + ~400 行,逐项列提交号
- 顺带修出的 4 个真实缺陷(Access 隐式判别值、escape_js_string 漏 U+2028/2029、
  view 双 handler 路由、HOST id 稀疏无测试守护)
- 剩余可精简项:插件 ABI SDK(~550)、html 皮肤(~250)、debug_page(~120)、
  HostFn 五表(~450),合计约总量 2%,标注风险
- 结论:继续压体量的正确方向是砍特性,而不是在特性内部找重复(已找完)
2026-10-22 15:44:37 +08:00
cflmy deac53d0f5 refactor(view): AST 遍历器合流 — walk_stmts / stmt_line 收进 ast
三处各自实现的「深度优先遍历函数体」合并为一个:
- ast::walk_stmts(fun, &mut |stmt| ...):body + 分支臂 + 循环体 + 子函数
- ast::stmt_line(stmt):语句行号(原 view::document 私有副本)

改造:view/annot.rs::fun_stmt_lines、view/document.rs::index_stmt_lines
(annot 的 collect_name_sites 保留自己的收集逻辑,只借遍历)

cargo build 零警告;cargo test --release 609 passed / 0 failed。
view/annot.rs -30 行、view/document.rs -41 行。
2026-10-22 15:44:20 +08:00
cflmy 932403237a test(host): HostFn id/name/params 一致性测试;refactor: 转义函数去重
一、先暴露问题:写 4 个一致性测试后发现——
- id 空间是**稀疏**的(10 个退役 id),不是连续的;测试按"每个已分配 id 都能还原"重写
- Access 变体只有隐式判别值,补 `= 212` 使之显式(避免重排时静默错位)
- 四个测试现在锁定:id→as_u16 往返、name→from_name 往返、名称唯一、
  required/optional 不重叠且无重复参数。审计提到的 from_name/name 漂移由此可被捕获。

二、转义去重
- urlencoding_encode 与 urlencoding_path 逐字相同 → 合并为 urlencoding_path(pub(crate))
- escape_js_string 两份:debug_page 的副本漏了 U+2028/2029 转义(真实缺陷)
  → 保留 html 的完整版并 pub(crate),debug_page 改为引用

cargo build 零警告;cargo test --release 609 passed / 0 failed(605 + 4 个新测试)。
2026-10-22 15:42:42 +08:00
cflmy a14a6e221d refactor: 删除无调用点的死代码(审计项)
- src/parse/mod.rs: parse_italic_assign(17 行,0 引用)
- src/host/sandbox_fs.rs: unavailable
- src/knowledge/extract.rs: stem_of
- src/knowledge/lifecycle.rs: _system_time_now
- src/debug/ctrl.rs: action_channel
- 连带清理 3 处随之失效的 import

cargo build 零警告;cargo test --release 605 passed / 0 failed。
src 行数 53,079 → 52,96x。
2026-10-22 15:40:31 +08:00
cflmy 8b0ea9ed7a refactor: 精简三处重复 — as_text×18、catalog 助手×4、view 路由 34 臂
按审计结论清理冗余(不改变行为):
1. as_text:17 个 host 模块各自复制同一函数(两种措辞),合并为
   crate::host::as_text(统一 "{label} needs text",无测试依赖旧措辞)
2. catalog.rs:extract_fm_field / extract_nested_by / extract_fm_list /
   yaml_escape 与 knowledge::util 逐字相同,改为直接引用
3. view/mod.rs:handle 29 臂 + handle_debug 5 臂折叠成两张路由表
   (Notebook/Debug/Action 三种处理器),每臂原本重复同一 api_debug_post 包装

实测:
- cargo build 零警告;cargo test --release 605 passed / 0 failed
- view 服务实测:GET / → 200;POST /api/debug/continue → 200(真实响应
  {"error":"unknown session"});POST /api/nope → 405

行数:view/mod.rs -99(168 删 69 增);src 合计由 53,276 降至约 53,000
(as_text 18 文件各约 6 行、catalog 4 函数约 70 行)

期间发现并修正一处真实风险:路由臂分布在两个 handler(handle / handle_debug),
首次只替换了一个导致 debug 路由 405;已按 handler 分别建表并由实测覆盖。
2026-10-22 15:39:18 +08:00
cflmy 6ae0d39e5a feat(labels): 兼容文档里的 labels pending / labels search 写法
设计文档写的是 `labels pending` / `labels search --grep`,CLI 是扁平参数。
把 pending/search 作为无意义位置词过滤掉,使两种写法都可用(不动参数语义)。
实测:labels pending --count → 2;labels search --grep 联调 --count → 1。
全量 605 passed / 0 failed。
2026-10-22 15:34:55 +08:00
cflmy 307c8efa81 feat(labels): 支持多路径扫描;docs: 里程碑全量完成状态与变更文档索引
- labels 接受多个 PATH(默认 .),合并去重后扫描
- occlusion-syntax.md §13.1 记录 M0–M10 全部完成,附 11 份变更文档索引
- 全仓校验:98 个文件 check 零诊断(label.* 全为 0,确认无噪音)
- cargo test --release 605 passed / 0 failed;0 编译警告
2026-10-22 15:34:29 +08:00
cflmy 34b0911218 feat(labels): M8 债务棘轮 — --baseline + --fail-on-increase
规则:未完成项只许减少,不许增加。
- 台账不存在 → 建立(写入当前计数)并提示,exit 0
- 当前 > 台账 → 失败并提示"未完成项增加了 K",exit 1
- 当前 ≤ 台账 → 通过;若减少则**收紧**台账(N → M)

为什么减少即收紧:否则债务可先降后升,棘轮形同虚设;
收紧后回退到旧数量同样失败(测试第 4 步验证)。

台账格式 {"count":N,"words":[…]},记录词集使"口径变更"可审计。

为什么用棘轮而非硬门禁:硬门禁(必须为 0)会让存量债立刻红一片、逼人关检查;
棘轮做到"老账不追、新账必拦",与防疲劳机制的结论一致。

呈现面复核:expr_display / view 把遮蔽渲染为 [描述](实现)、桩为 [描述](),
实测 view output 页面含 access(;未做桩徽章——桩已是显眼形状,再加装饰是噪音。

测试:四步集成用例(建账 → 增加失败 → 减少收紧 → 回退再次失败);
全量 605 passed / 0 failed(M7 后 604 + 1)。

文档:doc/design/change-m8-ratchet.md
2026-10-22 15:34:07 +08:00
cflmy 4488a3cb70 feat(migrate): M7 迁移与版本门 — per-file markup + migrate labels + 全仓迁移
原计划的"翻转默认 + 旧形硬报错"不可行:`[键](集合)` 与 `[描述](实现)` 外形相同,
翻转会让 506 处取元静默变义,硬报错又拿不到证据。改为**按文件声明**。

一、per-file markup
- frontmatter `markup: occlusion`(或 `标记: 遮蔽`)决定该文件模式
- load.rs 先取模式,用 parse::expr::with_markup(线程局部压栈)包住解析
- 同一进程可同时加载两种模式的文件(imports);MARQDO_MARKUP 仍作进程默认
- 好处:迁移逐文件、可增量、可回滚,不存在半迁移的静默错义

二、`marqdo migrate labels [--write|--json]`
改写规则:
  [键](集合)      → [键](access(集合, "键"))
  [`名`](集合)    → [名](access(集合, `名`))
  - [项](集合)    → - [项](遍历 集合 为 项)

安全模型:改写 → 重解析 → 证明等价 → 才写
- 原文件按 classic 解析得 AST-A;改写后按 occlusion 解析得 AST-B
- 反归一化 B(标签与键同名且 payload 为 access 的遮蔽还原成 Index)
- Debug(A) == Debug(反归一化(B))(抹掉行号)才写入,否则原文件一字不动

只改代码行(LineKind::Code);表格行只改 **…** 单元格,散文 markdown 链接不碰;
链式索引由内向外改写,已迁移的有守卫不二次改。

三、access 提升为宿主函数 HostFn::Access(u16 id 212)
与旧取元逐字一致(Map 按键 / List 1-based / 缺键 missing map key);
进 HostFn 是为了两个后端共用同一实现,interp 里的特例已删除。

四、顺带修的两处真实语义缺陷
1. payload 继承外层"文本模式":`f text=[k](access(c,k))` 中 access 不被当调用
   → `()` 内永远允许 callee(args)
2. 遮蔽形状判定过宽:`[问候] ([格式化] "Bo")` 误判为遮蔽
   → 要求 `]` 后紧跟 `(`,否则落回方括号调用

五、全仓迁移结果
migrate labels: 256 index, 23 loop, 80 file written;0 文件被等价性拒绝;
迁移后 cargo test --release → 604 passed / 0 failed;再跑迁移幂等。

等价性检查先后抓出 4 类改写 bug(表格散文链接、payload 文本模式、链式索引、
遮蔽与方括号调用混淆),每类都是先拦下再修工具,未污染文件。

测试:6 个单测 + 3 个集成(干跑不写盘 / 写入后运行输出不变且幂等 /
等价失败文件不动);全量 604 passed / 0 failed(M3 后 595 + 9);双后端一致。

文档:doc/design/change-m7-migration.md
2026-10-22 15:33:31 +08:00
cflmy 9dbcc728b6 docs(design): 记录里程碑进度 — M0/M1/M2/M2.5/M3/M4/M5/M6/M9/M10 已完成,M7/M8 待做 2026-10-22 15:23:54 +08:00
cflmy 0405a60d68 feat(lang): M3 access 内建与遮蔽循环 — 为 M7 迁移准备等价语义
access(集合, 键)(别名 取/取值):
- 复用 builtin_footnote_get,与旧 [键](集合) 语义完全一致
  (Map 按键 / List 1-based 下标 / 缺键报 missing map key,不静默 None)
- 不新增平行实现,避免两套索引语义漂移
- 用途:M7 把 506 处 [k](c) 机械改写成 access(c, k),语义零漂移

遮蔽循环:- [描述](遍历 集合 为 变量)
- 仅 occlusion 模式识别;接受 遍历/for 与 为/as/in
- 描述存入 Stmt::ForEach.label(Option<String>),供 M8 渲染/诊断

为什么先 M3 后 M7:迁移目标必须先存在且等价,否则就是"边迁移边发明语义"。

实测:
  access(`表`,"键") → 值;access(`列`,2) → 二;
  缺键 → missing map key(与旧取元同一错误)
  - [篮子里的每个果子](遍历 `列` 为 `果`) → 果=一 / 果=二

测试:2 个集成(含缺键错误保真);全量 595 passed / 0 failed(M5 后 593 + 2)

文档:doc/design/change-m3-access-and-loop.md
2026-10-22 15:23:36 +08:00
cflmy 409b8df2cb feat(check): M5 隐式遮蔽 — > 调用上方的叙述作为描述(默认关闭)
规则:`>` 调用上方的叙述段即其"描述";段内反引号实体必须被该调用用到,
或能解析到模块/内置,否则报 label.implicit_stale(warning)。
段落边界:紧邻上一行起,允许一个分隔空行(blockquote 前常空一行),
遇第二个空行/标题/代码行即止。

关键决策:**默认关闭(--implicit-labels 开启)**,依据是实测噪音:
- 初版(任何反引号都算断言):lib+ext/ai 上 6 条警告,**全为误报**
  (`## open`、`{ path, kind }`、`source=`、`exec`/`net`)
- 加"实体名形状"过滤后:2 条
- 再加默认关闭:**0 条**
理由:描述一个调用可以用任意措辞,机械校验必然模糊;
默认开启就制造疲劳(违背 warning-fatigue-control)。这与 L1 不同:
L1 是"能证明才报",隐式检查是"可疑就报",必须 opt-in。

实体名过滤:首字符字母/_/非ASCII,其余字母数字/_/./非ASCII非空白
→ 排除 `## open` / `{ path, kind }` / `source=` / `path=`。

用法:marqdo check 文件 --implicit-labels

测试:3 个集成(默认静默 / opt-in 报不一致 / opt-in 对一致描述仍静默,
后两条是反向验证"不乱响");全量 593 passed / 0 failed(M6 后 590 + 3)。

文档:doc/design/change-m5-implicit-occlusion.md
2026-10-22 15:21:23 +08:00
cflmy 6bba0be6d2 feat(mlsp): M6 T1 会话内陈旧检测 — repair_apply 前后对照 + session.summary
机制:repair_apply 内同一作用域已同时持有 source(改前) 与 new_source(改后),
所以「描述是否还成立」可纯内存判定,无需 git/台账/exec:
  stale ⟺ 标签文本未变 ∧ payload 指纹变了
按 (标签文本, 出现序号) 配对 → 移动代码不误报。

协议:
  请求加可选 check_labels(默认 false,零开销零噪音)
  响应加 labels.stale[{label,line,code_past,code_now}] + newly_seen
  新增 session.summary → {labels_stale_seen, labels_fixed, labels_outstanding, items},
  返回后清零(客户端收尾调用一次即闭合,不主动打屏)

取舍:
- 标签变了 → 不报(作者改描述即"已复核"信号)
- 新标签 → 不报(无历史可比)
- 指纹用 Debug:只需进程内一致;跨版本稳定指纹留给 T2/T3
- code_past/code_now 用 view::expr_display 渲染成人可读的表面语法

实测:
  改 payload 0.1→0.2、标签不变 → stale 且带 code_past="100 * 0.1" / code_now="100 * 0.2"
  同时改标签 → stale: []
  session.summary → stale_seen=1, outstanding=1, items=["按税率算总价"]

测试:3 个集成(含反向验证"改描述即复核不误报");
全量 cargo test --release:590 passed / 0 failed(M10 后 587 + 3)

文档:doc/design/change-m6-t1-session.md
2026-10-22 15:19:17 +08:00
cflmy 1c90312c02 feat(ai): M10 把「接不了就申报」写进 agent 提示词(standing + how-to-act)
两处:
1) how-to-act 协议段(每轮都带):无法真正接通的capability 不许静默伪造、不许声称完成,
   改写成带状态的遮蔽,例如 [按关键词检索,接口未接,待开发](None);
   桩必须能跑并写清返回值(None 亦可);收尾用 labels.search 自查。
2) 默认 standing(p):追加一句"接不了就在描述里申报(待开发/模拟),别假装成功"。

为什么两处:standing 定基调(每轮开头),how-to-act 定动作(每轮),
只写一处会被长上下文冲淡或缺动机。
设计要点:给范式而非规则(可直接抄)、给返回值要求(对应 label.empty_payload)、
给自查动作(labels.search)、用英文与既有协议一致。

验证:marqdo check ext/ai/agent.mq.md(occlusion 模式)通过;
grep 确认两处文本落地;全量回归 587 passed / 0 failed(不改逻辑)。

文档:doc/design/change-m10-engineering-habits.md
2026-10-22 15:17:43 +08:00
cflmy fd0cfcb566 feat(labels): M9 两级词表检索 — labels CLI + MLSP labels.search
第一级(内置,数据常量):六组关键词 —— 未完成/假数据/示例/实验/废弃/待校验,
pending = 未完成 ∪ 假数据。作用是默认查询、LLM 范例、跨项目可比。
第二级(参数):--grep 替换,--also-builtin 并集,--group 选组。
**词表是数据不是语法**:扩充它不改任何解析规则。

CLI:
  marqdo labels .                              # pending 口径
  marqdo labels . --grep "联调"                 # 自定义替换
  marqdo labels . --grep "联调" --also-builtin   # 并集
  marqdo labels . --group 示例,实验
  marqdo labels . --count / --json

MLSP:{"method":"labels.search","params":{path|source, grep?, also_builtin?, group?}}
→ {"ok":true,"words":[…],"count":N,"hits":[{line,unit,label,words,has_payload}]}
与 CLI 共用同一份 label::search。

检索语义 v1:子串匹配(CJK 无词边界)、多词 OR、英文大小写不敏感;
误判只影响计数,输出带描述原文可人工判断;不做否定语法(留 v1.1)。

测试:4 个集成(pending=2 / grep 替换=1 / also-builtin 并集=3 / MLSP 返回 hits);
全量 cargo test --release:587 passed / 0 failed(M4 后 583 + 4)。

实测:
  pending → 2 命中("待开发"、"模拟"两处)
  --grep 联调 → 1 命中
  --grep 联调 --also-builtin → 3 命中

文档:doc/design/change-m9-label-search.md
2026-10-22 15:16:39 +08:00
cflmy 6dd0ce47b1 feat(check): M4 L1 引用一致性 — 描述里的反引号实体必须可解析(label.ref_dangling)
规则:描述里的 `名字` = 断言,必须能解析 ——
要么 () 的实现用到它,要么文档定义了它(函数/参数/import 绑定/frontmatter 键),
要么是内置函数。否则报 label.ref_dangling(error)。

只认反引号(可证伪原则):普通汉字不参与判定,避免海量假阳性;
代价是作者不写反引号就得不到保护,这是刻意的——机器只校验它看得懂的断言。

实现:
- refs(label):扫描成对反引号取内部(未闭合/空串忽略,不 panic)
- payload_idents(payload):Var / callee / path 段 / receiver / [k] 变量键 / 插值变量
- module_symbols(module):函数与子函数、参数、import/use 绑定、frontmatter 键
- 内置函数用 crate::host::HostFn::from_name 判定
- OcclusionSite 增加 payload_idents,collect 阶段一次算好

实测:
  悬空 → "描述引用了不存在的实体:`税率` ..." 1 error, exit 1
  可解析(payload 变量 / len 内置 / `> 加 1 2` 行内调用)→ 零诊断

测试:3 个单测(抽取/多引用与散文混排/未闭合不 panic)
+ 2 个集成(悬空 exit 1;三类可解析零诊断)
全量 cargo test --release:583 passed / 0 failed(M2.5 后 578 + 5)

文档:doc/design/change-m4-label-refs.md
2026-10-22 15:14:50 +08:00
cflmy 1a94cc8490 feat(check): M2.5 遮蔽标签诊断 — label.missing(error) / label.empty_payload(warning)
新增 src/label.rs:
- OcclusionSite { label, has_payload, line, unit }
- collect(module):遍历函数/分支/循环/表达式收集遮蔽点(描述只读,不产生读引用)
- check(module, path):产出两条诊断

两条诊断:
- label.missing(error):[](...) 描述为空 —— 写一句人话,或改用不带遮蔽的写法
- label.empty_payload(warning):[描述]() 载荷为空 —— 写清桩返回什么(None/0),或补实现
warning 不影响退出码;JSON 出口自动继承既有 schema(含 doc_quote/span/suggestion)。

接入 check_module:walk 之后 extend(crate::label::check(..)),保持一行;
M4(引用一致性)与 M9(检索)都往 label 模块加,check 不再膨胀。

测试:
- 3 个集成(tests/occlusion.rs):空描述 exit 1、空载荷 exit 0、干净样例无诊断
- 全量 cargo test --release:578 passed / 0 failed(M2 后 575 + 3)
反向验证:干净样例必须零输出,证明不会误响。

实测:
  MARQDO_MARKUP=occlusion marqdo check empty-label.mq.md    # 1 error, exit 1
  MARQDO_MARKUP=occlusion marqdo check empty-payload.mq.md  # 1 warning, exit 0

文档:doc/design/change-m25-label-diagnostics.md
2026-10-22 15:13:33 +08:00
cflmy 11417c42e0 feat(lang): M2 遮蔽语法 [描述](实现) — 描述不执行,payload 是唯一执行体
新增 Expr::Occluded { label, payload: Option<Box<Expr>> }:
- [] 描述:自由文本,永不执行(仅用于检索/统计/过期校验)
- () 实现:唯一执行体;为空时值为 None(空载荷桩)
- 支持嵌套遮蔽、描述含空格与中文标点、\] 转义

关键决策:**模式开关,暂不切换语义**
[键](集合) 与 [描述](实现) 外形完全相同;M2 若直接改语义,全仓 506 处取元会
静默变成"遮蔽整个集合"(同形换义,文档点名的最坏一类)。
故 M2 只实现能力:
- 默认 Classic:MARQDO_MARKUP 未设 → [a](b) 仍是取元
- 纯度 Occlusion:MARQDO_MARKUP=occlusion/purity/1/on → 遮蔽
M7 才迁移语料、翻转默认、对旧形报 syntax.legacy_index 硬错误。

实现:
- ast.rs 新节点
- parse/expr.rs:Markup 枚举 + set_markup_default + parse_expr_markup(显式模式,
  避免测试依赖全局) + parse_occluded(描述扫描到 ]、\] 转义、必须紧跟 (、
  空载荷 → None)+ Parser.markup 字段
- interp.rs:有 payload 求值 payload,否则 None;collect_decl_reads 递归 payload
- bytecode/compile.rs:编译 payload(空则 Op::None_),双后端一致
- view/render.rs:expr_prec 渲染 [描述](payload) / [描述]()
- parse/mod.rs:pub mod expr
- main.rs:MARQDO_MARKUP 环境变量(init_markup_from_env)

测试:
- 8 个单元(值直通/空载荷/描述空格标点/转义/嵌套/classic 仍取元/缺括号报错)
- 3 个集成 tests/occlusion.rs + tests/occlusion/*.mq.md
- 全量 cargo test --release:575 passed / 0 failed(M1 后 565 + 10)
- tree 与 bytecode 双后端一致

文档:doc/design/change-m2-occlusion.md
2026-10-22 15:11:59 +08:00
cflmy 13012cac0e refactor: 精简 — 删除归档的 Rust web 插件(14,235 行)
审计结论:plugins/web-rust-archive/ 不是 Cargo workspace 成员、默认不构建、
无任何脚本/代码引用,官方 web 插件早已是 Go 版(plugins/web/ + libweb.so)。
仅作为"参考"留在树里,占 Rust 代码量约 18%。

删除内容:
- plugins/web-rust-archive/(31 个文件,14,235 行 Rust,528K)
- 更新三处指向:Cargo.toml 注释、plugins/web/README.md、ext-web-go-rewrite.md,
  说明历史保留在 git 中
- CHANGELOG Unreleased 记录此次精简

验证:cargo build --release 通过;cargo test --release 565 passed / 0 failed。

这是「不要让冗余代码毁坏 marqdo 设计」的第一步;后续按审计报告继续:
HostFn 元数据表合一(~400L)、plugin ABI 共用 SDK(~550L)、
catalog 复用 knowledge 助手(~140L)、view 路由表化(~130L)、
as_text 19→1(~90L)、view/html 字符串拆分与去重(~300L)。
2026-10-22 15:09:31 +08:00
cflmy 5a0f4ed747 refactor(parse): M1 收尾 — 删除重构后变成死代码的两个函数
- parse_call_arg_value_prefer_var:统一成 parse_call_arg_value_mode 后无调用点
- Parser::new_plain:改回 new(唯一构造点)

cargo build --release 警告清零;cargo test --lib 248 passed。
2026-10-22 15:08:55 +08:00
cflmy 05b8edc186 feat(parse): M1 ()内调用语法 — ) 终止 / 逗号 / 嵌套 / 带空格 callee
实现 M1(occlusion-syntax.md §13):把 `(…)` 变成一等调用外形。

四件事:
1. `)` 是参数终止符(历史缺陷:末个位置实参吞掉 `)`,导致 `加(31)` 报
   unknown function `加(31`)
2. 可选逗号分隔:`加(1, 2)` / `加(1 2)` 等价
3. 嵌套调用:`加(加(1 2), 10)` → 13
4. **callee 可含空格**:`加一 号(31)` → 32 —— 这是缺陷 D8 的结构性解法
   (`(` 是明确分隔符,空格不再参与切词)

实现要点:
- split_first_token / find_next_arg_boundary 重写为深度感知扫描器:
  跟踪 ()[]{} 嵌套 + 字符串 + 反引号;顶层 )/空白(括号形还含逗号)终止 token
  且不吞终止符;字符串内逗号不受影响。
- 新增 try_paren_call:callee = 第一个 '(' 之前的全部文本。
  护栏:callee 含 = [ ] ( ) " ' 即拒绝(避免把 `text=a(b)` 具名实参与
  `trim [stdout](…)` 方括号实参误判为调用);反引号允许(保留 `obj`.方法 写法)。
- 表达式级 postfix 调用(parse_primary 裸词分支,要求 `(` 紧跟)。
- is_bracket_callee_inner 允许空格:[加一 号] 31 亦可用。

关键决策(回归测试逼出来的):括号形与空格形的**参数值语义不同**——
括号形是表达式(允许嵌套调用),空格形仍是文本(`source=print(2+2)` 必须保持文本,
否则 foreign.run_lang 报 source must be text)。用 Parser.allow_paren_call +
parse_call_arg_value_mode(input, prefer_var, allow_call) 区分。

测试:新增 11 个单测(TDD:先 10 红后全绿);全量 cargo test --release
565 passed / 0 failed(基线 554 + 11);tree 与 bytecode 双后端输出一致;
端到端 marqdo run 六用例符合预期。

顺带:删除变成死代码的 end_of_quoted_string(编译警告清零)。

文档:doc/design/change-m1-paren-call.md(含决策依据、护栏表、边界)。
2026-10-22 15:08:02 +08:00
cflmy 8926f7bed6 docs(design): M0 语义冻结 — 遮蔽语法系列文档标记 Accepted
用户已批准:内置词表先按现方案(六组、两级检索),后续可调。
本提交只改文档状态,不动代码:

- occlusion-syntax.md:Proposed → Accepted · 实施中(M0 起)
- occlusion-description-and-search.md:Proposed → Accepted · 实施中
- warning-fatigue-control.md:Proposed → Accepted(机制基线:stale 是变更报告)
- staleness-providers.md:Proposed → Accepted · 修订
- t1-session-staleness.md:Proposed → Accepted · 机制说明
- label-freshness-and-repair.md:Proposed → Accepted

后续按 M1 → M2 → M2.5 → M4 → M9 → M10 → M6 → M5 → M3 → M7 → M8 逐步落地。
2026-10-22 15:03:26 +08:00
cflmy 18b0c655f7 docs: 两级词表定稿 + README 工程习惯 + M10 提示词落点
按用户决定:内置词表保留(作范例与默认检索集),检索语义仍由参数指定;
工程化写进 README;有提示词的更新提示词。

一、occlusion-description-and-search.md 改为「两级检索」
- 第一级 内置词表 = 范式 + 默认检索集 + 默认豁免集(零配置可用,跨项目可比,
  给 LLM 稳定范本,避免它每次发明措辞)。六组:未完成/假数据/演示/不稳/将删/待核;
  pending = 未完成 ∪ 假数据。
- 第二级 参数:--grep A,B 替换;--also-builtin 并集;--group 选内置组;MLSP 同构
  (labels.search { grep, also_builtin })。
- 明确:内置词表是数据不是语法;词表扩容不动语法;写别的措辞完全合法。
- 空载荷一律 warning(写 None 消除);「命中内置集则降为 hint」留作非默认旋钮。
- stale 豁免默认用内置 pending/将删组,--stub-words 可覆盖。
- 识别仍为纯子串、无位置/分隔符要求;识别不到不报错;误判只影响计数。

二、README.md 新增「工程习惯:允许申报未完成,但不允许假装完成」
- 示例:空载荷桩 / 假数据桩 + 桩契约
- 四条约定:桩必须能跑、必须写明返回值、申报有范例、接不了就申报别声称完成
- 盘点与门禁命令:labels pending / labels search --grep / --also-builtin /
  --count --baseline --fail-on-increase(棘轮)
- 指向两份设计文档

三、总纲增补 M10(工程化落点):README 一节 + ext/ai/agent.mq.md 提示词两处
(:48 默认 standing、:39 how-to-act 协议段)追加申报约定;顺序
M0→M1→M2→(M2.5)→M4→M9→M10→M6→M5→M3→M7→M8。

四、实现点明确分层:内置词表是常量数据、检索是纯函数、语法零依赖。

未改代码(README 为文档)。
2026-10-22 14:25:51 +08:00
cflmy 924885969f docs(design): 删除内置词表,检索改为调用方传词;空载荷一律 warning
用户质疑「关键词表其实不是很有必要,为什么不能允许 LLM 直接传入某个关键词做检索」——成立,
词表是冗余层。本文重写并改名 occlusion-description-and-search.md(原 occlusion-tags-and-stubs.md)。

一、编译器不再内置任何词表
只做两件事:原样保存描述字符串 + 提供参数化检索。
  marqdo labels search --grep 待开发,未实现,开发中   # OR 子串匹配
  marqdo labels search --grep 接口 --json            # 任意词
  marqdo labels search --grep 待开发 --count         # 只数数
MLSP 对应 labels.search。
删词表的理由:词表是语义偏见("什么算未完成"是项目判断);永远不全
(开发中/未接/待联调/占位/TODO 追不上真实语言);闭集要改编译器;分类应在查询期而非编译期;
LLM 更会挑词。**编译器保持哑,查询保持聪明。**

二、唯一代价与其解法
CI 需要"什么算欠债"的定义 → 不是把词表放回编译器,而是**在调用处声明**(通常写在 CI 脚本):
  marqdo labels search --grep "待开发,未实现,开发中,模拟,桩" --count \
    --baseline .marqdo/pending.json --fail-on-increase
词集在仓库里可读可改可评审,换项目只换词集,编译器一行不改。

三、空载荷改为**一律 warning**
原设计"已申报则不打扰"依赖词表;词表删掉后无法判定是否申报,故改为一律:
() 为空 → label.empty_payload。修法极简——写 None 或一个真实返回值。
实测确认 None 是合法表达式(json.stringify → null),所以 [功能开发中](None) 可用。
补充:遮蔽语法是新形式,今天仓库里一处都没有,**这条 warning 不可能产生历史债**。

四、stale 豁免也改为调用方决定
check --stub-words "待开发,模拟" / MLSP validate.stub_words;**不传则不豁免**。
与"参数化"一致:豁免也是调用方的判断,不在编译器里写死。

五、检索语义 v1:子串匹配(CJK 无词边界)+ OR + 英文忽略大小写;
输出含文件/行号/描述原文/() 代码/命中词;误判必然存在但只影响计数,且输出带原文可人工判断;
不做否定语法(留 v1.1「否定词窗口」可选项)。

六、工程化章节保留并简化:agent 提示词(写不了就申报、桩必须能跑、写清返回值、
收尾用 labels.search 自查)、四个工具面、四个指标(pending_count/unlabeled_empty/stub_ratio/stub_age)。

七、实现点:无任何词表常量;src/label.rs 为索引与检索器;
check 三条硬规则(label.missing error / label.ref_dangling error / label.empty_payload warning);
描述不影响求值;空载荷 → None。

同步 occlusion-syntax.md(空载荷说明改为一律 warning、M9 改为「描述检索与桩」、增补链接)
与 doc/README.md 索引;文档改名为 occlusion-description-and-search.md。未改代码。
2026-10-22 14:21:36 +08:00
cflmy 619271b8eb docs(design): 关键词改为纯子串检索(无分隔符)+ 空载荷 warning + 工程化实践
按用户两点修正:

一、关键词匹配不再有任何位置/分隔符规则 —— **纯子串检索**
[某某功能开发中]() 合法且可被统计;[搜索接入,待开发]、[【待开发】x] 同样命中。
关键词表扩为六组(未完成/假数据/演示/不稳/将删/待核),每组含同义词
(待开发·未开发·开发中·未实现·待接…;模拟·假数据·桩·占位·stub…)。
识别不到不报错不提示;最多取 3 组,最强者决定语义(未完成>假数据>示例>实验,将删正交)。
诚实写明子串必然误判([不属于待开发范围] 会命中):不影响执行,只让计数偏大;
stubs --list 显示描述原文可人工识别;否定词窗口留作 v1.1 可选。

二、空载荷必须提示,不得静默
() 为空 → label.empty_payload(**warning**);**若描述已含关键词(已申报)则不报**
——否则每个桩都报,正好制造要消灭的疲劳。
文案:「空载荷遮蔽:请补 (),或在描述里写明未完成状态」。

三、新增「工程化」一节(本设计的真正落点)
- §5.1 可直接放进 agent standing 的提示词片段:接不了就申报,别静默伪造、别声称已完成;
  桩必须能跑,返回值建议带 stub:true;收尾用 stubs 工具确认剩余项。
  要点:把"编造"变成"填表"——模型不必判断算不算伪造,只需写状态词。
- §5.2 三个 LLM 工具面:stubs --json(待办)/ --changed(本次改过的桩)/ labels --grep(任意词检索)
- §5.3 工程指标:pending_count、unlabeled_empty、stub_ratio、stub_age
- §5.4 CLI 示例

四、生命周期与防疲劳协同保持:桩(含空载荷、含未完成/假数据/将删)豁免 stale;
债务用棘轮;空载荷只在未申报时警告(说过的不再重复)。

实现点更新:src/label.rs 为检索器(label_text.contains(word)),
check 三条硬规则(label.missing / label.ref_dangling / label.empty_payload warning),
关键词不影响求值,空载荷→None。

同步 occlusion-syntax.md(文法允许空载荷 + 空载荷说明 + M9 改为「关键词与桩」+ 增补措辞)
与 doc/README.md 索引。未改代码。
2026-10-22 14:18:58 +08:00
cflmy 719b7a8d82 docs(design): 修正标签定位 — 描述是自由文本,内置词只做检索不做语法
按用户修正重写 occlusion-tags-and-stubs.md:
1. `[]` 里是**纯粹的描述文字,对执行零作用**;编译器不解析,只在其内**检索**
   (供统计、清单、LLM 待办)。写成 `[某个功能,没开发完成]()` 完全合法。
2. **标签不是语法**,是内置词;想被统计就顺手写上 `[某个功能,没开发完成。待开发]()`。
3. 标签的作用是"让人和模型多看一眼",不是审批、不是门禁——所以标在任何地方都无害。

识别规则改为检索语义:
- 结尾识别([搜索接入,待开发] / [搜索接入-待开发] / [功能待开发])
- 显式括号识别(【待开发】可出现在任意位置)
- 句中裸词不识别(避免误判)
- **识别不到不报错、不提示**(描述自由,机器只是"看见了就记一笔")

撤回上一版的错误判断:原把 `[税率-待开发](0.1)` 列为反例是错的。
标在已知常量上也无害——多四个字换来一次深入检查与阅读,按用户判断**收益优先**。
仅保留不报警的提醒:stubs --changed / --uncounted 展示债务构成,避免数字被撑大后失去参考。

空载荷语义调整:描述非空时 `()` 可空(返回 None),并**自动计入 `stubs --uncounted`**
(未标注的桩也会被看见),不再把"必须有内置词"作为语法门槛。

桩豁免 stale 保持(待开发/模拟/废弃,以及空载荷),并补"防忘去标签"的兜底:
stubs --changed + 会话汇总里的 stubs_touched(一次性,不催)。

实现点相应改为"检索层":parse 原样保存描述字符串;src/label.rs 为检索器;
Tag 为闭集枚举但词表可扩(后续支持 frontmatter 自定义),**不影响任何语法规则**;
check 只保留两条硬规则(label.missing 描述为空、label.ref_dangling 引用悬空)。

同步 occlusion-syntax.md(增补措辞 + M9 改为"检索层")与 doc/README.md 索引。未改代码。
2026-10-22 14:14:15 +08:00
cflmy dfe99a10b4 docs(design): 遮蔽标签与桩 — 把 LLM 的「假接通」改造成可结算的欠据
按用户提议新增:描述文字内可带尾标签([某某功能-示例-待开发](实现)),
编译器在描述里检索标签,从而让"未开发"变成可枚举、可统计、可门禁的债务。

核心框架:**遮蔽是承诺,承诺有三态** —— 兑现(fresh) / 过期(stale) / 尚未兑现(pending)。
前两态由新鲜度机制管,第三态由标签管。于是假接通从"无法追踪的谎言"变成"可结算的欠据"。

一、动机:LLM 假接通的三条路 —— 禁止(改隐蔽)、放任(静默撒谎)、**申报(本方案)**。
关键不是提高道德要求,而是改变激励:申报比伪造省力,且申报后代码照样能跑。

二、()` 内部语法定稿(用户授权自行制定)
- 取元:at(表, 键) / get(表, 键, 默认)
- 调用:callee(args),逗号可选;**callee = 第一个 '(' 之前的全部文本**(空格合法,解决 D8)
- 循环:- [描述](遍历 集合 为 变量),变量名搬进 ()
- 空载荷:() 仅在带桩标签时合法(返回 None),否则 label.empty_payload

三、标签规范
形态 [描述-标签[-标签]](实现);抽取规则:**从右往左**剥离已知标签(最多 3 个),
分隔符 - 或 -;剩余为描述;未知尾段不剥离([报表-2026] 描述不变);
疑似拼错报 label.tag_suspect;字面尾标签用 \- 转义。
词汇表 v1 闭集:待开发 / 模拟 / 示例 / 实验 / 废弃(闭集才可枚举、可统计、可门禁)。
多标签以最强者决定语义:待开发 > 模拟 > 示例 > 实验;废弃正交。
标签放 [] 里而不是 () 里:人必须看得见、与描述同处一室、不可执行(守住铁律)、可正则检索。

四、桩的语义:必须能跑(不得报错)、必须有标签、不得被当成已完成。
返回手段:空载荷 None / 常量占位 / 假数据 / **桩+契约=有类型的洞**(推荐)。
建议惯例:桩返回值显式带 stub:true,下游跑通也知道是假的。

五、生命周期(自愈):写桩 → 计数 → 开发 → T1 检测 → 复核去标签 → 债务-1。
**桩豁免 stale**(待开发/模拟/废弃):否则 12 个桩变 12 条常驻警告,正好制造要消灭的疲劳。
代价是"做完了忘去标签" → 用 stubs --changed 与会话汇总里的 stubs_touched 兜住(一次性,不催)。

六、与防疲劳机制协同:桩豁免 stale;债务用**棘轮**(stubs.json 基线,只在增加时失败);
stubs 是按需命令不进 check 人类输出;会话末汇总带 stubs_touched。

七、编译器实现点:parse 抽标签 → ast Expr::Occluded{label,tags,inner} → 新增 src/label.rs →
check 报 label.missing/empty_payload/tag_suspect → interp **标签绝不影响求值** →
mlsp stubs → main marqdo stubs → view 桩徽章。
**铁律守住:[] 永不执行,标签只影响诊断/统计/呈现。**

八、示例集(按 LLM 真实风格):假装接入搜索 / 假算指标 / 假接通 ERP / 已废弃旧实现 /
反例(税率不该标待开发——桩只用于"应存在但未实现的连接",不是懒得查的数据)。

九、实施增补:M2 抽标签、M2.5 空载荷与 label.missing、M4 L1(桩不影响引用校验)、
**M9(新)marqdo stubs(清单/--json/--check 棘轮/--changed)+ MLSP stubs**、M6 汇总加
stubs_touched、M8 view 徽章与教程。顺序 M2→M2.5→M4→M9→M6→M8。

十、风险:标签滥用(棘轮+评审约定)、桩腐化(--changed 提示,不靠常驻警告)、
假功能上生产(view 显著标记 + 知识库仓可 error)、词汇不够(后续可配但须可枚举)、
**LLM 伪造标签**(标签只增加可见性,不减少任何检查)。

同步更新 occlusion-syntax.md(增补引用 + M9 行 + 顺序)与 doc/README.md 索引。未改代码。
2026-10-22 14:08:54 +08:00
cflmy fac68e85ea docs(design): 遮蔽语法总纲(实施依据)— 示例先行 + M0–M8 实施计划
按用户定调:不把 []() 写成「循环/表格取元/函数调用」的语法,而是写成
**遮蔽语法(occlusion syntax)**:用叙述显示逻辑、用括号承载实现,
解决"刻意语法设计导致文档不可读",并依靠链接特性使知识过期可被检查。

一、示例先行(六个)
1 嵌套取值:三层 [1]([苹果]([水果类](货架))) → [水果类里苹果的第 1 项价格](at(at(at(货架,水果类),苹果),1))
2 长表达式打断叙述 → [应缴税额](...) 让句子完整
3 抽象层次混杂 → 论证留在叙述,算法退居括号
4 循环来源不可见 → - [从篮子里取出的每个果子](遍历 篮子 为 果)
5 **带空格函数名(已实测)**:> 加一 号 31 ❌ unknown function 加一;
   括号调用 加一 号(31 ) ✅ 32 —— 因为 callee = 第一个 '(' 之前的全部文本,空格不再是切词依据
6 反例:描述=实现时不该遮蔽

二、核心定理(本文档的理论支点)
**遮蔽创造信任负债**:把实现藏起来,读者就必须相信描述;
不遮蔽时描述过期无伤大雅,遮蔽后描述过期=文档变假。
所以「新鲜度校验」不是附加功能,而是遮蔽语法的**合法性来源**与代价。

三、场景按动机分类(不按语法分类)
A 不可读 / B 打断叙述 / C 层次混杂 / D 来源不明 / E 名称受限。
D 与 E 是遮蔽顺带解决的问题,不是目的;按动机写才能覆盖未来没想到的不可读情形。

四、语法规范:[] 永不执行、() 唯一执行;空标签 label.missing(error);
() 内用现有表达式文法,callee 允许空格;取元改为 at/get(纯度);
循环 - [描述](遍历 集合 为 变量),变量名从 [] 搬进 ()。

五、两种遮蔽关系,**都要查**
显式遮蔽([]())与**隐式遮蔽(叙述段 + 紧接 > 调用)**——
按用户要求把 > 调用也纳入过期检查:取上方紧邻叙述段为描述,
其反引号实体须出现在实参/callee;无叙述或无反引号则跳过(零噪音)。

六、新鲜度机制:L1 引用一致性(零依赖)+ T1 会话内(repair_apply 前后版对比)
+ **会话末一次性汇总(用户要求做)**:{labels_stale_seen, fixed, outstanding, items};
能力自述与无 git 降级(沙箱 exec=false / WASM 均可用)。

七、实施计划 M0–M8(每个里程碑含目标/改动文件/关键点/测试/验收/回滚)
M0 语义冻结 / M1 () 内调用增强() 终止·逗号·嵌套·空格 callee)/ M2 遮蔽语法 /
M3 at·get 与循环 / M4 L1 / M5 隐式遮蔽 / M6 T1+汇总 / M7 迁移与版本门 / M8 呈现与门禁。
**顺序建议 M0→M1→M2→M4→M6→M5→M3→M7→M8**:先让"断言+复核+修复"跑通,
再动 506 处迁移(中间态最痛)。

八、迁移实测规模:取元 506 处/136 文件,循环 44 处/24 文件,可执行方括号调用 0
(189 行是 lib/* 的 Caller 说明,不执行)。旧形必须 syntax.legacy_index 硬报错
(同形换义最危险),并用 label.provisional 承接机械迁移,避免 506 处全红。

九、测试计划与风险登记:单元/金样/回归 554/双后端/迁移差异/反向验证/环境矩阵/性能;
硬要求"每个新检查必须证明它会响"。

十、附环境前置(踩过的坑):scripts/dev-env.sh + build-web-plugin.sh;
$HOME 不可写 → zig 缓存重定向;/tmp 是 noexec → TMPDIR 必须可执行。
基线 cargo test 554/0;check 对 59 文件 0 warning/0 error,任何里程碑不得变差。

同步在 doc/README.md 登记 5 份新设计文档。未改代码。
2026-10-22 14:03:31 +08:00
cflmy 639b0ebcd1 docs(design): 讲清 T1「会话内陈旧检测」— 为什么模型在结构上收不到重复警告
回答:能不能在不改变的情况下让模型免于多次警告疲劳。能,且几乎不用改什么。

一、机制成立的根据(代码事实)
repair_apply(src/mlsp.rs:233)里 source(before)与 apply_edits 后的 new_source(after)
在同一个函数作用域内同时存在。所以"比较改动前后"不需要任何外部东西:
改动前 AST / 改动后 AST / 标签配对 / () 指纹 / [] 文本,全部在内存里算完。
零 git、零台账、零缓存文件、零环境依赖——这就是"agent 回路根本不需要 VCS"的确切含义。

二、时序:模型在自己这次编辑的响应里收到
validate → repair_targets → 模型产出 edits → repair_apply(source, ranges, edits)
→ 内部 before/after 对比 → 响应追加 labels.stale[{text, code_past, code_now, span}]。
模型只需回答一个问题:"你刚动了这段实现,描述还成立吗"。

三、重复为什么在结构上消失(三性质,缺一不可)
作用域=自己的 diff(旧债永不进上下文);投递=一次(后续 validate 不再出现);
自包含(下一轮 diff 是新的,没碰就不提)。刻意取舍:**宁可漏一次,也不反复骚扰**。
对比:20 处标签的文件 5 轮修复,扫描式累计上百条,T1 最多 0–2 条且每条一次。

四、关键重构:它在性质上不是 warning,而是**编辑期诊断**
对照 lint 警告 / 编译器错误 / T1 stale 的四个维度(时机、数量、是否重复、用户态度)。
没有人抱怨"编译器又报语法错了",因为那是一次性、可归因、改动驱动的。
**疲劳不是靠压制解决的,是把 stale 从 lint 类别搬到编译错误类别解决的。**

五、「不改变」到什么程度
文档内容不变(不嵌指纹、不加 noqa);工作流不变;不新增状态文件;不依赖 VCS;
纯内存计算。唯一改动:MLSP 加一个可选参数 check_labels + 一个响应字段 labels。
缺省关闭 = 零开销零噪音。

六、配对规则(按标签文本配,不按行号)
标签未变+() 变=stale;标签变了=作者在更新描述(不报);新增/删除不报;移动位置不报。
→ "挪位置"不误报,"改计算"必报警。

七、漏掉的三层兜底:循环预算(现有 max_attempts:2 直接可用)、可选阻塞
check_labels:"block"、会话末一次性汇总。建议默认 true + 循环预算。

八、边界:T1 保证"改动者当场被问一次",不保证"全仓库始终新鲜"(那是 T2/T3 的活,
可选、不进默认路径)。

附 §1.1 指纹可行性:Expr 目前只有 Debug 无 PartialEq;T1 只需进程内一致,
用 format!("{:?}", expr) 即可;更严谨可补 derive(PartialEq)(Literal 含 f64,只能 PartialEq)。
T2/T3 才需要跨版本稳定指纹,那时再用 knowledge/fingerprint.rs。

未改代码。附四项待确认。
2026-10-22 13:52:26 +08:00
cflmy 2c4dac005c docs(design): 修订 — 标签保鲜不该依赖 git,改为「前一状态」provider 分层
用户反驳成立:不是所有开发都用 git,依赖 git 不是好设计。三条理由:
1. 环境覆盖不到:沙箱 allow_exec=false(src/host/sandbox_fs.rs:378)文档内调不了 git;
   浏览器 WASM(wasm32)无进程能力;单文件/zip 工件无 .git;非 git 用户无从使用
2. 语言不该绑定 VCS:把语义正确性外包给"某工具目录是否存在"
3. 最要命的:最高价值场景(agent 修复回路)恰在不能调 git 的环境里

修订方案:保住 M5 的**原则**(变更驱动而非扫描驱动),把"前一状态"抽象为 provider:
判定逻辑只有一份 stale ⟺ fingerprint(()) 变 ∧ label 未变;变的只是 prev 从哪来。

四层能力:
- T0 引用一致性(零依赖,纯文档)——查引用腐烂
- T1 会话内前后对照(零依赖,最高性价比)——repair_apply / view 保存 / 编辑器钩子 / agent diff
- T2 外部历史源(可选,git/hg/svn 适配器)——跨会话漂移
- T3 台账(可选,.marqdo/labels.json)——无 VCS 时的持久化 + 确认状态

环境能力矩阵:CLI+git / CLI 无 VCS / agent 沙箱 / 浏览器 WASM / 单文件 / 对象存储,
**没有一行全 ❌**——T0+T1 在所有环境成立,足以支撑"agent 改动即时提醒"。

最关键一条:repair_apply 已同时持有 before(source) 与 after(应用 edits 后),
所以建议协议加一个可选 base_code / check_labels 字段,Marqdo 在同一次调用内即可算出
"哪些标签的 () 指纹变了而 [] 没变",返回带 code_past / code_now 的 stale 列表。
零外部状态、零依赖、零 git——而这正是模型改完代码别忘了改描述的场景。

provider 五条硬规则:核心不依赖 / 缺失即静默降级(不报错不提示)/ 能力必须自述
(labels status 显示启用层级,避免"没报=没问题"的误判)/ 判定单一定义 / 不写进文档。

被否:强制 git、文档内嵌指纹、零宽字符、mtime 启发式、# noqa、静音清单。

同步修订 warning-fatigue-control.md:M5a 由"核心"降级为可选 T2 适配器,
补一条验收指标"provider 缺失时标签相关输出也必须为 0"。其余结论不受影响。

未改代码。附五项待决策(是否接受分层、T1 是否够、能力自述、T2 适配范围、T3 是否推迟)。
2026-10-22 13:49:03 +08:00
cflmy 0ac661eef2 docs(design): 防警告疲劳机制 — stale 必须是「变更报告」而非「扫描报告」
触发:用户指出 []() 每次报 warning 会导致烦躁与忽略,机制必须先定再开工。

一、为什么标签检查特别容易被忽视
高频(标签密度≈每个取值/调用)、主观(自然语言断言,机器只能近似)、
持续(代码天天改)。且实测基线是**零噪音**:lib/ + ext/ai/ 共 59 文件跑 check,
warning=0、error=0 —— 标签校验会成为项目第一个持续警告源,一次就要做对。

二、疲劳的真正根因不是"报得多",而是「同一件已知的事被反复告知」。
目标改成三条硬约束:没有新信息就不说话 / 说了就能做点什么 / 说过的就不再重复。

三、六个机制评估
M1 分级(按证据强度:error=能证明断裂,warning=能证明变化但不知谁错,hint=弱信号)
M2 聚合(check 人类输出最多一行,细节进 --json / view / labels)
M3 基线(bootstrap 静默吸收,用于迁移后的存量)
M4 确认即静默(ack 台账,同指纹不再报)
M5 **结构化 diff(推荐核心)**:stale 只在「() 变了 ∧ [] 没变 ∧ 在本次变更集」时报
M6 文档内抑制 # noqa —— **否决**(污染文档、不可审计、会永久化;抑制只放台账/配置)

四、M5 的性质(这是把疲劳问题降级的关键)
零台账(git 即台账,无新文件/无合并冲突)、零基线(首次也安静)、
零重复(提交后 diff 清空报告即消失)、天生带 before/after(正好是 LLM 复核输入)、
格式化免疫(比 AST 指纹而非文本)。非 git 环境降级为 L1,仍安静。

五、推荐组合
默认:M5a + 默认 hint + check 最多一行 + 每条带定位/before-after/建议 + 变更集去重 + 非 git 降级
严格模式(知识库仓 opt-in):升 warning/error + 基线与确认台账 + **棘轮(允许存量、禁止新增)**
+ labels status 进 CI。棘轮是最值得抄的机制:老债不阻塞、新债立刻拦、债务数字可下降。

六、确认的三种语义:改标签 / 改代码 / 显式确认。
建议三者都提供,但显式确认留痕(confirmed_by + 次数)——**被反复确认的标签本身是坏味道**。

七、可证伪原则:只有能被证伪的断言才被检查。标签含反引号实体→参与 L1;纯口语→L1 不检查。
检查成本由书写具体程度决定,同时反向抑制"为凑数写废话"。

八、agent 节流:只对它自己刚改到的标签做检查,每轮一次,超 N 条只报前 N+汇总。
模型看到的是"你刚改的这处描述可能不成立",而不是"全仓库 200 处过期"。

九、防「用忽视解决」三道闸:债务可见(labels status 给数字)、可 gate(error)、
可审计抑制(labels audit + 过期抑制提示)。

十、验收指标(写进文档防走样):无变更时标签相关输出=0;单变更集提示≤3 或≤20%;
重复=0;可行动率 100%;误报≤10%;check 人类输出≤1 行;hint/warning 不影响退出码。

未改代码。附五项待决策(核心机制、默认级别、棘轮、确认留痕、check 聚合行是否常显)。
2026-10-22 13:44:36 +08:00
cflmy 1dd74578b5 docs(design): 纯度路线落地 + 标签过期检测(L1/L2/L3),对接 MLSP 修复回路
决策:取纯度(() 只装机器语句,取元搬进 ());标签可省略书写但编译器必须报错;
循环写法不追求统一。

一、纯度强制两件事(推论)
① 必须有不带标签的普通表达式写法(否则每个访问都被迫配人话 = 仪式感复辟)
② 带标签形式是「想做断言时的可选包装」——由此解决「标签凑数」退化:
   不想断言就别用这个形式。
普通取元四个候选:A 现有内建 at value= index=(零新语法、啰嗦)、
B 后置方括号 篮子[1](自然但引入第二种方括号角色)、C at(篮子, 1)(需逗号参数,
与之前想要的 f(args) 同一改动)、D 点号(与库路径/方法冲突)。建议 C,零风险选 A。
空标签 [](…) → label.missing 硬错误。
循环:- [从篮子取出的每个果子](foreach 篮子 为 果),变量名从 [] 搬进 (),不再让 [] 兼任标识符。

二、标签 = 可校验断言的载体(不是注释)
锚定 AST(有 span)/ 可机械核验 / 可进修复协议 / 变更可感知。

三、过期检测三层
L1 引用一致性(无状态):标签内反引号=实体断言,必须可解析且出现在 () 中。
   低假阳性(只有显式反引号才算),但查不出语义腐烂(乘改除)。
L2 指纹台账(有状态):.marqdo/labels.json 记 hash(())+code_quote。
   复用 knowledge/fingerprint.rs(collect_calls/ops_hint/fingerprint_hash)。
   键=规范化标签文本+序号,移动代码不误报。能查语义腐烂。
   存 code_quote = 「保留内容用于校验」的对称物:doc_quote 留 [],code_quote 留 ()。
L3 LLM 复核:诊断同时带 doc_quote / code_past / code_now,模型三选一
   (改标签 / 改代码 / 确认无害),走 repair_targets → repair_apply 越界必拒 → 复验 → 写回台账。

四、与现有设施对接(落地成本低的关键)
- diagnostics.rs to_json 已有 doc_anchor / doc_quote / contract_ref{declared} / suggestion
  → 无需新造字段;contract_ref.declared 就是「声明 vs 实际」的现成先例,只是从类型层下沉到散文层
- contract.rs:203 Contract::diagnostic 一次性装配同一组字段,标签诊断照抄,kind 换 "label"
- mlsp repair_apply 的 ranges 天然支持多区间 → 允许「标签行 ∪ 代码行」,护栏不变
- knowledge/lifecycle.rs 已有 find_stale/stale_json/verify → 标签过期走同一条 stale 通道,
  成为知识库健康指标(知识腐烂的新类型:文档断言 vs 实现)

五、诊断 schema 草案:code=label.stale,doc_quote=标签原文,
label_ref{text,refs,missing_refs,code_past,code_now,fingerprint_past/now,layer},
suggestion 给可执行建议,ranges=[[行,行]]。

六、反幻觉的精确表述:只解决「文档断言与实现不一致」这一类;
不解决模型编造、代码本身写错、标签含糊。价值 = 把文档可信度从「靠人自觉」
提升到「可机械复核 + 可被 LLM 裁决」。

七、风险诚实清单:误报疲劳(最危险,L1 只在能证明冲突时报、L2 同指纹只报一次)、
台账腐烂与合并冲突(视为可丢弃缓存、重算优先)、语义鸿沟(L1 边界)、
LLM 用幻觉修幻觉(护栏+双向信息+人工确认)、
**标签不得参与安全判定**(策略/沙箱/工具白名单只读 () 语义,永不读 [])、增量成本。

八、分阶段 P0 纯度语法 / P1 L1 / P2 schema+MLSP / P3 台账 / P4 L3+CI。
建议先做 P1(零状态、确定性、不依赖纯度迁移),先把「断言→复核→修复」链路跑通。

未改代码。附五项待决策。
2026-10-22 13:40:02 +08:00
cflmy 14114993c4 docs(design): 评定「[描述](语句)」提案 — 方括号=人话、圆括号=机器话
提案:`[]()` 不再读作"两个部分两个含义",而是 `[描述性显示文字](实际执行的简短语句)`;
表格取元的嵌套难描述也没关系——括号里可以写长,方括号只放人话。

一、为什么这个写法"美":三处真实同构
- 超链接 `<a>`:可见文本 ↔ 目标
- 文学编程 chunk 名(Knuth `<<name>>`)
- **Marqdo 自己的 `![marqdo-out](…)`**:方括号放指令、圆括号放负载
经验佐证:`[f] args` 可执行用量 **0**;189 处全是 lib/* 的 `Caller:` 用法说明(给人看)。
`[]` 在实践中的天性确实偏"描述"。

二、三个真实收益(本文最大的肯定)
1. 两条规则变一条:**解散 link-call 死结**。前几轮反复撞墙是因为默认 `()` 只能是集合;
   改成"任意语句"后,取元只是特例,不再独占外形。
2. 嵌套可读:`[1]([苹果](货架))` → `[货架里苹果的第一项](…)`,人读标签、机器读嵌套。
3. 循环来源可见 —— 但要精确限定:`view` 已把 foreach 渲染成带徽章的 loop-card
   (render.rs:1354),取元仍渲染为字面 `[键](集合)`(1502)。所以问题只在**通用 Markdown
   阅读器**里成立,而这恰是多数场合。由此升级为更强的论点:
   **语义正确性不该依赖读者是否用了 marqdo view。**
附:标签→锚点→点击跳转可行(view 已有 span),且 agent 用人话定位比行列号稳。

三、结构性弱点(代价最大、最易被忽略)
若 `[]` 只是标签,`(菜单)` 就只是"整个菜单",取元必须搬进 `()`:
点号 / 函数式 / 嵌套方括号 / 英文式,每种都有消歧问题。
→ **收益一能否兑现,取决于愿不愿新增一条取元规则**。用一条新规则换一条旧规则,不必然净简化。

四、描述漂移:不同意"不重要"
1. 它是注释的回归(贴在执行体上、必须短、可说谎的文本)
2. 一旦作为定位锚点,漂移就有操作后果(错误信息也撒谎)
3. agent 安全面:标签是模型会信任的自然语言,"标签写只读、代码做写入"从文档瑕疵升级为误导通道
缓释:①标签永不参与绑定 ②check 做词重叠校验(标签提到的名字全不在 () 中出现 → warn)
③trace 双输出 ④策略判定绝不读标签。**② 最划算,能抓住最恶劣的一类漂移。**

五、采用风险:可能重演 v0.3 废除 `+ 名` 的"仪式感"(原文理由:仪式感强、与正文脱节)。
两种可预测退化:凑数、噪音。矛盾在于"可省略 vs 歧义回归"必须在设计里正面解决。

六、迁移面实测:索引 506 处 / 136 文件;循环 44 处 / 24 文件;可执行方括号调用 0。
若 `[]` 改纯标签,506 处是**同形换义**(不报错就变义)——最坏一类,必须硬报错 + 版本门。

七、两条落地路线
- 路线一(推荐)双层:长形 `[描述](语句)` + 短形 `[键](集合)` 定义为长形缩写。零迁移、
  调用零成本收编、收益全拿;代价是短形两义仍在但可解释。
- 路线二(纯度):`()` 只装机器语句,取元搬进去;语义最纯但要新增取元规则 + 506 处迁移。

八、评定:本系列结构最强的提案(哲学自洽 ★★★★★,解决问题 ★★★★☆,
规则净简化 ★★★☆☆,迁移风险 ★★☆☆☆,漂移风险 ★★★☆☆)。
建议走双层 + 先把「词重叠校验」做出来,让标签从装饰变成可轻度核验的描述,
才配得上"AI 定位锚点"与"点击跳转"两个职责。

未改代码。附五项待决策。
2026-10-22 13:30:07 +08:00
cflmy e80c944c40 docs(design): 函数的水土不服与「命名/代入」重构 — 设计哲学层(含 1322 函数实测分类)
命题(来自用户):函数是预先抽象,自然语言是即席描述;正常人不会说「要算 37 的两倍
得先抽象一个函数」,而是直接说乘二。故函数在代码即文档里错位。

本文只谈语义表示与自然语言映射,不谈编译器与语法糖。

一、量化证据:Marqdo 的 ## 其实不是「过程」
1322 个函数:
- 纯返回式(零可执行语句,只有一个返回表达式)765(57.9%)
- 一行式 935(70.7%);可执行语句数中位数 0、平均 2.2
- 较长(≥10 行)仅 62(4.7%)
按语义功能分类:
- 纯命名式 754(57.0%)→ 对应「所谓 X,是指…」
- 条款式(有分支无副作用)103(7.8%)→ 对应「凡…则…」
- 遍历式 26(2.0%)、命令式(含 print)83(6.3%)、线性计算 356(26.9%)
结论:命名+条款 = 64.8%,真实副作用只有 6.3%。
即三分之二的 ## 落在「定义/条款」两种自然语言形态里,不需要过程语义。

二、复用经济学:为什么文档里抽象格外别扭
成本 = 定义 + 读者的跳转 + 维护;收益 = N 次复用省下的重复。
抽象值得做 ⟺ 复用次数×复杂度 > 定义成本 + N×跳转成本。
代码里 N 大、跳转便宜;文档里 N 常为 1、跳转昂贵(读者被打断)。
→ 大量文档中的「函数」是负收益:只用一次却强迫回头查定义。
这正是「正常人不会这么说话」的形式化解释:说话默认对方不知道你的定义,倾向就地展开。

三、自然语言复用的六种形态(程序语言只承认一种)
重复 / 指称(该金额)/ 命名(所谓 X)/ 条款(凡…则…)/ 范例(以 37 为例)/ 表格。
命名只是六分之一,却被程序语言变成唯一入口。

四、三个语义立场
甲 定义—代入:一段正文被命名,使用=按角色代入后重述。覆盖 58% 现状,与 ## 结构一致。
乙 条款—援引:条件→结论,援引条款给出适用事实。最贴中文说明文,1./2./3. 已有。
丙 配方—配料:用料表+做法,参数=配料行。最可读但表达力最弱、无法组合。
→ 推荐甲为主、乙为辅;丙作为甲的呈现(契约表)。

五、代入 vs 调用(为什么代入更贴人话)
心理动作、输入意义(一套名字 vs 两套)、结果意义、可嵌入叙述、一次性使用可取消。
关键:抽象必须能被「取消」——就地描述与命名代入是同一切换,提升/展开是编辑动作而非必经入口。

六、落到已有载体:只缺一环
命名(#/##)、正文(叙述+标记)、未定的量(体推断)、结论(*…*)、条款(1./2./3.)、
配料表(GFM+契约表)全部已有。**唯一缺的是「具名给值」**——问题因此缩小。

七、硬边界:自然性 vs 可判定性
角色具名(可判定,略啰嗦)/ 位置(实测叙述顺序一变绑定就翻转)/
语境隐式(130 个形参名撞车,不可判定)。
→ 只有「具名」同时可读且可判定。也解释了为何叙述式动词不可取:把判定交给未标记的词。

八、三个未决哲学难题:副作用(6.3% 需保留命令语义)、递归(代入=有限展开)、定义时序(能否前向引用)。

未改代码。附四项待裁决(含是否接受「不支持递归」、具名给值的最小形态)。
2026-10-22 13:14:03 +08:00
cflmy 30cd5a0833 docs(design): 在「只执行标记」原则下设计调用语法 — 含 3.8× 后端实测与叙述顺序实验
接受纠正:上一轮的「叙述式动词」L0 方案违背「叙述默认安全、只执行标记」的底层原则,
已否决。本文从该原则重新推导调用语法。

设计约束(硬):调用的每个语义成分(被调者、每个实参、绑定关系)必须落在标记内,
叙述词只能连接与解释,永不改变语义。

一、标记字母表:可承载调用的只有 `> 行`、`**…**`、`[callee]` 三种;
`[k](coll)` 已被取元独占(前几轮结论)。问题收敛为「在标记内如何连接函数名与槽赋值」。

二、三个候选
- A 括注具名 `**加一函数(n=31)**` —— 与通用函数调用同构,取元不冲突,具名可静态映射槽位
- B 箭头 `**n=31 → 加一函数**` —— 最贴汉语语序、链式可读,但优先级与返回值语义需增设计
- C 空格式 `**加一函数 n=31**` —— 今天就能跑(实测 **r = 加 1 2** 已可用),但参数边界靠空格

三、「不分实参形参」的编译器面(实测,结论意外)
| 路径 | 绑定方式 | 200k 次(1 int) | 2000 次(500 元素) |
| 树遍历(默认) | Env{HashMap},实参 k.clone()+v.clone() 深拷贝 | 167ms | 66ms |
| 字节码 | slots:Vec<Value>,pop 按位置移动,无克隆无哈希 | 44ms | 23ms |
即「变量始终在某个位置」已是字节码现实(vm.rs Op::Call),收益 3.8× 是真的。
但**它与语法无关**:槽位化只需编译期知道形参顺序,而体推断已给出顺序。
瓶颈是树遍历用名字哈希+深拷贝、以及默认后端是 Tree。
→ 不要用性能论证语义变更;省 IO 走「默认切字节码/解释器槽位化」这条正交工程路径。

四、真实耦合点:具名 vs 位置(决定性实验)
形参顺序 = 叙述里首次声明顺序(v0.3 §8.2),而叙述可自由改写。两文件只差语序:
| 调用 | 叙述 a,b | 叙述 b,a |
| a=10 b=3 | 7 | -7(随函数体改变,符合预期) |
| 位置 10 3 | 7(a=10,b=3) | **7(b=10,a=3)绑定翻转,不报错** |
→ 「实参形参不分」时位置传参等于把语义挂在可改写的叙述顺序上。
推论:调用应以具名为准;具名同时让编译期静态映射 slots[i],既稳又快。

五、建议
- 主形态 A:`**f(k=v)**`;单参允许 `f(31)`;多参要求具名,旧位置写法 check 期 warn
- B 箭头作后续可选项(定位为语句式组合子)
- 明确不做:未标记动词、[f](args)(撞取元,已实测 2 个真实冲突文件)、
  动态作用域(七条硬伤 + 130 个撞车形参名)、位置实参作主流

附优劣总表与待决策四项(含是否把默认后端切字节码)。未改代码。
2026-10-22 13:06:57 +08:00
cflmy e2068c2051 docs(design): 参数能否从上下文推断 — 拆成 L0/L1/L2 三层,附 1322 函数语料实测
回应「让函数参数从上下文推断,写成 对**n=31**执行**加一函数** 可能吗」。

核心结论:**用户示例其实不需要隐式推断** —— n=31 就写在句子里,
缺的是「叙述式调用」语法,不是新的作用域语义。拆成三层:
- L0 叙述式调用(绑定在句中)→ 纯语法糖,安全,建议做
- L1 就近绑定(上一行绑定,下一行只写函数)→ 段落级隐式,不建议
- L2 真隐式(动态作用域)→ 不建议,七条硬伤

实测(1.5.2,8 组):
1. 示例原样跑:无输出、无报错、exit 0 —— 静默 no-op
2. 拆开看:散文行里的 **n=31** **真的执行了**(main 的 n 变 31);
   而 **加一函数** 只被求值丢弃,从未被当作调用
3. `**n = 31**` + `> 加一函数`(不传参)→ missing argument for parameter n
   —— 函数看不见调用者作用域(严格分离,这是语义基石)
4. `> 加一函数 n=31` → 32,今天就能做
5. `# main` 读 frontmatter `税率` → 0.1 ✅;`## 函数` 读同一个 → undefined ❌

用户担心的「大项目变量名难用」有数据支撑(全仓库扫描 1322 个函数):
- 819 个不同形参名,其中 **130 个被 ≥5 个函数共用**
- 最严重:path 70、value 59、text 53、id 47、list 38、内容 38、路径 35
→ 若参数靠上下文推断,调用任何读 text 的函数都会捡到作用域里的 text,撞车是常态

L2 七条硬伤:同名捕获、递归自毁、无法复用、契约报废(call_arg_diag 没有校验点)、
指纹/arity 失真(隐式调用在 AST 上像零参)、沙箱隔离破坏、不可审计。

给出受控替代:**常量默认值** —— 形参未传入时取文件级常量(frontmatter),
静态可判定、不随调用者变化、契约与序列化都不受影响。

顺带发现并记录 **D11(高)**:函数可见环境随运行面不同。
- # main 走 Env::with_metadata(interp.rs:473)→ 能读 frontmatter
- 普通函数调用走 Env::new() → 读不到
- 浏览器 WASM 入口 invoke_in_entry(interp.rs:365)→ metadata + entry_bindings 都给
即同一份文档在 Web 能跑、在 CLI 报 undefined variable。已写入缺陷实录(含复现与两条修法,
倾向「统一为函数可见 metadata」,正好成为常量默认值的现成基础)。

未修改任何代码。
2026-10-22 13:00:01 +08:00
cflmy 9cda80ee7d docs(design): [函数名](参数) 与 f(参数) 调用写法评估 — 原型实测 554/0(已回退)
更正前两轮对用户意图的误读:用户问的是**调用写法**,不是表/函数即值。

核心结论:
- [函数名](参数) 技术上能做,但撞的是已定的取元语义
  「方括号=取出的名字,圆括号=从哪取」(collection-access-link.md §1;
  call-arguments.md §2 锁定 `]` 紧邻 `(` = 取元)
- 按名字消歧不可行(**实测证据**):全仓库 851 文件 / 2367 个 ## 名 /
  983 次 [k](c),键名与同文件函数名冲突 5 处、去重后 2 个真实文件:
    ext/data/db.mq.md:122        *[count](r)*        (## count + r 里的 count 列)
    examples/code-as-docs/index.mq.md:79  价=[单价](行)  (## 单价 + 行里的单价字段)
  函数名优先 → 打断这两处取元;数据优先 → 永远无法 [f](1) 调用。两条都走不通。
- 且存在不可消除的歧义子集:[f](1) 与 [1](篮子) 同形,单参调用永远无法表达;
  「多参能用、单参不能用」的语法不可教。

但去掉方括号的 函数名(参数) 是**完全空闲的语法**(实测原型前 加(1) 报
trailing input in expression),且原型验证可行:

原型(已回退,仅验证):
1. src/parse/expr.rs 新增 try_paren_call,紧随其后的 ( 视为参数列表
2. src/parse/mod.rs 两处「像调用」判定加 looks_like_paren_call,让单 token 也能进调用分支

原型实测:
- 加(1) / 加(1 2 ) / 加("1" "2") / txt.str_trim("  x  ") 均通过
- 加(1 2)、加(a=1 b=2)、加(1, 2)、嵌套 加(加(1 2) 3) 失败
- **全量 cargo test --release: 554 passed / 0 failed(零回归)**

关键判断:失败点不在语法而在**参数分词器**——加(1 2) 失败、加(1 2 ) 成功,
差别只是 ) 前多一个空格,说明 parse_call_args/split_first_token 把 ) 当成了
token 的一部分;修它要动所有调用共享的分词器。这解释了「看着 10 行、实为一次核心改动」。

另一个重要性质:f(args) 最终仍产出 CallExpr{callee,args},
EKC 指纹 collect_calls、契约校验、字节码 Op::Call(fid,argc) **全部自动兼容**——
它只换写法,不改调用模型(与一等函数方案本质不同)。

人读性:f(1 2) / f(a=1 b=2) 与数学记号同构、参数边界显式、渲染不成超链接,
优于 [f](1 2)(预览里会变成链接)。

建议:不做 [f](args);做 f(args),先具名后位置。
附工作量清单 9 项与三档实施选择(A 仅具名 / B 具名+位置 / C 全量)。未改代码。
2026-10-22 12:53:03 +08:00
cflmy eae4815fc7 docs(design): 函数能否解释为 GFM 表 — 11 组实验 + 史料考古(未改代码)
回应「代码函数(## 名 + 参数 + 体)从某种角度能否解释成 GFM 表,
这样的解释运行时有没有巨大风险、有没有实际收益、历史上出现过吗为什么放弃」。

核心答案:命题在 Marqdo 里**已经实现**,但实现的是「关于函数的表」(契约表),
不是「函数本身」。界:表能描述外延(输入→结果)与签名(元数据),
不能描述内涵(怎么算);而调用恰恰是内涵操作。
[k](集合) 是投影已有数据,f(x) 是计算新数据,只有 f 已是预先枚举的表函数才重合。

一、固定表格几何(实测)
- 1 列 N 行 → List;≥2 列 1 行 → Map 记录(实测 {"x":1,"y":2})
- ≥2 列 N 行 → **列向聚合** Map(实测 {"档位":[1,2],"税率":[...]})
- 行向记录必须显式标记(行/@/row),文档原话「不得与默认列向字典静默混用」
→ 「行 = 参数」在 Marqdo 里不是自然形态

二、命题已存在:契约表(tests/contracts/ok_contract.mq.md)
src/contract.rs:表头含 参数/返回/字段 + 必须有「类型」列 → 契约块。
契约表的首列标头正是 §3.5 那种「显式形态标记」的同类做法。

三、11 组实验(1.5.2 实跑)划定边界
- E1b 表列 n 但体不读 → > f 无参调用成功 → 表**不能声明**形参
- E3 叙述声明 n + 表 + 传"七" → 参数 n 期望 number,实际 text(契约校验)
- E4 无表 → 七1,不校验
- E5 + `n` 旧式形参行 + 表 → 契约生效(用户草图形态可用)
- E6 表写 2 行、体只读 1 个 → too many positional(**表 ≠ arity**)
- E7 单列参数表 → 七1,**契约静默失效**(1 列 = List,且 check 报"无契约问题")
- E8 重复行 → 取首行无诊断;E9 幽灵行 → 静默忽略
- E10 同一张表加 `tc` = 绑定 → 契约消失
→ 隐含规则:**未绑定的表 = 声明/元数据;绑定的表 = 数据**

四、若表成为定义(把静默漂移从"少个校验"升级为"少个参数")
漏类型列/表体漂移/重复行/调换行序都会变成绑定语义;
最致命的是行序携带语义——「把 b 行移到 a 上面」这个无害编辑会改变位置参数绑定。
而 [键](集合) 之所以安全是因为**键是显式的**,取元不依赖顺序。

五、链接式调用第三次论证(带史料)
collection-access-link.md §1「方括号 = 取出的名字,圆括号 = 从哪取」;
§4 非目标排除点号/在/箭头/(键)[集合];call-arguments.md 锁定 `]` 紧邻 `(` = 取元。
→ [f](args) 不是未决定,而是**已被明确分配给取元**。

六、史料:这条路是被反向走过的
- v0.2 要求手写 `+ 名` 形参表 → v0.3 列为**代价**(仪式感强、与正文脱节),
  P4 改为体推断,`+ 名` 标注「过渡兼容,新代码不推荐」
- objects.md §6 非目标:**用表格声明字段 schema**(表格仍表示数据集合)
- tables-maps-footnotes §3.3 行向记录「不默认」,§3.5 显式标记才开启
- collection-access-link §3 记录了取元语法的迁移与定稿

七、收益(诚实)
tool schema 最实:tools 已能写成记录行(tool_names 接受含 name/工具 的 Object),
但 agent_format_tools 只渲染 `- name`,说明与参数被丢弃——能力已在那儿,只差接上签名。

八、建议:表做声明不做定义,补三件事
① 消灭静默:契约表缺类型列/幽灵行/重复行/与 arity 不符 → check 应 warn(当前全静默)
② 反向生成:marqdo view 从签名生成契约表草案(单一真相仍是体,表是投影)
③ 签名可供机器消费:knowledge 能力条目带参数 schema → tool schema 自动生成
零语法改动。§9 给了「双写 + 一致性校验」的可试写法(E5 已验证可跑)。

未修改任何代码。
2026-10-22 12:46:13 +08:00
cflmy 3260494e5c docs(design): 评估「函数作为变量 / 函数即表」(未改代码)
回应「函数能不能是变量的一种,`函数名` = 参数|函数体 表,取元即调用」的提议。

核心结论:这个直觉在数学上成立,但一句话里混了四种不同的「函数」观,必须拆开:
- 外延观:函数是图 → 就是表,调用是查表(有限域才成立)
- 内涵观:函数是规则 → 调用是执行(定义域无穷,写不成表)
- 闭包观:函数 = 代码 + 环境
- 名字观:函数是命名空间一条(Marqdo 现状)
用户草图是「参数声明 + 函数体」的混合体,而「像表格取元」的直觉来自外延观。

现状实测(1.5.2,六组实验):
1. Value 枚举十种无函数;函数是 AST,挂 Module.functions
2. CallExpr.callee 是 String 不是 Expr → 语法上无法调用「计算出来的值」
3. 对象本来就是 Value::Map + _type 标签(对象是值,函数不是,这个不对称是关键)
4. 已存在 call_fn 按名字间接调用,但零参、限当前模块、只在运行期校验
5. 实验:`**f = > greet**` 报 missing argument(> 名字 是调用语法,无法引用函数本身)
6. 实验:表里存函数名 + [h](reg) + call_fn → 动态派发今天就能做

关键实测纠正(我最初写错、已改):
GFM 两列表绑定为「列映射」{"档位":[1,2],"税率":[...]},不是按首列键控的映射,
所以 [2](两列表) 报 missing map key 2。真正键→值查表需 Map(json.parse)
或用 table.index_of + table.at 显式索引(两条配方均已跑通)。

三条断裂点:表格有限 vs 函数常无限;函数体是代码不是数据(需 eval,静态检查/契约/
EKC 全失效);[k](x) 会被语义重载(与上一轮 [函数名](参数) 冲突同源)。

五条路径与代价对比(值模型改动/静态可索引/契约/EKC 指纹/序列化沙箱/成本),
并逐项分析对 Marqdo 特有机制的冲击:契约 T2.1/T2.2 依赖静态 target、
EKC 指纹 collect_calls 读静态 callee(src/knowledge/fingerprint.rs:76)、
value_to_json 对 Value 穷举(src/host/json.rs:98)、字节码 Op::Call(fid) 用编译期 id
(src/bytecode/compile.rs:709)。

建议分阶段:
- 立即:决策表(零改动),但补 table.lookup / table.by_column 库缺口
- 短期:扩展 call_fn(args=、跨模块、字面量静态校验)——不动值模型
- 中期:若要一等函数,走 ADR 并回答匿名函数如何进 EKC 索引
- 不建议:「函数即表」强主张(语义重载 + 削弱静态可索引性)

§9 给出折中:数据在表、逻辑在命名函数,兼顾表驱动直觉与可索引性。
未修改任何代码。
2026-10-22 12:35:40 +08:00
cflmy 3330a0fc66 chore: 还原 go.mod 被构建副产物改动的依赖分类
上一个提交误带入 plugins/web/go.mod 变更:构建 libweb 时用了 -mod=mod,
Go 把 jackc/pgx/v5 与 yuin/goldmark 从 indirect 提升为 direct。
这与本次文档提交无关,属于构建副产物,还原为提交前状态(内容与版本不变,
仅 require 块归类复原)。
2026-10-22 11:59:50 +08:00
cflmy 42a1a46383 docs: 链接式调用 [函数名](参数) 评估 + 开发环境脚本 dev-env.sh
两件事:

1. doc/design/link-style-call-evaluation.md(Proposed · 待决策)
   评估用户提议的 Markdown 链接式调用 [函数名](参数…)。

   结论:语法优雅,但与既有特性「链接索引 [key](map)」形状完全相同,无法可靠消歧。
   实测证据:
   - [a](m) → 链接索引,取成员,返回 1(既有特性,v0.3 明确推广)
   - [greet](alice) → 被当链接索引处理,报 undefined variable alice
   两者区别只在「greet 是函数还是键名」,需要符号表信息,而语法判定发生在
   解析期(跨模块时未知)。若靠「已知函数表」消歧,会把清晰的
   missing map key 变成误导性的 unknown function。

   给出四个受限方案并对比,推荐 L3:用「] 与 ( 之间是否有空格」消歧
   - [key](coll)  紧贴 → 链接索引,语义一字不动(零回归)
   - [callee] (args) 有空格 → 调用,参数显式成组,顺带解决 D8 空格函数名
   并附 8 条验证计划。未改任何代码。

2. scripts/dev-env.sh(新增,可 source 复用)
   本机测试环境缺失导致基线本来就有失败,本次装好并固化:
   - 约束1:$HOME 不可写 → zig/rust 缓存显式重定向
   - 约束2:/tmp 是 noexec tmpfs → TMPDIR 必须指向可写且可执行目录
     (这是 Go 链接报 "signal: aborted"、zig 报 AccessDenied 的真正原因)
   - 提供 rust 1.81 / go 1.25 / python 3.12 / gcc shim(zig, glibc 2.36)

   环境修复前后:
   - 无 python3:231 passed / 2 failed
   - 加 python3:233 / 0(lib)
   - 加 go + libweb:gold 284 / 0
   - 全量:554 passed / 0 failed

   libweb.so 构建要点:Go cgo 需要 gcc,用 zig cc 充当
   (/workspace/qdagent/.tools/zigcc/bin/gcc,过滤 Go 传入的
   -Qunused-arguments,该参数会让 zig 驱动 abort)。

变更文档同步追加 §8 记录环境安装过程与前后对比。
2026-10-22 11:59:14 +08:00
cflmy b6629e5450 fix(parse): D9 未闭合引号不再静默吞行(分类层 + 解析层双层修复)
缺陷:`**s = "abc`(引号未闭合)被静默当成叙述丢弃,退出码 0,
没有输出也没有报错,该行凭空消失。对「文档即程序」来说这是最危险的一类
错误——文档看起来完整、能跑、check 通过,实际少了一节。

根因在**分类层**而不是解析层:
parse_quoted_string 里 `unterminated " string` 的报错一直都在,
但 matching_bold_close 扫描时遇到未闭合的 '"' 后一直处于 in_str 状态,
再也找不到收尾 '**',于是 is_marqdo_star_line 返回 false,
该行被判为 LineKind::Comment 成为叙述,解析器根本看不到它。
解析层精心准备的报错不可达。

修复(两层,缺一不可):
1. src/lex/mod.rs
   - 新增 pub fn has_unterminated_string:统计未被 \ 转义的 '"',奇数即「开了没收」
   - is_marqdo_star_line:粗体起始且找不到收尾时,若引号未闭合则仍判 Code
     (判 Comment 会静默丢行;判 Code 才能让解析器说话)
2. src/parse/mod.rs
   - parse_simple_stmt 紧跟既有粗体分支之后,对「粗体起始 + 引号未闭合」
     给出精确报错,而不是笼统的 unrecognized statement

影响面(改前量化,避免凭直觉改核心解析):
- 全仓库 845 个 .mq.md、620 个含代码行文件
- 引号计数为奇数的代码行:**0**
- 结论:不改变任何现有文件的解析结果,只作用于畸形输入

测试(TDD,先写测试确认失败再修):
- 新增 4 个单测:未闭合→Code、闭合→Code、叙述含引号→Comment、
  叙述含孤立引号→Comment
- 修复前 unterminated_quote_inside_bold_is_code_not_comment 如期失败
- 修复后 lex 14/14;cargo test --lib 237 passed 0 failed(基线 233 + 新增 4)
- cargo test --test gold 276 passed 8 failed;git stash 验证基线同样 8 failed,
  失败全部是 ext_web_*(依赖 Go 插件 libweb,本机环境不具备),与本次无关

文档:
- doc/design/parser-diagnostics-d8-d9.md  设计依据、根因链路、候选方案评判、影响面
- doc/design/change-d9-unterminated-string.md  变更记录(现象/根因/改法/测试/边界)
- doc/design/spaced-function-names-d8.md  D8 方案评估(待审阅,未改代码)

已知边界:单引号 '...' 未闭合仍是旧行为,留作后续评估
(单引号兼作英文撇号,误判风险高于双引号)。
2026-10-22 11:52:27 +08:00
cflmy ecd7d5e433 examples: 新增 oa2026-showcase(2026 开源项目大赛作品介绍示例集)
五个可运行示例,覆盖 Marqdo 的核心能力面:

| 文件 | 展示 |
|------|------|
| add.mq.md | 叙述统一、粗体即代码、斜体即返回 |
| invoice.mq.md | 表格即数据、循环、分支、断言 |
| calculus.mq.md | 公式即变量、求导、求根、绘图 |
| bell.mq.md | 量子电路、概率、断言、SVG 派生物 |
| foreign-node.mq.md | 外联一次性执行、持久会话、显式传值 |

全部实测跑通(1.5.2),输出与 README「预期输出」一节一致:
- add → 42
- invoice → 960 / 912 / 966 / within-cap
- calculus → 3*x^2 - 3 / 9 / [-1.73, 0, 1.73] / plot-ok
- bell → {00: 0.5, 11: 0.5} / bell-00-ok / bell-11-ok / bell-draw-ok
- foreign-node → 区域汇总表 + 持久会话复读

仓库侧改动:
- examples/oa2026-showcase/*.svg 随示例入库(README 有说明,属固定产物)
- .gitignore 忽略根目录 bell-*.svg / calculus-*.svg —— 从仓库根运行示例时
  draw/plot 会把 SVG 写到 cwd,那是运行产物不是源文件
- examples/marqdo-blog/db/posts.mq.md 首行正文去掉了内嵌 `#` 标题写法
2026-10-22 10:41:41 +08:00
cflmy aeb5a2a43d docs(tutorial): 新增《常见陷阱手册》,并补 D8–D10、按实测收敛 D3
把 qdagent 重构期间踩到的坑整理成**使用向**手册 doc/tutorial/15-常见陷阱.md
(417 行,全部条目在 1.5.2 逐条实测,含现象/原因/改法三段式与提交前自查清单)。

手册要点:
- §1 写文档:行首数字必报错(2026 年 / 42 条 / 3 个要点 都中招);
  行首 + 报错;未闭合引号静默吞行(最危险)
- §2 变量作用域:模块级变量在 # main 与各 ## 之间不可见;
  顶层不许裸语句;table.put 不原地修改
- §3 函数:函数名含空格时定义成功但调用必崩
- §4 字符串:引号内 ** / | / # 实为安全,只有引号不配对才出事
- §5 导入:相对路径以当前文件为基准;标准库必须带库名前缀
- §6 易记错的函数签名(txt.contains 的 sub、table.put 的 in/at/value …)
- §7 结构:# main 体不被 ## 截断;1./2./3. 是 if/elif/else 链
- §8 自查清单(marqdo check + run 双跑)

同步修正缺陷实录 research/qdagent-refactor-defects-2026-10.md:
- D3 收敛:实测证明 - / > / | / [ 在叙述区**安全**,只有行首数字与 +
  会被当语句;判据是「该行能否被解析成完整语句」
- 新增 D8 函数名含空格:定义成功、调用必崩,check 却通过(不对称)
- 新增 D9 未闭合引号静默吞行,退出码 0(静默类最危险)
- 新增 D10 table.put 非原地,累积计数静默失效
- 同步复现清单与变更记录

索引:tutorial/README 增第 15 章;doc/README 增手册与缺陷实录两行。
手册内所有代码示例均实测跑通(含参数传递修法、if 链、标准库前缀)。
2026-10-22 09:46:17 +08:00
cflmy f2d651e063 docs(research): qdagent 重构期间发现的运行时缺陷实录(D1–D7)
在 qdagent 实现「智能体输出必须是可运行 .mq.md」的机械门禁
(提取 → 结构检查 → 沙箱试跑)时,暴露 Marqdo 1.5.2 的一批
行为与文档不一致、诊断不可用、静默降级问题,逐条记录并给出建议:

- D1 高 sandbox.profile 仅回显不生效:readonly 与 default 等价,
  RunOptions 硬编码 allow_fs_write=true(安全语义静默失效)
- D2 高 全角冒号 调用:<name> 无法解析,但提示文案推荐全角;
  extract_tool_name 用 split sep=":",与 READ/DECISION 的全半角支持不一致
- D3 中 叙述行行首执行标记(数字/-/>/|/[/**/*)导致中文文档解析失败;
  对 LLM 生成文档是高频陷阱,建议增强诊断与 check 规则
- D4 中 sandbox.run source= 报错丢上下文:文件名显示 <memory>,
  未提示「源文本必须含 # main」
- D5 中 [key](map) 键缺失硬崩:sandbox.run 成功形状无 error 键,
  按防御式写法在成功路径崩溃;建议统一形状
- D6 低 未绑定 GFM 表不可迭代,报错不指向根因
- D7 低 沙箱内 subtask spawn path= 设计性不可用,未在沙箱文档明示

附「确认正常的项」以避免误报,与逐条复现清单。
2026-10-22 09:03:07 +08:00
cflmyandCursor b020b9d218 Ignore PLDI harness scratch and test plot SVG leftovers.
Keep experiment temp trees and regenerated *-plot-*.svg out of the interpreter tree.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-15 13:12:53 +08:00
1965 changed files with 173741 additions and 44617 deletions

No files matched your search

View File
File mode changed.
+6 -161
View File
@@ -1,169 +1,14 @@
---
name: marqdo-dev
description: >-
Develop Marqdo programs and libraries the readable way: GFM tables as data,
code-as-documentation, table.put over json.set chains, lib/ext authoring.
Use when writing or refactoring .mq.md, creating lib/* or ext/*, reviewing
Marqdo style, fixing unreadable json glue, or when the user asks how to
develop Marqdo / 如何开发 marqdo.
description: Write, refactor and verify Marqdo programs, standard libraries and extensions through the executable development handbook. Use native Marqdo file tools and marqdo call; extend capability gaps through plugins or explicit external tools.
---
# Marqdo development (author + library)
Read [the executable development entry](../../../skills/marqdo-dev/index.mq.md), then [the programming guide](../../../doc/library-development.mq.md). The same guide governs programs, libraries and executable SKILLs. For installed skills, resolve these paths against the Marqdo source checkout.
Read this **before** writing or expanding `.mq.md`. Syntax basics stay in [marqdo](../marqdo/SKILL.md); this skill is the **style and library craft** contract.
Use `**statement**` to execute and `*return*` to return; write `[intent](actual code)` inside executable positions, and `access(coll, key)` to read collections. The guide provides real examples. Native file tasks live in [files.mq.md](../../../skills/marqdo-dev/files.mq.md): read, write, patch, search, inventory, audit and apply. Do not generate Python or shell programs for ordinary file operations.
## Non-negotiable: code is documentation
Prepare the native engineering plugin with the development entry before using its analysis or process tasks. The repository development binary is `target/debug/marqdo`; installed older binaries may need a bootstrap Cargo build through `lib/sys.mq.md exec`. All subsequent task execution uses `marqdo call`. Keep decisions and sequencing in readable mq.md; use a new extension or a documented foreign tool only for a real capability gap.
A `.mq.md` file must stay readable as Markdown. If a human cannot skim the data and intent without decoding nested `json.set` / `json.append` chains, the code is wrong.
The guide is authoritative for narrative over 50%, immediate parameter/return tables, inline statements and returns, GFM data, index.mq.md organization, recursive Markdown web components, failure evidence and verification. Read each task's contract and grant its actual effects. External processes retain their OS authority. Do not rewrite intentional test fixtures or restore removed compose_* APIs.
| Prefer | Avoid |
|--------|--------|
| GFM tables for maps, lists, records, wire, commands | Building the same with `json.set` / `json.append` |
| Named library helpers (`web.*`, `browser.*`, `table.*`) | Copy-paste effect-map glue in every handler |
| `table.put` for **one** dynamic key | Long `json.set` pipelines |
| `json.parse` / `json.stringify` / `json.quote` only | Using `json` as a general dict builder |
`lib/json` is for **parse / stringify / quote**. Collection edits use **GFM tables** and **`lib/table`** (`doc/design/stdlib-table.md`).
## How to shape data
### 1. GFM table geometry (memorize)
| Shape | Result |
|-------|--------|
| 1 column | list |
| ≥2 columns, **one** data row | map (headers = keys) |
| ≥2 columns, **many** rows | map of lists (column-oriented) |
| First header `@` / `行` / `row` | **list of maps** (row records) |
Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = text, `` `var` `` = variable, quote paths/`/` ratios.
### 2. Good patterns
**Wire / steps / commands** — `@` record table:
```markdown
`wire` =
| @ | 选择器 | 事件 | 调用 |
|---|--------|------|------|
| 1 | "#bump" | click | bump |
```
**Multi-key return / boot** — map table with variable cells:
```markdown
`boot` =
| wire | set_text |
|------|----------|
| `wire` | `set_text` |
```
**Single dynamic key** — one `table.put` (or a helper), not a json chain:
```markdown
**`set_text` = table.put in=None at="#log" value=msg**
**table.put in=None at="set_text" value=set_text**
```
Better still — call a named helper:
```markdown
**browser.set_text sel="#log" text=msg**
```
### 3. Bad pattern (do not write)
```markdown
**`ret` = json.set map=None key="set_text" value=…**
**`ret` = json.set map=ret key="canvas" value=…**
**`cmds` = json.append list=cmds item=c0**
```
## Writing application `.mq.md`
1. Frontmatter: title + imports (`table`, domain libs). **Do not import `json` unless parsing strings.**
2. `# main`: state binds, then **tables** for wire/config, return boot map via table or helper.
3. `##` handlers: short prose OK; data as tables; return via `browser.*` / `web.*` / one `table.put`.
4. Blank line between comment paragraphs and code.
5. Run `marqdo run path.mq.md` from repo root.
6. **Calls in narrative:** prefer `**结果 = 某函数 名=`x`**` (no `>` on the RHS). Bracket form `礼貌 [问候] "x"` / `**出 = [put] …**` is fine when modifiers help. Use `> …` for standalone step lists. See `examples/code-as-docs/`.
7. **Do not use `##` inside `# main` for document sectioning** — those become nested functions. Use paragraphs / `---` breaks instead.
8. **Index:** prefer `[键](集合)` / `` [`名`](集合) `` over footnote `` m[^k] ``.
Browser client programs: prefer `import browser:lib/browser.mq.md` (no native plugin). Server sites: 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
- [ ] No `json.set` chains in new code — use `table.put` / `table.merge` / GFM
- [ ] `marqdo run` on a tiny demo under `examples/` or inline smoke
### Where helpers live
| Need | Place |
|------|--------|
| Browser effect maps (WASM client) | `lib/browser.mq.md` |
| Site HTML / HTTP | `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 |
## Refactoring existing glue
When editing a file full of `json.set`:
1. Turn static structures into GFM tables.
2. Replace repeated effect shapes with `browser.*` / `web.text_patch` / `web.dom_patch`.
3. Leave at most sparse `table.put` for dynamic keys.
4. Drop `import json:…` if unused.
## Anti-patterns
| Wrong | Right |
|-------|-------|
| `json.set` × N to build boot | GFM map table or `browser`/`web` helper |
| `json.append` to build command list | `@` record table |
| Dummy column to force a 1-key map | `table.put` or helper |
| Importing `ext/web` only for `text_patch` in WASM | `lib/browser` (no native plugin) |
| Unreadable nested maps as “clever” | Flatten into tables humans can read |
## Related
- Syntax: [marqdo/SKILL.md](../marqdo/SKILL.md) · [examples.md](../marqdo/examples.md)
- Tables: `doc/design/stdlib-table.md` · `doc/design/table-cell-expressions.md`
- Browser effects: `doc/roadmap/browser-wasm-e.md` · `doc/roadmap/browser-wasm-f.md`
- Release: [marqdo-release](../marqdo-release/SKILL.md)
## 渐进式契约 + 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 面)。
Use the development entry's audit task to discover and review maintained repository sources. Its failed Result retains every finding; write_report=True saves the same evidence under .marqdo/audit. It does not execute inspected source or treat known placeholder warnings as completed logic.
+6 -201
View File
@@ -1,209 +1,14 @@
---
name: marqdo-release
description: >-
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.
description: Prepare, publish and verify a user-authorized Marqdo full, cli or extension release through its executable mq.md handbook. Use for release versioning, immutable tags, matching CI gates, GitHub/R2 parity and Ubuntu PPA publication.
---
# Marqdo release
Read [the executable release entry](../../../skills/marqdo-release/index.mq.md) and use its task routing. Version and mode come from the user; an already stated choice remains authorized. Inspection of an old release does not authorize republishing it. Never infer a new version, replace a tag, force-push or bypass hooks.
Canonical release playbook for **cflmy/marqdo**. Read this skill **before** tagging or uploading assets. Details: [reference.md](reference.md).
Use `marqdo call` on the actual handbook headings. The repository development binary is `target/debug/marqdo`; prepare its engineering plugin through [the development entry](../../../skills/marqdo-dev/index.mq.md). File reading and authoring use native [file tools](../../../skills/marqdo-dev/files.mq.md). No Python release orchestrator is required. New OS/service capabilities belong at explicit plugin or external-tool boundaries; version decisions, retries and publication order remain readable mq.md.
## Hard rules
The entry preserves full/cli/ext deliverables, separate editor sources, clean-main tagging, bilingual authored notes, exact-commit Release and EK gates, both native platforms, GitHub/R2 identical bytes, VERSION-after-ZIP ordering and Ubuntu source/build/apt evidence. Every applicable obligation must be verified before declaring completion. Default full/cli work includes PPA; gh-pages deployment needs its own instruction.
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:** 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.
Read-only status and verification are separate from publication. Grant effects stated by each task. Inspect Result.ok before value; use --require-ok when an external automation must stop on a failed Result. Credentials stay in their existing private stores. Interactive sudo/GPG/dput or a failed service request remains incomplete: report the concrete failure and the exact handbook recovery call, preserving local evidence.
## Release modes
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** 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 ask example:
> 当前最新 CLI **vA.B.C**,扩展包 **E.F.G**。请指定下一个版本号与模式(`full` / `cli` / `ext`,如 `1.0.3 full`)。
## Phase 0 — Detect versions (mandatory stop)
```bash
python3 .cursor/skills/marqdo-release/scripts/detect_version.py
```
Report briefly, then **ask for SemVer + mode** (unless already given). Normalize `VER` / `TAG`.
## Phase 1 — Preflight
```
Release progress:
- [ ] Phase 0: version + mode confirmed
- [ ] Phase 1: preflight green
- [ ] Phase 2: docs + version bumps committed
- [ ] Phase 3: extension branch (full/cli)
- [ ] Phase 4: main pushed; tag created & pushed
- [ ] 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: clean tree; `main` ff-only; smoke tests; CHANGELOG Unreleased; no secrets.
## Phase 2 — Docs & version bumps (main)
| 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 # when public/ sources changed
```
Commit + push `main` (proxy origin). On push failure → reference § Proxy; if still blocked, **print** for the user:
```bash
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git HEAD:main
# or: python3 scripts/push-via-hk-jump.py
```
## Phase 3 — VS Code / Cursor extension (full/cli only)
Default: bump `vscode-extension` package.json to `VER`, compile, push branch `vscode-extension`, return to `main`.
## Phase 4 — Tag & trigger CI (full/cli)
```bash
git tag -a "vVER" -m "vVER"
git push origin "vVER"
```
Ext-only:
```bash
git tag -a "ext-vVER" -m "ext-vVER"
git push origin "ext-vVER"
```
(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 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 (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`.
Independent extension releases commit reviewed bilingual notes at doc/releases/ext-X.Y.Z.md before tagging. The [pack handbook](../../../skills/marqdo-release/packs.mq.md) and extension-release.yml run native staging, both platform builds, exact-tag release creation and non-clobbering gh asset upload through marqdo call. An existing upload is inspected rather than replaced. Windows execution remains a CI obligation; a local Linux ZIP cannot prove it.
+2 -396
View File
@@ -1,397 +1,3 @@
# Marqdo release — reference
# Release task reference
Companion to [SKILL.md](SKILL.md). Use during a release; keep SKILL short.
## Detect versions (commands)
```bash
# From repo root
python3 .cursor/skills/marqdo-release/scripts/detect_version.py
# or manually:
git fetch --tags origin 2>/dev/null || true
echo "Cargo: $(sed -n 's/^version = \"\(.*\)\"/\1/p' Cargo.toml | head -1)"
echo "wasm: $(sed -n 's/^version = \"\(.*\)\"/\1/p' crates/marqdo-wasm/Cargo.toml | head -1)"
echo "tags: $(git tag -l 'v*' --sort=-v:refname | head -3 | tr '\n' ' ')"
gh release list --limit 3 2>/dev/null || true
```
**SemVer guidance for the ask (do not choose for the user):**
| Kind | When |
|------|------|
| patch `x.y.(z+1)` | Fixes, docs, no public API / MQ surface break |
| minor `x.(y+1).0` | New features (WASM route C, new ext APIs) backward compatible |
| major `(x+1).0.0` | Breaking MQ / CLI / plugin ABI |
## Asset matrix (CI tag `v*`)
Produced by `.github/workflows/release.yml` on **windows-latest** (`windows` job) and **ubuntu-latest** (`linux` job, **required**, `needs: windows`):
| Asset | Role | Job |
|-------|------|-----|
| `marqdo-VER-x86_64-pc-windows-msvc.exe` | CLI (stdlib embedded) | windows |
| `marqdo-VER-x86_64-pc-windows-msvc.zip` | `marqdo.exe` + `lib/` + `ext/` + native DLL | windows |
| `marqdo-VER-stdlib.zip` | `lib/` only | windows |
| `marqdo-VER-ext.zip` | Official `ext/` L1 | windows |
| `marqdo-VER-native-x86_64-pc-windows-msvc.zip` | Prebuilt Windows plugins (`native/*.dll`) | windows |
| `marqdo-VER-native-x86_64-unknown-linux-gnu.zip` | Prebuilt Linux plugins (`native/lib*.so`) — **must ship** | linux |
| `marqdo-VER-x86_64-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + native `.so` — **must ship** | linux |
| `marqdo-VER-source.zip` | `git archive` of tagged commit | windows |
| `marqdo-VER.vsix` | VS Code / Cursor (from branch `vscode-extension`) | windows |
| `marqdo-VER-public.zip` | Static user docs (`marqdo view output public`) | windows |
Not CI-uploaded (document in notes): macOS build from source; WASM via `marqdo wasm build` → `dist/wasm/`.
A release **without** the Linux native zip is incomplete (`marqdo ext add` on Linux cannot download prebuilts).
## Doc sync checklist (Phase 2 detail)
### CHANGELOG.md
1. Ensure `## Unreleased` lists everything shipping.
2. Rename to `## vVER — YYYY-MM-DD` (use release day in Asia/Shanghai unless user says otherwise).
3. Add a short **Highlights** subsection (install snippet + 3–6 bullets).
4. Insert empty:
```markdown
## Unreleased
### Added
### Fixed
### Changed
```
### README.md
Update every user-visible version pin, typically:
- Section title `## 现状(vVER)`
- `### 如何使用最新 Marqdo(vVER)`
- `git checkout vVER`
- Release URL `…/releases/tag/vVER`
Keep install / `ext add` / plugin build instructions accurate for this release.
### `.cursor/skills/marqdo/SKILL.md`
- Sync hard rules / feature bullets that this release changes (e.g. WASM, web).
- Do **not** dump full CHANGELOG into the skill.
- If release-only process changed, point to `.cursor/skills/marqdo-release/`.
### `public/` (author Markdown sources)
User tutorials under `public/` (not generated HTML). Update when:
- New CLI (`marqdo wasm …`, `ext add`, `version`)
- New tutorials (browser hello, web client embed)
- Version badges / “requires vVER” lines
Then regenerate HTML for zip/pages:
```bash
./scripts/build-public.sh
# Windows: powershell -File ./scripts/build-public.ps1
```
HTML under `public/**/*.html` is typically gitignored — zip still ships from CI `marqdo view output public`.
### Workflow stub
Edit `.github/workflows/release.yml` `body:` **Highlights** so the first auto body matches this tag (agent still replaces with full notes via `gh release edit`).
### Roadmaps / ADRs
If this release closes a wave: set status Completed in `doc/roadmap/*`; leave ADRs immutable (link from CHANGELOG).
## Extension checklist (Phase 3 detail)
Branch policy: `doc/design/vscode-extension-commit.md`.
```bash
git fetch origin vscode-extension
git checkout vscode-extension
# edit vscode-extension/package.json version → VER
# npm ci && npm run compile
git add vscode-extension/
git commit -m "$(cat <<'EOF'
vscode-extension: bump to VER for release
EOF
)"
git push origin vscode-extension
git checkout main
```
Local VSIX only (fallback):
```bash
git fetch origin vscode-extension
git checkout origin/vscode-extension -- vscode-extension
(cd vscode-extension && npm ci && npm run compile && npx @vscode/vsce package --no-dependencies -o "../dist/marqdo-VER.vsix")
# cleanup ignored tree if desired
gh release upload "vVER" "dist/marqdo-VER.vsix" --clobber
```
## Defaults (mirror of SKILL)
| Setting | Default |
|---------|---------|
| Sync `vscode-extension` to `VER` | yes |
| Push main + annotated tag immediately | yes |
| Release notes | 中英双语 |
| Skip VSIX / docs-only / deploy pages | no |
Phase 0 asks **only** for the next version unless the user wants overrides.
## Notes template (中英双语 — default)
Save as `/tmp/marqdo-vVER-notes.md` then:
```bash
gh release edit "vVER" --notes-file /tmp/marqdo-vVER-notes.md
```
```markdown
## Marqdo vVER
### 亮点 / Highlights
- **中文** … / **EN** …
- …
### 安装 / Install
```bash
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout vVER
cargo build --release
./target/release/marqdo version
cargo build --release -p marqdo_plugin_web -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg
marqdo ext add web && marqdo ext add agent && marqdo ext add quantum
# 中文 id:网页 / 智能体 / 量子
```
**浏览器 WASM / Browser WASM**
```bash
marqdo wasm build
# → dist/wasm/marqdo_wasm_bg.wasm + marqdo-bridge.js
# examples: examples/browser-hello/
```
### 破坏性变更 / Breaking changes
- 无 / None
- …
### 下载 / Downloads
| Asset | 内容 / Contents |
|-------|-----------------|
| `marqdo-*-windows-msvc.exe` | CLI(内置 stdlib) |
| `marqdo-*-windows-msvc.zip` | exe + `lib/` + `ext/`(含 native) |
| `marqdo-*-unknown-linux-gnu.zip` | Linux CLI + `lib/` + `ext/` + `.so` |
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`(Win + **Linux 必出**) |
| `marqdo-*-stdlib.zip` | 仅 `lib/` |
| `marqdo-*-ext.zip` | 官方 `ext/` |
| `marqdo-*-source.zip` | 源码快照 |
| `marqdo-*.vsix` | VS Code / Cursor 扩展 |
| `marqdo-*-public.zip` | 用户文档站 |
扩展源码分支 / Extension branch: **`vscode-extension`** ([policy](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension-commit.md)).
### 链接 / Links
- [CHANGELOG](https://github.com/cflmy/marqdo/blob/main/CHANGELOG.md)
- [README](https://github.com/cflmy/marqdo/blob/main/README.md)
```
## Proxy & auth (network recovery)
Symptoms seen in this project: broken local Clash on `127.0.0.1:7890`, flaky GitHub TLS, `gh` needing token, Cursor agent sandbox with only `lo`.
### `proxy.cflmy.top` (try this first)
This machine’s `origin` is typically:
```
https://proxy.cflmy.top/github.com/cflmy/marqdo.git
```
Push / fetch / tag through that remote (HTTPS reverse proxy to GitHub):
```bash
git remote -v # confirm origin uses proxy.cflmy.top
git push origin main
git push origin vVER
git push origin vscode-extension
# one-shot if origin still points at github.com:
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git HEAD:main
git push https://proxy.cflmy.top/github.com/cflmy/marqdo.git vVER
```
Short GETs via the proxy often work; **long `git push` may still time out**. If push hangs or drops, skip Clash retries and go to **HK SSH jump** below.
`gh` / 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 --max-time 15 https://github.com | head -5
curl -sS --max-time 15 -o /dev/null -w 'proxy=%{http_code}\n' https://proxy.cflmy.top/ || true
gh auth status
ip -br addr | head -5 # agent may lack enp*; use required_permissions: ["all"]
```
### Fix order
1. **Unset bad proxy** if connection refused:
```bash
unset http_proxy https_proxy HTTP_PROXY HTTPS_PROXY ALL_PROXY all_proxy
# also clear for one git call: git -c http.proxy= -c https.proxy= …
```
2. **Set a working proxy** only if the user provides one (or known working):
```bash
export HTTPS_PROXY=http://HOST:PORT
export HTTP_PROXY=http://HOST:PORT
```
3. **Agent Shell**: retry `git push` / `gh` with `required_permissions: ["all"]` (and `full_network` if needed).
4. **`gh` auth**: if `gh auth status` fails, ask user to `gh auth login` or set `GH_TOKEN` / `GITHUB_TOKEN` for the session — **never commit tokens**. Fallback used in this repo: load password from `git credential fill` (`protocol=https` / `host=github.com`) into `GH_TOKEN` for the session only, then delete the temp env file.
5. **Git remote**: prefer `https://github.com/cflmy/marqdo.git`; SSH needs keys.
6. **HK SSH jump (preferred when GitHub is blocked but HK is reachable)** — see next subsection.
7. **Partial upload**:
```bash
gh release upload "vVER" dist/FILE --clobber
```
8. **Re-run CI** without retagging (if tag already correct):
```bash
gh workflow run Release --ref "vVER" # only if workflow_dispatch exists; else fix + new patch tag
```
Current Release workflow is **tag-push only**. Red CI after tag → fix on `main`, then either new patch tag or **user-approved** delete+recreate tag (dangerous; prefer patch).
### HK SSH jump (Paramiko CONNECT)
**When to use:** local → GitHub fails (timeout / TLS / Clash flaky / reverse-proxy `proxy.cflmy.top` connect drops), but this host can reach an overseas box that has stable GitHub (default `hk.cflmy.de`). Proven path for v0.3.9 push/tag/`gh`.
**Do not** rely on OpenSSH + `sshpass` here — password auth has hung; use **Paramiko** (`python3-paramiko`).
**Never** commit the HK root password or tokens. Ask the user for the password (or a key), put it in env / a `600` temp file, scrub after.
```bash
# one-shot password file (example — use the secret the user gave this session)
printf '%s' "$HK_PASSWORD_FROM_USER" > /tmp/.hk_ssh_pw && chmod 600 /tmp/.hk_ssh_pw
export HK_SSH_HOST=hk.cflmy.de # or 83.229.126.119
export HK_SSH_USER=root
export HK_SSH_PASSWORD_FILE=/tmp/.hk_ssh_pw
# optional: HK_JUMP_PORT=18081
SCRIPT=.cursor/skills/marqdo-release/scripts/push-via-hk-jump.py
# push / tag / extension (git gets CONNECT proxy + github.com askpass)
python3 "$SCRIPT" -- git push origin main
python3 "$SCRIPT" -- git push origin vscode-extension
python3 "$SCRIPT" -- git push origin vVER
# gh (sets GH_TOKEN from git credential fill if unset)
python3 "$SCRIPT" -- gh release edit vVER --notes-file /tmp/notes.md
python3 "$SCRIPT" -- gh run list --workflow=Release --limit 3
# leave proxy up for manual commands
python3 "$SCRIPT" --serve # then: export https_proxy=http://127.0.0.1:18081
rm -f /tmp/.hk_ssh_pw
```
Script behavior: SSH to HK → local `http://127.0.0.1:$HK_JUMP_PORT` HTTP CONNECT via `direct-tcpip` → run `git`/`gh`/`curl` with that proxy. Git auth uses local `git credential` via `http.extraHeader` (Basic) — **not** `GIT_ASKPASS` (askpass has hung under agent/no TTY). Tokens never go to the jump host disk.
Optional path reverse-proxy (`https://proxy.cflmy.top/github.com/…` `insteadOf`) may work for short GETs; treat long `git push` failures as a signal to use the HK jump instead of retrying Clash forever.
## Local Windows fallback
```powershell
powershell -File ./scripts/release-full.ps1 -Tag vVER -Upload
# -SkipVsix / -SkipPublic / -DeployPages as needed
```
Also: `scripts/release-windows.ps1`, `scripts/publish-release.py` if present.
## Commit message style
```text
release: vVER — <highlight>
```
Extension:
```text
vscode-extension: bump to VER for release
```
## Pre-tag test suggestions
Minimum:
```bash
cargo test --test gold structure_hello
./target/release/marqdo version # after cargo build --release
```
Stronger (time permitting):
```bash
cargo test --test gold
cargo test -p marqdo-wasm -- --nocapture # if wasm tests exist
# optional Node: node tests/wasm/smoke.mjs after marqdo wasm build
```
## Ask-user prompt (copy)
```text
版本探测结果:
- Cargo.toml: A.B.C
- crates/marqdo-wasm: …
- 最新 git tag: v…
- 最新 GitHub Release: v…
- CHANGELOG Unreleased: 有 / 无(摘要:…)
请指定下一个版本号(例如 0.3.2)。
默认(无需确认):同步 vscode-extension 同号、立刻 push tag 发版、发布说明中英双语。
若要改默认请一并说明。
```
Use [the executable release entry](../../../skills/marqdo-release/index.mq.md) and [its maintained task reference](../../../skills/marqdo-release/reference.md). File authoring, mode rules, native service/process boundaries and recovery live with the actual mq.md tasks. Do not reconstruct the former Python or terminal playbook from historical copies.
Regular → Executable
+53 -352
View File
@@ -1,361 +1,62 @@
---
name: marqdo
description: >-
Author and edit Marqdo programs (.mq.md): Markdown markers are executable
syntax (functions, calls, statements, returns, control flow). Use when writing
or modifying .mq.md files, teaching Marqdo, generating Marqdo from prose,
importing lib/* or ext/web or ext/quantum or ext/linalg, running marqdo CLI,
building dynamic sites with ext/web, quantum circuits with ext/quantum,
formula-first linear algebra with ext/linalg, or when the user mentions
Marqdo, mq.md, markup-as-syntax, code-as-documentation, web/网页, quantum/量子,
or linalg/线性代数 extension.
description: Author, run and review readable Marqdo programs, libraries and executable knowledge. Use for .mq.md, marqdo call, Document/Endpoint/Resource web projects and quantum tools; read the executable programming and development handbooks.
---
# Marqdo development
# Marqdo
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.
<!-- CORE_SYNTAX_V2.1: keep this card within the first 1200 body characters -->
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).
## CORE SYNTAX
**Authoring / library craft** (GFM-first, no json glue, how to develop Marqdo): use **[marqdo-dev](../marqdo-dev/SKILL.md)** whenever writing or refactoring `.mq.md`, `lib/*`, or `ext/*`.
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets, **ext → R2+GitHub**, **CLI → Ubuntu PPA**): use [marqdo-release](../marqdo-release/SKILL.md) — detect versions, **ask for SemVer + mode (`full` / `cli` / `ext`)**, then follow that playbook. Ext-only releases are allowed. If sudo/GPG/PPA steps need the user, print the exact commands.
## Hard rules (do not violate)
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
2. **`**…**` = code** (assign / call). **`*…*` = return value**. Output is **not** either marker — use `> print text=…` / `**print text="…"**` / `> 打印 内容=…`.
3. **Prose:** unmarked narrative may contain `` `名` `` (declare/ref), inline `**code**`, and `*return*`. Soft Markdown emphasis that is **not** code-shaped (`**说明**`, mid-line `*only*`) is ignored — see [code-as-docs-gaps.md](../../doc/design/code-as-docs-gaps.md). Dead `` `名` `` (never read) is OK and does not become a param.
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**. Params: prefer prose `` `名` `` / `` `名`=默认 `` (inferred); `` + `名` `` still accepted.
5. **Identifiers:** `` `名` `` in prose; inside `*…*` / `**…**`, bare ids are **variables**. **Text literals must be quoted** in bold/italic: `**print text="hi"**`. Standalone `>` calls: bare words = text; vars need ticks: `` > str `n` ``.
6. **Structure lines** (`#` `>` `+` `-` `|` `1.`) need not be wrapped in bold.
7. **Paths:** In bare expressions `/` is division. In call args / defaults / table cells, unspaced `a/b` and quoted paths are text.
8. Prefer ending side-effect-only bodies with `*None*` / `*无*` / whole-line `**` / `****` when the next lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped everywhere), not function end.
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 必读)
**不必背 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)
Occlusion is the current default. `**…**` executes a statement; `*…*` returns.
Use `[intent](actual code)` in an executable position: the label is prose and
only its payload executes. Empty parentheses are a pending None stub.
Read collections with `access(coll, key)`. Classic indexing is only for explicit
legacy sources and migration. Reading narrative references never runs effects.
| Marker | Meaning |
|--------|---------|
| `#` | **Object / type** (constructor body). `# main` = entry object. `# Child = > Parent` = inherit (**no** implicit parent constructor; call `` `self` = > Parent … `` explicitly when needed). |
| `##` … `######` | **Function / method** (nesting by heading depth). |
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
| `1.` `2.` … in body | Branch arm (condition or `N. *` else). **Same-indent restart at `1.` = new branch statement** (not more arms of the previous list). |
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
| Line `N. *` | Else arm |
| `> fn args` | Call (named `k=v` or positional) |
| `修饰 [fn] args` | Bracket-marked call; leading words → `名=True` |
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
| `**…**` | **Code** (assign / call) — closing `**` touches last token; bare ids are variables; quote text literals |
| `*…*` | **Return value** — closing `*` touches last token; bare ids are variables |
| `****` / whole-line `**` / `*None*` | Return `None` and end function body |
| 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 |
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
## Minimal program
```markdown
# main
> print text=Hello World!
```
Chinese builtins (same functions, no import):
```markdown
# main
> 打印 内容=你好
```
## Functions, calls, end-body
```markdown
# main
> greet who=Marqdo
## greet
+ `who`
> print text=Hello, `who`!
*None*
```
- Call: `> name key=value` or `> name value`.
- Nested helpers use deeper `#` (`##`, `###`, …).
- 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**
## add_one
+ `n`
*n + 1*
```
```markdown
**n = 0**
1. `n` > 0
> print text=positive
2. `n` < 0
> print text=negative
3. *
> print text=zero
```
## Frontmatter imports + stdlib
Imports use `import bind:target` (`导入` equivalent): file (`.mq.md`) or short name (`lib.member`). Members are **not** flattened into the caller. Call with a bare dotted path:
```markdown
---
title: example
import text:lib/text.mq.md
import clock:lib/time.mq.md
---
# main
**xs = > text.str_split s="a,b,c" sep=","**
> print text=`xs`
**t = > clock.now_unix**
```
- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages).
- Instance methods stay `` > `obj`.method `` (backticks on the receiver only).
- `lib/…` resolves via `MARQDO_LIB`, cwd `lib/`, or `lib/` next to the `marqdo` binary.
- Design: [module-namespace.md](../../doc/design/module-namespace.md).
- Official optional extensions (`ext/`, not stdlib): install with `marqdo ext add llm|agent|web|quantum|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`/`非`.
Stdlib map: [reference.md](reference.md).
## Official extension: `ext/agent` (document-driven)
Install: `marqdo ext add agent` (ZH: `智能体`). Native: `cargo build --release -p marqdo_plugin_agent`.
**Constitution (do not dilute):**
1. **Code is documentation** — the runbook `.mq.md` is the model’s ground truth, not a hidden system prompt bag.
2. **Call site is first-class** — `build_step_context` injects path/function/line so the model knows where it is in the program.
3. **Document is the knowledge base (OKF)** — writeback → promote/solidify → reuse / `llm_free`; MCP/corpus are evidence only. **Engineering Knowledge(EKC)**:`marqdo knowledge|find|reuse|…` + `agent.preflight`(REUSE→ADAPT→CREATE)——见 [engineering-knowledge.md](../../doc/design/engineering-knowledge.md)。
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` / `# 智能体` → `## 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) · 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` (Document / Endpoint / Resource)
Install: `marqdo ext add web` (ZH id: `网页`). Build native plugin: `scripts/build-web-plugin.sh` / `marqdo ext add web`.
**Constitution (ADR 0007 — do not degrade):**
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`
```markdown
---
type: web
route: /
title: Hello
import web:ext/web/web.mq.md
---
# Hello
Executable document as a page.
```
```markdown
---
type: endpoint
method: POST
path: /api/ping
response: json
---
*{"ok": true}*
```
Site entry may `# main` → `web.serve root="."`. Client WASM: `ext/web/client.mq.md` / `lib/browser` — no author JS.
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) · API index: [reference.md](reference.md).
## Official extension: `ext/quantum` (circuits + Q7/Q8)
Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --release -p marqdo_plugin_quantum`, then **`marqdo ext add quantum` again** so view loads the new `libquantum.so` (stale plugin = old black/white circuits).
- EN: `import quantum:ext/quantum/quantum.mq.md`
- ZH: `导入 量子:ext/quantum/量子.mq.md`
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; ≤12 qubits for statevector; density-matrix ops ≤6 qubits; one language file per program; quote draw string args (`kind="…"`, `theme="…"`).
**Core:** `# circuit` / `# gate` / `# density` — table `steps=` or method chain; `simulate` / `probabilities` / `run` / `draw`.
**Q7 linear algebra:** `density`, `partial_trace`, `eig`, `expect` (Pauli string, left=high bit), `purity`, `kron`, `schmidt`, `fidelity`.
**Draw kinds:** `circuit|probs|bloch|hinton|city|density|paulivec|qsphere|multibloch`.
**Q8 themes (circuit / probs / bloch):** `theme="dark"|"light"|"bw"` (ZH `主题=`; **default `dark`** — slate lab look, gate-family colors, label chips so wires never cross `q0` text). View plot chrome follows `data-theme` on the SVG. Advanced kinds (hinton/…) still Q8c pending full re-skin.
```markdown
*_ = > `qc`.draw kind="circuit" theme="dark"*
*_ = > `qc`.draw kind="probs" theme="light"*
```
Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7.md](../../doc/design/ext-quantum-q7.md) · Q8 viz: [ext-quantum-viz-style.md](../../doc/design/ext-quantum-viz-style.md) · examples: [quantum-bell](../../examples/quantum-bell/) · [quantum-entanglement](../../examples/quantum-entanglement/).
## Official extension: `ext/linalg` (formula-first LA)
Install: `marqdo ext add linalg` (ZH id: `线性代数`). Build: `cargo build --release -p marqdo_plugin_linalg`, then **`marqdo ext add linalg` again** so view loads the new native lib.
- EN: `import la:ext/linalg/linalg.mq.md`
- ZH: `导入 la:ext/linalg/线性代数.mq.md`
**Hard rules:** `ext/**` never calls `host_*`; hot path is ABI plugin; prefer top-level `la.symbol` (not `matrix.symbol` without a receiver); quote `kind=` strings; dense `explicit` / factorize obey size guards.
APIs (EN): `symbol` → `# matrix`;中缀 `+`/`-`/`*`;方法 `` `A`.T `` / ``.simplify`` / ``.ascii`` · `from_formula` / `explicit` / `factorize` / `draw` · `lstsq` / `norm` / `cond` / `rank`.
Examples: [linalg-svd](../../examples/linalg-svd/) · [linalg-least-squares](../../examples/linalg-least-squares/). Design: [ext-linalg.md](../../doc/design/ext-linalg.md) · formula-doc: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
## AI authoring workflow
1. **查再写**:不确定语法就 `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)
| Wrong | Right |
|-------|-------|
| `**Hello**` to print | `> print text=Hello` |
| `# main` then prose then code with no blank line | Blank line before code |
| `if x > 0:` | `1. `x` > 0` |
| `* > print text=hi *` | `> print text=hi` |
| `` *`a` = 1 * `` (trailing space + backticks) | `*a = 1*` — bare bind, no trailing space before `*` / `**` |
| `*xs = > text.split value=a,b sep=,*` (bare text args) | `*xs = > text.split value="a,b" sep=","*` — quote text literals; bare words are variables |
| Forgetting 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` / `compose_*` page parts | `type: web` Document + View table / `web.render` / `web.serve` |
| Import `json` for every browser handler | `import browser:lib/browser.mq.md` + tables ([marqdo-dev](../marqdo-dev/SKILL.md)) |
| Mix `web.page` and `网页.页面` in one file | One import language per `.mq.md` |
| Call `host_web_*` from `ext/web` | Use `# app` / `# db` methods; plugin ABI only |
| Call `host_*` from `ext/quantum` | Use `# circuit` / `# density` methods; plugin ABI only |
| Call `host_*` from `ext/linalg` | Use `la.*` L1 wrappers; plugin ABI only |
| Bare `kind=eig` inside `*…*` | `kind="eig"` — quote text literals |
| Bare `theme=dark` inside `*…*` | `theme="dark"` — quote; ZH `主题="dark"` |
| Rebuild plugin but skip `ext add` | `cargo build -p marqdo_plugin_quantum` then `marqdo ext add quantum` (or set `MARQDO_QUANTUM_PLUGIN`) |
## Checklist before finishing
- [ ] File ends with `.mq.md`
- [ ] Print via `print` / `打印`, not bold
- [ ] Blank lines separate comment paragraphs from code
- [ ] `# main` exists when the file is an entry program
- [ ] Nested 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
|---|---|
| `**…**` | Statement (assign / call / expression) |
| `*…*` | Return |
| `[intent](payload)` | Readable intent with executable payload |
| `access(c, k)` | Collection read |
| `- [intent](for items as item)` | Explicit traversal |
| `1.` / `2.` | Branches; numbered * is else |
| GFM table | Data: one column list, one row record, @ row records |
Read [the executable programming guide](../../../doc/library-development.mq.md)
before authoring. Its actual callable examples demonstrate inline computation,
structured results, defaults and recoverable native file reads. Use
[the development entry](../../../skills/marqdo-dev/index.mq.md) and its file tools for source
work, and [the release entry](../../../skills/marqdo-release/index.mq.md) for an authorized
release. These mq.md files are the working instructions and tools; do not rebuild
a parallel command playbook in SKILL.md.
Call the actual file and heading with `marqdo call`. In a source checkout use
the built `target/debug/marqdo`; prepare its engineering plugin through the
development entry. Large structured inputs use --args-json FILE or stdin;
JSON strings stay literal during call-session replay. --require-ok makes failed
Results stop external automation while preserving their returned evidence.
Read each function's parameter/return tables and effect contract before calling.
Author programs as readable explanations: useful narrative exceeds half of
each callable unit; parameter and return tables immediately follow its heading;
inline assignments, actions and returns explain their purpose. Standard libraries
remain single-file handbooks. Multi-file projects and extensions use index.mq.md.
GFM describes data, public helpers describe operations, and components recursively
split web layouts until their content leaves are ordinary Markdown.
Native Marqdo capabilities handle file reading/writing, tables, parsing, hashing
and network reads. Add an extension for a reusable capability gap or call an
explicit existing external tool with argument arrays. Keep decisions, retries
and the execution flow in mq.md. Do not generate Python or shell programs for
already available native operations. OS processes and plugins retain their OS
authority; an fs-root does not sandbox their own access.
Use the current [web entry](../../../ext/web/index.mq.md) for Document, Endpoint and
Resource artifacts, or [quantum entry](../../../ext/quantum/index.mq.md) for circuit
workflows. Do not restore removed compose_* or app.configure APIs. Preserve
intentional fixtures and [classic migration context](migration-classic.md).
Validate the real calls and error paths; a narrative ratio or uploaded asset
alone is never functional evidence.
+2 -418
View File
@@ -1,419 +1,3 @@
# Marqdo examples (AI)
# Marqdo executable examples
v0.3: `**…**` = code (assign / call); `*…*` = return. Prefer `[key](coll)` over footnote get. Bracket calls: `礼貌 [问候] x`.
## 1. Hello (English)
```markdown
# main
> print text=Hello World!
```
## 2. Hello (Chinese builtins)
```markdown
# main
> 打印 内容=你好,世界!
```
## 3. Function + named call + empty return
```markdown
# main
Greeting via a nested function:
> greet who=Marqdo
## greet
+ `who`
> 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`**
**打印 内容=`b`**
## add_one
+ `n`
*n + 1*
```
## 5. Branch with else
```markdown
# main
**n = 0**
1. `n` > 0
> print text=positive
2. `n` < 0
> print text=negative
3. *
> print text=zero
```
## 6. Foreach loop
```markdown
# main
`篮子` =
| 果 |
|----|
| 苹果 |
- [果](篮子)
> print text=`果`
```
## 6b. Map table + link-index get
```markdown
# main
`分类` =
| 苹果 | 黄瓜 |
|------|------|
| 水果 | 蔬菜 |
**种 = [苹果](分类)**
**打印 内容=`种`**
`篮子` =
| 果 |
|----|
| 苹果 |
**第一 = [1](篮子)**
**打印 内容=`第一`**
```
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):
```markdown
`订单` =
| 行 | 品名 | 数量 |
|----|------|------|
| 1 | 苹果 | 2 |
**名 = [品名]([1](订单))**
```
## 6c. Bracket-marked call + modifiers
```markdown
# main
**打印 内容=(礼貌 [问候] "Marqdo")**
## 问候
+ `谁`
+ `礼貌`=False
**出 = `礼貌` + ", " + `谁` + "!"**
*出*
```
`礼貌 [问候] …` → `礼貌=True`. `]` immediately followed by `(` is index, not a call.
## 6d. Browser effects — tables + lib/browser (not json.set)
```markdown
---
import browser:lib/browser.mq.md
---
# main
`wire` =
| @ | 选择器 | 事件 | 调用 |
|---|--------|------|------|
| 1 | "#bump" | click | bump |
**`wire`**
## bump
**count = count + 1**
**label = str count**
**> browser.set_text sel="#count" text=label**
```
Do **not** build effect maps with `json.set` chains. See [marqdo-dev](../marqdo-dev/SKILL.md).
## 7. Import text stdlib
```markdown
---
title: split demo
import text:lib/text.mq.md
---
# main
**parts = [text.str_split] s="a,b,c" sep=","**
**打印 内容=`parts`**
```
## 7b. Mid M1 — regex + encoding (no plugin)
```markdown
---
import re:lib/re.mq.md
import enc:lib/encoding.mq.md
---
# main
**`ok` = [re.is_match] text="a@b.c" pattern="@"**
**`b64` = [enc.base64_encode] text="hi"**
**打印 内容=`ok`**
**打印 内容=`b64`**
```
## 7c. Mid M6 — log + uuid
```markdown
---
import log:lib/log.mq.md
import uuid:lib/uuid.mq.md
---
# main
> log.info text="start"
> log.set_level level="debug"
> log.debug text="detail"
**id = [uuid.v4]**
**打印 内容=`id`**
```
## 8. Comment paragraphs (blank-line rule)
```markdown
# main
This whole paragraph is a comment, including lines that look like code:
**not_executed = 1**
> print text=also still comment
After a blank line, code runs:
> print text=this runs
```
## 9. Frontmatter import only
```markdown
---
description: loads math
import math:lib/math.mq.md
---
# main
**t = > num value=3.5**
**打印 内容=`t`**
```
## 10. Object handle + method
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
```markdown
# Greeter
## hello
+ `who`
**msg = "Hello, `who`!"**
*msg*
# Loud = > Greeter
## hello
+ `who`
**msg = "HELLO, `who`!"**
*msg*
```
`_type` stays the most specific name (`Loud`). Methods walk the base chain; same-name `##` on the child overrides. **No implicit super** — if the child needs parent fields, call the parent explicitly:
```markdown
# Child = > Parent
+ `name`
**self = > Parent name=`name`**
**self = [table.put] in=`self` at="extra" value=1**
*self*
```
## 11. Agent layout (ABI)
```markdown
---
import agent:ext/agent.mq.md
---
# main
> load_native
**ws = > agent**
**n = > `ws`.ensure_layout**
**打印 内容=`n`**
```
Requires `MARQDO_AGENT_PLUGIN` pointing at the built `agent` shared library (see `doc/design/ext-agent.md`).
## 12. What not to emit
```markdown
# BAD — 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 as if it were a statement
*> print text=hi*
# BAD — old branch syntax (removed)
+ `x` > 0
# GOOD — ordered list arms
1. `x` > 0
> print text=pos
2. *
> print text=other
# GOOD — another independent branch (restart at 1.)
1. `y` > 0
> print text=y-pos
2. *
> print text=y-other
# GOOD — print / return
**打印 内容="hi"**
*n + 1*
```
## 13. Dynamic site (ext/web, minimal)
```markdown
---
title: hello-site
import web:ext/web/web.mq.md
import db:db/index.mq.md
---
# main
`shell` =
| 组件 | 样式 |
|------|------|
| nav | |
`main` =
| 属性 | 值 | 样式 |
|------|-----|------|
| title | posts.title | |
| body | posts.summary | |
**store = > db.open**
**css = "body{font-family:sans-serif}"**
**page = > web.page title="Hello"**
**page = > page.compose_components components=`shell`**
**page = > page.compose_main main=`main`**
**page = > page.css css=`css`**
**app = > web.app page=`page` port=8080**
**app = > app.static prefix="/static" dir="static"**
> listen app=`app`
```
- Import `ext/web/web.mq.md` **or** `ext/web/网页.mq.md` — not both; match API language to the file.
- Full blog/CMS patterns: `examples/marqdo-blog/` (routes, SEO, RSS, auth, upload, WS).
- Run after `marqdo ext add web` and building `marqdo_plugin_web`.
## 14. Quantum entanglement lab (ext/quantum Q7/Q8)
```markdown
---
import quantum:ext/quantum/quantum.mq.md
---
# main
`steps` =
| step | gate | qubits |
|------|------|--------|
| 1 | H | 0 |
| 2 | CX | 0,1 |
**qc = > quantum.circuit qubits=2 steps=`steps`**
**rho = > `qc`.density**
**red = > `rho`.partial_trace keep=0**
**sch = > `qc`.schmidt cut=1**
**_ = > `qc`.draw kind="circuit" theme="dark"**
**_ = > `qc`.draw kind="hinton"**
**打印 内容=`red`**
```
- Full lab: `examples/quantum-entanglement/`. Bell-only: `examples/quantum-bell/`.
- `theme="dark"|"light"|"bw"` (default dark) on `circuit` / `probs` / `bloch`. Quote `kind=` / `theme=`.
- After rebuilding the plugin: `marqdo ext add quantum` so view loads the new native lib.
## 15. Linear algebra (ext/linalg)
```markdown
---
import la:ext/linalg/linalg.mq.md
---
# main
**`A` = > la.symbol name="A" rows=2 cols=2**
**`B` = > la.symbol name="B" rows=2 cols=2**
**`C` = `A` + `B`**
**`P` = `A` * `B`**
```
Prefer:
```markdown
**`env` = > la.declare table=`shapes`**
**`P` = [A](env) * [B](env)**
**`t` = > `P`.T_ascii**
```
- Infix `+` / `-` / `*`;`ascii` / `T_ascii` 默认化简(`raw=True` 可关)。
- Formula-doc design: [ext-linalg-formula-doc.md](../../doc/design/ext-linalg-formula-doc.md).
- Examples: `examples/linalg-transpose/`, `examples/linalg-svd/`, `examples/linalg-least-squares/`.
Read [the maintained discovery note](../../../skills/marqdo/examples.md) and its actual mq.md source entries. The [programming guide](../../../doc/library-development.mq.md) is authoritative; source examples and real workflow tests stay together rather than being copied into SKILL reference fences.
+3
View File
@@ -0,0 +1,3 @@
# Classic migration
Read [the maintained migration context](../../../skills/marqdo/migration-classic.md) and [the executable programming guide](../../../doc/library-development.mq.md). Historical fixtures retain explicit classic markup; new code uses readable occlusion and access(collection, key).
+2 -203
View File
@@ -1,204 +1,3 @@
# Marqdo reference (AI)
# Marqdo executable reference
Load this when you need stdlib names, CLI, or edge cases. Core rules stay in [SKILL.md](SKILL.md).
## CLI
```text
marqdo --version
marqdo run FILE.mq.md
marqdo run FILE.mq.md --backend bytecode
marqdo view PATH # docs browser, default port 7429
marqdo debug PATH # debugger UI, default port 7430
marqdo catalog PATH -o .marqdo
marqdo ext list
marqdo ext add llm|agent|web|quantum|linalg
marqdo ext remove llm|agent|web|quantum|linalg
```
Diagnostics look like `path:line:col: message` (1-based line/col).
**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.
官方扩展(`ext/…`,非 stdlib):`marqdo ext add` 装到 `MARQDO_EXT` 或 `~/.marqdo/ext`;导入仍写 `import llm:ext/llm.mq.md`。解析还含 cwd `ext/`、二进制旁 `ext/`。对象:`doc/design/objects.md`。Agent:`doc/design/ext-agent.md` · 安装器:`doc/design/ext-cli.md`。
## Builtins (no import)
| EN | ZH | Role |
|----|----|------|
| `print` | `打印` | stdout; arg `text` / `内容` |
| `input` | `输入` | one line; arg `prompt` / `提示` |
| `len` | `长度` | length; arg `value` / `值` |
| `str` | `文本` | to text; arg `value` / `值` |
| `int` | `整数` | to int; arg `value` / `值` |
Keywords (not variable names): `True`/`真`, `False`/`假`, `None`/`空`, `and`/`且`, `or`/`或`, `not`/`非`.
## Standard library files
Import one file; use **that** file’s function names.
| EN import | ZH import | Typical APIs (EN / ZH) |
|-----------|-----------|-------------------------|
| `lib/text.mq.md` | `lib/文本.mq.md` | text helpers / 去空白·拆分·拼接… |
| `lib/table.mq.md` | `lib/表.mq.md` | `put`/`改` + list/map(见 `doc/design/stdlib-table.md`) |
| `lib/re.mq.md` | `lib/正则.mq.md` | Mid:`is_match`/`find`/`replace`/… |
| `lib/encoding.mq.md` | `lib/编码.mq.md` | Mid:base64/hex |
| `lib/path.mq.md` | `lib/路径.mq.md` | Mid:join/normalize/… |
| `lib/hash.mq.md` | `lib/哈希.mq.md` | Mid:sha256/hmac/… |
| `lib/secrets.mq.md` | `lib/机密.mq.md` | Mid:token_hex/urlsafe |
| `lib/csv.mq.md` | `lib/逗号表.mq.md` | Mid:parse/stringify |
| `lib/cli.mq.md` | `lib/命令行.mq.md` | Mid:`parse` flags |
| `lib/log.mq.md` | `lib/日志.mq.md` | Mid:level-filtered one-line logs |
| `lib/uuid.mq.md` | `lib/标识.mq.md` | Mid:UUID v4 |
| `lib/browser.mq.md` | `lib/浏览器.mq.md` | WASM client effect helpers(GFM + `set_text`/`canvas`/…;见 marqdo-dev) |
| `lib/fs.mq.md` | `lib/文件.mq.md` | filesystem |
| `lib/sys.mq.md` | `lib/系统.mq.md` | process / cwd / load_dotenv |
| `lib/plugin.mq.md` | `lib/插件.mq.md` | load native ABI plugins (`doc/design/ext-abi.md`) |
| `lib/time.mq.md` | `lib/时间.mq.md` | time/format |
| `lib/net.mq.md` | `lib/网络.mq.md` | HTTP(S) helpers (+ optional headers) |
| `lib/json.mq.md` | (see design) | **parse / stringify / quote only** — not a dict builder |
| `lib/math.mq.md` | `lib/数学.mq.md` | num, trig, random, formula, plot |
| `lib/foreign.mq.md` | `lib/外联.mq.md` | run foreign fenced blocks |
| `ext/llm.mq.md` | `ext/大模型.mq.md` | `# llm` / `# 大模型` object + chat methods |
| `ext/agent.mq.md` | `ext/智能体.mq.md` | document-driven **step** / **plan** + OKF;示例 `examples/agent-pong` · `agent-okf-flywheel`;Wave B:[agent-framework-2026-09.md](../../doc/research/agent-framework-2026-09.md) |
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | dynamic sites — see **ext/web** section below |
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | circuits + Q7 density/viz + Q8 themes — see **ext/quantum** below |
| `ext/linalg/linalg.mq.md` | `ext/linalg/线性代数.mq.md` | formula MatExpr + factorize/draw — see **ext/linalg** below |
Open the imported `.mq.md` under `lib/` or `ext/` to see exact `##` / `#` names and parameters. Gold tests: `tests/lib/`, `tests/structure/`, `tests/ext/`.
## ext/web (dynamic sites)
Install: `marqdo ext add web` (`网页`). Native: `cargo build --release -p marqdo_plugin_web`.
| EN import | ZH import | Core types |
|-----------|-----------|------------|
| `ext/web/web.mq.md` | `ext/web/网页.mq.md` | `# page` `# style` `# db` `# form` `# app` `# auth` `# cache` `# storage` |
| Area | EN methods (representative) | Notes |
|------|----------------------------|-------|
| Page | `compose_components`, `compose_main`, `render`, `meta`, `paginate` | GFM tables; cells are literal path strings |
| DB | `init`, `insert`, `select`, `paginate`, `get`, `update`, `delete`, `migrate`, `fts`, `search`, `count`, `事务`/`txn` | init supports `unique`/`index`/`fk`; auto `created_at`/`updated_at` |
| App | `route`, `static`, `configure`, `listen`, `auth`, `gate`, `upload`, `download`, `gallery`, `route_rss`, `redirect`, `error_page`, `sitemap`, `robots` | W0–W7 + P3 complete |
| Auth | `login`, `check`, `logout`, `hash_password` | argon2 + CSRF + SQLite sessions; `role` for RBAC |
Drivers (Postgres / Redis / S3): `db url=postgres://…`, `cache url=memory:`, `storage url=file:…` — see `doc/design/ext-web-drivers.md`.
Example project: `examples/marqdo-blog/`. Capability matrix: `doc/design/web-net-capabilities.md`.
## ext/quantum (circuits + Q7/Q8)
Install: `marqdo ext add quantum` (`量子`). Native: `cargo build --release -p marqdo_plugin_quantum`, then re-run `ext add` so view picks up the new `.so`.
| EN import | ZH import | Core types |
|-----------|-----------|------------|
| `ext/quantum/quantum.mq.md` | `ext/quantum/量子.mq.md` | `# circuit` `# gate` `# density` |
| Area | EN APIs | Notes |
|------|---------|-------|
| Circuit | `h`/`cx`/…, `simulate`, `probabilities`, `run`, `draw`, `noise` | `steps=` GFM table; ≤12 qubits |
| Gate | `matrix`, `matches_matrix`, `draw` | named or `matrix=` custom unitary |
| Density (Q7) | `purity`, `partial_trace`, `eig`, `expect`, `draw` | ≤6 qubits for dense ρ |
| Free (Q7) | `kron`, `schmidt`, `fidelity` | top-level on import bind |
| Draw kinds | `circuit\|probs\|bloch\|hinton\|city\|density\|paulivec\|qsphere\|multibloch` | quote `kind="…"` |
| Themes (Q8) | `theme="dark"\|"light"\|"bw"` (ZH `主题=`) | default **dark**; circuit/probs/bloch themed; SVG `data-theme` |
Examples: `examples/quantum-bell/`, `examples/quantum-entanglement/`. Design: `doc/design/ext-quantum.md` · Q7: `doc/design/ext-quantum-q7.md` · Q8: `doc/design/ext-quantum-viz-style.md`.
## ext/linalg (formula-first linear algebra)
Install: `marqdo ext add linalg` (`线性代数`). Native: `cargo build --release -p marqdo_plugin_linalg`, then re-run `ext add`.
| EN import | ZH import | Notes |
|-----------|-----------|-------|
| `ext/linalg/linalg.mq.md` | `ext/linalg/线性代数.mq.md` | Top-level `symbol`/`mul`/`factorize`/`draw` |
Examples: `examples/linalg-svd/`, `examples/linalg-least-squares/`. Design: `doc/design/ext-linalg.md` · formula-doc: `doc/design/ext-linalg-formula-doc.md` · roadmap: `doc/roadmap/ext-linalg.md`.
## Formula + plot (math)
```markdown
---
import math:lib/math.mq.md
---
# main
`f` =
$$
x^2 - 2
$$
*_svg = > plot formula=`f` var=x min=-3 max=3*
```
Empty RHS assignment + following `$$…$$` binds a formula value. Narrative-only `$$` without binding is display, not assignment.
## Foreign (Python example)
```markdown
---
import foreign:lib/foreign.mq.md
---
# main
`hi` =
```python
print("hello-from-python")
```
```
Lines starting with `` ` `` can be code (binding). Keep a blank line before/after fences per comment rules.
## Function-end details
| Form | Effect |
|------|--------|
| Lone `---` or `***` (≥3 same chars) at function body top level | End function; no return value |
| `****` or empty bold | Return `None` and end body |
| `**expr**` | Return `expr`; does **not** by itself cut off later sibling statements — still use HR or shallower heading |
File-leading paired `---` is frontmatter only; body `---` is not frontmatter.
## Call arguments
- Named: `> greet who=World`
- Positional: `> greet World`
- Spaces in values: allowed in named forms as in docs (`who=marqdo user`)
- Inline call in statement: `` *`n` = > len value=`s`* ``
See `doc/design/call-arguments.md`.
## Identifiers
- Variables: `` `name` ``
- Comparisons: `==` `>` `<` `>=` `<=`
- Do not use keyword tokens as names
## Design docs (repo)
| Doc | Topic |
|-----|--------|
| `doc/design/markdown-mapping-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 |
| `doc/design/stdlib-i18n.md` | EN/ZH lib files |
| `doc/design/stdlib-modules.md` | L1 modules including plugin |
| `doc/design/ext-abi.md` | Native C ABI v1 |
| `doc/design/ext-llm.md` | `ext/llm` |
| `doc/design/ext-agent.md` | `ext/agent` agent **framework** (layout shipped; LLM orchestration roadmap) |
| `doc/design/ext-cli.md` | `marqdo ext list/add/remove` |
| `doc/design/ext-web.md` | `ext/web` dynamic sites (author API) |
| `doc/design/web-net-capabilities.md` | ext/web capability matrix (W0–W7 + P3) |
| `doc/design/ext-quantum.md` | `ext/quantum` circuits |
| `doc/design/ext-quantum-q7.md` | Q7 density linear algebra + advanced SVG |
| `doc/design/ext-quantum-viz-style.md` | Q8 themed SVG (`dark`/`light`/`bw`; circuit/probs/bloch) |
| `doc/design/ext-linalg.md` | `ext/linalg` formula MatExpr + factorize/draw |
| `doc/design/ext-linalg-formula-doc.md` | 公式文档面:跑通即正确 · 代数/计算两面 |
| `doc/design/view-debug.md` | view / debug hosts |
Read [the maintained discovery note](../../../skills/marqdo/reference.md) and its actual mq.md source entries. The [programming guide](../../../doc/library-development.mq.md) is authoritative; source examples and real workflow tests stay together rather than being copied into SKILL reference fences.
Regular → Executable
View File
File mode changed.
Regular → Executable
View File
File mode changed.
Executable
+3
View File
@@ -0,0 +1,3 @@
# Multipart protocol examples retain required CRLF bytes in every checkout.
examples/web-net-site/components/content/multipart.txt -text whitespace=cr-at-eol
examples/web-net-site-zh/components/content/multipart.txt -text whitespace=cr-at-eol
Regular → Executable
View File
File mode changed.
@@ -0,0 +1,46 @@
name: Build cinematic Markdown-to-execution video
on:
push:
branches: [docs/markdown-execution-cinematic-v2]
paths:
- "scripts/render-markdown-execution-promo.py"
- ".github/workflows/build-markdown-execution-video.yml"
workflow_dispatch:
permissions:
contents: write
jobs:
video:
if: github.ref_name == 'docs/markdown-execution-cinematic-v2'
runs-on: ubuntu-latest
timeout-minutes: 25
steps:
- uses: actions/checkout@v4
with:
persist-credentials: true
- name: Prepare fonts, Chrome and Python tools
run: |
sudo apt-get update -qq
sudo apt-get install -y -qq ffmpeg fonts-noto-cjk
python -m pip install --quiet pillow numpy markdown-it-py selenium
google-chrome --version
- name: Render promo video from two original images and Marqdo source
run: python scripts/render-markdown-execution-promo.py
- name: Check resulting video
run: |
test -s assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4
test -s assets/marketing/marqdo-2.7.1-markdown-to-execution-cover.jpg
test -s assets/marketing/marqdo-2.7.1-markdown-to-execution.srt
ffprobe -v error -show_entries format=duration,size:stream=codec_name,width,height -of json assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4
- name: Commit compiled video, poster and subtitles
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4 \
assets/marketing/marqdo-2.7.1-markdown-to-execution-cover.jpg \
assets/marketing/marqdo-2.7.1-markdown-to-execution.srt \
assets/marketing/marqdo-procurement-standard-markdown.png
git diff --cached --quiet || git commit -m "docs: publish cinematic Markdown-to-execution promotional film"
git push origin HEAD:docs/markdown-execution-cinematic-v2
@@ -0,0 +1,48 @@
name: capture-procurement-marketing-assets
on:
push:
branches: [docs/executable-skill-showcase-271]
paths:
- "scripts/capture-procurement-showcase.py"
- ".github/workflows/capture-procurement-marketing.yml"
workflow_dispatch:
permissions:
contents: write
jobs:
capture:
if: github.ref_name == 'docs/executable-skill-showcase-271'
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
persist-credentials: true
- uses: actions/setup-python@v5
with:
python-version: "3.11"
- name: Prepare Chrome, Chinese fonts and Python imaging
run: |
python -m pip install --quiet pillow selenium
sudo apt-get update -qq
sudo apt-get install -y -qq fonts-noto-cjk
google-chrome --version
- name: Download Marqdo v2.7.1 Linux release
run: |
mkdir -p /tmp/marqdo-marketing-cli
curl -fL --retry 3 "https://github.com/cflmy/marqdo/releases/download/v2.7.1/marqdo-2.7.1-x86_64-unknown-linux-gnu.zip" -o /tmp/marqdo-marketing.zip
unzip -q /tmp/marqdo-marketing.zip -d /tmp/marqdo-marketing-cli
BIN="$(find /tmp/marqdo-marketing-cli -type f -name marqdo | head -n 1)"
test -n "$BIN"
chmod +x "$BIN"
echo "CLI_BIN=$BIN" >> "$GITHUB_ENV"
- name: Record real command outputs and capture real View
run: python scripts/capture-procurement-showcase.py --cli "$CLI_BIN"
- name: Commit reproducible promotional assets
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add assets/marketing/procurement-cli.gif assets/marketing/procurement-view.png
git diff --cached --quiet || git commit -m "docs: capture live procurement CLI GIF and View screenshot"
git push origin HEAD:docs/executable-skill-showcase-271
+50
View File
@@ -0,0 +1,50 @@
name: executable-knowledge
on:
push:
branches: [main]
pull_request:
jobs:
gate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- name: Build agent + llm plugins (EK / workbench gates)
run: |
cargo build -p marqdo_plugin_agent --locked
cargo build -p marqdo_plugin_llm --locked
- name: Native agent choice and bounded recovery unit tests
run: cargo test -p marqdo_plugin_agent --locked
- name: Check short AI flow documents
run: |
cargo run --locked -- check ext/ai/flow.mq.md
cargo run --locked -- check ext/ai/recovery.mq.md
cargo run --locked -- check ext/ai/context.mq.md
cargo run --locked -- check tests/ext/ai-native-flow.mq.md
cargo run --locked -- check ext/ai/workflow.mq.md
cargo run --locked -- check tests/ext/ai-native-workflow.mq.md
- name: Native AI flow interpreter smoke (offline)
env:
MARQDO_AGENT_PLUGIN: ${{ github.workspace }}/target/debug/libagent.so
run: |
cargo run --locked -- run tests/ext/ai-native-flow.mq.md
cargo run --locked -- run tests/ext/ai-native-workflow.mq.md
- name: Workbench contracts (M00–M06 / F-subset)
run: cargo test --test workbench_contracts --locked
- name: Offline executable-knowledge gate
run: cargo test --test executable_knowledge --locked
- name: Isolated execute MR-01 (dual 60s SSE + short reads)
run: |
cargo build -p marqdo_plugin_llm --locked
bash scripts/build-web-plugin.sh
cargo test --test isolated_execute_mr01 --locked -- --nocapture
timeout-minutes: 5
- name: no ignored tests counted as success
run: |
if grep -n '#\[ignore\]' tests/executable_knowledge.rs; then
echo "executable_knowledge must not use #[ignore] as success evidence" >&2
exit 1
fi
echo "ok: no #[ignore] in executable_knowledge gate"
+68
View File
@@ -0,0 +1,68 @@
# Independent extension sources and native libraries; no CLI/PPA publication.
name: Extension Release
on:
push:
tags:
- "ext-v*"
permissions:
contents: write
jobs:
windows:
runs-on: windows-latest
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: dtolnay/rust-toolchain@stable
- uses: actions/setup-go@v5
with:
go-version: "1.23.x"
- name: Install cgo toolchain
run: choco install mingw -y
- name: Build the handbook CLI and native capabilities
shell: bash
run: |
set -euo pipefail
export PATH="/c/ProgramData/mingw64/mingw64/bin:/c/ProgramData/chocolatey/lib/mingw/tools/install/mingw64/bin:$PATH"
cargo build --release -p marqdo -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering
bash scripts/build-web-plugin.sh
- name: Build and validate the runner's exact pack bytes
shell: bash
run: |
set -euo pipefail
./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json
- name: Attach source and Windows native packs without replacement
shell: bash
run: |
set -euo pipefail
./target/release/marqdo.exe call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json
linux:
runs-on: ubuntu-latest
needs: windows
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: dtolnay/rust-toolchain@stable
- uses: actions/setup-go@v5
with:
go-version: "1.23.x"
- name: Install ZIP and cgo tools
run: sudo apt-get update && sudo apt-get install -y zip gcc libc6-dev
- name: Build the handbook CLI and native capabilities
run: |
set -euo pipefail
cargo build --release -p marqdo -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering
bash scripts/build-web-plugin.sh
- name: Build and validate the runner's exact pack bytes
run: target/release/marqdo call skills/marqdo-release/packs.mq.md ci --effects plugin,fs.read,fs.write,environment.read --fs-root . --require-ok --json
- name: Attach Linux native pack without replacement
run: target/release/marqdo call skills/marqdo-release/packs.mq.md attach_ci --effects plugin,fs.read,environment.read --fs-root . --require-ok --json
+40
View File
@@ -0,0 +1,40 @@
# Cargo feature compatibility gate.
#
# `sema` (the core compiler) must build without the `cli` feature. Library
# consumers such as qdagent depend on `marqdo` with `default-features = false`,
# so any unconditional reference to a `cli`-gated module is a release blocker.
# Keep this matrix in sync with the feature graph in Cargo.toml.
name: feature-matrix
on:
push:
branches: [main]
paths:
- "src/**"
- "Cargo.toml"
- "Cargo.lock"
- ".github/workflows/feature-matrix.yml"
pull_request:
paths:
- "src/**"
- "Cargo.toml"
- "Cargo.lock"
- ".github/workflows/feature-matrix.yml"
workflow_dispatch:
concurrency:
group: feature-matrix-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
jobs:
lib-feature-matrix:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@1.81.0
- name: Library builds with no default features
run: cargo check --locked --lib --no-default-features
- name: Library builds with only the cli feature
run: cargo check --locked --lib --no-default-features --features cli
- name: Library builds with default features
run: cargo check --locked --lib
@@ -0,0 +1,50 @@
name: knowledge-proof-full-gate
on:
pull_request:
paths:
- "src/knowledge/**"
- "src/sema/**"
- "src/prove/**"
- "tests/**"
- "doc/verification/skill-proof/**"
- ".github/workflows/knowledge-proof-full-gate.yml"
workflow_dispatch:
concurrency:
group: knowledge-proof-full-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
jobs:
complete-proof-regression:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- name: Install pinned Lean kernel
run: |
curl -sSf https://elan.lean-lang.org/elan-init.sh | sh -s -- -y --default-toolchain leanprover/lean4:v4.35.0
echo "$HOME/.elan/bin" >> "$GITHUB_PATH"
- name: Validate Lean kernel and embedded proof library
run: |
lean --version
bash scripts/check-proof-library.sh
lean doc/verification/skill-proof/MarqdoModularProof.lean
lean doc/verification/skill-proof/MarqdoEffects.lean
- name: Build and run all knowledge unit tests
run: |
cargo build --locked
cargo test --locked --lib knowledge::
cargo test --locked --lib sema::ir::tests
- name: Knowledge and execution compatibility suites
run: |
cargo test --locked --test knowledge_proof
cargo test --locked --test executable_knowledge
cargo test --locked --test prove
- name: Full genuine Lean proof matrix
env:
MARQDO_PROOF_REQUIRE_LEAN: "1"
run: |
cargo test --locked --test prove_lean
cargo test --locked --test prove_corpus
cargo test --locked --test conformance
+70
View File
@@ -0,0 +1,70 @@
name: modular-proof-smoke
on:
pull_request:
paths:
- "src/knowledge/**"
- "src/sema/ir.rs"
- "src/prove/**"
- "tests/prove_lean.rs"
- "doc/verification/skill-proof/**"
- ".github/workflows/modular-proof-smoke.yml"
workflow_dispatch:
concurrency:
group: modular-proof-smoke-${{ github.event.pull_request.number || github.ref }}
cancel-in-progress: true
jobs:
modular:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- name: Compile isolated modular proof candidates
run: cargo test --locked --lib knowledge::composition::tests -- --nocapture
- name: Compile parameter-projection proof backend
run: cargo test --locked --lib knowledge::projection -- --nocapture
- name: Compile pure-expression VC backend
run: cargo test --locked --lib knowledge::expression::tests -- --nocapture
- name: Unified contract engine and evidence lattice unit tests
run: |
cargo test --locked --lib knowledge::unified::tests -- --nocapture
cargo test --locked --lib knowledge::evidence::tests -- --nocapture
- name: Compile path-sensitive VCs
run: cargo test --locked --lib knowledge::symbolic::tests -- --nocapture
- name: Compile closed-argument VCs
run: cargo test --locked --lib knowledge::vc::tests -- --nocapture
- name: Install Lean 4.35
run: |
curl -sSf https://elan.lean-lang.org/elan-init.sh | sh -s -- -y --default-toolchain leanprover/lean4:v4.35.0
echo "$HOME/.elan/bin" >> "$GITHUB_PATH"
- name: Lean proof of exception, ABI and fuel-bound models
run: |
lean doc/verification/skill-proof/MarqdoModularProof.lean
lean doc/verification/skill-proof/MarqdoEffects.lean
- name: Independently composed Lean modules
env:
MARQDO_PROOF_REQUIRE_LEAN: "1"
run: cargo test --locked --test prove_lean composition_emits_independently_replayable_caller_certificate -- --nocapture
- name: Symbolic parameter projection with independent Lean replay
env:
MARQDO_PROOF_REQUIRE_LEAN: "1"
run: cargo test --locked --test prove_lean projection_composition_proves_symbolic_caller_and_replays_from_source -- --nocapture
- name: Independent arithmetic contract composition with real Lean
env:
MARQDO_PROOF_REQUIRE_LEAN: "1"
run: cargo test --locked --test prove_lean pure_expression_composition_proves_and_replays_real_lean -- --nocapture
- name: Three module DAG and branching caller with independent Lean replay
env:
MARQDO_PROOF_REQUIRE_LEAN: "1"
run: cargo test --locked --test prove_lean unified_modular_contract_proves_multicall_branch_and_transitive_dag -- --nocapture
- name: Regenerated provenance for original Lean certificates
env:
MARQDO_PROOF_REQUIRE_LEAN: "1"
run: cargo test --locked --test prove_lean g2_certificate_hit_after_real_run -- --nocapture
- name: Linear symbolic arithmetic path implication with real Lean
env:
MARQDO_PROOF_REQUIRE_LEAN: "1"
run: cargo test --locked --test prove_lean arithmetic_symbolic_path_implication_uses_real_lean -- --nocapture
- name: Symbolic path implication with real Lean
env:
MARQDO_PROOF_REQUIRE_LEAN: "1"
run: cargo test --locked --test prove_lean symbolic_path_implication_uses_real_lean_without_runtime_promotion -- --nocapture
+40
View File
@@ -0,0 +1,40 @@
name: native-ai-flow
on:
push:
branches:
- feat/native-ai-flow-recovery-20261118
pull_request:
paths:
- 'plugins/agent/**'
- 'ext/ai/flow.mq.md'
- 'ext/ai/context.mq.md'
- 'ext/ai/recovery.mq.md'
- 'ext/ai/workflow.mq.md'
- 'tests/ext/ai-native-*.mq.md'
- '.github/workflows/native-ai-flow.yml'
jobs:
agent:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: dtolnay/rust-toolchain@stable
- name: Build the agent plugin
run: cargo build -p marqdo_plugin_agent --locked
- name: Run native agent and workflow tests
run: cargo test -p marqdo_plugin_agent --locked
- name: Check the public Marqdo ABI libraries
run: |
cargo run --locked -- check ext/ai/flow.mq.md
cargo run --locked -- check ext/ai/context.mq.md
cargo run --locked -- check ext/ai/recovery.mq.md
cargo run --locked -- check ext/ai/workflow.mq.md
cargo run --locked -- check tests/ext/ai-native-flow.mq.md
cargo run --locked -- check tests/ext/ai-native-workflow.mq.md
- name: Exercise offline integration through Marqdo
env:
MARQDO_AGENT_PLUGIN: ${{ github.workspace }}/target/debug/libagent.so
run: |
cargo run --locked -- run tests/ext/ai-native-flow.mq.md
cargo run --locked -- run tests/ext/ai-native-workflow.mq.md
Regular → Executable
View File
File mode changed.
+28
View File
@@ -0,0 +1,28 @@
name: procurement-example-smoke
on:
push:
branches: [main, docs/executable-skill-showcase-271]
paths: ["examples/procurement/**", ".github/workflows/procurement-example.yml"]
pull_request:
paths: ["examples/procurement/**", ".github/workflows/procurement-example.yml"]
jobs:
smoke:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Fetch released v2.7.1 Linux CLI
run: |
curl -fL --retry 3 "https://github.com/cflmy/marqdo/releases/download/v2.7.1/marqdo-2.7.1-x86_64-unknown-linux-gnu.zip" -o /tmp/marqdo.zip
unzip -q /tmp/marqdo.zip -d /tmp
BIN="$(find /tmp -type f -name marqdo | head -n 1)"
test -n "$BIN"
chmod +x "$BIN"
echo "CLI_BIN=$BIN" >> "$GITHUB_ENV"
- name: Check and run procurement skill
run: |
"$CLI_BIN" check examples/procurement/index.mq.md
"$CLI_BIN" call examples/procurement/index.mq.md 查询余额 已花费=120 --json
"$CLI_BIN" call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=120 交付要求天数=7 --effects time.read,process.control --json | tee /tmp/allowed.json
"$CLI_BIN" call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=360 交付要求天数=7 --effects time.read,process.control --json | tee /tmp/denied.json
grep -q '本地模拟' /tmp/allowed.json
grep -q '采购金额超过' /tmp/denied.json
+43
View File
@@ -0,0 +1,43 @@
name: Build Marqdo promotional video
on:
push:
branches: [docs/promo-video-271]
paths:
- scripts/make-procurement-promo.py
- .github/workflows/promo-video.yml
workflow_dispatch:
permissions:
contents: write
jobs:
build-video:
if: github.ref_name == 'docs/promo-video-271'
runs-on: ubuntu-latest
timeout-minutes: 20
steps:
- uses: actions/checkout@v4
with:
persist-credentials: true
- name: Prepare video environment
run: |
sudo apt-get update -qq
sudo apt-get install -qq -y ffmpeg fonts-noto-cjk
python -m pip install --quiet --disable-pip-version-check pillow numpy
ffmpeg -version | head -n 2
- name: Compose 32-second Marqdo video
run: python scripts/make-procurement-promo.py
- name: Verify deliverable
run: |
test -s assets/marketing/marqdo-2.7.1-promo.mp4
test -s assets/marketing/marqdo-2.7.1-poster.jpg
test -s assets/marketing/marqdo-2.7.1-promo.srt
ffprobe -v error -show_entries format=duration,size -of default=noprint_wrappers=1 assets/marketing/marqdo-2.7.1-promo.mp4
- name: Commit video into promotional branch
run: |
git config user.name "github-actions[bot]"
git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
git add assets/marketing/marqdo-2.7.1-promo.mp4 assets/marketing/marqdo-2.7.1-poster.jpg assets/marketing/marqdo-2.7.1-promo.srt
git diff --cached --quiet || git commit -m "docs: render Marqdo 2.7.1 promotional video from existing assets"
git push origin HEAD:docs/promo-video-271
+115
View File
@@ -0,0 +1,115 @@
# 判定流水线(marqdo prove)
#
# 验证「SKILL 编排文档 → Lean 4 → 自动证明」全链路:
# 1. 构建内置 Lean 底座(MarqdoProof.lean)。
# 2. 跑判定矩阵(tests/prove_lean.rs):真定理 proved、假定理 unproved、
# 证书缓存命中跳判定、--require-lean 退出码。
# 3. CI 硬性要求(MARQDO_PROOF_REQUIRE_LEAN=1):没有工具链即失败,
# 不允许悄悄降级成 unverified。
#
# 说明:仓库不强制贡献者装 Lean——本工作流在装有 elan 的 runner 上运行;
# 本地无 Lean 时判定状态为 unverified(advisory,不阻塞)。
name: proof
on:
push:
branches: [main]
paths:
- "src/prove/**"
- "doc/verification/skill-proof/**"
- "lib/**"
- "tests/prove*.rs"
- ".github/workflows/proof.yml"
pull_request:
paths:
- "src/prove/**"
- "doc/verification/skill-proof/**"
- "lib/**"
- "tests/prove*.rs"
- ".github/workflows/proof.yml"
workflow_dispatch:
jobs:
proof:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install Rust (1.81)
run: |
rustup toolchain install 1.81.0 --profile minimal
rustup default 1.81.0
# leanprover/lean-action@v1 已移除 lean4-version;本仓库运行时只需 lean 二进制
# (底座内嵌、不经 lake)。用 elan 钉 v4.35.0,与 doc/verification/skill-proof/lean-toolchain 一致。
- name: Install Lean 4.35.0 (elan)
run: |
curl -sSf https://elan.lean-lang.org/elan-init.sh | sh -s -- -y --default-toolchain leanprover/lean4:v4.35.0
echo "$HOME/.elan/bin" >> "$GITHUB_PATH"
"$HOME/.elan/bin/lean" --version
- name: Verify embedded proof library
run: |
chmod +x scripts/check-proof-library.sh
scripts/check-proof-library.sh
- name: Build
run: cargo build --locked
- name: Judgment matrix (real Lean; CI requires toolchain)
env:
MARQDO_PROOF_REQUIRE_LEAN: "1"
run: cargo test --locked --test prove_lean
- name: Rest of prove suite (no toolchain assumptions)
run: cargo test --locked --test prove
- name: Corpus monotonicity — offline_checked ⊆ lean_proved (40 fixtures)
env:
MARQDO_PROOF_REQUIRE_LEAN: "1"
run: cargo test --locked --test prove_corpus
- name: T4 differential consistency — interpreter == Lean
env:
MARQDO_PROOF_REQUIRE_LEAN: "1"
run: cargo test --locked --test conformance
- name: Full sweep — divergence guard bites on injected fault
env:
MARQDO_PROOF_REQUIRE_LEAN: "1"
run: |
# A3:注入分歧必须显式失败(error[proof.divergence],退 1)——
# 护栏失灵(静默落绿)比单点失败严重得多。
set -e
tmp=$(mktemp -d)
cat > "$tmp/审批.mq.md" <<'FIXTURE'
---
markup: occlusion
---
# 台账
## 记录
+ `金额`
| 定理 | 结论 | 策略 |
|---|---|---|
| 记过即记 | 长度(轨迹) = 1 | auto |
**结果 = [登记](result.ok(value=`金额`))**
*结果*
FIXTURE
set +e
out=$(cargo run --locked -- prove "$tmp/审批.mq.md" --fault-inject offline-claim --json 2>/dev/null)
code=$?
echo "$out" | head -c 400
if [ "$code" -ne 1 ]; then
echo "::error::注入分歧未被拦截(exit=$code)——单调性护栏失灵"
exit 1
fi
echo "$out" | grep -q "proof.divergence" || {
echo "::error::未出现 proof.divergence 诊断"
exit 1
}
echo "divergence guard OK"
+32 -36
View File
@@ -5,6 +5,7 @@ on:
push:
tags:
- "v*"
workflow_dispatch:
permissions:
contents: write
@@ -38,7 +39,7 @@ jobs:
run: |
export PATH="/c/ProgramData/mingw64/mingw64/bin:/c/ProgramData/chocolatey/lib/mingw/tools/install/mingw64/bin:$PATH"
cargo build --release
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering
bash ./scripts/build-web-plugin.sh
- name: Checkout extension sources (branch vscode-extension only)
@@ -51,6 +52,7 @@ jobs:
New-Item -ItemType Directory -Force -Path dist | Out-Null
Push-Location vscode-extension
npm ci
npm version "$ver" --no-git-tag-version --allow-same-version
npm run compile
npx @vscode/vsce package --no-dependencies -o "../dist/marqdo-$ver.vsix"
Pop-Location
@@ -88,6 +90,7 @@ jobs:
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"
Copy-Item target/release/engineering.dll "$stageNative/native/engineering.dll"
if (Test-Path "dist/$nativeZip") { Remove-Item "dist/$nativeZip" -Force }
Compress-Archive -Path "$stageNative/*" -DestinationPath "dist/$nativeZip" -Force
$stage = "dist/stage-bundle"
@@ -102,6 +105,7 @@ jobs:
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"
Copy-Item target/release/engineering.dll "$stage/ext/native/engineering.dll"
if (Test-Path "dist/$zip") { Remove-Item "dist/$zip" -Force }
Compress-Archive -Path "$stage/*" -DestinationPath "dist/$zip" -Force
$stageLib = "dist/stage-stdlib"
@@ -116,48 +120,18 @@ jobs:
echo "VSIX=$vsix" >> $env:GITHUB_ENV
echo "SOURCE=$source" >> $env:GITHUB_ENV
echo "PUBLIC=$public" >> $env:GITHUB_ENV
echo "PUBLISH_EXT=$((Get-Content ext/VERSION -Raw).Trim() -eq $ver)" >> $env:GITHUB_ENV
echo "EXT=$extZip" >> $env:GITHUB_ENV
echo "NATIVE=$nativeZip" >> $env:GITHUB_ENV
- name: Upload release assets
uses: softprops/action-gh-release@v2
with:
body: |
## Marqdo ${{ github.ref_name }}
### 亮点 / Highlights
- **v1.3.0**:Engineering Knowledge Compiler——L0–L4 · `reuse`/`find`/`duplicate` · Agent preflight(REUSE→ADAPT→CREATE)
- **v1.3.0**: Engineering Knowledge Compiler — L0–L4 catalog, reuse/find/duplicate, Agent preflight (REUSE→ADAPT→CREATE)
- **v1.2.0**:Web Artifact(ADR 0007)——Document/Endpoint · `web.serve`/`render`/`inspect` · `ext/data|security|net` · 移除 `compose_*`/`configure`
- **v1.2.0**: Web Artifact (ADR 0007) — Document/Endpoint, web.serve/render/inspect, ext/data|security|net, compose_*/configure removed
- **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
| Asset | Contents |
|-------|----------|
| `marqdo-*-windows-msvc.exe` | CLI with **embedded** official stdlib |
| `marqdo-*-windows-msvc.zip` | `marqdo.exe` + `lib/` + `ext/`(含 native DLL) |
| `marqdo-*-native-*.zip` | 预编译 `web`/`agent`/`quantum`/`linalg`/`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`) |
| `marqdo-*.vsix` | VS Code / Cursor extension |
| `marqdo-*-public.zip` | Static user docs site |
Extension workflow: [vscode-extension-commit.md](https://github.com/cflmy/marqdo/blob/main/doc/design/vscode-extension-commit.md)
body_path: doc/releases/${{ github.ref_name }}.md
files: |
dist/${{ env.EXE }}
dist/${{ env.ZIP }}
dist/${{ env.STDLIB }}
dist/${{ env.EXT }}
dist/${{ env.NATIVE }}
dist/${{ env.VSIX }}
dist/${{ env.SOURCE }}
dist/${{ env.PUBLIC }}
@@ -165,6 +139,17 @@ jobs:
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Upload independently versioned extension assets
if: env.PUBLISH_EXT == 'True'
uses: softprops/action-gh-release@v2
with:
files: |
dist/${{ env.EXT }}
dist/${{ env.NATIVE }}
fail_on_unmatched_files: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
linux:
runs-on: ubuntu-latest
# Wait until Windows has created the GitHub Release, then attach Linux zips
@@ -188,7 +173,7 @@ jobs:
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
cargo build --release -p marqdo_plugin_agent -p marqdo_plugin_quantum -p marqdo_plugin_linalg -p marqdo_plugin_llm -p marqdo_plugin_engineering
bash ./scripts/build-web-plugin.sh
- name: Package Linux native zip + CLI bundle
@@ -196,8 +181,11 @@ jobs:
set -euo pipefail
VER="${GITHUB_REF_NAME#v}"
TARGET="x86_64-unknown-linux-gnu"
if [[ "$(tr -d '[:space:]' < ext/VERSION)" == "$VER" ]]; then
echo "PUBLISH_EXT=true" >> "$GITHUB_ENV"
fi
mkdir -p dist/stage-native/native
for lib in libweb.so libagent.so libquantum.so liblinalg.so libllm.so; do
for lib in libweb.so libagent.so libquantum.so liblinalg.so libllm.so libengineering.so; do
src="target/release/${lib}"
if [[ ! -f "$src" && "$lib" == libweb.so ]]; then
src="plugins/web/build/libweb.so"
@@ -224,8 +212,16 @@ jobs:
uses: softprops/action-gh-release@v2
with:
files: |
dist/${{ env.NATIVE }}
dist/${{ env.LINUX_ZIP }}
fail_on_unmatched_files: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
- name: Upload independently versioned Linux native pack
if: env.PUBLISH_EXT == 'true'
uses: softprops/action-gh-release@v2
with:
files: dist/${{ env.NATIVE }}
fail_on_unmatched_files: true
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
Regular → Executable
+43 -5
View File
@@ -1,5 +1,7 @@
/target/
/dist/
# Plugin unit tests use package-relative scratch checkpoints.
/plugins/agent/target/
# Copied by gold harness for ABI plugins
/tests/lib/demo.dll
@@ -42,11 +44,7 @@ spike/.pytest_cache/
*.pyc
# Built browser WASM (rebuild via crates/marqdo-wasm README)
/examples/browser-hello/marqdo_wasm.wasm
/examples/browser-hello/pkg/
/examples/web-client-site/static/marqdo_wasm.wasm
/examples/browser-app/marqdo_wasm.wasm
/examples/browser-media/marqdo_wasm.wasm
# Local sqlite / scratch
/data/
@@ -61,7 +59,6 @@ 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
@@ -71,9 +68,24 @@ plugins/*/tmp/
/examples/linalg-*/**/*.svg
/examples/linalg-*/*.svg
/examples/linalg-*.svg
# oa2026 showcase: SVGs beside the examples ARE tracked; root-level ones are
# run artifacts (draw/plot write to cwd when the example is run from root)
/bell-*.svg
/calculus-*.svg
# Plot SVGs emitted beside tests / notebooks when demos run
/tests/**/*-plot-*.svg
# Lean Lake build outputs (sources under verification/ stay tracked)
**/.lake/
# PLDI / thesis harness scratch must never land in this tree
.lx*-tmp/
# Local ABI plugin copies (use `marqdo ext add quantum` / cargo build)
/ext/native/
# Install-root path hints from `marqdo ext add` — never belong in the source tree
/ext/*.plugin
# Go web plugin c-shared build output (./scripts/build-web-plugin.sh)
/plugins/web/build/
@@ -87,3 +99,29 @@ tests/ext/:memory:
# local secrets
.env
# sandbox gold leftovers
tests/ext/_sbx_cow/
tests/ext/_sbx_*/
examples/**/_example_sbx/
.secrets/
# Generated runtime resources for callable browser handbook examples
/examples/web-spa-app/static/marqdo_wasm.wasm
/examples/web-spa-app/static/marqdo-bridge.js
/examples/web-collab-doc/static/marqdo_wasm.wasm
/examples/web-collab-doc/static/marqdo-bridge.js
# Native browser runtime and compiled theme produced by the network-site handbook.
/examples/web-net-site/public/generated/
/examples/web-net-site-zh/public/generated/
# Generated literary-site theme resources (the declarative sources stay tracked).
/examples/web-site/public/generated/
/examples/web-site-zh/public/generated/
# Native browser-effects example generated resources.
/examples/browser-app/static/marqdo_wasm.wasm
/examples/browser-app/static/marqdo-bridge.js
/examples/browser-app/static/theme.css
+876
View File
@@ -1,5 +1,497 @@
# Changelog
## v2.9.1 — 2026-11-18 · Full release / 正式补丁版本
Marqdo 2.9.1 修复 2.9.0 的库构建回归:`knowledge` 属于核心编译器,不再由 `cli` 特性门控,`default-features = false` 的下游库恢复可编译;并新增 feature-matrix CI 守卫。无运行时语义、插件 ABI 或证书格式变化。
**EN:** 2.9.1 fixes the 2.9.0 library regression where the core compiler's `knowledge` module was gated on `cli`, breaking `default-features = false` consumers; a feature-matrix CI gate now prevents regressions. No runtime semantics, plugin ABI or certificate format changes.
### Fixed
- Library builds with `--no-default-features` again. `sema::ir` unconditionally
emits `proof-index.json` / `proof-obligations.json` through `knowledge`, but
`knowledge` was gated on `cli`; it is now part of the core compiler, so
downstream crates using `default-features = false` no longer hit
`E0433: could not find knowledge in the crate root`.
- CI: `feature-matrix` checks the library with no features, `cli` only, and
default features to prevent feature-gate regressions.
详情 / Details: [2.9.1 release notes](doc/releases/v2.9.1.md).
## v2.9.0 — 2026-11-18 · Full release / 正式完整版本
Marqdo Verified Knowledge Compiler: source-addressable knowledge proof artifacts, bounded Lean 4 modular contract composition, precise evidence grades, independent replay, and fail-closed unsupported semantics.
- Unified source-derived pure-function proof DAG with symbolic parameters, sequential calls, total conditional branches, multi-module imports, and kernel-checked caller contracts.
- Stable statement and theorem anchors, dependency closure signatures, proof indexes and source-change invalidation.
- `proved`, `model_proved`, `tested`, `assumed`, `unknown`, `refuted`, `stale` are distinct; Lean Int-model proofs **do not** prove the complete Marqdo `number` or i64 runtime.
- Independent Lean replay and negative regression tests for changed source, missing preconditions, unsupported effects, and false caller conclusions.
- Full CLI/WASM/ext version synchronization, Windows/Linux native archives and editor release packaging (completion requires actual release workflow and asset verification).
- Existing `marqdo prove` behavior, classic knowledge references, and `marqdo call` remain supported. Unsupported loops, recursive functions, dynamic dispatch, plugins and unverified runtime behaviors never become auto-proved.
Marqdo 2.9.0(full)发布可寻址知识制品、统一纯函数模块化契约组合、真实 Lean 证书独立重放与证据等级;保留旧证明证书重放。仅支持明确的纯整数抽象子集,不宣称完整运行时正确性或所有函数自动可证。
详情 / Details: [2.9.0 release notes](doc/releases/v2.9.0.md) · [Trust boundaries](doc/design/verified-knowledge-compiler-boundaries.md).
## Ext pack v2.8.1 — 2026-11-18
### Highlights
**AI native durable workflow(CLI 仍为 v2.8.0)**:`ext/ai` 以插件侧步骤机交付持久化
工作流(`workflow`/`flow`/`context`/`recovery`),含有界模型选择、作用域上下文、
只读失败恢复、`inspect`/`list` 与可隔离 `resume_dir`。Windows 打包使用 `path.join`
根路径与 `System32\tar.exe`。详见 [双语发布说明](doc/releases/ext-2.8.1.md)。
```bash
marqdo ext add agent # CDN latest → 2.8.1
# 或:MARQDO_EXT_VERSION=2.8.1 marqdo ext add agent
```
**核心表面 Δ(Core surface Δ)**:**无增删**——仅 Extension / Agent Runtime。
### Added
- `ext/ai/workflow`:`open/next/commit/cancel/tick/retry_*`,以及只读 `inspect`/`list`
与各操作的 host-relative `resume_dir`。
- `ext/ai/flow` · `context` · `recovery`:ask/choose、作用域打包、CheckpointV2 恢复面。
- Agent ABI:`agent_workflow_*`、`agent_choice_parse`、`agent_context_scope`、
`agent_input_*`、`agent_parallel_report`。
- Offline fixtures:`tests/ext/ai-native-flow.mq.md`、`tests/ext/ai-native-workflow.mq.md`;
CI:`.github/workflows/native-ai-flow.yml`。
### Fixed
- `flow.choose` no longer leaks a branch-local `parsed` value into the function
contract; the repaired-choice path is fully scoped.
- CI builds the agent cdylib and runs offline integration without the removed
`run --effects` flag, using `MARQDO_AGENT_PLUGIN` instead.
- Atomic checkpoint/effect temp names no longer collide under parallel writes;
resume tests no longer race on process-wide cwd.
- Windows `extension-release`:engineering root 使用 `path.join` / cwd 回退;
ZIP 显式调用 `System32\tar.exe`(bsdtar);`packs.ci` 授予 `fs.read`。
### Changed
- 扩展包 SemVer **2.8.1**(`ext/VERSION`);与 CLI **v2.8.0** 可独立安装。
- 分支已合并 v2.8.0 依赖锁后的 AI 工作流增量,不再从 2.7.1 基线分叉。
## v2.8.0 — 2026-11-17
`marqdo prove` 正式发布:定理表 → Lean 4 证明 → 自动判定。离线符号执行(F1–F5)无工具链可用,`checked` 永远弱于 `proved`;单调性护栏让判定器缺陷显式失败;假定理给出反例见证;证书缓存与目录模式面向智能体批量出证。
`marqdo prove` ships: theorem tables compile to Lean 4 and are judged automatically. Offline symbolic execution works without a toolchain, monotonicity guardrails fail loudly on judger defects, fake theorems get counterexample witnesses, and certificate caching plus directory mode support agent-scale proving.
详见 [双语发布说明](doc/releases/v2.8.0.md)。
## v2.7.1 — 2026-11-11
CLI 修复发布:View 实际逻辑的手动开合不再被布局重排或运行结果刷新覆盖;函数、链接、列表和记录按内容排版,手机详情整行展示。核心仍为 19 个构造;拓展库保留 2.7.0。
CLI fix release: implementation disclosures retain mouse/keyboard choices across resize, nested source reading and live replacement. Typed call/link/value details preserve real navigation and read-only inspection. Independent extension packs remain 2.7.0.
详见 [双语发布说明](doc/releases/v2.7.1.md)。旧静态站点需要用新 CLI 重新导出。
## v2.7.0 — 2026-11-10
### Highlights / 亮点
源码手册进入真实开发与用户站点:原生文件操作、可调用开发/发版流程、递归 View 站点及当前请求资源。CLI、WASM、拓展包与编辑器版本统一为 2.7.0。详见 [完整双语发布说明](doc/releases/v2.7.0.md)。
Executable source handbooks now drive actual development and user sites: native file operations, callable release tasks, recursive View Documents and current request resources. CLI, WASM, extension packs and editor version are 2.7.0.
**核心表面 Δ / Core surface Δ**:无增删,仍为 19 个核心构造;沿用既有 Markdown 标记与插件 ABI。
### Added
- Native development and release handbooks, bounded engineering plugin boundaries, literal CLI JSON file/stdin arguments and --require-ok failure propagation.
- 原生文档表读取与保留正文的修改;纯 head 资源,以及当前请求的数据查询、表单与会话导航资源。
- Both-language recursive user sites, source-aware route inspection, retained theme declarations and actual browser acceptance.
- Structured nested list/control records in the official bridge, documented in EN/ZH browser libraries and the callable browser-app.
### Fixed
- Occlusion receivers, nested and hyphenated-path calls, prose literal defaults and exact CLI argument/session replay semantics.
- 授权站点根下的文件/SQLite 定位;嵌套 Document 与 Endpoint 回调上下文;表单重试 CSRF、成功跳转、管理入口与片段选择。
- Browser duplicate-item deletion, literal content rendering, Back/Forward history and asynchronous outcome reporting.
### Changed
- SKILL discovery delegates to executable handbooks; ordinary file IO and orchestration use Marqdo instead of Python release scripts.
- 中英文用户站点保留原始主题、当前文章与管理能力;移除无关的暗恋工程和过时独立浏览器演示,保留底层测试夹具。
- Native packs include the engineering plugin. Main excludes editor sources; immutable tags, both-platform builds and independent GitHub/CDN/Ubuntu verification remain release obligations.
## v2.6.0 — 2026-11-08
### Highlights / 亮点
标准库、拓展库与阅读界面共同围绕“源码即手册,文档即 SKILL,函数即工具”完成更新。
CLI、WASM、扩展包与 VS Code 扩展统一为 2.6.0。
- 标准库新增完整文件整理、二进制与分块、集合处理、结构化数据、文档修改、HTTP、子任务与时区能力。
- 61 份公开标准库提供 650 个函数,保持单文件自述;多文件拓展库通过 index 组织真实工作流。
- Quantum 提供可执行实验与会话句柄;Web 明确从区域树递归拆到 Markdown 叶子的工程方式。
- View 正文只呈现动作说明,实际逻辑进入左右侧注,空括号明确提示待补逻辑;知识区按输入输出与依据组织。
- Standard libraries add practical file, binary, collection, structured-data, document, HTTP, task and timezone workflows.
- Libraries are executable handbooks with contracts, narrative parameters and readable inline operations; View separates action text, implementation and observed results.
**核心表面 Δ(Core surface Δ)**:无增删,仍为 19 个核心构造。新增能力属于 Runtime / Document;
行内遮蔽边界与 GFM 转义修复沿用既有标记,不引入另一套语法或 Skill 编译器。
### Added
- 文件:查找、行读写、JSON/CSV 读写、二进制字节和分块操作、临时资源、单文件原子写、摘要检查、目录批处理与可选 ZIP。
- 集合:范围、枚举、投影、筛选、首项/任一/全部判断、分组汇总、连接、集合运算、模式校验及 key/value 行记录构造。
- 数据与工程:Result、完整 TOML、IANA 时区/DST、结构化 HTTP 结果与下载、子任务超时/并发/取消、保留周围叙述的受控文档修改。
- 标准库单文件手册、开发指南、真实工程示例,以及数据、安全、网络、线性代数、AI 的工程入口与安装依赖。
- Quantum 任务导航、实验与双语门面;Web 递归布局、普通 Markdown 叶子和双语参考站点;call 会话中传递实际资源句柄。
- View 核心语法阅读指南、实现侧注、可读知识卡片、最终绑定与调用记录,以及静态/实时/无脚本浏览器验收。
### Fixed
- 修复中文智能体单步被说明中的斜体 map 提前返回、事务构造器返回未绑定 self、策略说明标题被误识别为对象等旧问题。
- 修复行内遮蔽中标签星号和载荷乘法的结束边界,以及 GFM 单元格的转义竖线。
- 修复整句遮蔽只处理首个链接、改写叙述的问题;普通导航与文字字面量不冒充可执行逻辑。
- 单文件 View 只分析实际依赖闭包,避免无关同目录模块重名使知识说明整体不可用。
- 修复回放策略 wire 命令与 agent smoke 工具注册,保持可执行知识门禁可复现。
### Changed
- 标准库和拓展库的参数与返回表紧接标题;移除库源码中的旧加号形参,使用叙述形参与句中赋值、调用、返回。
- 每个库单元叙述超过 50%;行内代码和绑定数据表仍计作代码,避免以模板或排版替代说明。
- 知识区将身份和摘要折叠为技术详情,分别呈现静态检查、测试、来源与领域审阅;阅读操作不会执行代码。
- 既有可用接口、默认值和副作用边界保持兼容。原生专属能力不宣称在 WASM 可用,目录批处理不宣称事务,摘要写入不宣称内核 CAS。
### Validation
- 本地全量回归 984 通过、0 失败、2 个原有忽略项;发布提交与打包产物另行复核。
- 实际 wasm32 产物通过 ABI、桥接、双语集合与 32 位边界验收。
- Chromium 验证七种宽度、实时与静态页面、无脚本回退、源码定位、曲线、帧切换与重新运行。
## v2.5.1 — 2026-11-07
### Highlights
**View 标注连线与工具栏优化 / View annotation and toolbar refinement**:执行标注精确绑定源码行与字节区间;连续 S 形曲线取代水平长线,标注贴近正文错落排布,并避让正文和相邻连线;浮动工具栏增加文字说明。CLI · wasm · ext **2.5.1**。
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造);无 Markdown 语法或插件 ABI 变更。
### Fixed
- 执行标注从实际源码片段引出并连接标注标题,不再从正文边缘引出;多调用帧与循环轮次共用准确的源码区间,避免按类型猜测锚点。
- 处理源码换行、重跑、窗口变化与字体加载后的连线定位;保留密集区域和窄屏的文内降级。
- 连线连续弯曲、柔和金绿过渡,并为相邻曲线保留间距;宽屏标注更靠近正文,横纵方向错落排布。
### Changed
- 底部工具栏显示“刷新、设置、运行、清理、更多”,保留深浅色配色与原有操作行为。
- 新增七种屏宽、曲率、连线交叉、两端定位及共享源码帧绑定的浏览器回归。
- CLI、WASM、扩展包和 VS Code / Cursor 扩展同步 **2.5.1**;扩展包功能沿用 v2.5.0。
## v2.5.0 — 2026-11-07
### Highlights
**View 文档阅读界面重构 / View reader redesign**:暖白金色排版、新 Marqdo 标志与花枝羽毛素材;宽屏执行信息左右引出,窄屏回到正文下方;导航、搜索与悬浮工具栏;实时 view 与静态导出同源,公式和素材离线可用。CLI · wasm · ext **2.5.0**。
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)。本次变更集中于 view 展示与普通文档执行结果刷新;无 Markdown 语法或插件 ABI 变更。
```bash
marqdo view public
marqdo view output public -o site
```
### Added
- 暖白/深色阅读主题、新 Logo、透明花枝与羽毛;顶部导航、正文/函数/文件搜索、阅读设置和悬浮工具栏。
- 宽屏执行标注左右排布与避让,点击查看完整捕获值;窄屏、密集段落和打印采用正文内标注。
- 内嵌 KaTeX 0.16.22、字体和装饰素材,静态页面断网仍可渲染公式。
- 六种屏宽的 live/static 浏览器回归与普通文档重跑结果一致性回归。
### Fixed
- 普通文档重跑后,从同一次执行捕获刷新正文、变量与轨迹,避免为更新标注重复执行。
- 移除重复的正文 `id="structure"`,确保刷新定位到实际正文;修复搜索框 Escape 关闭与隐藏目录焦点行为。
### Changed
- 函数和变量面板按需打开;调用帧与循环轮次选择保留;高级 notebook 操作从工具菜单进入。
- CLI、WASM、扩展包和 VS Code / Cursor 扩展同步为 **2.5.0**;扩展包功能沿用 v2.4.0 已发布内容。
## v2.4.0 — 2026-11-06
### Highlights
**Oracle journal 作语言值**:`foreign.oracle_journal` / `foreign.replay_check` 把观测与纯比较暴露为普通 Marqdo 值(非仅 notebook API);handle/code 不得入 journal;`copy` 拒绝 code。Bytecode / frontend / foreign session 模块化与 applications 金样例;`verification/replay-policy` Lean 策略身份。CLI · wasm · ext **2.4.0**。
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——变更在 `lib/foreign` 宿主表面与实现结构,不增 Markdown 标记。
### Added
- **`foreign.oracle_journal` / `foreign.replay_check`**:文档级观测列表与纯 journal 比较(`doc/design/oracle-journal-values.md`)。
- **回归**:`foreign-oracle-{journal,names,failure}`、`foreign-{,session-}copy-code-refuse`、`tests/oracle_journal.rs`、applications 四场景、`verification/replay-policy`。
- **文档**:`oracle-journal-values.md`;frontend-call / foreign-library 方向笔记。
### Fixed
- **view notebook API**:`OnceLock` 初始化等待兼容 MSRV **1.81**(不再调用 ≥1.84 的 `wait`)。
- JSON `float_roundtrip` 特征,减少外联浮点往返失真。
### Changed
- Bytecode compile/VM、foreign_doc/session、sema resolution、notebook interrupt 路径拆模块(行为对齐既有 Strong 契约)。
## v2.3.0 — 2026-11-01
### Highlights
**Foreign Strong(session / value / replay)**:会话句柄改为不透明 `handle`(不可 JSON 过桥、禁止 text 伪造);`close` 仿射消费(双 close / use-after-close 故障);`replay_check` 对照 oracle journal(旧 `replay_snapshot` 仅重跑保留);GFM 表行 arity 与列长映射拒绝静默补空;Ω 返回域外整数故障。对齐 PLDI Strong 叙事与 Lean SessionReg / \(V_{\mathsf{safe}}\)。CLI · wasm · ext **2.3.0**。
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——破坏面在宿主 foreign/session/JSON 与表解析纪律,不增 Markdown 标记。
### Added
- **`Value::Handle`**:`session_open` 返回句柄;session 操作拒绝 text 伪造。
- **`DocumentSession::replay_check`** + API `/api/session/snapshot/replay_check`;snapshot 录音字段 + **`oracle_journal`**(与 execution journal 分名)。
- **API** `/api/session/oracle_journal`。
- **文档**:`doc/design/foreign-strong-correspondence.md`;`v-safe-json.md` 补 Handle / 列 arity / Ω 门。
- **回归**:`foreign-session-{use-before-open,use-after-close,double-close,cold-replay-empty,isolation,handle-no-serialize,result-vsafe-refuse}`;`tests/errors/table-arity.mq.md`。
### Fixed
- 不等宽 GFM 表不再静默补空单元格;解析报 `table row arity mismatch`。
- Py/Node session bootstrap:Ω 结果 OOD 整数不再 `default=str` 偷渡,宿主升级为故障。
### Changed
- **`session_close`**:未知 / 已关闭句柄 → 故障(不再返回 `False`)。
- **`session_list`**:`id` 字段为 `handle`。
- Snapshot export 含 `ok`/`code`/`stdout`/`result`/`source_hash` 与 `oracle_journal`。
## v2.2.2 — 2026-11-01
### Highlights
**\(V_{\mathsf{safe}}\) JSON 整数契约落地**:外联 / `json.parse` / `json.stringify` / `session_set` 等共用映射对齐 Lean ForeignJSON——`|n| > 2^{53}-1` 的 JSON 整数显式拒绝(错误前缀 `json: integer outside V_safe`),禁止 Node 路径静默扭曲;宽整数仍用十进制字符串 + 对端 `BigInt`。CLI · wasm · ext **2.2.2**。
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——宿主 JSON 契约与测试,不改 Markdown 标记。
### Added
- **`doc/design/v-safe-json.md`**:宿主 ↔ Lean \(V_{\mathsf{safe}}\) 契约锁定(`MAX_SAFE`、encode/decode refuse、嵌套、float 为宿主扩展)。
- **回归**:`tests/lib/json-vsafe-*`、`foreign-vsafe-*`、`foreign-session-vsafe-refuse`(含算术后越界 refuse)。
### Fixed
- **`src/host/json.rs`**:对域外整数与 `u64 > i64::MAX` 显式失败;不再经 `f64`/`Text` 静默降级。
- **`doc/design/foreign-kernel.md`**:Int→number 仅当 `|n| ≤ 2^{53}-1`;宽整数走 string 桥。
### Changed
- 外联 JSON 桥与 `lib/json` 行为:OOD 整数从「可能静默失真」改为「诊断失败」。
## v2.2.1 — 2026-10-30
### Highlights
**view / 静态导出大纲侧栏修复**:带遮蔽(occlusion)语句的文档页里,Functions / Variables 右侧栏会掉到正文下面;中等窗口宽度下也会被错误叠成单列。CLI · wasm · ext **2.2.1**。
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——布局与 HTML 闭合修复,不改 Markdown 标记。
### Fixed
- **`marqdo view` / `view output`**:occlusion 行提前返回时未关闭 `.doc-block`,把 `#outline-rail` 嵌进 `document-surface`,侧栏排到文档下方;现已闭合并保留标注带。
- **view 壳 CSS**:大纲折叠改为按主栏 `@container mq-panel` 宽度(32rem),不再用视口 `960px` 媒体查询把右侧栏压到正文下;极窄时大纲上移到文档上方。
## v2.2.0 — 2026-10-30
### Highlights
**函数级调用 `marqdo call`**:同一份 `.mq.md` 已经是文档、知识和程序。这一版补上从外部调用其中某个函数的入口。人继续读这一页;开发者、测试和 Agent 用同一条命令传入参数并执行。知识复用、把函数当工具、逐个函数做测试、改完再跑,都是这一入口的用法,不是另一套 Skill 系统。CLI · wasm · ext **2.2.0**。
```bash
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
# 5
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3 --json
```
**作用**:最小可执行单位从「整份文件」扩展到「文件里的一个函数」。不必为了试一个函数再写 `# main`、打印和包装程序。
**价值**:说明和实现仍在同一页。Agent 读函数旁边的叙述,定位函数,传入参数,得到可检查的结果。正式发布和权限仍走已有的项目验证;`call` 默认不开放写文件、进程、网络和插件。
说明页:[public/features/22-函数调用.mq.md](public/features/22-函数调用.mq.md) · [public/features/22-call.mq.md](public/features/22-call.mq.md)
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——新增的是 CLI 入口,不新增 Markdown 标记。`**…**` 仍是语句,`*…*` 仍是返回。
### Added
- **`marqdo call <文件.mq.md> <函数> [名字=值 ...]`**:加载该文件及其 import,按显示路径、SymbolId 或唯一短名定位函数,用现有签名和契约绑定参数,再用现有运行时执行。
- **`--json`**:成功 `{"ok":true,"result":...}`,失败 `{"ok":false,"error":...}`,错误带诊断 `code`。`--backend tree|bytecode` 与 `marqdo run` 相同;指定函数时两个后端都不会改去跑 `# main`。
- **默认纯函数**:效应含写入、网络、进程或插件时,执行前返回 `artifact.effect_denied`,副作用不会发生。
- **参照文档** `examples/calculator.mq.md`,以及用户说明页 `public/features/22-*`。
### Fixed
- 官方语法说明与 Agent 语法卡的标记极性与解析器对齐:粗体是语句,斜体是返回。同步测试会实际运行说明里的调用示例。
- Bytecode 的 `marqdo run --call-lib-path` 执行被点名的导入函数,不再忽略该参数去跑入口。
- 隔离运行时冒烟测试补上 `InvokeContext.fs_root`,`--tests` 可以编过。
### Changed
- CLI / wasm / `ext/VERSION` **同步 2.2.0**。扩展包版本号对齐;这一版的新能力在 CLI。
## v2.1.5 — 2026-10-27
### Highlights
**Agent 可靠工作台 + EKC 热路径**:ResourceView(JSON/CSV/PDF/image `blob_ref`、locator 页/行)· ToolSpec 授权先于调用 · CheckpointV2 / EffectLedger / ContextPackV2 · EKC `ir.json` 暖机与 `--refresh` · Web 短读/控制面与 execute 槽隔离。CLI · wasm · ext **2.1.5**。
```bash
git checkout v2.1.5 && cargo build --release
marqdo ext add web # CDN / Releases → 2.1.5
```
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——工作台协议与 Agent 运行时合同,不新增 Markdown 标记。
### Added
- **ResourceView v1**:有界 JSON/CSV 渲染;PDF/image `blob_ref`;`locator.page` / 行定位;CSV `text` 供 TablePreview。
- **Agent 合同**:ToolSpec 注册与 authorize-before-call;CheckpointV2 原子 resume;AgentErrorV1;输出通道;ContextPackV2;EffectLedger(含 mutating `run_tool` 水印)。
- **Workbench fixtures/schemas**:`tests/workbench_contracts` 协议金样例。
- **EKC `ir.json` 快照**:`marqdo knowledge` 写入 `.marqdo/ekc/graph/ir.json`;查询命令暖机热加载,免全量重编译。
- **`--refresh`**:`knowledge preflight` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify` 可强制重编译。
### Fixed
- **工程预检热路径**:`knowledge preflight`(及 find/reuse 等)默认不再每次 `ensure_compiled` 全量 compile,修复聊天「工程预检」墙钟过长。
- **Web 槽隔离**:`short`/`read`/`control` 不再填满 execute 槽;disconnect≠cancel。
- **CSV ResourceView**:去掉尾部空行伪影。
### Changed
- 查询类 knowledge CLI:**缺投影才 compile**;CI / 源变更请先 `marqdo knowledge` 或 `--refresh`。
- CLI / wasm / `ext/VERSION` **同步 2.1.5**。
## v2.1.4 — 2026-10-26
### Highlights
**默认隔离 HTTP execute(ADR 0009)**:`class=execute` / `sse-live` / `stream:true` 经 Supervisor worker 池(`marqdo run --call-lib-path`),父进程不再 `CallLibPath` 占 `INVOKE_LOCK`;短读 / 未声明非流式仍 `legacy_serial`(ADR 0008)。`/_runtime/*` 控制面;`runtime.isolated_execution=1`;MR-01 双 60s 假 SSE + 短读金样例。CLI · wasm · ext **2.1.4**。
```bash
git checkout v2.1.4 && cargo build --release
marqdo ext add web # CDN / Releases → 2.1.4
```
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——隔离运行时与 Web execute 路径,不新增 Markdown 标记。
### Added
- **默认隔离 execute(ADR 0009)**:HTTP `execute` / `sse-live` / `stream:true` 经 Supervisor worker 池(`marqdo run --call-lib-path`),父进程不再 `CallLibPath` 占 `INVOKE_LOCK`;可选 route `class`;`/_runtime/*` 控制面;`runtime.isolated_execution=1`。
- **MR-01 金样例**:`tests/isolated_execute_mr01.rs` + `tests/ext/isolated-execute-site/`(双 60s 假 SSE + 短读并行;槽满拒绝);接入 `executable-knowledge` workflow。
- **Worker CLI**:`marqdo run --call-lib-path` / `--fs-root` / `--args-json` / `--emit-result`;host `runtime` admit/dispatch/cancel/events。
### Fixed
### Changed
- **compile 1000 门禁**:executable-knowledge / workbench 路径恢复与能力探测诚实(isolated 默认开启)。
- CLI / wasm / `ext/VERSION` **同步 2.1.4**。
## v2.1.3 — 2026-10-25
### Highlights
**知识工作台运行时合同(M00–M06)**:`ModelSelectionV1` / `RunContextV1` / `ModelCallUsageV1` / `DocumentViewV1` / locator / snapshot;严格 selection;usage null≠0;`view document` 只读嵌入;LLM messages + cancel;agent.step selection 继承假模型 e2e;USTC 兼容 live smoke(env 注入)。CLI · wasm · ext **2.1.3**。设计证据仍为 Partial(原生适配器 unavailable;完整宿主 F12 留给应用)。
```bash
git checkout v2.1.3 && cargo build --release
marqdo ext add llm # CDN / Releases → 2.1.3
```
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)——工作台合同与 View/LLM/Agent 扩展面,不新增 Markdown 标记。
### Added
- **Workbench M00–M06**:capabilities / selection / RunContext / usage / DocumentView / locator / SnapshotManifest;`tests/workbench_contracts`(含 F02 agent.step+resume、F14 并发);`marqdo view document --out` 只读 HTML 嵌入。
- **LLM**:`messages=` / `selection=` / `strict_selection`;cancel token;reasoning_content 回退;双端点隔离门禁。
- **Live**:`tests/workbench_live`(`OPENAI_*` env only;`MARQDO_EXT` 指向仓内 `ext/`)。
- **Agent skeleton**:子工作簿禁 `llm.llm`,从 env selection `llm.create`。
### Fixed
- **`llm.ask` 升参**:hoist `p` 避免缺参 `missing argument for parameter p`;避免 `~/.marqdo/ext` 陈旧包遮蔽仓内 `ext/`(测试强制 `MARQDO_EXT`)。
### Changed
- CLI / wasm / `ext/VERSION` **同步 2.1.3**。
## v2.0.0 — 2026-10-22
### Highlights
**遮蔽语法(Occlusion)落地**:`[描述](实现)` —— 方括号是给人读的描述(**永不执行**),圆括号是**唯一执行体**。配套 `()` 内调用、`access` 取元、`遍历` 遮蔽循环、`labels` 两级检索与债务棘轮、`migrate labels` 迁移;`view` 把描述渲染为正文、实现渲染为代码片、空载荷给「桩」徽章。全仓 **80 个语料文件 / 256 处取元 / 23 处循环** 已迁移(M7),语义零漂移。
```bash
git checkout v2.0.0 && cargo build --release
marqdo ext add web # CDN → 2.0.0
```
**核心表面 Δ(Core surface Δ)**:**无增删**(仍 19 个构造)—— 遮蔽是既有 `[键](集合)` 与 `- [项](集合)` 形状在 `markup: occlusion` 文件中的**第二种读法**,默认 `classic` 语义不变;`access` 是宿主函数(id 212),不是新标记。
### Added
- **M2 遮蔽语法**:`[描述](实现)`;`[]` 为自由文本、永不执行,`()` 为唯一执行体;支持嵌套;空载荷 `()` 值为 `None`(桩)。frontmatter `markup: occlusion` 按文件启用,`MARQDO_MARKUP=occlusion` 可作进程默认。
- **M1 `()` 内调用**:`加(1)` / `加(1, 2)` / `加(加(1 2), 10)` / `加一 号(31)`(callee 可含空格,解决 D8)/ `txt.str_trim(" x ")`;`)` 是参数终止符,逗号可选,支持嵌套;括号形参数按表达式解析,空格形(`> f k=v`)仍按文本。
- **M3 `access` 与遮蔽循环**:新增宿主函数 `access(集合, 键)`(别名 `取` / `取值`),与旧取元逐字等价;`- [描述](遍历 集合 为 变量)` 遮蔽循环,接受 `遍历`/`for` 与 `为`/`as`/`in`。
- **M2.5 / M4 遮蔽诊断**:`label.missing`(空描述,error)、`label.empty_payload`(空载荷,warning)、`label.ref_dangling`(描述里的反引号实体不可解析,error);由 `marqdo check` 一并输出。
- **M5 隐式遮蔽**:`marqdo check --implicit-labels` 把 `>` 调用上方的叙述当作描述(默认关闭,不改变既有输出)。
- **M6 T1 会话内陈旧检测**:MLSP `repair_apply` 前后对照 payload 并返回变更的遮蔽点;新增 `session.summary` 会话末一次性汇总。
- **M7 迁移与版本门**:frontmatter `markup:` 按文件切换解析模式(同进程可混载 classic / occlusion,imports 亦然);`marqdo migrate labels`(多路径、`--write`、`--json`)把 `[键](集合)` 改写为 `[键](access(集合, "键"))`、`- [项](集合)` 改写为遍历形。
- **M8 债务棘轮与呈现**:`marqdo labels --baseline FILE` 记欠据、`--fail-on-increase` 只许降不许升;`view` 浏览 / 卡片 / 静态导出一致呈现遮蔽:描述为正文、实现为代码片、空载荷「桩」徽章。
- **M9 两级词表检索**:`marqdo labels`(默认 `pending` 口径 / `--grep` 自定义词 / `--group` / `--also-builtin` / `--count` / `--json`,支持多路径);MLSP `labels.search`;兼容文档写法 `labels pending` / `labels search`。
- **M10 工程化落点**:`ext/ai` 提示词加入「接不了就申报」;README「工程习惯」;空载荷一律 warning。
- **示例与教程**:`examples/syntax-tour` 一页跑通全部现行语法;`examples/oa2026-showcase`;`doc/tutorial/15-常见陷阱.md`(D1–D10 实测)。
### Fixed
- **D9 未闭合引号**:不再静默吞掉后续行——分类层与解析层双层修复,直接报错并给出原始行。
- **`加(31)`**:曾被解析成 `unknown function 加(31`(末个位置实参吞掉 `)`)。
- **view 解析模式回归**:带 `markup: occlusion` 的文档在 `view` 结构区报 `expected ')' after link-index collection`;新增 `load::parse_source_auto` 统一五处解析点。
### Changed
- **HostFn 单表**:五张分派表合一为 `HOST_FN_TABLE`(`src/host/dispatch.rs` **−404 行**),203 项逐字节一致,行为零变化。
- **插件 ABI 共享 crate**:新增 `marqdo-plugin-sdk`,5 个原生插件共用同一份 ABI 前言;**ABI 不变**(`include/marqdo_abi.h` / 符号与布局不变)。
- **精简**:删除归档的 Rust web 插件 `plugins/web-rust-archive/`(14,235 行,非 workspace 成员,已由 Go `libweb` 取代);删除无调用点死代码,收拢 `as_text` 18 处重复、catalog 助手与 view 路由 34 臂,AST 遍历器合流。
- **语料迁移(M7)**:`public/` `ext/` `tests/` `examples/` `doc/` 等语料加 `markup: occlusion`,改写 **80 个语料文件 / 256 处取元 / 23 处循环**;新增 `tests/ratchet` 锁定标签债务。
- **文档**:遮蔽语法总纲 + M0–M10 变更记录、标签新鲜度 / 修复回路、函数作为值 6 篇评估、代码体量审计;`doc/design/code-volume-audit.md` 记 53k 行构成。
## v2.1.0 — 2026-10-23
### Highlights
**文件级可执行知识语义**:标准库、扩展库、示例与公开文档全部采用显式 `markup: occlusion`;`[描述](实现)` 成为默认链接语义,`access` 与 `遍历` 承担原有取元与循环职责。迁移工具可离线证明语法形状等价,Tree 与 Bytecode 均完成全量回归。
```bash
git checkout v2.1.0 && cargo build --release
marqdo ext add web
```
**核心表面 Δ**:默认链接语义从 Classic 切换到 Occlusion。未迁移的旧 `[键](集合)` 仅可用 `markup: classic` 或一个版本周期内的 `marqdo run --legacy-markup` / `check --legacy-markup` 执行。
### Added
- **文件级新语义迁移**:`marqdo migrate labels --mark` 可把整个库/目录迁移到显式 `markup: occlusion`,即使文件没有旧式索引也不再依赖进程默认值。迁移验证为语法级、无导入解析依赖,并在写入前比较 Classic 与 Occlusion AST 形状。
- **显式过渡入口**:`marqdo run --legacy-markup` 与 `marqdo check --legacy-markup` 可在一个版本周期内审阅未迁移的旧文件;环境变量不再改变语法。
### Fixed
- 标准库、扩展库、示例、公开文档与可解析测试夹具迁移为文件级 Occlusion;旧的 `[键](集合)` 和 `- [项](集合)` 分别改为 `access` 与 `遍历`。
### Changed
- 未标注源码默认采用 Occlusion。Classic 仅能通过明确的 frontmatter 或 `--legacy-markup` 进入,避免同一文档因进程配置而静默改变含义。
## Unreleased
### Added
@@ -8,6 +500,388 @@
### Changed
## v2.1.2 — 2026-10-24
### Highlights
**可执行知识生产消费链 + View 阅读体验发版门槛**:证据摘要进闭包/句柄;`artifact.verify` / `knowledge adjudicate` 结构化裁决;`artifact.reuse_execute` 与 `agent_eng_bind_execute` / `publish_gate` 实际复用(非 n-gram);`document.extract` 文本/Markdown + PDF/OCR 显式失败;View `KnowledgePresentation`、说明锚点、SSE `page_token` 过期包拒绝;上传 `max_bytes`;门禁 45 项(含 100/1000 单元)。CLI · wasm · ext **2.1.2**。
```bash
git checkout v2.1.2 && cargo build --release
marqdo ext add web
cargo test --offline --locked --test executable_knowledge
```
**核心表面 Δ(Core surface Δ)**:**无增删关键词**——语义/MLSP/View/Agent 宿主扩展;不改变默认 Occlusion 链接读法与表几何。
### Added
- **证据与闭包(F0/M02)**:来源 digests 进入 artifact/evidence/closure;business handle 改/删来源失效;锚点/可读性诊断。
- **验证裁决(F0/M03)**:`artifact.verify` 结构化 `may_bind` / `may_publish`;policy 枚举;`knowledge adjudicate`;CLI `--fail`。
- **语法 Skill(F0/M05)**:CORE SYNTAX 置顶;`migration-classic.md`;`skill_core_card` 与预算截断防护。
- **绑定执行(F1/M04)**:`artifact.reuse_execute`;`agent_eng_bind_execute` + `eng_publish_gate`(`candidate_only` / product gate);host_query `mlsp`;`tests/ext/agent-eng-bind-gate.mq.md`。
- **发布与来源(F2/M06–M07)**:统一 `EXCLUDED_DIRS`;`publish_manifest.json`;`function_sources` 函数级来源覆盖。
- **文档提取(F3/M01)**:`document.extract` DocumentSource→ExtractedDocument;PDF/DOCX/OCR 显式 `failed`;超限截断 `partial`;Web 上传 `MaxBytesReader` / `LimitReader`。
- **View V0–V3(子集)**:正文优先;no-exec;`KnowledgePresentation`(`semantic_generation` / `page_token` / `local_deps`);SSE 过期包拒绝与帧选择保留;print/响应式;1000 单元 compile smoke。
- **故事门禁(M08)**:建库→复用→来源变更失效→修复重绑。
### Fixed
- View 说明链接 raw-string 截断;skill_brief / CORE SYNTAX 预算不被冲突旧规则吃掉。
- 上传体积限制在 multipart 解析前生效(不再只靠内存 form 预算)。
### Changed
- CLI / wasm / `ext/VERSION` **同步 2.1.2**。
- `tests/executable_knowledge` 门禁扩至 45 项;README 切片进度表与发版子集对齐。
## v2.1.1 — 2026-10-23
### Highlights
**可执行知识主链落地(S0–S6)**:BoundCall 双后端共享解析、正文 NarrativeRef、来源/适用期、digest 保护补丁与纯表达式提取、整代 `CURRENT` 投影与闭包摘要;订单发票示例双后端输出 `113`;离线门禁含 100 单元语料与 CLI 冒烟。
```bash
git checkout v2.1.1 && cargo build --release
marqdo ext add web
marqdo run examples/executable-knowledge/docs/invoice-answer.mq.md
```
**核心表面 Δ**:**无增删关键词**——同模块 `Type.member` 纳入 BoundCall;语义投影新增 `bound_calls` / `dynamic_calls` / `hashes.closure` / NarrativeRef 步骤;不改变默认 Occlusion 链接读法。
### Added
- **BoundCall / DynamicCall**:`sema::bind::resolve_for_exec`;Tree 与 Bytecode 静态路径对齐;`bound_calls.json` / `dynamic_calls.json`;同模块定义树路径绑定。
- **NarrativeRef**:注释行 Markdown 链接 → `narrate` / `navigation` 步骤;围栏与行内代码不计步骤。
- **来源与适用性**:frontmatter `sources` / `valid_until` → `evidence=sourced|expired|missing_source`;`artifact.bind policy=business`。
- **局部编辑与提取**:MLSP `artifact.patch`(digest + wording 回滚);`artifact.extract_pure` 纯表达式预览。
- **整代与闭包**:`generations/<id>/` + `CURRENT`;`hashes.closure` 随依赖变化;锁报告 `classes`。
- **门禁**:`tests/executable_knowledge`(含 100 单元);CI `.github/workflows/executable-knowledge.yml`;项目扫描 depth/size/count 上限。
- **示例**:`examples/executable-knowledge` 发票含税链可运行;负知识文档。
### Fixed
- Bytecode 裸名解析不再跨 import scope 误连同名函数;同模块 `Type.member` 写入 path_index 供兄弟调用。
### Changed
- Agent / reuse 发现结果标记 `discovery_only` + `bind_required` / `bind_targets`,不可把打分结果直接当可执行目标。
## v1.5.2 — 2026-10-18
### Highlights
**外联 v3 P0/P1**:session eval 支持 raw stdin(Python/Node 持久内核);每 cell 独立 stdin 与 Interrupt;plan generation/add/remove/value API;snapshot export/import/replay;`view capture` / `view output --snapshot` 捕获实时快照;显式 Persist 按钮。CLI · wasm · ext **1.5.2**。
```bash
git checkout v1.5.2 && cargo build --release
marqdo ext add web # CDN → 1.5.2
```
**核心表面 Δ(Core surface Δ)**:**无增删**——外联 v3 扩展 `lib/foreign` 库 API;不改 MQ 关键词 / 表几何。
### Added
- **raw stdin + 每 cell 输入**:session eval 支持 raw stdin;`foreign.session inputs=` 每 cell 独立 stdin;view 增加每卡 stdin 字段与 Interrupt 按钮。
- **plan API**:plan generation/add/remove/value;运行时 plan 更新与 generation。
- **snapshot**:snapshot export/import/replay;`view capture` / `view output --snapshot` 捕获 live 快照用于静态导出。
- **显式 Persist**:Persist 按钮 + `/api/session/cell/persist`。
- **嵌套 plan 边界**:显式 persist 与嵌套 plan 边界;foreign 拒绝嵌套 view plans。
### Fixed
- **`session_list` arity**:保持空 arity。
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.5.2**。
## v1.5.1 — 2026-10-18
### Highlights
**view 静态/动态统一 + 外联值传递**:静态导出与 live view 共用同一套 `foreign_doc` 执行路径;构建时实际运行代码单元并注入 stdout;`foreign.session` 可把 Marqdo 值传入多内核会话;cell stdin 支持 live/static/持久内核三种模式。CLI · wasm · ext **1.5.1**。
```bash
git checkout v1.5.1 && cargo build --release
marqdo ext add web # CDN → 1.5.1
```
**核心表面 Δ(Core surface Δ)**:**无增删**——view 执行路径统一 + 外联值传递;不改 MQ 关键词 / 表几何。
### Added
- **外联值传递**:`foreign.session kernels= cells=` 可把 Marqdo 值传入多内核 view 会话;`view` 只消费 `会话` 绑定,不再识别 `内核表` / `会话表` 保留名。
- **Cell stdin**:view 增加 `Cell stdin / input` 输入框;Run/Step/Run All 都会传给外联 cells;无状态 cell 使用 raw stdin,持久内核使用 `marqdo_input`;静态导出使用 frontmatter `stdin` 作为构建时输入。
- **静态导出真实执行**:构建时实际执行代码单元并把 stdout/stderr 注入代码卡;静态示例通过代码 fallback 或 frontmatter `stdin` 提供输入。
- **可运行外联写回示例**:新增 `examples/foreign-writeback/index.mq.md`,用 `foreign.run` + `writeback.record` 将结果写入 `.mq.md` 的 keyed 槽位。
- **写回块分组与主题**:view 对写回块按目标分组并统一主题样式。
### Fixed
- **code 卡控制恢复**:恢复每个代码卡的内核切换下拉与 Clean 按钮;Clean 清除单个 cell 输出/记录,不重启内核。
- **导入函数返回锚定**:导入函数的返回值锚定在调用位置。
- **静态导出自包含**:静态示例不再依赖空 stdin 或外部内核状态。
- **Execution 输出清除**:view 清除 Execution 输出从 view 表面。
- **文档表不再变 call chips**:view 不再把文档表转为 call chips。
- **写回表标签**:写回表标签保持为行内代码。
### Changed
- **静态/动态统一执行路径**:static 与 live cells 使用同一 `foreign_doc` `run_all` 路径;移除 `In []` / `Out []` 与 Notebook 品牌。
- **静态按钮行为**:静态页面执行按钮点击显示"静态页面无法真实执行",不伪造成功。
- **低层会话评估可见**:文档展示低层 session evaluation 为代码围栏。
- CLI / wasm / `ext/VERSION` **同步 1.5.1**。
## v1.5.0 — 2026-10-18
### Highlights
**外联 v2 / 文档原生 Notebook**:`lib/foreign` 从“运行一段代码”升级为完整外联内核:结构化 `invoke` 记录、JSON 进出的 `call` / `call_many`、并行扇出、Python/Node 持久内核、显式状态桥,以及用绑定表声明的 Notebook 单元。`view` 增加 cell 单步、Run All、内核切换、journal、状态面板、浅/深主题与可调高度代码区;高对比度 token 修复了代码和 STRUCTURE 文字与背景区分度不足的问题。CLI · wasm · ext **1.5.0**。
```bash
git checkout v1.5.0 && cargo build --release
```
**核心表面 Δ(Core surface Δ)**:**无增删**——外联 v2 只扩展 `lib/foreign` 的库 API;Notebook 的 `内核表` / `会话表` 是既有绑定表;没有新增 Markdown 标记。
### Added
- **用户静态站(外联 / OKF / EKC)**:新增中英双语 `features/19-foreign-view-cells` 与 `features/20-okf-ekc`,重写 `stdlib/foreign`,首页加入「一份文件三个面」、外联 Python 运行、Notebook 表、OKF/EKC 与 preflight 说明。
- **`lib/foreign` F0/F1**:`invoke` 结构化记录(`ok`/`code`/`stdout`/`stderr`/`ms`/`timed_out`/`truncated`/`result`);`run`/`run_lang` 新增 `env`/`cwd`/`timeout`/`args`/`max_output`;15 个语言预设;`probe`/`register`/`unset`/`load_config`;`.marqdo/foreign.toml`。
- **`lib/foreign` F2**:JSON 进 / JSON 出 `call`;并行 `run_many` / `call_many`(有序、单项隔离、并发上限);`invoke` 的 `input` / `output` / `result` / `result_error`。
- **`lib/foreign` F3/F3.5**:Python / Node 持久会话 `session_open` / `session_eval` / `session_close` / `session_list`;状态桥 `session_set` / `session_get` / `session_names`;会话超时即杀、崩溃隔离、drop 清理。
- **Notebook D1/D2**:`内核表` / `会话表` 文档原生语法;`DocumentSession`(cell index / 命名内核 / journal / value store);view Notebook 工具栏(Run All / Restart & Run All / Step / State / Journal / Reload)、状态徽标、内核下拉、Push/Pull 状态表单;`POST /api/session/*`。
- **Notebook D3**:`reload` 重新解析并保留内核,源码变更的 cell 标为 `dirty`;Journal/Reload/Debug 按钮;Debug 打开同一 view 服务的语句级单步页(`/debug` + `/api/debug/*`);状态桥 Push/Pull。
- **安全与健壮性**:所有外联入口检查 `exec` 能力;有界 stdout/stderr 读取与截断标记;stdin 写线程;Unix 进程组 / Windows `taskkill /T` 超时清理;shell-like argv 切分。
### Fixed
- **view 文档表面与标注 chip**:把旧 view 的 `--ink` / `--fill` / `--line` 等 token 映射到当前主题,修复 STRUCTURE 中 `main`、`内核表 =`、函数名和 annot-chip 深色文字/白色卡片与暗色背景不一致的问题。
- **view 代码对比度**:移除会互相覆盖的 highlight.js 深/浅两套外链样式,改用内置高对比 token 变量;深色代码正文 `#f0f0f0` on `#1e1e1e`(14.6:1),浅色 `#24292f` on `#f6f8fa`(13.8:1);关键词/字符串/注释均使用可读的对比色。
- **view 反向代理兼容**:Notebook / Debug 的 API 与 Debug URL 改为相对路径,可在 `/marqdo-view/...` 路径前缀下工作,便于 Docker 内通过 DSH 同源预览。
- **分支内共同局部变量**:if/else 各臂都赋值的局部变量不再被误提升为必选形参;修复 `# llm` 构造器无端要求 `key`,恢复 agent/llm/ext 全量测试。新增 `branch_else_common_local_is_not_a_param` 回归测试。
- **外联临时脚本路径**:入口目录为相对路径时,脚本参数现在使用绝对路径,避免 `tests/lib/tests/lib/...` 双拼接。
- **外联失败可观测**:解释器不存在时进入 `invoke` 记录,`run` 仍报错;view 显示 stderr / exit / ms。
### Changed
- **Notebook view 视觉重做**:采用 VS Code Dark 的扁平色板与 Jupyter 的 cell 组织:单一深色底、明确 surface/border 层级、`In [n]` / `Out [ ]` 提示、顶部 cell 工具栏、无渐变/无重阴影、暗色代码区与一致的字号/间距;保留并统一原始左侧文件导航、右侧 Functions/Variables 栏与 Execution/Source 区块;支持深色/浅色主题切换(localStorage 记忆)与代码区、输出区纵向拖拽调整高度。
- **`langs`** 现在返回「预设 ∪ 注册 ∪ 配置」的已知语言(原集合是子集)。
- 大输出从 `Err` 改为「截断 + `truncated=true`」;`subtask` 外联输出同步采用该语义。
## v1.4.6 — 2026-10-16
### Highlights
**裸自增升参**:粗体首次赋值的左值按设计 §8.2 视为声明。`**n = n + 1**` 在没有反引号提及时也会把 `n` 升成必选形参;缺参报 `missing argument for parameter`,不再是函数体内的 `undefined variable`。纯局部赋值(`**score = 1**`)与循环变量不升参。CLI · wasm **1.4.6**(扩展包仍为 **1.4.5**)。
```bash
git checkout v1.4.6 && cargo build --release
```
**核心表面 Δ(Core surface Δ)**:**无增删**——升参与 §8.2 对齐(赋值左值声明);不改 MQ 关键词 / 表几何。
### Fixed
- **升参**:`merge_inferred_params` 纳入首次粗体赋值左值。右值在绑定前读取同名(`n = n + 1`)时,该名成为必选推断形参。
### Changed
- CLI / wasm SemVer **1.4.6**。扩展包保持 **1.4.5**。
## v1.4.5 — 2026-10-16
### Highlights
**Streamable HTTP MCP + web `/v1` 鉴权硬化**:`agent_mcp_serve` 支持 `transport=http`(MCP Streamable HTTP 2025-03-26);web invoke 注入 `Authorization` / `X-Api-Key`,`ok=false`+`unauthorized` → HTTP 401;`ext/ai` openai/agent 字段访问改 `json.get`,消除 footnote 硬崩。CLI · Ext · wasm **1.4.5**。
```bash
git checkout v1.4.5 && cargo build --release
cargo build --release -p marqdo_plugin_agent
# HTTP MCP:
# QDAGENT_MCP_TRANSPORT=http marqdo run cli/求道-mcp.mq.md
marqdo ext add agent # CDN → 1.4.5
```
**核心表面 Δ(Core surface Δ)**:**新增** MCP Streamable HTTP 传输(`transport=http|streamable-http`);web invoke 契约扩展(header 注入 · 401);**无** MQ 关键词 / 表几何变更。
### Added
- **`agent_mcp_serve` Streamable HTTP**:`transport=http` · `host`/`port`/`path`;POST JSON-RPC + 可选 GET SSE;`Mcp-Session-Id`。facade:`ext/ai/agent` `## serve`。
### Fixed
- **web invoke**:`Authorization` / `X-Api-Key` 注入 payload;`jsonWrapInvokeValue` 对 `unauthorized` 返回 401;`{sse}` 自动 event-stream。
- **`ext/ai/llm/openai` · `agent` · `llm`**:字段访问改 `json.get` / `at`,避免 `[field](x)` 在非 map 上硬崩。
- **explore workbook**:子任务 `stream=False`(网关 SSE 524 更稳)。
### Changed
- CLI / Ext / wasm SemVer **1.4.5**。
- 设计:[doc/design/ext-web-artifact.md](doc/design/ext-web-artifact.md)(sse / bearer)。
## v1.4.4 — 2026-10-16
### Highlights
**LLM 传输软失败 + `ext/ai` 表优先重构**:上游连接拒绝/超时/HTTP≠200 时,Runtime 返回结构化 `finish|status=error`(不再硬中断 VM);`agent` / `智能体` / `llm/openai` 去掉 `json.set`/`json.append` 袋胶水。含 CLI host · `plugins/llm` · Ext pack **1.4.4**。
```bash
git checkout v1.4.4 && cargo build --release
cargo build --release -p marqdo_plugin_llm
marqdo run tests/ext/agent-llm-transport-soft.mq.md
marqdo ext add agent # CDN → 1.4.4
```
**核心表面 Δ(Core surface Δ)**:**无增删**——HTTP 宿主软失败契约 + Extension 风格重构;不改 MQ 关键词 / 表几何。
### Fixed
- **LLM / Agent 传输软失败**:`host_http_post` / SSE · `plugins/llm` · `ext/ai/llm/openai` 结构化 `finish=error`;`agent.step` / `plan` / `run` 收成 `status=error`。金样 `tests/ext/agent-llm-transport-soft.mq.md`。说明:[doc/research/agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)。
- **`agent.run`**:`cache == "soft-hit"` 引号比较(裸 `soft-hit` 曾被解析为减法)。
### Changed
- **`ext/ai` 去 json 胶水**:结果 map / 事件用 GFM 表 + `table.put` / `table.append` / `table.empty_*`。SKILL 正面示例:`.cursor/skills/marqdo-dev` §2 · `marqdo/examples.md` §6e。
- CLI / Ext / wasm SemVer **1.4.4**。
## Ext pack v1.4.3 — 2026-10-16
### Highlights
**Agent cold EFI / resolve 硬崩修复(CLI 仍为 v1.4.2)**:qdagent 接通 `agent.run` 时空 OKF 触发 `unknown function preflight` 与 `missing map key llm_free`。本包修复 `ext/ai/agent` facade 与 `agent` native;金样 `tests/ext/agent-run-cold-efi.mq.md`。说明:[`doc/research/agent-run-efi-resolve-bugs-2026-10.md`](doc/research/agent-run-efi-resolve-bugs-2026-10.md)。
```bash
marqdo ext add agent # CDN latest → 1.4.3
# 或:MARQDO_EXT_VERSION=1.4.3 marqdo ext add agent
```
**核心表面 Δ(Core surface Δ)**:**无增删**——仅 Extension / Agent Runtime 契约修补。
### Fixed
- **`agent.run`**:`efi=True` 改为 `` `self`.preflight ``(不再裸调全局 `preflight`)。
- **`agent_resolve` miss**:返回字段对齐命中路径,含 `llm_free: false`;facade 对 `llm_free` / route 字段改用 `json.get`。
### Changed
- 扩展包 SemVer **1.4.3**(`ext/VERSION`);与 CLI **v1.4.2** 可独立安装。
## v1.4.2 — 2026-10-16
### Highlights
**Agent/LLM 优化 O1–O5**:`ext/ai/sandbox` CoW 试跑接入 `agent.trial` / `run sandbox=`(默认关);promote 强制 sandbox proof;步骤路由 `step_route` + EFI preflight + `usage`/`token_cost`;风格 lint 与 `sandbox.report`;技能 `quarantine` 与离线 standing/policy 优化脚本。表优先、少 json 胶水。路线:[ext-ai-optimize.md](doc/roadmap/ext-ai-optimize.md)。
```bash
git checkout v1.4.2 && cargo build --release
cargo build --release -p marqdo_plugin_agent
marqdo run tests/ext/agent-sandbox-optin.mq.md
marqdo run examples/agent-sandbox-okf/index.mq.md
# Ubuntu: sudo apt update && sudo apt install marqdo
marqdo ext add agent # CDN latest → 1.4.2
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Extension / Agent Runtime**(`ext/ai` 沙盒与晋升闸门),不触碰语言标记。
### Added
- **`ext/ai/sandbox`**:CoW 工作区(`open` / `run` / `diff` / `commit` / `discard` / `inspect` / `profile` / `report`);经 `plugins/agent` `sandbox_*` → `host_query`;默认拒 `plugin`/`exec`/`net`。
- **O1**:`agent.trial` · `run`/`step` `sandbox=` · 中文 `试跑`/`沙盒=` · 示例 `examples/agent-sandbox-okf/` · 金样 `agent-sandbox-optin`。
- **O2**:`agent_kb_promote` 默认 sandbox proof;OKF `applies_when`/`fixtures`/`sandbox_profile`/`proof`;harness Skill Lift。
- **O3**:`agent.step_route` · `ext/ai/policies/step-route.mq.md` · `run efi=`(缺工程知识时软放行)· 结果 `usage`/`token_cost`。
- **O4**:`scripts/mq-style-lint.sh` · `sandbox.report` markdown 审阅面。
- **O5**:`agent_kb_quarantine` / `agent.quarantine` · `scripts/optimize-standing-policy.sh`。
### Fixed
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.4.2**。
- Skill:强制表/链接取元、禁同文件混 EN/ZH、点名 sandbox 试跑习惯。
## v1.4.1 — 2026-10-15
### Highlights
**view 叙述标注连线**:Browse / `view output` 中 underline→chip 改为 SVG 正交连线(描述底边中点 → 轨道 → 短竖线 → 值顶边中点);同跨度多帧 chip 共用 annot id;可见 chip 按锚点 L→R;帧切换后重算密度。设计:[view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)。
```bash
git checkout v1.4.1 && cargo build --release
marqdo view public/00-welcome.mq.md --no-open
marqdo view output public -o /tmp/mq-public
# Ubuntu: sudo apt update && sudo apt install marqdo
marqdo ext add web # CDN latest → 1.4.1
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(view 标注几何与帧 chip 对齐),不触碰语言标记。
### Added
- 设计缺口文档 [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md):叙述 fence 卡、帧感知 chip 密度、L-leader 几何约定。
### Fixed
- view L-leader:id 与 mark 错配、chip 逆序交叉、border 无色变黑碎段、横线穿过 chip 文字;现为 mid→mid SVG path。
- 叙述 fence / 代码卡单层渲染;静态页隐藏 Run;主文函数引用 call chip + leader。
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.4.1**。
## v1.4.0 — 2026-10-15
### Highlights
**叙述统一 + 公式 meta + 图片自写回**:块公式 `% marqdo: var=`;分支/循环体与函数体同权叙述;foreach 中英糖;自写回图片 `![marqdo-out](…)`(扩展名校验)与 view/静态站同源标记;view 展示推断形参实值;欢迎页迁到 v0.3 叙述面。
```bash
git checkout v1.4.0 && cargo build --release
marqdo run tests/markup-v03/formula-meta-var.mq.md
marqdo run tests/markup-v03/foreach-narrative.mq.md
marqdo view tests/view/document-annot-demo.mq.md --no-open
# Ubuntu: sudo apt update && sudo apt install marqdo
marqdo ext add web # CDN latest → 1.4.0
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。Language 层在既有 `formula` / `branch-list` / `loop-list` 上扩展语义(块公式 TeX 注释绑定、臂/循环体叙述、foreach 糖);Runtime:自写回图片形态 + view 推断形参展示。设计:[fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.md)。
### Added
- **块公式 meta 绑定**:`$$` 内 `% marqdo: var=<ident>`(剥离后解析;可无空 RHS);金样 `tests/markup-v03/formula-meta-var.mq.md`。
- **控制流叙述统一**:臂/循环体 `parse_indented_body` 与函数体同权;分支条件行支持叙述前缀与行内 `**…**`;foreach 糖 `- 对…的每一项…` / `- for each … in …`。
- **图片自写回**:路径/URL 且扩展名合法 → `![marqdo-out](…)`;文本仍 HTML 注释;view / `view output` 同源样式卡与 `<img>`。
- **view 推断形参实值**:Browse 展示 body-inferred 参数绑定值;欢迎页 EN/ZH 迁 v0.3 叙述。
### Fixed
- `ext/net/url.encode`:经 `lib/net` 包装,不再直接 `host_*`(金样 `ext_mq_md_never_calls_host`)。
- PPA 源包:`ppa-build-source.sh` 本地 `.orig` 已在 build-area 时跳过重复 `cp`。
- view:嵌套调用欢迎页与公式/代码卡渲染清理。
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.4.0**;词法评论段遇有序分支臂 / 循环头 / 图片自写回标记时断开,避免吞掉控制流行。
## v1.3.3 — 2026-10-15
### Highlights
**view 文档面 Structure**:Browse 保真叙述与标记面(变量/语句/返回无源码定界符);表/循环/分支结构块;语句后绑定值、分支命中臂、函数多调用与循环迭代下拉(默认末帧);`#mq-view-trace` AI JSON。静态 `marqdo view output` 与 live view **同源渲染**(含用户站 `public/` → gh-pages)。
```bash
git checkout v1.3.3 && cargo build --release
marqdo view tests/view/document-annot-demo.mq.md --no-open
marqdo view output public -o public
# Ubuntu: sudo apt update && sudo apt install marqdo
marqdo ext add web # CDN latest → 1.3.3
```
**核心表面 Δ(Core surface Δ)**:**无增删**——19 个核心构造不变。本版为 **Runtime / Tooling**(view 文档面 + 帧选择),不触碰语言标记。
### Added
- **Browse Structure 文档面**(`src/view/document.rs` · `annot.rs`):叙述保真、标记面、GFM 表 / `doc-loop` / `doc-branch`、CSS L-leader 标注带。
- **StmtEvent / CallFrame / LoopFrame** 静默轨迹:post-stmt 绑定、分支 `call_id`、循环 `分 = 分数表[i] · value`;调用/迭代 picker(源码常显,只滤 chip)。
- **`ViewExecutionReport`** JSON(`#mq-view-trace` · `/api/view-trace` · SSE `trace_json`)。
- 设计:[view-document-annotations.md](doc/design/view-document-annotations.md) · [view-execution-trace.md](doc/design/view-execution-trace.md) · [view-frame-selection.md](doc/design/view-frame-selection.md);样例 `tests/view/document-annot-demo.mq.md`。
### Fixed
- 多调用分支 taken 混叠;调用切换误藏未执行臂源码;循环头重复 chip。
### Changed
- CLI / wasm / `ext/VERSION` **同步 1.3.3**;静态导出与 live view 共用 `build_file_view` → 文档面。
## Ext pack v1.3.2 — 2026-10-13
### Highlights
@@ -399,6 +1273,8 @@ marqdo run tests/markup-v03/inc-prose.mq.md
### Highlights
历史说明(2026-11-10):本节的 anlian-mq 是当时发布内容记录,现已移出仓库,旧启动命令不适用于当前工作树。当前完整站点见 examples/web-site 与 examples/web-site-zh。
**Go `libweb` 默认落地(W-G0–W-G14)**:官方网页原生插件改为 Go C ABI;CLI / gold / Release 走 `scripts/build-web-plugin.sh`;Rust 源码归档。另附 **anlian-mq** 验收站与表单插槽 / `MARQDO_EXT` 提示修复。
```bash
Generated
+205 -18
View File
@@ -143,9 +143,9 @@ dependencies = [
[[package]]
name = "bumpalo"
version = "3.20.3"
version = "3.20.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"
checksum = "87a0cf66fd1eb2fb7b822cb78370d82303750809bc6ba855f3f58e517d3238db"
[[package]]
name = "byteorder"
@@ -186,6 +186,27 @@ dependencies = [
"windows-link",
]
[[package]]
name = "chrono-tz"
version = "0.10.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "cd6dd8046d00723a59a2f8c5f295c515b9bb9a331ee4f8f3d4dd49e428acd3b6"
dependencies = [
"chrono",
"chrono-tz-build",
"phf",
]
[[package]]
name = "chrono-tz-build"
version = "0.4.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8f10f8c9340e31fc120ff885fcdb54a0b48e474bbd77cab557f0c30a3e569402"
dependencies = [
"parse-zoneinfo",
"phf_codegen",
]
[[package]]
name = "chunked_transfer"
version = "1.5.0"
@@ -264,9 +285,9 @@ dependencies = [
[[package]]
name = "crossbeam-utils"
version = "0.8.21"
version = "0.8.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "d0a5c400df2834b80a4c3327b3aad3a4c4cd4de0629063962b03235697506a28"
checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
[[package]]
name = "crypto-common"
@@ -307,6 +328,12 @@ version = "0.3.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "780955b8b195a21ab8e4ac6b60dd1dbdcec1dc6c51c0617964b08c81785e12c9"
[[package]]
name = "equivalent"
version = "1.0.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "00d174d5400e5e8fd687ad1049e2f578285fa914201b1af7e8b112a4546bd826"
[[package]]
name = "find-msvc-tools"
version = "0.1.10"
@@ -414,6 +441,12 @@ dependencies = [
"wasi",
]
[[package]]
name = "hashbrown"
version = "0.15.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
[[package]]
name = "heck"
version = "0.4.1"
@@ -525,6 +558,16 @@ dependencies = [
"quote",
]
[[package]]
name = "indexmap"
version = "2.7.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "8c9c992b02b5b4c94ea26e32fe5bccb7aa7d9f390ab5c1221ff895bc7ea8b652"
dependencies = [
"equivalent",
"hashbrown",
]
[[package]]
name = "is_terminal_polyfill"
version = "1.70.2"
@@ -539,9 +582,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
[[package]]
name = "js-sys"
version = "0.3.104"
version = "0.3.107"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0e0c1080212aad755ea003d18543e8768dd432c48819efd73a7bf1e39b7a5a3a"
checksum = "8dc09d2154098bbf4ef54eab6b117a3c24cbbffe94046b16ee6d6d4510584d3a"
dependencies = [
"cfg-if",
"futures-util",
@@ -572,11 +615,12 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "marqdo"
version = "1.3.0"
version = "2.9.1"
dependencies = [
"anyhow",
"assert_cmd",
"chrono",
"chrono-tz",
"clap",
"futures-util",
"getrandom",
@@ -589,6 +633,7 @@ dependencies = [
"predicates",
"pulldown-cmark",
"regex",
"serde",
"serde_json",
"sha1",
"sha2",
@@ -596,14 +641,22 @@ dependencies = [
"tiny_http",
"tokio",
"tokio-tungstenite",
"toml",
"ureq",
"zeroize",
"zip",
]
[[package]]
name = "marqdo-plugin-sdk"
version = "2.0.0"
dependencies = [
"serde_json",
]
[[package]]
name = "marqdo-wasm"
version = "1.3.0"
version = "2.9.1"
dependencies = [
"marqdo",
"serde_json",
@@ -614,6 +667,8 @@ name = "marqdo_plugin_agent"
version = "0.1.0"
dependencies = [
"chrono",
"marqdo-plugin-sdk",
"pulldown-cmark",
"serde_json",
]
@@ -621,13 +676,32 @@ dependencies = [
name = "marqdo_plugin_demo"
version = "0.1.0"
dependencies = [
"marqdo-plugin-sdk",
"serde_json",
]
[[package]]
name = "marqdo_plugin_engineering"
version = "0.1.0"
dependencies = [
"base64",
"chrono",
"flate2",
"hmac",
"libc",
"marqdo",
"marqdo-plugin-sdk",
"serde_json",
"sha2",
"ureq",
"zip",
]
[[package]]
name = "marqdo_plugin_linalg"
version = "0.1.0"
dependencies = [
"marqdo-plugin-sdk",
"serde",
"serde_json",
]
@@ -637,6 +711,7 @@ name = "marqdo_plugin_llm"
version = "0.1.0"
dependencies = [
"idna_adapter",
"marqdo-plugin-sdk",
"serde_json",
"ureq",
"zeroize",
@@ -646,6 +721,7 @@ dependencies = [
name = "marqdo_plugin_quantum"
version = "0.1.0"
dependencies = [
"marqdo-plugin-sdk",
"serde",
"serde_json",
]
@@ -714,12 +790,59 @@ version = "1.70.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"
[[package]]
name = "parse-zoneinfo"
version = "0.3.1"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1f2a05b18d44e2957b88f96ba460715e295bc1d7510468a2f3d3b44535d26c24"
dependencies = [
"regex",
]
[[package]]
name = "percent-encoding"
version = "2.3.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"
[[package]]
name = "phf"
version = "0.11.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1fd6780a80ae0c52cc120a26a1a42c1ae51b247a253e4e06113d23d2c2edd078"
dependencies = [
"phf_shared",
]
[[package]]
name = "phf_codegen"
version = "0.11.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "aef8048c789fa5e851558d709946d6d79a8ff88c0440c587967f8e94bfb1216a"
dependencies = [
"phf_generator",
"phf_shared",
]
[[package]]
name = "phf_generator"
version = "0.11.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3c80231409c20246a13fddb31776fb942c38553c51e871f8cbd687a4cfb5843d"
dependencies = [
"phf_shared",
"rand",
]
[[package]]
name = "phf_shared"
version = "0.11.3"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "67eabc2ef2a60eb7faa00097bd1ffdb5bd28e62bf39990626a582201b7a754e5"
dependencies = [
"siphasher",
]
[[package]]
name = "pin-project-lite"
version = "0.2.17"
@@ -958,6 +1081,15 @@ dependencies = [
"zmij",
]
[[package]]
name = "serde_spanned"
version = "0.6.9"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "bf41e0cfaf7226dca15e8197172c295a782857fcb97fad1808a166870dee75a3"
dependencies = [
"serde",
]
[[package]]
name = "sha1"
version = "0.10.6"
@@ -992,6 +1124,12 @@ version = "0.3.10"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "3a219298ac11a56ea9a6d2120044824d6f01aeb034955e7af7bc16858527deea"
[[package]]
name = "siphasher"
version = "1.0.4"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "33f4fe9184a62d842c9ef383018f3306d8ba224fd9d836f56d7288308847c256"
[[package]]
name = "slab"
version = "0.4.12"
@@ -1139,6 +1277,47 @@ dependencies = [
"tungstenite",
]
[[package]]
name = "toml"
version = "0.8.23"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "dc1beb996b9d83529a9e75c17a1686767d148d70663143c7854d8b4a09ced362"
dependencies = [
"serde",
"serde_spanned",
"toml_datetime",
"toml_edit",
]
[[package]]
name = "toml_datetime"
version = "0.6.11"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "22cddaf88f4fbc13c51aebbf5f8eceb5c7c5a9da2ac40a13519eb5b0a0e8f11c"
dependencies = [
"serde",
]
[[package]]
name = "toml_edit"
version = "0.22.27"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "41fe8c660ae4257887cf66394862d21dbca4a6ddd26f04a3560410406a2f819a"
dependencies = [
"indexmap",
"serde",
"serde_spanned",
"toml_datetime",
"toml_write",
"winnow",
]
[[package]]
name = "toml_write"
version = "0.1.2"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5d99f8c9a7727884afe522e9bd5edbfc91a3312b36a77b5fb8926e4c31a41801"
[[package]]
name = "tungstenite"
version = "0.24.0"
@@ -1278,12 +1457,11 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
[[package]]
name = "wasm-bindgen"
version = "0.2.127"
version = "0.2.130"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1b70935747edd64d89de3efa29d73789b806c15798f8e7dca4d8ac356b50ce70"
checksum = "a0181c14ddd6c7b8b0b0132a5f1ea2f32be0d893cd3ea97b6e3b28886b8a3d1c"
dependencies = [
"cfg-if",
"once_cell",
"rustversion",
"wasm-bindgen-macro",
"wasm-bindgen-shared",
@@ -1291,9 +1469,9 @@ dependencies = [
[[package]]
name = "wasm-bindgen-macro"
version = "0.2.127"
version = "0.2.130"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "77775f8f3f7217702089053b94958f8f54061a3f663417df76e19cbdcca29bc1"
checksum = "6e931a02a39abdbf66966fc35902b5ed58344750a70885bed4ebb3d8eaf28ed9"
dependencies = [
"quote",
"wasm-bindgen-macro-support",
@@ -1301,22 +1479,22 @@ dependencies = [
[[package]]
name = "wasm-bindgen-macro-support"
version = "0.2.127"
version = "0.2.130"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e11d33f857dc2fb11b8bc75aee111aa9cbeb12cd9f25efd3d4c2a3dd4e235284"
checksum = "2ca4b54280e455bd831e33a6b8e734baf432fe63fbc35c42ac14ce67a043a53a"
dependencies = [
"bumpalo",
"proc-macro2",
"quote",
"syn 2.0.119",
"syn 3.0.3",
"wasm-bindgen-shared",
]
[[package]]
name = "wasm-bindgen-shared"
version = "0.2.127"
version = "0.2.130"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7ef64dbcc55df09c7e5a46182d181c2cfa3e925f3da937ea764728b4bbb9dcbf"
checksum = "3b1f9c3798725016c6ee5f2f57869ec0831e8bbc0ab0310a86e787e97f41389e"
dependencies = [
"unicode-ident",
]
@@ -1480,6 +1658,15 @@ version = "0.52.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
[[package]]
name = "winnow"
version = "0.7.15"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "df79d97927682d2fd8adb29682d1140b343be4ac0f08fd68b7765d9c059d3945"
dependencies = [
"memchr",
]
[[package]]
name = "zerocopy"
version = "0.8.56"
+16 -5
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "1.3.0"
version = "2.9.1"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -12,6 +12,12 @@ name = "marqdo"
path = "src/main.rs"
required-features = ["cli"]
# Lean 判定集成测试(独立目标:缓存/判定/退出码矩阵,见 tests/prove_lean.rs)。
[[test]]
name = "prove_lean"
path = "tests/prove_lean.rs"
required-features = ["cli"]
[features]
default = ["native"]
native = ["cli", "view", "net-host", "plugin-host", "exec-host", "fs-host", "tty"]
@@ -19,7 +25,7 @@ cli = ["dep:clap"]
view = ["dep:tiny_http"]
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize", "dep:zip"]
plugin-host = ["dep:libloading"]
exec-host = []
exec-host = ["dep:libc"]
fs-host = []
tty = ["dep:libc"]
wasm-core = []
@@ -29,7 +35,8 @@ anyhow = "1"
chrono = { version = "0.4", default-features = false, features = ["clock", "std"] }
clap = { version = "=4.4.18", features = ["derive"], optional = true }
pulldown-cmark = "0.12"
serde_json = "1"
serde = { version = "1", features = ["derive"] }
serde_json = { version = "1", features = ["float_roundtrip"] }
thiserror = "1"
tiny_http = { version = "0.12", optional = true }
sha2 = { version = "=0.10.9", default-features = false }
@@ -48,6 +55,8 @@ zip = { version = "=0.6.6", default-features = false, features = ["deflate"], op
libloading = { version = "=0.8.6", optional = true }
include_dir = "0.7"
libc = { version = "0.2", optional = true }
chrono-tz = "=0.10.0"
toml = "=0.8.23"
[target.'cfg(target_arch = "wasm32")'.dependencies]
# Custom entropy — no `js`/wasm-bindgen imports (raw mq_* ABI + marqdo-bridge.js).
@@ -57,14 +66,16 @@ getrandom = { version = "=0.2.17", default-features = false, features = ["custom
[workspace]
members = [
"plugins/demo",
"plugins/engineering",
"plugins/agent",
"plugins/llm",
"plugins/quantum",
"plugins/linalg",
"crates/marqdo-wasm",
"crates/marqdo-plugin-sdk",
]
# Official web plugin is Go (`plugins/web/`); Rust sources kept as
# `plugins/web-rust-archive/` for reference (not a workspace member).
# Official web plugin is Go (`plugins/web/`). The legacy Rust web plugin was
# deleted from the tree (see CHANGELOG); git history keeps it if ever needed.
resolver = "2"
[dev-dependencies]
Regular → Executable
View File
File mode changed.
+318 -23
View File
@@ -1,15 +1,143 @@
# Marqdo
# Marqdo — Your SKILL is now a TOOL.
**代码即文档。文档即知识库。知识即可执行。**
<p align="center"><strong>Write it. Inspect it. Call it.</strong></p>
<p align="center"><em>让 SKILL 真正成为工具:文档即知识,知识即可执行。</em></p>
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。它不是「又一个 Markdown 编程语言」,而是**文档原生的编程运行时(Document-native runtime)**——一门关于**可执行知识(Executable Knowledge)**的语言。
<p align="center">
<a href="https://github.com/cflmy/marqdo/releases/tag/v2.9.0"><img alt="release" src="https://img.shields.io/badge/release-v2.9.0-DDBA86?style=flat-square"></a>
<a href="LICENSE"><img alt="Apache-2.0" src="https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square"></a>
<img alt="Rust runtime" src="https://img.shields.io/badge/runtime-Rust-B38E68?style=flat-square">
<img alt="Pure by default" src="https://img.shields.io/badge/call-pure_by_default-467C83?style=flat-square">
</p>
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
**Marqdo is a Rust-based, document-native runtime for executable AI skills and tools.** Write human-readable prose, GFM tables, parameter contracts, and real functions in one `.mq.md` document. Call a function by its heading, inspect the implementation, and grant side effects explicitly.
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · Engineering Knowledge:[engineering-knowledge.md](doc/design/engineering-knowledge.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
**Not a prompt wrapper.** The document is interpreted as a program by Marqdo; its tool functions are not merely natural-language instructions.
<p align="center">
<a href="#one-markdown-file-three-views-real-execution">56s film</a> ·
<a href="#quickstart--one-function-one-command">Quickstart</a> ·
<a href="#a-procurement-skill-with-a-600-budget">Procurement demo</a> ·
<a href="#explore-the-view">View</a> ·
<a href="doc/library-development.mq.md">Guide</a> ·
<a href="https://www.marqdo.com/">Website</a> ·
<a href="doc/releases/v2.9.0.md">Release notes</a>
</p>
## Marqdo 2.9.0 — Verified Knowledge Compiler
Knowledge statements and claims have stable addresses; verified pure contracts compose across static modules and produce independently replayable Lean certificates. Evidence distinguishes abstract `model_proved` from true runtime `proved`. Unsupported runtime effects and semantics are explicitly unverified. [Proof scope and acceptance](doc/design/verified-knowledge-compiler-boundaries.md) · [Release notes](doc/releases/v2.9.0.md).
## One Markdown file. Three views. Real execution.
[![Watch Marqdo 2.7.1 — from Markdown to execution](assets/marketing/marqdo-2.7.1-markdown-to-execution-cover.jpg)](assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4)
**[▶ Watch the 56-second film](assets/marketing/marqdo-2.7.1-markdown-to-execution.mp4)** · [Bilingual captions](assets/marketing/marqdo-2.7.1-markdown-to-execution.srt) · [Reproducible video source](scripts/render-markdown-execution-promo.py)
> **The point is not to invent a new document format.** A `.mq.md` file uses Markdown headings, paragraphs and tables. Ordinary Markdown renderers still show a readable document. Marqdo adds explicit execution semantics and a View that can inspect functions, values and their relationships on the same document.
![Three views, one source — source Markdown, rendered Markdown, executable View](assets/marketing/source-markdown-view-concept.png)
<sub>**Concept artwork** showing the design principle: **source → ordinary Markdown rendering → Marqdo View**. Illustrative labels are not a live execution trace. The video includes [a real View screenshot](assets/marketing/user-procurement-view.png), [a standard Markdown rendering](assets/marketing/marqdo-procurement-standard-markdown.png) produced from the actual procurement source, and a business example verified with the 2.7.1 CLI.</sub>
**One `.mq.md` source, three ways to interact:**
| Source | Standard Markdown | Marqdo runtime + View |
|---|---|---|
| Edit the same Markdown text | Read headings, prose and data tables | Inspect the same document's calls, values and effects |
| No separate prompt or tool implementation specification needed | Works as ordinary readable documentation | Call named functions with `marqdo call` |
## Quickstart — one function, one command
Install the [latest 2.9.0 CLI release for Windows or Linux](https://github.com/cflmy/marqdo/releases/tag/v2.9.0), then run from this repository's root:
```bash
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
# => 5
```
The function heading is the callable name. The function's explanation, parameters, return contract, and implementation live **in the same source file**. Use `--json` for machine-readable call results and diagnostics. No LLM key is needed for this quickstart.
## A procurement skill with a ¥600 budget
[Read the complete executable procurement document](examples/procurement/index.mq.md) · [How to run and verify the example](examples/procurement/README.md)
This is a **seven-tool, offline demonstration**. It knows the local supplier directory, queries a static price catalog, checks the budget, and conditionally creates a **simulated** work order. It also documents receipt handling, negotiation and supplier switching as unconnected stubs.
![Animated results from real Marqdo 2.7.1 function calls](assets/marketing/procurement-cli.gif)
<sub>**Real CLI results**, edited into a short animation; the accepted order is explicitly **simulated** and never sent. [Capture workflow](scripts/capture-procurement-showcase.py) · [Passing checks](https://github.com/cflmy/marqdo/actions/runs/43358288563).</sub>
```bash
# 1. Approve suppliers: paused or blacklisted entries are excluded.
marqdo call examples/procurement/index.mq.md 查询采购商 "采购商状态='正常'" --json
# 2. Quote: SUP_JN, 8 ball bearings × ¥36 = ¥288 (sample price).
marqdo call examples/procurement/index.mq.md 查询采购商价格 "采购商标识符='SUP_JN'" 数量=8 有效秒数=300 --json
# 3. Budget: ¥600 - ¥120 = ¥480.
marqdo call examples/procurement/index.mq.md 查询余额 已花费=120 --json
# 4. Recheck supplier, quote, delivery and budget before a local mock order.
marqdo call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=120 交付要求天数=7 --effects time.read,process.control --json
# 5. Over budget: ¥600 - ¥360 = ¥240 < ¥288. The mock work order must be denied.
marqdo call examples/procurement/index.mq.md 向采购商发工单 "采购商标识符='SUP_JN'" 数量=8 单价=36 已花费=360 交付要求天数=7 --effects time.read,process.control --json
```
| Case | Budget check | Expected business result |
|---|---|---|
| `已花费=120` | ¥480 available ≥ ¥288 | `ok: true`, **local simulation only, not sent** |
| `已花费=360` | ¥240 available < ¥288 | `ok: false`, budget denial |
| `SUP_YY` | Supplier on blacklist | Excluded from quote / order |
**Why this matters:** The document doesn't merely tell an agent to obey a limit. The work-order **function itself** calls supplier validation, price lookup, and `查询余额` before returning an order record. Agent instructions and callable business logic can be inspected together.
> **Important limits:** Price and supplier records are fixtures; `已花费` is caller supplied. No authoritative budget ledger, concurrent reservation, live supplier prices, ERP messaging, real receipt, or payment is implemented. A successful **simulated** order is **not** a real transaction. The demo is a testable starting point, not a financial safety guarantee.
## Explore the View
Marqdo 2.7.1 improves the interactive reading experience: implementation details stay open when manually expanded, structured values are presented more clearly, and function/source links are easier to inspect. It **does not introduce new language syntax or APIs**.
```bash
marqdo view examples/procurement --no-open
```
![Marqdo View — original detailed screenshot provided by the project author](assets/marketing/user-procurement-view.png)
<sub>**Original View screenshot provided by the project author.** Notice the natural document typography, values in the margins, and curved connections originating from function calls in the prose. [Additional automated View capture](assets/marketing/procurement-view.png) · [Static Markdown rendering](assets/marketing/marqdo-procurement-standard-markdown.png).</sub>
## One document, multiple uses
| Prompt-oriented agent skill | Marqdo executable skill |
|---|---|
| Natural-language tool instructions | Natural-language guidance **and** executable functions |
| Description and code often separated | Heading, parameter table, return table and implementation in one `.mq.md` |
| Validation may require separate wiring | Named function calls can be checked, executed and tested |
| Prompts ask a model to comply | Runtime permissions control **declared** effects of a function call |
| Hard to follow implementation through files | View links readable content and implementation details |
Agent Skills already support scripts; Marqdo's claim is **one document-native language surface** for authoring, inspecting, executing and reusing functions. This is **not** a claim of full formal verification, zero-delay execution, or OS-level isolation of all plugin/process behavior.
**Resources:** [Release v2.8.0](https://github.com/cflmy/marqdo/releases/tag/v2.8.0) · [Ext pack 2.8.1](https://github.com/cflmy/marqdo/releases/tag/ext-v2.8.1) · [Procurement example](examples/procurement/index.mq.md) · [Executable library authoring](doc/library-development.mq.md) · [Function calling](public/features/22-函数调用.mq.md) · [Link syntax](doc/design/link-syntax.md) · [Website](https://www.marqdo.com/)
---
## Deep dive · 语言、设计与执行系统
标准库单文件本身就是手册:直接阅读[文件库](lib/文件.mq.md)、[集合库](lib/表.mq.md)等源码,按函数标题下的参数表、返回契约和动作说明调用;[工程实践](examples/stdlib-handbook/索引.mq.md)演示文件整理、CSV 汇总与文档维护。
开发标准库和拓展库请直接阅读[可执行库开发指南](doc/library-development.mq.md):契约表、叙述式实现、遮蔽调用与多文件工程组织均有可运行示范。
当前 CLI **2.8.0** 新增 `marqdo prove`:知识文件的定理表编译为 Lean 4 并自动判定真假——没有 Lean 工具链也能离线符号执行(诚实降级,绝不冒充证明),有 Lean 时全链路证明并给出反例见证。参见[发布说明](doc/releases/v2.8.0.md)。
独立拓展包 **2.8.1**(CLI 仍为 2.8.0):`ext/ai` 插件侧持久化工作流(选择 / 作用域上下文 / 只读失败恢复 / `inspect`)。`marqdo ext add agent` → CDN latest。参见[拓展包说明](doc/releases/ext-2.8.1.md)。
CLI **2.8.0** adds `marqdo prove`: theorem tables in knowledge files compile to Lean 4 and are judged automatically — offline symbolic execution without a toolchain (honest degradation, never impersonating a proof), full proofs with counterexample witnesses when Lean is available.
Ext pack **2.8.1** (CLI remains 2.8.0): plugin-only durable AI workflows with bounded choice, scoped context, failed-only read-only recovery and `inspect`.
## 核心优势:可执行知识(Executable Knowledge)
> **Knowledge That Can Run —— 知识即可执行。**
@@ -29,15 +157,97 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
| 真正的核心优势 | 说明 |
|------|------|
| **知识-代码一致性**<br>Knowledge-Code Coherence | 说明、数据、示例与实现**同一份源文件**:文档里的表格就是程序的数据,文档里的调用就是真实执行。「文档过期」不再是悄悄漂移,而是可被机器发现的**知识不一致**——知识陈述本身可以被测试。 |
| **函数即工具**<br>`marqdo call` | 最小可执行单位是文件中的函数,不只是整份文件。人阅读函数旁边的叙述;开发者、测试和 Agent 用 `marqdo call 文件 函数 名字=值` 执行它。知识复用、工具调用、函数级测试和局部改进是同一入口的四种用法。 |
| **默认安全,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 的下一步。 |
| **表格即数据结构** | 程序的数据结构直接就是文档的数据结构:单列竖表 → `List`;横表(1 数据行)→ `Map`;横表(多数据行)→ `Map` of `List`(列向聚合);首列写 `@` / `行` / `row` → 行向记录 `List` of `Map`。取元使用 `access(集合, "键")`,链接 `[描述](表达式)` 只承载叙述与执行体。这是 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。 |
| **链接即调用**<br>Link as Call | 文档里的 `[描述](类.函数)` 不是装饰,是跨文档类调用;编译器解析类/函数并返回 **LinkInfo**,`view` 显示调用点,EKC 建边,`links.lock` 可选复现。**v2.1 已实现可执行知识基础设施**。 |
| **完整工程,不是玩具** | Rust 正经解释器(词法 / 语法 / 语义 / 树遍历 + 字节码后端)、stdlib、模块与对象、debugger、viewer、catalog、WASM、原生插件 ABI、VS Code 扩展、agent / LLM / MCP。 |
---
## 链接语法:链接即调用(v2.1 设计声明)
> **这是 v2.1 的可执行知识模型。**
> `[]()` 不新增语法:`[]` 是 Markdown 链接的描述;`()` 是**已有代码**,与 `**代码**` 同权。
> `#` 是类,`##` 是函数;`类.函数` 是**类调用**。
> 链接只是给这次调用一个名字;`view` 显示调用信息,编译器返回 **LinkInfo**,EKC 建边。
### 两文档,一次类调用
知识文档 `libai.mq.md`:
```markdown
# 李白
这个文档存储了李白的信息。
## 李白的出生年份
*701*
```
- `# 李白` = 类;
- `## 李白的出生年份` = 函数;
- `*701*` = 返回值。
调用文档 `main.mq.md`:
```markdown
# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
```
`[]` 是描述,`()` 是已有调用 `李白.李白的出生年份`——**类 `李白` 调用函数 `李白的出生年份`**。
不需要 `print`:`view` 模式天然显示 `()` 的调用信息(类、函数、签名、值)。
要终端输出,就把同一段代码放进代码链接并加 `print`:
```markdown
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
输出:`701`。
### 四条语义
1. **`[]` 永不执行**:描述只给人读、给检索/诊断/展示用。
2. **`()` 与 `**代码**` 同权**:同一套 parser/evaluator;`类.函数` 是类调用,`obj.函数` 是实例调用。
3. **`#` 是类,`##` 是函数**:不使用 `self`/`自` 的函数是**类函数**,可直接 `类.函数` 调用;使用 `self`/`自` 的是**实例函数**。
4. **链接 = 描述 + 调用**:`view` 显示调用点;编译器返回 `LinkInfo`;EKC 建边;`links.lock` 可选复现。
### 现状与目标
| 能力 | v2.0.0 | v2.1 |
|------|-------------|-----------|
| 本地表达式链接(遮蔽) | ✅ `markup: occlusion` | ✅ |
| `()` 与 `**代码**` 同权 | ✅ 表达式/调用 | ✅ |
| 类调用 `类.函数` | ❌ 需先构造实例 | ✅ 直接调用 |
| 跨文档类索引 | ❌ 需 `import` + 实例 | ✅ 项目类索引 |
| 正文链接 `view` 信息 | ❌ | ✅ 目标/签名/值 |
| LinkInfo / check | ❌(`check` 只查契约) | ✅ `link.*` |
| 链接图边(EKC) | ❌ | ✅ `calls` / `references` |
| `links.lock` 可复现 | ❌ | ✅ 可选 |
### 知识分层:本体 → 知识个体 → 调用面
| 层 | 写法 | 语义 |
|----|------|------|
| L1 本体 | `# 诗人` + 字段/类型表 | 类/模式 |
| L2 知识个体 | `# 李白 = > 诗人` + `## 出生年份` + `*701*` | 单体知识类(不是运行时实例) |
| L3 调用面 | `[出生年份](李白.出生年份)` | 类调用/链接 |
> `# 李白 = > 诗人` 语法上是继承/特化,语义上是「李白是诗人」的知识个体;
> 运行时实例仍是 `> 诗人` / `> 李白`。详见 [knowledge-layers.md](doc/design/knowledge-layers.md)。
兼容迁移示例见 [examples/link-syntax/main.compat.mq.md](examples/link-syntax/main.compat.mq.md)。
设计宪法:[doc/design/link-syntax.md](doc/design/link-syntax.md) · 链接示例:[examples/link-syntax/](examples/link-syntax/) · 知识分层示例:[examples/knowledge-layers/](examples/knowledge-layers/) · 证据复核:[occlusion-vs-executable-knowledge-2026-10.md](doc/research/occlusion-vs-executable-knowledge-2026-10.md)
---
## 愿景与期许
不把「AI 能写 Marqdo」当终点,而是 **「AI 能可靠地生成可验证的 Marqdo」**:
@@ -45,8 +255,9 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
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)。
4. **链接即调用 / 可执行知识图**:`[描述](类.函数)` 既是文档链接,也是类/函数调用;编译器解析目标、校验签名、返回 LinkInfo;`view` 显示调用点;`.mq.md` 之间的链接长成文档图 + 知识图 + 程序图(Executable Knowledge Graph)。
5. **知识可测试**:文档中的示例表自动执行;知识与执行结果不一致会被机器报告——Knowledge-Code Coherence 从理念变为日常。
6. **知识可证明**:知识文件内的定理表 → Lean 4 定理 → 自动判定(`marqdo prove`);离线符号执行与 Lean 单调一致,分歧显式报错——Trusted Knowledge,判定器缺陷优先于任何绿灯。
6. **可靠性基准**:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成真实任务,测量生成长度、语法 / 语义错误率、修复轮次、token 消耗与人类阅读 / 修改成本——用实验数据证明「文档型语法降低 LLM 生成熵」。
---
@@ -64,24 +275,30 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
---
## 语法速览(v0.3)
## 语法速览
| 标记 | 含义 |
|------|------|
| 无标记行 | 叙述(注释);行内 `` `名` `` 可声明 |
| `**…**` | **代码**(赋值 / 调用 / 表达式) |
| `[描述](表达式)` | **链接(本地)**:描述 + 代码;`()` 与 `**…**` 同权(默认语义) |
| `[描述](类.函数)` | **链接(跨文档/类调用)**:描述 + 已有类函数调用;可解析、可执行(v2.1 目标) |
| `[描述](url)` | 普通 Markdown 导航链接(惰性,不执行) |
| `*…*` | **返回值**(整行、`返回*n*`、或表达式形) |
| `****` / 整行 `**` / `*None*` | **空返回**(`None`),并结束本函数体 |
| `> print …` 等 | 输出等副作用 = **普通函数**,非架构标记 |
| `#` | 对象 / 类型(构造体;`# main` = 入口) |
| `##` … | 函数 / 方法(按标题深度嵌套) |
| `#` | **类 / 类型**(知识命名空间;`# main` = 入口) |
| `##` … | **函数**(类下函数;使用 `self`/`自` 时为实例方法) |
| `类.函数` | **类调用**(不使用 `self` 的函数;v2.1 目标) |
| `` > `obj`.method … `` | 方法调用(`obj` 为带 `_type` 的 map) |
| 叙述 `` `名` `` / `` `名`=默认 `` | 形参由体推断(`` + `名` `` 仍可用) |
| `1.` … | 体内 `1.` `2.` … = 分支(`N. *` = else) |
| `-` | 循环(`` - `条件` `` 或 `` - [项](集合) ``) |
| 表格 | 集合(几何即类型,见下);取元优先 `[键](集合)` |
| `-` | 循环(`` - `条件` `` 或 `` - [项](遍历 集合 为 项) ``) |
| 表格 | 集合(几何即类型,见下);取元使用 `access(集合, "键")` |
| 单独一行 `---` / `***` | **叙述分隔**(跳过;不是函数收束) |
> `[键](集合)` / `- [项](集合)` 是旧取元/循环形;迁移后使用 `access(集合, "键")` 与 `- [描述](遍历 集合 为 项)`。旧形只在显式 `markup: classic` 或 `--legacy-markup` 过渡入口中保留,见 [link-syntax.md](doc/design/link-syntax.md)。
```markdown
# main
@@ -116,6 +333,51 @@ Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,
---
## 工程习惯:允许申报未完成,但不允许假装完成
Marqdo 允许你写出"还没接通"的代码——**只要写在描述里**。这样文档整体仍能跑,
而欠账是可见、可数、可结算的(而不是假装完成):
```markdown
## 检索资料
| 返回 | 类型 | 说明 |
|------|------|------|
| | list | 命中列表(当前未接) |
[按关键词检索,接口未接,待开发](None)
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
```
`[]` 里是**自由描述**(不执行);`()` 里是**目标**(唯一执行)。这条语法叫**链接语法**:
目标是本地表达式时,就是**遮蔽**(把代码折叠在括号里);目标是 `类.函数` 时,就是**跨文档类调用**。
v2.1 实现了文件级链接语义与可执行知识投影(见 [link-syntax.md](doc/design/link-syntax.md))。
**四条约定**
1. **桩必须能跑**:不得报错,否则整篇文档被阻断。
2. **桩必须写明返回值**:写 `None` 也比空着好;空 `()` 会报 `label.empty_payload`(warning)。
3. **申报用词有范例**:内置词表(`待开发` `未实现` `开发中` `模拟` `桩` `示例` `实验` `废弃` …)
是**推荐用词与默认检索集**,不是语法——写别的说法同样合法。
4. **接不了就申报,别声称完成**:这条已写进 `ext/ai` 的 agent 提示词。
**盘点与门禁**
```bash
marqdo labels --count # 内置口径:还有多少未完成
marqdo labels --grep "接口未联调,联调中" --count # 用你自己的说法
marqdo labels --grep 联调 --also-builtin --count # 自定义 + 内置一起数
marqdo labels --count --baseline .marqdo/pending.json --fail-on-increase
```
最后一条是**棘轮**:只拦"新增未完成",不追旧账。
设计依据:[link-syntax.md](doc/design/link-syntax.md) · [occlusion-syntax.md](doc/design/occlusion-syntax.md) ·
[occlusion-description-and-search.md](doc/design/occlusion-description-and-search.md)
---
## OKF 风格清单(自动生成)
从源码派生 YAML / Markdown 知识包(勿手改生成物):
@@ -149,34 +411,65 @@ marqdo catalog public -o .marqdo
---
## 现状(v1.3.0)
## 现状(v2.7.0)
- **实际工程与可执行 SKILL(v2.7.0)**:中英文用户站点使用递归 View、普通 Markdown、当前数据/表单/会话资源并保留原始主题。开发与发版手册通过 `marqdo call` 执行,固有文件能力负责读写,工程插件承接进程、认证与格式边界。旧独立浏览器演示已收敛到实际可运行的工程;详见 [2.7.0 发布说明](doc/releases/v2.7.0.md)。
- **标准库与拓展库手册(v2.6.0)**:61 份公开标准库、650 个函数;源码内参数/返回契约、叙述形参、句中遮蔽调用与真实工程。新增文件/字节/集合/Result/文档/HTTP/任务/TOML/时区工作流;多文件拓展库以 index 组织。
- **View 可读动作与知识(v2.6.0)**:正文读动作,侧注看实现,运行标注看实际结果;空逻辑明确提示待补。知识说明先看输入、返回、依赖和依据,技术身份按需展开。
- **Quantum / Web 工程实践(v2.6.0)**:可执行实验、会话句柄与双语门面;网页先递归拆布局,直到叶子可以直接用 Markdown 表达。CLI · wasm · ext · VS Code 扩展同步 **2.7.0**。
- **View 连线与工具栏(v2.5.1)**:真实源码锚点、连续 S 形曲线、错落标注与连线避让;底部工具栏增加文字标签。深浅色配色保持一致。CLI · wasm · ext 同步 **2.5.1**。
- **View 阅读界面(v2.5.0)**:暖白金色主题、新 Logo 与花枝装饰;真实执行信息左右引出、窄屏内联;导航/搜索/阅读设置/工具栏;重跑同步刷新与离线公式。CLI · wasm · ext 同步 **2.5.0**。
- **Oracle journal 语言值(v2.4.0)**:`foreign.oracle_journal` / `foreign.replay_check` 作普通值;handle/code 拒入 journal;bytecode/frontend 硬化;扩展包同步 **2.4.0**
- **Foreign Strong(v2.3.0)**:会话 `handle`(不可过桥)· 仿射 close · `replay_check`/oracle journal · 表 arity refuse · Ω∈\(V_{\mathsf{safe}}\)。扩展包同步 **2.3.0**
- **\(V_{\mathsf{safe}}\) JSON 整数(v2.2.2)**:外联与 `lib/json` 拒绝 `|n| > 2^{53}-1` 的 JSON 整数(对齐 Lean ForeignJSON);宽整数用十进制字符串 + Node `BigInt`。
- **view 大纲侧栏(v2.2.1)**:修复 occlusion 文档与中等宽度下 Functions / Variables 掉到正文下方的问题;静态 `view output` 同源。
- **函数级调用(v2.2.0)**:`marqdo call <文件.mq.md> <函数> 名字=值`。同一份文档给人读,也按函数执行;Tree 与 Bytecode 都跑被点名的函数,不回退到 `# main`。默认只执行纯函数。`--json` 给 Agent 读取结果或诊断。说明与价值见 [22-函数调用](public/features/22-函数调用.mq.md)。示例:`marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3` → `5`。扩展包同步 **2.2.1**
- **Agent 可靠工作台(v2.1.5)**:ResourceView(JSON/CSV/PDF/image)· ToolSpec 授权先于调用 · CheckpointV2 / EffectLedger / ContextPackV2 · EKC `ir.json` 暖机与 `--refresh` · Web 短读/控制与 execute 槽隔离;扩展包同步 **2.1.5**
- **默认隔离 HTTP execute(v2.1.4 · ADR 0009)**:`execute` / `sse-live` / `stream:true` → Supervisor worker 池(`--call-lib-path`);父进程不再占 `INVOKE_LOCK`;`/_runtime/*`;`runtime.isolated_execution=1`;MR-01 金样例
- **知识工作台运行时(v2.1.3)**:ModelSelection / RunContext / usage null≠0 · `view document` 只读嵌入 · LLM selection/messages/cancel · agent.step selection e2e · live smoke(设计 Partial:原生适配器 unavailable)
- **可执行知识生产链(v2.1.2)**:证据/闭包失效 · `verify`/`adjudicate` · `reuse_execute` / `eng_bind_execute`+`publish_gate` · `document.extract` · View `KnowledgePresentation`+SSE `page_token` · 上传限流 · 门禁 45 项(100/1000 单元)
- **可执行知识主链(v2.1.1)**:BoundCall 双后端 · NarrativeRef · 来源/适用期 · `artifact.patch` / `extract_pure` · 整代 `CURRENT` + closure · 发票示例 `113`
- **链接语法(v2.1.0)**:`[描述](目标)` 描述不执行 · `()` 与 `**代码**` 同权(`加(1)` / `加一 号(31)`)· `access` 取元与 `遍历` 链接循环 · `marqdo labels` 两级检索 / `--baseline` 债务棘轮 · `migrate labels --mark` · 诊断 `label.*` · view 描述正文 + 代码片 + 桩徽章 · **可执行知识 [link-syntax.md](doc/design/link-syntax.md)**(项目索引、LinkInfo、链接图与 lock)
- **外联 v3 P0/P1(v1.5.2)**:raw stdin + 每 cell 独立输入 · plan API · snapshot export/import/replay · `view capture` · Persist 按钮 · 扩展包同步 **1.5.2**
- **view 静态/动态统一 + 外联值传递(v1.5.1)**:静态导出与 live view 共用 `foreign_doc` 执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin;扩展包同步 **1.5.0**
- **裸自增升参(v1.4.6)**:首次粗体赋值左值即声明;`**n = n + 1**` 无反引号也升为必选形参。扩展包仍为 **1.4.5**
- **Streamable HTTP MCP + web invoke 鉴权(v1.4.5)**:`agent_mcp_serve transport=http` · Bearer/`X-Api-Key` 注入 · `unauthorized`→401 · openai/agent `json.get` 硬化
- **LLM 传输软失败 + `ext/ai` 表优先(v1.4.4)**:上游不可达 → `status=error`(不 abort);`agent`/`llm` 去 `json.set` 胶水 · [agent-llm-transport-soft-2026-10.md](doc/research/agent-llm-transport-soft-2026-10.md)
- **Ext pack 1.4.3**:修复 `agent.run` cold EFI(`` `self`.preflight `` + miss resolve `llm_free`);已并入 **≥1.4.4** · [agent-run-efi-resolve-bugs-2026-10.md](doc/research/agent-run-efi-resolve-bugs-2026-10.md)
- **Agent/LLM 优化 O1–O5(v1.4.2)**:`ext/ai/sandbox` CoW · `agent.trial` / `sandbox=` · promote sandbox proof · `step_route` / EFI / cost · style lint · quarantine · [ext-ai-optimize.md](doc/roadmap/ext-ai-optimize.md)
- **view 标注连线(v1.4.1)**:underline→chip SVG mid→mid(底边中点→轨道→短竖线→顶边中点)· 帧 chip 共用 id · L→R 密度 · [view-prose-annot-gaps.md](doc/design/view-prose-annot-gaps.md)
- **叙述统一 / 公式 meta / 图片自写回(v1.4.0)**:`% marqdo: var=` 块公式绑定 · 臂/循环体叙述与 foreach 中英糖 · `![marqdo-out](…)` 图片自写回 · view 推断形参实值 · [fence-meta-and-control-prose.md](doc/design/fence-meta-and-control-prose.md) · [stdlib-writeback.md](doc/design/stdlib-writeback.md)
- **view 文档面(v1.3.3)**:Browse Structure 叙述保真 · 标记面 · 分支/循环帧下拉 · AI `#mq-view-trace` · 静态 `view output` / gh-pages 同源 · [view-document-annotations.md](doc/design/view-document-annotations.md)
- **Engineering Knowledge(v1.3.0)**:EKC L0–L4 · `marqdo knowledge|find|reuse|duplicate|verify|…` · Agent `preflight` / REUSE→ADAPT→CREATE · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
- **Web Artifact(v1.2.0 · ADR 0007)**:Document/Endpoint 一等公民(`type: web|endpoint`)· facade `page`/`route`/`serve`/`render`/`inspect`/`use` · Resource 拆到 `ext/data`/`security`/`net` · 统一 View 表 · 破坏性移除 `compose_*`/`configure`
- **AI 栈(v1.1.1)**:`ext/ai/llm` 语义 `ask`/`stream`/`collect` · Artifact Metadata Binding(`${env|arg|sys|secret}`)· Agent Skill Compilation + Adaptive Routing · MCP stdio 客户端 + resume 检查点 · 可选 `plugins/llm` Transport ABI
- **AI 原生闭环(v1.1.0)**:核心表面守卫(19 构造,单边改动 CI 必红)· **渐进式契约**(文档内嵌 `参数`/`返回`/`字段` 表 + 四边界校验 + `marqdo check` 防漂移)· **MLSP for AI**(`marqdo mlsp`:`locate`/`syntax`/`validate`/`repair_targets`/`repair_apply`/`schema`,AI 按需查语法而非背诵)· **结构化诊断**(`run --json`,错误即数据);验证见 [perf-validation-report-2026-09-23.md](doc/roadmap/perf-validation-report-2026-09-23.md)
- 映射与解释器:**v0.3 语法宪法**(`**` 代码 / `*` 返回 / 叙述声明);Phase I 树遍历 + 字节码后端;金样例在 `tests/` 与 `tests/markup-v03/`
- **对象**:`#` = 类型/构造,`##`+ = 函数/方法;见 [objects.md](doc/design/objects.md)
- **`marqdo view`**:文档浏览器(Structure + 函数大纲/搜索 + Execution + Variables 浮窗)
- **`marqdo view`**:文档浏览器(**文档面** Structure + 标注 / 调用·循环帧 + 函数大纲/搜索 + Execution + Variables 浮窗;`view output` 同构)
- **`marqdo debug`**:独立调试页(断点 / 单步 / locals;默认端口 7430;页面 favicon / 品牌使用官方 Logo)
- **`marqdo catalog` / `sync`**:OKF 风格 YAML + 模块概念页(默认挂钩 EKC)
- **`marqdo knowledge` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify`**:Engineering Knowledge Compiler([engineering-knowledge.md](doc/design/engineering-knowledge.md))
- **`marqdo version --check`**:与 GitHub 最新 release 对比
- 标准库:**内置于二进制**(v0.1.2+);磁盘 `lib/` 或 `MARQDO_LIB` 可覆盖。模块含文本、表、**浏览器效应**、文件、系统、时间、JSON、网络、数学、外联、插件、**自写回**、**子任务**;**中层 Mid M1–M6** + **Mid2 M7–M10**(datetime/url/toml/html/fs++/stats/log.fields 等,见 [stdlib-mid.md](doc/design/stdlib-mid.md) · [stdlib-mid2.md](doc/design/stdlib-mid2.md))
- **官方扩展库 `ext/`**(**非** stdlib,本版收口):
- **`web`**:**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/)
- **`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/) · [完整站点](examples/web-site/) · [中文完整站点](examples/web-site-zh/)
- **`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/Client stdio** + Skill Compilation + Adaptive Routing + resume + **Engineering preflight**(`agent.preflight` / `eng_preflight`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md) · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
- **`agent`**:A1–A4 + **MCP Server/Client**(stdio + **Streamable HTTP**)+ Skill Compilation + Adaptive Routing + resume + **Engineering preflight**(`agent.preflight` / `eng_preflight`);宿主缺口见 [ext-hosting.md](doc/roadmap/ext-hosting.md) · [agent-framework-gaps-after-a4.md](doc/research/agent-framework-gaps-after-a4.md) · [engineering-knowledge.md](doc/design/engineering-knowledge.md)
- **`llm`**:语义 `ask`/`stream`/`collect`(OpenAI/Ollama;可选原生 `plugins/llm`)
- 安装:`marqdo ext list` / `add …` / `remove`([ext-cli.md](doc/design/ext-cli.md);默认 `~/.marqdo/ext`)。原生插件先 `cargo build -p marqdo_plugin_*` 再 `ext add`
- **原生插件 ABI**:[`include/marqdo_abi.h`](include/marqdo_abi.h) · [ext-abi.md](doc/design/ext-abi.md);`plugins/{demo,agent,web,quantum,linalg,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))
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-app](examples/browser-app/) · [web-spa-app](examples/web-spa-app/) · [web-collab-doc](examples/web-collab-doc/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
### 如何使用最新 Marqdo(v1.3.0)
### 如何使用最新 Marqdo(v2.7.0)
**安装解释器(任选其一)**
@@ -191,14 +484,16 @@ marqdo catalog public -o .marqdo
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v1.3.0 # 或留在 main
git checkout v2.7.0 # 或留在 main
cargo build --release
export PATH="$PWD/target/release:$PATH"
marqdo version
marqdo version --check
# 2) 跑解释器 / 文档站 / catalog
# 2) 跑整个文件,或只调用其中一个函数
marqdo run tests/structure/hello.mq.md
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3
marqdo call examples/calculator.mq.md 计算器.加法 a=2 b=3 --json
marqdo run tests/structure/hello.mq.md --backend bytecode
marqdo view public --no-open
marqdo debug public --no-open
@@ -222,15 +517,15 @@ marqdo ext add llm # 或:大模型(.mq.md + 可选 native llm)
# 4) 动态站示例(扩展装好后)
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 验收站
marqdo call examples/web-site/index.mq.md serve --effects plugin,fs.write,network.write --fs-root examples/web-site --json
# 浏览器打开终端打印的 listen 地址;/favicon.ico 与 logo 装配见 W8
# 5) 浏览器 WASM(可选)
marqdo wasm build
# → dist/wasm/ … 见 examples/browser-hello/
# → dist/wasm/ … 实际工程见 examples/browser-app/
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
# https://github.com/cflmy/marqdo/releases/tag/v1.3.0
# https://github.com/cflmy/marqdo/releases/tag/v2.7.0
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
Binary file not shown.

After

Width:  |  Height:  |  Size: 132 KiB

@@ -0,0 +1,35 @@
1
00:00:00,000 --> 00:00:04,800
Your SKILL is now a TOOL.
让 Markdown 直接承载可执行语义。
2
00:00:04,800 --> 00:00:11,600
源码态:标题、段落、表格都沿用 Markdown。
执行逻辑就在文档之中。
3
00:00:11,600 --> 00:00:18,000
渲染态:同一份代码也能成为普通 Markdown 文档。
4
00:00:18,000 --> 00:00:25,000
源码态、标准 Markdown 渲染态、Marqdo View 态。
三种视图,同一份源文件。
5
00:00:25,000 --> 00:00:32,500
一份 .mq.md,既可以阅读,也可以编译执行。
6
00:00:32,500 --> 00:00:42,000
真实 View 截图:函数调用和值沿着优雅曲线呈现。
7
00:00:42,000 --> 00:00:50,800
预算校验不是文字承诺,而是函数执行。
模拟订单通过或拒绝,均由运行时返回结果。
8
00:00:50,800 --> 00:00:56,000
Marqdo 2.7.1 · github.com/cflmy/marqdo
Binary file not shown.

After

Width:  |  Height:  |  Size: 78 KiB

Binary file not shown.
+29
View File
@@ -0,0 +1,29 @@
1
00:00:00,000 --> 00:00:03,900
Your SKILL is now a TOOL.
让 SKILL 真正成为工具。
2
00:00:03,900 --> 00:00:09,000
One readable document. Callable business logic.
规则、数据、工具在同一份文档里。
3
00:00:09,000 --> 00:00:17,400
Five verified CLI calls, from quote to decision.
真实 CLI 结果:询价、预算、模拟发单。
4
00:00:17,400 --> 00:00:23,400
¥120 spent: mock order. ¥360 spent: rejected.
¥120 时模拟通过;¥360 时预算不足。
5
00:00:23,400 --> 00:00:29,000
Inspect the actual document in Marqdo View.
查看 Marqdo 真实 View 页面。
6
00:00:29,000 --> 00:00:32,000
github.com/cflmy/marqdo
开源 · Marqdo 2.7.1
Binary file not shown.

After

Width:  |  Height:  |  Size: 161 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 139 KiB

+42
View File
@@ -0,0 +1,42 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1340" height="720" viewBox="0 0 1340 720" role="img" aria-label="Animated illustration of a procurement skill being called, including a budget denial">
<defs><linearGradient id="night" x1="0" y1="0" x2="1" y2="1"><stop stop-color="#0b1324"/><stop offset="1" stop-color="#1a2335"/></linearGradient></defs>
<rect x="0" y="0" width="1340" height="720" rx="0" fill="url(#night)" stroke="none"/>
<text x="46" y="52" fill="#f6d39c" font-size="30" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">Marqdo</text>
<text x="207" y="50" fill="#9eacc1" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">/ EXECUTABLE SKILLS</text>
<rect x="1137" y="25" width="165" height="38" rx="19" fill="#283348" stroke="#4b5b6b"/>
<text x="1154" y="50" fill="#d3d9e4" font-size="15" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">2.7.1 · DEMO</text>
<text x="46" y="109" fill="#f6f5ee" font-size="37" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">Your SKILL is now a TOOL.</text>
<text x="47" y="141" fill="#a8b6c7" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">A human-readable document → callable business logic → structured results</text>
<rect x="43" y="168" width="608" height="493" rx="18" fill="#182235" stroke="#38485c"/>
<rect x="677" y="168" width="620" height="493" rx="18" fill="#111a2b" stroke="#38485c"/>
<rect x="43" y="168" width="608" height="57" rx="18" fill="#263349" stroke="none"/>
<rect x="677" y="168" width="620" height="57" rx="18" fill="#263349" stroke="none"/>
<text x="65" y="204" fill="#f5dba9" font-size="20" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">index.mq.md</text>
<text x="707" y="204" fill="#e5eaf4" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">$ marqdo call ... 向采购商发工单</text>
<text x="66" y="266" fill="#faf7f1" font-size="27" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">## 向采购商发工单</text>
<text x="66" y="307" fill="#a2b2ca" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">Read the rules. Call the function.</text>
<rect x="65" y="328" width="564" height="166" rx="9" fill="#101a2a" stroke="none"/>
<text x="86" y="365" fill="#abd6fa" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">报价 = 查询采购商价格(...)</text>
<text x="86" y="407" fill="#abd6fa" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">预算 = 查询余额(已花费=...)</text>
<text x="86" y="453" fill="#e9ba84" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">1. 剩余额度 &lt; 本单金额 → 拒绝</text>
<text x="65" y="552" fill="#d4e0ee" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">One file: prose + contracts + tables</text>
<text x="65" y="588" fill="#d4e0ee" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">+ executable functions + result records</text>
<text x="706" y="272" fill="#d7deef" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">SUP_JN 数量=8 单价=36</text>
<text x="706" y="311" fill="#98aec9" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">最高预算 = ¥600</text>
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.04;0.09;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="345" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="374" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">01 SUPPLIER</text><text x="920" y="374" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">SUP_JN · active</text></g>
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.19;0.24;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="399" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="428" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">02 QUOTE</text><text x="920" y="428" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">8 × ¥36 = ¥288</text></g>
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.35;0.39999999999999997;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="453" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="482" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">03 BALANCE</text><text x="920" y="482" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">¥600 - already spent</text></g>
<g opacity=".18"><animate attributeName="opacity" values="0.18;0.18;1;1;0.18" keyTimes="0;0.53;0.5800000000000001;0.91;1" dur="13s" repeatCount="indefinite"/><rect x="704" y="507" width="565" height="45" rx="9" fill="#233248" stroke="none"/><text x="719" y="536" fill="#9db5cf" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">04 DECISION</text><text x="920" y="536" fill="#f5d8aa" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">check requested amount</text></g>
<g opacity="0"><animate attributeName="opacity" values="0;0;1;1;0" keyTimes="0;0.62;0.66;0.85;1" dur="13s" repeatCount="indefinite"/>
<rect x="704" y="572" width="565" height="68" rx="10" fill="#193a34" stroke="#478a71"/>
<text x="718" y="600" fill="#b5ebcb" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">✓ 已花费=120 ¥480 ≥ ¥288</text>
<text x="718" y="625" fill="#d9f7e8" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">ok: true · 本地模拟,未发送</text>
</g>
<g opacity="0"><animate attributeName="opacity" values="0;0;0;1;1;0" keyTimes="0;0.78;0.84;0.88;0.95;1" dur="13s" repeatCount="indefinite"/>
<rect x="704" y="572" width="565" height="68" rx="10" fill="#42252d" stroke="#a45a67"/>
<text x="718" y="600" fill="#f8b1bc" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">✕ 已花费=360 ¥240 &lt; ¥288</text>
<text x="718" y="625" fill="#fde7ea" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">ok: false · 预算不足,拒绝工单</text>
</g>
<path d="M 652 430 C 665 429 674 429 688 430" fill="none" stroke="#f0c58c" stroke-width="3"/><circle cx="665" cy="429" r="4" fill="#f0c58c"><animate attributeName="cx" values="656;681;656" dur="2.5s" repeatCount="indefinite"/></circle>
<text x="44" y="698" fill="#7e90a7" font-size="14" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">ILLUSTRATED EXPECTED FLOW · NOT A TERMINAL CAPTURE · NO REAL PURCHASE</text>
</svg>

After

Width:  |  Height:  |  Size: 7.4 KiB

@@ -0,0 +1,35 @@
<svg xmlns="http://www.w3.org/2000/svg" width="1340" height="740" viewBox="0 0 1340 740" role="img" aria-label="View-inspired editorial concept for the procurement function, not a real screenshot">
<rect x="0" y="0" width="1340" height="740" rx="0" fill="#f8f6f0" stroke="none"/>
<rect x="0" y="0" width="1340" height="68" rx="0" fill="#f2ede4" stroke="none"/>
<text x="69" y="45" fill="#8d7358" font-size="29" font-family="Georgia,serif" font-weight="600">marqdo</text>
<text x="577" y="43" fill="#665d53" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">文档 函数 执行 变量</text>
<text x="1030" y="44" fill="#998773" font-size="13" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">VIEW CONCEPT / NOT CAPTURE</text>
<line x1="325" y1="113" x2="325" y2="688" stroke="#e0d5c7"/><line x1="1032" y1="113" x2="1032" y2="688" stroke="#e0d5c7"/>
<text x="374" y="128" fill="#b0895e" font-size="16" font-family="Georgia,'Noto Serif CJK SC',serif" font-weight="400">采购智能体</text>
<text x="372" y="196" fill="#39352d" font-size="37" font-family="'Noto Serif CJK SC',Georgia,serif" font-weight="600">向采购商发工单</text>
<text x="374" y="238" fill="#5d5851" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">核对准入、价格、交付与预算之后,生成本地模拟工单。</text>
<line x1="374" y1="267" x2="993" y2="267" stroke="#b69b78"/>
<text x="375" y="309" fill="#514a41" font-size="21" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="600">参数</text>
<text x="375" y="348" fill="#5b5146" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">采购商标识符</text>
<text x="625" y="348" fill="#96754f" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">text</text>
<text x="811" y="348" fill="#8e8171" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">必填</text>
<line x1="374" y1="365" x2="994" y2="365" stroke="#ded6c9"/>
<text x="375" y="392" fill="#5b5146" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">数量 / 单价 / 已花费</text>
<text x="625" y="392" fill="#96754f" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">number</text>
<text x="811" y="392" fill="#8e8171" font-size="17" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">必填</text>
<line x1="374" y1="408" x2="994" y2="408" stroke="#ded6c9"/>
<text x="374" y="463" fill="#5e584f" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">发单前,必须再次查询并核对本轮的可用余额。</text>
<rect x="373" y="483" width="618" height="48" rx="8" fill="#ebe3d5" stroke="none"/>
<text x="391" y="513" fill="#805b35" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">预算 = [重新查询预算](查询余额(...))</text>
<text x="374" y="565" fill="#7b5b4b" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">1. 剩余额度 &lt; 本单金额</text>
<text x="374" y="612" fill="#a06b5f" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400"> 返回 [预算不足,拒绝模拟工单](...)</text>
<text x="375" y="682" fill="#8c8276" font-size="16" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">仅在全部检查通过时产生“本地模拟、未发送”的结果。</text>
<path d="M 408 503 C 295 503 278 339 146 339" stroke="#ba9a75" stroke-width="1.7" fill="none"/><circle cx="408" cy="503" r="4.3" fill="#ba9a75"/>
<text x="73" y="281" fill="#a78255" font-size="15" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">BUDGET CHECK</text>
<text x="73" y="315" fill="#756350" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">已花费 ¥360</text>
<text x="73" y="343" fill="#756350" font-size="18" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">剩余额度 ¥240</text>
<path d="M 823 602 C 1010 586 1026 396 1122 396" stroke="#b7837e" stroke-width="1.7" fill="none"/><circle cx="823" cy="602" r="4.3" fill="#b7837e"/>
<text x="1080" y="319" fill="#a67871" font-size="15" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">REJECTION</text>
<text x="1080" y="354" fill="#945e55" font-size="22" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="700">¥240 &lt; ¥288</text>
<text x="1080" y="393" fill="#945e55" font-size="19" font-family="ui-monospace,Consolas,'Noto Sans CJK SC',monospace" font-weight="400">拒绝工单</text>
</svg>

After

Width:  |  Height:  |  Size: 4.9 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 204 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 1.9 MiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 523 KiB

+7
View File
@@ -0,0 +1,7 @@
[package]
name = "marqdo-plugin-sdk"
version = "2.0.0"
edition = "2021"
[dependencies]
serde_json = "1"
+195
View File
@@ -0,0 +1,195 @@
//! Shared ABI plumbing for Marqdo native plugins (`<TAB>` slimming).
//!
//! Every plugin used to copy the same `MarqdoHostApi` struct, the alloc/free
//! statics, `host_strdup`, `set_out`/`set_err`, `parse_args` and `reply`
//! (about 140 lines each × 5 crates). This crate holds the single copy; the
//! `marqdo_plugin!` macro emits the `#[no_mangle]` exports each `.so` needs.
//!
//! The ABI itself is unchanged: `include/marqdo_abi.h` and the host loader
//! (`src/host/plugin.rs`) still see exactly the same symbols and layout.
use std::ffi::{CStr, CString};
use std::os::raw::{c_char, c_int, c_void};
use std::ptr;
pub use serde_json::{json, Value};
/// Highest ABI version this SDK speaks.
pub const ABI_VERSION: u32 = 2;
pub type PluginFn = unsafe extern "C" fn(
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int;
pub type HostQueryFn = unsafe extern "C" fn(
userdata: *mut c_void,
name: *const c_char,
args_json: *const c_char,
out_json: *mut *mut c_char,
err_msg: *mut *mut c_char,
) -> c_int;
#[repr(C)]
pub struct MarqdoHostApi {
pub userdata: *mut c_void,
pub register_fn: Option<
unsafe extern "C" fn(
userdata: *mut c_void,
name: *const c_char,
params: *const c_char,
fn_ptr: PluginFn,
) -> c_int,
>,
pub alloc: Option<unsafe extern "C" fn(n: usize) -> *mut c_void>,
pub free: Option<unsafe extern "C" fn(p: *mut c_void)>,
pub host_query: Option<HostQueryFn>,
}
pub static mut HOST_FREE: Option<unsafe extern "C" fn(*mut c_void)> = None;
pub static mut HOST_ALLOC: Option<unsafe extern "C" fn(usize) -> *mut c_void> = None;
pub static mut HOST_QUERY: Option<HostQueryFn> = None;
pub static mut HOST_USERDATA: *mut c_void = ptr::null_mut();
/// Duplicate `s` into host-allocated memory (the host frees it).
pub unsafe fn host_strdup(s: &str) -> *mut c_char {
let alloc = HOST_ALLOC.expect("host alloc");
let bytes = s.as_bytes();
let p = alloc(bytes.len() + 1) as *mut u8;
if p.is_null() {
return ptr::null_mut();
}
std::ptr::copy_nonoverlapping(bytes.as_ptr(), p, bytes.len());
*p.add(bytes.len()) = 0;
p as *mut c_char
}
pub fn set_out(out: *mut *mut c_char, s: &str) {
if out.is_null() {
return;
}
unsafe {
*out = host_strdup(s);
}
}
pub fn set_err(err: *mut *mut c_char, s: &str) {
if err.is_null() {
return;
}
unsafe {
*err = host_strdup(s);
}
}
/// Parse the JSON args object handed to a plugin entry point.
pub fn parse_args(args_json: *const c_char) -> Result<Value, String> {
if args_json.is_null() {
return Ok(json!({}));
}
let s = unsafe { CStr::from_ptr(args_json) }
.to_str()
.map_err(|_| "args not utf-8".to_string())?;
if s.trim().is_empty() {
return Ok(json!({}));
}
serde_json::from_str(s).map_err(|e| e.to_string())
}
/// Write a plugin result (or error) back through the ABI pointers.
pub fn reply(out_json: *mut *mut c_char, err_msg: *mut *mut c_char, r: Result<Value, String>) -> c_int {
match r {
Ok(v) => {
set_out(out_json, &v.to_string());
0
}
Err(e) => {
set_err(err_msg, &e);
1
}
}
}
/// Ask the host for a builtin with no arguments (`host_query`).
pub fn host_query_json(name: &str) -> Result<Value, String> {
host_query_json_with(name, &json!({}))
}
/// Ask the host for a builtin, passing `args` as its argument object.
pub fn host_query_json_with(name: &str, args: &Value) -> Result<Value, String> {
let q = unsafe { HOST_QUERY }.ok_or("host_query unavailable")?;
let n = CString::new(name).map_err(|e| e.to_string())?;
let a = CString::new(args.to_string()).map_err(|e| e.to_string())?;
let mut out: *mut c_char = ptr::null_mut();
let mut err: *mut c_char = ptr::null_mut();
let rc = unsafe { q(HOST_USERDATA, n.as_ptr(), a.as_ptr(), &mut out, &mut err) };
if rc != 0 {
return Err(take_host_string(err).unwrap_or_else(|| "host_query failed".into()));
}
let text = take_host_string(out).ok_or("host_query returned nothing")?;
serde_json::from_str(&text).map_err(|e| e.to_string())
}
/// Copy a host-allocated C string into a Rust `String` and free the original.
pub fn take_host_string(p: *mut c_char) -> Option<String> {
if p.is_null() {
return None;
}
let s = unsafe { CStr::from_ptr(p) }
.to_string_lossy()
.into_owned();
if let Some(free) = unsafe { HOST_FREE } {
unsafe { free(p as *mut c_void) };
}
Some(s)
}
fn register(host: &MarqdoHostApi, name: &str, params: &str, f: PluginFn) -> c_int {
let Some(reg) = host.register_fn else {
return 1;
};
let n = CString::new(name).unwrap();
let p = CString::new(params).unwrap();
unsafe { reg(host.userdata, n.as_ptr(), p.as_ptr(), f) }
}
/// Store the host callbacks and register every entry point.
pub unsafe fn init_plugin(host: *const MarqdoHostApi, regs: &[(&str, &str, PluginFn)]) -> c_int {
if host.is_null() {
return 1;
}
let host = &*host;
HOST_ALLOC = host.alloc;
HOST_FREE = host.free;
HOST_QUERY = host.host_query;
HOST_USERDATA = host.userdata;
for (name, params, f) in regs {
if register(host, name, params, *f) != 0 {
return 1;
}
}
0
}
/// Emit the four `#[no_mangle]` exports every plugin `.so` must provide,
/// wiring `marqdo_plugin_init` to the given registration table.
#[macro_export]
macro_rules! marqdo_plugin {
($version:expr, [ $( ($name:expr, $params:expr, $f:expr) ),* $(,)? ]) => {
#[no_mangle]
pub unsafe extern "C" fn marqdo_plugin_abi_version() -> u32 {
$version
}
#[no_mangle]
pub unsafe extern "C" fn marqdo_plugin_shutdown() {}
#[no_mangle]
pub unsafe extern "C" fn marqdo_plugin_init(
host: *const $crate::MarqdoHostApi,
) -> i32 {
$crate::init_plugin(host, &[ $( ($name, $params, $f as $crate::PluginFn) ),* ])
}
};
}
+2 -2
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo-wasm"
version = "1.3.0"
version = "2.9.1"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo interpreter as WebAssembly (browser host bridge)"
@@ -12,4 +12,4 @@ crate-type = ["cdylib", "rlib"]
[dependencies]
marqdo = { path = "../..", default-features = false, features = ["wasm-core"] }
serde_json = "1"
serde_json = "1"
Regular → Executable
+3 -1
View File
@@ -11,7 +11,7 @@ Raw `cdylib` exports — no `wasm-bindgen` CLI required.
```bash
# from repo root (C5 size profile)
marqdo wasm build -o examples/browser-hello
marqdo call skills/marqdo-dev/index.mq.md build_browser --effects plugin,process.exec,fs.write --fs-root . --json
# or:
cargo build -p marqdo-wasm --target wasm32-unknown-unknown --profile release-wasm
```
@@ -19,3 +19,5 @@ cargo build -p marqdo-wasm --target wasm32-unknown-unknown --profile release-was
Prints size in KiB; runs `wasm-opt -Oz` when Binaryen is on `PATH`.
See [doc/design/browser-marqdo-wasm.md](../../doc/design/browser-marqdo-wasm.md).
Use the maintained [browser-app](../../examples/browser-app/index.mq.md) for a runnable native Document and browser program. The ABI counter fixture lives in tests/wasm/counter.mq.md, with no independent HTML demo host. The former browser-hello and browser-media directories were retired in 2.7.0; their host capabilities remain documented in lib/browser.mq.md.
+43 -19
View File
@@ -228,28 +228,52 @@ function applyStyle(el, styleVal) {
}
export function renderListItems(spec) {
const tag = String(spec.tag || "li");
const rootTag = String(spec.tag || "li");
const items = Array.isArray(spec.items) ? spec.items : [];
return items
.map((it) => {
if (it == null) return "";
if (typeof it === "string" || typeof it === "number") {
return `<${tag}>${escapeHtml(String(it))}</${tag}>`;
}
if (!isPlainObject(it)) return "";
const text = it.text != null ? String(it.text) : it.html != null ? null : "";
const cls = it.class != null ? ` class="${escapeAttr(String(it.class))}"` : "";
let attrs = "";
if (isPlainObject(it.attrs)) {
for (const [k, v] of Object.entries(it.attrs)) {
if (v === null || v === false) continue;
attrs += ` ${escapeAttr(k)}="${escapeAttr(String(v))}"`;
let count = 0;
const render = (item, fallbackTag, depth) => {
if (depth > 32 || ++count > 10000) throw new Error("render_list: structural limit exceeded");
if (item == null) return "";
if (typeof item !== "string" && typeof item !== "number" && !isPlainObject(item)) return "";
const record = isPlainObject(item) ? item : { text: String(item) };
const tag = String(record.tag || fallbackTag);
if (!/^[a-z][a-z0-9-]*$/i.test(tag) ||
/^(script|style|iframe|object|embed|link|meta|base)$/i.test(tag)) {
throw new Error("render_list: unsupported element name");
}
let attrs = record.class != null ? ` class="${escapeAttr(String(record.class))}"` : "";
if (isPlainObject(record.attrs)) {
for (const [key, value] of Object.entries(record.attrs)) {
if (!/^[a-z_:][a-z0-9_.:-]*$/i.test(key) || /^on/i.test(key)) {
throw new Error("render_list: invalid attribute name");
}
if (value === null || value === false) continue;
if (!["string", "number", "boolean"].includes(typeof value)) throw new Error("render_list: attributes must be scalar");
if (/^(href|src|action|formaction)$/i.test(key) &&
/^[\s\u0000-\u0020]*(javascript|vbscript|data)[\s\u0000-\u0020]*:/i.test(String(value))) {
throw new Error("render_list: unsupported URL");
}
attrs += ` ${key}="${escapeAttr(String(value))}"`;
}
const inner = it.html != null ? String(it.html) : escapeHtml(text ?? "");
return `<${tag}${cls}${attrs}>${inner}</${tag}>`;
})
.join("");
}
let inner;
if (record.children != null) {
if (!Array.isArray(record.children) || record.text != null || record.html != null) {
throw new Error("render_list: children must be an unambiguous record list");
}
inner = record.children.map(child => render(child, "span", depth + 1)).join("");
} else {
// Preserve the existing explicit HTML escape hatch. Ordinary business
// values use text/children and never become source or markup.
inner = record.html != null ? String(record.html) : escapeHtml(String(record.text ?? ""));
}
if (/^(input|img|br|hr|area|col|source|wbr)$/i.test(tag)) {
if (inner) throw new Error("render_list: void elements cannot have content");
return `<${tag}${attrs}>`;
}
return `<${tag}${attrs}>${inner}</${tag}>`;
};
return items.map(item => render(item, rootTag, 0)).join("");
}
function escapeHtml(s) {
View File
File mode changed.
Regular → Executable
View File
File mode changed.
Vendored Regular → Executable
View File
File mode changed.
+237
View File
@@ -1,3 +1,240 @@
marqdo (2.9.1-1ppa1) noble; urgency=medium
* Release 2.9.1; see the reviewed upstream CHANGELOG.
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Wed, 18 Nov 2026 18:43:10 +0800
marqdo (2.8.0-1ppa1) noble; urgency=medium
* Release 2.8.0; see the reviewed upstream CHANGELOG.
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Wed, 18 Nov 2026 10:24:08 +0800
marqdo (2.7.1-1ppa2) noble; urgency=medium
* Release 2.7.1; see the reviewed upstream CHANGELOG.
* Stop reapplying the engineering compatibility fix already in upstream.
* Include cached orig bytes until publication is confirmed by Launchpad.
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Wed, 11 Nov 2026 00:03:29 +0800
marqdo (2.7.0-1ppa2) noble; urgency=medium
* Repair engineering plugin compatibility for this 2.7.0 release.
* Keep the accepted upstream orig archive; carry the fix as a quilt patch.
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Tue, 10 Nov 2026 17:53:03 +0800
marqdo (2.7.0-1ppa1) noble; urgency=medium
* Release 2.7.0; see the reviewed upstream CHANGELOG.
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Tue, 10 Nov 2026 16:40:29 +0800
marqdo (2.6.0-1ppa1) noble; urgency=medium
* Executable standard/extension handbooks and practical file/data/task tools.
* Readable View action notes, knowledge contracts and offline reader support.
* Preserve effect, platform and source compatibility boundaries.
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sun, 08 Nov 2026 23:01:35 +0800
marqdo (2.5.1-1ppa1) noble; urgency=medium
* Marqdo 2.5.1: exact source anchors, flowing annotation curves,
staggered margin notes, connector avoidance and a labeled toolbar.
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 07 Nov 2026 13:05:55 +0800
marqdo (2.5.0-1ppa1) noble; urgency=medium
* Marqdo 2.5.0: redesigned document reader, margin execution annotations,
offline math/assets, navigation/search, and consistent live result refresh.
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 07 Nov 2026 10:00:00 +0800
marqdo (2.4.0-1ppa1) noble; urgency=medium
* Marqdo 2.4.0: oracle journal as language values (foreign.oracle_journal /
replay_check), bytecode/frontend hardening, MSRV 1.81 OnceLock wait fix.
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Fri, 06 Nov 2026 15:15:00 +0800
marqdo (2.3.0-1ppa1) noble; urgency=medium
* Marqdo 2.3.0: Strong foreign session — opaque Handle, affine close,
replay_check vs oracle journal, table arity refuse, Omega V_safe gate.
-- Marqdo Maintainers <cflmy@users.noreply.github.com> Sat, 01 Nov 2026 14:45:00 +0800
marqdo (2.2.2-1ppa1) noble; urgency=medium
* Marqdo 2.2.2: V_safe JSON integer contract on foreign/json bridge —
refuse integers outside +/- (2^53-1); wide ints via decimal string.
-- Marqdo Maintainers <noreply@marqdo.com> Sat, 01 Nov 2026 09:45:00 +0800
marqdo (2.2.1-1ppa1) noble; urgency=medium
* Marqdo 2.2.1: fix view/static-export outline rail under document
(occlusion doc-block close + panel container query layout).
-- Marqdo Maintainers <noreply@marqdo.com> Fri, 30 Oct 2026 11:45:00 +0800
marqdo (2.2.0-1ppa1) noble; urgency=medium
* Marqdo 2.2.0: marqdo call runs one named function in any .mq.md.
The same file stays the document, the knowledge and the program.
Tree and bytecode both execute that function. External calls stay
pure: write, process, network and plugin stay off by default.
-- Marqdo Maintainers <noreply@marqdo.com> Fri, 30 Oct 2026 09:20:00 +0800
marqdo (2.1.5-1ppa2) noble; urgency=medium
* Rebuild 2.1.5 against Launchpad (previous 1ppa1 failed with no build log).
-- Marqdo Maintainers <noreply@marqdo.com> Tue, 27 Oct 2026 09:35:49 +0000
marqdo (2.1.5-1ppa1) noble; urgency=medium
* Marqdo 2.1.5: agent reliability workbench — ResourceView / ToolSpec /
CheckpointV2 / EffectLedger; EKC ir.json warm-load; web short/read lanes.
-- Marqdo Maintainers <noreply@marqdo.com> Tue, 27 Oct 2026 07:39:08 +0000
marqdo (2.1.4-1ppa1) noble; urgency=medium
* Marqdo 2.1.4: default isolated HTTP execute (ADR 0009) — Supervisor
worker pool for execute/sse-live/stream, /_runtime/* control plane,
MR-01 dual 60s SSE gold sample, runtime.isolated_execution=1.
-- cflmy <pingan@cflmy.cn> Mon, 26 Oct 2026 10:00:00 +0000
marqdo (2.1.3-1ppa1) noble; urgency=medium
* Marqdo 2.1.3: workbench M00–M06 runtime contracts (ModelSelection,
RunContext, DocumentView, usage null≠0, LLM selection/cancel,
agent.step selection e2e, view document CLI, live smoke).
-- cflmy <pingan@cflmy.cn> Sun, 25 Oct 2026 15:20:00 +0000
marqdo (2.1.2-1ppa1) noble; urgency=medium
* Marqdo 2.1.2: executable-knowledge F0–F3 + View V0–V3 release bar
(evidence/closure, verify gates, bind/reuse_execute, document.extract,
KnowledgePresentation, SSE page_token, upload max_bytes).
-- cflmy <pingan@cflmy.cn> Sat, 24 Oct 2026 14:50:00 +0000
marqdo (2.1.1-1ppa1) noble; urgency=medium
* Marqdo 2.1.1: executable-knowledge spine (BoundCall, NarrativeRef,
sources/applicability, generation CURRENT + closure digests).
-- cflmy <pingan@cflmy.cn> Fri, 23 Oct 2026 15:40:00 +0000
marqdo (2.1.0-1ppa1) noble; urgency=medium
* Marqdo 2.1.0: file-scoped Occlusion is the default syntax; migrated
standard/extension libraries and executable-knowledge projections.
-- cflmy <pingan@cflmy.cn> Fri, 23 Oct 2026 12:00:00 +0000
marqdo (2.0.0-1ppa1) noble; urgency=medium
* Marqdo 2.0.0: Occlusion syntax — [description](payload), where the
bracketed label is inert prose and the parenthesized payload is the
only executed part. Adds paren-call arguments, access() element
access, occlusion loops, marqdo labels (two-tier search + debt
ratchet), marqdo migrate labels, and label.missing / empty_payload /
ref_dangling diagnostics; view renders labels as prose, payloads as
code, stubs with a badge. 80 corpus files migrated.
-- cflmy <pingan@cflmy.cn> Thu, 22 Oct 2026 16:30:00 +0800
marqdo (1.5.2-1ppa1) noble; urgency=medium
* Marqdo 1.5.2: Foreign v3 P0/P1 — raw stdin with per-cell inputs and
interrupt, plan generation/add/remove/value API, snapshot
export/import/replay, view capture for static export, explicit Persist
button, nested plan boundary.
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 15:00:00 +0800
marqdo (1.5.1-1ppa1) noble; urgency=medium
* Marqdo 1.5.1: View static/live execution path unified; foreign value
passing into multi-kernel sessions; cell stdin for live/static/persistent
kernels; build-time execution with stdout injection in static exports;
runnable foreign writeback example; writeback block grouping.
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 22:00:00 +0800
marqdo (1.5.0-1ppa1) noble; urgency=medium
* Marqdo 1.5.0: Foreign kernels v2 (structured invoke, JSON calls,
parallel fan-out, persistent Python/Node kernels, explicit state
bridge) and document-native notebooks in view; high-contrast
light/dark view themes, resizable code/output panes, OKF/EKC and
Python examples on the user site. Fixes branch-local variables
leaking into required constructor parameters.
-- cflmy <pingan@cflmy.cn> Sun, 18 Oct 2026 03:30:00 +0800
marqdo (1.4.6-1ppa1) noble; urgency=medium
* Marqdo 1.4.6: Promote a bare self-increment to a required parameter.
The first bold assignment LHS is a declaration (design §8.2); a missing
argument reports missing argument for parameter, not undefined variable.
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 23:56:00 +0800
marqdo (1.4.5-1ppa1) noble; urgency=medium
* Marqdo 1.4.5: Streamable HTTP MCP (agent_mcp_serve transport=http);
web invoke Bearer/X-Api-Key inject + unauthorized→401; openai/agent
field access via json.get (no footnote hard-fail).
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 17:40:00 +0800
marqdo (1.4.4-1ppa1) noble; urgency=medium
* Marqdo 1.4.4: Soft LLM transport errors (structured status=error);
ext/ai table-first refactor (no json.set glue).
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 14:40:00 +0800
marqdo (1.4.2-1ppa1) noble; urgency=medium
* Marqdo 1.4.2: Agent/LLM optimize O1–O5 — sandbox trial opt-in,
promote sandbox proof, step_route/EFI/cost, style lint, quarantine.
-- cflmy <pingan@cflmy.cn> Fri, 16 Oct 2026 11:51:05 +0800
marqdo (1.4.1-1ppa1) noble; urgency=medium
* Marqdo 1.4.1: View annot leaders — SVG mid-to-mid (mark bottom-center
to chip top-center), unify frame chip ids, L-to-R chip density.
-- cflmy <pingan@cflmy.cn> Thu, 15 Oct 2026 20:40:00 +0800
marqdo (1.4.0-1ppa1) noble; urgency=medium
* Marqdo 1.4.0: Prose-unified control flow — block formula % marqdo: var=,
arm/loop narrative + foreach sugar, image writeback ![marqdo-out](...),
view inferred-param values; welcome pages on v0.3 prose surface.
-- cflmy <pingan@cflmy.cn> Wed, 15 Oct 2026 15:53:00 +0800
marqdo (1.3.3-1ppa1) noble; urgency=medium
* Marqdo 1.3.3: Browse document-surface Structure — narration-preserving
markers, branch/loop frame pickers, ViewExecutionReport JSON; static
view output / gh-pages share the same render path as live view.
-- cflmy <pingan@cflmy.cn> Wed, 15 Oct 2026 13:20:00 +0800
marqdo (1.3.0-1ppa1) noble; urgency=medium
* Marqdo 1.3.0: Engineering Knowledge Compiler (EKC) — L0–L4 catalog,
Vendored Regular → Executable
View File
File mode changed.
Vendored Regular → Executable
View File
File mode changed.
+18
View File
@@ -0,0 +1,18 @@
Description: Use stable Option map_or in the engineering release boundary
Author: Marqdo Maintainers <cflmy@users.noreply.github.com>
Forwarded: not-needed
Last-Update: 2026-11-10
diff --git a/plugins/engineering/src/lib.rs b/plugins/engineering/src/lib.rs
index 6891f01..f0c5ffc 100644
--- a/plugins/engineering/src/lib.rs
+++ b/plugins/engineering/src/lib.rs
@@ -283,7 +283,7 @@ fn r2_settings(root:&Path)->Result<BTreeMap<String,String>,String> {
}
}
for k in ["R2_ENDPOINT","R2_BUCKET","R2_ACCESS_KEY_ID","R2_SECRET_ACCESS_KEY"] {
- if settings.get(k).is_none_or(String::is_empty) {return Err(format!("missing {k}; configure ~/.marqdo/r2.env"));}
+ if settings.get(k).map_or(true, String::is_empty) {return Err(format!("missing {k}; configure ~/.marqdo/r2.env"));}
}
Ok(settings)
}
Vendored Executable
+2
View File
@@ -0,0 +1,2 @@
# engineering-stable-option.patch
# The fix is already in upstream 2.7.1.
Vendored Regular → Executable
View File
File mode changed.
Vendored Regular → Executable
View File
File mode changed.
Regular → Executable
+54 -5
View File
@@ -13,10 +13,29 @@
## 当前文档
> **可执行知识下一阶段的阅读顺序**:[原始意图 009](next/009.md) → [文档原生开发指导](design/document-native-development-guide.md)(作者体验、语法审查结论、AI 工作协议)→ [详细开发规范](next/Marqdo_Executable_Knowledge_Development.md)(目标语义与工程约束)→ [缺口与交付路线](roadmap/executable-knowledge-gaps-2026-10-23.md)(现状证据、S0–S6)。指导文档修订作者负担、场景政策和交付次序;不得把所有内部治理字段变成作者必填项。与之冲突的早期设计只作历史参考,设计目标不等于已实现能力。
>
> **可执行知识门禁**:[tests/executable_knowledge/](../tests/executable_knowledge/README.md) — S0–S2 BoundCall / 效应 / MLSP bind,以及后续 NarrativeRef、来源与整代投影子集;`cargo test --test executable_knowledge --locked`(CI:`.github/workflows/executable-knowledge.yml`)。`status: design` / 预期失败与已实现分开报告。
| 文档 | 摘要 |
|------|------|
| [design/markdown-mapping.md](design/markdown-mapping.md) | **v0.2 语法宪法(现行运行时)** |
| [design/markdown-mapping-v0.3.md](design/markdown-mapping-v0.3.md) | **v0.3 草案:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断** |
| [design/prove-cli.md](design/prove-cli.md) | **Proposed:`marqdo prove` 设计**;SKILL 控制平面 → Lean 4、函数级定理表与语言习惯审查、离线判定片段、`proved`/`checked` 诚实性契约、无公理 TCB |
| [roadmap/prove.md](roadmap/prove.md) | **Proposed:`marqdo prove` 实施路线**;P0–P3 周计划、8 类测试矩阵(单调性/一致性/不执行/子集/定理表/CLI/缓存/编码)、CI 与验收证据 |
| [adr/0010-skill-proof-boundary.md](adr/0010-skill-proof-boundary.md) | **ADR 0010**:定理表作为契约表第四角色、可证子集封闭、Lean 为唯一 `proved` 来源、顾问式不强制 |
| [roadmap/agent-reliability-crossrepo-2026-10-27.md](roadmap/agent-reliability-crossrepo-2026-10-27.md) | **Proposed:跨仓 Agent 可靠性开发计划**;M-A0–M-A6 ∥ Q-A0–Q-A7 排期、依赖图、F01–F20 映射、MA-T*/QA-* 验收与第一刀切片;协议真源仍见下方设计文档 |
| [design/agent-reliability-tools-resources-2026-10-27.md](design/agent-reliability-tools-resources-2026-10-27.md) | **Proposed:智能体能力补足**;基于 `16f26d7`,增量设计错误恢复、检查点/效应账本、结构化工具、输出通道、上下文与只读资源视图;含跨仓边界、阶段计划和故障验收 |
| [research/agent-capabilities-2026-10-27.md](research/agent-capabilities-2026-10-27.md) | **官方能力调研与源码复核**;OpenAI/Claude/Gemini/LangGraph/Deep Agents/MCP,求道当前问题 F01–F20;区分现有能力、设计推导与待实测项 |
| [design/isolated-web-runtime-development-2026-10-26.md](design/isolated-web-runtime-development-2026-10-26.md) | **隔离执行与响应式 Web 运行时**:进程池、控制/读取分离、取消、事件恢复、发布一致性;实现见 `src/runtime/` |
| [adr/0009-isolated-web-runtime.md](adr/0009-isolated-web-runtime.md) | **ADR 0009**:隔离 Web 运行时决策;金样例通过后替代 ADR 0008 的并行性结论 |
| [跨库缺陷复核(2026-10-26)](../../qdagent/doc/gaps/04-workbench-runtime-and-product-audit-2026-10-26.md) | **最新源码与测试证据**:实际 HTTP 路由、知识发布/阅读断点、旧缺陷处置及 1000 单元编译性能失败;需同级 qdagent checkout |
| [design/qdagent-workbench-runtime-and-view-2026-10-25.md](design/qdagent-workbench-runtime-and-view-2026-10-25.md) | **qdagent 知识工作台框架支持**:M00–M05 合同落地中(`src/workbench/`、MLSP `capabilities` / `view.document` / `view.reference_resolve`、`tests/workbench_contracts.rs`);完整 verified 以切片验收证据为准 |
| [design/view-knowledge-reading-experience-2026-10-24.md](design/view-knowledge-reading-experience-2026-10-24.md) | **View 知识阅读体验重设计(建议)**:正文优先、结构导航、就地知识说明、来源与运行状态、响应式线框、实现契约与验收;含当前呈现和 no-exec 反例 |
| [design/view-readable-actions.md](design/view-readable-actions.md) | **View 阅读优化实现**:动作留在正文、实际逻辑引到侧注、空逻辑明确标识;语法阅读指南、输入输出与依据卡片、单文件依赖分析及浏览器验收 |
| [roadmap/qdagent-knowledge-support-gaps-2026-10-24.md](roadmap/qdagent-knowledge-support-gaps-2026-10-24.md) | **求道知识沉淀与文档编译支撑缺口**:2.1.1 源码复核、来源/依赖失效反例、验证与 Agent 协议、语法提示词、导入底座及跨库分工 |
| [design/document-native-development-guide.md](design/document-native-development-guide.md) | **下一阶段开发指导**:语法审查裁决、正文→命名→复用工作流、AI 上下文与局部编辑、渐进严格、作者成本及 S0–S6 验收 |
| [design/core-surface.md](design/core-surface.md) | **核心构造清单**:v2.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 设计背景**:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断;链接语义以 v2.1 规范和测试为准 |
| [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) | **`#` 对象 / `##` 函数与方法** |
@@ -33,6 +52,7 @@
| [design/keywords.md](design/keywords.md) | **英文最小关键字 / 内置函数** |
| [design/keywords-i18n.md](design/keywords-i18n.md) | **内核中英双名(无需导入;少而精)** |
| [design/module-namespace.md](design/module-namespace.md) | **模块命名空间:导入绑定库名、`库.成员` / `use`(M1+M2 已落地)** |
| [library-development.mq.md](library-development.mq.md) | **可执行库开发指南**:单文件标准库、多文件拓展库、叙述超过 50%、标题下参数与返回表、句中赋值/返回和遮蔽调用;含真实调用及失败场景 |
| [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/网络/数学/外联/插件** |
@@ -48,7 +68,13 @@
| [roadmap/stdlib-mid.md](roadmap/stdlib-mid.md) | **Mid M1–M6 路线(done)** |
| [roadmap/stdlib-mid2.md](roadmap/stdlib-mid2.md) | **Mid2 M7–M10 路线(规划)** |
| [design/stdlib-math.md](design/stdlib-math.md) | **数学库(数值/随机/作图/轻量求解)** |
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— 已落地** |
| [design/stdlib-foreign.md](design/stdlib-foreign.md) | **外联胶水(\`\`\`lang 具名块)— v1 已落地** |
| [design/foreign-kernel.md](design/foreign-kernel.md) | **外联内核:持久内核 / JSON 桥 / 状态桥 / 安全** |
| [design/notebook-session.md](design/notebook-session.md) | **文档会话:cell / kernel / step / journal / 状态面板** |
| [design/notebook-syntax.md](design/notebook-syntax.md) | **文档原生 notebook 语法:内核表 / 会话表** |
| [research/foreign-notebook-decisions.md](research/foreign-notebook-decisions.md) | **外联 / notebook 决策记录(逐问逐答)** |
| [roadmap/foreign-v2.md](roadmap/foreign-v2.md) | **外联内核 v2 路线(F0–F4)** |
| [roadmap/notebook-session.md](roadmap/notebook-session.md) | **文档会话路线(D0–D5)** |
| [design/ext-abi.md](design/ext-abi.md) | **原生插件 C ABI v1**(`lib/plugin`) |
| [design/ext-llm.md](design/ext-llm.md) | **官方扩展 `ext/llm`(OpenAI 兼容)** |
| [design/ext-agent.md](design/ext-agent.md) | **官方扩展 `ext/agent`(文档驱动:单步 / 多步工作簿 + 自写回;废弃 thin TOOL 循环)** |
@@ -57,7 +83,7 @@
| [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 验收) |
| [design/ext-web-go-rewrite.md](design/ext-web-go-rewrite.md) | **`plugins/web` Go 全量重写**(多语言 ABI · 网页制备完备 · 独立工作流验收) |
| [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、布局…) |
@@ -90,10 +116,33 @@
| [research/agent-frameworks-and-marqdo.md](research/agent-frameworks-and-marqdo.md) | 主流智能体框架 vs Marqdo 优势 |
| [research/agent-framework-gaps-after-a4.md](research/agent-framework-gaps-after-a4.md) | **`ext/agent` A0–A4 之后缺口盘点** |
| [research/agent-framework-2026-09.md](research/agent-framework-2026-09.md) | **2026-09 刷新:宪法优先 Wave B** |
| [research/ai-agent-sandbox.md](research/ai-agent-sandbox.md) | **AI 扩展沙盒调研**:Wasm / OS / CoW / symlink 对比与 Marqdo 分层推荐 |
| [design/ext-ai-sandbox.md](design/ext-ai-sandbox.md) | **`ext/ai/sandbox` 设计锁定**:CoW · 能力表 · agent ABI(非 stdlib) |
| [roadmap/ext-ai-sandbox.md](roadmap/ext-ai-sandbox.md) | **`ext/ai/sandbox` 实现里程碑** S0–S4 |
| [research/ai-agent-llm-optimize-2026-10.md](research/ai-agent-llm-optimize-2026-10.md) | **2026-10 调研**:代码即文档×OKF×沙盒下的 Agent/LLM 优化与问题分析 |
| [design/ext-ai-optimize.md](design/ext-ai-optimize.md) | **Accepted**:Agent/LLM 优化 O1–O5 locked |
| [roadmap/ext-ai-optimize.md](roadmap/ext-ai-optimize.md) | **O1–O5 实现路线**(沙盒接入→证明晋升→路由/成本→lint→隔离) |
| [research/ext-hosting-gaps.md](research/ext-hosting-gaps.md) | **宿主集成缺口**:同域 SSE 中继 · HTTP→`##` · MCP Server · 副端口 · 跨模块 db/corpus |
| [design/ext-hosting-fill.md](design/ext-hosting-fill.md) | **宿主缺口补齐设计**(`ext/web` proxy/invoke · `ext/ai` mcp_server) |
| [roadmap/ext-hosting.md](roadmap/ext-hosting.md) | **宿主集成 H0–H4**(规划) |
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** |
| [design/code-volume-audit.md](design/code-volume-audit.md) | **代码体量审计**:53k 行的构成 · 已清 14.5k 冗余 · 剩余是特性面 · 可精简项与风险 |
| [design/link-syntax.md](design/link-syntax.md) | **链接语法(v2.1 设计声明)**:链接即调用 · `()` 与 `**代码**` 同权 · `类.函数` 跨文档 · LinkInfo · view 调用点 · 图边 · lock · L0–L5 开发指导 |
| [design/executable-knowledge-system.md](design/executable-knowledge-system.md) | **可执行知识系统(v2.1 重构草案)**:每个 `[]()` 都是命名的可执行知识步骤 · 取元/推导/循环/调用/叙述统一建图 · 跨文件稳定寻址 · check/view/verify/impact 闭环 |
| [next/Marqdo_Executable_Knowledge_Development.md](next/Marqdo_Executable_Knowledge_Development.md) | **可执行知识系统详细开发规范**:以 `next/009.md` 及两份附属文档为真实意图基线,冻结统一语义 IR、稳定寻址、绑定/验证/锁定、EKC/Agent 集成、迁移路线与验收矩阵 |
| [next/Marqdo_Executable_Knowledge_Testing.md](next/Marqdo_Executable_Knowledge_Testing.md) | **可执行知识语法测试与兼容性规程**:标准库、扩展库、CLI、Tree/Bytecode 的仓库级门禁 |
| [roadmap/executable-knowledge-gaps-2026-10-23.md](roadmap/executable-knowledge-gaps-2026-10-23.md) | **v2.1 现状与规划缺口审计(方向修订)**:保留 G01–G12 代码证据,以可读步骤、确定执行、早期 AI 复用和局部修改重排 S0–S6,严格治理按场景增加 |
| [../tests/executable_knowledge/README.md](../tests/executable_knowledge/README.md) | **S0 作者基线门禁**:六类任务语料、作者成本计数、预期失败与 Bytecode 同名误连缺陷指纹 |
| [design/knowledge-layers.md](design/knowledge-layers.md) | **知识分层(语法评审)**:原始语料 / 本体 / 可执行知识 / 调用面 · 单体知识类 vs 运行时实例 · `# 李白 = > 诗人` · 出处/还原验证 · EKC 映射 |
| [design/occlusion-description-and-search.md](design/occlusion-description-and-search.md) | **遮蔽描述与两级检索**:内置词表=范例/默认,参数=扩展 · 空载荷一律 warning · 申报习惯 |
| [design/occlusion-syntax.md](design/occlusion-syntax.md) | **遮蔽语法总纲(实施依据)**:`[描述](实现)` 的目的/语义/新鲜度校验 + M0–M8 计划 |
| [design/label-freshness-and-repair.md](design/label-freshness-and-repair.md) | 标签过期检测:L1 引用一致性 · 指纹台账 · LLM 复核 · MLSP 修复回路 |
| [design/warning-fatigue-control.md](design/warning-fatigue-control.md) | 防警告疲劳:stale 是变更报告而非扫描报告 · 分级/聚合/会话末汇总 |
| [design/staleness-providers.md](design/staleness-providers.md) | 变更检测不依赖 git:T0/T1 零依赖 + T2/T3 可选 provider |
| [design/t1-session-staleness.md](design/t1-session-staleness.md) | 会话内陈旧检测:为何模型在结构上收不到重复警告 |
| [tutorial/15-常见陷阱.md](tutorial/15-常见陷阱.md) | **使用向陷阱手册**:行首数字、跨函数作用域、空格函数名、导入路径、`table.put` 非原地(1.5.2 实测) |
| [research/qdagent-refactor-defects-2026-10.md](research/qdagent-refactor-defects-2026-10.md) | **qdagent 重构期缺陷实录 D1–D7**(沙箱 profile 不生效 · 全角 CALL 静默丢失 …) |
| [research/occlusion-vs-executable-knowledge-2026-10.md](research/occlusion-vs-executable-knowledge-2026-10.md) | **遮蔽 vs 可执行知识复核**:v2.0.0 的 `[]()` 只做了呈现层 · 两文档例子实测不可执行 · `check`/`labels`/图边工程漂移证据 · 原始设计=类-函数调用(见 link-syntax) |
| [roadmap/ext-agent-optimize.md](roadmap/ext-agent-optimize.md) | **`ext/agent` A0–A4 done · Wave B Active** · 后续优化见 [ext-ai-optimize](roadmap/ext-ai-optimize.md) O 波次 |
金样例与集成测试:[`tests/`](../tests/)。面向访客的可执行文档:[`public/`](../public/)。Spike 存档:[`spike/`](../spike/)。
View File
File mode changed.
View File
File mode changed.
View File
File mode changed.
Regular → Executable
+2
View File
@@ -1,5 +1,7 @@
# ADR 0004:网络拓展库原生实现改为 Go
历史说明(2026-11-10):下文业务站点仅记录当时决策背景,相关工程已移出本仓库;当前验收使用维护中的完整站点、网络站点及隔离测试,见 [当前工作流](../design/ext-web-go-rewrite.md#8-独立工作流与隔离验收)。
| | |
|---|---|
| Status | **Accepted** |
View File
File mode changed.
View File
File mode changed.
View File
File mode changed.
+68
View File
@@ -0,0 +1,68 @@
# ADR 0008:Web 热路径单解释器串行化(设计缺陷与缓解)
| | |
|---|---|
| Status | **Accepted**(缺陷已记录;缓解已落地;真并行见 [ADR 0009](0009-isolated-web-runtime.md)) |
| Date | 2026-10-26 |
| Related | [web-invoke-serialization.md](../design/web-invoke-serialization.md) · [ADR 0009](0009-isolated-web-runtime.md) · ADR [0004](0004-web-plugin-go.md) · ADR [0007](0007-web-document-endpoint.md) · [ext-abi.md](../design/ext-abi.md) · [ext-web-go-rewrite.md](../design/ext-web-go-rewrite.md) |
## Context
- Go `plugins/web` 的 HTTP 服务是**多 goroutine** 的:每个请求可并发进入 `handleInvoke` / `handleInvokeLiveSSE`。
- 每个 Endpoint 最终经 C ABI `host_query("call_lib_path", …)` 回到 Rust 宿主,在**同一个** `HostContext`(Marqdo 解释器状态)上执行作者 `.mq.md`。
- `HostContext` **不是** `Sync`:共享可变会话、库装载、写回、事件总线等状态不能安全地被多线程同时求值。
- 因此宿主用进程级 `INVOKE_LOCK`(`src/host/plugin.rs`)串行化所有来自 worker 线程的 `call_lib_path`。
### 常见误解
> 「web 都是单线程的吗?不能多线程吗?」
| 层 | 并发模型 |
|----|----------|
| Go HTTP / SSE flush / 取消 | **多线程(多 goroutine)** |
| Marqdo 解释器 `call_lib_path` | **单飞(一把全局锁)** |
| 浏览器 UI | 与后端锁无关;但若短 API 同步阻塞等待锁,会表现为「整页卡死」 |
**缺陷不在「HTTP 单线程」,而在「多 HTTP 工作线程共享一个非 Sync 解释器」。**
真并行需要多解释器实例(或可共享的隔离运行时),不是去掉 Go 侧并发。
### 事故形态(已观测)
长对话(`return=sse-live` / `stream:true`)在 `CallLibPath` 期间一直持有 `INVOKE_LOCK`。并发的短路由(如 `/v1/models`、设置页探测)在旧实现里对锁 **无限期** `lock()`,HTTP 挂起 → 前端 `fetch` 无超时 → 页面无响应。重启进程可恢复,但属于运维掩盖,不是正确错误处理。
## Decision
1. **承认并文档化**本限制为宿主架构缺陷(单 `HostContext` + 全局 `INVOKE_LOCK`),不得再被表述为「web 插件只能单线程」。
2. **缓解(已实现,非根治)**:
- `call_lib_path` 从 worker 进入时用 **限时 try-lock**(默认 `MARQDO_INVOKE_WAIT_MS=1500`),超时返回错误串 `interpreter busy: …`。
- Go `handleInvoke` 将含 `interpreter busy` 的错误映射为 **HTTP 503**,并设 `Retry-After: 2`。
- **禁止**在 SSE 期间把进程级 `MARQDO_INVOKE_WAIT_MS` 拉长:那会让并发短请求重新卡死。
- 长 SSE 在启动时用同一短预算争锁;一旦拿到则持有至调用结束(对话本来就要跑完)。
3. **客户端契约**:短 API 必须有超时与 503 文案;不得假设「任意时刻都能同步进入解释器」。
4. **根治(未决,另案)**:解释器池 / per-request isolate / 可 `Send` 的会话切片。未落地前,产品行为以本 ADR 的 503 语义为准。
## Consequences
### Positive
- 对话进行中,设置/模型列表等短请求约 1.5s 内失败并可读,UI 不再无限挂起。
- 缺陷有名有姓,后续多解释器工作不会被「修好了」的假象挡住。
### Negative / Risks
- 同一进程仍无法真正并行跑两个 Marqdo Endpoint 体;第二个长 SSE 也会在短预算后失败。
- 极短窗口内,短请求若正好撞上锁交接,可能偶发 503(可重试)。
- `MARQDO_INVOKE_WAIT_MS` 是进程环境变量;误设过大仍会复现卡顿。
### Neutral
- Go 多 goroutine、SSE 桥(`MARQDO_EVENT_FORWARD`)、取消令牌(`MARQDO_CANCEL_TOKEN`)保持不变。
- 不改变 Document / Endpoint 作者面(ADR 0007);只约束宿主与 web 插件错误语义。
## Implementation pointers
| 位置 | 职责 |
|------|------|
| `src/host/plugin.rs` → `acquire_invoke_lock` | 限时争锁;失败 `set_err("interpreter busy…")` |
| `plugins/web/.../routes_invoke.go` → `handleInvoke` | `interpreter busy` → 503 + `Retry-After` |
| 设计长文 | [web-invoke-serialization.md](../design/web-invoke-serialization.md) |
+33
View File
@@ -0,0 +1,33 @@
# ADR 0009: Isolated Web Runtime (worker process pool)
| 项目 | 约定 |
|---|---|
| 状态 | **Accepted**;HTTP **execute** 路径正式替代 [ADR 0008](0008-web-invoke-serialization.md) 的并行性结论。`legacy_serial`(未声明且非流式)仍引用 0008 单飞 / 父进程 `CallLibPath`。 |
| 日期 | 2026-10-26(修订 2026-10-27:disconnect≠cancel;control/read/short 无父锁) |
| 设计 | [isolated-web-runtime-development-2026-10-26.md](../design/isolated-web-runtime-development-2026-10-26.md) |
| 金样例 | `tests/isolated_execute_mr01.rs`(MR-01 双 60s SSE + short reads;同文件 MR-02 槽满拒绝;disconnect-keeps-running;control-under-dual-execute) |
## 背景
ADR 0008 确认:Go HTTP 多线程,但所有 Endpoint 共享一把解释器锁与进程级 SSE 桥环境变量。1500ms busy → 503 只是缓解,不是并行。
## 决策
1. **首选架构**:预热的一次性 Marqdo worker 进程池;每个租约独占一个进程与 HostContext。
2. **HTTP 默认**:`class=execute` 或 `return=sse-live` / body `stream:true` → `admit` → `dispatch`(`--call-lib-path` worker);**禁止**父进程 `CallLibPath` / `Setenv` / `legacySSEBridgeMu`。声明的 `short`/`read`/`control` 走父进程短路径(execute 已离进程,父锁通常空闲);未声明非流式 → `legacy_serial`。
3. **控制/读取分离**:`/_runtime/*`(cancel、events、task get)不进入解释器锁。短读勿挤占 execute worker 槽(池默认 2);产品 cancel 优先 `/_runtime`。
4. **订阅 ≠ 取消**:`sse-live` 观察者 `ctx.Done()` 默认**只结束订阅**,不 `runtime.cancel`;后台仍 reap worker 以释放槽。仅显式 header `X-Marqdo-Cancel-On-Disconnect: 1` 才 disconnect=cancel。同步 `waitIsolatedJSON` 可保留 disconnect 取消。重连:`GET /_runtime/tasks/{id}/events` + `Last-Event-ID` / `after_seq`。
5. **协议**:`InvokeRequestV2` / worker env + NDJSON `MARQDO_EVENT_FORWARD` + `--emit-result`(首期);`/_runtime/*` 控制面。
6. **能力探测**:`runtime.isolated_execution=1`、`runtime.task_control_v2`、`runtime.event_replay`、`view.analysis_cache_v2`、`runtime.read_lane=1`(短读不与 execute 抢父锁)。
7. **发布**:`expected_generation` CAS + publish journal;逻辑文档 ID 与物理 generation 路径解耦。
## 后果
- Execute / live SSE 不再抢进程级 SSE 桥;双流可并行(MR-01)。
- 短读走父进程:在 dual execute 下通常仍 200(父锁空闲);勿把 short/read/control 塞进 2 槽 execute 池。
- Legacy 未声明非流式路径仍可走父进程锁(ADR 0008)。
- 产品(qdagent)`turn_events` / Last-Event-ID / cancel CAS 接线由 qdagent 验收;框架侧 disconnect≠cancel 与 `/_runtime` 无锁控制面已落地。
## 验收(摘要)
MR-01 绿:双假上游 60s 流不混字、短读全 200、两 worker `--call-lib-path`、第三路槽满 429/503、`runtime.isolated_execution=1`、`runtime.read_lane=1`。观察者断连后任务仍跑完并可经 `/_runtime` 重放。其余见设计文档 §12。
+79
View File
@@ -0,0 +1,79 @@
# ADR 0010: SKILL 证明边界:定理表、可证子集与顾问式判定
| 项目 | 约定 |
|---|---|
| 状态 | **Accepted(决策已定)**;实现未开始,路线见 [roadmap/prove.md](../roadmap/prove.md) |
| 日期 | 2026-11-13 |
| 设计 | [design/prove-cli.md](../design/prove-cli.md) |
| 相关 | [core-surface.md](../design/core-surface.md)(不新增标记)· [layers.md](../design/layers.md)(Language 层扩表角色)· [contract.rs](../../src/contract.rs)(既有契约表提取)· [replay-policy](../../verification/replay-policy/README.md)(Lean 伴随判定先例) |
## 背景
Agent 改写 SKILL 后,人需要逐行确认"分支是否绕开审核、失败是否被吞掉"。这类**控制平面**性质适合形式化:编排是带条件的有限 DAG,没有死循环、没有指针。同时,把整个 Marqdo 当通用语言编译到 Lean 会立刻撞上字符串/JSON/浮点/IO 的语义鸿沟,收益被稀释。
项目已有一条 Lean 纪律:`verification/replay-policy` 用 Lean 做唯一判定,Rust 不保留第二份实现,缺伴随进程时失败关闭。本 ADR 决定把同样的纪律用于 SKILL 编排,但**降级为顾问式**:证明用于减少审核量,不作为发布门禁。
## 决策
1. **定理是契约表的第四种角色**,不是新标记。
函数体首条可执行语句之前可放一张「定理表」(`定理 | 结论 | 前提 | 策略`),与 `参数`/`返回`/`字段` 表同槽位;解析期提取进 `Function.claims`,从 body 移除,不参与运行。核心标记计数不变,`CORE_CONSTRUCTS` 不增行;`layers.md` 的 Language 清单补记该角色。
2. **可证子集显式封闭**:无 `while`、无递归、无动态派发(插件、变量函数名、`code` 值调用)。越界函数被跳过(`rejected`),不降级成不透明块。外部操作是 `Env := Op → Val` 参数,不是公理;后置条件只能来自 `假设` 表并成为定理前提。
3. **Lean 是唯一能产生 `proved` 的判定器**。离线判定只到 `checked`,且被限制在一个极小的片段(路径枚举、轨迹、字面结果、命题组合、单变量区间),凡是离线判定为真的定理都必须同时生成 Lean 脚本。运行期若 Lean 可用则复核;离线 `checked` 而 Lean 未关闭视为内部错误(`proof.divergence`),以 Lean 为准并退出非零。
4. **顾问式,不强制**。默认退出码只对"作者写下的定理未被关闭"(`unproved`)与工具错误非零;缺工具链、`rejected`、`unverified` 默认 0。需要严格覆盖的调用方显式传 `--require-lean`。规范与技能手册**推荐**在发布 SKILL 前运行,但不设为门禁。
5. **`prove` 不执行被证程序**。只读源码、写缓存与 `--emit` 目录;这一点由测试夹具(带 `fs.write` 的函数)守住。
## 备选与取舍
| 备选 | 否决理由 |
|---|---|
| frontmatter `proof:` 块 | 丢函数作用域与行级锚点;多函数文件无法分派;诊断指不回具体行 |
| `# 证明` 标题 | `#` 是对象、`##` 是函数;新增"标题=命题"破坏"标题即可调用单元"的既有习惯,还会进命名空间 |
| ` ```proof ` 围栏 | 代码围栏必须跟在空赋值后,为写定理先造死变量,比表更别扭;且会被当作可执行值 |
| 普通注释承载定理 | 注释不参与语义,无法可靠区分说明与定理,拿不到行锚点 |
| 旁挂 `.proof.md` | 把真理拆成两份,违背"文档与代码同一份"的项目前提 |
| 细化类型(refinement types) | 语义增量过大,且与既有契约表形成两份作者真相 |
| 强制门禁(proved 才能发布) | 与"降低审核难度"的目标冲突;无 Lean 的团队会绕过工具 |
## 后果
**正面**
- 作者在一个地方写清"这条编排保证什么",机器可判定、行号可定位;
- 定理表与契约表同一提取路径,`check` / `view` / `catalog` 可逐步接入,不产生第二套声明;
- 外部依赖以假设形式显式化,证书是本项目一贯的"可复核证据";
- 不新增核心标记,守卫测试与文档计数不膨胀。
**负面 / 代价**
- 新增一个语言层语义角色与一个 CLI 命令,需要 ADR + 测试 + 文档(本 ADR 即准入材料);
- 离线判定器是新代码,必须长期用 Lean 语料护栏,防止"过度自信";
- 作者可能误以为定理会在运行时生效——需要文档、`view` 与 `check` 三处反复澄清;
- `proved` 容易被读成"整份 SKILL 安全"——README 必须写死"只对陈述负责"。
## 语义增量清单
| 新增 | 是否进运行时 | 说明 |
|---|---|---|
| `Function.claims` | 否 | 与 `Function.contract` 同类的声明元数据 |
| `结果` / `轨迹` 与 `包含` / `长度` / `下标` | 否 | 仅定理作用域;与普通表达式作用域隔离 |
| `check --proof` | 否 | 静态校验,默认关 |
不新增:求值规则、作用域规则、调用约定、核心标记、类型系统扩展。同名遮蔽(参数或局部变量叫 `结果`/`轨迹`)一律报 `proof.name_shadow`,不做隐式优先。
## 验收(摘要)
- 核心表面:`cargo test --test core_surface` 不变红;`CORE_CONSTRUCTS` 计数不变。
- 单调性:语料中每条离线 `checked` 的定理,Lean 均 `proved`;分歧为 0。
- 不执行:带 `fs.write` 的夹具在 `prove` 后无副作用。
- 确定性:同输入两次 `emit` 字节一致。
- 诚实性:文本、JSON、证书三处对 `checked`/`proved` 的措辞一致。
## 未决(不阻塞实现)
- `假设` 表是否需要扩展列(`来源`、`责任方`)。
- `--all` 的聚合粒度(按文件/按函数)。
- 证书是否需要签名,以及签名由谁持有。
+348
View File
@@ -0,0 +1,348 @@
# Marqdo 智能体能力补足:恢复、工具、上下文与资源视图
| 项目 | 约定 |
|---|---|
| 状态 | **Proposed**;本次交付设计,不代表以下新接口已实现 |
| 日期 / 基线 | 2026-10-27(Asia/Shanghai);Marqdo `16f26d7` / 2.1.4;qdagent `68b757e` |
| 调研与现状 | [官方资料与源码证据 F01–F20](../research/agent-capabilities-2026-10-27.md) |
| 产品配套 | [qdagent 智能体能力与预览设计](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级 checkout) |
| 继承 | [ext/agent](ext-agent.md)、[隔离 Web 运行时](isolated-web-runtime-development-2026-10-26.md)、[工作台合同](qdagent-workbench-runtime-and-view-2026-10-25.md) |
## 1. 目标与架构边界
让同一套文档原生 Agent 在模型错误、工具失败、网络中断后有界恢复;让工具可发现、可验证、可审计;让结果同时服务模型上下文与用户阅读。保留 `.mq.md` 工作簿、EKC 与验证证据的权威地位,不把框架改成第二套产品聊天服务。
现有 `src/runtime/` 已实现隔离进程、任务/事件与控制通道,本设计在其上补 Agent 步骤语义。现有 `ext/ai/agent.mq.md` 已有 step/plan/run、CALL/READ、观察压缩,继续扩展。框架不持有求道“笔记”业务表、中文按钮、默认回答字数或具体供应商账户。
| 议题 | Marqdo 所有 | qdagent 所有 |
|---|---|---|
| 恢复 | 错误分类、预算、检查点、工具效应、运行/事件语义 | 恢复按钮、会话关联、凭证修复入口、产品政策 |
| 工具 | ToolSpec/Call/Result、schema、权限执行、并发、MCP 传输 | 业务工具、默认集合、连接配置、用户授权范围 |
| 回答 | 结果分通道、输出预算、角色消息、finish reason | 简洁/标准/详细策略、摘要与产物卡、ASK/BUILD 行为 |
| 资源 | ResourceRef、只读内容/派生预览、定位、转换插件接口 | 笔记/文件/产物 ID 映射、owner 权限、预览组件和布局 |
| 知识 | preflight/reuse/verify/compile、记忆原语 | 何时提议沉淀、用户画像与可见管理 |
| 调试 | span、结构化事件、用量与错误码 | 可读过程、运行详情、产品评测语料 |
```mermaid
flowchart LR
APP[qdagent 产品策略与授权] --> RUN[ext/ai/agent step / plan / run]
RUN --> CTX[ContextPack 与预算]
RUN --> LLM[LLM Adapter]
RUN --> DISPATCH[Tool Dispatcher]
DISPATCH --> LOCAL[受控 Marqdo 函数]
DISPATCH --> MCP[MCP Client]
DISPATCH --> RES[资源读取 / 转换]
RUN --> REC[Checkpoint / Effect Ledger]
REC --> RT[既有 runtime task store / event log]
RUN --> OUTPUT[answer / artifact / progress / diagnostic]
RES --> VIEW[DocumentView / ResourceView]
OUTPUT --> APP
VIEW --> APP
```
## 2. 现状与增量
| 已有能力 | 本轮不能误判为缺失 | 要补的具体语义 |
|---|---|---|
| runtime.task_control_v2/event_replay/read_lane | 不再新建一套队列与 SSE 框架 | Agent 步骤恢复与传输重放的边界 |
| resume_save/load | 不再新建平行 checkpoint 命名空间 | 原子提交、版本摘要、作用域、效应关联 |
| CALL、ARGS、READ、plan patch | 不废弃文档式编排 | 类型化 schema、校验错误、有限修复、稳定 call_id |
| MCP stdio client | 不从零重写连接器 | timeout/cancel、resource、远程 transport 的能力探测 |
| DocumentViewV1 / Locator | 不另写 `.mq.md` 解析器 | 普通资源类型、明确 renderer、历史与相对资源处理 |
| LLM messages/usage | 不把 provider 行为交给产品猜测 | 输出预算、原生工具适配探测、角色边界与分通道 |
新模块路径及协议名以下均是**建议落点**。首批开发先固化 schema 与 fixture,再开放 feature bit;不得只更新 capabilities 把未实现能力标真。
## 3. 错误和恢复合同
### 3.1 ErrorV1
现有字符串错误保留兼容适配,新工具与 Agent 结果返回:
```json
{
"schema": "AgentErrorV1",
"code": "tool.timeout",
"category": "transient",
"stage": "tool",
"message": "读取资源超时",
"retryable": true,
"retry_after_ms": 1200,
"effect_state": "none",
"recovery_action": "retry_step",
"call_id": "call_01",
"details_ref": "resource:diagnostic_01"
}
```
`retryable` 仅是候选信息,最终动作由可信策略结合效应、截止时间、预算、取消状态决定。远端工具声称 readOnly/idempotent 不构成授权依据。凭证和原始堆栈不进入公开 message。
| 错误类别 / 例子 | 框架动作 | 不允许的动作 |
|---|---|---|
| transient:429、部分 5xx、连接失败 | 只在安全步骤重试,遵守 Retry-After | 无限重试、复用同一流片段直接追加 |
| invalid_arguments:schema 不匹配 | 把字段级错误作为 observation,最多 1 次参数修复 | 启动工具后才校验;静默丢弃字段 |
| validation_failed:编译/文档校验 | 保留候选与诊断,局部修复后重新验证 | 将未验证草稿标为成功 |
| context_overflow | 压缩可重建上下文,保留任务/限制/未决效应 | 丢失最新用户指令、授权或版本 |
| auth / forbidden | 直接 needs_input/blocked,交应用处理 | 换身份、扩大范围或匿名绕过 |
| conflict / stale_revision | 重新读取版本并重新规划 | 覆盖用户修改、对写操作盲重试 |
| capability_unavailable | 返回可行替代操作清单 | 假称已搜索、已渲染或已执行 |
| policy_denied | 显式拒绝该动作 | 把限制当工具错误让模型规避 |
| budget_exhausted | 保存状态与已完成结果,返回 partial | 自动增预算或伪造 completed |
| unknown_effect / worker_crash | 对账、查询外部状态,不能判断则 needs_reconciliation | 重跑整个工作簿 |
| cancelled | 停止新调用、保留可读产物、传播取消 | 在后台悄悄修复或恢复 |
初始建议:传输最多 2 次重试(总 3 次尝试),指数退避基准 0.5/1 秒并加 jitter;有 Retry-After 时使用服务端建议并受总 deadline 限制。参数修复最多 1 次,内容修复最多 2 次。预算由应用传入,框架只提供默认上限与执行机制。所有重试、修复和摘要模型调用计入同一成本账本。
错误指纹 `hash(tool_id, normalized_arguments, error_code, relevant_revision)` 连续出现 2 次且没有新证据时中止该策略,允许一次有依据的替代路径;不能通过改写错误文本绕过循环检测。
### 3.2 四类“恢复”必须分开
1. **续订事件**:客户端从 cursor 重放和订阅同一个 task,不发起新推理。
2. **重试步骤**:相同逻辑 operation、同幂等键;新 invocation attempt,复用成功的前序结果。
3. **恢复工作流**:从兼容 checkpoint 建立新 runtime task / attempt,关联 `resumed_from`,不把旧终态改回 running。
4. **重新生成答案**:新的输出版本;已有成功工具结果可复用,用户明确重新执行才重新产生效应。
当前 TaskState 把 interrupted/needs_reconciliation 视为终态,沿用此约定。新增 `AgentRun` 逻辑关联只管理目标和 attempt 链;调度权仍在原 runtime。恢复请求带 `expected_revision`、checkpoint digest 与幂等键,相同请求返回同一新 attempt,冲突返回 409 对应的框架错误。
执行失败不必丢掉有用内容:`outcome.status = succeeded | partial | failed | needs_input | cancelled`,伴随 `answer_ref/artifacts/error/recovery_options`。HTTP 调用成功与 Agent 业务 succeeded 不再混为同一字段。
## 4. 检查点与工具效应
### 4.1 CheckpointV2
在 `plugins/agent/src/resume.rs` 扩展已有实现,统一根目录由宿主提供,客户端不能传任意绝对路径。保留 legacy load,但旧 checkpoint 无效应信息时默认 `manual_review`,不能自动重做写操作。
| 字段组 | 内容 |
|---|---|
| 身份 | schema、checkpoint_id、logical_run_id、task_id、attempt_id、step_id、parent_checkpoint_id |
| 作用域 | principal_ref、workspace_id、session_id、授权 scope digest |
| 输入 | task revision、workbook revision/hash、输入资源 revisions、knowledge generation |
| 运行配置 | ModelSnapshot public ref、tool registry digest、policy revision、runtime compatibility |
| 进度 | completed_steps、pending_operation、observation refs、context summary ref |
| 约束 | 剩余 token/tool/time/cost 预算、deadline、cancel epoch |
| 一致性 | effect ledger watermark、event seq、manifest digest、committed_at |
写入协议:写唯一临时文件→flush/fsync→原子 rename→提交 checkpoint 指针;持久化配置下目录 fsync 按平台支持实现。所有引用 blob 在指针提交前落盘。损坏记录报 `checkpoint.corrupt` 并尝试上一个完整版本,不能读取半个 JSON 当无历史。
恢复前校验身份/授权、源版本、工具 schema 与模型兼容性。权限撤销立即生效;checkpoint 不是永久授权。源文件改变返回 `checkpoint.input_changed`,重新计划受影响步骤,不能偷偷使用最新文件继续旧验证结果。
### 4.2 Effect ledger
```text
prepared → started → committed
↘ failed_no_effect
↘ unknown → reconciled_committed | reconciled_no_effect | needs_input
```
每个 operation 持久记录 `operation_id/idempotency_key/args_digest/resource_scope/expected_revision/effect_class/result_ref`。幂等键作用域是 principal + workspace + logical_run + step + operation,不用随机 attempt ID 替换稳定 operation key。对同 key 不同 payload 拒绝。
读工具可重试;确定幂等写由服务端去重;可补偿写仅在补偿明确安全时执行;未知写先查询 receipt/版本。对外部系统不能承诺通用 exactly-once。关键 crash 窗口是“远端已成功、本地尚未记账”,必须返回 unknown 并对账。
本地文件使用 expected revision + staging + atomic replace;变更提交后检查点失败也靠 operation receipt 恢复。`tool.completed` 必须在结果与 receipt 可读取后提交,再对外发事件。事件发送失败不回滚已发生的业务效应。
不要复制 runtime 事件存储:Agent ledger 与 artifact manifest 是步骤事实,现有 runtime event log 是传输/调度事实;以 ID 关联,采用可重建投影与 outbox。跨 DB/文件不能声称一个事务完成,使用 manifest 提交点和恢复扫描补齐索引。
## 5. 结构化工具与调度
### 5.1 ToolSpecV1
```json
{
"schema": "ToolSpecV1",
"id": "workspace.read",
"version": "1",
"description": "读取授权资源的指定行范围",
"input_schema": {
"type": "object",
"properties": {
"resource_id": {"type": "string"},
"revision": {"type": "string"},
"start_line": {"type": "integer", "minimum": 1},
"max_lines": {"type": "integer", "minimum": 1, "maximum": 500}
},
"required": ["resource_id"],
"additionalProperties": false
},
"output_schema_ref": "ResourceReadV1",
"effect": "read",
"scopes": ["workspace:read"],
"timeout_ms": 10000,
"max_result_bytes": 65536,
"idempotency": "safe",
"concurrency_group": "resource-read",
"availability": "ready"
}
```
定义由宿主/可信模块注册;用户认证、scope 与资源根由宿主注入,不接受模型提供 principal 或任意 root。`read`、`write`、`execute`、`external_write` 是策略分类,不是靠工具命名推断。
ToolCallV1:`call_id/tool_id/tool_version/arguments/operation_id/parent_span_id`。ToolResultV1:`ok/status/summary/structured_content/resources/citations/error/usage/truncated/next_cursor/effect_receipt_ref`。超限结果先写 artifact,再返回摘要和范围读取句柄;不把几十 MB 文本送进 prompt。
### 5.2 一条执行通道
```text
发现 → 加载 schema → schema 校验 → 授权与范围解析 → 预算/取消检查
→ 幂等查询 → 执行 → 结果 schema/大小校验 → receipt/结果提交 → 事件 → observation
```
provider 原生 function call 与文档 `CALL:name + ARGS:{...}` 都归一到该通道。保留旧白名单适配,已有 `.mq.md ##` 可根据形参推导初始 schema,再允许显式描述收紧。转换不允许调用未暴露的框架内部函数。禁止对模型参数使用 eval/任意代码反序列化。
`tools.search` 返回已授权且当前可用的工具摘要;`tools.describe` 按 ID 返回完整 schema。核心 5–8 个工具可常驻,其余按需加载;此数量是产品起始配置,不写死框架。每次真正调用仍重新检查授权;搜索索引可列 unavailable 原因供诊断,但不能让未授权工具名字泄露私有连接信息。
初始支持 JSON Schema 的明确子集并公开能力;不支持的 schema 拒绝注册,不静默放宽。原生工具能力、并行工具调用、图片输入、结构化输出分别探测;纯文本兼容 provider 继续走 CALL,但并发和可靠性承诺按测试能力开放。
### 5.3 并发、MCP 与程序化执行
独立只读调用可并发,默认最多 4 个;修改同一资源的调用串行且用 revision CAS。依赖链、审批与取消检查保持顺序。一个并发调用失败不丢弃其他已成功结果。
MCP 扩展现有 client:先完善 timeout/cancel、错误映射、工具分页与 schema、resource read/link,再按 capability 增加远程 Streamable HTTP 与连接认证。stdio 不应允许模型选择任意宿主可执行文件。连接元数据归应用,凭证通过 secret handle 注入 worker,工具输出和 trace 不记录密钥。
工具 annotations 只是提示,可信策略确定真实效应。外部结果全部为数据,不能提升为 standing/system。MCP resource URI 转成宿主授权 ResourceRef,不允许前端直接请求任意 file:// 或内部网地址。
程序化工具编排和子 Agent 为后续切片:在沙箱中仅暴露注册 dispatcher,逐次执行同样的授权、预算和效应日志;禁止通过一段脚本绕过逐工具控制。子任务继承更小权限和共享总预算,不默认开放写同一资源。
## 6. 输出通道与上下文
### 6.1 AgentOutputV1
```json
{
"schema": "AgentOutputV1",
"status": "succeeded",
"answer": {"format": "markdown", "text": "已整理为三点,完整笔记见右侧。"},
"artifacts": [{"resource_id": "res_note_01", "revision": "sha256:example"}],
"citations": [],
"validation": {"status": "passed", "report_ref": "resource:verify_01"},
"finish_reason": "completed",
"recovery_options": []
}
```
这是结果传输协议,不要求模型每次逐字生成这张 JSON。文档式编排仍可产出 `.mq.md`,框架把稳定产物、摘要与事件归一化。普通文本回答可没有 artifact 和 validation;未运行的内容标 `not_applicable/not_run`,不能填 passed。
channel 至少区分 `answer/artifact/progress/diagnostic`。只有 answer delta 可追加到聊天正文;工作簿 token 和工具日志进入其他通道。进度是可观察动作摘要,不要求或泄露模型内部思维链。
应用传 `ResponsePolicy`:detail level、目标长度、最大输出 tokens、是否允许 artifact、用户显式需求。框架负责 budget 和 finish_reason,中文字符数与最终文案由应用决定。达到 token 上限返回 `length_limited` 和完整/不完整标记,不能裁剪 JSON/代码后假装成功。
优先从已验证产物结构投影摘要。必要时增加一次受预算控制的摘要模型调用;摘要不得新增未经证据支持的结论。修复成功后 accepted candidate、结果正文、artifact revision 与 verification digest 必须全部一致。
### 6.2 ContextPackV2
按优先级组装:可信运行规则→最新用户目标/约束→用户选中资源范围→未决操作/成功步骤摘要→检索证据→近期对话→可回读历史。保持角色结构,不把用户/工具文本简单拼进系统指令。
每个 item 携带 `origin/trust/resource_ref/revision/token_estimate/priority`。预算初值建议保留模型窗口 20% 给输出与协议开销;上下文使用达到可用预算 70% 时触发整理,具体比例配置化。优先剔除可重读的完整工具输出,保留摘要、引用和失败恢复锚点。
Compaction 必须保留:目标、用户限制、当前计划、已完成步骤、待决写入、授权范围、输入版本、已接受产物与引用、余量。summary 绑定其 source event range 和 digest,不能当成新的已验证知识。工具输入过时须重读,不能依赖压缩摘要执行写入。
已有 EKC/agent memory 继续提供知识发现和复用。长期用户记忆的创建/修改/删除政策归 qdagent;网页中的指令不能自动变成长期偏好。
## 7. 统一资源与只读视图
### 7.1 ResourceRefV1 / ResourceViewV1
ResourceRef 统一携带 `resource_id/workspace_id/kind/media_type/revision/digest/title/size/origin/locator`;opaque ID 由宿主映射,不将浏览器 path 直接当文件权限。revision 是内容版本,generation 是知识发布代,两者不混用。
```json
{
"schema": "ResourceViewV1",
"resource": {
"resource_id": "res_01", "workspace_id": "ws_01", "kind": "file",
"revision": "sha256:example", "media_type": "text/markdown", "title": "设计说明"
},
"renderer": {"id": "markdown", "version": "1", "trust": "sanitized"},
"render": {"format": "sanitized_html", "fragment": "<p>正文</p>"},
"outline": [],
"locators": [],
"completeness": "complete",
"no_exec": true,
"diagnostics": [],
"next_cursor": null
}
```
继续把 `.mq.md` 交 `view.document`,ResourceView 只包装/扩展,不能另解释一套 Marqdo 语义。普通 `.md/.txt/代码/JSON/CSV` 走媒体类型处理,避免全仓语义编译。浏览器组件由 qdagent 实现,框架只提供可读内容、受控片段或短期授权 blob 引用。
`fragment`、`text`、`blob_ref` 是互斥载荷,按严格 format enum 解码。未知格式返回 unsupported,不能用 `format.includes('html')` 猜测 HTML。为空与加载失败必须有独立状态。
### 7.2 格式矩阵
| 格式 | 框架提供 | 前端消费 | 未具备能力时 |
|---|---|---|---|
| `.mq.md` | 静态 DocumentView、outline、节点/引用 | 正文、语义链接、源码切换 | 只读源码 + 明确诊断,不执行 |
| Markdown / 笔记正文 | 共享静态 Markdown→受控结构/HTML、相对资源引用 | 标题、列表、表格、代码、链接 | 纯文本 |
| 文本/代码 | 分页行片段、编码信息、行定位 | 行号与语法高亮 | 编码提示/下载 |
| JSON / CSV | 有界解析、路径/行列定位、分页 | 树/表/源码 | 原始文本,标格式错误 |
| 图片 | 授权 blob、尺寸/元信息 | 缩放/旋转/替代文本 | 下载,不暗示已做 OCR |
| PDF | blob、页元信息,可选提取插件 | PDF.js 页渲染与定位 | 文件卡;提取不可用不阻止支持的视觉预览 |
| DOCX/XLSX/PPTX | 受限转换插件,可选 PDF/HTML 派生物 | 按派生格式预览 | 未安装转换器,保留下载 |
| HTML/SVG | 默认源码;允许时经严格清洗或受限派生物 | 隔离预览 | 不以内联可执行页面显示 |
| 未知二进制/压缩包 | 元数据 | 下载卡 | 不自动解压/执行 |
提取、预览、执行各有独立 capability。办公转换、OCR 使用受限 worker,禁宏与网络、限制时间/内存/页数/解压膨胀比;结果绑定原件 digest、转换器版本和参数。首期不承诺保真编辑。
### 7.3 安全、定位、缓存
所有读取先校验宿主授予的 workspace/resource scope,canonicalize 并处理 symlink 逃逸;读取句柄与校验对象一致,防路径检查后替换。读取原件的身份权限不可被缓存绕过。
预览绝不调用 `run/verify` 或有执行副作用的 view 路径;正文中的 Marqdo 调用链接只展示语义与导航,执行需单独工具调用与授权。远程图片、相对链接、资源 URL 经受控解析;下载入口不允许任意内网 fetch。
HTML 清洗在框架产出侧和浏览器插入侧都有明确边界;用成熟 allowlist 实现而非正则。禁止 script/event handler、危险 URI、任意 style/form/嵌入对象。前端配 CSP;对需要交互的产物另建无权限 sandbox,不复用文档渲染器。
缓存 key:workspace + resource ID + revision + renderer version + render options + policy version;命中前重新授权。历史 revision 不存在就返回 `version_unavailable`,不能默默展示当前版。locator 支持 node/span/line/page/cell,失效时标 stale 并提供用户主动查看最新版的操作。
建议首期限制:文本片段 256 KiB、代码单次 500 行、CSV 单次 200 行;更大内容分页,完整文件保留。数值需压测校准,不作为现有系统性能声明。
## 8. 事件、可观测性与能力协商
复用 RuntimeEventV2 的 task/run/attempt/seq/event_id。拟增加事件类型:`agent.step.started/completed`、`tool.started/completed/failed`、`recovery.scheduled/exhausted`、`checkpoint.committed`、`artifact.updated`、`answer.delta/committed`、`context.compacted`。现有 `message.delta` 由兼容适配映射 answer channel,不能同时重复消费两套事件。
终态提交包含 accepted output manifest、last_seq、result digest;断流客户端能通过快照补齐最终答案。stream delta 是预览,最终 committed revision 是权威。统计每次尝试的 usage,摘要和修复调用分别标 purpose;未知计量保持 unknown。
拟新增 capability:`agent.error_v1`、`agent.checkpoint_v2`、`agent.tool_schema_v1`、`agent.output_channels_v1`、`agent.context_pack_v2`、`resource.view_v1`,以及各 media renderer 的独立版本/可用状态。保持现有 probe,新增字段向后兼容;未知 feature 当不可用。
trace 记录因果 ID、耗时、错误类别、参数摘要、资源版本和 effect receipt。正文与密钥按配置脱敏,不默认把用户全文件复制进日志。输出中不包含模型私有推理;可审计的是实际动作与结果。
## 9. 分阶段实现与文件落点
| 包 | 修改/新增建议 | 交付内容 | 依赖 / 退出条件 |
|---|---|---|---|
| M-A0 | `src/workbench/capabilities.rs`、`tests/workbench_contracts.rs`、新增合同 fixtures | 上述协议、旧适配、状态映射 | 先冻结跨仓字段,未知字段/版本可降级 |
| M-A1 | `ext/ai/agent.mq.md`、`plugins/agent/src/resume.rs`、新 recovery/effects 支撑模块 | 分类错误、有界修复、accepted candidate、原子检查点 | M-A0;故障注入不重复写、旧记录不冒险自动恢复 |
| M-A2 | `plugins/agent/src/lib.rs`、`mcp_client.rs`、新 tool registry/dispatcher | schema 工具、调用统一、分页与结果资源 | M-A0;未授权调用为 0,失败结果结构正确 |
| M-A3 | `src/workbench/document_view.rs`、新 resource_view、媒体适配模块 | ResourceRef/View、普通格式静态阅读、no-exec | M-A0;资源定位与安全语料通过 |
| M-A4 | `ext/ai/agent.mq.md`、`plugins/llm/src/lib.rs`、`src/workbench/run_context.rs` | 输出分通道、预算、ContextPackV2 | M-A1/2;原生和纯文本 provider fixture 都可用 |
| M-A5 | `src/runtime/` 的既有存储/事件适配、MCP 与转换插件 | 恢复对账、PDF/Office 插件、远程 MCP | M-A1/2/3;持久模式 crash/restart 通过 |
| M-A6 | plan/subtask/sandbox 扩展 | 程序化工具、有界委派与可选浏览器 | 后置;须证明任务收益和预算/效应可控 |
先交 M-A0 与 qdagent P0 的静态阅读/错误结果修复;不要让完整 checkpoint v2 阻塞笔记预览。M-A1 可先上只读重试,写恢复待 ledger 通过再开放。新特性默认关闭直到对应合同实测通过,旧路径继续可读。
## 10. 验收与评测
所有目标是 proposed gate,尚未实测。基础机制用确定性 fake provider/tool;真实 provider 做少量单独 smoke 并记录费用,不能把随机模型输出作为唯一门禁。
| 编号 | 故障/任务 | 必须观察到的结果 |
|---|---|---|
| MA-T01 | 第一次 429、第二次成功 | 尊重退避、计量 2 次、最终只有一个 accepted answer |
| MA-T02 | 连续 schema 参数错误 | 一次修复后停止;工具未在无效参数下执行 |
| MA-T03 | 工具写成功但 receipt 提交前杀 worker | unknown_effect→查询对账;写计数不增加 |
| MA-T04 | checkpoint 写一半杀进程 | 读取上个完整 checkpoint 或明确 corrupt,不产生伪成功 |
| MA-T05 | 终态事件丢失、cursor 重放 | 最终快照恢复完整消息,工具执行次数不增加 |
| MA-T06 | 恢复请求重复/并发 | 同一幂等键只产生一个恢复 attempt |
| MA-T07 | 用户取消与重试定时器竞争 | 取消生效后无新工具调用,旧任务不复活 |
| MA-T08 | 执行中资源/权限改变 | stale/conflict/forbidden,不覆盖新版本 |
| MA-T09 | 恶意文本伪造 CALL/system | 不跨越工具白名单和授权范围 |
| MA-T10 | `.mq.md` 预览含写文件/联网语句 | 哨兵文件/网络计数不变;只读渲染成功或安全降级 |
| MA-T11 | 资源格式、超长输出、路径逃逸 | 正确 renderer/分页;越界拒绝;无 HTML 注入 |
| MA-T12 | 修复原文 A 得到通过验证的 B | answer/artifact/verification 都绑定 B digest |
| MA-T13 | 上下文压缩后继续 | 最新约束、待决效应、资源版本与剩余预算不丢失 |
| MA-T14 | 旧 CALL、旧 DocumentView 消费端 | 基础行为可用,能力缺失有明确返回 |
先运行受影响的 Rust/Go/Marqdo 合同与既有隔离 runtime 金样例,再做跨仓 HTTP/browser gate。性能目标:已缓存 100 KiB 文本视图服务端 p95 < 300 ms、核心工具发现 p95 < 100 ms,基准机器/并发/冷暖缓存必须记录;第三方网络延迟单独列出。
## 11. 迁移、回滚与未决项
兼容迁移按“新增协议→双读→新写→验证→逐步移除旧适配”推进。`.mq.md` 源码与旧运行产物不批量重写;旧 resume JSON 可读取但不能自动升级成带副作用保证的检查点。v2 checkpoint/ledger 保留 schema 版本,新老版本不并发写同一运行。
回滚关闭新工具自动发现、输出通道或转换器时,已提交资源和最终答案仍可读;执行恢复中的任务先 drain/停止接纳,不能切回会盲重做写操作的旧路径。迁移前备份可变索引与 manifest,回滚不删除用户产物。
实现前验证项:现有 runtime 持久存储可提供的原子提交边界、各平台 fsync/rename 行为、LLM adapter 原生 tool call 流式兼容、转换插件部署体积。协议优先按本文保守语义实现,验证不能满足则 feature 保持不可用,不阻塞已经完成的只读预览切片。
Regular → Executable
View File
File mode changed.
+252
View File
@@ -0,0 +1,252 @@
# 语义评估:参数能否从上下文推断(含叙述式调用)
> **2026-10-23 审阅裁决**:保留参数来源可见、避免隐藏调用者环境的边界;下文已被否决的 L0 建议不可重新启用。自然语言只连接和解释,不能成为隐式执行触发器;当前指导见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **§3 的 L0 方案已被否决**(违反「只执行标记」原则);L1/L2 结论仍有效 |
| 日期 | 2026-10-22 |
| 提出 | 「让函数参数从上下文推断,`对**n=31**执行**加一函数**` 这种写法可能吗」 |
| 方法 | 运行时实测 8 组 + 全仓库语料扫描(1322 个函数)+ 源码比对 |
| 相邻 | [call-syntax-from-marks.md](call-syntax-from-marks.md)(**接替本文 §3 的设计**)· [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) |
> **后续更正**:本文 §3 提出的 L0「叙述式调用」用**未标记的词**(`执行`)触发调用,
> 这会破坏「叙述默认安全、只有标记才执行」的底层原则,已被否决。
> 在「只执行标记」约束下重新设计的调用语法见
> [call-syntax-from-marks.md](call-syntax-from-marks.md)
> (含树遍历 vs 字节码 3.8× 实测、叙述顺序导致位置绑定翻转的实验)。
---
## 0. 结论:你的示例其实**不需要**隐式推断
先把一个关键事实摆出来:**你的例子里 `n=31` 明明写在那儿**。
```markdown
# main
对**n=31**执行**加一函数**
```
`n` 的绑定**就写在句子里**,这不是「从上下文推断」,这是**具名实参换了语序**。
所以这个写法需要的是**新的叙述式调用语法**,不是新的作用域语义。
它今天跑出来的结果很能说明问题:**无输出、无报错、退出码 0**。
不是参数推断失败,而是 `执行**加一函数**` 里的裸名字**只是被求值然后丢弃**,
从来没被当成一次调用。
三层拆解:
| 层 | 写法 | 需要什么 | 裁决 |
|----|------|---------|------|
| **L0 叙述式调用** | `对**n=31**执行**加一函数**` | 只要语法糖(绑定仍在句中) | ✅ **可做,且安全** |
| **L1 就近绑定** | 上一行 `**n=31**`,下一行 `执行**加一函数**` | 段落级隐式作用域 | ⚠️ 能做但危险,不建议 |
| **L2 真隐式** | 只写 `执行**加一函数**`,n 全靠上下文 | 动态作用域 | ❌ **不建议**,见 §4 |
---
## 1. 实测:今天到底发生了什么
| # | 用例 | 实测 | 说明 |
|---|------|------|------|
| 1 | 你的示例原样 | **无输出、无报错、exit 0** | 静默 no-op |
| 2 | 同样写法 + `> print text=`n`` | `main里的n=31` | **散文行里的 `**n=31**` 真的执行了** |
| 3 | 只写 `对`加一函数`执行` | `done`,无报错 | 裸名字只被求值丢弃,**未调用** |
| 4 | `**n = 31**` + `> 加一函数`(不传参) | `missing argument for parameter n` | **函数看不见调用者的 `n`** |
| 5 | `> 加一函数 n=31` | `32` | 显式写法今天就能做 |
| 6 | `# main` 读 frontmatter `税率` | `0.1` ✅ | 入口可见 |
| 7 | `## 函数` 读同一个 `税率` | `undefined variable` ❌ | 函数不可见 |
| 8 | 浏览器 WASM 入口调用函数 | metadata + `entry_bindings` **都会传** | 见 §5,**与 CLI 不一致** |
**第 2 与第 3 条合起来是关键**:散文行里的粗体确实会执行,但一个裸函数名在粗体里
只是一个**表达式语句**(值算了就丢),不会变成调用。所以「看起来该调用」的句子,
实际什么也没做——又是一次静默失败(与 D9 同一类)。
**第 4 条是语义基石**:Marqdo 现在的作用域是**严格分离**的,
函数只能看到自己的形参与局部变量。你想要的 L2,就要拆掉这块基石。
---
## 2. 你自己的担心是对的:数据在这里
你提到「大项目变量名会难以使用」。我把仓库里 `lib/ ext/ examples/ tests/` 全扫了一遍:
| 指标 | 数值 |
|------|------|
| 扫描函数数 | **1322** |
| 不同形参名 | 819 |
| **被 ≥5 个函数共用的形参名** | **130 个** |
撞车最严重的一批:
| 形参名 | 用它的函数数 |
|--------|-------------|
| `path` | **70** |
| `value` | 59 |
| `text` | 53 |
| `id` | 47 |
| `list` | 38 |
| `内容` | 38 |
| `路径` | 35 |
| `a` / `b` | 各 32 |
结论很直接:**如果参数靠上下文推断,那么每次调用一个读 `text` 的函数,
它都会去捡当前作用域里的 `text` 是什么**。53 个函数在等这个值——
撞车是常态,不是例外。这不是「大项目才有」的问题,中型项目就已经不可控。
---
## 3. L0:叙述式调用(推荐做)
### 3.1 目标写法
```markdown
## 加一函数
对`n`我们让**n=n+1**之后返回*n*
# main
**结果 = 对 n=31 执行 加一函数**
> print text=`结果` # → 32
```
### 3.2 语义映射(零模型改动)
```
对 <绑定子句> 执行 <函数名> ≡ Call { callee: <函数名>, args: [<绑定子句>…] }
```
也就是**纯粹换语序**的语法糖。它与今天的
```markdown
**结果 = > 加一函数 n=31**
```
产出**同一个 `CallExpr`**。因此:
| 面 | 影响 |
|----|------|
| 契约校验(T2.1/T2.2) | **不变**(实参照常绑定与校验) |
| EKC 指纹 `collect_calls` | **不变**(callee 仍是静态名) |
| 字节码 `Op::Call(fid, argc)` | **不变** |
| 序列化 / 沙箱 | **不变** |
| `view` 渲染 | 需决定回显哪一种语序 |
这正是它与「一等函数」「动态作用域」的本质区别:**只改写法,不改调用模型。**
### 3.3 设计细节要定的三件事
1. **动词**:`执行` 目前**不是**关键字;而 `调用` **已经是**关键字(`src/aliases.rs:39`
把 `调用` 映射到内建 `call_fn`)。两个近义词并存会混乱,需要二选一或明确分工。
2. **绑定子句的边界**:`对 n=31 执行 …` 里 `n=31` 到 `执行` 之间是参数区;
多参数写 `对 n=31 m=2 执行 …`。
3. **与散文的冲突**:`对` 起头的行今天是叙述(CJK 开头 = 注释)。
要让这行变成代码,得给「叙述里出现 `执行 <函数名>`」一个可判定的规则,
否则又是一处「看起来是代码、实际是注释」的静默陷阱。
---
## 4. L2:真隐式参数(不建议)
### 4.1 它到底是什么
L2 = **动态作用域**(dynamic scoping):被调函数在**调用者的环境**里查找自由变量。
历史上被反复试过、也反复放弃:早期 Lisp 改成词法作用域、Shell 的动态作用域被视为坑。
### 4.2 七条硬伤(每条都是具体后果,不是理论洁癖)
| # | 问题 | 具体后果 |
|---|------|---------|
| 1 | **同名捕获** | `加一函数` 调 `记录日志`,两者都读 `text` → 日志函数静默拿到加一的局部值,输出错内容而不报错 |
| 2 | **递归自毁** | `n=n+1` 后调自身:内层看到的是**已被改过的** n(还是副本?)——必须新增一套遮蔽规则,而规则本身又会成为新的坑 |
| 3 | **无法复用** | 同一函数两次不同入参,只能反复改外部变量并祈祷调用顺序,等于把「参数」退化成全局可变状态 |
| 4 | **契约报废** | `call_arg_diag` 在**调用边界**校验实参类型;如果不传实参,就没有校验点。T2.1/T2.2 契约体系直接失效 |
| 5 | **指纹/arity 失真** | `collect_calls` 记录被调名,arity 由形参推断;隐式调用在 AST 上看起来是零参调用 → 复用预检、`plan` 能力匹配、查重全都失真 |
| 6 | **沙箱与序列化** | `sandbox.run` 以隔离方式执行文档;隐式依赖外部作用域会破坏隔离语义;环境也必须可序列化 |
| 7 | **不可审计** | 函数行为依赖看不见的上下文——这就是「全局可变状态」的经典问题,与「文档即程序、可被人读懂」直接冲突 |
再叠加 §2 的数据(130 个名字被 ≥5 函数共用),第 1 条不是边角情况,而是默认情况。
### 4.3 但有一个**受限版**值得考虑
如果你真正想要的是「短脚本读起来顺」,那么下面这个版本是安全的:
> **常量默认值**:允许函数在**未传入**某形参时,从**文件级常量**取值。
```markdown
---
title: 报价
税率: 0.1
---
## 含税
+ `金额`
*`金额` * (`税率`)* # 税率 未传入 → 取 frontmatter 常量
# main
**a = > 含税 金额=100** # 10
**b = > 含税 金额=100 税率=0.06** # 6,显式覆盖
```
为什么它安全而 L2 不安全:
| 维度 | L2 动态作用域 | 常量默认值 |
|------|--------------|-----------|
| 取值来源 | 调用者的**任意**变量 | 文件顶部**写一次**的常量 |
| 静态可判定 | ❌ 取决于运行路径 | ✅ 打开文件就能看到 |
| 随调用者变化 | ✅ 会变(最危险) | ❌ 不会 |
| 契约 | 失效 | 仍可校验(实参照常声明) |
| 序列化/沙箱 | 破坏隔离 | 可序列化(常量是数据) |
| 复用 | 破坏 | 不受影响 |
**关键差别**:常量是**文档的一部分**(frontmatter 就在文件开头,人读得到),
而动态作用域的值是**运行路径的一部分**(人读不到)。
---
## 5. 顺带发现的真问题:CLI 与 Web 的环境不一致
实测 §1 第 6/7/8 条时发现:
| 路径 | 函数可见环境 | 源码 |
|------|-------------|------|
| `# main`(CLI 运行) | frontmatter metadata ✅ | `src/interp.rs:473` `Env::with_metadata` |
| **普通函数调用** | 只有实参 ❌ | `eval_call` 用 `Env::new()` |
| **浏览器 WASM 入口** | metadata ✅ + `# main` 的 `entry_bindings` ✅ | `invoke_in_entry`(`src/interp.rs:365`) |
也就是说:**同一份文档,在浏览器里函数能读到 frontmatter 常量、还能读到 `# main`
的绑定;在 CLI 里读不到。** 行为随运行面不同而不同。
这是一个**真实缺陷**,已记入 [D11](../research/qdagent-refactor-defects-2026-10.md):
- 对使用者:同一文件在 Web 能跑、在 CLI 报 `undefined variable`,极难排查
- 对设计:说明「受控环境通道」其实已经存在(只是没在 CLI 打开),
这既是 L2 受限版的现成基础,也是必须先统一的地方
---
## 6. 建议
| 优先级 | 事项 | 性质 |
|--------|------|------|
| 1 | **先统一 CLI/Web 的函数环境**(D11) | 修缺陷,消除行为分裂 |
| 2 | **做 L0 叙述式调用**(`对 X 执行 F`) | 纯语法糖,零模型改动,554 回归可守 |
| 3 | 若要「少写参数」,做**常量默认值**(§4.3) | 受控隐式,静态可判定 |
| 4 | **不做 L2 动态作用域** | 七条硬伤 + 130 个撞车名 |
关于「代码即文档」的取向,我的理解是:
> 文档化的是**写法**(句子怎么读),不是**语义**(值从哪来)。
> 让句子更像人话是值得的;让值从看不见的地方来,是把可读性换成不可预测性。
---
## 7. 待你决策
1. **L0 是否采纳?** 若采纳,动词用 `执行` 还是复用已有的 `调用`?
2. **`对…执行…` 的行如何与散文区分**(§3.3 第 3 点)?这决定它会不会变成新的静默陷阱。
3. **常量默认值**(§4.3)要不要做?
4. **D11(CLI/Web 环境不一致)** 是否现在就修?我建议先修它,因为它会影响 L0/L2 的所有验证结论。
Regular → Executable
+2 -1
View File
@@ -36,7 +36,8 @@ 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
import:
sys: lib/sys.mq.md
---
```
+302
View File
@@ -0,0 +1,302 @@
# 评定:`[描述](语句)` —— 方括号读作「人话」,圆括号读作「机器话」
> **2026-10-23 审阅裁决**:本文的 Classic 冲突统计和兼容取舍属于迁移历史;v2.1 默认采用描述包裹 payload,不能据旧冲突恢复默认 `[键](集合)`。保留标签的阅读/检索/步骤价值,不强制所有子表达式命名,也不把标签当作目标或权限依据。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **已决策:走「路线二 纯度」**(落地见 [label-freshness-and-repair.md](label-freshness-and-repair.md)) |
| 日期 | 2026-10-22 |
| 提案 | 「`[]()` 不是两个部分两个含义,而是 `[描述性显示文字](实际执行的简短语句)`」 |
| 方法 | 语料实测(索引 506 / 循环 44 / 方括号调用 0)+ 渲染器源码核对 + 设计史对照 |
| 相邻 | [label-freshness-and-repair.md](label-freshness-and-repair.md)(后续:纯度落地 + 标签过期检测)· [function-as-naming-philosophy.md](function-as-naming-philosophy.md) · [collection-access-link.md](collection-access-link.md) · [call-syntax-from-marks.md](call-syntax-from-marks.md) |
> **决策**:用户选择**路线二(纯度)**——`()` 只装机器语句,取元搬进 `()`;
> 标签可省略书写但**编译器必须报错**;循环写法不追求统一,`()` 内自洽即可。
> 落地细节、普通取元形态,以及**标签过期检测(L1 引用一致性 / L2 指纹台账 / L3 LLM 复核)**
> 见 [label-freshness-and-repair.md](label-freshness-and-repair.md)。
---
## 0. 先把提案精确化
你的话可以解析出三种读法,差别很大,必须先分清:
| 读法 | `[]` 是什么 | `()` 是什么 | 语义是否变 |
|------|------------|------------|-----------|
| **A 标签化(你的原意,本文主评)** | 这个值的**人话名字**(纯描述) | 算出它的**机器语句** | **变** |
| B 命名规范化 | 更好的键名(描述取出的东西) | 仍是集合 | 不变 |
| C 内联命名 | 同时引入可引用的名字 | 算出它的语句 | 新增绑定 |
你说「`[]()` 函数也有了落脚地」「括号里面可以写长一些」,指向的是 **A**:
**`[]` 只负责说人话,`()` 负责说准话;两者合起来才是一条完整语句。**
---
## 1. 为什么我们会下意识觉得这个写法"美"
你的直觉不是审美偏好,它对应三个**真实存在**的设计同构:
### 1.1 超链接:可见文本 ↔ 目标
`<a>` / `[可见文字](目标地址)` 的全部意义就是**给机器一个目标,给人类一个说法**。
这是人类最早、最成功的"双面文本"。
### 1.2 文学编程的 chunk 名(Knuth)
Knuth 的 `<<chunk name>>` 就是"可执行片段的人话名字"。
而**文学编程的整个出发点,正是你前面说的"代码要像文章"**——这个类比不是巧合。
### 1.3 Marqdo 自己已经有这个形态
```markdown
![marqdo-out](图片路径)
```
- `[]` 里是**指令/说明**(`marqdo-out`、可带 key)
- `()` 里是**负载**(图片 URL / data URI)
**语言里已经有一个"方括号说意图、圆括号放负载"的地方。** 你的提案是把这个模式提升为通则。
### 1.4 一个经验证据:`[]` 在实践里本来就偏"给人看"
| 用法 | 数量 | 谁读 |
|------|------|------|
| `[键](集合)` 取元 | 506 | 机器 |
| `- [项](集合)` 循环 | 44 | 机器 |
| `[函数] 参数` 调用 | **0(可执行)** | — |
| `[函数.名] 参数` 用法说明(`lib/*` 的 `Caller:` 行) | **189** | **人** |
**可执行的方括号调用从未被使用**;`[]` 在文档里出现最多的地方,恰恰是"给人看的用法示例"。
这支持你的判断:`[]` 的天性更接近"描述",而不是"标识符"。
---
## 2. 提案的三个真实收益(这部分我完全同意,而且比你说的更强)
### 2.1 收益一:两条规则变一条 —— 这是最大的价值
现在 `[x](y)` 是**两个部分、两个含义**(键 + 集合)。这导致前几轮那个死结:
> `[f](args)` 想当调用,但它和 `[k](c)` **同形**;按名字消歧会打断 2 个真实文件。
你的重读**直接解散了这个死结**:如果 `[x](y)` 一律是"标签 + 语句",
那么**根本不存在"取元独占外形"这件事**——取元只是"`()` 恰好是个取值语句"的特例。
> 这是本提案最硬的结构收益:**它把一条只能容纳一种语义的外形,改造成能容纳任意语句的外形。**
> 前几轮我们反复撞墙,是因为一直默认 `()` 只能是集合。你换了默认。
### 2.2 收益二:嵌套取元终于可读
现在是:
```markdown
**第一 = [1]([苹果](货架))**
```
两层嵌套,人类读者要在"货架→苹果→第1项"之间跳三次。
改成标签后:
```markdown
**第一 = [货架里苹果的第一项](…机器语句…)**
```
**人读标签,机器读嵌套。** 你点出的"嵌套难以描述"问题被真正解决了。
### 2.3 收益三:循环的"来源"可见 —— 但要说清它成立的范围
你的原话:`- [果](篮子)` 在 Markdown 渲染里看不出"果是从篮子拿的"。
**这一点需要精确化,因为它决定这块值不值得改**:
| 阅读场合 | `- [果](篮子)` 的表现 |
|---------|---------------------|
| 通用 Markdown(GitHub / VSCode 预览 / 编辑器) | 渲染成**名为「果」的链接指向「篮子」**——看不出是遍历,你的批评成立 |
| **Marqdo 自己的 `view`** | 已渲染成带 `foreach` 徽章的 `loop-card`(`src/view/render.rs:1354`)——已经看得出 |
而取元在 `view` 里仍渲染成字面 `[键](集合)`(`render.rs:1502`),和 Markdown 链接同形。
**结论**:循环的"来源不可见"在**通用 Markdown 阅读器**里成立,而这恰好是大多数人的阅读场合
(`marqdo view` 需要额外一步)。所以这条收益真实,但它其实在说另一件事:
> **Marqdo 的语义正确性,不应该依赖读者是否用了 `marqdo view`。**
> 文档的第一载体是 `.mq.md` 本身,它在任何 Markdown 渲染器里都该读得通。
这比你原本的表述更有力——它把"渲染不好看"升级成"语义不可自解释"。
### 2.4 附带收益:标签是天然的锚点
你提到"点击之后跳转到对应位置"。这件事可行性很高,而且价值不小:
- `view` 已经保留每个语句的 span(`stmt_start`),标签可以让锚点从"行号"升级为"人话定位"
- 报错信息可以说「在 **货架里苹果的第一项** 处出错」,而不是 `foo.mq.md:118`
- 对 agent 尤其有用:模型用自然语言描述定位,比用行列号稳得多
---
## 3. 结构性弱点:`()` 要变成"语句",就必须再发明一套取元
这是本提案**代价最大、也最容易被忽略**的一点,必须摊开。
若 `[]` 只是标签,那 `(菜单)` 就只表示"整个菜单",**不再表示取成员**。要取成员,`()` 内需要新语法:
| 方案 | 形态 | 问题 |
|------|------|------|
| 点号 | `(菜单.拿铁)` | 与库路径 `txt.str_trim`、对象方法 `obj.m` 三者同形,容易混淆 |
| 函数式 | `(取 菜单 拿铁)` | 需要新内建;与自然语言"取"字冲突多 |
| 保留方括号 | `([拿铁](菜单))` | **嵌套方括号**,正是标签想消除的东西 |
| 英文式 | `(get(菜单, 拿铁))` | 破坏中文叙述风格 |
**这就是核心张力**:
> 你想用 `()` 装"任意机器语句",来换取 `[]` 的纯粹描述性;
> 但"取值"本身就需要一个语法,而这个语法要么是新的(增规则),
> 要么就是旧的 `[k](c)`(则 `[]` 仍然兼任键,两义仍在)。
换句话说:**收益一(一条规则)能不能兑现,取决于你愿不愿意新增一条取元规则。**
这不是否决理由,但必须算进成本——因为 Marqdo 的宪法是「标记即语法,少而精」,
**用一条新规则换掉一条旧规则,不必然是净简化**。
---
## 4. 描述漂移:我认为不能轻描淡写
你说「从语言设计上这好像又不是特别重要」。我不同意,理由三条:
### 4.1 它是"注释"的回归
Marqdo 用「叙述 + 标记」取代了注释:叙述在外面说意图,标记在里面说事实。
而标签是**贴在执行体上的、可说谎的、必须短的文本**——这正是注释的老问题。
Marqdo 花了很大力气让"文档即程序",标签会把"文档可能是假的"重新引进来。
### 4.2 一旦标签成为锚点,漂移就有操作后果
你在 §2.4 里期望标签用于跳转与定位。那么:
- 报错说「在 **安全读取** 处失败」,而实际代码是写入 → **错误信息也撒谎**
- agent 用标签定位 bug → 被标签误导
- 点击跳转跳到一段与描述不符的代码 → 读者信任崩塌
**标签的可信度必须与它的用途匹配。** 纯装饰可以漂移;一旦用于定位,就必须可校验。
### 4.3 安全面:标签是 agent 可读的攻击面
Marqdo 是 agent 框架。标签是**作者可控的自然语言**,而模型天然倾向相信自然语言。
「标签写:只读校验;`()` 里:删除文件」这类不一致,从"文档瑕疵"升级为**误导 agent 的通道**。
**所以我建议把漂移当成一条可检查的不变量,而不是接受它的存在**:
| 缓释手段 | 说明 | 成本 |
|---------|------|------|
| ① 标签永不参与绑定 | 纯显示,不进符号表、不进作用域 | 零 |
| ② 词重叠校验 | `check` 检查"标签里提到的名字"是否至少有一个出现在 `()` 里;全不重叠 → warn | 低 |
| ③ trace 双输出 | 错误/trace 同时给标签与 `()` 原文 | 低 |
| ④ 策略不看标签 | 沙箱/权限判定只读 `()` 的语义,绝不读标签 | 设计约束 |
其中 ② 最划算:它能抓住**最恶劣的一类漂移**(标签说 A,代码做 B),
而对"标签写得更细"这种正常情况不误报。
---
## 5. 采用风险:可能重演 v0.3 废除的"仪式感"
v0.3 废除 `+ \`名\`` 形参表的原话理由是:**「仪式感强;函数头像另一套签名语言,与正文脱节」**。
强制每个访问都配一段人话标签,是**同一类仪式**。两种可预测的退化:
1. **凑数**:作者写 `[x](…)`、`[价格](…)`——标签退化成变量名,等于没有
2. **噪音**:标签越写越长,正文被切碎,扫描性下降
这不是反对,而是提醒:**标签的价值只在"写得比键更有信息"时成立**。
所以设计上应当考虑"**可以省略**",但一旦可省略,`[]` 就又变成可选键 → 歧义回归。
**这个矛盾必须在设计里正面解决,不能靠自觉。**
---
## 6. 迁移面(实测)
| 受影响的写法 | 数量 | 文件 |
|------------|------|------|
| `[键](集合)` 取元 | **506 处** | 136 个文件 |
| `- [项](集合)` 循环 | **44 处** | 24 个文件 |
| `[函数] 参数` 可执行调用 | **0** | (189 处是 `lib/*` 的 `Caller:` 说明行,不执行) |
**危险点**:如果 `[]` 改为"纯标签",那 506 处取元的**含义会变**(`(菜单)` 变成整个菜单),
而且是**同形换义**——同一段文本含义变了、还不报错。这是最坏的一类变更(参见 D9)。
所以若走这条路,**必须硬报错 + 版本门**:旧写法在新版本下直接报
「`[键](集合)` 已改为 `[描述](语句)`,请写成 X」。
另有一个好消息:**可执行方括号调用量为 0**,所以"把 `[f] args` 收编进新形式"是零迁移成本。
---
## 7. 两条落地路线
### 路线一:双层(推荐,兼容)
> **规则一句话:`[]` 永远是「这个值的人话名字」;`()` 永远是「怎么算出它」。**
- **长形(新增)**:`[描述](语句)` —— 承载调用、复杂取元、循环
- **短形(现状保留)**:`[键](集合)`、`- [项](集合)` 定义为长形的**缩写**
- 文档里显式承认:短形是历史妥协,`[]` 在短形中兼任键
| 优 | 劣 |
|----|----|
| 零迁移(506 处不动) | 短形的"两义"仍在(但被定义为可解释的缩写) |
| 调用终于有落脚地(且 0 成本收编) | 规则仍是"一条 + 一个特例",不是纯一条 |
| 嵌套可读、循环可写清来源 | |
| 标签可以逐步引入,不强迫 | |
### 路线二:纯度(一条规则到底)
> `()` 只装机器语句,取元必须搬进 `()`。
必须同时决定:**`()` 内取元用什么形式**(§3 表),然后迁移 506 处 + 版本门。
| 优 | 劣 |
|----|----|
| 语义最纯,教学最简 | 需新增取元规则(可能不是净简化) |
| `[]` 完全自由,可写很长的描述 | 506 处迁移,同形换义风险 |
| 与 Markdown 链接语义完全一致 | 新取元语法与库路径/方法调用需要消歧设计 |
---
## 8. 我的评定
**这是本系列里结构上最强的一个提案**,因为它第一次正面回答了"为什么 `[]()` 一直不肯就范":
不是我们选错了语义,而是我们把一个"双面文本"当成了"两段语义"。
| 维度 | 评分 | 说明 |
|------|------|------|
| 哲学自洽性 | ★★★★★ | 与超链接、文学编程、`![alt](src)` 三处同构;且"文档自解释"优于"依赖 view 渲染" |
| 解决问题 | ★★★★☆ | 解散 link-call 死结、治嵌套可读性、治循环来源——三个真问题 |
| 规则净简化 | ★★★☆☆ | 收益是"两规则→一规则",但代价可能是"新增一条取元规则" |
| 迁移风险 | ★★☆☆☆ | 506 处同形换义,必须硬报错;但可执行方括号调用为 0 是利好 |
| 漂移风险 | ★★★☆☆ | 比你估计的重(注释回归 + 锚点说谎 + agent 攻击面),但可用 ② 词重叠校验兜住 |
| 采用风险 | ★★★☆☆ | 有重演 v0.3"仪式感"的可能,需正面解决"可省略 vs 歧义" |
**我的建议**:走 **路线一(双层)**,但把"长形"作为**推荐写法**、把文档里的示例全部改成长形,
让短形成为"读得懂但不必写"的兼容层。这样:
- 你今天就能拿到全部三个收益(描述性、嵌套可读、循环来源)
- 506 处零迁移
- 调用终于有家,且成本为零
- 未来若要纯度,可以在长形已被广泛使用后,再决定是否废弃短形
**一条具体建议**:先把 §4 的 ②(词重叠 warn)做出来。
它让"标签"从"可能说谎的装饰"变成"**可被机器轻度核验的描述**"——
这一步做完,标签才配得上你要给它加的"AI 定位锚点"和"点击跳转"这两个职责。
---
## 9. 待你决策
1. **路线一(双层)还是路线二(纯度)?**
2. 若路线二:`()` 内的取元用哪种形式(点号 / 函数式 / 其他)?——这决定要不要新增规则。
3. **标签可否省略?** 若可,省略时算"以 `()` 的文字为标签",还是要额外标记?
4. **是否采纳 §4.2 的"词重叠校验"**?我认为它是这套设计能否安全的支点。
5. 循环的新写法你倾向哪一种:
- `- [从篮子取出的每个果子](遍历 篮子 为 果)`
- `- [篮子里的果子](篮子 → 果)`
- 保留 `- [果](篮子)` 作短形
View File
File mode changed.
+9 -5
View File
@@ -1,5 +1,8 @@
# 浏览器 Marqdo(WASM 解释器)设计
> 2.7.0 维护说明:独立的 browser-hello 与 browser-media 演示已删除。下文保留既有能力设计与宿主边界,当前可运行工程使用 browser-app;底层计数器冒烟夹具位于 tests/wasm/counter.mq.md。Canvas、音频等仍是 lib/browser 的宿主能力,不宣称当前 browser-app 演示包含这些交互。
| | |
|---|---|
| 状态 | **Accepted(设计锁定)** · 实现见路线图 C0–C5 |
@@ -124,7 +127,7 @@ source: &str (+ optional import map)
| `marqdo`(根) | 核心;feature-gate |
| `crates/marqdo-wasm` | `cdylib`:`mq_*` ABI + `js/marqdo-bridge.js` |
| `ext/web` 或 `web/browser` | L1:`浏览器.运行` / `交互装配`(C3+) |
| `examples/browser-hello/` | 静态页 + wasm 冒烟 |
| `examples/browser-app/` | 静态页 + wasm 冒烟 |
| `tests/browser/` 或金样脚本 | Node/wasmtime 跑 `run_source` 对齐 |
发行:`marqdo wasm build`(C2 CLI 糖)或 `wasm-pack build crates/marqdo-wasm`。
@@ -156,7 +159,8 @@ source: &str (+ optional import map)
```markdown
---
import json:lib/json.mq.md
import:
json: lib/json.mq.md
---
# main
@@ -209,7 +213,7 @@ L1 `浏览器.交互装配`(ext)可后置;C3 以 bridge + 返回 wire 表
Bridge:`applyEffects(exports, value)` — 先 DOM,再调度异步;**不**在 WASM 内阻塞。
示例见 `examples/browser-hello/fetch.mq.md`。
示例见 `examples/browser-app/static/app.mq.md`。
---
@@ -250,7 +254,7 @@ marqdo wasm build -o static # marqdo_wasm.wasm + marqdo-bridge.js
# app.static dir=static
```
业务页再 `boot` 自己的 `.mq.md`(见 `examples/browser-hello/`)。
业务页再 `boot` 自己的 `.mq.md`(见 `examples/browser-app/`)。
---
@@ -260,7 +264,7 @@ marqdo wasm build -o static # marqdo_wasm.wasm + marqdo-bridge.js
|----|------|
| 单元 | `run_source("…# main\n> print…")` native 与 wasm 同测 |
| 金样子集 | `tests/structure/hello.mq.md` 等无 fs/net/plugin 的样例 |
| 浏览器冒烟 | `examples/browser-hello`:按钮点击 → Marqdo 函数 → 改 DOM 文本 |
| 浏览器冒烟 | `examples/browser-app`:按钮点击 → Marqdo 函数 → 改 DOM 文本 |
| 回归 | CI:`cargo test` native;另 job `wasm-pack build` / `cargo check --target wasm32-unknown-unknown --no-default-features --features wasm-core` |
---
Regular → Executable
View File
File mode changed.
Regular → Executable
+2
View File
@@ -1,5 +1,7 @@
# 调用实参:具名与位置
> **2026-10-23 适用范围校正**:本文保留早期调用尾部规则和历史示例,不是 v2.1 全部调用语法。当前已有 `f(args)` 及具名实参;默认紧邻 `](` 是描述包裹 payload,不再是下文所述的 Classic 取元。语法审阅与开发取舍见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),当前行为须由默认模式测试复核。
| | |
|---|---|
| 状态 | 已定(v0.1 增补;2026-09-14:方括号标记调用) |
+289
View File
@@ -0,0 +1,289 @@
# 语法设计:标记如何构成调用(在「只执行标记」原则下)
> **2026-10-23 审阅裁决**:保留显式标记和正文默认安全;性能数值是旧实验,不作为当前基准。持久跨文档接口优先具名参数,但不禁止位置参数;反引号声明与顺序改变可能是接口变化。当前调用与开发方向见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **Proposed · 待决策**(未改代码) |
| 日期 | 2026-10-22 |
| 前置纠正 | 用户否决上一轮的「叙述式动词」方案:**未标记词承载语义 = 破坏「叙述默认安全」** |
| 方法 | 实测 6 组(含双后端性能对比、叙述顺序实验)+ 源码比对 |
| 相邻 | [ambient-parameters-evaluation.md](ambient-parameters-evaluation.md) · [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) |
---
## 0. 先接受纠正:错在哪
我上一轮提的 `对**n=31**执行**加一函数**`,靠**未标记的词「执行」**来触发调用。这确实违背底层原则:
> **叙述(未标记)= 默认安全,不执行;标记 = 才进编译器。**
一旦「执行」这种词能改变语义,那么:
- 作者改一句措辞("执行" → "运行" / "调用" / 换个说法)就可能改变程序行为;
- 读者无法只看标记判断哪句是代码——必须逐字读叙述;
- 与 D9 同类的静默风险:语义藏在叙述里。
**所以本文的设计约束是硬的**:
> **调用的每一个语义成分(被调者、每个实参、绑定关系)必须落在标记内;
> 叙述词只能起连接与解释作用,永不改变语义。**
---
## 1. 先盘清「标记字母表」
要设计调用,先得知道手上只有哪些字。
| 标记 | 现行语义 | 可否参与构成调用 |
|------|---------|-----------------|
| `**…**` | 执行段(赋值 / 调用 / 表达式) | ✅ 主载体 |
| `*…*` | 返回 | ✅ 终止 |
| `` `x` `` | 变量引用;首次出现即声明 | ✅ 槽名 |
| `` `x` = `` | 叙述中的绑定 | ✅ 槽赋值 |
| `**x = …**` | 赋值 | ✅ |
| `> …`(行首) | 调用语句 | ✅ 已是调用标记 |
| `[callee] args` | 方括号调用(消歧 / 前置修饰) | ✅ 已是调用标记 |
| `[k](coll)` | 取元 | ⚠️ 与调用抢外形(已否) |
| `- [x](coll)` | 遍历 | — |
| `#` / `##` | 对象 / 函数声明 | — |
| 表格 | 数据 / 契约 | — |
| ```lang | 外联代码 | — |
**关键观察**:调用载体其实只有三种标记:`> 行`、`**…**`、`[callee]`。
而 `[k](coll)` 这个外形已被取元独占(前几轮结论),不能用。
所以问题收敛为:
> **在 `**…**` 或 `> …` 内部,用哪些标记把「函数名」和「槽赋值」连起来?**
---
## 2. 可读性从哪来(这是设计的核心)
Marqdo 的叙述与代码是**两层**:叙述解释「为什么」,标记表达「做什么」。
所以可读性不是靠把叙述词变成语法,而是靠:
1. **标记本身足够像自然记号**(`=`, `(`, `)`, `→` 都是跨语言的);
2. **叙述与标记紧邻**,人一句一码地读;
3. **同一件事只写一遍**(叙述不要复述代码)。
一句话:
> **叙述负责「说人话」,标记负责「说准话」;两者相邻即高可读,混在一起即两败。**
---
## 3. 三个候选设计
### 设计 A — 括注具名调用:`**加一函数(n=31)**`
**读法**:`加一函数(n=31)` —— 与数学/几乎所有语言的函数调用同构。
```markdown
## 加一函数
对 `n` 让 **n = n + 1**,返回 *n*
# main
**结果 = 加一函数(n=31)**
```
| 维度 | 评价 |
|------|------|
| 完全由标记构成 | ✅ 整段在 `**…**` 内 |
| 无歧义 | ✅ 圆括号紧跟名字 = 调用;取元需方括号,不冲突 |
| 与叙述结合 | ✅「把 n 设为 31 后**加一函数(n=31)**」 |
| 多参数 | ✅ `f(a=1 b=2)` |
| 编译器 | ✅ 具名 → 编译期映射到槽下标(见 §4) |
| 实现成本 | ⚠️ 需改参数分词器:`)` 作终止符、逗号、嵌套(原型已验 554/0,但 `f(1 2)` 的末参数会吞 `)`) |
### 设计 B — 箭头槽赋值:`**n=31 → 加一函数**`
**读法**:「n 设为 31,交给加一函数」——最贴合汉语「先条件、后动作」语序。
```markdown
# main
**n=31 → 加一函数**
```
| 维度 | 评价 |
|------|------|
| 完全由标记构成 | ✅ `→` 是符号标记,不是词 |
| 可读性 | ✅✅ 流水线极顺:`**订单 → 计税 → 汇总**` |
| 无歧义 | ⚠️ 需定义优先级;`**x = a=1 → f**` 有歧义,得靠括号 |
| 求值结果 | ⚠️ 箭头式天然是语句式;要拿返回值还得包一层 |
| 实现成本 | 中:新增运算符 + 优先级 + 与 `=`/`*…*` 的交互 |
### 设计 C — 现成空格式:`**加一函数 n=31**`(今天就可用)
| 维度 | 评价 |
|------|------|
| 完全由标记构成 | ✅ |
| 实现成本 | **零**(实测 `**r = 加 1 2**` 已可跑) |
| 可读性 | ⚠️ 参数边界靠空格;函数名含空格时不可用(D8) |
| 编译器 | ✅ 具名同样可映射槽位 |
### 三者的取舍
| | A 括注 | B 箭头 | C 空格 |
|---|---|---|---|
| 像通用函数调用 | ✅✅ | ⚠️ | ✅ |
| 中文语序自然 | ⚠️ | ✅✅ | ✅ |
| 参数边界清晰 | ✅✅ | ✅ | ❌(空格切分) |
| 链式组合 | ⚠️ | ✅✅ | ❌ |
| 改动成本 | 中 | 中高 | **零** |
| 与取元冲突 | 无 | 无 | 无 |
---
## 4. 「不分实参形参」:编译器视角的真实收益
你问的是:不再区分实参/形参,是否意味着变量总在某个固定位置、能否减少 IO。
这一节用实测回答,结论会有点意外。
### 4.1 现状:两条执行路径,差异 3.8 倍
| 路径 | 参数如何绑定 | 200k 次调用(1 个 int 实参) | 2000 次调用(500 元素列表) |
|------|-------------|------------------------------|------------------------------|
| **树遍历**(默认 `Backend::Tree`) | `Env { HashMap<String, Value> }`,每个实参 `k.clone()` + `v.clone()`(**深拷贝**) | 167 ms | 66 ms |
| **字节码**(`--backend bytecode`) | `slots: Vec<Value>`,`pop` 后**按位置移动**入槽(**无克隆、无哈希**) | **44 ms** | **23 ms** |
源码依据:
```rust
// src/bytecode/vm.rs Op::Call(fid, argc)
let mut slots = vec![Value::None; callee.locals.len().max(argc).max(1)];
for i in (0..argc).rev() {
slots[i] = pop(&mut stack)?; // 移动,不克隆
}
frames.push(Frame { fn_idx: fid, ip: 0, slots, .. });
```
### 4.2 三个结论
**结论一:「变量始终在某个位置」已经是字节码的现实。**
形参按下标落槽,实参按位置移动入槽。这正是你说的模型——它已经存在。
**结论二:收益是真的,3.8×。**
每次调用 0.83µs → 0.22µs;大实参 33µs → 11.5µs(省掉了深拷贝)。
**结论三(关键):这与「不分实参形参」的语法无关。**
槽位化只需要「编译期知道形参顺序」,而形参顺序今天就有(v0.3 体推断给出确定顺序)。
真正的瓶颈是**树遍历解释器用名字哈希 + 深拷贝**,以及**默认后端是 Tree**。
> **所以:不要用性能去论证语义变更。**
> 想省 IO,把默认后端切到字节码、或把树遍历解释器槽位化即可——
> 这是一条与语法正交的工程路径,收益确定、风险可控。
> 而改语义(动态作用域)换来的性能,等于用正确性买速度。
### 4.3 但有一个真实的语法—性能耦合点:具名 vs 位置
这是本节最有价值的发现。**在「形参由体推断」的世界里,形参顺序 = 叙述里首次声明的顺序**
(v0.3 §8.2:顺序按升参名字的首次声明事件出现序)。而叙述是可以自由改写的。
我用两个只差一句话序的文件做了实验:
```markdown
## 减
对于`a`和`b`。 ← 叙述顺序 a, b
*`a` - `b`*
```
```markdown
## 减
对于`b`和`a`。 ← 只把叙述顺序改成 b, a
*`b` - `a`*
```
| 调用写法 | 叙述 a 在前 | 叙述 b 在前 |
|---------|------------|------------|
| 具名 `a=10 b=3` | 7 | -7(语义随函数体改变,符合预期) |
| **位置 `10 3`** | 7(a=10,b=3) | **7(b=10,a=3)** ← **绑定翻转了** |
**同一行调用代码 `> 减 10 3`,只因为作者改了前面的叙述语序,实际绑定就变了,而且不报错。**
这在「实参形参不分」的模型下是致命的:既然只有槽、槽序来自叙述,
那么**位置传参等于把程序语义挂在叙述的可改写顺序上**。
**推论**:调用应当**以具名为准**,位置实参在体推断世界里是脆弱语法。
这一点与编译器优化正好同向——具名调用让编译期把 `n` 静态映射到 `slots[0]`,
既稳又快(不需要运行期哈希,也不需要猜顺序)。
---
## 5. 我的设计建议
### 5.1 主形态:括注具名调用
```markdown
## 加一函数
对 `n` 让 **n = n + 1**,返回 *n*
# main
**结果 = 加一函数(n=31)**
```
理由:
1. **全部语义在标记内**(满足你的核心原则);
2. 与通用函数调用同构,零学习成本;
3. 具名 → 编译期静态映射槽位(对接字节码已有的 `slots[]`);
4. 不碰取元 `[k](coll)`,不碰遍历 `- [x](c)`;
5. 参数边界显式,顺带解决函数名含空格的调用难题(D8)。
### 5.2 位置实参:降级而非禁止
| 情形 | 建议 |
|------|------|
| 单参数 | 允许 `f(31)`(无歧义、写法自然) |
| 多参数 | **要求具名**;位置仅保留给 `> f 1 2` 这种旧写法,并在 `check` 里 **warn** |
| 理由 | §4.3:顺序来自叙述,可被改写而不报错 |
### 5.3 箭头(设计 B)作为可选补充
如果后续确实需要「流水线可读性」,再引入 `→`,定位为**语句式组合子**:
```markdown
**订单 → 计税 → 汇总**
```
但它是增量特性,不是本设计的前提。优势是链式,代价是优先级与返回值语义。
### 5.4 明确不做
| 方案 | 理由 |
|------|------|
| 未标记动词触发调用(上轮 L0) | 违背「叙述默认安全」 |
| `[f](args)` | 与取元同形,已实测 2 个真实冲突文件 |
| 动态作用域(参数从上下文推断) | 七条硬伤 + 130 个撞车形参名 |
| 位置实参作为主流 | §4.3 叙述顺序会静默改变绑定 |
---
## 6. 优劣总表
| 设计 | 标记完备 | 可读性 | 无歧义 | 编译器友好 | 改动 | 结论 |
|------|---------|--------|--------|-----------|------|------|
| **A 括注具名 `f(n=31)`** | ✅ | 高 | ✅ | ✅ 静态槽映射 | 中 | **推荐主形态** |
| C 空格式 `f n=31` | ✅ | 中 | ✅ | ✅ | 零 | 今天可用,作兼容 |
| B 箭头 `n=31 → f` | ✅ | 最高(流水线) | ⚠️ 优先级 | ✅ | 中高 | 可选增量 |
| `[f](args)` | ✅ | 高 | ❌ 撞取元 | — | — | 不做 |
| 未标记动词 | ❌ | 高 | ❌ | — | — | 不做 |
| 动态作用域 | ✅ | 最高 | ❌ | ❌ 契约/指纹失效 | 高 | 不做 |
---
## 7. 待你决策
1. **主形态选 A(括注具名)吗?** 若选,我按 B 档实现:`f(k=v)` 必通、`f(x)` 单参、多参数求具名。
2. **位置实参**:多参时"要求具名 + 旧写法 warn"(§5.2),还是保持现状不动?
3. **箭头**现在做还是留作后续?
4. **顺带**:默认后端要不要切字节码(实测 3.8×,但需先验证 554 用例在 `--backend bytecode` 下全绿)?这条与语法无关,但可能是最划算的性能改进。
> 若你同意 A,我下一步会:改分词器(`)` 终止、逗号、嵌套)→ 补金样例 →
> 跑双后端 554 回归 → 写变更文档。
Regular → Executable
View File
File mode changed.
+231
View File
@@ -0,0 +1,231 @@
# 变更记录:D9 未闭合引号不再静默吞行
| | |
|---|---|
| 状态 | **Implemented**(待合入) |
| 日期 | 2026-10-22 |
| 缺陷 | [D9](../research/qdagent-refactor-defects-2026-10.md) |
| 设计 | [parser-diagnostics-d8-d9.md](parser-diagnostics-d8-d9.md) §1 |
| 改动文件 | `src/lex/mod.rs` · `src/parse/mod.rs` |
| 影响面 | 行分类 + 语句解析(仅影响**畸形**输入) |
---
## 1. 修了什么
**修复前**:`**s = "abc`(引号未闭合)被静默当成叙述丢弃,退出码 0。
```bash
$ marqdo run u.mq.md
$ echo $?
0 # 没有输出、没有报错,s 这一行凭空消失
```
**修复后**:解析期报错,退出码非 0。
```bash
$ marqdo run u.mq.md
error: u.mq.md: 7:1: unterminated string: this line starts bold code but
contains an odd number of `"` -- close the string and the trailing `**`
(line: **s = "abc)
$ echo $?
1
```
(实测记录:报错回显中 `unterminated` 前的空格与行号格式由
`Diagnostic` 的 span 渲染决定,与其它语法错一致。)
---
## 2. 根因
问题**不在**解析器——`parse_quoted_string` 里的
`bail!("unterminated {quote} string")` 一直都在,措辞也对。
问题是这一行**根本到不了解析器**:
```
"**s = \"abc"
↓ classify_line
↓ 首字符 '*' → is_marqdo_star_line?
matching_bold_close() 扫描时遇到 '"' → in_str = true
之后再也没有 '"' 来关闭 → 后续所有 '*' 都被当作字符串内容跳过
→ 找不到收尾 '**' → 返回 None
↓ is_marqdo_star_line = false
↓ 落入 `Some('*') if !is_marqdo_star_line` → LineKind::Comment
↓ 成为「叙述」,解析器看不到
```
**这是分类层的静默降级,不是解析层的缺陷。**
它比一般的解析错误更危险,因为:
| 场景 | 后果 |
|------|------|
| 手写漏一个引号 | 该行消失 → 别处报 `undefined variable`,排查方向被引偏 |
| LLM 生成文档 | 少一段内容,但 `exit 0`、`check` 通过,**文档看起来完整却缺节** |
| CI / 文档门禁 | 门禁试跑通过 → 残缺文档被沉淀入库 |
---
## 3. 怎么改的
两层,缺一不可。
### 3.1 分类层:把畸形行留在 Code 类
`src/lex/mod.rs`
```rust
if trimmed.starts_with("**") {
if trimmed.trim() == "** **" {
return true;
}
if matching_bold_close(trimmed).is_some() {
return true;
}
// D9: 粗体起始但引号永不闭合 → 找不到收尾 `**`
// 判为 Comment 会静默丢行;判为 Code 让解析器报错
return has_unterminated_string(trimmed);
}
```
新增辅助函数:
```rust
pub fn has_unterminated_string(line: &str) -> bool {
// 统计未被 \ 转义的双引号个数,奇数即「开了没收」
}
```
### 3.2 解析层:给出精确报错
`src/parse/mod.rs`,紧跟既有粗体分支之后:
```rust
// D9: 粗体起始但引号未闭合 —— 走到这里说明没有收尾 `**`,
// 通用 "unrecognized statement" 会掩盖真正原因。
if trimmed.starts_with("**") && has_unterminated_string(trimmed) {
bail!("{span}: unterminated string: ... (line: {trimmed})");
}
```
没有这一层,用户会看到 `unrecognized statement: **s = "abc`——
能定位到行,但不知道是引号没闭合。
---
## 4. 影响面(改前量化过)
对仓库内全部 `.mq.md`(`target/` 除外)做静态扫描,正确跳过 `\` 转义:
| 指标 | 数值 |
|------|------|
| `.mq.md` 文件总数 | 845 |
| 含 `**` 起始代码行的文件 | 620 |
| **引号计数为奇数的代码行** | **0** |
**结论:不改变任何现有文件的解析结果。** 这条修复只作用于畸形输入。
---
## 5. 测试
### 5.1 新增单元测试(`src/lex/mod.rs`,4 个)
| 测试 | 断言 |
|------|------|
| `unterminated_quote_inside_bold_is_code_not_comment` | 未闭合引号的粗体行 → `Code`(修复前失败,修复后通过) |
| `balanced_quote_inside_bold_still_code` | 闭合引号仍是 `Code` |
| `prose_with_quotes_stays_comment` | 叙述里提引号 → 仍是 `Comment` |
| `prose_bold_emphasis_with_quote_stays_comment` | 叙述里含孤立引号 → 仍是 `Comment` |
**先写测试确认失败**(TDD):
```
---- lex::tests::unterminated_quote_inside_bold_is_code_not_comment
panicked: expected Code (so parser reports the error),
got [ClassifiedLine { kind: Comment, text: "**s = \"abc" }]
```
修复后 14/14 通过。
### 5.2 回归
| 范围 | 结果 |
|------|------|
| `cargo test --release --lib` | **237 passed, 0 failed**(基线 233 + 新增 4) |
| `cargo test --release --test gold` | 276 passed, 8 failed |
| ↑ 上述 8 个失败是否本次引入 | **否**。`git stash` 后基线同样 8 failed |
| 8 个失败的原因 | 全部 `ext_web_*`,依赖 Go 插件 `libweb` 构建,本机环境不具备 |
---
## 6. 已知边界
| 情形 | 行为 | 说明 |
|------|------|------|
| `**s = "a` + 下一行 `b"**` | 报错 | 字符串不跨行,符合现状 |
| 单引号 `'...'` 未闭合 | **仍是旧行为**(静默) | 本次只处理双引号;单引号在 Marqdo 里使用频率低,留作后续 |
| 叙述行含孤立 `"` | 不受影响 | 判定入口是 `starts_with("**")`,叙述行不进入 |
> 单引号的情况建议后续按同样思路处理,但需要单独评估
> (单引号也用于英文撇号,误判风险高于双引号)。
---
## 7. 变更清单
| 文件 | 变更 |
|------|------|
| `src/lex/mod.rs` | `is_marqdo_star_line` 增加未闭合引号分支;新增 `pub fn has_unterminated_string`;新增 4 个测试 |
| `src/parse/mod.rs` | import 辅助函数;`parse_simple_stmt` 增加精确报错分支 |
| `doc/design/parser-diagnostics-d8-d9.md` | 新增(设计依据 + 影响面 + 方案评判) |
| `doc/design/spaced-function-names-d8.md` | 新增(D8 方案评估,待审阅) |
| `doc/design/change-d9-unterminated-string.md` | 本文件 |
---
## 8. 附:本机测试环境(2026-10-22 装好)
修复过程中发现本机缺两样东西,导致基线本来就有失败。补环境后全量测试 **554 passed / 0 failed**。
### 8.1 两个非直觉约束
| 约束 | 表现 | 解法 |
|------|------|------|
| `$HOME` 不可写 | zig 报 `error: AccessDenied`(全局缓存无处可写) | `ZIG_GLOBAL_CACHE_DIR` / `ZIG_LOCAL_CACHE_DIR` 显式指向工作区 |
| **`/tmp` 是 noexec tmpfs** | Go 链接报 `running gcc failed: signal: aborted`;zig 链接报 `AccessDenied` | `TMPDIR` 指向可写**且可执行**目录 |
第二条最隐蔽:`/tmp` 挂载为 `rw,nosuid,nodev,noexec`,构建工具会把产物写到那里再执行,
于是「文件能写、却执行不了」。错误信息完全指向不了这一点。
### 8.2 Go 插件(`libweb.so`)
`gold` 测试里 8 个 `ext_web_*` 失败全因缺 `libweb.so`:
```bash
source scripts/dev-env.sh # 提供 go 1.25 + gcc shim(zig) + TMPDIR
./scripts/build-web-plugin.sh # 产出 plugins/web/build/libweb.so
cp plugins/web/build/libweb.so target/release/ target/debug/
```
Go 的 cgo 要 `gcc`,本机没有,用 zig cc 充当:
`/workspace/qdagent/.tools/zigcc/bin/gcc`(会过滤 Go 传入的 `-Qunused-arguments`,
该参数会让 zig 驱动 abort)。
### 8.3 一键复用
新增 `scripts/dev-env.sh`,`source` 后即具备完整工具链:
```
marqdo dev-env: rust=1.81.0 go=go1.25.0 python=3.12.15 cc=zig-glibc2.36
```
### 8.4 环境修复前后的测试对比
| 阶段 | lib 测试 | gold 测试 |
|------|----------|-----------|
| 无 python3 | 231 / 2 failed | — |
| 加 python3 | 233 / 0 failed | 276 / 8 failed |
| 加 go + libweb | — | **284 / 0 failed** |
| **全量** | | **554 passed / 0 failed** |
+99
View File
@@ -0,0 +1,99 @@
# 变更记录:HostFn 五张表合一(`HOST_FN_TABLE` 单一来源)
| | |
|---|---|
| 状态 | **Implemented** |
| 日期 | 2026-10-22 |
| 来源 | [code-volume-audit.md](code-volume-audit.md) §4 第 4 项 |
| 改动 | `src/host/dispatch.rs`:**−404 行**(639 删 / 235 增) |
| 行为 | **零变化**(203 项逐字节一致) |
---
## 1. 原来有五张并行表
202 个宿主函数的元数据分散在五个手写 match 里:
| 表 | 行数 | 作用 |
|----|------|------|
| `from_u16` | ~215 | id → 变体 |
| `from_name` | ~215 | 名字/别名 → 变体(**保留**,见 §4) |
| `name` | ~210 | 变体 → 规范名 |
| `required_params` | ~145 | 变体 → 必填参数 |
| `optional_params` | ~90 | 变体 → 可选参数 |
五张表必须同步维护,而 [code-volume-audit.md](code-volume-audit.md) 记录过
`from_name` 接受 `http_get` 而 `name()` 只输出 `host_http_get` 的一类漂移。
## 2. 现在只有一张
```rust
pub struct HostFnDef {
pub id: u16,
pub f: HostFn,
pub name: &'static str,
pub required: &'static [&'static str],
pub optional: &'static [&'static str],
}
pub const HOST_FN_TABLE: &[HostFnDef] = &[
HostFnDef { id: 1, f: HostFn::ReadText, name: "host_read_text",
required: &["path"], optional: &[] },
…
];
```
四个函数改为查表(`from_u16` 按 id 查,其余按判别值查);
`call_host` 保留它那 202 个一行臂——**分派逻辑不动**,只把元数据集中。
## 3. 怎么保证没改坏
迁移采用**快照比对**:
1. 先在旧实现上导出全部 203 项的 `(id, name, required, optional)` 到 TSV
2. 合并成表后,用同一段代码再导出一份
3. `diff` 两份文件 → **完全一致**
```
$ diff /tmp/host_fns_baseline.tsv /tmp/host_fns_new.tsv && echo IDENTICAL
IDENTICAL
```
快照测试是一次性的,比对通过后删除;长期守护交给四个不变量测试:
| 测试 | 内容 |
|------|------|
| `every_assigned_id_round_trips` | 每个已分配 id → `as_u16()` 往返(id 空间稀疏是**退役 id**,不复用) |
| `every_id_has_a_name_that_round_trips` | `name()` → `from_name()` 回到同一变体 |
| `names_are_unique` | 规范名唯一 |
| `required_and_optional_params_are_disjoint` | 必填/可选不重叠、`all_params` 无重复 |
## 4. 为什么 `from_name` 没有并进表
它是**别名注册表**(`http_get`、`get`、中文别名…),语义与"规范名"不同;
并进表会让 `name()` 与 `from_name` 又变成一对映射。
现在它保留原样,由上面的往返测试保证不与表漂移。
## 5. 收益
| 指标 | 前 | 后 |
|------|----|----|
| `dispatch.rs` | 2,052 行 | **1,648 行** |
| `src/` 合计 | 53,040 | **52,668** |
| 需同步维护的表 | 5 | **1** |
## 6. 验证
| 项 | 结果 |
|----|------|
| `cargo build --release` | 零警告 |
| `cargo test --release` | **609 passed / 0 failed** |
| 快照 diff | 203 项逐字节一致 |
| 四个不变量测试 | 全绿 |
## 7. 变更清单
| 文件 | 变更 |
|------|------|
| `src/host/dispatch.rs` | 新增 `HostFnDef` / `HOST_FN_TABLE`(203 项);`from_u16` / `name` / `required_params` / `optional_params` 改为查表;删除对应四个 match |
| `doc/design/change-hostfn-table.md` | 本文件 |
+134
View File
@@ -0,0 +1,134 @@
# 变更记录:M1 `()` 内调用语法(`)` 终止 / 逗号 / 嵌套 / 空格 callee)
| | |
|---|---|
| 状态 | **Implemented** |
| 日期 | 2026-10-22 |
| 里程碑 | M1([occlusion-syntax.md](occlusion-syntax.md) §13) |
| 改动文件 | `src/parse/expr.rs` |
| 影响面 | **共享参数分词器**(所有调用都会经过) |
---
## 1. 修了什么
四件事,一句概括:**`(…)` 现在是一等调用外形**。
| # | 前 | 后 |
|---|----|----|
| 1 | `加(31)` 报 `unknown function 加(31` | ✅ 调用,返回 32 |
| 2 | 末个位置实参会吞掉 `)` | `)` 是**参数终止符** |
| 3 | 只支持空白分隔 | 支持 `,` / `,` 可选分隔 |
| 4 | 嵌套 `加(加(1 2), 3)` 不可用 | ✅ 递归解析 |
| 5 | `加一 号(31)` 不可用(D8) | ✅ **callee 可含空格** |
实测(1.5.2 本地构建,tree 与 bytecode 双后端结果一致):
```
空格参=3 加(1 2)
逗号=3 加(1, 2)
嵌套=13 加(加(1 2), 10)
带空格callee=32 加一 号(31) ← 缺陷 D8 的结构性解法
库函数=x txt.str_trim(" x ")
具名=3 加(a=1, b=2)
```
---
## 2. 实现要点
### 2.1 参数扫描:深度感知 + `)` 终止
`split_first_token` 与 `find_next_arg_boundary` 改为**通用扫描器**:
- 跟踪 `()` `[]` `{}` 嵌套、`"…"` 字符串、`` `…` `` 反引号
- **顶层** `)` / 空白(以及括号形里的 `,`)终止当前 token,且**不吞掉终止符**
- 字符串内的逗号不受影响(`拼接("a,b", "c")` 仍是 2 个参数)
### 2.2 `try_paren_call`:callee = 第一个 `(` 之前的全部文本
```rust
let Some(open) = s.find('(') else { return Ok(None) };
let callee_tok = s[..open].trim(); // 允许空格
```
**安全护栏**(否则会误判):
| callee 里出现 | 判定 |
|--------------|------|
| `=` | 不是括号调用(那是 `text=a(b)` 具名实参) |
| `[` `]` `(` `)` `"` `'` | 不是括号调用(那是 `trim [stdout](…)` 方括号实参) |
| 以 `[` `]` `"` `'` 开头 | 不是括号调用 |
| 反引号 | **允许**(保留 `` `obj`.方法(…) `` 接收者写法) |
### 2.3 表达式级 postfix 调用
`parse_primary` 的裸词分支:**紧跟** `(` 时按调用解析。
```rust
if self.allow_paren_call && self.rest().starts_with('(') { … }
```
要求"紧跟"(不隔空格),使 `加 (1)` 仍是原来的"文本 + 括号"行为。
### 2.4 方括号形也允许空格 callee
`is_bracket_callee_inner` 不再拒绝空白:`[加一 号] 31` 可用。
(仓库内可执行的方括号调用用量为 0,风险极低。)
---
## 3. 关键设计决策:括号形 vs 空格形的参数**值**语义不同
这是本里程碑唯一有争议的点,必须写清。
| 形态 | 参数值 | 例子 |
|------|--------|------|
| **括号形** `f(…)` | 表达式(**允许** `name(args)` 调用) | `加(加(1 2), 3)` |
| **空格形** `> f k=v` | 文本(**不允许**裸 `name(args)` 变成调用) | `source=print(2+2)` 仍是文本 |
**为什么必须区分**:`source=print(2+2)` 在 Marqdo 里历来是**文本**(未加引号的实参按文本处理)。
若不区分,它会变成对 `print` 的调用,`foreign.run_lang` 直接报 `source must be text`
—— 这正是本次回归测试抓到的 3 个失败。
实现:`Parser` 增加 `allow_paren_call` 字段;`parse_call_arg_value_mode(input, prefer_var, allow_call)`
统一两种值解析(`allow_call=false` 即旧行为)。
---
## 4. 测试
| 层 | 内容 | 结果 |
|----|------|------|
| 单元 | 新增 11 个(单参/多参/逗号/具名/空格 callee/零参/库路径/嵌套/引号内逗号/旧写法不回归/方括号形) | ✅ |
| 全量 | `cargo test --release` | **565 passed / 0 failed**(基线 554 + 11) |
| 双后端 | tree 与 `--backend bytecode` 跑同一文档 | 输出一致 |
| 端到端 | `marqdo run` 六个用例 | 输出符合预期 |
**TDD 过程**:先写 11 个测试 → 10 个失败(红灯确认)→ 实现 → 全绿。
---
## 5. 顺带移除的死代码
`end_of_quoted_string`:新扫描器取代其唯一用途后变成 `never used`,删除(编译器警告清零)。
---
## 6. 边界(本里程碑不做)
| 项 | 说明 |
|----|------|
| 逗号仅在括号形生效 | 空格形 `text=a,b` 的逗号仍是文本(兼容) |
| `加 (1)`(空格后跟括号) | 不视为调用,保持旧行为 |
| 遮蔽语法 `[描述](…)` | M2 才引入,本里程碑不解析 |
| 位置实参顺序脆弱性 | 与叙述顺序绑定,M7/M8 再处理(诊断) |
---
## 7. 变更清单
| 文件 | 变更 |
|------|------|
| `src/parse/expr.rs` | 参数扫描器重写(`)`/逗号/嵌套);新增 `try_paren_call` + `split_callee` 抽取;表达式级 postfix 调用;`Parser.allow_paren_call`;`parse_call_arg_value_mode` 统一两种值语义;方括号 callee 允许空格;删除 `end_of_quoted_string` |
| `doc/design/change-m1-paren-call.md` | 本文件 |
+73
View File
@@ -0,0 +1,73 @@
# 变更记录:M10 工程化落点(README + agent 提示词)
| | |
|---|---|
| 状态 | **Implemented** |
| 日期 | 2026-10-22 |
| 里程碑 | M10([occlusion-description-and-search.md](occlusion-description-and-search.md) §5) |
| 改动文件 | `ext/ai/agent.mq.md`(README 一节已在文档阶段落地) |
---
## 1. 改了什么
把「接不了就申报,别假装完成」写进 **agent 的默认提示词**,两处:
### 1.1 `how-to-act` 协议段(每轮都会带)
```
Call ONLY names listed under --- tools --- (whitelist). …
If a capability cannot truly be wired, do NOT fake it silently and never claim it works:
write an occlusion with an explicit status, e.g. [按关键词检索,接口未接,待开发](None).
Stubs must run without error and must state their return value (None is acceptable).
Before finishing, check your own declarations with labels.search.
Tools run via Marqdo subtask (spawn fn / wait).
```
### 1.2 默认 standing(`p`)
```
You are a Marqdo agent. Code is documentation: … not a hidden system prompt.
When you cannot wire a capability, declare it in the description (待开发 / 模拟)
instead of faking success.
```
**为什么这两处**:standing 定基调(每次对话开头),how-to-act 定动作(每轮)。
只写 standing 容易被长上下文冲淡;只写 how-to-act 又缺"为什么要申报"。
---
## 2. 设计要点
| 要点 | 说明 |
|------|------|
| 给**范式**而不是规则 | 直接给出可抄的 `[按关键词检索,接口未接,待开发](None)`,模型不必发明措辞 |
| 给**返回值**要求 | "必须写清返回什么(None 也行)"——对应 `label.empty_payload` 的 warning |
| 给**自查**动作 | `labels.search` 让模型收尾时能自己盘点,而不是靠人提醒 |
| 用**英文**写 | 与既有 standing / 协议段语言一致(模型对英文指令更稳) |
---
## 3. 验证
| 项 | 结果 |
|----|------|
| `marqdo check ext/ai/agent.mq.md`(occlusion 模式) | `contract check OK` |
| 提示词文本落入模块 | `grep` 命中 2 处(standing 与 how-to-act 各 1) |
| 全量回归 | 587 passed / 0 failed(与 M9 相同,本改动不动逻辑) |
---
## 4. 边界
- 提示词是**建议**,不是门禁;违反不会被拒绝,但会在描述/诊断里暴露。
- `labels.search` 需要 M7 翻转默认后对 classic 文档才有意义;提示词先就位。
---
## 5. 变更清单
| 文件 | 变更 |
|------|------|
| `ext/ai/agent.mq.md` | how-to-act 协议段与默认 standing 各追加申报约定 |
| `doc/design/change-m10-engineering-habits.md` | 本文件 |
+126
View File
@@ -0,0 +1,126 @@
# 变更记录:M2 遮蔽语法 `[描述](实现)`
| | |
|---|---|
| 状态 | **Implemented**(模式开关默认仍是 classic) |
| 日期 | 2026-10-22 |
| 里程碑 | M2([occlusion-syntax.md](occlusion-syntax.md) §13) |
| 改动文件 | `src/ast.rs` · `src/parse/expr.rs` · `src/parse/mod.rs` · `src/interp.rs` · `src/bytecode/compile.rs` · `src/view/render.rs` · `src/main.rs` · `tests/occlusion.rs` |
| 影响面 | 语法(新节点)+ 两个后端 + 渲染 |
---
## 1. 新增语法
```markdown
[描述](实现)
```
- `[]` = **描述**(自由文本,**永不执行**;仅用于检索、统计、过期校验)
- `()` = **实现**(唯一执行体)
- `[]` 为空 → `label.missing`(error,M2.5 落诊断)
- `()` 为空 → 值为 `None`(空载荷桩,M2.5 落 warning)
实测(`MARQDO_MARKUP=occlusion`):
```
a=2 [加一之后的值](1 + 1)
b=42 [外层]([内层](40 + 2)) ← 嵌套遮蔽
c=True [某某功能开发中]() ← 空载荷 → None
```
---
## 2. 关键决策:**模式开关,暂不切换语义**
`[键](集合)` 与 `[描述](实现)` **外形完全相同**。若 M2 直接改语义,全仓 506 处取元
会**静默变成"遮蔽整个集合"** —— 这正是文档里点名的最坏一类变更(同形换义)。
因此 M2 只**实现能力**,不动默认:
| 模式 | `MARQDO_MARKUP` | `[a](b)` 的语义 |
|------|-----------------|-----------------|
| `Classic`(默认) | 未设 / 其他值 | 取元(今天的行为) |
| `Occlusion`(纯度) | `occlusion` / `purity` / `1` / `on` | 遮蔽(描述 + 实现) |
**M7 才迁移语料并翻转默认**,同时对旧形报 `syntax.legacy_index` 硬错误。
这样 M2 可独立验证,且不会出现"半迁移的静默错义"。
---
## 3. 实现要点
### 3.1 AST
```rust
Occluded {
label: String,
payload: Option<Box<Expr>>, // None = 空载荷桩(值 None)
}
```
### 3.2 解析
- `Parser` 增加 `markup: Markup` 字段;`parse_expr_markup(input, prefer_var, markup)`
供测试/迁移显式指定;CLI 通过 `MARQDO_MARKUP` 设置进程默认。
- 描述扫描:读到 `]` 为止;`\]` 转义字面方括号;跨行即报未闭合。
- 之后必须紧跟 `(`;`()` 内若无内容 → `payload: None`;否则 `parse_or()` 后要求 `)`。
- 嵌套自然成立:payload 是完整表达式,可再含遮蔽。
### 3.3 求值(两个后端一致)
| 位置 | 处理 |
|------|------|
| `interp.rs` `eval_expr` | 有 payload → 求值 payload;无 → `Value::None` |
| `bytecode/compile.rs` | 有 payload → 编译 payload;无 → `Op::None_` |
| `collect_decl_reads` / `collect_reads_expr` | 递归 payload(描述不产生读引用) |
| `view/render.rs` `expr_prec` | 渲染成 `[描述](payload)` / `[描述]()` |
**描述永不参与求值**——守住铁律 1。
---
## 4. 测试
| 层 | 内容 | 结果 |
|----|------|------|
| 单元(8) | 值直通 / 空载荷 / 描述含空格与标点 / `\]` 转义 / 嵌套 / classic 仍是取元 / 缺括号报错 | ✅ |
| 集成(3) | `MARQDO_MARKUP=occlusion` 跑通三个值;不设该变量时旧取元不变;occlusion 模式下旧形**不再**是取元 | ✅ |
| 全量 | `cargo test --release` | **575 passed / 0 failed**(M1 后 565 + 10) |
| 双后端 | tree 与 `--backend bytecode` | 一致 |
---
## 5. 顺带重构
- `Markup` 枚举与 `parse_expr_markup` 抽为显式参数,避免测试依赖全局可变状态
(全局只由 CLI 入口设置一次)。
- `parse::expr` 由 `mod` 改 `pub mod`,供 `main.rs` 设置模式。
---
## 6. 边界
| 项 | 说明 |
|----|------|
| 描述不参与作用域/类型 | 写什么都不影响执行 |
| 描述里的 `` `实体` `` | M4 才做引用一致性校验 |
| 空载荷 warning | M2.5 落诊断(本提交只有语义) |
| 跨行描述 | 不支持(v1) |
| 旧取元 | 仍可用;M7 迁移后改为硬错误 |
---
## 7. 变更清单
| 文件 | 变更 |
|------|------|
| `src/ast.rs` | 新增 `Expr::Occluded { label, payload }` |
| `src/parse/expr.rs` | `Markup` 枚举 + 全局默认 + `parse_expr_markup` + `parse_occluded` + `Parser.markup` |
| `src/parse/mod.rs` | `pub mod expr`;`collect_reads_expr` 递归 payload |
| `src/interp.rs` | 求值 + 读引用收集 |
| `src/bytecode/compile.rs` | 编译为 payload(或 `None_`) |
| `src/view/render.rs` | 表面渲染 + 输入提示收集 |
| `src/main.rs` | `MARQDO_MARKUP` 环境变量 |
| `tests/occlusion/value.mq.md` · `tests/occlusion/classic-index.mq.md` · `tests/occlusion.rs` | 新增集成测试 |
| `doc/design/change-m2-occlusion.md` | 本文件 |
+91
View File
@@ -0,0 +1,91 @@
# 变更记录:M2.5 遮蔽标签诊断(`label.missing` / `label.empty_payload`)
| | |
|---|---|
| 状态 | **Implemented** |
| 日期 | 2026-10-22 |
| 里程碑 | M2.5([occlusion-syntax.md](occlusion-syntax.md) §13,诊断规范 §10) |
| 改动文件 | **新增 `src/label.rs`** · `src/check.rs` · `src/lib.rs` · `tests/occlusion.rs` |
| 影响面 | `marqdo check`(新增两类诊断) |
---
## 1. 两条诊断
| code | 级别 | 触发 | 文案要点 |
|------|------|------|---------|
| `label.missing` | **error** | `[](实现)` 描述为空 | 「给这段实现写一句人话,或改用不带遮蔽的写法」 |
| `label.empty_payload` | **warning** | `[描述]()` 载荷为空 | 「这里没有可执行内容」,建议写 `(None)` 或补实现 |
实测:
```
$ MARQDO_MARKUP=occlusion marqdo check empty-label.mq.md
empty-label.mq.md:3:1: 遮蔽缺少描述:`[](…)` —— 给这段实现写一句人话,或改用不带遮蔽的写法
contract check: 1 条诊断(1 error) # exit 1
$ MARQDO_MARKUP=occlusion marqdo check empty-payload.mq.md
empty-payload.mq.md:3:1: 空载荷遮蔽:`[某某功能开发中]()` —— 这里没有可执行内容
contract check: 1 条诊断(0 error) # exit 0(warning 不影响退出码)
```
JSON 出口(自动继承既有 schema,含 `doc_quote`):
```json
{"code":"label.empty_payload","severity":"warning","span":{"line":3,"col":1},
"doc_quote":"某某功能开发中","message":"空载荷遮蔽:…","suggestion":"写清桩的返回值(如 `(None)` 或 `(0)`)…"}
```
---
## 2. 实现
### 2.1 新增 `src/label.rs`
- `OcclusionSite { label, has_payload, line, unit }`
- `collect(module)`:遍历函数体与嵌套语句/表达式,收集所有遮蔽点
(描述只读,**不产生任何读引用**)
- `check(module, path)`:产出上面两条诊断
### 2.2 接入 `check_module`
```rust
walk(module, &module.functions, path, &known, &mut out);
out.extend(crate::label::check(module, path)); // M2.5
```
设计上把"标签诊断"独立成模块,M4(引用一致性)与 M9(检索)都往这里加,
`check` 只做一行汇总。
---
## 3. 测试
| 层 | 内容 | 结果 |
|----|------|------|
| 集成(3 新) | 空描述 → exit 1 + 文案;空载荷 → exit 0 + 文案;干净样例 → 无诊断 | ✅ |
| 全量 | `cargo test --release` | **578 passed / 0 failed**(M2 后 575 + 3) |
反向验证:三条断言分别验证"会响"与"不会误响"(干净样例必须无输出)。
---
## 4. 边界
| 项 | 说明 |
|----|------|
| 描述内容不校验 | 写什么都可以;M4 才校验反引号引用 |
| 空载荷仅在 occlusion 模式可能出现 | classic 模式下 `()` 空是语法错 |
| warning 不影响退出码 | 与既有 `Severity` 语义一致 |
---
## 5. 变更清单
| 文件 | 变更 |
|------|------|
| `src/label.rs` | **新增**:遮蔽点收集 + 两类诊断 |
| `src/lib.rs` | `pub mod label;` |
| `src/check.rs` | `check_module` 追加 label 诊断 |
| `tests/occlusion.rs` + `tests/occlusion/{empty-label,empty-payload,clean}.mq.md` | 新增 3 个集成测试与样例 |
| `doc/design/change-m25-label-diagnostics.md` | 本文件 |
+89
View File
@@ -0,0 +1,89 @@
# 变更记录:M3 `access` 与遮蔽循环
| | |
|---|---|
| 状态 | **Implemented** |
| 日期 | 2026-10-22 |
| 里程碑 | M3([occlusion-syntax.md](occlusion-syntax.md) §4 / §13) |
| 改动文件 | `src/interp.rs` · `src/ast.rs` · `src/parse/mod.rs` · `src/bytecode/compile.rs` · `tests/occlusion.rs` |
| 影响面 | 新增内建 `access`;`Stmt::ForEach` 增可选标签 |
---
## 1. `access(集合, 键)`
旧取元 `[键](集合)` 的语义是**多态**的:Map 按键、List 按 1-based 下标、缺键报错。
纯度路线把取元移进 `()`,因此需要一个与之**完全等价**的调用形式:
```markdown
**a = [取表项](access(`表`, "键"))**
**b = [取列表第二项](access(`列`, 2))**
```
- 别名:`取` / `取值` / `access`
- 缺键 → `missing map key …`(**与旧取元同一错误**,不静默返回 None)
- 用途:M7 迁移把 `[k](c)` 机械改写成 `access(c, k)`,语义零漂移
实现:`interp.rs` 的 special-callee 分派里直接复用 `builtin_footnote_get`,
**不新增平行实现**(避免两套索引语义)。
---
## 2. 遮蔽循环
```markdown
- [篮子里的每个果子](遍历 `列` 为 `果`)
> print text=`果`
```
- 只在 occlusion 模式识别(classic 模式下 `- [x](c)` 仍是旧 foreach)
- 接受 `遍历`/`for` 与 `为`/`as`/`in`
- 描述存入 `Stmt::ForEach.label`(`Option<String>`),供 M8 渲染/诊断使用
实测:
```
a=值
b=二
果子=一
果子=二
```
---
## 3. 为什么先做 M3 再做 M7
迁移(M7)要把 506 处 `[k](c)` 改写掉,而改写目标必须**先存在且等价**。
先有 `access` 与循环新形,迁移才是"机械替换",而不是"边迁移边发明语义"。
---
## 4. 测试
| 层 | 内容 | 结果 |
|----|------|------|
| 集成(2) | `access` 表/列表 + 循环遍历输出正确;缺键报 `missing map key`(与旧取元一致) | ✅ |
| 全量 | `cargo test --release` | **595 passed / 0 failed**(M5 后 593 + 2) |
---
## 5. 边界
| 项 | 说明 |
|----|------|
| `access` 不做缺省值 | 缺省语义请用 `get(表, 键, 默认)`;两者并存 |
| 循环描述暂只存不用 | M8 在 `view` 与诊断里使用 |
| 旧 foreach 仍可用 | M7 迁移并加门禁后才变成错误 |
---
## 6. 变更清单
| 文件 | 变更 |
|------|------|
| `src/interp.rs` | `access` / `取` / `取值` 分派(复用 `builtin_footnote_get`) |
| `src/ast.rs` | `Stmt::ForEach.label: Option<String>` |
| `src/parse/mod.rs` | `parse_occluded_foreach`;occlusion 模式下优先识别 |
| `src/bytecode/compile.rs` / `src/ast.rs` / `src/interp.rs` | 穷举模式补 `label: _` |
| `tests/occlusion.rs` + `tests/occlusion/access-and-loop.mq.md` | 2 个集成测试 |
| `doc/design/change-m3-access-and-loop.md` | 本文件 |
+84
View File
@@ -0,0 +1,84 @@
# 变更记录:M4 L1 引用一致性(`label.ref_dangling`)
| | |
|---|---|
| 状态 | **Implemented** |
| 日期 | 2026-10-22 |
| 里程碑 | M4([label-freshness-and-repair.md](label-freshness-and-repair.md) §3.1 / [occlusion-syntax.md](occlusion-syntax.md) §11.1) |
| 改动文件 | `src/label.rs` · `tests/occlusion.rs` · `tests/occlusion/ref-*.mq.md` |
| 影响面 | `marqdo check`(新增一条 error) |
---
## 1. 规则
> 描述里用反引号写出的名字 = **断言**:它必须能解析
> —— 要么 `()` 的实现用到它,要么文档里定义了它,要么它是内置函数。
```markdown
**a = [按 `税率` 计算](100 * 0.1)** # ❌ label.ref_dangling(税率为空悬)
**b = [按 `税率` 算](100 * `税率`)** # ✅ 实现里用到
**c = [取长度](len("abc"))** # ✅ 内置函数
**d = [用 `加` 求和](> 加 1 2))** # ✅ 模块内函数
```
实测:
```
dangling.mq.md:3:1: 描述引用了不存在的实体:`税率` —— 本段实现没有用到它,模块里也没有定义
contract check: 1 条诊断(1 error) # exit 1
```
---
## 2. 为什么只认反引号(可证伪原则)
| 写法 | 是否检查 | 原因 |
|------|---------|------|
| `` `税率` `` | ✅ | 显式引用,可证伪 |
| 普通汉字"税率" | ❌ | 自然语言无法机械判定,检查必然假阳性 |
代价:作者不写反引号就得不到保护。这是刻意的——**机器只校验它看得懂的断言**,
同时反向抑制"为凑数写废话"。
---
## 3. 实现
| 环节 | 做法 |
|------|------|
| 抽取 | `refs(label)`:扫描成对反引号,取内部去空白;未闭合/空串忽略 |
| 作用域 | `payload_idents(payload)`(Var / callee / path / receiver / `[k]` 的变量键 / 插值变量)∪ `module_symbols(module)`(函数与子函数、参数、import/use 绑定、frontmatter 键)∪ `HostFn::from_name` |
| 诊断 | `label.ref_dangling`,**error**,带 `doc_quote`(描述原文)与可执行建议 |
`OcclusionSite` 增加 `payload_idents` 字段,在 `collect` 阶段一次算好,`check` 只做集合查找。
---
## 4. 测试
| 层 | 内容 | 结果 |
|----|------|------|
| 单元(3) | 单引用 / 多引用与散文混排 / 无引用与未闭合反引号不 panic | ✅ |
| 集成(2) | 悬空引用 exit 1 + 文案;三类可解析引用(payload 变量 / 内置 / 模块函数)零诊断 | ✅ |
| 全量 | `cargo test --release` | **583 passed / 0 failed**(M2.5 后 578 + 5) |
---
## 5. 边界与后续
| 项 | 说明 |
|----|------|
| 只查"能否解析" | 不查"语义是否仍成立"——那是 T1(M6)与人工/LLM 复核的活 |
| 不查"能解析但实现没用到" | 该情形在模块级符号时无法区分误报,留待 T1 变更驱动 |
| 描述里的反引号不是变量绑定 | 只是断言,不进入任何作用域 |
---
## 6. 变更清单
| 文件 | 变更 |
|------|------|
| `src/label.rs` | `refs()` · `payload_idents()` · `module_symbols()` · `OcclusionSite.payload_idents` · `check` 增 `label.ref_dangling` · 3 个单测 |
| `tests/occlusion.rs` + `tests/occlusion/{ref-dangling,ref-ok}.mq.md` | 2 个集成测试 |
| `doc/design/change-m4-label-refs.md` | 本文件 |
+103
View File
@@ -0,0 +1,103 @@
# 变更记录:M5 隐式遮蔽(`>` 调用上方的叙述)
| | |
|---|---|
| 状态 | **Implemented**(**默认关闭**,`--implicit-labels` 开启) |
| 日期 | 2026-10-22 |
| 里程碑 | M5([occlusion-syntax.md](occlusion-syntax.md) §11.2) |
| 改动文件 | `src/label.rs` · `src/check.rs` · `src/main.rs` · `tests/occlusion.rs` |
| 影响面 | `marqdo check` 新增可选检查(默认不改变输出) |
---
## 1. 规则
> **`>` 调用上方的叙述段**就是它的"描述";段内的反引号实体必须被这次调用用到
> (或能解析到模块/内置)。
```markdown
按 `税率` 与 `档位` 计算应缴税额: ← 描述
> 计税 档位=2 金额=100 ← 实现用到了 `档位`,但没有 `税率`
```
```
impl.mq.md:5:1: 调用上方的描述提到 `税率`,但这次调用没有用到它
```
段落边界:紧邻上一行起,遇空行(允许**一个**分隔空行,因为 blockquote 前通常空一行)、
标题、代码行(`**`/`>`/`-`/`|`/数字开头)即止。
---
## 2. 关键决策:**默认关闭**
这不是洁癖,是实测结论:
| 阶段 | lib + ext/ai 上的警告数 |
|------|------------------------|
| 初版(任何反引号都算断言) | **6 条**(全部误报:`` `## open` ``、`` `{ path, kind }` ``、`` `source=` ``、`` `exec` ``/`` `net` ``) |
| 加"实体名形状"过滤 | 2 条 |
| **再加默认关闭** | **0 条** |
理由:**描述一个调用可以用任意措辞**,这比"遮蔽"松散得多;
机械校验必然模糊,默认开启就会制造疲劳(违背 [warning-fatigue-control.md](warning-fatigue-control.md))。
所以它和 L1 不同:L1 是"能证明才报",隐式检查是"觉得可疑就报"——后者必须 opt-in。
---
## 3. 实体名过滤(降低误报)
反引号内容必须**像实体名**才算断言:
```rust
首字符:字母 / `_` / 非 ASCII(不能是数字)
其余:字母数字 / `_` / `.` / 非 ASCII 且非空白
```
于是 `` `## open` ``、`` `{ path, kind }` ``、`` `source=` ``、`` `path=` `` 全部被排除。
---
## 4. 用法
```bash
marqdo check 文件.mq.md # 默认:不含隐式检查(零噪音)
marqdo check 文件.mq.md --implicit-labels # 开启
```
MLSP 侧留了同义参数位(`validate` 的 `implicit_labels`),M8 一并接。
---
## 5. 测试
| 层 | 内容 | 结果 |
|----|------|------|
| 集成(3) | 默认静默;opt-in 报不一致;opt-in 对一致描述仍静默 | ✅ |
| 全量 | `cargo test --release` | **593 passed / 0 failed**(M6 后 590 + 3) |
**反向验证**:`implicit_labels_off_by_default` 与 `..._stays_quiet_when_consistent`
两条都在证明"不乱响"。
---
## 6. 边界
| 项 | 说明 |
|----|------|
| 只查 `>` 语句调用 | 表达式内调用没有"上方叙述"这回事 |
| 只认反引号 + 实体形状 | 普通散文永远不参与 |
| 不查 payload 语义 | 只查"提到的实体是否被用到" |
---
## 7. 变更清单
| 文件 | 变更 |
|------|------|
| `src/label.rs` | `CallSite` · `call_sites` · `paragraph_above` · `is_entity_ref` · `check_implicit` |
| `src/check.rs` | `check_path_opts(path, implicit_labels)`(`check_path` 保持默认关闭) |
| `src/main.rs` | `check --implicit-labels` |
| `tests/occlusion.rs` + `tests/occlusion/implicit-*.mq.md` | 3 个集成测试 |
| `doc/design/change-m5-implicit-occlusion.md` | 本文件 |
+109
View File
@@ -0,0 +1,109 @@
# 变更记录:M6 T1 会话内陈旧检测 + 会话末汇总
| | |
|---|---|
| 状态 | **Implemented** |
| 日期 | 2026-10-22 |
| 里程碑 | M6([t1-session-staleness.md](t1-session-staleness.md) · [staleness-providers.md](staleness-providers.md) T1) |
| 改动文件 | `src/label.rs` · `src/mlsp.rs` · `src/view/mod.rs` · `tests/occlusion.rs` |
| 影响面 | MLSP `repair_apply` 新增可选字段;新增 `session.summary` 方法 |
---
## 1. 机制
`repair_apply` 内部同一作用域里同时有 `source`(改前)与 `new_source`(改后),
所以「描述是否还成立」可以**纯内存**判定:
```
stale ⟺ 标签文本未变 ∧ payload 指纹变了
```
配对按 `(标签文本, 出现序号)`,因此**移动代码不会误报**。
请求:
```json
{"method":"repair_apply","params":{
"source":"…","ranges":[[3,3]],
"edits":[{"op":"replace","line":3,"text":"**a = [按税率算总价](100 * 0.2)**"}],
"check_labels":true}}
```
响应:
```json
{"id":1,"ok":true,"result":{
"source":"…","edits_applied":1,
"labels":{"newly_seen":1,"stale":[
{"label":"按税率算总价","line":3,
"code_past":"100 * 0.1","code_now":"100 * 0.2"}]}}}
```
**同一份 `source` / `new_source` 就是"前一状态"**——不需要 git、不需要台账、
不需要沙箱里的 exec 权限。这是"agent 回路不需要 VCS"的落地。
---
## 2. 会话末汇总(你要求做)
`session.summary` 返回并**重置**计数:
```json
{"ok":true,"labels_stale_seen":1,"labels_fixed":0,
"labels_outstanding":1,"items":["按税率算总价"]}
```
| 字段 | 含义 |
|------|------|
| `labels_stale_seen` | 本次会话累计发现过多少条(去重按标签) |
| `labels_fixed` | 曾经 outstanding、现在不再 stale 的条数 |
| `labels_outstanding` | 仍未处理 |
| `items` | 未处理的标签文本(只给文本,不重复诊断细节) |
设计:客户端在收尾时调用一次即可闭合;**不主动打屏**,不污染协议。
---
## 3. 关键取舍
| 取舍 | 理由 |
|------|------|
| `check_labels` 默认 **false** | 零开销、零噪音;agent 框架在修复回路里显式打开 |
| 标签变了 → **不报** | 作者改描述本身就是"已复核"的信号 |
| 新标签 → 不报 | 无历史可比 |
| 指纹用 `Debug` | **只需进程内一致**;跨版本稳定指纹是 T2/T3 的事 |
| payload 渲染用 `view::expr_display` | 让 `code_past/code_now` 是人能读的表面语法,而非 AST 调试串 |
---
## 4. 测试
| 层 | 内容 | 结果 |
|----|------|------|
| 集成(3) | 只改 payload → `stale` 含 `code_past`/`code_now`;同时改标签 → `stale: []`;`session.summary` 计数正确 | ✅ |
| 全量 | `cargo test --release` | **590 passed / 0 failed**(M10 后 587 + 3) |
**反向验证**:`t1_silent_when_label_also_changes` 证明"改描述即复核"不会误报。
---
## 5. 边界
| 项 | 说明 |
|----|------|
| 只看本次编辑 | 跨会话漂移是 T2/T3 的职责(可选 provider) |
| 解析失败则跳过 | 修复后的源码可能语法错误,此时不评测标签,交给 `validate` |
| 会话状态是进程级 | 一条 MLSP 连接(一个进程)即一个会话;`session.summary` 后清零 |
---
## 6. 变更清单
| 文件 | 变更 |
|------|------|
| `src/label.rs` | `StaleItem` · `payload_fingerprint` · `compare` · `SessionSummary`(含 `record`)· `OcclusionSite.payload_fp/payload_src` |
| `src/mlsp.rs` | `repair_apply` 的 `check_labels`;`session.summary`;进程级 `SESSION` |
| `src/view/mod.rs` | `pub use render::expr_display`(供诊断渲染 payload) |
| `tests/occlusion.rs` | 3 个 T1 集成测试 |
| `doc/design/change-m6-t1-session.md` | 本文件 |
+127
View File
@@ -0,0 +1,127 @@
# 变更记录:M7 迁移与版本门(per-file 标记 + `migrate labels` + 全仓迁移)
| | |
|---|---|
| 状态 | **Implemented** |
| 日期 | 2026-10-22 |
| 里程碑 | M7([occlusion-syntax.md](occlusion-syntax.md) §13) |
| 改动文件 | **新增 `src/migrate.rs`** · `src/load.rs` · `src/parse/mod.rs`(expr) · `src/host/dispatch.rs` · **80 个语料文件** · 测试 |
| 影响面 | 语法模式按文件切换;全仓 256 处索引 + 23 处循环已迁移 |
---
## 1. 原计划的问题:同形换义
原设计想"翻转默认 + 对旧形硬报错"。但 `[键](集合)` 与 `[描述](实现)` **外形完全相同**:
- 翻转默认 → 506 处取元**静默变成**"遮蔽整个集合",正是文档点名的最坏变更
- 硬报错 → 无法实现:解析器拿不到"这是旧写法"的证据(两种读法都合法)
**结论:模式不能全局翻转,必须按文件声明。**
## 2. 新方案:per-file `markup:`
```markdown
---
markup: occlusion
---
```
| 文件 | 解析模式 | `[a](b)` 的含义 |
|------|---------|----------------|
| 无 `markup:` | classic(进程默认) | 取元 |
| `markup: occlusion` | 纯度 | 遮蔽 |
实现:`load.rs` 先读 frontmatter 取出模式,用 `parse::expr::with_markup(m, …)`
(线程局部覆盖,压栈/出栈)包住解析。**同一进程里可以同时加载两种模式的文件**
(imports!),且 `MARQDO_MARKUP=occlusion` 仍可作为进程默认。
好处:迁移是**逐文件、可增量、可回滚**的;不存在"半迁移的静默错义"。
## 3. 迁移工具 `marqdo migrate labels`
```bash
marqdo migrate labels . # 干跑:列出将改什么
marqdo migrate labels . --write # 实际写入
marqdo migrate labels . --json # 机器可读
```
### 3.1 改写规则
| 旧 | 新 |
|----|----|
| `[键](集合)` | `[键](access(集合, "键"))` |
| `` [`名`](集合) `` | `` [名](access(集合, `名`)) `` |
| `- [项](集合)` | `- [项](遍历 集合 为 项)` |
`access` 是新增宿主函数(`host_access`,id 212),语义与旧取元**逐字一致**
(Map 按键 / List 1-based / 缺键 `missing map key`)。它进 `HostFn` 是有意的:
**两个后端共用同一实现**,不再有特例分支。
### 3.2 安全模型:改写 → 重解析 → 证明等价 → 才写
1. 原文件按 classic 解析,得到 AST-A
2. 文本改写后,按 occlusion 解析,得到 AST-B
3. **反归一化** B:把"标签与键同名 + payload 为 `access(x, k)`"的遮蔽还原成 `Index`
4. 比较 `Debug(A)` 与 `Debug(反归一化(B))`(抹掉行号,因为插入了 marker 行)
5. 只有相等才写入;否则**原文件一字不动**并报告 `equivalence check failed`
这条校验是真干活的:它先后抓出 4 类改写 bug(表格散文链接、payload 继承文本模式、
链式索引、`[问候] (…)` 与遮蔽混淆),每一类都是**先被拦下、再修工具**,没有污染文件。
### 3.3 只改代码行
用词法层的 `LineKind::Code` 限定范围;表格行只改 `**…**` 单元格
(散文里的 markdown 链接 `[docs](https://…)` 必须原样保留)。
### 3.4 由内向外
链式索引 `[content]([1]([messages](req)))` 必须**最内层先改**,
否则外层改写会让内层的位置失效;已迁移的 `[k](access(…))` 有守卫,不会二次改写。
## 4. 全仓迁移结果
```
migrate labels: 256 index, 23 loop, 80 file written
```
- 覆盖 `lib/ ext/ examples/ public/ cli/ tests/`
- **0 文件被等价性检查拒绝**
- 迁移后 `cargo test --release` → **604 passed / 0 failed**
- 再跑一次迁移 → **幂等**(只剩刻意保留的 classic 测试样例)
## 5. 顺带修的两处真实语义缺陷
| 缺陷 | 现象 | 修法 |
|------|------|------|
| payload 继承外层"文本模式" | `f text=[k](access(c,k))` 里 `access(...)` 不被当调用 → 退化成插值文本 | `()` 内**永远**允许 `callee(args)`(`parse_occluded` 临时置位) |
| 遮蔽形状判定过宽 | `[问候] ([格式化] "Bo")` 被误判为遮蔽 | 要求 `]` 后**紧跟** `(`;否则落回方括号调用 |
## 6. 版本门
- 旧写法**不再**被硬报错——因为无法与遮蔽区分;真正的门是 **per-file 声明**:
没写 `markup: occlusion` 的文件按 classic 解析,行为不变。
- 需要"禁止新写旧形"的仓库可用 `migrate labels` 干跑做 CI 门禁(有改动即失败)。
## 7. 测试
| 层 | 内容 | 结果 |
|----|------|------|
| 单元(6) | 静态键 / 动态键 / 嵌套三层 / 已迁移不重写 / 循环 / 非循环 | ✅ |
| 集成(3) | 干跑不写盘;写入后**运行输出不变**且幂等;等价失败则文件不动 | ✅ |
| 全量 | `cargo test --release` | **604 passed / 0 failed**(M3 后 595 + 9) |
| 双后端 | gold 套件含 bytecode 变体 | ✅ |
## 8. 变更清单
| 文件 | 变更 |
|------|------|
| `src/migrate.rs` | **新增**:改写器、等价性证明、`migrate_file` / `migrate_path` |
| `src/load.rs` | `frontmatter_markup` + `with_markup` 包裹两处 `parse_source` |
| `src/parse/expr.rs` | `with_markup` 线程局部覆盖;`()` 内强制允许调用;`occlusion_shape_ahead` 严格判定 |
| `src/host/dispatch.rs` | `HostFn::Access`(enum / from_u16 212 / from_name / name / required_params / call_host) |
| `src/main.rs` | `migrate labels` 子命令 |
| `src/interp.rs` | 移除 access 特例(改用 HostFn,单一实现) |
| 80 个语料文件 | 索引与循环迁移 + `markup: occlusion` 标记 |
| `tests/migrate.rs` + `src/migrate.rs` 单测 | 9 个测试 |
| `doc/design/change-m7-migration.md` | 本文件 |
+81
View File
@@ -0,0 +1,81 @@
# 变更记录:M8 债务棘轮与呈现
| | |
|---|---|
| 状态 | **Implemented** |
| 日期 | 2026-10-22 |
| 里程碑 | M8([warning-fatigue-control.md](warning-fatigue-control.md) §4 棘轮 · [occlusion-syntax.md](occlusion-syntax.md) §13) |
| 改动文件 | `src/main.rs` · `tests/ratchet.rs` |
| 影响面 | `labels` 新增 `--baseline` / `--fail-on-increase` |
---
## 1. 棘轮规则
```bash
# CI:未完成项只许减少,不许增加
marqdo labels . --baseline .marqdo/pending.json --fail-on-increase
```
| 情形 | 行为 | 退出码 |
|------|------|--------|
| 台账不存在 | **建立**(写入当前计数),提示 `已建立 N` | 0 |
| 当前 > 台账 | 失败,提示 `未完成项增加了 K` | **1** |
| 当前 ≤ 台账 | 通过;若减少则**收紧**台账(`N → M`) | 0 |
**为什么"减少即收紧"**:否则债务可以先降后升,棘轮形同虚设。
收紧后台账记住新的低水位,回退到旧数量同样会失败(测试第 4 步验证)。
台账格式:
```json
{"count": 1, "words": ["待开发", "未开发", "…"]}
```
记录词集是为了让"口径变了"可被审计——换词集时会看到 `words` 变化。
---
## 2. 为什么用棘轮而不是硬门禁
| 方案 | 老债 | 新债 | 结论 |
|------|------|------|------|
| 硬门禁(必须为 0) | 阻塞一切 | 拦住 | 存量债立刻红一片,逼人关检查 |
| **棘轮(只拦增量)** | 不阻塞 | 拦住 | ✅ 债务可见且不恶化 |
| 无门禁 | 不阻塞 | 不拦 | 债务无声增长 |
这与 [warning-fatigue-control.md](warning-fatigue-control.md) 的结论一致:
**老账不追、新账必拦**。
---
## 3. 呈现(已具备)
| 面 | 表现 |
|----|------|
| `expr_display` / `view` | 遮蔽渲染为 `[描述](实现)`,桩渲染为 `[描述]()`,实测 `view output` 页面含 `access(` |
| `labels` | 人类行 `文件:行 [函数] 描述 ← 命中词`;`--json` 一个数组 |
| `check` | `label.*` 三类诊断(missing / empty_payload / ref_dangling) |
| MLSP | `labels.search` · `session.summary` |
**没有做桩徽章**:桩已经是 `[描述]()` 这个显眼形状,再加装饰是噪音;
需要计数时用 `labels --count`。
---
## 4. 测试
| 层 | 内容 | 结果 |
|----|------|------|
| 集成(1 个四步用例) | 建账 → 增加失败 → 减少收紧 → 回退再次失败 | ✅ |
| 全量 | `cargo test --release` | **605 passed / 0 failed**(M7 后 604 + 1) |
---
## 5. 变更清单
| 文件 | 变更 |
|------|------|
| `src/main.rs` | `labels --baseline` / `--fail-on-increase`;建账/收紧/违约逻辑 |
| `tests/ratchet.rs` | 四步棘轮用例 |
| `doc/design/change-m8-ratchet.md` | 本文件 |
+89
View File
@@ -0,0 +1,89 @@
# 变更记录:M8 view 遮蔽呈现(+ 修一个真实回归)
| | |
|---|---|
| 状态 | **Implemented** |
| 日期 | 2026-10-22 |
| 来源 | [occlusion-syntax.md](occlusion-syntax.md) §13 M8「view 徽章/呈现」 |
| 改动 | `src/load.rs` · `src/view/{document,render,html,mod,debug_page}.rs` |
| 影响 | 只影响呈现;顺带修了 **view 无法解析遮蔽文件** 的回归 |
---
## 1. 先修回归:view 用错解析模式
`view` 内部多处直接用 `crate::parse::parse_source(source)` 重新解析文件,
而 per-file `markup:` 是在 `load` 层生效的(M7)。结果:
```
<div class="structure"><div class="err">parse/load error: expected ')' after link-index collection</div></div>
```
任何带 `markup: occlusion` 的文档在 view 里**结构区直接报错**,只能退化成源码视图。
用户看到的"粗体里的 `[描述](实现)` 没渲染"其实是这个错误的表象。
**修法**:`load::parse_source_auto(source)` —— 先读 frontmatter 的 `markup:`,
用 `with_markup` 包住 `parse_source`,view 的五处解析点全部改用它。
## 2. 遮蔽呈现
### 2.1 浏览视图(`document.rs`,`/file`)
```html
<div class="doc-line doc-occl" data-line="81">
<span class="occl-pre">留存 =</span> <!-- 变量名:灰、等宽 -->
<span class="occl-label">客户留存率,模拟数据</span> <!-- 描述:正文 -->
<code class="occl-code">0.42</code> <!-- 实现:代码片 -->
</div>
```
- 空载荷 → `<span class="occl-stub">桩</span>`(琥珀色徽章,title 说明"未接通或待补返回值")
- 前缀里的反引号/`**` 都剥掉(与其它行 `mq-anchor` 的处理一致)
- 只在词法上切分,不改语义:解析器早已验证结构,这里只决定怎么画
### 2.2 卡片视图(`render.rs`,`/debug`)
按 AST 直接匹配 `Expr::Occluded`(`Assign` / `Expr` / `Return` 三种语句),
渲染成 `card occl-card`:徽章「遮蔽」+ 变量名 + 描述 + 代码片/桩徽章。
### 2.3 样式(`html.rs`)
```css
.doc-occl { display:flex; align-items:baseline; flex-wrap:wrap; gap:.4rem; }
.occl-pre { font-family:var(--mono); font-size:.86em; color:var(--muted); }
.occl-label { color:var(--ink); }
.occl-code { font-family:var(--mono); background:var(--fill); border:1px solid var(--line);
border-radius:6px; padding:.02rem .38rem; }
.occl-stub { background:rgba(255,159,10,.18); color:#9a5b00; border-radius:999px; }
```
刻意**不加**虚线下划线:容易被读成链接/缩写。描述就是正文,靠代码片的边框与之区分。
## 3. 验证
| 项 | 结果 |
|----|------|
| 结构区解析错误 | **消失**(`/file` 页面 0 处 `parse/load error`) |
| 七个遮蔽行 | 全部渲染为 `doc-occl`:6 个代码片 + 1 个桩徽章 |
| 文本抽取 | `留存 = 客户留存率,模拟数据 [0.42]` / `待接 = 搜索接入,接口未接,待开发 [桩]` |
| 单元(4) | 裸赋值 / 粗体赋值 / 空载荷+嵌套 payload / 非遮蔽行不误判 |
| 全量 | `cargo test --release` **613 passed / 0 failed**(609 + 4) |
## 4. 未能做到的:截图
本机没有任何浏览器(`chromium`/`chrome`/`firefox` 均不存在),
`npm i puppeteer` 装上了包但 Chromium 下载被网络阻断(`storage.googleapis.com`
TLS 断连,两次重试均失败)。所以无法自动截图比对,改为:
DOM 结构断言 + 提供 `/.preview/occlusion.html` 方案对照页由作者目视确认。
## 5. 变更清单
| 文件 | 变更 |
|------|------|
| `src/load.rs` | 新增 `parse_source_auto`(按 frontmatter `markup:` 解析) |
| `src/view/mod.rs` | 3 处解析改 `parse_source_auto` |
| `src/view/debug_page.rs` | 1 处同上 |
| `src/view/document.rs` | `split_occlusion` / `match_delim` / `render_occlusion_line` + 4 个单测 |
| `src/view/render.rs` | `occl_card` + 三个 `Expr::Occluded` 语句分支 |
| `src/view/html.rs` | `.doc-occl` / `.occl-*` 样式 |
| `doc/design/change-m8-view-occlusion.md` | 本文件 |
+113
View File
@@ -0,0 +1,113 @@
# 变更记录:M9 两级词表检索(`labels` CLI + MLSP `labels.search`)
| | |
|---|---|
| 状态 | **Implemented** |
| 日期 | 2026-10-22 |
| 里程碑 | M9([occlusion-description-and-search.md](occlusion-description-and-search.md) §3 · [occlusion-syntax.md](occlusion-syntax.md) §13) |
| 改动文件 | `src/label.rs` · `src/main.rs` · `src/mlsp.rs` · `tests/occlusion.rs` |
| 影响面 | 新增 CLI 子命令与 MLSP 方法(**不改语法**) |
---
## 1. 两级词表
| 级 | 在哪 | 作用 |
|----|------|------|
| **第一级:内置** | `label::BUILTIN_GROUPS`(数据常量) | 默认查询 + LLM 范例 + 跨项目可比 |
| **第二级:参数** | `--grep` / `grep` | 替换或并集,项目自己的说法照样能搜 |
内置六组:`未完成`(待开发/未开发/开发中/未实现/待实现/未接/接口未接/TODO)、
`假数据`(模拟/假数据/桩/占位/stub/mock)、`示例`、`实验`、`废弃`、`待校验`。
`pending` = `未完成 ∪ 假数据`。
**词表是数据不是语法**:扩充它不改任何解析规则。
---
## 2. CLI
```bash
marqdo labels . # 默认:pending 口径(内置两组)
marqdo labels . --grep "联调" # 替换为自定义词
marqdo labels . --grep "联调" --also-builtin # 自定义 ∪ 内置
marqdo labels . --group 示例,实验 # 选内置组
marqdo labels . --count # 只给数字(CI/棘轮用)
marqdo labels . --json # 一个 JSON 数组
```
输出(人类):
```
a.mq.md:3 [main] 按关键词检索,接口未接,待开发 ← 待开发,未接,接口未接
a.mq.md:4 [main] 客户留存率,模拟 ← 模拟
label search: 2 命中(1 文件,词=[…])
```
`--json`:
```json
[{"file":"a.mq.md","line":3,"unit":"main","label":"…","words":["待开发"],"has_payload":true}]
```
---
## 3. MLSP
```json
{"id":1,"method":"labels.search",
"params":{"source":"…"|"path":"…","grep":["联调"],"also_builtin":true}}
```
返回:
```json
{"ok":true,"words":[…],"count":2,"hits":[{"line":3,"unit":"main","label":"…",
"words":["待开发"],"has_payload":true}]}
```
语义与 CLI 完全一致(同一份 `label::search`)。
---
## 4. 检索语义(v1)
| 项 | 规则 |
|----|------|
| 匹配 | **子串**(CJK 无词边界,子串最稳) |
| 多词 | OR |
| 大小写 | 英文不敏感(`TODO`/`todo` 等价) |
| 误判 | 必然存在(`[不属于待开发范围]` 会命中)——只影响计数,输出带描述原文可人工判断 |
不做否定语法;留作 v1.1 可选项。
---
## 5. 测试
| 层 | 内容 | 结果 |
|----|------|------|
| 集成(4) | pending 计数=2;`--grep` 替换=1;`--also-builtin` 并集=3;MLSP `labels.search` 返回 hits | ✅ |
| 全量 | `cargo test --release` | **587 passed / 0 failed**(M4 后 583 + 4) |
---
## 6. 边界
| 项 | 说明 |
|----|------|
| 只在 occlusion 模式产生命中 | classic 模式下没有 `Expr::Occluded`;M7 翻转默认后自然可用 |
| 解析失败的文件跳过 | 那是 `check` 的职责,检索不应因一个坏文件整体失败 |
| 不做棘轮 | `--baseline` / `--fail-on-increase` 留给 M8(门禁) |
---
## 7. 变更清单
| 文件 | 变更 |
|------|------|
| `src/label.rs` | `WordGroup` / `BUILTIN_GROUPS` / `PENDING_GROUPS` / `group_words` / `parse_words` / `matched_words` / `Hit` / `search` |
| `src/main.rs` | `labels` 子命令 + `collect_mq_files` 递归扫描 |
| `src/mlsp.rs` | `labels.search` 方法 + 分发 |
| `tests/occlusion.rs` + `tests/occlusion/labels.mq.md` | 4 个集成测试 |
| `doc/design/change-m9-label-search.md` | 本文件 |
+103
View File
@@ -0,0 +1,103 @@
# 变更记录:插件 ABI 共享 crate(`marqdo-plugin-sdk`)
| | |
|---|---|
| 状态 | **Implemented** |
| 日期 | 2026-10-22 |
| 来源 | [code-volume-audit.md](code-volume-audit.md) §4 第 1 项 |
| 改动 | **新增 `crates/marqdo-plugin-sdk`** · 5 个插件改为依赖它 |
| ABI | **不变**(`include/marqdo_abi.h`、`src/host/plugin.rs` 看到的符号与布局完全一致) |
---
## 1. 问题
5 个原生插件各自复制同一套 ABI 前言(约 140 行/个):
| 复制的内容 | 说明 |
|-----------|------|
| `type PluginFn` / `HostQueryFn` / `struct MarqdoHostApi` | 布局必须逐字一致,抄错就是 UB |
| `static mut HOST_ALLOC/FREE/QUERY/USERDATA` | 同上 |
| `host_strdup` / `set_out` / `set_err` / `parse_args` / `reply` | 语义必须一致 |
| `register` + `#[no_mangle]` 四导出 | 样板 |
一共 5 份,任何一份漂移都会在运行期表现为"某插件偶发崩"。
## 2. 方案
新增工作区成员 `crates/marqdo-plugin-sdk`,持有唯一一份实现,并提供一个宏生成各 `.so` 必需的导出:
```rust
marqdo_plugin!(marqdo_plugin_sdk::ABI_VERSION, [
("llm_ping", "", llm_ping),
("llm_chat_completions", "base_url,api_key,...", llm_chat_completions),
]);
```
宏展开为 `marqdo_plugin_abi_version` / `marqdo_plugin_shutdown` / `marqdo_plugin_init`,
其中 init 调 `init_plugin(host, &[…])`(保存回调 + 逐个注册)。
`demo` 是 ABI **v1**,宏接受版本参数:`marqdo_plugin!(1, [...])`,语义不变。
## 3. 安全措施:注册项逐一核对
迁移时把每个插件的 `register(...)` 调用抽取成表。**第一次抽取漏了 11 项**——
正则是 `[a-z_0-9]+`,匹配不到 `mcp_server::agent_mcp_serve`、`sandbox::*` 这类
**路径限定**的函数名。编译能过(表少几行),运行时才会 `unknown function`。
补救:正则允许 `::`,并把新旧两张表逐项比对:
| 插件 | HEAD 注册项 | 迁移后 | 差异 |
|------|------------|--------|------|
| agent | 63 | 63 | **0** |
| quantum | 41 | 41 | 0 |
| linalg | 31 | 31 | 0 |
| llm | 2 | 2 | 0 |
| demo | 2 | 2 | 0 |
比对脚本同时校验 `(名称, 参数串, 函数)` 三元组完全一致,不只比数量。
另外两次由"编译通过但语义已变"暴露的问题:
| 问题 | 现象 | 处理 |
|------|------|------|
| `mcp_client` 被误判为死模块 | 我删掉 327 行后发现 `agent_mcp_client` 正注册它 | 恢复模块(教训:先查注册表,再判死) |
| 量子插件两个"未使用"函数 | 删除时连带吃掉 `density_from_amps`/`flat_to_nested` | 恢复并加 `#[allow(dead_code)]` 注释 |
## 4. 收益
| 插件 | 迁移前 | 迁移后 | 变化 |
|------|--------|--------|------|
| agent | 1,237 | 929 | −308 |
| quantum | 1,045 | 835 | −210 |
| linalg | 688 | 524 | −164 |
| llm | 405 | 278 | −127 |
| demo | 170 | 73 | −97 |
| 新增 SDK | — | 232 | +232 |
净减 **≈ 906 − 232 = 674 行**,且 ABI 前言从 5 份变 1 份。
## 5. 验证
| 项 | 结果 |
|----|------|
| `cargo build --release`(含 5 个插件) | 零警告 |
| `cargo test --release` | **609 passed / 0 failed** |
| 金样实跑(量子) | `p00-ok` / `p11-ok` / `ping-ok` |
| 注册项三元组比对 | 5 个插件全部 0 差异 |
## 6. 边界
- ABI 版本号、`#[no_mangle]` 符号、结构体布局**一律未变**;旧 `.so` 与新宿主仍可互操作。
- 插件私有逻辑(HTTP、矩阵、量子态、agent 工具)一行未动。
- 后续新增插件只需依赖 SDK + 一行宏调用。
## 7. 变更清单
| 文件 | 变更 |
|------|------|
| `crates/marqdo-plugin-sdk/{Cargo.toml,src/lib.rs}` | **新增**:ABI 类型、静态回调、`host_strdup/set_out/set_err/parse_args/reply/host_query_json(_with)/take_host_string/init_plugin`、`marqdo_plugin!` 宏 |
| `Cargo.toml` | workspace 增加 `crates/marqdo-plugin-sdk` |
| `plugins/{agent,quantum,linalg,llm,demo}/Cargo.toml` | 增加 SDK 依赖 |
| `plugins/*/src/lib.rs` | 删除本地 ABI 前言与四导出,改用宏;注册表改为数组 |
| `doc/design/change-plugin-sdk.md` | 本文件 |
Regular → Executable
View File
File mode changed.
+103
View File
@@ -0,0 +1,103 @@
# 代码体量审计:53k 行里哪些是特性、哪些是冗余
| | |
|---|---|
| 状态 | **实施记录**(精简依据与进度) |
| 日期 | 2026-10-22 |
| 结论 | 冗余已清 ~14.5k 行;**剩余体量主要是特性面**,不是废弃物 |
---
## 1. 当前账目
| 部分 | 行数 | 说明 |
|------|------|------|
| `src/` | **52,668** | 其中约 **5,200** 是内联测试(`#[cfg(test)]`) |
| `plugins/` + `crates/` | **14,700** | 5 个 ABI 插件(含共享 SDK)+ wasm crate |
| 合计 Rust | **67,368** | |
最大的 10 个文件:
| 行数 | 文件 | 性质 |
|------|------|------|
| 4,451 | `src/view/html.rs` | 3,861 行是 CSS/HTML 字符串(页面皮肤) |
| 2,691 | `src/parse/mod.rs` | 解析器主体 + 412 行内联测试 |
| 2,194 | `src/parse/expr.rs` | 表达式解析 + 465 行内联测试 |
| 2,063 | `src/host/foreign_doc.rs` | 外部语言内核(python/node 文档执行) |
| 1,648 | `src/host/dispatch.rs` | 202 个宿主函数的元数据表(已合一) |
| 1,968 | `src/host/foreign.rs` | 外部进程/会话管理 |
| 1,925 | `src/interp.rs` | 树遍历求值器 |
| 1,913 | `src/view/render.rs` | 渲染 |
| 1,309 | `src/formula/mod.rs` | `$$…$$` 公式求值 |
| 1,168 | `src/view/annot.rs` | 注解/映射 |
---
## 2. 已清除的冗余(14.5k 行)
| # | 项 | 行数 | 提交 |
|---|----|------|------|
| 1 | `plugins/web-rust-archive/`(31 文件,非 workspace 成员、默认不构建、被 Go `libweb` 取代) | **14,235** | `13012ca` |
| 2 | `as_text` × 18 份复制(两种措辞)→ 一个 `host::as_text` | ~100 | `8b0ea9e` |
| 3 | `catalog.rs` 的 4 个助手(与 `knowledge::util` 逐字相同) | ~70 | `8b0ea9e` |
| 4 | `view` 路由 34 臂 → 2 张表(`handle` / `handle_debug`) | 99 | `8b0ea9e` |
| 5 | 无调用点死代码 ×5(`parse_italic_assign` 等) | ~50 | `a14a6e2` |
| 6 | 转义重复:URL 编码器 2 份、`escape_js_string` 2 份(debug 副本漏 U+2028/2029) | ~40 | `9324032` |
| 7 | AST 遍历器 3 份 → `ast::walk_stmts` / `ast::stmt_line` | ~50 | `deac53d` |
**顺带修出的真实缺陷**(不是行数问题,是正确性问题):
| 缺陷 | 发现方式 |
|------|---------|
| `Access` 变体只有隐式判别值(重排即错位) | 新加的一致性测试 |
| HOST id 空间稀疏——不是 bug,但此前无测试守护 | 同上(测试先报"不连续",核实后改成"稀疏但可还原") |
| `escape_js_string` 的 debug 副本漏转义 U+2028/2029(JS 里是换行符) | 对比两份实现 |
| `view` 路由分布在两个 handler,只改一个会让 debug 路由全 405 | 改完实测 HTTP |
---
## 3. 剩余体量为什么不是"冗余"
逐项核过,剩下的都是**功能**,删掉就是砍特性:
| 区域 | 行数 | 为什么保留 |
|------|------|-----------|
| `view/` 合计 | ~12,000 | live server + notebook UI:路由、渲染、注解、调试面板、执行报告;审计确认是 feature-gated 的一等 CLI 面 |
| `host/foreign*` | ~5,100 | 外部语言内核(python/node 持久会话、快照、中断);qdagent 的沙箱执行依赖 |
| `parse/` | ~4,900 | 词法/语法主体 + 内联测试 |
| `bytecode/` | 1,921 | 第二后端;72 处测试引用(含双后端一致性) |
| `knowledge/` | ~4,000 | catalog / EKC / 指纹;`marqdo catalog` 的输出有 golden 测试 |
| `formula/` | 1,741 | `$$…$$` 公式;与 `ast::Expr` 是**不同类型**的两套求值器(不可合并) |
| `host/dispatch.rs` | 2,052 | 202 个宿主函数的元数据 + 分派;`call_host` 是 202 个一行臂 |
| `view/html.rs` | 4,451 | 其中 3,861 是页面皮肤字符串 |
---
## 4. 剩余可精简项(已定位,未做)
| 项 | 结论 |
|----|------|
| ~~插件 ABI 前言共享 crate~~ | **已完成**:[change-plugin-sdk.md](change-plugin-sdk.md),净减 674 行,注册项 0 差异 |
| ~~HostFn 五表合一~~ | **已完成**:[change-hostfn-table.md](change-hostfn-table.md),−404 行,203 项逐字节一致 |
| `view/html.rs` 皮肤"重复声明基础 CSS" | **审计判断不成立**:实测基础样式 312 条规则、notebook 128 条,**选择器零重叠**,无重复可删 |
| `debug_page.rs` "复刻 shell" | **判断基本不成立**:只在 head/favicon 上有约 10 行相似;它没有 nav/topbar,是独立极简页 |
| 内联测试迁到 `tests/` | 不减总量,只让 `src` 变薄;不做 |
**结论(修正后)**:可机械消除的重复**已经清完**。剩余体量全是特性实现,
要再压只能砍功能(例如 `view` 调试面板、`formula` 引擎),不是"找重复"。
**判断**:这些加起来约 1.3k 行(总量的 2%),收益边际递减;其中插件 SDK 最值得做(消除 5 份漂移),
其余属于"可以但不必"。
---
## 5. 与设计的关系
精简的目的不是数字好看,而是**不让冗余掩盖设计**:
- 已消除的都是**重复实现**(同一逻辑多份 → 必然漂移)
- 保留的都是**单一实现的特性能耐**
- 每一条删改都跑全量测试:`605 → 609 passed / 0 failed`,编译零警告
如果后续还要压体量,正确的方向是**砍特性**(例如 `view` 的调试面板、`formula` 引擎),
而不是继续在特性内部找"重复"——那已经找完了。
Regular → Executable
View File
File mode changed.
View File
File mode changed.
Loaded 100 of 1965 files, more files were not shown because too many files have changed in this diff. Show more