Compare commits

..
190 Commits
Author SHA1 Message Date
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
981 changed files with 66889 additions and 19355 deletions

No files matched your search

+57 -5
View File
@@ -38,7 +38,7 @@ A `.mq.md` file must stay readable as Markdown. If a human cannot skim the data
Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = text, `` `var` `` = variable, quote paths/`/` ratios.
### 2. Good patterns
### 2. Good patterns (copy these — not `json.set`)
**Wire / steps / commands** — `@` record table:
@@ -60,7 +60,53 @@ Cells are expressions (`doc/design/table-cell-expressions.md`): bare words = tex
| `wire` | `set_text` |
```
**Single dynamic key** — one `table.put` (or a helper), not a json chain:
**Agent / LLM result map** — one readable row, not a `json.parse` + `json.set` chain:
```markdown
`out` =
| status | task | result | llm_calls | tokens |
|--------|------|--------|-----------|--------|
| ok | `task` | `reply` | `llm_calls` | `tokens` |
*out*
```
**Soft error pack** (transport / gate failure) — still a table humans can skim:
```markdown
`pack` =
| finish | text | error | usage | tool_calls |
|--------|------|-------|-------|------------|
| error | "" | `msg` | `usage0` | `empty_tc` |
*pack*
```
**Optional / conditional key** — sparse `table.put` after the static table (one dynamic key only):
```markdown
`out` =
| status | task |
|--------|------|
| error | `task` |
1. `err`
**out = > table.put in=`out` at="error" value=`err`**
2. *
**_ = 1**
```
**Empty list / empty map** — prefer stdlib seeds over `json.parse text=[]` / `{}`:
```markdown
**empty_tc = > table.empty_list**
**empty_map = > table.empty_map**
```
**Single dynamic key from scratch** — one `table.put` (or a helper), not a json chain:
```markdown
**`set_text` = table.put in=None at="#log" value=msg**
@@ -73,14 +119,20 @@ Better still — call a named helper:
**browser.set_text sel="#log" text=msg**
```
### 3. Bad pattern (do not write)
**When `json.*` is OK:** `json.parse` / `json.stringify` / `json.quote` on **wire text**; `json.get` to read an opaque map. Never use `json.set` / `json.append` to *build* author-facing structures.
### 3. Bad pattern (do not write — and do not copy from old `ext/ai`)
```markdown
**`ret` = json.set map=None key="set_text" value=…**
**`ret` = json.set map=ret key="canvas" value=…**
**`cmds` = json.append list=cmds item=c0**
**`out` = json.parse text={"status":"ok"}**
**`out` = json.set map=out key="task" value=task**
```
Matching surrounding **legacy** `json.set` in `ext/ai/*.mq.md` is **not** compliance. Refactor the call site to tables / `table.put` instead of extending the glue.
## Writing application `.mq.md`
1. Frontmatter: title + imports (`table`, domain libs). **Do not import `json` unless parsing strings.**
@@ -92,7 +144,7 @@ Better still — call a named helper:
7. **Do not use `##` inside `# main` for document sectioning** — those become nested functions. Use paragraphs / `---` breaks instead.
8. **Index:** prefer `[键](集合)` / `` [`名`](集合) `` over footnote `` m[^k] ``.
Browser client programs: prefer `import browser:lib/browser.mq.md` (no native plugin). Server sites: 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`.
Browser client programs: prefer nested `import:` with `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/*`)
@@ -134,7 +186,7 @@ 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.
4. Drop unused `json:` (or other) entries under nested `import:`.
## Anti-patterns
+12 -6
View File
@@ -28,6 +28,7 @@ Canonical release playbook for **cflmy/marqdo**. Read this skill **before** tagg
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.
12. **GitHub auto-build must be green before declaring a release done.** For full/cli: wait for the tag-triggered **Release** workflow (`windows` + `linux`) **and** the push-triggered **`executable-knowledge`** workflow on the release commit / `main` tip. Release asset zips alone are **not** sufficient — a green Release job with a red EK gate is an incomplete release. Do not skip or reframe a red `executable-knowledge` as “assets already uploaded.”
## Release modes
@@ -78,6 +79,7 @@ Release progress:
```
Checks: clean tree; `main` ff-only; smoke tests; CHANGELOG Unreleased; no secrets.
Also confirm the latest `main` **`executable-knowledge`** Actions run is green (or that this release commit will be covered after push) — do not proceed to tag if EK is already red on tip without a fix in the same release PR.
## Phase 2 — Docs & version bumps (main)
@@ -129,7 +131,9 @@ 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.
1. Wait for Actions (full/cli):
- Tag **Release** workflow: both `windows` and `linux` green when ext natives required.
- Push **`executable-knowledge`** workflow on the release commit / `main`: **must be success**. Poll with `gh run list --workflow=executable-knowledge.yml --branch main` / `gh run watch`. If EK is red → **stop**; fix plugin/harness on `main`, re-run; do **not** declare the release complete from assets alone.
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.
@@ -174,10 +178,11 @@ On Launchpad failure: read the build log, fix `debian/` or bundle script, bump `
## 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.
2. Confirm **`executable-knowledge`** and **Release** Actions are both green for this tag/commit; if either is red, say so and do not claim “发版完成”.
3. CDN `https://ext.marqdo.com/vVER/` (if ext shipped).
4. PPA build green (if cli shipped).
5. Tell user URLs: GitHub release, CDN, PPA install one-liner.
6. Optional gh-pages only if asked.
## Extension-only release (mode=ext)
@@ -194,7 +199,8 @@ On Launchpad failure: read the build log, fix `debian/` or bundle script, bump `
| `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 |
| CI red (Release assets) | Fix on main; retag only if user allows |
| `executable-knowledge` red | Fix agent plugin / test harness (e.g. `ensure_agent_plugin_built`); push `main`; wait for EK green. **Do not** treat uploaded Release zips as a successful release |
| 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` |
@@ -304,6 +304,15 @@ gh workflow run Release --ref "vVER" # only if workflow_dispatch exists; else f
Current Release workflow is **tag-push only**. Red CI after tag → fix on `main`, then either new patch tag or **user-approved** delete+recreate tag (dangerous; prefer patch).
**Also required before declaring release done:** the push-triggered **`executable-knowledge`** workflow on the release commit / `main` tip must be **success**. Poll with:
```bash
gh run list --workflow=executable-knowledge.yml --branch main --limit 5
gh run watch <run-id>
```
A green Release asset job with a red `executable-knowledge` gate is an **incomplete** release — fix the plugin/harness (e.g. `ensure_agent_plugin_built` for agent-dependent EK tests), push `main`, and wait for EK green. Do not skip.
### 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`.
+74 -52
View File
@@ -14,55 +14,66 @@ description: >-
Marqdo = **Markdown markers as syntax**. A `.mq.md` file is both documentation and a runnable program. Read this skill **before** inventing syntax from Markdown habits or Python.
Canonical design (repo): `doc/design/markdown-mapping.md`, `doc/design/keywords.md`. Deeper tables: [reference.md](reference.md). Copy-paste patterns: [examples.md](examples.md).
<!-- CORE_SYNTAX_V2.1: must stay at the top so skill_brief budgets never truncate it -->
**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/*`.
## CORE SYNTAX (v2.1 Occlusion — mandatory)
**Product release** (tag, CHANGELOG, README, public docs, VSIX, GitHub assets): use [marqdo-release](../marqdo-release/SKILL.md) — detect latest version, **ask the user for the next SemVer**, then follow that playbook. Do not invent a version number.
These rules are the **current default**. Do **not** teach Classic `[key](map)` index or “bold is return of print”. Classic migration only: [migration-classic.md](migration-classic.md).
1. **File suffix** `.mq.md`. Print with `> print text=…` / `> 打印 内容=…` — never use `**…**` to print.
2. **`**…**` = statement** (assign / call / expression). `*…*` = return. Closing markers touch the last token (no trailing space).
3. **`[描述](payload)` = occlusion:** `[]` is prose (never executed); `()` is the only executed part. Empty `()` → `None` stub.
4. **Read collections with `access(coll, key)`** (aliases `取` / `取值`). **Never** use `[key](map)` as index under default Occlusion.
5. **Foreach:** `- [描述](遍历 coll 为 item)` (`遍历`/`for`, `为`/`as`/`in`). Prefer explicit traversal when generating new code.
6. **Import / call:** frontmatter `import:` / `导入:`; call `lib.member`. One language (EN or ZH) per file.
7. **Control flow:** `#` object/type, `##`+ function, `+` params, `1.`/`2.` branches, `-` loops, `N. *` else. No invented `if`/`for`/`def`/`return` keywords.
8. **Prose vs code:** blank line separates comment paragraphs from executable lines.
9. **GFM tables** for data; prefer `table.put` over `json.set` chains. `ext/**` never calls `host_*`.
10. Body narrative `[描述](target)` is lazy (NarrativeRef) — reading does not execute side effects.
| Marker | Meaning (v2.1) |
|--------|----------------|
| `#` / `##`+ | Object/type · function/method |
| `**…**` | Statement (assign / call / expression) |
| `*…*` | Return |
| `[描述](payload)` | Occlusion step (payload executes) |
| `access(c, k)` | Collection read |
| `> fn …` | Call |
| GFM table | Collection literal |
Canonical: `doc/design/core-surface.md`, `doc/design/document-native-development-guide.md`. Deeper tables: [reference.md](reference.md). Patterns: [examples.md](examples.md). Authoring craft: [marqdo-dev](../marqdo-dev/SKILL.md). Release: [marqdo-release](../marqdo-release/SKILL.md).
Executable-knowledge gate: [`tests/executable_knowledge/`](../../tests/executable_knowledge/README.md).
## Hard rules (do not violate)
1. **File suffix** must be `.mq.md` (never plain `.md` for executable sources).
2. **Output is not `**bold**`.** Print with `> print text=…` (or `> 打印 内容=…`). Bold `**…**` is **return value only**.
3. **Prose vs code:** after a blank line, an unmarked first line starts a **comment paragraph**; every following non-blank line stays comment until the next blank line. Put a **blank line** between narration and executable lines.
4. **Do not invent keywords** `if` / `else` / `while` / `for` / `def` / `return`. Control flow is Markdown: **`+` params** (under heading), **`1.` `2.` … branches**, **`-` loops**, arm `N. *` = else, `#` = **object/type**, `##`+ = **function/method**, `**…**` = return.
5. **Identifiers use backticks** — params `` + `name` ``. **Exemptions:** foreach `` - [item](coll) ``; footnote `` name[^key] ``; **inside italic `*…*` / bold `**…**`**, bare ids are **variables** (Python-style unified namespace) and method-call receivers are bare too. **Drop the backticks on value-expression variable names and method receivers inside `*…*` / `**…**`** — they are redundant once the `*…*`/`**…**` markers mark the segment as code: `*分类 = 分类[^苹果]*`, `**n * 2**`, `*p = > page.主体装配 组件=home*`. **Text literals must be quoted**: `*a = > text.split value=src sep=","*`. Backticks **still required** where a bare word is *not* a variable in **standalone `>` calls** (bare = text there): `` > str `n` ``, `` > `obj`.method ``. **No trailing space** inside `*…*` / `**…**` wrapped code: the closing marker must touch the last token directly (`*a = 1*`, `**n**`), never `` *a = 1 * ``.
6. **Structure lines are not wrapped in italics.** `#` `>` `+` `-` `|` lines stand alone; use `*…*` only for general statements (bindings / expressions).
7. **Paths:** In bare *expressions* `/` is division. In **call args / param defaults / table cells**, unspaced `a/b` and quoted `".marqdo/agent-kb"` are path text — no `json.parse` needed. Numeric ratios that must stay text use quotes (`"1/5"`, `"16/9"`); bare `1/5` is division.
8. Prefer ending side-effect-only function bodies with `*None*` / `*无*` / whole-line `**` / `****` when later lines must belong to an outer function. Lone `---` / `***` are Markdown thematic breaks (skipped), not function end.
9. **`ext/**` never calls `host_*`.** Agent/OKF helpers are plugin names (`agent_kb_*`, …) after `plugin.load`. Do **not** add agent/OKF domain code to `src/host/` (core bloat). See `doc/design/ext-agent.md` §4.
10. **Browser (route C/D/E/F):** client logic is Marqdo on WASM; official bridge is host glue and **may** implement lists, routing, storage, WebSocket, canvas, file read, observers — authors **must not hand-write business JS**. Use `web.client_embed` / `data-mq-source-url` auto-mount. Client effects: prefer **GFM tables + `lib/browser`** ([marqdo-dev](../marqdo-dev/SKILL.md)).
11. **Code-as-documentation / no bag glue:** Prefer **GFM tables** for maps, lists, wire, commands. Prefer **`table.put` / named helpers** over `json.set` / `json.append` chains. `lib/json` is for parse/stringify/quote only — not a dict builder. Unreadable json pipelines are a style bug. Read collections with **`[key](map)`**, not footnote indexes for new code.
12. **One language per file:** Do not mix EN and ZH API names in the same `.mq.md` (imports, calls, params). Pick English *or* Chinese mirrors for the whole program.
13. **Sandbox trial habit (Agent / generated `.mq.md`):** Prefer `agent.trial` / `run sandbox=True` / `sandbox.open`→`run`→`diff`→`commit` before promoting to the host tree. Host files must stay unchanged until a successful commit. Caps live in `sandbox.profile` GFM tables — do not invent a second dialect.
1. Obey **CORE SYNTAX** above — Occlusion is default; do not emit Classic index links.
2. **Identifiers:** params `` + `name` ``; inside `*…*` / `**…**` bare ids are variables. Quote text literals. Standalone `>` calls: backticks where bare would be text.
3. **Structure lines** (`#` `>` `+` `-` `|`) are not wrapped in italics.
4. **Paths:** bare `/` in expressions is division; in call args / table cells unspaced `a/b` is path text. Ratios as text need quotes (`"1/5"`).
5. End side-effect-only helpers with `*None*` / `*空*` / `**` / `****` when the outer function continues. Lone `---` is a thematic break, not function end.
6. **`ext/**` never calls `host_*`.** Prefer tables over `json.set` / `json.append`.
7. **One language per file.** Sandbox trial before promoting Agent-generated trees.
8. Browser: Marqdo on WASM + `lib/browser` tables; do not hand-write business JS.
## Markup → meaning (v0.2)
## Call one function
| Marker | Meaning |
|--------|---------|
| `#` | **Object / type** (constructor body). `# main` = entry object. `# Child = > Parent` = inherit (**no** implicit parent constructor; call `` `self` = > Parent … `` explicitly when needed). |
| `##` … `######` | **Function / method** (nesting by heading depth). |
| `` + `name` `` under heading | Parameter (optional `` `name`=default ``) |
| `1.` `2.` … in body | Branch arm (condition or `N. *` else). **Same-indent restart at `1.` = new branch statement** (not more arms of the previous list). |
| `- …` inside body | Loop (`while` or `` [item](coll) `` / `` [`item`](`coll`) ``) |
| Line `N. *` | Else arm |
| `> fn args` | Call (named `k=v` or positional) |
| `` > `obj`.method args `` | Method call (`obj` must be a map with `_type`) |
| Frontmatter `import bind:path.mq.md` / `导入` | Import file (bind library name) |
| Frontmatter `import bind:lib.member` / `导入` | Short name for a library member (same keyword; no separate `use`) |
| `> lib.member …` / `> lib.Type.member …` | Call via bare dotted path (instance methods need `` `var`.m ``) |
| `*…*` | Statement (bind / expr) — closing `*` touches last token, **no trailing space**; bare ids are variables |
| `**…**` | Return value — closing `**` touches last token, **no trailing space**; bare ids are variables |
| `****` or `**` + spaces + `**` | Return `None` and end function body |
| Lone `---` / `***` | 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 |
```markdown
# 计算器
Entry: load file (often `index.mq.md`) → collect defs → run `# main`.
## 加法
计算两个数字`a`和`b`的和。
*[计算结果](a + b)*
```
```
marqdo call calculator.mq.md 计算器.加法 a=2 b=3
```
prints `5`. The same command works on any `.mq.md`; the file does not need a special skill name.
## Minimal program
@@ -103,13 +114,13 @@ Chinese builtins (same functions, no import):
## Statements, returns, branches
```markdown
*x = 1*
*y = x + 2*
**x = 1**
**y = x + 2**
## add_one
+ `n`
**n + 1**
*n + 1*
```
```markdown
@@ -125,20 +136,21 @@ Chinese builtins (same functions, no import):
## 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:
Imports use nested YAML `import:` (`导入:` 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
import:
text: lib/text.mq.md
clock: lib/time.mq.md
---
# main
*xs = > text.split value="a,b,c" sep=","*
**xs = > text.split value="a,b,c" sep=","**
> print text=`xs`
*t = > clock.now_unix*
**t = > clock.now_unix**
```
- Import **English** or **Chinese** library file; call that file’s API names via `lib.member` (do not mix languages).
@@ -197,12 +209,22 @@ Install: `marqdo ext add quantum` (ZH id: `量子`). Build: `cargo build --relea
**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"*
**_ = > `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/).
## Foreign kernels (v1.5.0)
`lib/foreign` is now a full foreign-kernel surface, not only `run`:
- `invoke` returns a record (`ok`, `code`, `stdout`, `stderr`, `ms`, `timed_out`, `truncated`, `result`); pass `input` for JSON stdin and `output="json"` for a parsed result.
- `call` is JSON-in / JSON-out; `call_many` fans out one program over a list with ordered results.
- `session_open` returns an opaque `handle` (not text; not JSON-serializable). `session_eval` / `set` / `get` borrow the handle; `session_close` consumes it (double-close / use-after-close fault). Prefer `replay_check` against the oracle journal when comparing recordings (`replay_snapshot` only re-runs). JSON integers outside \(\pm(2^{53}-1)\) and ragged table columns are refused (`doc/design/v-safe-json.md`, `foreign-strong-correspondence.md`).
- A view document opts into kernel state with `会话 = > foreign.session kernels=... cells=...`; the table names are free. `view` consumes only the `会话` handle and never scans source lines or reserved table names. Without `会话`, cells are stateless one-shot runs; no kernel is created. Clearing outputs calls `/api/session/clear` and keeps persistent kernel state. There is no separate notebook CLI mode or command, and no new Markdown marker exists.
- The same source remains the authority; state crossing kernels is explicit, never implicitly mirrored.
## AI authoring workflow
1. Decide language surface (English builtins + `lib/text.mq.md`, or Chinese + `lib/文本.mq.md`).
@@ -219,8 +241,8 @@ Design: [ext-quantum.md](../../doc/design/ext-quantum.md) · Q7: [ext-quantum-q7
| `# 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 |
| `` *`a` = 1 * `` (trailing space + backticks) | `**a = 1**` — bare bind, no trailing space before `*` / `**` |
| `*xs = > text.split value=a,b sep=,*` (italic is return, and bare text args) | `**xs = > text.split value="a,b" sep=","**` — statement; quote text literals |
| 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 文本) |
+72 -12
View File
@@ -141,7 +141,8 @@ Row-oriented records (SQL-like): first header `@` / `行` / `row` → list of ma
```markdown
---
import browser:lib/browser.mq.md
import:
browser: lib/browser.mq.md
---
# main
@@ -162,12 +163,64 @@ import browser:lib/browser.mq.md
Do **not** build effect maps with `json.set` chains. See [marqdo-dev](../marqdo-dev/SKILL.md).
## 6e. Agent / LLM result maps — GFM first (positive)
Return and soft-error packs are **tables**, not `json.set` pipelines. Full style contract: [marqdo-dev](../marqdo-dev/SKILL.md) §2.
```markdown
---
import:
table: lib/table.mq.md
---
## step_ok
+ `task`
+ `reply`
`out` =
| status | task | result |
|--------|------|--------|
| ok | `task` | `reply` |
*out*
## step_err
+ `task`
+ `err`
`out` =
| status | task | error |
|--------|------|-------|
| error | `task` | `err` |
*out*
## soft_http_pack
+ `msg`
+ `usage0`
**empty_tc = > table.empty_list**
`pack` =
| finish | text | error | usage | tool_calls |
|--------|------|-------|-------|------------|
| error | "" | `msg` | `usage0` | `empty_tc` |
*pack*
```
Do **not** mirror legacy `ext/ai/agent.mq.md` `json.parse`+`json.set` chains when adding new arms — convert the shape to a table.
## 7. Import text stdlib
```markdown
---
title: split demo
import text:lib/text.mq.md
import:
text: lib/text.mq.md
---
# main
@@ -180,8 +233,9 @@ import text:lib/text.mq.md
```markdown
---
import re:lib/re.mq.md
import enc:lib/encoding.mq.md
import:
re: lib/re.mq.md
enc: lib/encoding.mq.md
---
# main
@@ -196,8 +250,9 @@ import enc:lib/encoding.mq.md
```markdown
---
import log:lib/log.mq.md
import uuid:lib/uuid.mq.md
import:
log: lib/log.mq.md
uuid: lib/uuid.mq.md
---
# main
@@ -228,7 +283,8 @@ After a blank line, code runs:
```markdown
---
description: loads math
import math:lib/math.mq.md
import:
math: lib/math.mq.md
---
# main
@@ -276,7 +332,8 @@ See `tests/structure/object-handle.mq.md` and `ext/ai/llm.mq.md`: `# Type` const
```markdown
---
import agent:ext/agent.mq.md
import:
agent: ext/agent.mq.md
---
# main
@@ -328,8 +385,9 @@ if x > 0:
```markdown
---
title: hello-site
import web:ext/web/web.mq.md
import db:db/index.mq.md
import:
web: ext/web/web.mq.md
db: db/index.mq.md
---
# main
@@ -366,7 +424,8 @@ import db:db/index.mq.md
```markdown
---
import quantum:ext/quantum/quantum.mq.md
import:
quantum: ext/quantum/quantum.mq.md
---
# main
@@ -395,7 +454,8 @@ import quantum:ext/quantum/quantum.mq.md
```markdown
---
import la:ext/linalg/linalg.mq.md
import:
la: ext/linalg/linalg.mq.md
---
# main
+4 -2
View File
@@ -122,7 +122,8 @@ Examples: `examples/linalg-svd/`, `examples/linalg-least-squares/`. Design: `doc
```markdown
---
import math:lib/math.mq.md
import:
math: lib/math.mq.md
---
# main
@@ -141,7 +142,8 @@ Empty RHS assignment + following `$$…$$` binds a formula value. Narrative-only
```markdown
---
import foreign:lib/foreign.mq.md
import:
foreign: lib/foreign.mq.md
---
# main
@@ -0,0 +1,34 @@
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: 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"
+30
View File
@@ -126,6 +126,36 @@ jobs:
## Marqdo ${{ github.ref_name }}
### 亮点 / Highlights
- **v2.3.0**:Foreign Strong——不透明 `handle`、仿射 close、`replay_check`/oracle journal、表 arity refuse、Ω∈V_safe
- **v2.3.0**: Foreign Strong — opaque handle, affine close, replay_check/oracle journal, table arity refuse, Ω∈V_safe
- **v2.3.0 ext**:扩展包同步 2.3.0 / Ext pack 2.3.0
- **v2.2.1**:view / 静态导出——修复 occlusion 与中等宽度下大纲侧栏掉到正文下方
- **v2.2.1**: view / static export — fix outline rail nested under document (occlusion + mid-width layout)
- **v2.2.1 ext**:扩展包同步 2.2.1 / Ext pack 2.2.1
- **v2.2.0**:函数级调用 `marqdo call`——同一份 .mq.md 就是文档、知识和工具;Tree/Bytecode 执行被点名的函数;外部调用默认只跑纯函数
- **v2.2.0**: `marqdo call` runs one function in any .mq.md — the file is the document, the knowledge and the tool; Tree and Bytecode execute that function; external calls stay pure
- **v2.2.0 ext**:扩展包同步 2.2.0 / Ext pack 2.2.0
- **v2.1.5**:Agent 可靠工作台——ResourceView / ToolSpec / CheckpointV2 / EffectLedger · EKC ir.json 暖机 · Web 短读槽隔离
- **v2.1.5**: Agent reliability workbench — ResourceView / ToolSpec / CheckpointV2 / EffectLedger, EKC ir.json warm-load, web short/read lane isolation
- **v2.1.5 ext**:扩展包同步 2.1.5 / Ext pack 2.1.5
- **v2.1.4**:默认隔离 HTTP execute(ADR 0009)——worker 池 / `--call-lib-path` · `/_runtime/*` · MR-01 双流金样例 · `runtime.isolated_execution=1`
- **v2.1.4**: Default isolated HTTP execute (ADR 0009) — worker pool / `--call-lib-path`, `/_runtime/*`, MR-01 dual-stream gold, `runtime.isolated_execution=1`
- **v2.1.3**:知识工作台运行时——ModelSelection/RunContext/usage · view document 只读嵌入 · LLM selection/messages/cancel · agent selection e2e
- **v2.1.3**: Workbench runtime — ModelSelection/RunContext/usage, view document read-only embed, LLM selection/messages/cancel, agent selection e2e
- **v2.1.1**:可执行知识主链——BoundCall · NarrativeRef · 来源/适用期 · patch/extract · 整代 CURRENT + closure · 发票示例 113
- **v2.1.1**: Executable-knowledge spine — BoundCall, NarrativeRef, sources, patch/extract, generation CURRENT + closure, invoice example 113
- **v1.5.2**:外联 v3 P0/P1——raw stdin + 每 cell 输入 · plan API · snapshot · `view capture` · Persist
- **v1.5.2**: Foreign v3 P0/P1 — raw stdin + per-cell inputs, plan API, snapshot export/import/replay, `view capture`, Persist
- **v1.5.2 ext**:扩展包同步 1.5.2 / Ext pack 1.5.2
- **v1.5.1**:view 静态/动态统一 + 外联值传递——共用执行路径 · 构建时运行注入 stdout · `foreign.session` 值传递 · cell stdin
- **v1.5.1**: View static/live unified + foreign value passing — shared execution path, build-time run with stdout injection, `foreign.session` value passing, cell stdin
- **v1.5.0**:外联 v2 + 文档原生 Notebook——invoke/JSON call/并行/持久 Python·Node/状态桥 · cell 单步 · 高对比 view
- **v1.5.0**: Foreign v2 + document-native notebooks — invoke, JSON calls, fan-out, persistent Python/Node, state bridge, cell stepping, high-contrast view
- **v1.5.0 ext**:扩展包同步 1.5.0 / Ext pack 1.5.0
- **v1.4.6**:裸自增升参——首次粗体赋值左值即声明;`n = n + 1` 无反引号也是必选形参
- **v1.4.6**: Bare self-increment is a required parameter — first bold assignment LHS is a declaration
- **v1.4.5**:Streamable HTTP MCP + web invoke Bearer/401 · openai/agent json.get 硬化
- **v1.4.5**: Streamable HTTP MCP + web invoke Bearer/401; openai/agent json.get hardening
- **v1.4.2**:Agent/LLM 优化 O1–O5——sandbox trial · promote proof · step_route/EFI/cost · lint · quarantine
- **v1.4.2**: Agent/LLM optimize O1–O5 — sandbox trial, promote proof, step_route/EFI/cost, lint, quarantine
- **v1.4.1**:view 标注连线——SVG mid→mid(underline 底中 → chip 顶中)· 帧 chip id 对齐 · L→R 密度
+11
View File
@@ -71,6 +71,16 @@ 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
# 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/
@@ -93,3 +103,4 @@ tests/ext/_sbx_cow/
tests/ext/_sbx_*/
examples/**/_example_sbx/
.secrets/
+526
View File
@@ -8,6 +8,532 @@
### Changed
## 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
### Fixed
### 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
Generated
+29 -16
View File
@@ -1,6 +1,6 @@
# This file is automatically @generated by Cargo.
# It is not intended for manual editing.
version = 4
version = 3
[[package]]
name = "adler2"
@@ -264,9 +264,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"
@@ -539,9 +539,9 @@ checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"
[[package]]
name = "js-sys"
version = "0.3.104"
version = "0.3.106"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0e0c1080212aad755ea003d18543e8768dd432c48819efd73a7bf1e39b7a5a3a"
checksum = "7883d941dae510fb2d978fc3fe018c71c9e2892fd38854de3e8b92c2e5ad9cc5"
dependencies = [
"cfg-if",
"futures-util",
@@ -572,7 +572,7 @@ checksum = "0ceec5bc11778974d1bcb055b18002eba7f4b3518b6a0081b3af5f21666da9ad"
[[package]]
name = "marqdo"
version = "1.4.1"
version = "2.3.0"
dependencies = [
"anyhow",
"assert_cmd",
@@ -589,6 +589,7 @@ dependencies = [
"predicates",
"pulldown-cmark",
"regex",
"serde",
"serde_json",
"sha1",
"sha2",
@@ -601,9 +602,16 @@ dependencies = [
"zip",
]
[[package]]
name = "marqdo-plugin-sdk"
version = "2.0.0"
dependencies = [
"serde_json",
]
[[package]]
name = "marqdo-wasm"
version = "1.4.1"
version = "2.3.0"
dependencies = [
"marqdo",
"serde_json",
@@ -614,6 +622,7 @@ name = "marqdo_plugin_agent"
version = "0.1.0"
dependencies = [
"chrono",
"marqdo-plugin-sdk",
"serde_json",
]
@@ -621,6 +630,7 @@ dependencies = [
name = "marqdo_plugin_demo"
version = "0.1.0"
dependencies = [
"marqdo-plugin-sdk",
"serde_json",
]
@@ -628,6 +638,7 @@ dependencies = [
name = "marqdo_plugin_linalg"
version = "0.1.0"
dependencies = [
"marqdo-plugin-sdk",
"serde",
"serde_json",
]
@@ -637,6 +648,7 @@ name = "marqdo_plugin_llm"
version = "0.1.0"
dependencies = [
"idna_adapter",
"marqdo-plugin-sdk",
"serde_json",
"ureq",
"zeroize",
@@ -646,6 +658,7 @@ dependencies = [
name = "marqdo_plugin_quantum"
version = "0.1.0"
dependencies = [
"marqdo-plugin-sdk",
"serde",
"serde_json",
]
@@ -1278,9 +1291,9 @@ checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
[[package]]
name = "wasm-bindgen"
version = "0.2.127"
version = "0.2.129"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "1b70935747edd64d89de3efa29d73789b806c15798f8e7dca4d8ac356b50ce70"
checksum = "9bb54f33acc68fd454578d9820b0bde1a1a3d17aa17bb7b6595806d02886d409"
dependencies = [
"cfg-if",
"once_cell",
@@ -1291,9 +1304,9 @@ dependencies = [
[[package]]
name = "wasm-bindgen-macro"
version = "0.2.127"
version = "0.2.129"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "77775f8f3f7217702089053b94958f8f54061a3f663417df76e19cbdcca29bc1"
checksum = "2e29d0c35b16e224a7eeb5cd2d25e3e1968fbd65604117b44d3b789d00ee8535"
dependencies = [
"quote",
"wasm-bindgen-macro-support",
@@ -1301,22 +1314,22 @@ dependencies = [
[[package]]
name = "wasm-bindgen-macro-support"
version = "0.2.127"
version = "0.2.129"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "e11d33f857dc2fb11b8bc75aee111aa9cbeb12cd9f25efd3d4c2a3dd4e235284"
checksum = "6f501a8bc3719dba86ef8ae4728879c08001bea749eb1333ac5b91e040e2a6b7"
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.129"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "7ef64dbcc55df09c7e5a46182d181c2cfa3e925f3da937ea764728b4bbb9dcbf"
checksum = "23f0c9c52aa7cd7d77769a4cfe2a9adb1b331f489a41d912ce14513d5ab995c6"
dependencies = [
"unicode-ident",
]
+6 -4
View File
@@ -1,6 +1,6 @@
[package]
name = "marqdo"
version = "1.4.2"
version = "2.3.0"
edition = "2021"
license = "Apache-2.0"
description = "Marqdo — Markdown markers as an interpreted programming language"
@@ -19,7 +19,7 @@ cli = ["dep:clap"]
view = ["dep:tiny_http"]
net-host = ["dep:ureq", "dep:idna_adapter", "dep:zeroize", "dep:zip"]
plugin-host = ["dep:libloading"]
exec-host = []
exec-host = ["dep:libc"]
fs-host = []
tty = ["dep:libc"]
wasm-core = []
@@ -29,6 +29,7 @@ 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 = { version = "1", features = ["derive"] }
serde_json = "1"
thiserror = "1"
tiny_http = { version = "0.12", optional = true }
@@ -62,9 +63,10 @@ members = [
"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]
+169 -15
View File
@@ -1,12 +1,14 @@
# Marqdo
# Marqdo
**代码即文档。文档即知识库。知识即可执行。**
Marqdo 把 Markdown **标记当作编程语法**:同一个 `.mq.md` 文件,既是给人读的文稿,也是给机器跑的程序。写文档的过程就是在写可执行逻辑——大型项目里,说明、示例与实现不再分叉成三份真相。它不是「又一个 Markdown 编程语言」,而是**文档原生的编程运行时(Document-native runtime)**——一门关于**可执行知识(Executable Knowledge)**的语言。
v2.2.0 起,`marqdo call` 可以直接调用这份文件里的一个函数。读的是同一页说明,跑的是同一个实现。知识因此可以当工具用,测试也不必再包一层 `# main`。
欢迎访问 [marqdo 官方网站](https://www.marqdo.com/) 阅读更多特性与可执行文档。
语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · 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)
**链接语法**:[doc/design/link-syntax.md](doc/design/link-syntax.md) · 语法宪法:[doc/design/markdown-mapping.md](doc/design/markdown-mapping.md) · 对象:[objects.md](doc/design/objects.md) · 调用实参:[call-arguments.md](doc/design/call-arguments.md) · 用户站:[user-site.md](doc/design/user-site.md) · 浏览:[view.md](doc/design/view.md) · 调试:[view-debug.md](doc/design/view-debug.md) · OKF 清单:[catalog-cli.md](doc/design/catalog-cli.md) · Engineering Knowledge:[engineering-knowledge.md](doc/design/engineering-knowledge.md) · VS Code 扩展:[vscode-extension.md](doc/design/vscode-extension.md)(分支 **`vscode-extension`**;提交约定 [vscode-extension-commit.md](doc/design/vscode-extension-commit.md)) · **AI Skill**:[skills/marqdo/](skills/marqdo/)(说明 [ai-skill.md](doc/design/ai-skill.md)) · 官方扩展:[ext-llm.md](doc/design/ext-llm.md)(`ext/llm`)· [ext-agent.md](doc/design/ext-agent.md)(智能体开发框架)· [ext-cli.md](doc/design/ext-cli.md)(`marqdo ext list/add/remove`) · 原生插件 ABI:[ext-abi.md](doc/design/ext-abi.md)(`lib/plugin`) · 金样例:[tests/](tests/) · 用户文档:[public/](public/) · 变更:[CHANGELOG.md](CHANGELOG.md)
---
@@ -29,15 +31,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,7 +129,7 @@ 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. **可靠性基准**:让同一个 AI 分别用 Python / TypeScript / Marqdo 完成真实任务,测量生成长度、语法 / 语义错误率、修复轮次、token 消耗与人类阅读 / 修改成本——用实验数据证明「文档型语法降低 LLM 生成熵」。
@@ -64,24 +148,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 +206,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,8 +284,25 @@ marqdo catalog public -o .marqdo
---
## 现状(v1.4.2)
## 现状(v2.3.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)
@@ -171,7 +323,7 @@ marqdo catalog public -o .marqdo
- **`web`**:**Artifact 模型(ADR [0007](doc/adr/0007-web-document-endpoint.md))** — `type: web|endpoint` Document/Endpoint;facade `page`/`route`/`serve`/`render`/`inspect`/`use`;Resource 在 `ext/data` · `ext/security` · `ext/net`;设计 [ext-web-artifact.md](doc/design/ext-web-artifact.md);原生 **Go `libweb`**([ADR 0004](doc/adr/0004-web-plugin-go.md));示例 [marqdo-blog](examples/marqdo-blog/) · [web-client-site](examples/web-client-site/) · [anlian-mq](examples/anlian-mq/)
- **`quantum`**:Q0–Q7 + Q8a/b 主题 SVG;示例 [quantum-entanglement](examples/quantum-entanglement/)
- **`linalg`**:L0–L6 + 公式文档面(中缀 / `declare` / 展示化简);示例 [linalg-transpose](examples/linalg-transpose/) · [linalg-svd](examples/linalg-svd/) · [linalg-least-squares](examples/linalg-least-squares/)
- **`agent`**:A1–A4 + **MCP Server/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)
@@ -180,7 +332,7 @@ marqdo catalog public -o .marqdo
- **浏览器 Marqdo(WASM)**:`marqdo wasm build` + 官方 bridge 自启(作者零业务 JS;桥内可含列表/路由/storage/ws/文件/Canvas/音频/Observer/拖放);`lib/browser` + GFM;`web.client_embed`;示例 [browser-hello](examples/browser-hello/) · [browser-app](examples/browser-app/) · [browser-media](examples/browser-media/) · [web-client-site](examples/web-client-site/)([ADR 0002](doc/adr/0002-browser-marqdo-wasm.md) · [D](doc/roadmap/browser-wasm-d.md) · [E](doc/roadmap/browser-wasm-e.md) · [F](doc/roadmap/browser-wasm-f.md))
- 选型:[ADR 0001 — Rust](doc/adr/0001-implementation-language.md) · [ADR 0002 — 浏览器 WASM](doc/adr/0002-browser-marqdo-wasm.md)(C0–C5 完结,见 [roadmap/browser-wasm.md](doc/roadmap/browser-wasm.md))· [ADR 0003 — 异步效应](doc/adr/0003-browser-async-effects.md)
### 如何使用最新 Marqdo(v1.4.2)
### 如何使用最新 Marqdo(v2.3.0)
**安装解释器(任选其一)**
@@ -195,14 +347,16 @@ marqdo catalog public -o .marqdo
```bash
# 1) 源码安装(跟 tag 或 main)
git clone https://github.com/cflmy/marqdo.git && cd marqdo
git checkout v1.4.2 # 或留在 main
git checkout v2.3.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
@@ -234,7 +388,7 @@ marqdo wasm build
# → dist/wasm/ … 见 examples/browser-hello/
# 6) Releases:Windows exe/zip/vsix;Linux CLI zip + native `.so` zip
# https://github.com/cflmy/marqdo/releases/tag/v1.4.2
# https://github.com/cflmy/marqdo/releases/tag/v2.3.0
```
开发期也可用 `cargo run -- …` 代替已安装的 `marqdo`:
+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.4.2"
version = "2.3.0"
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"
+145
View File
@@ -1,3 +1,148 @@
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,
+41 -3
View File
@@ -13,10 +13,25 @@
## 当前文档
> **可执行知识下一阶段的阅读顺序**:[原始意图 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 草案:叙述统一 · 粗体代码 · 斜体返回 · 形参体推断** |
| [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 反例 |
| [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) | **`#` 对象 / `##` 函数与方法** |
@@ -48,7 +63,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 循环)** |
@@ -99,6 +120,23 @@
| [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**(规划) |
| [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/)。
+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。
@@ -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 保持不可用,不阻塞已经完成的只读预览切片。
+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 的所有验证结论。
+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. 循环的新写法你倾向哪一种:
- `- [从篮子取出的每个果子](遍历 篮子 为 果)`
- `- [篮子里的果子](篮子 → 果)`
- 保留 `- [果](篮子)` 作短形
+2 -1
View File
@@ -156,7 +156,8 @@ source: &str (+ optional import map)
```markdown
---
import json:lib/json.mq.md
import:
json: lib/json.mq.md
---
# main
+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 回归 → 写变更文档。
+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` | 本文件 |
@@ -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` | 本文件 |
@@ -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` | 本文件 |
+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` 引擎),
而不是继续在特性内部找"重复"——那已经找完了。
+9 -7
View File
@@ -3,22 +3,24 @@
| | |
|---|---|
| 状态 | **Accepted · 核心语法封闭集合(CI 守卫锁定)** |
| 日期 | 2026-09-22 |
| 日期 | 2026-09-22;2026-10-23 校正 v2.1 默认链接语义 |
| 守卫 | `tests/core_surface.rs` ⇄ `src/parse/mod.rs` `CORE_CONSTRUCTS`(改动任一侧不同步 → CI 红) |
| 相关 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md)(语义宪法)· [layers.md](layers.md)(准入戒律)· [three-problems.md](../roadmap/three-problems.md) 问题一 · [three-problems-plan.md](../roadmap/three-problems-plan.md) T1.1/T1.3 |
> **戒律总纲**:核心标记是**封闭集合**(约 19 个构造)。新增任何一行必须走 ADR(见 [layers.md](layers.md) 准入戒律)并回答「为什么现有标记不够」;生态需求的默认答案是**进 ext**。本表 id 列与守卫测试强一致:改表不同步 `CORE_CONSTRUCTS`(或反之)、样例文件缺失,一律 CI 红。
> **版本边界**:构造 ID 是历史守卫标识,不是固定不变的语义说明。`link-index` ID 暂保留以匹配注册表,但默认 `[]()` 已是描述包裹 payload;旧索引语义仅属于显式 Classic 兼容路径。未来步骤/知识投影见[文档原生指导](document-native-development-guide.md),不要把目标能力当作当前已实现。核心数量之外,还要审查上下文例外和作者负担。
## 1. 行构造
| id | 外形 | 语义 | 戒律 | 样例 |
|----|------|------|------|------|
| `narrative` | 无标记文字 | 叙述(注释) | 段落内延续到空行;**默认安全**——永远不存在「叙述被执行」的路径 | `tests/markup-v03/soft-emphasis.mq.md` |
| `narrative` | 无标记文字 | 叙述(不执行) | 段落内延续到空行;普通叙述不触发执行;未来知识引用投影也不改变此权限边界 | `tests/markup-v03/soft-emphasis.mq.md` |
| `blank` | 空行 | 段落边界 | 叙述分段的唯一手段;不得被赋予其它语义 | `tests/markup-v03/inc-prose.mq.md` |
| `heading-unit` | `#` / `##` | 对象 / 函数单元 | 标题即单元边界,按深度嵌套;正文禁止用 `##` 做版式(会变成函数) | `tests/markup-v03/decl-ident-only.mq.md` |
| `call-line` | `>` | 调用行 | 输出等副作用 = **普通函数**,不是架构标记 | `tests/markup-v03/dual-call.mq.md` |
| `branch-list` | 体内 `1.` 递增 | 分支 | 自 `1.` 起序号递增构成一个判断;重出 `1.` 开新判断;`N. *` = else;**不是所有有序列表都是 if** | `tests/markup-v03/greet-default.mq.md` |
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [项](集合)` | `tests/structure/loop.mq.md` |
| `loop-list` | `-` | 循环 | 条件形 `` - `条件` `` 或遍历形 `- [说明](遍历 集合 为 项)`;描述不是绑定变量名 | `tests/structure/loop.mq.md` |
| `param` | `` + `名` `` | 形参(兼容形) | 首选叙述 `` `名` `` 升参(宪法 §8);`+` 形仅兼容保留 | `tests/markup-v03/greet-default.mq.md` |
| `table` | GFM 表 | 集合 | 几何即类型([tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md));**绑定 = 数据,未绑定 = 文档表** | `tests/structure/collection.mq.md` |
| `fence` | ` ```lang ` | 外联 | 语言块原样外联,不进 Marqdo 语义 | `tests/lib/foreign-python.mq.md` |
@@ -30,12 +32,12 @@
| id | 外形 | 语义 | 戒律 | 样例 |
|----|------|------|------|------|
| `ident` | `` `名` `` | 声明 / 引用 | 首次未赋值 = 声明;叙述与程序共用同一视觉习惯 | `tests/markup-v03/decl-ident-only.mq.md` |
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 只有粗体进入执行;判别序:赋值 → 调用 → 表达式 | `tests/markup-v03/multi-bold.mq.md` |
| `bold-code` | `**…**` | 代码(赋值 / 调用 / 表达式) | 粗体内代码判别序:赋值 → 调用 → 表达式;不取消调用行、返回等其它显式执行入口 | `tests/markup-v03/multi-bold.mq.md` |
| `italic-return` | `*…*` | 返回 | 改变控制流(**返回是架构**);返回即结束函数体 | `tests/markup-v03/inc-prose.mq.md` |
| `empty-return` | `*None*` / `****` | 空返回 | 返回 `None` 并结束函数体 | `tests/markup-v03/empty-return-none.mq.md` |
| `link-index` | `[键](集合)` | 取元 / foreach | **主取元语法**;与 bracket-call 靠 `]` 后是否紧邻 `(` 消歧 | `tests/lib/table-collections.mq.md` |
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;与 link-index 消歧同上 | `tests/structure/bracket-call.mq.md` |
| `footnote-index` | `集合[^键]` | 过渡取元 | **仅兼容**;新代码一律写 link-index | `tests/structure/footnote-index.mq.md` |
| `link-index` | `[描述](表达式)` | 描述包裹 payload(历史 ID) | 默认 Occlusion;取元可写 `[说明](access(集合, 键))`,不按描述取键;循环载荷见上 | `tests/occlusion/access-and-loop.mq.md` |
| `bracket-call` | `修饰… [函数] 实参…` | 方括号标记调用 | 前置修饰 → `名=True`;紧邻 `](` 的默认语义为 payload 遮蔽,不是旧索引 | `tests/structure/bracket-call.mq.md` |
| `footnote-index` | `集合[^键]` | 兼容取元 | 保留既有能力;新代码优先 `access(...)`,需要解释时包裹描述,不再推荐旧 `[键](集合)` | `tests/structure/footnote-index.mq.md` |
| `soft-emphasis` | `*仅*` / `**说明**` | 忽略 | 非代码形强调**不执行**——默认安全的关键消歧规则 | `tests/markup-v03/soft-emphasis.mq.md` |
## 3. 词法大类(LineKind,`src/lex/mod.rs`)
+1 -1
View File
@@ -80,7 +80,7 @@ Marqdo 换 **Rust 或 C++** 都不改变「主前端不该是 Flex/Bison」这
| **pulldown-cmark** *或* **comrak** | GFM 事件/AST | 标题、列表、表格、emphasis/strong;Spike 已证明「库 + 行扫描」可行。二选一做 Spike 对比后钉死 |
| **thiserror** / **anyhow** | 错误类型 | 诊断与 CLI 报错 |
| **clap** | CLI | `marqdo run [path]` |
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;`import x:x.mq.md` 仍按**行**抽取(见 Spike) |
| **serde** + **serde_yaml** | 元信息 | 仅解析 frontmatter 中的 YAML **键值**;嵌套 `import:` 映射与其它 YAML 键一并解析 |
| **ureq** (=2.9.7) | HTTP(S) | `lib/net`;为 Cargo 1.81 另钉 `idna_adapter`/`zeroize`(见根 `Cargo.toml`) |
| **regex** (=1.13.1) | 正则 | Mid M1 `lib/re`;`default-features=false` + `std`/`unicode`;无回溯引用 |
| **sha2** (=0.10.9) / **sha1** (=0.10.6) / **md-5** (=0.10.6) / **hmac** (=0.12.1) | 摘要 | Mid M3 `lib/hash` |
@@ -0,0 +1,284 @@
# Marqdo 文档原生开发指导:让知识的表达、执行与复用成为同一件事
| 项目 | 约定 |
|---|---|
| 状态 | 下一阶段开发指导与规划修订;不表示下述目标接口已经实现 |
| 日期 / 审阅基线 | 2026-10-23 / `main`,`7674ebb`;继承缺口审计的 `434be9f` 代码证据 |
| 原始意图 | [009](../next/009.md)、[附属设计](../next/Marqdo_Executable_Knowledge_Design.md)、[附属示例](../next/Marqdo_Executable_Knowledge_Example.md) |
| 配套实施文件 | [详细开发规范](../next/Marqdo_Executable_Knowledge_Development.md)、[缺口与交付路线](../roadmap/executable-knowledge-gaps-2026-10-23.md) |
| 本轮边界 | 校正开发方向、作者体验、AI 工作协议和验收;不新增语法,不宣称实现新能力 |
## 1. 审阅结论与规范关系
Marqdo 的优势不在于给传统程序换一套 Markdown 符号,而在于:**读者解释知识、作者修改知识、程序执行知识、AI 查找并复用知识,能够指向同一份有结构的文档和其中的同一步。** 标题、叙述、表格、链接描述、输入输出、来源及执行行为不应分散在彼此手工同步的系统中。
现有规划没有放弃这一目标,但工程排序存在偏移:把身份、图、证据、锁、句柄、晋升全部铺完,再验证人和 AI 是否更容易使用。这样可能交付一个功能齐全的制品管理系统,却让文档作者承担另一套注册、声明、审核和配置工作。需要改变交付方法,不必推翻确定性编译、绑定和权限机制。
本指导规定**为何开发、作者维护什么、怎样证明值得开发**;详细规范规定语义模型与执行约束;路线图规定当前缺口、切片与完成证据。三者不是三套平行设计。遇到冲突,依次采用:`009` 的产品意图 → 本指导对作者负担、场景分级和交付次序的修订 → 详细规范的工程规则 → 附属概念示例。当前代码与测试证明“已实现什么”,不能把代码局限升级为永久语言禁令;原始讨论保留,不据其重新引入已被否决的方案。
### 1.1 方向修订清单
| 容易偏移的做法 | 修订后的要求 | 必须保留的技术约束 |
|---|---|---|
| 先做完整知识治理平台,再给作者使用 | 从一篇可读、可运行、可定位步骤的文档交付,逐层扩展 | 每个已支持路径都有准确的目标和效应边界 |
| 为进入知识库再写 YAML、注册表和索引 | 从源码推导;只有不能推导的领域事实才需作者补充 | 生成物有版本,可重建,可检查来源 |
| 所有逻辑先封装成可登记函数/类 | 一次性逻辑直接写;需要命名、解释或复用时逐步提取 | 作用域、形参、返回与副作用明确 |
| 所有调用先审核、锁定、签发远程凭据 | 本地探索、项目复用、严格业务、远程执行分级 | 精确目标、运行时权限不能被标签或模型绕过 |
| AI 只能搜文档、填工具参数 | AI 可以读步骤、组合、选择候选、局部修改、提取和验证 | 模型的选择必须转成显式目标,由编译器校验 |
| 为“独特”拒绝普通调用或新增更多标记 | 保留简单 payload;让 Markdown 结构提供程序之外的信息 | 无第二套表达式文法,无裸词隐式执行 |
| 核心构造数量不增长就是简单 | 同时检查上下文例外、记忆负担和诊断成本 | 新构造需 ADR;不靠把新规则藏进旧构造绕过审查 |
### 1.2 四个不能互相替代的完成条件
1. **读得懂**:不打开生成图,也能从源文件看出目的、关键步骤、参数角色和限制。
2. **执行同一件事**:标签表达意图,payload 决定计算;运行 trace 能回到源码步骤,不能执行另一个同名目标。
3. **改得动**:人或 AI 能修改一个明确步骤,看到影响与验证结果,不必重写整份文档或同步多份签名。
4. **复用得对**:找到已有能力后实际调用它;不满足条件时给出具体拒绝原因,而非用复制源码掩盖失败。
“更适合 AI”是待验证的产品假设,不是 Markdown 文件后缀自动赋予的性质。正确性和作者成本优先于 token 下降;错误复用更便宜不算优化。
## 2. 语法审查的保留、修正与暂缓
以下裁决针对审查结论的适用范围,不重写历史实验记录。旧文档中的原型、性能数值和当时的 `Value`/AST 限制,不能直接当作 v2.1 的规范或测试结果。
| 审查材料 | 保留的洞见 | 需要修正的外推 / 本轮处置 |
|---|---|---|
| [函数即命名](function-as-naming-philosophy.md) | 从正文计算出发,命名应降低理解和复用成本;避免无意义包装 | “具名给值缺失”是历史观察,当前有具名参数;替换模型是教学解释,不意味着禁止递归、前向引用或必须文本展开 |
| [方括号作为标签](bracket-as-label-evaluation.md) | 描述与 payload 共址;标签帮助解释、检索和拆步骤 | Classic 冲突是迁移历史,不据此恢复默认 `[键](集合)`;不强制每个常量或子表达式都有标签 |
| [圆括号与可读调用](paren-call-and-readable-invocation.md) | 调用标记应明确;保留 `f(args)` 的局部可读性 | 原型撤回不代表现有版本缺少该能力;Marqdo 的独特性不依赖消灭熟悉的表达式形式 |
| [从标记推导调用](call-syntax-from-marks.md) | 语义成分有明确标记;自然语言是连接与解释,不参与猜测调用 | 持久跨文档接口优先具名实参;短而稳定的位置参数仍合法。推断参数的声明次序变化属于接口变化,不承诺任意润色都无影响 |
| [环境参数](ambient-parameters-evaluation.md) | 参数来源应可见,避免调用者隐式环境影响复用 | 文档顶部已否决 L0 裸“执行”触发,正文旧建议不能重新生效;文件级常量也须有明确绑定与依赖,不变成动态作用域 |
| [函数作为值](functions-as-values-evaluation.md) | 区分名称数据、一等函数、有限查表;避免无需求增加核心复杂度 | “匿名函数必不能索引”“动态调用必然破坏契约”不是普遍定理。将来可研究稳定节点身份与运行时契约;本轮不引入闭包,也不永久禁止 |
| [函数作为表格](function-as-table-semantics.md) | 数据表几何有既定含义;契约表不可另造一份参数声明 | 不把表格全部变成函数,也不把“现有实现不支持”写成“表格不能计算”;有限决策表先评估库方案,只有明确角色和歧义测试后才讨论语言扩展 |
| [核心表面](core-surface.md)、[分层](layers.md) | 核心小、标记可解释、构造有测试与准入流程 | 清单中的旧取元/循环说明需随迁移更新;固定数量不等于低认知成本,守卫通过也不证明文档语义正确 |
| [链接设计](link-syntax.md)、[告警疲劳](warning-fatigue-control.md) | 单一 payload 文法;标签漂移可提示;默认安静、按需严格 | 标签不是纯粹可丢弃的注释,也不是事实证明;不做每次运行重复的批准仪式,不靠词汇相似度证明描述与代码一致 |
### 2.1 继续冻结的语法边界
- 默认 `[]()` 是描述包裹 payload;旧取元只能在显式历史兼容路径下解释。现行取元用 `access(...)` 等已支持形式;循环使用明确遍历载荷。
- `[]()` 不等于“仅函数调用”:计算、取元、调用、遍历、叙述引用都需要各自语义角色,不能只收集 call 边就宣称完成知识步骤。
- 正文引用与可执行位置有不同调度权限。普通句子不因出现“执行”“发送”或工具名而运行;正文解析成引用也不自动求值。
- 不把所有 `#` 解释成某种知识对象,或把继承悄悄变成实例关系。标题的既有语义必须兼容,IR 可区分 Type、Entity、Fact、Function。
- 不给同一参数增加正文声明、签名表、工具 schema 三套作者真相。规范签名和工具 schema 是投影;契约表补充类型、约束和说明,不偷偷增加形参。
- 可读源文件是硬要求;普通 Markdown 渲染器是否把含空格/嵌套表达式的链接渲染成可点击链接是另一件事。不能承诺全部标准渲染器理解执行语义。
### 2.2 哪些编辑不能当成“只是改文案”
不含语义标记的普通叙述润色,应保持执行结果和实现摘要;标签改名应保留 payload 行为,但更新展示/检索内容。反引号声明、首次出现顺序、标题名称/层级、粗斜体、表格几何、契约、来源和适用范围的改变则可能影响程序或知识可信性。编辑器必须展示真实差异,不能统一标为 prose-only。
标签漂移诊断应说明“描述或实现可能需要复核”,不能自动替作者改写业务意图。自然语言一致性检查可作辅助建议,确定性检查仍需可定位的符号、类型、契约或测试证据。
## 3. 作者工作流:先写清楚,再获得复用能力
### 3.1 一次性计算不需要预先建知识模型
下面是当前默认语法的完整最小程序。无模式开关、无项目注册、无知识 ID、无锁文件。
```markdown
# main
这是演示订单,单价与数量直接写在计算处。
**小计 = [两件商品的小计](2 * 30)**
> print text=`小计`
```
可读意图和精确计算共址。这个标签值得保留,因为它说明本次计算的业务角色;不要求把 `2`、`30`、乘法分别命名。
### 3.2 需要解释或复用时才提取命名能力
```markdown
## 商品小计
根据购买数量`数量`和商品单价`单价`计算小计。
*[按数量与单价计算](数量 * 单价)*
# main
计算同一笔演示订单。
**小计 = [两件商品的小计](商品小计(数量=2, 单价=30))**
> print text=`小计`
```
两个完整程序在本轮本地现有 `target/debug/marqdo` 上分别以 Tree 和 Bytecode 执行,均输出 `60`。这仅验证基础语法,不证明步骤身份、重构工具或 Agent 闭环已经实现;也不是全仓测试报告。可将各块保存为 `.mq.md` 后用 `marqdo run 文件 --backend tree` / `--backend bytecode` 复核。
**后续工具目标**:从选中表达式提取为标题单元,推导自由变量为参数、保持求值顺序与 effect 次数、生成具名调用,并给出可审阅补丁。反向内联也应保留契约和来源关联;无法证明安全的捕获变量、递归、控制流、动态目标或有副作用表达式,先拒绝自动变换并说明原因,不伪称等价。
### 3.3 跨文档复用与事实说明分别增长
当第二篇文档需要这段计算,才提取模块并显式 import;不要为十行单文件强制创建 `corpus/knowledge/apps` 目录树。项目索引按约定发现,明确边界或外部来源时再加入配置。
当“商品小计”依赖政策、时间、币种等条件,再就地补契约与来源。简单乘法不要求假造现实来源;“某商店当前折扣为九折”则不能仅凭函数返回 `0.9` 声称真实。
正文可以说明结果为何成立,目标是引用同一能力和同一次受控执行的结果,而非手抄另一份公式。正文引用 AST、结果投影和绑定身份尚需开发;完整业务链使用[目标示例](../next/Marqdo_Executable_Knowledge_Example.md)验收,不把它冒充当前全部可运行的教程。
### 3.4 维护时看到知识变化,而不只是文件变化
目标维护流程:修改上游规则 → 显示受影响的计算、正文陈述和消费者 → 执行相关测试 → 展示结果/证据/接口各自变化 → 按使用策略接受更新。普通显示文案变更不应触发全库业务审批;证据过期也不必使无关纯工具全部失效。
## 4. 人维护语义,编译器维护机械关联
| 信息 | 作者责任 | 编译器 / 工具责任 |
|---|---|---|
| 目的与步骤 | 有帮助的标题、叙述、标签;避免空泛重复 | 保留源位置和层级,生成步骤投影,不要求手工节点注册 |
| 输入输出 | 一份参数来源和必要契约;领域单位不能靠猜 | 推断规范签名、检查调用、生成 schema 和签名视图 |
| 目标与依赖 | 显式 import、可读名称、必要消歧 | 绑定唯一 SymbolId,生成依赖边与闭包;不要求手写 ID |
| 效应 | 扩展作者声明宿主能力;业务作者必要时收窄允许范围 | 汇总直接及传递效应;未知不得推断 pure;运行时执行能力上限 |
| 事实与来源 | 原始资料、范围、有效期、人工审阅等不可推导信息 | 关联来源、记录验证事件、传播失效;不将文件路径视为事实证明 |
| 身份与版本 | 有意移动/更名时确认必要迁移 | 区分身份与内容摘要;报告歧义,不靠猜测维持假稳定 |
| view / AI 索引 | 不维护第二份可执行描述 | 同一语义模型投影;显示生成代、验证政策和缺失字段 |
生成信息不等于免费:首次编译、缓存修复、错误定位都要可理解。失败时应回到源文档中可修改的位置,而不是只报内部 Artifact 字段名。
稳定身份要诚实:同一次编译内引用和 trace 必须一致;普通文本编辑不应打乱无关节点;复制相似步骤、跨文件移动等无法唯一识别时,要求确认迁移或明确生成新身份。禁止用文本相似度悄悄继承已审核的知识身份。
## 5. AI 原生工作协议:读步骤、改步骤、验证步骤
本节是**待实现的协议约束**,不是新增 CLI 命令清单。优先扩展现有 MLSP、view、EKC 和 Agent 工作簿,不另造一套 Agent 框架或知识库。
### 5.1 发现后的最小上下文包
一次检索返回可展开的上下文卡,而非强制倾倒整个文件或只给函数 schema:
1. 标题路径、任务相关叙述、标签和精确源码片段;
2. SymbolId/步骤节点、source span、源码摘要、生成代;
3. 输入角色、返回、单位、默认值和适用条件;
4. 直接依赖、效应、必要来源及分层验证状态;
5. 支持该能力的例子/测试,相关失败经验、禁用条件和替代能力;
6. 还缺哪些检查、能否在当前 policy 下运行、为何被拒绝。
来源不可用、字段未推导、上下文被截断都须显式标识。按预算可展开依赖,但不能悄悄省略改变适用性或权限的重要信息。原始资料及标签是内容,不是可以覆盖 Agent 策略的指令。
### 5.2 复用、适配、新建的分界
- **REUSE**:AI 可根据任务选候选,提交精确目标与输入;resolver 确认目标、契约、适用性、版本和 effect,执行既有制品。复用不靠“没有生成文件”推断,必须有实际调用 trace。
- **ADAPT**:已有能力接近但不适用;说明差异,保留依赖/来源关联,在局部副本或补丁中改变必要部分,再验证。不为了通过测试改写原始来源或放宽全局策略。
- **CREATE**:没有合适候选或明确需要新语义;记录检索范围和失败原因,在任务预算及写权限允许时新建。不能把检索服务故障当作“仓库没有能力”。
- **ASK / STOP**:缺业务决策、权限或关键证据时报告具体缺口。编译器无法决定的真实意图不交给近似匹配默默补全。
AI 并非只能发现和解释。它可以提出精确目标、组合已有能力、改进表达、重构及补测试;不能以自然语言自报正确来替代执行验证,也不能把含糊名称传给后端任意选一个目标。
### 5.3 局部修改的事务边界
编辑请求至少携带目标文件/节点、期望源码摘要、补丁范围和预期行为变化。应用前检查摘要,源已变化则重新定位和审阅,不覆盖用户改动。应用后重新解析受影响文档,生成语义 diff:参数/返回、目标、effect、控制流、证据与依赖是否改变。
对“只改措辞”请求,检测到接口或实现改变时停止自动合并;对“改计算”请求,运行相关正负例并展示影响。原始文本、格式与未知 metadata 尽量保留,不通过整篇重生成来完成一行修改。禁止修改生成图伪装修复源码。
首个试点只支持可确定定位的纯计算步骤与普通函数,不等待通用 AST 编辑器、跨项目事务或完整知识治理。安全拒绝超范围输入也属于验收。
### 5.4 解释和负知识必须有落点
解释结果应关联到“哪一步、用了哪个目标、哪些输入、哪份来源、哪次验证”,区分已执行观察和模型推断。运行 trace 可以证明程序路径,不能证明任意自然语言论证正确。
失败经验需要保存适用范围、触发条件、关联能力、原因与失效时间/版本。例如“此折扣不适用于退款”应在查询定价能力时可见,而不是埋在另一份聊天记录里。先由普通文档与结构化关联承载,不先新增通用推理语言;过期负知识也要撤销,不能永久拦截修复后的能力。
## 6. 渐进严格:不把治理门槛塞进每一行正文
下面是目标政策分级,不是当前已有四种 CLI 模式。政策由项目/宿主配置和调用上下文选定,源文档保持同一种语法。
| 场景 | 必需条件 | 默认不要求 |
|---|---|---|
| 本地探索、单文件运行 | 明确语法与目标、已有运行时契约、宿主能力限制;如实显示未知状态 | lock、来源、ready 晋升、远程签名句柄 |
| 项目内自动复用 | 精确绑定、输入/适用性检查、效应许可、状态满足所选政策、执行 trace | 所有纯工具都有人审证据、每次独立确认 |
| 严格业务/可复现任务 | 相关依赖与证据锁定、必要验证新鲜度、受控环境和审计;明确不可重放部分 | 对无关文案变化重审整个项目 |
| 远程/多租户/不受信调用方 | 上述相关约束,加可信授权主体、范围、服务端能力上限、撤销/期限与防伪设计 | 把客户端提交的 `allow_effects` 当授权本身 |
`ready` 是“对某项 policy 和输入/上下文已具备复用条件”,不是永久万能认证。未验证的本地草稿可以被检索、查看和按明确权限试跑;不能冒充满足严格政策的可复用事实。测试通过与事实证实分别报告。
正文 `check/view static` 不执行外部效应。用户主动打开的纯预览可复用项目或会话已有政策,不要求每个链接弹窗;effectful 运行始终受宿主能力和明确执行上下文控制。锁和摘要是完整性机制,不自动等于远程授权;可信本地引用无需先搭建凭据服务。
## 7. 交付切片:每片都有文档作者与 AI 能看见的结果
编号与[缺口路线图 §7](../roadmap/executable-knowledge-gaps-2026-10-23.md#7-依赖顺序与可合并切片)一致;G 编号沿用现状证据,M0–M6 保留为工程能力映射,不再被理解为必须全部串行完成的墙。
### S0 作者基线与最小语料
- 选定单文件计算、提取函数、两文档引用、表格取元/遍历、业务政策及拒绝复用六类任务;记录当前写法、输出、诊断和作者重复维护项。
- 优先整理 `doc/README`、核心语法卡片、教程与运行示例的版本状态;不要先扩展通用库数量。
- 为最小样例建立无网络门禁。100 单元及更大语料逐步增长,不阻塞首个可读文档切片。
- 完成证据:别人按当前入口能写出正确默认语法;已实现与预期失败分开报告,不能把待实现测试跳过计为成功。
### S1 可读步骤与唯一目标
- 主要落点:`src/parse/`、`src/ast.rs`、`src/sema/`、`src/knowledge/compile.rs`、`src/view/`。
- 在最小故事内联合完成 G01/G03:保留 label、payload、上下文和跨度;每类步骤有输入输出与依赖投影;旧 EKC 查询索引不再覆盖语义图。
- 普通导航、正文引用、可执行表达式、循环分别处理,正文保持惰性。先确保支持范围内同一引用在源码、view、图中是同一个目标,再扩展覆盖范围。
- 完成证据:作者能从渲染步骤返回对应源码;同名目标不误连;计算/取元/循环不是伪造的 call;重复构建可对照;未支持上下文明示。
### S2 确定执行与早期 AI 复用试点
- 主要落点:`src/sema/`、`src/interp.rs`、`src/bytecode/`、`src/mlsp.rs` 与现有 Agent 入口。
- 完成静态普通函数、显式 import、关联函数的 BoundCall 主链;G02 与 G06 的效应安全下限不可延期。小范围可先用明确纯操作白名单,未知路径必须拒绝纯证明,而非猜 pure。
- 实现最小上下文卡与本地绑定引用;以 stub/no-LLM 测试验证协议,然后用现有 Agent 跑相同故事。无需先完成远程鉴权平台或全面来源审核。
- 完成证据:同一需求实际调用既有函数,不新增同义实现;两个后端 trace 对上图中目标;改目标、错误输入、未知效应、权限不足不能静默执行。
### S3 局部编辑、提取与库可读性
- 主要落点:MLSP 编辑/定位、相关 sema/检查入口、`lib/`、`ext/`、教程与测试。
- 按 §5.3 实现受摘要保护的局部修改和语义 diff;实现受限纯表达式提取,或明确标为待实现,不用人工演示冒充工具能力。
- 迁移标准库/扩展时删掉重复包装与噪音标签,保留有意义的业务步骤、契约和负例;中英镜像含义一致。兼容旧调用接口,不用增加旧语法解释救迁移遗漏。
- 完成证据:同义润色不改执行;改反引号声明能检测签名变化;表达式提取前后结果/effect 次数一致;冲突补丁拒绝;CLI、库、扩展与 view 既有能力继续通过。
### S4 业务知识的来源与适用性
- 主要落点:契约、SourceRef/VerificationRecord、验证事件、Agent 候选解释;完成 G05 与 G07 的项目政策部分。
- 选定书店案例的币种、数量边界、会员范围与政策有效期;给 schema、拒绝诊断及可运行负例,不泛化为全能业务规则语言。
- 同步补齐传递效应与相关负知识;生成契约/状态展示,减少作者重复填写。
- 完成证据:同一计算因输入或证据不同而正确通过/拒绝;来源过期不被 `tests=passed` 覆盖;普通纯工具无需虚构 SourceRef。
### S5 变化传播与严格复用
- 主要落点:`src/sema/lock.rs`、图/impact、产物提交与消费者;完成 G04/G08 和严格 handle 复核。
- 区分身份/接口/实现/证据/闭包,给出可读升级 diff;整代快照保证消费者不会读取混代数据。并发读写一旦开放,该一致性就是前置条件,不能等到此片才承认风险。
- 完成证据:修改依赖政策后,下游计算和正文解释进入影响集合;文案变化不误判实现变化;并发编辑或构建崩溃不导致错目标执行;锁不声称重放网络/随机/LLM。
### S6 生态验收与发布
- G10/G11 从 S0 起每片执行;S6 汇总兼容矩阵、真实工作流和打包后冒烟,不把测试留到最后。
- G12 随实际规模需求推进;远程凭据/多租户是有条件的独立交付。它们不阻塞受信本地试点,也不得被本地通过的测试覆盖为“已安全支持”。
- 完成证据:当前默认语法的 lib/ext/CLI/MLSP/view/WASM 等受影响消费者有明确结果;目标示例中的已发布子集实际可运行,未发布部分保留状态;发布声明与证据一一对应。
## 8. 验证 Marqdo 优势,而不只验证组件存在
### 8.1 必须收集的产品指标
| 维度 | 记录方法 | 失败信号 |
|---|---|---|
| 作者负担 | 完成同一任务所需手写声明、重复字段、配置、跳转和确认次数 | 简单本地算式也必须填写制品清单 |
| 阅读与定位 | 给定问题,定位正确步骤/限制的准确率、耗时与上下文量 | 只看 label 会误导,必须打开生成 JSON 才理解源文档 |
| 可修改性 | 修改范围、无关 diff、语义变化检测率、冲突覆盖数 | 为改一步而重生成全文件;措辞调整偷偷改变接口 |
| 复用质量 | 已有能力发现率、实际调用率、重复实现率、误用率 | 检索命中却重新写代码;正确拒绝算成任务失败而被优化掉 |
| 知识可追溯性 | 结果关联目标、步骤、输入、来源和验证的覆盖率 | `tested` 被当作事实正确;解释引用未执行的步骤 |
| 总成本 | 正确完成任务的 token、工具调用、轮次、总耗时及编译成本 | 只报模型 tokens,隐藏额外注册/审核/修复成本 |
### 8.2 对照实验与门槛
1. 固定任务、可访问能力、输入数据、模型版本、工具能力、预算与超时;比较普通 Markdown+代码/RAG、当前 EKC 和新方案。不能给新方案更多现成实现再声称语法更优。
2. 任务包括成功复用、同名冲突、近似但不适用、未知 effect、过期来源、正文不执行、局部修改及库升级。加入自然语言诱导绕过 policy 的负例。
3. 先测确定性协议,再测多次 AI 运行,保留种子(支持时)、原始 trace、版本、失败样本与分布;小样本不夸大收益。
4. 正确目标、无越权和正文无外部 effect 是硬门槛。原有兼容测试不得降低;效率阈值先测基线再登记,不捏造提升百分比。
5. 若作者负担增加或误用率上升,回到交互/语义设计分析原因,不能只用“更多治理更安全”或“模型更便宜”解释过去。
### 8.3 发布声明分层
- “支持新语法”需语法、迁移、双后端与库兼容证据,不意味着完整知识复用已经交付。
- “本地确定性知识复用”需 S1/S2 支持范围内的端到端与拒绝用例;范围外路径显式不支持,不能回落为模糊执行。
- “严格业务知识复用”还需相关 S4/S5 来源、适用性、失效、锁和一致性证据。
- “安全远程知识执行”需额外的授权、能力上限、凭据/撤销及隔离测试;本地 JSON handle 不等于远程安全。
## 9. 每个开发变更必须回答的问题
提交设计或实现时给出一份短而具体的审阅记录:
- 用户要读/写/改/复用的知识是什么?附源文档前后对照,不只给内部结构图。
- 利用了哪种文档原生信息?若只增加通用框架能力,与主线的必要关系是什么?
- 新增了哪些作者必须手工维护的信息?为什么不能从现有语义推导?
- 是否改变标记、作用域、求值顺序、形参顺序、表格几何或正文安全?分别有哪些测试?
- 人、CLI、view、图和 Agent 是否看到同一目标与状态?失败能否回到源码修复?
- AI 的正确复用/局部编辑如何证明?哪些部分仍需模型判断,哪些由编译器决定?
- 标准库和扩展是否先迁移?是否保住既有公开接口、输出与 effect?
- 这是已实现、受限试点还是设计目标?文档和发布声明是否一致?
**准入原则**:内部可以使用成熟编译器、数据库和协议技术;外部必须减少知识在“说明、程序、索引、工具描述”之间的重复翻译。独特性由这条链的实际收益体现,不由新符号数量或与其他语言不同的程度体现。
+8 -5
View File
@@ -51,22 +51,25 @@ Marqdo 把仓库投影为 **可查询、可验证、可复用** 的工程知识
`implements` · `uses` · `depends_on` · `tested_by` · `documented_by` · `constrained_by` · `decided_by` · `supersedes` · `conflicts_with` · `deprecated_by` · `derived_from` · `failed_by` · `related_to`
落盘:`.marqdo/graph/graph.json` · `edges.json` · `index.json`。
落盘(G01 分离后):
- **权威语义图**:`.marqdo/graph/edges.json` · `nodes.json`(`SemanticProject`,含 `authority` 字段)· `steps.json`
- **EKC 检索投影**(非执行依据):`.marqdo/ekc/graph/graph.json` · `edges.json` · `index.json` · **`ir.json`**(完整 IR 快照,供查询热路径)
## 5. CLI
```bash
marqdo knowledge [PATH] -o .marqdo # compile(默认)
marqdo knowledge preflight "task"
marqdo knowledge [PATH] -o .marqdo # compile(默认;写投影 + ir.json)
marqdo knowledge preflight "task" # 暖机读 ir.json;缺图才 compile
marqdo knowledge preflight "task" --refresh # 强制全量重编译后再预检
marqdo knowledge record REUSE
marqdo knowledge learn --task ... --failure ...
marqdo find "authentication"
marqdo find "authentication" # 同上:缺图才 compile;--refresh 强制
marqdo reuse "implement oauth login"
marqdo impact path/to/file.mq.md
marqdo conflicts | stale | duplicate [--fail] | verify
```
统一 `--json`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
统一 `--json`。查询类命令(`preflight` / `find` / `reuse` / `impact` / `conflicts` / `stale` / `duplicate` / `verify`)默认 **读已编译投影**;CI 或源变更后应先 `marqdo knowledge` 或加 `--refresh`。`duplicate` 默认阈值 `0.75`;`--fail` 作 CI Gate。
## 6. Reuse 协议
+206
View File
@@ -0,0 +1,206 @@
# 可执行知识系统:`[]()` 的统一语法与跨文件闭环
| | |
|---|---|
| 状态 | **Design Draft · v2.1 语义重构** |
| 核心判断 | `[]()` 不是“普通代码”与“知识链接”的分界;每一个 `[]()` 同时是代码、文档和知识图节点。 |
| 关联 | [link-syntax.md](link-syntax.md) · [knowledge-layers.md](knowledge-layers.md) · [module-namespace.md](module-namespace.md) · [engineering-knowledge.md](engineering-knowledge.md) |
| 示例 | [examples/executable-knowledge/](../../examples/executable-knowledge/) |
---
## 0. 一句话
> **`[名称](载荷)` 是一个命名的可执行知识步骤:`()` 做原有的任何事,`[]` 说明这一步对人意味着什么;编译器把它们一起编入知识图。**
它不增加、替代或限制 payload 语法。字典取元、表操作、算术、函数调用、嵌套调用、遍历/循环、
甚至受控副作用,都保留原有解释器语义。差别只在于:原来不可见的一步现在获得一个稳定的人话名字、
源位置、输入/输出、依赖和影响范围。
```text
代码投影: eval([名称](载荷)) = eval(载荷)
文档投影: 读者看到 名称,必要时展开载荷、输入与输出
知识投影: 编译器生成 KnowledgeStep(名称, 载荷, 依赖, 类型, 效果, 来源位置)
```
这三种投影缺一不可。只保留前两者是“带标签的代码”;只保留后两者会牺牲可运行性;
三者同源,才是代码即文档、文档即知识、知识即可执行。
---
## 1. 统一节点:`Named<T>`
`[]()` 的正确抽象不是“链接调用”,而是泛型 AST 装饰器:
```text
Named<T> { label, inner: T, span }
```
`T` 是它出现位置原有的语法节点,绝不另造“知识表达式” parser:
| 既有位置 | `T` | 示例 | 知识角色 |
|---|---|---|---|
| 表达式 | `Expr` | `[收件人](at(订单, "收件人"))` | 观测/取值 |
| 表达式 | `Expr` | `[含税价](金额 * (1 + 税率))` | 推导 |
| 表达式 | `Expr` | `[适用税率](税率.查询(地区, 品类))` | 复用/查询 |
| 遍历位置 | `LoopSpec` | `[逐个订单行](遍历 订单.行 为 行)` | 过程/展开 |
| 正文位置 | `InlinePayload` | `订单总额为[含税总价](定价.总额(订单))。` | 叙述中的可执行槽 |
| URL/路径 | `NavigationLink` | `[税率原文](corpus/tax.md)` | 导航/证据定位 |
运行时只执行 `inner`;`label` 不进符号表、不改变作用域、不重复计算。与此同时,
parse/check/catalog 保留整个 `Named<T>`。所以循环不会被误判成“返回一个事实”,取元也不会
被迫拥有来源表;但两者都能在图中被看见、被搜索、被影响分析。
### 1.1 每个节点都有角色,而不是两套语法
角色由既有 AST、类型、效果和依赖推导,必要时由所在 `#`/`##` 的契约约束:
| role | 如何识别 | `check` 应问什么 |
|---|---|---|
| `observe` | 取元、读取字段、读取表/文档 | 读什么、类型是什么、是否可用 |
| `derive` | 纯计算、聚合、映射 | 输入、输出、公式/依赖是否完整 |
| `reuse` | 调用已解析的 `##` / 模块能力 | 调用到哪个稳定符号、参数/返回是否匹配 |
| `iterate` | 已有遍历/循环载荷 | 遍历什么、绑定什么、循环体依赖什么 |
| `act` | 写入、请求、打印等副作用 | 权限、幂等性、影响目标 |
| `narrate` | 正文中的命名载荷 | 它在句中替代什么值、依赖是否可解析 |
一个节点可以有多个 role,例如 `[同步并记录](写入(...) + 记录(...))` 是 `act`,也依赖
若干 `observe`/`reuse` 节点。角色是编译结果,不是作者需要记忆的关键字。
---
## 2. 知识层不是目录隔离,而是同一图的不同投影
“几层知识”不应把语法和项目切断。它们是同一个 `Named<T>` 图中不同职责的节点;
同一份 `.mq.md` 可以同时有多层节点。
| 投影层 | 在统一图中的节点 | 由什么语法产生 | 它回答的问题 |
|---|---|---|---|
| **E 证据** | 原文、数据、文件/表读取节点 | Markdown 链接、`at(...)`、读取调用 | 事实从哪里来? |
| **C 概念** | 类型、字段、术语、约束 | `#`、字段/契约表 | 这些值是什么意思、能否组合? |
| **K 原子知识** | 命名个体、事实、规则 | `# 个体`、`##`、`Named<Expr>` | 哪个可调用单元给出什么知识? |
| **D 推导知识** | 聚合、计算、决策、工作流步骤 | 任意 `Named<Expr>` / `Named<LoopSpec>` | 如何从已有知识得到新结论/行动? |
| **N 叙述知识** | 段落与正文调用槽 | 正文 `Named<InlinePayload>` | 如何把结论说给人或 agent? |
同一条边可以跨层:`[出生年份](at(人物表, "出生年份"))` 同时是 E 的观测、K 的事实值和
可被 N 层引用的节点。`[逐个订单行](遍历...)` 是 D 的过程知识,也为其内部每个推导提供上下文。
这正是通用语法本身兼容知识体系的含义。
### 2.1 `#` / `##` 的位置
- `#` 给一组知识步骤提供可读命名空间、类型/个体语义和文档边界;
- `##` 给可复用步骤提供稳定的公开入口、参数与返回契约;
- `[]()` 给入口内部的**每一小步**命名,并将它们暴露给文档、图和工具;
- `> 类型` 仍只构造运行时实例;知识个体不等于运行时 map。
因此 `## 含税总额` 不是黑盒函数:其函数体中的 `[订单行](...)`、`[逐行计税](遍历...)`、
`[汇总](sum(...))` 都是可检索、可解释、可追踪的知识步骤。函数是知识单元的边界,
`[]()` 是知识单元的内部结构。
---
## 3. 大项目的寻址:可读短名与稳定身份同时成立
全局只靠 `# 李白` 寻址在大项目中不可行:同名、重命名和加载顺序都会让图不稳定。
但这不意味着作者要失去 `李白.出生年份` 的自然语言体验。
1. 文件的既有 frontmatter `id` 是稳定身份;
2. 现有 `import bind:target` 是代码中的规范加载/寻址;
3. `#` / `##` 是人可读的路径段;
4. 正文短地址由 catalog 发现,解析成功后写入 LinkInfo/lock 的稳定 `symbol_id`;歧义必须报错。
```markdown
---
id: knowledge.people.li-bai
import:
li_bai: knowledge/people/li-bai.mq.md
---
# 回答
**year = [李白的出生年份](li_bai.李白.出生年份)**
李白出生于[公元 701 年](李白.出生年份)。
```
第一处是可运行代码,使用显式 import;第二处是正文的发现地址。它们编译后都指向
`knowledge.people.li-bai::李白.出生年份`。短地址从来不是“按项目扫描第一个名字”,
而是可读的查询,必须由 lock 固化。
---
## 4. 每个 `[]()` 产生统一的知识记录
不要把 LinkInfo 固定成单一的 `target`。任意载荷都可能含有多个读、写、调用和循环依赖:
```json
{
"label": "逐个订单行",
"payload_kind": "loop",
"roles": ["iterate"],
"source": {"file": "capabilities/order-pricing.mq.md", "line": 22},
"inputs": ["订单.行"],
"outputs": ["行"],
"dependencies": [
{"kind": "local_value", "path": "订单.行"},
{"kind": "symbol", "id": "capability.order-pricing::订单定价.含税价"}
],
"effect": "pure",
"fingerprint": "sha256:…"
}
```
此记录就是统一知识图节点:
- 本地取元有输入/类型边;
- 纯计算有输入/输出/公式边;
- 循环有集合、变量绑定和循环体边;
- 调用有 `calls`/`uses` 边;
- 有来源的事实再增加 `derived_from` 边;
- 正文节点有 `narrates` 边,连接它所在句子和计算结果;
- 副作用节点有权限/影响目标边,不能被 `view` 或 `verify` 静默执行。
来源不是每个节点的前提,而是图中的一种边。没有来源的字典取元仍是知识步骤;
若它最终支撑对外事实,沿依赖链应能找到来源,否则在“发布/验证事实”时才报证据不足。
---
## 5. 闭环:写、跑、看、查、变
```text
作者写 Named<T>
│
├─ run:擦除 label,按原语义执行
├─ view:显示 label,可展开值、输入、步骤和来源
└─ check:解析所有依赖,编译统一知识图
│
catalog / lock / context pack
│
来源、规则、代码任一变化 ── impact / verify ──> 所有受影响 Named<T> 与叙述句子
│
作者或 agent 修复后重新 check/verify
```
### 5.1 命令边界
| 操作 | 做什么 | 不做什么 |
|---|---|---|
| `run` | 执行代码位置的原 payload | 不因为正文出现 `[]()` 而执行副作用 |
| `check` | 建图、解析类型/符号/依赖、检查 label 漂移 | 不求值、不伪造运行结果 |
| `view` | 呈现命名步骤及可选值/来源 | 静态模式不执行;live 模式遵守 effect 权限 |
| `verify` | 在沙箱中重算 pure 节点、核对来源/指纹 | 不执行 `act` 节点 |
| `impact` | 从变更节点反查依赖、函数、文档 span | 不按文本猜测关系 |
这样,任意通用代码一开始就属于知识图;只有在执行/验证权限上分级,而不是在语法上被分裂。
---
## 6. 实施顺序
1. 在表达式、遍历和正文三处统一保留 `Named<T>`;payload 复用各自现有 parser。
2. 为任意 `Named<T>` 提取 `inputs`、`outputs`、`dependencies`、`effect`、`roles`;从单 target 演进为依赖集合。
3. 让 `#`/`##` 契约为内部步骤提供类型/公开边界;让 frontmatter `id` + import 提供跨文件稳定解析。
4. 把现有 EKC 图扩展为步骤图:`observes`、`derives`、`iterates`、`calls`、`acts`、`narrates`、`derived_from`。
5. 接入 `check`、`view`、`verify`、`impact` 与 lock;让一次变更能回到具体的 `[]()` 和具体句子。
验收不是“能把一个类函数链接出来”,而是:**改一处表字段、来源、规则或函数,系统能列出受影响的
取元、循环、推导、调用和正文;其中每一步既可展开为代码,也可读成文档。**
+2 -1
View File
@@ -61,7 +61,8 @@ Unknown names fail. Queries are only valid during a plugin function call (host s
```markdown
---
import plugin:lib/plugin.mq.md
import:
plugin: lib/plugin.mq.md
---
# main
+6 -5
View File
@@ -159,11 +159,12 @@ REPLACE
```markdown
---
title: agent-run-…
import llm:ext/ai/llm.mq.md
import agent:ext/ai/agent.mq.md
import json:lib/json.mq.md
import writeback:lib/writeback.mq.md
import subtask:lib/subtask.mq.md
import:
llm: ext/ai/llm.mq.md
agent: ext/ai/agent.mq.md
json: lib/json.mq.md
writeback: lib/writeback.mq.md
subtask: lib/subtask.mq.md
---
# 总目标
+5 -4
View File
@@ -72,10 +72,11 @@ Marqdo 的宪法是 **代码即文档、文档即知识库**:
```markdown
---
导入 智能体:ext/ai/智能体.mq.md
导入 大模型:ext/ai/大模型.mq.md
导入 自写回:lib/自写回.mq.md
导入 时间:lib/时间.mq.md
导入:
智能体: ext/ai/智能体.mq.md
大模型: ext/ai/大模型.mq.md
自写回: lib/自写回.mq.md
时间: lib/时间.mq.md
---
## 获取时间
+2 -1
View File
@@ -197,7 +197,8 @@
````markdown
---
import la:ext/linalg/linalg.mq.md
import:
la: ext/linalg/linalg.mq.md
---
# 转置反序
+3 -2
View File
@@ -201,8 +201,9 @@ $$
````markdown
---
import la:ext/linalg/linalg.mq.md
import table:lib/table.mq.md
import:
la: ext/linalg/linalg.mq.md
table: lib/table.mq.md
---
# main
+2 -1
View File
@@ -20,7 +20,8 @@ Import:
```markdown
---
import llm:ext/ai/llm.mq.md
import:
llm: ext/ai/llm.mq.md
---
```
+4 -2
View File
@@ -101,7 +101,8 @@ marqdo ext add quantum
```markdown
---
import quantum:ext/quantum/quantum.mq.md
import:
quantum: ext/quantum/quantum.mq.md
---
```
@@ -341,7 +342,8 @@ Q5 教学噪声 + barrier/measure/append/state — 见 [ext-quantum-q5.md](ext-
```markdown
---
title: Bell state
import quantum:ext/quantum/quantum.mq.md
import:
quantum: ext/quantum/quantum.mq.md
---
# Bell |Φ+⟩
+7 -5
View File
@@ -62,8 +62,9 @@ route: /
method: GET
data_source: posts
data_order: -created_at
import web:ext/web/web.mq.md
import data:ext/data/db.mq.md
import:
web: ext/web/web.mq.md
data: ext/data/db.mq.md
---
# Marqdo
@@ -106,7 +107,8 @@ path: /api/posts
request: json
response: json
auth: member
import data:ext/data/db.mq.md
import:
data: ext/data/db.mq.md
---
**post = > data.db.insert …**
@@ -120,8 +122,8 @@ import data:ext/data/db.mq.md
| `path` | `路径` | URL |
| `method` | `方法` | GET/POST/… |
| `request` | `请求` | `json` / `form` / `none` |
| `response` | `响应` | `json` / `text` / `html` |
| `auth` | `鉴权` | 角色名或 `none` |
| `response` | `响应` | `json` / `text` / `html` / `sse`(`text/event-stream`) |
| `auth` | `鉴权` | 角色名或 `none`;`bearer` / `api_key` = 不要求 cookie,把 `Authorization` / `X-Api-Key` 注入 payload 由 `# main` 校验 |
正文在请求时执行;返回值按 `response` 序列化。Result 协议见 §8。
+2 -1
View File
@@ -49,7 +49,8 @@
英文:
```markdown
import web:ext/web/web.mq.md
import:
web: ext/web/web.mq.md
# main
+2 -1
View File
@@ -347,7 +347,8 @@ plugins/web/ # Go module(替换原 Rust crate)
scripts/build-web-plugin.sh # go build -buildmode=c-shared -o …/libweb.so
```
原 Rust 源码:`plugins/web-rust-archive/`(**已移出 Cargo workspace**;参考用,默认不构建)。
原 Rust 源码:曾置于 `plugins/web-rust-archive/`(已移出 Cargo workspace,参考用);
该目录已于 v1.6 精简时从工作树移除,历史保留在 git 中。
### 9.2 产物与解析
+16 -14
View File
@@ -128,13 +128,14 @@ myapp/
---
title: web-site
description: Home = page table; main may be inline; class methods assemble.
import web:ext/web/web.mq.md
import shell:styles/shell.mq.md
import nav:components/nav.mq.md
import side:components/side.mq.md
import foot:components/foot.mq.md
import articles:db/articles.mq.md
import db:db/index.mq.md
import:
web: ext/web/web.mq.md
shell: styles/shell.mq.md
nav: components/nav.mq.md
side: components/side.mq.md
foot: components/foot.mq.md
articles: db/articles.mq.md
db: db/index.mq.md
---
# main
@@ -171,13 +172,14 @@ Main content is not a reusable component, so it is authored here.
```markdown
---
title: 站点
导入 网页:ext/web/网页.mq.md
import shell:styles/shell.mq.md
import nav:components/nav.mq.md
import side:components/side.mq.md
import foot:components/foot.mq.md
import articles:db/articles.mq.md
import db:db/index.mq.md
导入:
网页: ext/web/网页.mq.md
shell: styles/shell.mq.md
nav: components/nav.mq.md
side: components/side.mq.md
foot: components/foot.mq.md
articles: db/articles.mq.md
db: db/index.mq.md
---
# main
+453
View File
@@ -0,0 +1,453 @@
# 外联内核(Foreign Kernel)
| | |
|---|---|
| 状态 | **F0–F3.5 已实现** |
| 日期 | 2026-10-17 |
| 层 | Runtime(`src/foreign/` · `src/host/foreign*` · `lib/foreign.mq.md`) |
| 相关 | [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [notebook-syntax.md](notebook-syntax.md) · [notebook-session.md](notebook-session.md) · [stdlib-foreign.md](stdlib-foreign.md) · [stdlib-subtask.md](stdlib-subtask.md) |
| 核心表面 Δ | 无 |
> 外联内核 = 一个长期存活的外部语言进程 + 生命周期 + 类型桥 + 记录。它既能被 `marqdo run` 里的显式调用使用,也能被 view 的 notebook 会话使用。
---
## 1. 定位与边界
### 1.1 负责
- 解释器发现、注册、配置、探测。
- 一次性执行:临时脚本、stdin/stdout/stderr、超时、输出上限。
- 持久内核:启动、求值、状态、关闭、列表。
- 状态桥:`session_set` / `session_get` / `session_names`。
- JSON 值桥:Marqdo `Value` ↔ JSON。
- 结构化记录:`ok/code/stdout/stderr/ms/timed_out/truncated/result/error`。
- 安全:`exec` 门禁、`cwd` 沙箱、进程组、并发/输出上限。
- 视图诊断:代码卡片 Run 的完整结果。
### 1.2 不负责
- 文档语法(`内核表` / `会话表`)→ [notebook-syntax.md](notebook-syntax.md)。
- 文档会话 / cell 顺序 / journal / view UI → [notebook-session.md](notebook-session.md)。
- Foreign → Marqdo 函数回调(v2 不做)。
- 依赖安装(pip/npm)。
- 远程 / 容器执行。
### 1.3 与相邻模块的区别
| 模块 | 生命周期 | 用途 |
|---|---|---|
| `foreign` | 一次性或持久 | 调外部语言;状态可选 |
| `subtask` | 一次性并发 | 后台任务、文件子任务、函数子任务 |
| `plugin` | 进程内 | 原生 C ABI 扩展 |
| `writeback` | 文档级 | 把输出写回 `.mq.md` |
`subtask` 不管理持久状态;`foreign` 不管理文档执行顺序。
---
## 1.4 实施状态(2026-10-17)
| 阶段 | 状态 | 关键文件 |
|---|---|---|
| F0 安全执行 / `invoke` 记录 | ✅ | `src/host/foreign.rs` |
| F1 预设 / probe / register / config | ✅ | `src/foreign/registry.rs` · `src/host/foreign.rs` |
| F2 JSON 桥 / run_many / call_many | ✅ | `src/host/foreign.rs` |
| F3 Python/Node 持久内核 | ✅ | `src/host/foreign_session.rs` |
| F3.5 session_set/get/names | ✅ | 同上 |
| F4 history / view 打磨 / 发布 | 部分 | — |
测试:`cargo test --lib foreign`(11+)、`cargo test --test gold lib_foreign`(12,python 条件跳过)、`tests/notebook/shared.mq.md` 手工 view 验证。
---
## 2. 语言与内核模型
### 2.1 语言预设
| lang | 别名 | 默认命令 | 扩展名 | 版本探测 | 会话 |
|---|---|---|---|---|---|
| `python` | `python3`, `py` | `python3`(Windows `python`) | `.py` | `--version` | ✅ |
| `node` | `javascript`, `js` | `node` | `.js` | `-v` | ✅ |
| `deno` | — | `deno run` | `.ts` | `--version` | ❌ |
| `bun` | — | `bun` | `.js` | `--version` | ❌ |
| `ruby` | — | `ruby` | `.rb` | `--version` | ❌ |
| `perl` | — | `perl` | `.pl` | `--version` | ❌ |
| `php` | — | `php -r {inline}` | `.php` | `--version` | ❌ |
| `lua` | — | `lua` | `.lua` | `-v` | ❌ |
| `r` | `rscript` | `Rscript` | `.R` | `--version` | ❌ |
| `julia` | — | `julia` | `.jl` | `--version` | ❌ |
| `go` | — | `go run {file}` | `.go` | `version` | ❌ |
| `bash` | `sh`, `shell` | `bash` | `.sh` | `--version` | ❌ |
| `powershell` | `pwsh`, `ps1` | `pwsh`(Windows `powershell`) | `.ps1` | `--version` | ❌ |
| `sqlite` | `sqlite3` | `sqlite3` | `.sql` | `--version` | ❌ |
| `tsx` | `typescript` | `tsx` | `.ts` | `--version` | ❌ |
说明:
- 预设只是默认值;注册 / 配置 / 环境变量整体覆盖。
- 会话能力首批只有 Python / Node;其它语言一次性执行。
- `php` 用 `{inline}`,围栏里直接写 PHP,不需要 `<?php`。
- `deno` 默认不给权限;需要时通过配置追加 `--allow-*`。
### 2.2 解析优先级
从高到低:
1. 调用级 `cmd`(整行 argv,shell-like 切分)+ `args`(追加)。
2. 进程内注册:`register` / `set_cmd`。
3. 环境变量 `MARQDO_FOREIGN_<LANG>`(整行或 JSON 数组)。
4. 项目配置 `.marqdo/foreign.toml` / `MARQDO_FOREIGN_CONFIG`。
5. 内置预设。
6. 都没有 → 带修复建议的诊断。
Python 额外发现顺序(在预设层内):
1. `VIRTUAL_ENV/bin/python`(Windows `Scripts/python.exe`);
2. `<cwd>/.venv` / `venv` / `env`;
3. 入口目录与 `fs_root` 向上查找;
4. PATH 的 `python3` / `python`。
`MARQDO_FOREIGN_NO_VENV=1` 关闭 venv 探测;显式 `cmd` / `set_cmd` / `MARQDO_FOREIGN_PYTHON` 优先。
相对路径:配置里的 `cmd` 相对配置目录;注册 / `set_cmd` / 环境变量里的 `cmd` 相对 `cwd`。
### 2.3 注册与模板
`register(lang, cmd?, args?, template?, ext?, env?, version_args?)`。
模板占位符:
| 占位符 | 展开 |
|---|---|
| `{file}` | 临时脚本绝对路径 |
| `{dir}` | 临时目录 |
| `{base}` | 脚本文件名 |
| `{inline}` | 源码作为一个 argv;不写临时文件 |
| `{lang}` | 语言 id |
| `{cwd}` | 实际工作目录 |
规则:
- `cmd` 与 `template` 至少一个;都给 → 报错。
- `{file}` 与 `{inline}` 不能同时出现。
- 都没有时自动追加 `{file}`。
- `{inline}` 超过 60 KiB → 报错并建议 `{file}`。
- 模板不做 shell 转义;需要 shell 时显式写 `bash -c`,路径由引擎生成(安全字符)。
配置示例:
```toml
[python]
cmd = ".venv/bin/python"
args = ["-u"]
[go]
template = ["go", "run", "{file}"]
[rust]
template = ["bash", "-c", "rustc -O {file} -o {dir}/main && {dir}/main"]
[php]
template = ["php", "-r", "{inline}"]
```
---
## 3. 一次性执行
### 3.1 API
| 英文 | 中文 | 形参 | 结果 |
|---|---|---|---|
| `run` | `运行` | `code`, 可选 `stdin` `env` `cwd` `timeout` `args` `max_output` | stdout 文本(v1 兼容) |
| `run_lang` | `按语言运行` | `lang`, `source`, 可选同上 | stdout 文本 |
| `invoke` | `执行` | 可选 `code` / `lang`+`source` / `stdin` / `input` / `env` / `cwd` / `timeout` / `args` / `output` / `max_output` / `cmd` / `keep` / `cache` | 记录 map |
| `call` | `调用` | 可选 `code` / `lang`+`source` / `input` / `stdin` / `env` / `cwd` / `timeout` / `args` | 解析后的 JSON 值 |
| `run_many` | `批量运行` | `runs`, 可选 `concurrency` | 记录列表 |
| `call_many` | `批量调用` | `inputs`, 可选 `code` / `lang`+`source` / `cmd` / `env` / `cwd` / `timeout` / `args` / `max_output` / `concurrency` | 结果值列表 |
### 3.2 记录结构
`invoke` / `run_many` / `session_eval` 共用:
| 键 | 类型 | 含义 |
|---|---|---|
| `ok` | Bool | exit=0 且未超时 |
| `code` | Int | 退出码;未启动 / kill → -1 |
| `stdout` | Text | 原始 stdout(可能截断) |
| `stderr` | Text | 原始 stderr(可能截断) |
| `ms` | Int | 墙钟毫秒 |
| `lang` | Text | 实际语言 |
| `cmd` | Text | 实际 argv |
| `timed_out` | Bool | 是否超时 |
| `truncated` | Bool | stdout/stderr 是否截断 |
| `result` | 任意 / None | 按 `output` 解析 |
| `result_error` | Text | json 解析失败原因 |
| `error` | Text | 启动 / 超时 / 策略原因 |
| `script` | Text | `keep=True` 的脚本路径 |
| `cached` | Bool | 缓存命中(P4) |
`session_eval` 额外:`id`、`alive`。
### 3.3 输出模式
| `output=` | `result` |
|---|---|
| `auto`(默认) | 尝试 JSON;失败 → None |
| `text` | None |
| `json` | 解析;失败 → `result_error` |
| `lines` | 行列表 |
| `bytes` | stdout 原始字节的 base64 |
`call` 固定 JSON:空 stdout → None;非空非法 JSON → 错误。
### 3.4 失败语义
- `run` / `call`:执行失败 → `Err`;错误包含语言、argv、退出码、stderr(截 4 KiB)、stdout 头。
- `invoke` / `run_many`:执行失败 → 记录;只有参数非法 / 策略拒绝 → `Err`。
- 输出过大:截断 + `truncated=true`,不再 OOM / 报错。
---
## 4. JSON 状态桥
### 4.1 值映射
Canonical integer contract: [`v-safe-json.md`](v-safe-json.md) (Lean \(V_{\mathsf{safe}}\): `|n| ≤ 2^{53}-1`).
| Marqdo | JSON |
|---|---|
| None | null |
| Bool | bool |
| Int | number **仅当** `|n| ≤ 2^{53}-1`;越界 → 显式失败(禁止静默扭曲) |
| Num | number(NaN/Inf → null);float 为宿主扩展,∉ mechanized \(V_{\mathsf{safe}}\) |
| Text | string(宽整数用十进制字符串过桥,对端 `BigInt` / Python `int`) |
| List | array(子树递归;任一越界整数使整体失败) |
| Map | object(同上) |
| Formula | 矩阵 → 二维数组;其它 → 数字或字符串 |
| Code | 源码字符串 |
| Secret | JSON 中 `<secret>`;`env` 显式交付时取真实值 |
错误前缀:`json: integer outside V_safe (±(2^53-1)): <n>`。
### 4.2 输入
- `input=` → JSON;写 stdin;同时提供 `MARQDO_INPUT`(≤8 KiB)与 `MARQDO_INPUT_FILE`(任意大小)。
- `stdin=` 文本与 `input=` 互斥。
- 都不给 → stdin EOF。
- 大输入走文件,避免环境变量大小限制。
### 4.3 输出
- `result` 按 `output` 解析。
- 原始 stdout/stderr 始终保留(截断到上限)。
- `call` 返回解析值;`invoke` 返回记录。
### 4.4 类型限制
v2 是**值拷贝**,不是对象引用:
- Python DataFrame / NumPy / Node 对象 → 需要先 `to_dict` / `to_json` / `JSON.stringify`。
- 大对象传输成本高;后续考虑 Arrow / Parquet / 文件句柄。
- Secret 不默认进入 JSON;需要 env 显式交付。
---
## 5. 持久内核与会话
### 5.1 API
| 英文 | 中文 | 形参 | 结果 |
|---|---|---|---|
| `session_open` | `会话开启` | `lang`, 可选 `cmd` `env` `cwd` `timeout` | 会话 id(Text) |
| `session_eval` | `会话求值` | `id`, 可选 `code` / `source` / `input` / `timeout` | 记录(含 id/alive) |
| `session_set` | `会话设值` | `id`, `name`, `value` | None |
| `session_get` | `会话取值` | `id`, `name` | JSON 值 / None |
| `session_names` | `会话变量` | `id` | 名称列表 |
| `session_close` | `会话关闭` | `id` | Bool |
| `session_list` | `会话表` | — | map 列表 |
### 5.2 支持语言
| 语言 | 方式 |
|---|---|
| python | `python3 -u -c <bootstrap>` |
| node | `node -e <bootstrap>` |
| 其它 | 报错:`lang=… has no session bootstrap; use run/invoke` |
### 5.3 线路协议
stdin 每行一个 JSON 请求;原始 stdout 每行一个 JSON 响应:
```json
{"id":1,"code":"x = 41","input":null}
{"id":2,"code":"x + 1","input":null}
```
```json
{"id":1,"ok":true,"stdout":"","stderr":"","result":null,"error":""}
{"id":2,"ok":true,"stdout":"","stderr":"","result":42,"error":""}
```
- 同一会话严格串行:等到匹配响应后才发下一条。
- 响应单行;JSON 转义换行。
- 崩溃 / EOF → `alive=false`,会话移除。
- 超时 → kill 会话(状态不可信)。
### 5.4 Python bootstrap
- 保留原始 `sys.stdout` 写协议;用户输出用 `redirect_stdout/stderr` 捕获。
- `ast.parse`:最后一条是表达式 → 先 exec 前面,再 eval 最后,作为 result。
- 异常 → `traceback.format_exc(limit=8)`,`ok=false`;会话继续。
- `input` → 全局 `marqdo_input`。
- 不可序列化 → `default=str`。
### 5.5 Node bootstrap
- 保存原始 `process.stdout.write` 写协议。
- eval 期间替换 `console.*` 与 `process.stdout/stderr.write`;结束后恢复。
- `vm.runInThisContext` 保留全局状态;`require` 挂到 `globalThis`。
- Promise → await;顶层 await 需用户包 `(async()=>{…})()`。
- 序列化失败 → `String(result)`。
### 5.6 状态桥
- `session_set`:值 → JSON → 请求 `{"set": name, "value": ...}` 或执行一段赋值。
- `session_get`:请求 `{"get": name}` → JSON → Marqdo Value。
- `session_names`:请求变量名列表。
- 与 `session_eval` 同一线路协议;严格串行。
- 名称必须是合法标识符;保留名(`marqdo_input` 等)另行文档。
### 5.7 生命周期
- id 为 `s1`、`s2`…。
- 每会话独立进程、cwd、env。
- `HostContext` drop → 全部 kill + wait。
- `subtask` 不继承会话。
- 不跨文档共享。
---
## 6. 环境契约
| 变量 | 值 |
|---|---|
| `MARQDO_FOREIGN` | `1` |
| `MARQDO_FOREIGN_LANG` | 语言 id |
| `MARQDO_FOREIGN_SCRIPT` | 脚本路径(文件模式) |
| `MARQDO_FOREIGN_DIR` | 脚本目录 |
| `MARQDO_FOREIGN_CWD` | 实际 cwd |
| `MARQDO_ENTRY` | 入口 `.mq.md` 路径 |
| `MARQDO_ENTRY_DIR` | 入口目录 |
| `MARQDO_INPUT` | input JSON(≤8 KiB) |
| `MARQDO_INPUT_FILE` | input JSON 文件(任意大小) |
语言默认:
- Python:`PYTHONUNBUFFERED=1`、`PYTHONIOENCODING=utf-8`、`PYTHONUTF8=1`;`PYTHONPATH` 前插 cwd。
- Node:`NODE_PATH` 前插 cwd(可选)。
`env` 是 map;值 `as_display()`;Secret 取真实值(显式交付)。不主动清空父环境。
---
## 7. 临时文件与 cwd
- 默认 `<cwd>/.marqdo/tmp/foreign-<pid>-<nanos>/`;不可写 → 系统临时目录。
- `MARQDO_FOREIGN_TMPDIR` 覆盖。
- 脚本 `main.<ext>`;Python 加 utf-8 声明。
- 默认 cwd = 入口目录;调用级 cwd 经 `resolve_path` + `fs_root` 校验。
- 成功/失败/超时都清理;`keep=True` 保留并回填 `script`。
- Node 相对 `require('./x')` 相对脚本目录;需要项目相对路径时用 `MARQDO_FOREIGN_CWD` 或 `{inline}` 模板。
---
## 8. 超时、IO、进程组
- `timeout`:秒,可小数;默认 10s;上限 3600s;`<=0` 报错。
- 超时 kill 进程组:
- Unix:`process_group(0)` + `kill(-pid, SIGKILL)`;
- Windows:`taskkill /PID <pid> /T /F`。
- `max_output`:每流默认 1 MiB;范围 1 KiB–64 MiB;保留前 N 字节,余下丢弃并继续排空;`truncated=true`。
- stdin 独立写线程,避免双向管道死锁;EPIPE 忽略。
- stdout/stderr 两个读线程;UTF-8 lossy。
- 记录原始字节(至上限)以支持 `bytes` 输出。
---
## 9. 安全
| 项 | 策略 |
|---|---|
| 能力门禁 | `run` / `invoke` / `probe` / `session_*` 全部检查 `allow_exec()`;沙箱 → 拒绝 |
| shell | 默认不经 shell;模板显式 `bash -c` 才走 |
| cwd | `resolve_path` + `fs_root`;越界拒绝 |
| 输出 | 有界读取 + 丢弃式排空 |
| 时间 | 上限 + 进程组 kill |
| 并发 | 默认 4,上限 32 |
| 会话 | 每文档独立;关闭/drop 清理;超时即杀 |
| Secret | JSON 不默认暴露;env 显式;面板打码 |
| wasm | `exec-host` 关闭时全部返回清晰错误;`langs` 返回 [] |
---
## 10. 兼容性
- `run` / `run_lang` / `set_cmd` / `langs` 既有调用可用。
- `run` 成功仍返回 stdout(去一个尾换行);非 0 仍报错。
- `set_cmd` 增加可选 `args`。
- `langs` 扩展为「预设 ∪ 注册 ∪ 配置」;原集合是子集。
- `subtask` 的 `spawn code=` / `lang=` 仍返回 stdout 文本。
- HostFn id 只追加;字节码参数 < 255。
- 无核心表面 Δ。
---
## 11. 测试矩阵
| 测试 | 依赖 | 断言 |
|---|---|---|
| 既有 `foreign-python` / `run-lang` / `外联-python` | python | 兼容 |
| `foreign-invoke` | node | ok/code/stdout/stderr/ms |
| `foreign-env-cwd` | node | env/cwd/MARQDO_* |
| `foreign-timeout` | node | timed_out, 无遗留进程 |
| `foreign-call-json` | node | 嵌套 list/map 往返 |
| `foreign-call-many` / `run-many` | node | 顺序/隔离/并发 |
| `foreign-session` | node(python 可选) | 跨 eval 状态、异常不杀 |
| `foreign-session-set-get` | node | 变量推拉 |
| `foreign-session-timeout` | node | alive=false |
| `foreign-probe` | node | path/version/ok |
| `foreign-register` | node | 模板 `{inline}` |
| `foreign-config` | node | `MARQDO_FOREIGN_CONFIG` |
| `foreign-caps` | 无 | exec=false 拒绝 |
| 单元测试 | 无 | shell 切分/模板/别名/JSON |
当前环境无 Python:node + bash 为主;python 条件跳过;Windows 用 `python_available()` / `bash_available()` 守卫。
---
## 12. 实现落点
| 文件 | 内容 |
|---|---|
| `src/foreign/registry.rs` | 预设/别名/模板/venv/PATH/配置/shell 切分(纯逻辑) |
| `src/host/foreign.rs` | Job/Execution/ForeignEnv;run/invoke/call/run_many/call_many;probe/register/unset/langs/load_config |
| `src/host/foreign_session.rs` | Python/Node bootstrap;会话生命周期;set/get/names |
| `src/host/dispatch.rs` | HostFn 追加 |
| `src/aliases.rs` | 参数别名 |
| `lib/foreign.mq.md` / `lib/外联.mq.md` | L1 API + 文档 |
| `src/view/mod.rs` / `html.rs` / `debug_page.rs` | Run 诊断;后续接文档会话 |
| `tests/gold.rs` / `tests/lib/foreign-*.mq.md` | 测试 |
---
## 13. 明确不做
- Foreign line-level step。
- Foreign → Marqdo 函数 callback。
- 自动镜像变量。
- 跨语言共享对象引用。
- 全进程快照。
- 自动安装依赖。
- 浏览器 wasm 外联。
@@ -0,0 +1,23 @@
# Foreign Strong: Lean ↔ host correspondence
Pinned with PLDI Strong narrative (`FOREIGN-NARRATIVE-ASSESSMENT-2026-11-01.md`).
**Not** verified compilation — conformance evidence only.
| Lean / paper rule | Host surface | Evidence |
|---|---|---|
| `SessionReg` + `sessionOpen` / `Close` / `sessionEval` | `HostContext.foreign_sessions` + `Value::Handle` | `DocCalc.lean`; `foreign_session.rs` |
| `Ω(s, τ, c)` | Persistent kernel + process order | Oracle journal records `(cell, source_hash, stdout, result)` |
| `SafeVal` / Encode / Decode | `src/host/json.rs` + session bootstrap sanitize | `ForeignJSON.lean`; `v-safe-json.md`; gold `foreign-*-vsafe-*` |
| Handle ∉ \(V_{\mathsf{safe}}\) | `value_to_json(Handle) → Err` | `foreign-session-handle-no-serialize.mq.md` |
| Closed / Closed-Close | use-after-close / double-close `Err` | gold misuse suite |
| Oracle-Domain | Ω OOD integer → host `Err` | `foreign-session-result-vsafe-refuse.mq.md` |
| Table arity stuck | Parse refuse unequal GFM row width; JSON refuse unequal column lists | `Surface.lean` `table_arity_*`; `tests/errors/table-arity.mq.md` |
| Snapshot hash match/mismatch | `view/output.rs` `snapshot_page` | unit `snapshot_page_rejects_source_hash_mismatch` |
| `replay_check` vs journal \(J\) | `DocumentSession::replay_check` | unit + `defense/fate_matrix/run_replay_pack.py` |
| Dual-backend differential | `tests/gold.rs` tree + bytecode | 308 tests × 2; foreign subset includes session/V_safe |
## Intentional non-claims
- No static affine/linear session types (host death unsound).
- Floats are host extension outside Lean `SafeVal`.
- `replay_check` is host/document-session API, not a second interpreter backend.
+654
View File
@@ -0,0 +1,654 @@
# 外联运行时 v3 — 能力缺口与深化设计(Proposed)
| | |
|---|---|
| 状态 | **Proposed;尚未实现** |
| 日期 | 2026-10-18 |
| 层 | Runtime(foreign)· Document(`foreign.session`)· View(投影) |
| 相关 | [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [foreign-v2.md](../roadmap/foreign-v2.md) · [stdlib-writeback.md](stdlib-writeback.md) · [view-static-interactive.md](view-static-interactive.md) |
| 核心表面 Δ | **无增删**:不新增 Markdown 标记、不新增 notebook CLI |
> 本文只定义设计,不承诺已实现。当前基线是 v1.5.0 之后的本地工作:`foreign.session` 句柄、多内核、values 初始化、view 控制、静态执行与显式 writeback 已可用;本文处理仍然缺失的能力。
---
## 1. 设计约束
v3 必须继续满足以下约束,否则不进入实现:
1. **外联库拥有内核与状态**:`foreign` 管理内核、会话、cell 计划、输入、输出、journal 和生命周期。`view` 只消费句柄,不拥有第二套运行时。
2. **表与围栏是值**:`内核表`、`单元表`、`输入表`、`值表` 都是普通 Marqdo 值;没有保留表名,没有新增标记。
3. **单一执行语义**:`run` 是规范执行;`view` 是同一文档的交互投影;静态导出是同一会话的快照,不另写解释器。
4. **没有 Notebook 模式**:没有 `marqdo notebook`,没有 `In/Out`,没有“普通 view / notebook view”两套布局。
5. **显式 I/O**:Marqdo 值通过 `values` / `session_set` 传递;程序 stdin 是单独概念,不能伪装成 `marqdo_input`。
6. **显式持久化**:默认不改源码;writeback 必须由文档显式调用,或由用户显式选择策略。
7. **安全默认值**:执行受 capability 控制;输入/输出有界;不反序列化任意对象;跨文档共享必须显式开启。
---
## 2. 基线:现在已经有什么
| 能力 | 状态 |
|---|---|
| `foreign.run` / `run_lang` / `invoke` / `probe` | 已实现 |
| `foreign.call` / `call_many` / JSON 进出 / 并行 | 已实现 |
| `session_open` / `eval` / `set` / `get` / `names` / `close` / `list` | 已实现 |
| `foreign.session kernels= cells= values=` | 已实现 |
| 多内核 view 会话、cell 顺序、内核归属 | 已实现 |
| Marqdo 表通过 `values` 传入多个内核 | 已实现 |
| 无 `会话` 时无状态 cells | 已实现 |
| view 每 cell 内核选择 / Clean / Run | 已实现 |
| 静态导出执行 cells 并嵌入真实输出 | 已实现 |
| 静态页 session summary、内核归属、多内核展示 | 已实现 |
| 显式 `writeback.record` | 已实现(库能力) |
| 静态页按钮的“不可执行”提示 | 已实现 |
---
## 2.1 实施状态(2026-10-18)
| ID | 状态 | 备注 |
|---|---|---|
| G1/G2 | ✅ 已实现 | session eval raw stdin;`foreign.session inputs=`;per-cell UI;Python/Node 测试 |
| G5 | ✅ 基本实现 | `session_interrupt` + view Interrupt;Python SIGINT 保留会话;Node 进程可能被终止 |
| G4 | ✅ 已实现(API) | add/remove/set-value + generation;view 尚未提供 add/remove UI |
| G6 | ✅ 已实现(API) | export/import/replay JSON snapshot;view/CLI 尚未做文件封装 |
| G9 | ✅ 已实现(CLI/API 基础) | `view capture` + `view output --snapshot`;source hash 校验 |
| G3 | ✅ 边界已实现 | 顶层 plan;嵌套 plan 诊断 |
| G10 | ✅ 显式 persist | `/api/session/cell/persist` + view Persist;不自动写源码 |
| G7/G8 | 📌 已移出当前目标 | 设计保留,后续版本再开发 |
## 3. 缺口清单
| ID | 缺口 | 优先级 | 当前行为 | 目标 |
|---|---|---|---|---|
| G1 | 持久内核 raw stdin | P0 | 持久内核只有 `marqdo_input` | 程序 stdin 与控制协议分离 |
| G2 | 每 cell 独立 stdin | P0 | 页面级 Cell stdin,Run All 共用一个输入 | cell 级输入表 + UI |
| G3 | 动态 plan | P2 | 只读顶层 `会话` | 明确边界,或受控动态 |
| G4 | 运行时更新 plan | P1 | values 只在打开时初始化 | 显式 session 变更 API |
| G5 | kernel interrupt | P0 | 只能等超时/杀进程组 | 可中断当前 eval |
| G6 | 状态持久化 / replay | P1 | journal/dirty 只在内存 | 导出/恢复/replay |
| G7 | 跨文档内核 | P2 | 每文档独立 | 显式 scope/空间 |
| G8 | 非 Python/Node 持久内核 | P3 | Go 等一次性执行 | LangSpec 会话适配器 |
| G9 | live → static 输入捕获 | P0 | 静态构建不捕获临时 stdin | 显式 snapshot 捕获 |
| G10 | 自动 writeback | P2 | 必须显式调用 | 显式策略下的“运行后写回” |
---
## 4. 统一模型
### 4.1 会话句柄
`foreign.session` 返回的句柄是一个普通 Marqdo 值,建议稳定形状:
```text
{
kind: "foreign-session",
id: "<session-id>",
document: "<entry-source-hash>",
status: "created | ready | running | interrupted | dirty | closed",
kernels: [...],
cells: [...],
inputs: [...],
values: [...],
generation: 1
}
```
`view` 只读这些字段;任何执行操作都通过 `foreign` 的 host API。句柄不是第二套运行时。
### 4.2 三种输入
必须严格区分:
| 输入 | 目标 | 形态 | 当前 |
|---|---|---|---|
| `values` | 内核变量 | Marqdo 值 → JSON copy | 已实现 |
| `input` | `marqdo_input` | JSON 值 | 已实现(低层) |
| `stdin` | 程序 stdin | 原始文本/字节 | 仅无状态 cell 有 |
v3 不允许把 raw stdin 偷偷塞进 `marqdo_input`;两者语义不同。
### 4.3 每 cell 输入表
不新增标记,仍然使用普通表:
```mq.md
`单元输入` =
| 单元 | stdin | input |
|------|-------|-------|
| 计算 | hello | {rate: 0.08} |
| 复核 | | {check: true} |
```
`foreign.session` 增加可选参数:
```text
foreign.session kernels=... cells=... values=... inputs=`单元输入`
```
规则:
- `stdin` 只给该 cell 的程序 stdin;
- `input` 只给该 cell 的 `marqdo_input`;
- 空值表示不提供;
- 输入大小有上限,超限显式报错;
- 静态导出使用同一张表,因此 view 与静态快照可以一致。
### 4.4 执行流水线
```text
evaluate 会话 handle
→ open kernels
→ apply values
→ apply cell inputs
→ run cell
→ record {stdout, stderr, input_echo, result}
→ next cell
```
失败不终止整个 Run All;错误写入 cell record,journal 保留。
---
## 5. G1/G2:持久内核 stdin 与每 cell 输入
### 5.1 问题
当前持久内核的 worker 用 stdin 传输 JSON 控制协议,因此程序自己的 stdin 不可用;`marqdo_input` 只是 JSON 变量,不是 stdin。
### 5.2 方案 A(推荐):控制通道与程序 stdin 分离
- Unix:父进程创建 **socketpair**(或两个 pipe),worker 通过 fd 3/4 读写控制帧;程序 stdin 使用单独的 pipe。
- Windows:named pipe 或可继承的匿名 pipe 作为控制通道;程序 stdin 单独 pipe。
- worker 协议升级为 `protocol: 2`:
- 控制帧:`eval` / `set` / `get` / `interrupt` / `close`
- eval 帧可带 `stdin`(UTF-8)或 `stdin_b64`(二进制,后续)
- Python worker:每次 eval 前把 `sys.stdin` 替换为 `io.TextIOWrapper`/`StringIO`,eval 后恢复控制通道;用户代码读到的是真正的 stdin。
- Node worker:控制 readline 移到控制 pipe;每次 eval 把 `process.stdin` 替换为 `PassThrough`/`Readable`,eval 后恢复。
- 超时/中断关闭该次 stdin,不污染下一次 eval。
### 5.3 方案 B(降级):只支持 `input`
如果控制通道暂不实现,持久内核只支持 `input`,并显式拒绝 raw stdin:
```text
persistent kernel stdin is unavailable; use input= or stateless cells
```
不能静默把 stdin 变成 `marqdo_input`。
### 5.4 方案 C:stdin cell 降级为一次性
持久会话中遇到 raw stdin 时,用一次性进程执行该 cell;明确标记 `state: none`,不假装内核态连续。
### 5.5 UI 与静态
- `view`:每个代码卡提供 **Cell stdin** 小输入框,或者页面级输入表;推荐每 cell,因为它们经常不同。
- 静态:读取 `inputs` 表;没有输入时显示“requires stdin”说明,而不是 traceback。
- Run All 使用每 cell 的输入;不再把一个页面级 stdin 复制给所有 cell。
### 5.6 验收
- Python 与 Node 持久内核都能读取真实 stdin;
- 同一个 cell 连续 eval 不串输入;
- 超时/中断后下一次 eval 仍可读 stdin;
- 无状态 cell 行为不变;
- 静态快照使用相同输入表,结果与 live 一致(在相同输入下)。
---
## 6. G3:动态 plan 的边界
### 6.1 问题
`foreign.session` 目前只识别 entry 顶层的 `会话` 绑定。分支、函数、运行时循环中定义的 plan 不会被 view 发现。
### 6.2 设计决定(建议)
**v3 不支持任意控制流中的 plan。** 这是有意的语义边界:
- plan 是文档的声明,不是程序运行时的副作用;
- view 不应为了找 plan 而执行 `# main`;
- 避免 view 再次长出一套“运行程序再猜计划”的隐式逻辑。
允许的动态形式:
- 顶层赋值右侧的纯表达式,包括引入的纯函数;
- `foreign.session` 的 tables/values 可以由顶层表函数计算;
- 运行时变化通过 G4 的显式 session API 完成。
**不支持**:
- `##` 函数内部的 plan;
- `if`/`while` 分支里的 plan;
- 依赖 `# main` 副作用才能得到的 plan。
### 6.3 诊断
如果源码中出现非顶层 `foreign.session`,给出:
```text
foreign.session: plan must be a top-level binding (会话 = > foreign.session ...)
```
而不是静默降级为无状态。
---
## 7. G4:运行时更新 plan
### 7.1 目标
已打开的 view session 允许用户显式修改 cell 归属、增加/移除 cell、更新内核变量;所有修改都要可追踪。
### 7.2 API
```text
foreign.session_assign session=<handle> cell="计算" kernel="复核"
foreign.session_add_cell session=<handle> cell="新单元" kernel="分析"
foreign.session_remove_cell session=<handle> cell="旧单元"
foreign.session_set_value session=<handle> kernel="分析" name="rate" value=0.08
```
所有操作:
- 校验 cell/kernel 语言;
- 递增 `generation`;
- 写入 journal(kind=plan_change / value_change);
- 标记受影响 cell 为 `dirty`;
- 失败不改变 handle。
### 7.3 View
- 内核下拉复用 `session_assign`;
- 增加/删除 cell 放在显式菜单,不做隐式拖拽写入源码;
- UI 显示 generation / dirty 状态。
### 7.4 静态
静态快照不执行变更;它记录变更后的 plan,或在构建时执行一次并固化。
---
## 8. G5:kernel interrupt
### 8.1 API
```text
foreign.session_interrupt id=<session-id>
```
### 8.2 行为
- 控制通道发送 `interrupt`;
- worker 取消当前 eval,返回 `{ok:false, interrupted:true}`;
- 保留已完成的值和 journal;
- 状态从 `running` → `interrupted`;
- 下一次 eval 可以继续使用内核(除非进程已损坏);
- 超时继续作为最后一道防线。
### 8.3 View
- 工具栏增加 Interrupt;执行中的 cell 显示 interrupted;
- 不自动重跑;
- 静态导出没有 interrupt(快照不执行)。
### 8.4 跨平台
Unix:进程组信号 + 控制帧;Windows:控制帧 + `taskkill /T` fallback。两者都必须有测试。
---
## 9. G6:状态持久化与 replay
### 9.1 不做的事
- 不做 Python pickle / Node 堆快照;
- 不做任意对象反序列化;
- 不把内核内存默认写进 `.mq.md`。
### 9.2 显式快照
```text
foreign.session_export session=<handle> path=".marqdo/sessions/doc-1.json"
foreign.session_import path=".marqdo/sessions/doc-1.json"
```
快照只包含:
```text
{
version: 1,
document_hash: "...",
plan_hash: "...",
kernels: [{name, lang, cmd, values: {...}}],
cells: [{name, kernel, status, last_ok, last_error}],
journal: [...],
inputs: [...]
}
```
值只允许 JSON 可表达的 Marqdo 值;不可序列化的值显式失败。
### 9.3 replay
```text
foreign.session_replay path="..." verify=True
```
按 journal 顺序重放 cell + inputs,比较 stdout/status;差异写入 report。replay 不覆盖原 journal,除非显式 `append`。
### 9.4 存储
- 默认目录 `.marqdo/sessions/`(gitignore 可选);
- 用户可通过 path 放到受控目录;
- 不默认提交,不默认写源码。
---
## 10. G7:跨文档内核(Deferred / future)
> **状态:已移出 v3 当前实现目标。** 本节设计保留,作为后续版本(v4 或独立 session-scope 工作)的输入;当前不承诺 API 或兼容性。
### 10.1 原则
- 默认每文档独立;
- 跨文档必须显式 `scope=` / `space=`;
- 不自动按变量名或路径共享。
### 10.2 API
```text
foreign.session_open lang="python" scope="shared:analytics"
foreign.session_list scope="shared:analytics"
foreign.session_close id=... scope=...
```
- scope 注册表由 foreign runtime 管理;
- 同名冲突报错,不覆盖;
- view 只能打开当前文档声明允许的 scope;
- 生命周期由 owner/refcount 管理,最后一个引用关闭时清理。
### 10.3 安全
- 跨文档共享可能违反文档隔离,必须 capability + 显式配置;
- journal 标记 scope;
- 静态导出默认不打开跨文档 scope。
---
## 11. G8:非 Python/Node 持久内核(Deferred / future)
> **状态:已移出 v3 当前实现目标。** 本节设计保留,等待目标语言与 worker 适配器确定后再实现;当前不承诺 API。
### 11.1 模型
不是所有语言都需要持久内核。`LangSpec` 增加能力标志:
```text
session: none | protocol_v2
```
- `none`:只能 `run` / `invoke` 一次性;
- `protocol_v2`:实现控制通道与 eval 协议,可以 `session_open`。
### 11.2 适配器
Go 等语言通过一个薄 worker 实现:
```text
control frame: eval {code, stdin, input}
result frame: {ok, stdout, stderr, result, error}
```
不允许“看起来像持久内核、实际每次重启”的假实现。
### 11.3 失败语义
- `session_open` 对 `session: none` 的语言明确报错;
- `foreign.session` 的 plan 只能使用支持 session 的语言;
- 静态/无状态仍可使用一次性执行。
---
## 12. G9:live → static 输入捕获
### 12.1 问题
静态构建在构建环境执行,无法知道用户在 live view 中临时输入的 stdin;同一文档的结果可能不同。
### 12.2 设计
增加显式的“捕获快照”:
```text
view → Capture snapshot → .marqdo/snapshots/<doc>.view.json
```
快照内容:
- document source hash;
- session plan(kernels/cells/values);
- 每 cell 的 stdin/input;
- 每 cell 的 stdout/stderr/status;
- journal 摘要、语言/解释器版本;
- 捕获时间。
静态导出:
```text
marqdo view output --snapshot .marqdo/snapshots/doc.view.json
```
优先使用快照中的记录,校验 source hash,不重新执行;若 hash 不匹配,显式失败或 `--execute` 重跑。
### 12.3 安全/隐私
- 快照可能包含 secrets;默认不提交、不发布;
- 提供 `redact` 字段/正则;
- 静态页面只发布脱敏后的快照。
### 12.4 验收
- live 中成功的结果可以在静态页面原样显示;
- 不捕获内核内存,只捕获输入/输出/状态;
- 没有快照时回退到构建时执行,行为明确。
---
## 13. G10:自动 writeback
### 13.1 原则
**“自动”必须是用户显式选择的策略,不是默认副作用。**
### 13.2 API
```text
foreign.session persist=`写回策略`
```
策略表:
```mq.md
`写回策略` =
| 单元 | key |
|------|-----|
| 计算 | total |
| 复核 | check |
```
或 view 的 **Persist results** 按钮:将当前 cell 结果写到 `writeback.record key=...`。
### 13.3 语义
- 默认不写源码;
- 显式策略只在 **用户点击 Persist** 或 `marqdo run --writeback` 时执行;
- 静态构建默认不写回;`--writeback` 必须显式;
- writeback 只支持 JSON 可表达值;
- 写入位置/格式仍由 `writeback` 库决定。
### 13.4 与静态快照的关系
- 静态快照是只读发布;
- writeback 是源码内的活结果;
- 两者可以共存,但不能互相隐式触发。
---
## 14. API / 端点汇总
### 14.1 新增 foreign 函数
```text
foreign.session inputs=
foreign.session_assign
foreign.session_add_cell
foreign.session_remove_cell
foreign.session_set_value
foreign.session_interrupt
foreign.session_export
foreign.session_import
foreign.session_replay
foreign.session_open scope=
foreign.session_list scope=
```
### 14.2 View API
```text
POST /api/session/cell/run { cell, stdin }
POST /api/session/run_all { restart, inputs? }
POST /api/session/cell/clear
POST /api/session/plan/assign
POST /api/session/plan/add
POST /api/session/plan/remove
POST /api/session/plan/value
POST /api/session/interrupt
POST /api/session/snapshot/capture
```
所有端点只操作 foreign 句柄;view 不直接读写内核。
### 14.3 CLI
```text
marqdo view output --snapshot FILE
marqdo view output --execute
marqdo view output --no-exec
marqdo run --writeback
```
不新增 `marqdo notebook`。
---
## 15. 语义矩阵
| 能力 | run | view | static |
|---|---|---|---|
| `foreign.session` plan | 作为普通值执行 | 消费句柄 | 可执行或快照 |
| raw stdin | 支持(一次性/session) | 每 cell | inputs 表/快照 |
| interrupt | 无 UI | 可调用 | 不可用 |
| state export | 可调用 | 可显式导出 | 不导出或快照 |
| cross-doc(deferred) | 设计保留 | 设计保留 | 设计保留 |
| writeback | `--writeback` | 显式按钮 | 默认不写 |
---
## 16. 实施顺序
### P0(先做,直接影响真实使用)
1. **G1/G2 stdin**:控制通道 + 每 cell 输入表 + UI。
2. **G5 interrupt**:避免只能等超时。
3. **G9 snapshot capture**:解决 live/static 不一致。
### P1
4. **G4 runtime plan updates**。
5. **G6 export/replay**。
### P2
6. **G3 dynamic plan 边界**:按第 6 节,只做顶层纯表达式;任意控制流不承诺。
7. **G10 explicit writeback policy**。
### Deferred(不在当前目标)
- **G7 cross-document scope**:设计保留,后续版本再开发。
- **G8 non-Python/Node persistent adapters**:设计保留,等待目标语言与 worker。
---
## 17. 测试设计
### 单元
- `stdin` 协议:空输入、大输入、超时、中断、连续 eval;
- 每 cell 输入隔离;
- 返回值锚定在调用点(已修复的 CallFrame.call_line);
- 表格不产生 call chip(已修复);
- plan top-level 诊断;
- session generation / dirty;
- export/import/replay 校验。
### 集成
- Python 持久内核读 `sys.stdin`;
- Node 持久内核读 `process.stdin`;
- view Run All 使用每 cell 输入;
- interrupt 后下一次 eval 正常;
- static snapshot 与 live 结果一致;
- snapshot hash 不匹配显式失败;
- cross-doc scope 冲突/清理;
- Go 一次性 vs 持久能力诊断;
- writeback 只显式写入。
### 静态
- 输出无 traceback;
- 没有输入时显示说明而非伪造;
- 多内核 controls 显示;
- writeback slot 单块、暗色主题;
- 静态按钮提示。
---
## 18. 兼容与迁移
- 现有 `foreign.session kernels= cells= values=` 保持兼容;
- 新 `inputs=` 可选;
- `session_open` 旧协议继续可用;v2 控制通道通过 handshake 协商;
- 旧页面没有 `inputs` 时仍按空 stdin 执行/显示说明;
- 不修改已发布的 v1.5.0 tag;v3 以新版本发布。
---
## 19. 需要拍板的决策
1. **G1**:是否接受控制通道与程序 stdin 分离的协议改造?否则只能保留 `input`,不能宣称 raw stdin。
2. **G3**:是否接受“plan 必须是顶层声明”的边界?若不接受,需要定义 view 可安全调用的 plan 入口,风险更高。
3. **G6**:状态快照只允许 JSON 值,是否可接受?不做任意对象序列化。
4. **G9**:快照文件是否默认放在 `.marqdo/snapshots/` 且不提交?涉及 secrets。
5. **G10**:自动 writeback 是否只允许显式按钮/flag,而不是每次运行自动写源码?
---
## 20. 当前目标范围
v3 当前实现目标为:**G1、G2、G3、G4、G5、G6、G9、G10**。
**G7、G8 已移出当前目标**,但设计文档保留在本文件第 10、11 节,供后续开发;它们不计入 v3 完成条件,也不影响现有 API 的兼容性承诺。
## 21. 非目标
- 不新增 Markdown 标记;
- 不新增 notebook CLI/模式;
- 不把任意内核内存序列化;
- 不默认修改 `.mq.md`;
- 不自动镜像变量;
- 不把 view 变成第二套解释器;
- 不把“未实现”伪装成支持。
+306
View File
@@ -0,0 +1,306 @@
# 语法设计哲学:函数在「代码即文档」里为何水土不服,以及用什么语义取代
> **2026-10-23 审阅裁决**:保留“正文优先、按需命名”的方向;下文语料统计和“具名给值缺失”等判断属于当时快照。当前已有具名实参;“调用即代入”不规定文本展开实现,也不禁止递归。下一阶段以[文档原生指导 §2–3](document-native-development-guide.md#2-语法审查的保留修正与暂缓)的范围和验收为准,本文不是替换整个函数模型的已批准语法提案。
| | |
|---|---|
| 状态 | **Proposed · 哲学层讨论**(不涉及实现,不含语法提案细节) |
| 日期 | 2026-10-22 |
| 命题来源 | 用户:「函数是复用、是对高度凝练内容的提炼加工;正常人不会说『计算 37 的两倍需要抽象一个函数』,而是直接说乘二」 |
| 定位 | 本文只谈**语义表示**与**自然语言映射**,不谈编译器与语法糖 |
---
## 0. 把你的观察写成三条命题
**命题一(现象)**:函数是一种**预先抽象**装置——必须在使用之前先把内容提炼并命名,还要声明它需要哪些输入。
**命题二(对照)**:自然语言是**即席描述**——先把事说清楚,只有在内容确实要反复出现时,才顺手给它一个名字("以上做法,我们称为…"),而且命名之后它可以像普通名词/动词一样被使用。
**命题三(结论)**:因此「函数」这套仪式与「代码即文档」错位。要解决的不是调用写法,而是**用什么语义表示来承担"复用"这件事**。
本文的答案先给出来:
> **Marqdo 需要的不是更好的"函数",而是把「函数」还原成「命名」,把「调用」还原成「代入」。**
> 函数 = **一段被命名的正文**;参数 = **那段正文里尚未确定的量**;调用 = **把这些量代入后重述一遍**。
---
## 1. 语料给出的证据:Marqdo 的 `##` 其实不是"过程"
统计 `lib/ ext/ examples/ tests/` 全部 1322 个 `##`:
| 指标 | 数值 |
|------|------|
| 函数总数 | 1322 |
| **纯返回式**(零可执行语句,只有一个返回表达式) | **765(57.9%)** |
| 一行式(可执行行 ≤1 且返回 ≤1) | 935(70.7%) |
| 极短(可执行行 ≤2) | 1162(87.9%) |
| 较长(可执行行 ≥10) | 62(4.7%) |
| 可执行语句数**中位数** | **0** |
| 平均 | 2.2 |
典型代表:`## str_trim`、`## contains`、`## to_upper`——**一个名字包一个表达式**。
这说明:**人们用 `##` 在做"命名",语法却要求他们按"过程抽象"的仪式来做。**
签名(`+ n`)、祈使式调用(`> f 1 2`)、返回值约定(`*…*`)全是过程语言的行头,
而实际内容是"给这个式子起个名字"。
**水土不服不是感受,是可以量化的形式错配。**
### 1.1 按「语义功能」再分一次类
把 1322 个函数按内容形态归类(同一函数可能重叠,故按主特征优先):
| 形态 | 判据 | 数量 | 占比 | 自然语言对应 |
|------|------|------|------|-------------|
| **纯命名式** | 零语句、零副作用、零分支、零循环,只有一个返回式 | **754** | **57.0%** | 「所谓 X,是指…」 |
| **条款式** | 有分支、无副作用 | 103 | 7.8% | 「凡…则…」 |
| **遍历式** | 有循环、无副作用 | 26 | 2.0% | 「对每一项…」 |
| **命令式** | 含 `print` 等副作用 | **83** | **6.3%** | 「打印…」祈使句 |
| 线性计算(其余) | 有语句但无控制流/副作用 | 356 | 26.9% | 「先…再…」 |
两个结论:
1. **命名 + 条款 = 64.8%** —— 三分之二的 `##` 落在"定义"与"条款"两种自然语言形态里,
而这两种恰好不需要"过程"语义(§4 立场甲、乙)。
2. **真正的副作用只有 6.3%** —— 也就是说"命令/祈使"语义只是少数派,
完全可以隔离成一小块(§8.1),不必让它污染整体读法。
---
## 2. 为什么"抽象"在文档里格外别扭:复用经济学
抽象不是免费的。它有三项成本:
| 成本 | 内容 |
|------|------|
| **定义成本** | 要写一次定义(名字、输入、边界) |
| **跳转成本** | 读者看到名字,必须回到定义处才能理解(文档尤其致命:要翻页/滚动) |
| **维护成本** | 定义改了,所有使用处语义随之变化 |
收益只有一项:**同一内容被复用 N 次时省下的重复**。
于是有:
> **抽象值得做 ⟺ 复用次数 × 内容复杂度 > 定义成本 + N × 跳转成本**
在**代码**里,N 往往很大、跳转成本低(IDE 跳转、同屏),所以抽象划算。
在**文档**里,N 常常是 **1**,跳转成本高(读者在阅读流里被打断),于是:
> **文档中大量"函数"是负收益的**——它们只被用一次,却强迫读者回头查定义。
这解释了为什么你会有"正常人不会这么说话"的直觉:**说话的默认假设是对方不知道你的定义**,
所以人话倾向于**就地展开**;而函数默认假设读者愿意跳转。
---
## 3. 自然语言里「复用」到底有几种形态
程序语言只承认其中一种(命名+参数化),这是错配的第二层。
| 形态 | 自然语言的样子 | 对应的程序装置 | Marqdo 现状 |
|------|---------------|---------------|------------|
| **重复** | 再说一遍 | 复制粘贴 | ✅ 允许 |
| **指称** | 如上所述 / 同前 / 该金额 | 变量、引用 | ✅ `` `名` `` |
| **命名** | 所谓 X,是指…;以下称 X | 定义 / 函数 | ✅ `## X` |
| **条款** | 凡…则…;若…应… | 条件分支、规则 | ✅ `1. 2. 3.` |
| **范例** | 以 37 为例 | 样例/测试 | ⚠️ 仅测试目录 |
| **表格/清单** | 见下表;用料如下 | 数据、查表 | ✅ 表格 |
**关键发现**:命名只是六分之一,但程序语言把它变成了**唯一的复用入口**。
而文档写作里,**指称("该金额")与条款("凡…则…")比命名更常用**。
---
## 4. 三种候选语义表示(哲学立场)
要"代替水土不服",必须给出**语义模型**,而不只是换个写法。三个候选:
### 立场甲:定义—代入(Definition & Substitution)
**语义**:一段正文被命名 → 成为一个**定义**。使用它 = 把定义里的自由量按**角色**代入,再重述。
```markdown
## 加倍
把 `x` 乘以二,得 *y*
```
使用(语义读法):**按「加倍」代入 x=37,得 74。**
| 维度 | 评价 |
|------|------|
| 自然语言对应 | ✅ 「依定义」「按…计算」「所谓…是指…」——学术与说明文的主力 |
| 与 Marqdo 契合 | ✅ `##`/`#` 本来就是标题(文档结构),天然是"定义"的载体 |
| 参数观 | ✅ 角色(具名),不是位置占位符 |
| 复用单位 | ✅ **文本段落本身**(文档即单位,符合"代码即文档") |
| 71% 的现有一行式函数 | ✅ 直接就是"命名的表达式",无需过程仪式 |
| 缺点 | 定义与使用分离,仍有跳转成本(但可用"就地展开"缓解,见 §5) |
### 立场乙:条款—援引(Clause & Citation)
**语义**:条件 → 结论。使用 = 援引条款并给出适用的事实。
```markdown
## 计费规则
若 `里程` 超过 100 公里,则 `费用` 按 8 折计。
```
使用(语义读法):**本单里程 120 公里,依「计费规则」,费用按 8 折。**
| 维度 | 评价 |
|------|------|
| 自然语言对应 | ✅✅ 「凡…则…」是中文说明文/法条/规章的骨架 |
| 与 Marqdo 契合 | ✅ `1. 2. 3.` 分支已经就是条款形式 |
| 缺点 | 数值计算写成条款别扭("把 37 乘以二"不是条款) |
### 立场丙:配方—配料(Recipe & Ingredients)
**语义**:一张用料表 + 一段做法。参数 = 配料表中的行。
| 维度 | 评价 |
|------|------|
| 自然语言对应 | ✅ 菜谱、工艺卡、表单 |
| 与 Marqdo 契合 | ✅✅ 表格优先正是 Marqdo 的特色;契约表已是雏形 |
| 缺点 | 表达力弱;无法递归、无法组合;"给值"变成填表 |
### 取舍
| | 甲 代入 | 乙 条款 | 丙 配料 |
|---|---|---|---|
| 覆盖"命名表达式"(58% 的现状) | ✅✅ | ⚠️ | ❌ |
| 覆盖"条件规则" | ⚠️ | ✅✅ | ❌ |
| 覆盖"数值流程" | ✅ | ❌ | ⚠️ |
| 可读性 | 高 | 最高 | 最高(但最弱) |
| 与 `##` 结构一致 | ✅ | ✅ | ⚠️ 表为主 |
**推荐:以甲为主,乙作为甲内部的一种段落形态。** 理由见 §6。
---
## 5. 「代入」为什么比「调用」更贴自然语言
这不是文字游戏,三处实质差异:
| 维度 | 调用(invocation) | 代入(substitution) |
|------|-------------------|---------------------|
| 读者的心理动作 | "跳过去,看它做什么,再回来" | "把这个式子代进去" |
| 输入的意义 | 实参 → 形参(两套名字) | 角色 → 定义里的同一个名字(**一套名字**) |
| 结果的意义 | 函数返回了一个值 | 式子变成了具体结果 |
| 出现位置 | 必须是独立语句或表达式 | 可以**嵌在叙述里**("加倍后为 74 件") |
| 一次性使用 | 仍要付出定义+跳转成本 | 可以**不定义,直接展开**(§5.1) |
### 5.1 关键:抽象要能被"取消"
自然语言的强大在于**可省略**:能一句话说清就不起名字。
所以语义模型必须允许同一件事有**两种粒度**,并可以随时在两者之间移动:
| 粒度 | 写法(示意) | 何时用 |
|------|-------------|--------|
| **就地描述** | 把 37 乘以二,得 74 | 只用一次 |
| **命名后代入** | 按「加倍」代入 x=37,得 74 | 复用多次 |
而且**提升与展开都是作者的编辑动作,不是必须的入口**。
这正是"抽象可选"——今天的函数是"必须先抽象",这是错配的第三层。
### 5.2 与 58% 纯表达式函数的对应
`## to_upper` 这类函数,用"代入"读就是:
> 「to_upper 的定义是:把 `s` 变成全大写。」使用:`to_upper` 代入 s="abc" 得 "ABC"。
它读起来是一个**定义 + 一次代入**,而不是"调用一个过程"。这与它的实际内容(一个表达式)一致。
---
## 6. 这套语义如何落到 Marqdo 已有的东西上
| 自然语言的成分 | Marqdo 已有载体 | 需不需要新东西 |
|---------------|----------------|---------------|
| 命名(给出定义) | `#` / `##` 标题 | ❌ 已有 |
| 正文(定义的内容) | 叙述 + 标记代码 | ❌ 已有 |
| 未确定的量(角色) | 体推断出来的形参(v0.3 已有) | ❌ 已有 |
| 角色的**具名给值** | (缺失) | ✅ **这是唯一真正缺的一环** |
| 结论(得…) | `*…*` 返回 | ❌ 已有 |
| 条款(凡…则…) | `1. 2. 3.` 分支 | ❌ 已有 |
| 配料表 | GFM 表格 + 契约表 | ❌ 已有 |
| 引用(依…) | (缺失) | ⚠️ 与"具名给值"是同一件事 |
**结论:缺的只有一件事——「具名给值」的形式。**
也就是说:语义模型(代入)几乎不用改,语法只缺一个"把角色填上"的最小约定。
这把问题从"要不要重新设计函数"缩小到"这一个小约定怎么长得最不刺眼"。
---
## 7. 不可回避的哲学难题:自然性 vs 可判定性
自然语言判断"哪些量要代入"靠**语境**(前文、常识、指代)。
编译器不能。所以必须有一条**显式约定**,无法省掉。
三种可能的约定形态(只列哲学性质,不列语法细节):
| 形态 | 自然的程度 | 可判定的程度 | 风险 |
|------|-----------|-------------|------|
| **角色必须具名给出** | 中(像"按定义,其中 x=37") | ✅ 完全可判定 | 略啰嗦 |
| **靠语序(位置)** | 高 | ✅ 可判定 | ❌ 已实测:叙述顺序一变,绑定就翻转(见 call-syntax-from-marks.md §4.3) |
| **靠语境(隐式)** | 最高 | ❌ 不可判定 | ❌ 130 个形参名撞车 |
**这是整件事的硬边界**:越像人话,越难判定。Marqdo 必须选"具名"这一档——
它是**唯一同时可读且可判定**的点。
而这也解释了为什么"叙述式动词"(`执行`)不可取:它把判定交给了一个**未标记的词**,
既没有自然的程度优势,又破坏了"叙述安全"。
---
## 8. 三个尚未解决的哲学问题
这些是真问题,需要后续立场,不宜草率定:
1. **副作用怎么办?**
"把 37 乘以二"是纯代入;"打印 74"呢?打印**改变世界**,不是代入。
→ 副作用可能必须停留在"命令"语义(今天的 `> print`),
而这会让文档里同时存在"代入"与"命令"两套读法。这是否可接受?
2. **递归与自引用怎么办?**
代入是有限展开;递归是无限展开。若坚持代入选义,递归就不可表达。
→ 是否接受"Marqdo 不支持递归"?还是给递归单独一套"过程"语义?
3. **定义的时序怎么办?**
自然语言允许先使用后定义("如上,我们称之为…")。代入语义要求定义先存在。
→ 是否允许前向引用(读者先看到 `加倍`,后面才看到定义)?
---
## 9. 一句话总结与建议
> **Marqdo 的问题不是"函数不好用",而是"函数是过程语言留给文档的遗产"。**
> 文档需要的不是过程,是**命名**;不是**调用**,是**代入**。
建议的语义立场(待你裁决):
| 项 | 建议 |
|----|------|
| 复用单位 | **一段被命名的正文**(而非过程) |
| 参数观 | **正文中未确定的量**(角色,具名) |
| 调用观 | **代入**(可读作"按…代入…") |
| 抽象时机 | **可选提升**:默认就地展开,需要复用时才命名 |
| 唯一新增约定 | **具名给值**(形态待定,但必须具名,理由见 §7) |
| 保留"命令"语义 | 仅用于副作用(`print` 等),与"代入"分层 |
| 条款 | 作为定义的一种段落形态(`凡…则…`),不另设机制 |
---
## 10. 待你裁决
1. **是否接受"函数→命名 / 调用→代入"这个总重构?**
若接受,后续所有语法讨论都在这条轴上做取舍。
2. **§8 的三个难题**你的倾向是什么(尤其"是否接受不支持递归")?
3. **"具名给值"的最小形态**:你更接受哪一种读感?
- `**加倍(x=37)**`(像函数调用)
- `按**加倍**,`x`=37`(像句子,但需要判定规则)
- 表格给出角色(像配料表)
4. 是否需要我把这份哲学立场,反向校验一遍**现有 1322 个函数**——
看有多少在"命名表达式"框架下会更自然、多少必须保留"过程"语义?
+337
View File
@@ -0,0 +1,337 @@
# 语义探析:代码函数能否解释为一张 GFM 表
> **2026-10-23 审阅裁决**:下文 v1.5.2 实验不替代当前回归。保留现有数据表几何与契约表角色,不重复声明参数;“现有实现不支持函数表”不等于表格不能表达计算。有限决策表和生成式签名视图按真实用例评估,见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **Proposed · 待决策**(未修改任何代码) |
| 日期 | 2026-10-22 |
| 提出 | 「`## 函数名` + `+ 参数` + 函数体,从某种角度能否解释成 GFM 表」 |
| 方法 | 11 组运行时实验(1.5.2)+ 5 份设计/路线图文档考古 |
| 相邻 | [functions-as-values-evaluation.md](functions-as-values-evaluation.md) · [link-style-call-evaluation.md](link-style-call-evaluation.md) |
| 关键前置 | [collection-access-link.md](collection-access-link.md) · [call-arguments.md](call-arguments.md) · [tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) · [objects.md](objects.md) |
---
## 0. 一句话答案
**你的命题在 Marqdo 里已经实现了——但它实现的是「关于函数的表」,不是「函数本身」。**
```
## 加一
| 参数 | 类型 | 说明 |
|------|------|------|
| n | number | 输入值 |
*n+1*
```
这张表**今天就能跑**,是既有特性(契约表,`tests/contracts/ok_contract.mq.md`)。
它证明了:函数参数**确实可以**是一张 GFM 表。
但它只能**描述**参数,不能**声明**参数;它不含函数体,不决定 arity,也不能被调用。
一句话划界:
> **表能描述外延(输入→结果)与签名(元数据),不能描述内涵(怎么算)。**
> 而「调用」恰恰是内涵操作。
> `[k](集合)` 是**投影已有数据**,`f(x)` 是**计算新数据**——
> 只有 f 本身已经是「预先枚举好的表函数」时,两者才重合。
---
## 1. 先固定事实:Marqdo 的表格几何(实测)
讨论前必须先把「表」的语义钉死,否则会建在错觉上。
| 形状 | 绑定结果 | 实验 |
|------|---------|------|
| 1 列 N 行 | `List`(列值) | 文档锁定 + 实测 |
| ≥2 列 **1 行** | `Map`(表头→标量,即「记录」) | `{"档位":[1,2]}` 反例 → 单行才是记录 |
| ≥2 列 **N 行** | `Map`(表头→**列列表**,列向聚合) | 实测 `{"档位":[1,2],"税率":[0.03,0.1]}` |
| 首列标头为 `行` / `@` / `row` | `List[Map]`(**行向记录**,显式开启) | [tables-maps-footnotes](../roadmap/tables-maps-footnotes.md) §3.5 |
**关键点**:Marqdo 的默认是**列向**。多行多列表不是「一组记录」,
而是「一列一个列表」。行向记录是**显式标记**才能开的形态,
文档原话:「**不得**与默认列向字典静默混用」。
这一条直接决定了「行 = 参数」在 Marqdo 里**不是自然形态**:
按默认几何,`| 参数 | 类型 |` 两行参数会变成
`{"参数":["a","b"], "类型":["number","number"]}` —— 列向。
---
## 2. 你的命题已经存在:契约表
`src/contract.rs:308` 的注释写得很清楚:
```
/// 未绑定文档表(`Expr::Map`)→ 契约块。
/// - `None`:非契约形状(普通数据/说明表,原样保留)。
/// - `Some(Err)`:契约形状但畸形 —— 必产诊断。
/// - `Some(Ok)`:合法契约(`参数`/`返回`/`字段` 三形状之一,须含 `类型` 列)。
```
三条规则(`src/contract.rs:260-334`):
| 规则 | 实现 |
|------|------|
| 表头含 `参数`/`形参`/`param`/`arg` → 形参契约 | `PARAM_HEADERS` |
| 表头含 `返回`/`return`/`result` → 返回契约 | `RETURN_HEADERS` |
| **必须含 `类型` 列**,否则视为普通说明表 | `TYPE_HEADERS` 缺失 → `return None` |
也就是说:**「函数参数表」不仅可能,而且已经是正式语法**。
第一列标头(`参数` / `返回` / `字段`)扮演的正是
[tables-maps-footnotes](../roadmap/tables-maps-footnotes.md) §3.5 里
`行`/`@`/`row` 那种**形态标记**的角色:显式声明「这张表是干什么用的」。
---
## 3. 但它是「关于参数的表」,不是「参数本身」
11 组实验里最关键的 6 组(全部实跑):
| # | 写法 | 实测结果 | 说明 |
|---|------|---------|------|
| E1 | 参数表列 `n`,函数体不读 `n` | `> f` 无参调用**成功**,`n` 不是形参 | 表不能声明形参 |
| E3 | 叙述声明 `n` + 参数表 + 传 `"七"` | `参数 n 期望 number,实际 text(契约校验)` | **表能校验** |
| E4 | 叙述声明 `n`,**无表** + 传 `"七"` | `七1` | 无表则不校验 |
| E5 | `+ \`n\`` 旧式形参行 + 参数表 + 传 `"七"` | 同 E3,报契约错 | **你的草图形态可用** |
| E6 | 表写 2 行(`a`,`b`),体只读 `a` | `too many positional arguments` | **表 ≠ arity** |
| E7 | 单列参数表 `\| 参数 \|` + `\| n \|` | `七1`,**契约静默失效** | 1 列 = List,不成契约 |
| E8 | 表里重复两行 `n` | 取**首行**类型,无诊断 | 表内重复静默 |
| E9 | 表里有 `ghost`(体里没有) | 静默忽略 | 幽灵行静默 |
| E10 | 同一张表加 `` `tc` = `` 绑定 | `七1`,契约**消失** | 绑定 → 变数据 |
**E10 揭示了一条隐含且优雅的规则**:
> **未绑定的表 = 声明/元数据(契约);绑定的表 = 数据。**
这正是语言对「表可以是声明吗」给出的既有答案:可以,**但前提是它不是一个值**。
一旦你给它起名字(`` `tc` = ``),它就从「关于函数的声明」降级为「一个普通数据值」。
E6 + E7 + E8 + E9 合起来说明:**表与真实签名之间今天就可能漂移,而且是静默的**
(`marqdo check e7.mq.md` 输出「无契约问题」)。
---
## 4. 若让表成为「定义」,运行时会发生什么
把上面的静默漂移从「少个校验」升级成「少个参数」,风险等级完全不同。
| 风险 | 今天(表=注解) | 若表=定义 |
|------|----------------|-----------|
| 漏写 `类型` 列 | 契约静默失效(E7) | **参数静默消失**,调用直接错 arity |
| 表行数 ≠ 体读取数 | 表多余行被忽略(E6/E9) | **接口由表决定**,体重构后表未改 → 运行期崩 |
| 重复行 | 取首行(E8) | **参数重复定义**,行为取决于解析器取舍 |
| 表行重排 | 无影响(顺序由声明序决定) | **改变位置参数绑定顺序** → `> f 1 2` 含义变了 |
| 加名字绑定 | 变数据(E10) | 语义分叉:什么时候是函数、什么时候是数据? |
最后一条最致命。**表是「可自由编辑的文档」**:调整行序、增删说明列、
甚至把两张表合并,都是正常的写作行为。一旦表的行序决定位置参数绑定,
「把 `b` 那行移到 `a` 上面」这个无害的编辑动作就**改变了程序行为**。
而 Marqdo 的核心承诺是「**文档即程序,且文档可被人阅读与维护**」。
让排版顺序携带语义,等于给每张表埋一颗静默的雷。
对比一下:`[键](集合)` 之所以安全,是因为**键是显式的**,
取元不依赖顺序。而位置参数天然依赖顺序——所以**签名不该用表承载顺序**。
---
## 5. 为什么链接式调用 `[f](args)` 走不通(第三次论证,这次有史料)
前两轮已从「与取元同形」论证过。这次找到了设计层的原始决议。
[collection-access-link.md](collection-access-link.md) §1:
> 心智:**方括号 = 取出的名字,圆括号 = 从哪取。**
```markdown
**价 = [拿铁](菜单)** # 取出的名字 = 拿铁;从哪取 = 菜单
```
§4「非目标」明确排除:点号 map 访问、`在`、箭头取元、`(键)[集合]`。
[call-arguments.md](call-arguments.md) §2 同样锁定:
> `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记。
所以 `[f](x)` **不是「还没决定的语法」,而是已被明确分配给取元**。
让它兼作调用,就是把「从哪取」这个心智反转成「调用谁」——两套直觉会打架。
而且这与 §4 的表问题**同源**:都是「同一个外形要承载两种语义」,
只不过一个在值层面(表 vs 函数),一个在语法层面(取元 vs 调用)。
---
## 6. 历史:这条路走过,而且是被**反向**走过的
这是本轮考古最有价值的发现。四条史料:
### 6.1 v0.2 要求手写形参表 → v0.3 明确废除
[markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) §1 把 v0.2 的做法列为**代价**:
| v0.2 | 代价 |
|------|------|
| 形参必须 `` + `名` `` | **仪式感强;函数头像「另一套签名语言」,与正文脱节** |
§2 P4 直接给出新方针:
> **P4 — 形参由体推断(Body-inferred params)**
> **不再要求**作者手写 `` + `名` `` 形参表(v0.3 默认关闭;过渡期可兼容)
§5 对照表把 `+ 名` 标为「**过渡兼容**:显式形参;**新代码不推荐**」。
**结论**:Marqdo 的发展方向是**离「声明式签名」越来越远**,转向「叙述即签名」。
把参数改写成表,是在这条已经走反了的路上再走一遍。
### 6.2 「用表声明 schema」是明文非目标
[objects.md](objects.md) §6 非目标:
> - 用表格声明字段 schema(**表格仍表示数据集合**;见 tables-maps-footnotes.md)
路线图里同样列为非目标:
> 用表声明对象字段 schema(仍见 objects 非目标;**与数据集合分开**)
**结论**:语言已明确决定「表管数据,不管声明」。契约表是这一原则的**受控例外**——
它只提供注解与校验,不提供绑定。
### 6.3 行向记录必须显式标记,且「不得静默混用」
[tables-maps-footnotes.md](../roadmap/tables-maps-footnotes.md) §3.3:
> **备选语义(不默认):行向记录列表** …… 若未来需要,用显式标记区分,
> **不得**与默认列向字典静默混用。
§3.5 落地了 `行`/`@`/`row` 标记。
**结论**:凡是「形态会改变语义」的地方,Marqdo 一律要求**显式标记**。
「函数签名表」如果真要参与绑定,属于同类形态变化,必须同样显式——
而契约表的 `参数`/`返回` 头,正是这个显式标记的现成形态。
### 6.4 取元曾被反复挑选,最后选定链接形
[collection-access-link.md](collection-access-link.md) §3 记录了迁移史:
脚注形 `` 集合[^键] ``(左键右基)→ 链接形 `[键](集合)`(左键右基,更好读)。
**结论**:`[…](…)` 这块语法是被**反复权衡后定下来的**,不是随手占用。
---
## 7. 诚实的收益清单
不能只讲风险。这条路确实有真收益:
| 收益 | 现状 | 潜力 |
|------|------|------|
| **人读** | 契约表已能带类型+说明,比 `+ 名` 可读得多 | 正是 v0.3 批评 `+` 行「仪式感」的解药 |
| **调用边界校验** | 已实现(E3) | 可扩展到更多类型(枚举、范围) |
| **机器读:tool schema** | ⚠️ 半成品:`tools` 已能写成记录行(`tool_names` 接受含 `name`/`工具` 字段的对象),但 `agent_format_tools` **只渲染名字**(`- name`),说明与参数被丢弃 | 若函数暴露签名,工具可带 schema 与说明,实参可校验 |
| **机器读:CLI/表单** | ❌ 无 | 签名即表 → 直接生成命令行参数解析、Web 表单 |
| **文档一致性** | ❌ 表与体可静默漂移(E6/E9) | 可做成「漂移即报错」 |
最后三行是**最有价值的**。最典型的是 tool schema:`tools` 的数据形态**已经允许**每行带说明,
但渲染器只取名字——也就是说**能力已经在那儿,只差把签名接上去**。
这不需要把表变成定义,只需要让签名**可被投影成表**。
---
## 8. 建议:表做声明,不做定义(并补三件事)
### 8.1 结论
| 主张 | 裁决 |
|------|------|
| 函数参数可以用 GFM 表**描述** | ✅ **已经是特性**,继续用 |
| 函数参数可以由 GFM 表**声明**(表即真相) | ❌ 不建议:顺序携带语义、静默漂移、与 v0.3 方向相反 |
| 函数**本身**(含函数体)= 表 | ❌ 不可行:体是代码不是数据(见 functions-as-values §4.2) |
| `[f](args)` 链接式调用 | ❌ 已被明确分配给取元 |
**保持现有分工**:
> 未绑定的表 = 声明(契约);绑定的表 = 数据;**函数体与 arity 是唯一真相**。
### 8.2 该补的三件事(都低成本,且都是「消灭静默」)
**① 让漂移显式化(最高价值)**
现状:表写 2 行、体只读 1 个 → 静默忽略(E6/E9);1 列 → 静默失效(E7)。
建议 `marqdo check` 增加诊断:
| 情形 | 现在 | 应改为 |
|------|------|--------|
| 契约表缺 `类型` 列 | 静默视为普通表 | 若表头含 `参数`/`返回` 则 **warn**:缺 `类型` 列,已按说明表忽略 |
| 契约表列数不齐 | 有诊断(`Some(Err)`) | 保持 |
| 表里的参数名不在真实 arity 内 | 静默忽略 | **warn**:`ghost` 不是本函数的形参 |
| 表头重复参数名 | 取首行 | **warn**:重复声明 |
这与本轮 D9「未闭合引号静默吞行」是同一类问题——**静默类缺陷**优先修。
**② 反向生成:签名 → 表(满足「语法很美」)**
既然表是好的**呈现**,就让工具来生成它,而不是让人手写:
```
marqdo view --signature 文件.mq.md # 从体推断的签名生成契约表草案
```
单一真相仍是函数体,表是**投影**。这样既拿到「签名即表」的可读性,
又不引入第二真相。人也可以手写表,`check` 负责校验它与体一致(即 ①)。
**③ 让签名可供机器消费**
把 `Function` 的签名(名、参数、类型契约)暴露成结构化数据(如
`marqdo knowledge` 的能力条目里带上参数 schema),
`ext/ai` 的工具即可从「只渲染名字」升级为「带 schema 与说明的工具」。
这是 §7 里最实的收益,且**零语法改动**。
---
## 9. 一个可以试的新写法(示例,供你评判)
如果你想保留「表 + 函数体」的书写快感,最安全的形态是**双写 + 一致性校验**:
```markdown
## 税率
+ `档位`
| 参数 | 类型 | 说明 |
|------|------|------|
| 档位 | number | 1/2/3 档 |
| 返回 | 类型 | 说明 |
|------|------|------|
| | number | 适用税率 |
- [行](`税率表`)
**hit = [档位](`行`)**
1. `hit`
...
*[税率](`行`)*
```
| 优点 | 缺点 |
|------|------|
| 人读极好(表 + 正文) | 与真实签名可能漂移(需 ① 的校验兜住) |
| 已经是**今天可跑**的语法(E5 验证) | `+ 行` 是 v0.3 标注「新代码不推荐」的旧形态 |
| 类型校验已生效(E3) | 表不能替代体推断,参数仍要声明 |
**要点**:这张表**不是**函数的定义,而是它的**仪表盘**。
真正的接口由 `+ 档位`(或叙述声明)决定,表负责类型与说明。
只要两者不一致就报错,这套写法就既美又安全。
---
## 10. 待你决策
1. **裁决**:是否接受「表做声明、不做定义」(§8.1)?
2. **优先级**:§8.2 的三件事(① 漂移诊断 / ② 反向生成 / ③ 签名可供机器消费)
先做哪个?我建议 ①(消灭静默)→ ③(tool schema 是刚需)→ ②。
3. **是否要我把 `+ 行` 加契约表的组合**写成教程样例(§9),
并明确标注「`+` 是兼容形态、新代码优先叙述声明」?
4. 若你仍想推进「表即签名」,我可以做一次**限定实验**:
要求显式标记(如 `| 签名 | 参数 | 类型 |`)+ 与体推断不一致即报错,
在小范围金样里验证是否可控。要我做吗?
@@ -0,0 +1,471 @@
# 方案评估:函数能否作为变量的一种(函数即表)
> **2026-10-23 审阅裁决**:以下是旧实现约束与方案权衡,不是“匿名函数无法索引”或“动态调用无法检查契约”的普遍结论。一等函数/闭包本轮暂缓而非永久禁止;有限决策表先评估现有库表达,文中建议的新辅助函数不因此成为已实现能力。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓)。
| | |
|---|---|
| 状态 | **Proposed · 待决策**(未修改任何代码) |
| 日期 | 2026-10-22 |
| 提出 | 用户:「函数本身可以理解为 `` `函数名` = `` + 参数/函数体表;此时和表格取元有极大相似性」 |
| 相邻 | [link-style-call-evaluation.md](link-style-call-evaluation.md) · [spaced-function-names-d8.md](spaced-function-names-d8.md) · [function-as-table-semantics.md](function-as-table-semantics.md)(后续:函数与表格的语义考古,11 组实验) |
| 影响面 | 值模型 / 调用语义 / 契约 / EKC 指纹 / 字节码 / 序列化 |
---
## 0. 一句话结论
**你的直觉在数学上是对的,但在语言上要拆成三种强弱不同的主张**:
| 主张 | 是否已成立 | 代价 |
|------|-----------|------|
| 弱:函数**名**可当数据传递 | ✅ **今天就能做**(字符串 + `call_fn`),但零参、不可静态检查 | 无 |
| 中:函数是**一等值**(可存、可传、可返回) | ❌ 需要新值类型 + 动态 callee | 中高:契约、指纹、字节码、序列化全都要动 |
| 强:函数**就是表**(结构性、可遍历、可序列化) | ❌ 需要把代码降格为数据 | **高**:与「代码即文档」的静态可索引性冲突 |
**建议**:把你草图里真正有价值的那部分(**有限域决策表**)作为一等公民支持——它今天就成立、
且极其契合 Marqdo 的表格优先哲学;而「函数即表」的强主张不建议采纳,理由见 §4、§6。
---
## 1. 先把「函数是变量」拆开
这四个概念经常被混为一谈,必须分开,否则讨论会滑。
### 1.1 外延观(extensional)——函数是「图」
数学上函数就是一组有序对 $f = \{(a,1),(b,2)\}$,即它的**图像**。
按这个观点,函数**确实是一张表**,调用就是**查表**。
**但这里有一个必须先说清的实测事实**(我最初也想当然写错了):
GFM **两列表绑定成「列映射」,不是「按首列键控的映射」**:
```markdown
`税率` =
| 档位 | 税率 |
|------|------|
| 1 | 0.03 |
| 2 | 0.10 |
```
```json
{"档位":[1,2],"税率":[0.03,0.1]}
```
所以 `[2](`税率`)` **不是**取税率,而是:
```
error: missing map key `2`
```
真正能「键 → 值」查表的形态是 **Map**(来自 JSON 或库函数),实测两条可用配方:
**配方 A(推荐,最简)**
```markdown
**税率 = > json.parse text={"1":0.03,"2":0.10}**
**t = [2](`税率`)** # → 0.1
```
**配方 B(保留 GFM 表格可读性,但需显式索引)**
```markdown
**ks = [档位](`税率`)** # [1, 2]
**vs = [税率](`税率`)** # [0.03, 0.1]
**i = > table.index_of list=`ks` item=2** # 1
**r = > table.at xs=`vs` i=`i`** # 0.1
```
两条都在 1.5.2 上跑通了。**结论**:外延观的「函数=表」在 Marqdo 里不是
`[k](表)` 一句话就能实现,而是「**取到键值对**」这件事本身需要配方。
这恰好是一个可补的库缺口(见 §8.1)。
### 1.2 内涵观(intensional)——函数是「规则」
`f(x) = x² + 1` 无法写成有限表(定义域无穷)。此时函数是**代码**,调用是**执行**。
### 1.3 闭包观——函数是「代码 + 环境」
参数之外还要捕获外部变量。这需要运行时的环境快照。
### 1.4 名字观——函数是「命名空间里的一条」
今天 Marqdo 就是这一种:函数存在于 `Module.functions`,按名字解析。
**你的草图 `|参数|函数体|` 属于哪一种?** 它是**混合体**:行是参数声明(§1.4 的味道),
单元格放函数体(§1.2 的味道)。而「和表格取元相似」的直觉来自 §1.1。
**三种东西被一句话连起来了**——这正是评估要解开的结。
---
## 2. 现状实测(全部在 1.5.2 上跑过)
### 2.1 值模型里没有函数
`src/value.rs:15` 的 `Value` 枚举:`None / Bool / Int / Num / Text / List / Map / Formula / Code / Secret`。
**没有 `Func`。** 函数是 AST 节点(`src/ast.rs:58 Function`),挂在 `Module.functions`(`src/ast.rs:27`)。
`src/contract.rs:104` 的 `type_of` 同样是十种,穷举无函数。
### 2.2 调用的 callee 是静态名字,不是表达式
`src/ast.rs:130 CallExpr { callee: String, path, receiver, args }` ——
`callee` 是 **`String`**,不是 `Expr`。所以**语法上无法写出「对计算出来的值发起调用」**。
运行期 `src/interp.rs:1119 eval_call` 最终走到 `lookup_function`(`src/interp.rs:1774`),
按名字在 AST 树里查找。
### 2.3 对象已经是「表」
`src/interp.rs:1509 instance_type_name` 要求 method receiver 是**带 `_type` 键的 Map**:
```
error: method receiver needs a map with `_type`
```
也就是说 **Marqdo 里「用户定义的结构」本来就是普通 map + 一个标签**。
对象与表之间没有鸿沟——**这与你的直觉一致,而且已经是既成事实**。
但函数不是。对象是值,函数不是。这个不对称值得注意。
### 2.4 已存在按名字间接调用:`call_fn`
`src/interp.rs:1295`:
```rust
"call_fn" => {
// name 必须是 text
let target = lookup_function(module, fun, name)...;
if !target.params.is_empty() {
return Err("call_fn: `{name}` must have no parameters");
}
self.run_function(module, target, Env::new(), &[], false)
}
```
这是**今天最接近「函数可传递」的机制**,但有三道硬限制:零参、限当前模块、只在运行期校验。
### 2.5 六组实验
| # | 写法 | 结果 | 结论 |
|---|------|------|------|
| 1 | `**f = > greet**` | `missing argument for parameter who` | `> 名字` 是**调用**语法,**无法引用函数本身** |
| 2 | `> call_fn name="hello"`(无参函数) | `world` | 按名字调用可行 |
| 3 | `> call_fn name="add"`(有参) | `call_fn: `add` must have no parameters` | 不能传参 |
| 4 | 表里存函数名 + `[h](reg)` 取名 + `call_fn` | `dispatch=world` | **动态派发今天就能做**(名字即数据) |
| 5 | `> call_fn name="txt.str_trim"` | `unknown function` | **不能跨模块** |
| 6 | `> call_fn name="no_such_fn"` | `unknown function` | 拼错只能在**运行期**发现 |
**实验 4 是关键**:它已经是「函数作为表成员」的可用原型,只是把函数表示成**名字字符串**而不是函数值。
---
## 3. 你的类比中成立的部分
必须明确肯定,否则会低估这个想法。
### 3.1 「有限域函数 = 表」是完全成立的范式
这类函数在工程里非常常见,而且用它表达比写代码更清楚:
| 场景 | 适合表格 | 为什么 |
|------|---------|--------|
| 税率 / 费率档位 | ✅ | 有限、离散、常改动 |
| 状态机转移表 | ✅ | 二维查表一目了然 |
| 错误码 → 处理动作 | ✅ | 业务方直接维护 |
| 路由分发 | ✅ | 键即路径 |
| 配置映射 | ✅ | 本来就是数据 |
而且 Marqdo 的 `[键](集合)` 取元**在语义上就是函数应用** ——
前提是这个集合是 **Map**(键→值):
```markdown
**rate = [2](`税率`)** # 读作:税率(2)
```
只要 `税率` 是 Map,这行**无需任何语言改动**就是一个查表函数。你已经拥有它了。
唯一的坑是**数据形态要对**:GFM 两列表绑定的是**列映射**(§1.1 实测),
`[2](两列表)` 会报 `missing map key`。所以「表 = 函数」成立,
但**哪种表**有讲究——这正是 §8.1 要补 `table.by_column` / `table.lookup` 的原因。
### 3.2 表格对「参数边界」天然友好
上一轮讨论 `[函数名](参数)` 时,痛点是参数边界(空格切词)。表格完全绕开这个问题:
键是**显式**的,不需要切词。
### 3.3 对象已证明「结构即表」不会损害语言
§2.3 说明对象本来就是 map。既然对象能这样,把**数据的**函数化交给表格是自洽的。
---
## 4. 类比的断裂点
三个,每一个都是硬约束。
### 4.1 断裂点一:表格是有限的,函数通常是无限的
外延观只对**有限定义域**成立。`f(x)=x²+1` 写成表需要无限行。
所以「函数即表」只能覆盖**查表能解决的那部分**,不能作为函数的通用表示。
一旦你承认这一点,「函数即表」就从「函数的定义方式」降级为「一种特殊函数(图表函数)」。
这仍然有用,**但不是语言的核心函数机制**。
### 4.2 断裂点二:函数体是**代码**,不是数据
你的草图把「函数体」放进单元格。但函数体在 Marqdo 里是 `Vec<Stmt>`(AST),不是 `Value`。
要让函数体成为单元格内容,必须先让「代码」成为值——即 `Value::Code` 那种东西。
而 `Value::Code` 目前**只表示外联语言源码**(```lang 围栏),是交给外部执行器跑的,
不是 Marqdo 自己的代码。让 Marqdo 代码变成值 = 引入 `eval`,这会带来:
- 静态检查失效(代码在运行期才成形,`marqdo check` 看不见)
- EKC 指纹失效(§6.2)
- 契约失效(§6.1)
### 4.3 断裂点三:调用不是取元——`[k](x)` 会被语义重载
这是最要命的一条,**与上一轮 `[函数名](参数)` 的冲突同源**。
若「函数是表」且「调用 = `[参数](函数表)`」,那么:
```markdown
[a](m) # m 是普通 Map → 取成员 a
[参数](f) # f 是「函数表」→ 执行?还是取成员「参数」?
```
**形状完全一致,含义取决于值的类型**。这正是上一轮我们判定「不可靠消歧」的同一类问题,
只不过从「语法层歧义」升级成了「类型层重载」。
Marqdo 的 `[k](coll)` 目前是**唯一且清晰**的取元语义。让它兼职「调用」,
会让最常用的读表操作变得需要思考「这个表是不是函数」。
---
## 5. 五条设计路径
### 路径 A — `Value::Func` 闭包(一等函数)
```rust
Value::Func(Rc<FuncVal>) // params + body + captured Env
```
调用点需支持「对表达式求值后再调用」,即 `CallExpr.callee` 从 `String` 变成 `Callee::Name(String) | Callee::Expr(Expr)`。
**代价**:
| 面 | 影响 |
|----|------|
| 契约(T2.1/T2.2) | `call_arg_diag(c, &target.name, …)` 依赖静态 `target: &Function`;动态调用**拿不到**,契约检查只能退化为运行期 |
| 字节码 | `Op::Call(fid, argc)` 用**编译期函数 id**(`src/bytecode/compile.rs:709`),动态 callee 需要新指令或回退树遍历 |
| EKC 指纹 | `collect_calls` 读 `c.callee`(`src/knowledge/fingerprint.rs:76`),动态调用只剩字面 `call_fn`,**复用/查重能力下降** |
| 序列化 | `value_to_json`(`src/host/json.rs:98`)对 `Value` 穷举,函数值必须定义 JSON 语义(丢弃?报错?) |
| 沙箱 | 函数值无法跨沙箱边界,`sandbox.run` 的接口要加限制 |
| 闭包捕获 | 需要环境快照与生命周期管理;`Env` 目前是每次调用新建(`Env::new()`) |
**适用于**:确有高阶需求(回调、map/filter、事件处理)。属于**新语言特性**,应走 ADR。
### 路径 B — 函数即表(你的草图,强主张)
**代价**:A 的全部,**外加** §4.3 的语义重载,以及:
- 表可以 `table.put` 被修改 → 函数可变?还是只读?
- 表可以遍历 → 遍历函数会看到什么?参数名?函数体 AST?
- 表可以 `json.stringify` → 函数体以什么形式序列化?
- 宏展开式的能力(代码即数据)会引入**自修改程序**,与「可静态审计」直接冲突
**结论**:**不建议**。它把 Marqdo 从「可静态索引的文档程序」推向「运行期构造的代码」,
是在削弱自己最强的差异点(§6)。
### 路径 C — 对象可调用(复用 `_type` + 约定方法)
让 `# 类名` 实例在 `_type` 之外带一个约定的 `## 应用` 方法,`f(x)` 时若 `f` 是 map 且 `_type` 有该方
法则走方法调用。
**优点**:不新增 `Value` 变体;复用既有 method 机制。
**缺点**:仍需要「`f(x)` 里 f 是表达式」这一语法能力(同 A 的调用点改造);
且引入「有的 map 可调用」的隐式规则,可读性下降。
### 路径 D — 名字即函数(扩展现有 `call_fn`)
不引入函数值,而是把**名字**这条路径做完整:
```markdown
> call_fn name="add" args=[1, 2] # 支持传参
> call_fn name="txt.str_trim" args=[…] # 跨模块路径
> invoke table=`注册表` key="h" args=[…] # 从表里按名派发
```
**优点**:
- 零值模型改动 → 契约、字节码、指纹、序列化**全部不动**
- 保持「函数永远有名字」→ EKC 能索引,代码可审计
- 与实验 4 的现有用法完全兼容(只是补齐能力)
**缺点**:不是真正的一等函数(不能返回闭包);名字拼错仍要运行期发现
(但**可以**加静态检查:`call_fn name="字面量"` 时校验目标存在——见 §8.2)。
### 路径 E — 决策表作为一等公民(**推荐方向**)
不叫它「函数即表」,而明确它是什么:**有限域查表函数**。
```markdown
**税率 = > json.parse text={"1":0.03,"2":0.10}** # Map:键 → 值
**t = [2](`税率`)** # 今天就能跑 → 0.1
```
**优点**:**零语言改动**,只需文档与库函数支持(例如 `table.lookup` 带默认值,
把 §1.1 配方 B 的「列取 + 索引」四步压成一步)。
**定位诚实**:它是数据,不是代码;能被 EKC 索引、能序列化、能进沙箱、能被非程序员维护。
---
## 6. 对 Marqdo 特有机制的冲击面
这一节是决策的关键:Marqdo 不是通用语言,它的价值在**可静态索引的工程知识**。
### 6.1 契约系统(T2.1 / T2.2)
现有实现把契约挂在 `Function` 上(`src/ast.rs:71`),并在调用点用**静态 target**校验:
```rust
if let Some(c) = &target.contract {
if let Some(d) = contract::call_arg_diag(c, &target.name, &bound, …) { … }
}
```
动态 callee 拿不到静态 `target`,**契约检查必然退化到运行期**——而契约是 Marqdo
「渐进式契约」卖点的核心。
### 6.2 EKC 指纹与复用
`collect_calls` 把调用目标名字写进指纹(`src/knowledge/fingerprint.rs:76`)。
指纹用于**查重、复用预检、相似任务召回**。动态调用使指纹丢失真实目标,
`marqdo duplicate` / `preflight` 的准确率会下降——这直接影响智能体复用飞轮。
### 6.3 「函数必须有名字」是特性,不是限制
EKC 按符号名索引(`marqdo knowledge` 输出 `59 modules, 346 symbols`)。
匿名函数/表构造的函数**无法被索引**,也就无法被复用、被审计、被智能体发现。
> 对 Marqdo 而言,**函数有名字**不是妥协,而是「代码即文档」的必然:
> 文档里的每一段代码都得有一个可被引用的标题。
### 6.4 序列化与沙箱
`value_to_json` 穷举所有 `Value`。函数值需要 JSON 语义;
沙箱(CoW + 禁 exec/net/plugin)跨边界传值时,函数**无法表示**。
一旦函数成为值,`sandbox.run` 的入参约束必须收紧。
### 6.5 确定性与可审计
表格是**静态可读**的:非程序员能改税率表。代码构造的函数则要求读者在脑中执行程序。
Marqdo 面向的是「文档作者也能维护」的场景,这一点权重很高。
---
## 7. 方案对比
| 维度 | A 闭包 | B 函数即表 | C 可调用对象 | D 扩展 call_fn | E 决策表 |
|------|--------|-----------|-------------|---------------|----------|
| 值模型改动 | **需新变体** | 需新变体+代码即值 | 无 | **无** | **无** |
| 保持静态可索引 | 部分(匿名不可) | ❌ | ✅ | ✅ | ✅ |
| 契约检查 | **退化** | 退化 | 保持 | 保持 | 保持 |
| EKC 指纹 | 退化 | 退化 | 保持 | 保持 | 保持 |
| 序列化/沙箱 | 需特殊处理 | 需特殊处理 | 保持 | 保持 | 保持 |
| 解决参数边界 | ✅ | ✅ | ✅ | ✅ | ✅ |
| 支持无限定义域 | ✅ | ❌ | ✅ | ✅ | ❌(本质限制) |
| 实现成本 | 高 | 很高 | 中 | **低** | **零** |
| 风险 | 中高 | **高** | 中 | 低 | 无 |
---
## 8. 建议(分阶段)
### 8.1 立即可做:决策表(路径 E)
零语言改动。补三件事即可让它好用:
1. **补库缺口**:新增 `table.lookup map=`key=`default=`(键→值,缺键返回 default)与
`table.by_column rows=`key_col=`value_col=`key=`(把 §1.1 配方 B 的四步压成一步)。
**这是当前最实的缺口**——GFM 两列表无法直接键查表,用户会反复手写索引逻辑。
2. **文档**:在教程里明确「有限域映射怎么表达」,并给出三种形态的取舍:
- 键→值查表 → `json.parse` 的 Map + `[键](map)`
- 需要保留表格可读性 → 两列表 + `table.by_column`
- 缺键行为 → 用 `table.get` / `default=`,避免缺陷 D5 的 `missing map key` 硬崩
3. **命名**:明确它叫「决策表 / 查表」而不是「函数」——避免与 §1.2 的内涵观混淆。
**价值**:把用户已有的直觉固化成推荐用法,不付任何架构代价。
### 8.2 短期可做:扩展 `call_fn`(路径 D)
补齐三件事,都不触及值模型:
| 补充 | 说明 |
|------|------|
| `args=` | 允许传参,按目标签名绑定 |
| 跨模块路径 | `name="lib.fn"` 走 import 解析 |
| 字面量静态校验 | `call_fn name="字面量"` 在 `check` 期就校验目标存在(消灭实验 6 的类错误) |
**收益**:动态派发能力完整,且完全保留契约/指纹/序列化。
### 8.3 中期评估:一等函数(路径 A)
只有当出现**确实无法用名字表达**的需求时才做(例如回调、策略模式、事件处理器)。
届时必须写 ADR,并明确回答:
- 匿名函数如何进入 EKC 索引?(可能需要要求「赋给变量的函数字面量必须有名字」)
- 契约在动态调用下如何降级?
- 字节码是否引入 `Op::CallValue`?
- 函数值的 JSON 语义是什么?
### 8.4 不建议:路径 B(函数即表,强主张)
理由汇总:§4.3 语义重载 + §6 全面削弱静态可索引性 + §5 自修改程序风险。
---
## 9. 如果你想保留「函数即表」的形态,有一个折中
把「表」用于**参数与分发**,而不用于函数体:
```markdown
`税率表` =
| 档位 | 税率 |
|------|------|
| 1 | 0.03 |
| 2 | 0.10 |
## 税率
+ `档位`
**ks = [档位](`税率表`)**
**vs = [税率](`税率表`)**
**i = > table.index_of list=`ks` item=`档位`**
**r = > table.at xs=`vs` i=`i`**
*r*
```
(若 §8.1 的 `table.by_column` 落地,函数体可缩成一行:
`**r = > table.by_column rows=`税率表` key_col="档位" value_col="税率" key=`档位`**`。)
这里:
- **数据**在表里(可被非程序员维护、可序列化、可进沙箱、可被 EKC 索引)
- **逻辑**在命名函数里(可契约、可指纹、可审计)
- 调用仍是一等清晰的 `> 税率 档位=2`
这其实是**最好的分工**:表格承担「知识」,函数承担「行为」。
它同时满足你的类比直觉(表驱动)和 Marqdo 的静态可索引性。
---
## 10. 待你决策
1. **方向**:选 E(决策表,零改动)、D(扩展 call_fn)、还是 A(一等函数,需 ADR)?
2. 若倾向 D:`args=` 的参数形式用 `[1, 2]`(列表)还是 `a=1 b=2`(具名)?
3. 是否要我把 §9 的「数据在表、逻辑在函数」写成教程规范?
4. 是否存在**具体用例**驱动一等函数?(例如某个 ext 需要回调)
若有真实用例,评估会完全不同——请给我场景,我按场景重新评估。
@@ -0,0 +1,326 @@
# 隔离执行与响应式 Web 运行时:详细开发设计
| 项目 | 约定 |
|---|---|
| 状态 | **Verified**(execute 路径);HTTP `execute` / `sse-live` / `stream:true` 默认走 Supervisor worker 池(不再经父进程 `CallLibPath` / `INVOKE_LOCK`);`runtime.isolated_execution=1`;MR-01 金样例 `tests/isolated_execute_mr01.rs`;未声明非流式仍 `legacy_serial`(ADR 0008) |
| 基线 | Marqdo `1b11fe0` / 2.1.3;qdagent `64b97e5`;2026-10-26 |
| 问题依据 | [单解释器缺陷](web-invoke-serialization.md)、[ADR 0008](../adr/0008-web-invoke-serialization.md)、[本轮跨库复核 R01–R14](../../../qdagent/doc/gaps/04-workbench-runtime-and-product-audit-2026-10-26.md) |
| 产品配套 | [qdagent 可靠工作台开发设计](../../../qdagent/doc/design/reliable-workbench-development-2026-10-26.md) |
| 继承合同 | [工作台 M00–M06](qdagent-workbench-runtime-and-view-2026-10-25.md) 中 ModelSelection、ModelSnapshot、Usage、DocumentView、Locator;保留文档原生作者面 |
## 1. 目标、边界与不变量
目标是让用户在长对话、导入和构建过程中持续打开模型列表、读取来源、修改下一轮设置并可靠停止任务。高并发容量按资源预算显式限制;不能让所有请求进入一把解释器锁再超时。
Marqdo 负责通用执行隔离、资源调度、事件/取消、语义分析和制品校验。qdagent 负责用户/工作区授权、业务状态与发布政策。产品仍通过 `.mq.md` 调用 Marqdo Agent,不增加第二套模型循环或知识编译器。
必须保持的系统不变量:
1. 同一个可变 HostContext 同时最多一个求值者;不删除锁、不增加虚假的 `unsafe impl Sync` 来获得并行。
2. 一个执行租约只属于一个 run/attempt;凭证、事件、取消、cwd、权限和模型选择不可流入另一请求。
3. 控制与读取具有独立容量,不被 LLM 等待占满;停止不需要重新进入正在执行的解释器。
4. 事件可以重投,外部副作用不默认重做;不宣称跨网络 exactly-once。
5. 已确认终态不能被晚到完成/取消覆盖;取消不回滚已经完成的外部写入。
6. 阅读不执行 `.mq.md`,缓存不绕过授权或版本校验;缓存命中必须实际复用结果。
7. 正文、依赖、证据和编译代属于同一不可变快照;不会把两个代的结果拼成一次阅读或执行。
8. 任何能力开关都以实际探测和测试为依据;新 API/schema 在落地前都属于本文提案。
## 2. 架构选择
| 方案 | 优点 | 当前代价 | 本轮选择 |
|---|---|---|---|
| 继续全局锁,只增加 Go handler | 改动小 | 长任务依然阻塞所有 Endpoint,串扰变量也未消失 | 只保留作兼容模式 |
| 同进程多 HostContext | 潜在内存复用较好 | GLOBAL_HOST、插件回调、环境、cwd、事件 sink 生命周期需系统重做 | 后续优化,不是首个交付门槛 |
| 独立 Marqdo worker 进程 + 控制/读取通道 | 隔离现有全局状态,可强制回收卡死任务,复用现有语言与 Agent | IPC、进程启动、内存、发布写协调 | **首选实现** |
| 引入外部通用队列和新业务 Runtime | 容易扩到集群 | 运维复杂度及第二套编排风险 | 单机阶段不引入 |
首期采用**预热的一次性执行进程池**:进程可预装运行时和非用户特定模块,分配任务后独占,结束即退出并异步补充。这样不用假设清空部分字段就能安全复用 HostContext。长寿命多租约 worker 只有通过状态泄漏、插件资源与 RSS 回归后才开启。只读分析服务可以长寿命运行,但不得加载有副作用的求值插件。
```mermaid
flowchart TD
UI[浏览器 / CLI / MCP] --> WEB[Go HTTP / 认证入口 / 限流]
WEB --> CTRL[任务控制与事件服务]
WEB --> SHORT[短业务请求容量]
WEB --> READ[只读分析服务]
SHORT --> POLICY[qdagent .mq.md 授权与业务规则]
POLICY --> CTRL
CTRL --> DB[(任务索引 / outbox / 事件日志)]
CTRL --> SUP[Rust Supervisor / 有界调度]
SUP --> A[Marqdo worker A / 一个租约]
SUP --> B[Marqdo worker B / 一个租约]
A --> AGENT[既有 Marqdo Agent / LLM / sandbox]
B --> AGENT
A --> STAGE[每任务暂存目录]
B --> STAGE
STAGE --> COMMIT[按资源串行提交与 revision CAS]
COMMIT --> SNAP[(不可变知识代 / 发布 manifest)]
READ --> SNAP
A --> CTRL
B --> CTRL
CTRL --> UI
```
“短业务请求容量”依旧可执行产品 `.mq.md`,但有独立 worker 预算和短 deadline。控制服务只做通用接纳、状态 CAS、取消与日志投递,不把模型选型、知识晋升等业务逻辑搬进 Go。读取服务接收经过授权的资源句柄;不得直接相信浏览器提交的绝对路径。
## 3. 路由分类与接纳
### 3.1 执行类别
在 Endpoint 装配中新增可选 metadata(字段名待 schema 固定):
| 类别 | 示例 | 资源预算与规则 |
|---|---|---|
| `control` | 任务查询、事件订阅、取消、health | 不执行用户代码;认证后访问任务存储/租约注册表 |
| `read` | view.document、引用解析、已发布模型列表投影 | 只读快照;不写用户源码;可缓存 |
| `short` | 保存设置、创建导入、接纳任务 | 无 LLM 长等待;默认 deadline 2s,较慢动作转为任务 |
| `execute` | ASK/BUILD/生成/验证 | 有界队列、专属进程、显式任务 deadline |
| `commit` | 切换知识代、合并受控文件变更 | 按 workspace/kb 的短临界区;执行前检查 revision |
旧 Endpoint 未声明时仍走 legacy_serial;不能自动猜测任意函数是纯读。纯度来自静态能力和注册配置,实际写权限仍由宿主限制。文件上传字节传输不占解释器,应先落隔离存储,再进入短接纳路径。
### 3.2 接纳步骤
1. HTTP 层解析受限请求,验证身份、格式、速率与连接数量。
2. 产品短入口解析 workspace/model/policy;授权版本与模型配置 revision 一并冻结。返回规范化任务请求,不执行 Agent。
3. 控制服务在同一数据库事务中登记作用域化 idempotency key、payload hash、task 和 dispatch outbox;重复请求读回已有 task,同键异内容返回 409。
4. 提交事务后才返回 202/Location。调度器消费 outbox 分配租约,租约带 attempt/epoch。
5. 对同步兼容 API,先完成接纳,再挂接结果;等待客户端超时不等于安全重做。
队列入库前容量不足返回 429 + Retry-After;服务不可用返回 503;接纳失败不发送 started。控制通道须保留槽位,不能因为数据流连接占满而无法取消。
## 4. Supervisor、生命周期与调度
### 4.1 Worker 生命周期
`starting → ready → leased → running → draining → exited`;启动失败/心跳丢失走 `unhealthy → terminating → exited`。任务状态由控制服务维护,进程状态不能直接当作业务成功。
- worker 启动握手报告 CLI/ext/native、protocol_version、能力、构建摘要;不匹配不进入 ready。
- 预热阶段不读取用户凭证、不挂载工作区写权限。分配租约后挂载当前任务的 capability roots、只读快照和独立 staging。
- 每任务具有随机 lease_id、run_id、attempt_id、epoch、绝对 deadline 和资源限制。
- Supervisor 持有进程句柄、子进程组、事件通道与取消句柄。worker 不能自行修改其他 worker 状态。
- 返回业务结果后仍须 drain 事件/用量并提交最终 checkpoint,控制服务持久化终态后确认 ACK,之后释放租约。
- 超时或断连清理不能遗留孤儿子任务;正常优雅退出后再删除临时文件。异常由独立 janitor 按租约过期回收。
### 4.2 有界、公平与资源预算
初始验证配置建议 4 vCPU/8 GiB、执行槽 2、短请求槽 1、读取服务 1。具体容量由每类任务的 RSS p95 和 CPU profile 决定,不能把这个数当所有机器的默认。执行槽上限:
`min(CPU约束, floor((可用内存 - 系统/控制/缓存预留) / worker_RSS_p95))`。
运行队列按 workspace 轮转,再按 session FIFO;一个 session 默认只允许一个活动 turn,跨 session 可并行。相同知识库的生成可并行,发布只占短提交锁。interactive 优先于后台索引,但后台使用老化提升或最低服务配额,防永久饥饿。
全局队列初始上限 64、单工作区 16、单会话待处理 4,均可配置;队列超限及时返回,不能悄悄丢任务。显示队列位置或“前方有任务”,没有可靠完成时间估计时不显示虚构倒计时。
### 4.3 副作用与重试
任务声明 `read_only / staged_write / external_effect`,由工具权限校验而非模型自报。read_only 可按政策重试;staged_write 丢弃未提交 staging 后重试;external_effect 出现超时/失联时标记 `effect_unknown`,等待核对,不自动重复支付、发信或写入。
稳定的操作键使用 `task_id + logical_step_id`,attempt_id 只标记传输尝试,不应导致同一外部动作生成新的去重键。工具不支持幂等查询时,只能明确报告不确定。工作簿记录已完成与未知副作用;“已停止”不意味着“全部撤销”。
## 5. IPC 与请求上下文
首期使用本机 Unix socket 或匿名管道,采用长度前缀 JSON 控制帧与独立事件通道。协议禁止无上限 JSON/单行日志;控制帧初始上限 1 MiB,大文档通过授权 blob handle 传递。普通 stdout/stderr 仅诊断,不与协议混流。当前 NDJSON 文件桥保留为 legacy fallback。
新增 `InvokeRequestV2` 示例(提案):
```json
{
"schema": "InvokeRequestV2",
"schema_version": 2,
"task_id": "task_01",
"run_id": "run_01",
"attempt_id": "attempt_01",
"lease": {"id": "lease_01", "epoch": 3},
"entry": {"module": "agent/qdagent.mq.md", "function": "run"},
"args_ref": "blob:sha256:...",
"context": {
"workspace_id": "ws_01",
"snapshot_id": "generation_01",
"selection_ref": "model-snapshot_01",
"capabilities_ref": "grant_01",
"deadline_at": "2026-10-26T08:10:00Z"
}
}
```
`grant_01` 是服务端验证的短寿命授权句柄,内容包括 principal、scope、根目录、允许效应、授权 revision、失效时间。worker 不使用浏览器任意传入的 fn/path。权限撤回后,新的工具调用必须重新验证 lease/grant,已开始的外部调用记录撤回时间与实际结果。
`RunContextV1` 保留原有字段与序列化兼容,内部增补显式 Context 对象;扩展 V2 由能力协商启用。event_sink、usage_sink、cancel_token 使用句柄,不使用外部可控路径。子任务通过 IPC/Command.env 显式继承,禁止父进程 `setenv`/`set_current_dir` 承担请求状态。
凭证在租约启动时通过受保护 IPC 或继承 FD 注入;不落任务 JSON、argv、日志或通用事件。模型快照可含 credential_ref,不含 api_key。即使选择相同 provider,不同请求的授权也不得合并。
## 6. 取消协议与状态 CAS
任务基础状态:`accepted → queued → running → finalizing → succeeded/failed`;queued/running 可进入 `cancel_requested → cancelled`;worker 失联进入 `interrupted`,副作用不明时进入 `needs_reconciliation`。这些是提案,产品可以将 succeeded 映射为 completed。
取消顺序:
1. 验证调用者对 task 的权限,CAS 写 cancel_requested、revision 与 requested_at;终态返回原状态,未知 ID 返回 404。
2. 向匹配 lease/epoch 的控制通道发送 Cancel;不经任务解释器锁。queued 任务原子移出待派发队列。
3. worker 在每次 LLM/工具调用、重试、子任务启动和提交之前检查 token;网络请求使用可中断句柄,不能仅在一行输出结束后才检查。
4. 收到 ACK 仍不等于任务停止。等待 worker 报 stopped、落未完成副作用和用量,再 CAS 到 cancelled。
5. 默认 2s 协作宽限、额外 3s 进程退出宽限,之后回收进程组。强制退出记 interrupted/needs_reconciliation,不能伪造干净 cancelled。
完成与取消竞争的线性化点是控制存储的 CAS:终态先提交则 cancel 返回 already_terminal;取消先提交则晚到 result 只可作为证据追加,不能重新变 succeeded。若外部动作已发生但响应晚到,记录 effect outcome,不撤销取消事实。
兼容文件 token 统一:不存在/空/`0` 为未取消,`1`/`cancelled` 为取消;读取失败返回诊断并按明确策略处理。删除 token 只能发生在持有者退出之后。移除全局 `MARQDO_CANCEL` 对多个任务的隐式作用域。
## 7. 事件、SSE 与背压
### 7.1 事件权威
生产者发出 `(run_id, attempt_id, local_seq)`,控制服务去重、持久化并分配 task 内单调 seq/event_id;客户端游标来自持久化日志,不是 handler 重连后从 1 开始计数。终态事件唯一,usage 可以在终态后以更高 usage revision 补录,但不能再次结束任务。
```json
{
"schema": "RuntimeEventV2",
"schema_version": 2,
"event_id": "task_01:42",
"seq": 42,
"task_id": "task_01",
"run_id": "run_01",
"attempt_id": "attempt_01",
"type": "message.delta",
"payload": {"message_id": "msg_01", "offset": 24, "text": "结果"}
}
```
不要直接破坏 RuntimeEventV1;新增字段/新版本由能力协商确定。普通用户可见 progress 只描述工具、阶段、文件等结构化事实;模型内部 reasoning 不作为完成证据,也不默认写入公开事件。
### 7.2 App SSE
新增任务 API 的事件订阅用 `GET /tasks/{id}/events`(最终产品前缀见配套设计),发送 SSE `id`/`event`/`data`;每个 data 是一个完整 JSON。客户端支持 Last-Event-ID、CRLF、多行 data、任意 UTF-8 分块和 EOF 未完成帧。重复事件按 ID 去重;message offset 检查缺口,缺口时恢复快照。
心跳 15s,客户端空闲探测建议 45s;二者可配置。事件保留建议 24h,最终结果/审计按项目政策更长保留。游标早于保留边界返回 410 `event.cursor_expired` 和快照入口,不能默默从最新开始丢字。
订阅断开默认只关闭订阅。App 显式停止通过 cancel API,切页/移动网络重连可恢复同一任务。传统同步 OpenAI 调用可保持 disconnect=cancel 的兼容策略,但必须显式区分,不能统一把所有浏览器断流当取消。
### 7.3 OpenAI 兼容流
`/v1/chat/completions stream=true` 输出 OpenAI chunk 与 `[DONE]`;App 运行事件由独立入口或协商的协议提供。禁止仅凭任意 JSON body 中 stream=true 将不相关路由自动改为 RuntimeEvent 协议。已发 header 后的错误使用该协议允许的错误帧;发 header 前可用 429/503/401 等正确状态码。
token delta 与最终完整答复分开:最终事件持有结果引用/摘要和 finish reason,不再次追加整篇正文。无 token 能力的适配器报告 `evented_batch`,界面用阶段状态,不把整包人为拆字伪装成实时。
### 7.4 背压和旧桥修复
worker→事件服务与服务→订阅者均有界。建议每订阅者 256 KiB 待发送内存,超出后断开慢消费者并允许按游标重连;事件正文已持久化所以不能静默丢 token。允许合并短时间 delta,必须保留 message offset;usage/终态/错误不丢弃。磁盘压力时停止接纳新任务,已有任务使用保留终态空间并按策略中断,不能无限写事件。
legacy NDJSON tailer 只消费换行已完整到达的字节;保留残片,offset 按真实消费字节移动。超长行、I/O error、文件旋转显式报协议错误。测试至少分三次写一个 JSON、中文多字节边界、恰好 EOF、超过上限、取消与尾帧竞争。禁止吞掉 Scanner.Err() 继续宣告成功。
## 8. 只读快照与真正有效的缓存
### 8.1 快照一致性
分析服务构建 SnapshotKey:规范化 project identity、允许扫描范围、源文件闭包摘要、依赖/来源/配置摘要、compiler/lib/ext 版本、policy/schema、解析选项。输入由编译器枚举,不另造“前 200 个根目录文件”规则。
读取一次快照内的正文、语义和来源,完成后复核输入 manifest;文件在分析中发生变化则重试一次或返回 `snapshot.changed`。对不可变发布代直接读其 manifest。mtime/size 只用于快速发现候选变更,不能代替内容摘要;watcher 丢事件后以完整扫描修复。
### 8.2 缓存结构
- `AnalysisCache<SnapshotKey, Arc<Compilation>>`:实际编译结果。
- `DocumentCache<(SnapshotKey, document_digest, renderer_version, view_options), DocumentView>`:安全 fragment、outline、nodes。
- 同 key single-flight 的 follower 等待同一个 Result,不再次 compile。
- RAII guard 在 error/panic/cancel 时清除 inflight 并唤醒 waiters;等待者有自己的 deadline。
- compile 失败只返回给当前等待者,短暂错误缓存需显式 TTL;不得调用“finish_success”标记失败结果可复用。
- LRU 按字节而非条数上限管理;初始预算按部署内存的 10% 且设硬上限,长文档超限不缓存或分页;记录淘汰原因。
- 每次读取先授权再查缓存;权限敏感的响应按 scope/policy 分区。全局缓存只共享不含用户秘密且访问已验证的不可变语义数据。
性能证据必须统计 `compile_invocations`、输入字节、缓存结果命中、leader/follower、wait_ms、evictions;现有 hit counter 不能证明减少编译。
### 8.3 HTML 与来源定位
沿用 DocumentViewV1,明确 `render.format=plain_text|sanitized_html`。HTML 通过解析器白名单清洗标签/属性/URL scheme,剥离脚本、事件属性、危险 CSS/嵌入与可执行 SVG;相对资源经受限资源端点解析。纯文本始终转义,不以 `<` 字符判断类型。
node_id、revision、generation 必须从定位到读取到浏览器滚动完整传递。不存在历史快照返回 version_unavailable;返回当前版是用户显式操作且标明版本变化。no_exec 测试分别验证“无语言副作用”和“浏览器无脚本执行”,二者不能互相替代。
### 8.4 首次编译的性能改造
本轮 `v3_corpus_1000_compile_smoke` 在 debug 下 243.012s,超过既有 180s 门禁;缓存不能缩短一个全新项目的第一次编译。先为 `knowledge::compile` 的语义编译、语义落盘、检索 extract、检索落盘、manifest 分别加 span,再细分 `ProjectIndex::build`、源枚举/解析、导入挂接、绑定、效应传播、闭包摘要。记录文件数/总字节、节点/边数、parse 次数与序列化字节量。
源码中 `sema::compile_project` 在每个文件查找 module path、每个 module 过滤全量 symbols,属于值得测量的重复扫描;未取得 profile 前不将其认定为 243s 的唯一根因。优化候选按证据选择:建立 path→module 与 module→symbols 索引;同一输入快照共享 parsed module;绑定/依赖图用稳定索引;效应传播用 worklist;闭包按 SCC DAG 计算并保留循环依赖语义;减少每制品重复序列化和小文件写入。
任何优化须保持排序确定性、SymbolId/ArtifactId 与证据摘要规则,禁止通过跳过来源校验、删掉复杂 fixture 或改大超时过关。用 100/1000/10000 单元、无依赖/链/菱形/循环四种图分别测时间与 RSS;给出随 V/E 增长的曲线。release 和 debug 分开;已有 debug 门禁恢复通过只是第一步,§12 的 release 预算仍须独立验收。
## 9. 写入、发布与数据库边界
执行 worker 只写任务 staging;需要写工程时通过沙箱产生文件 diff。发布以 kb 资源锁 + expected_generation CAS 提交。锁只覆盖校验当前版本和切换 manifest,不覆盖 LLM、全文编译或网络调用。
完整发布代先写临时目录、校验摘要、完成必要 fsync,再原子 rename 到不可变 generation 目录;最后在同一文件系统原子替换 CURRENT。源码、编译投影和证据在该 manifest 下对齐。SQLite 中的产品“published”是投影,不参与虚构的文件/数据库跨系统原子事务。通过 publish journal + outbox 恢复:CURRENT 已切换但 DB 未更新时重放;未切换时旧代继续有效。
project_id 与逻辑文档 ID 不随 staging/generation 的物理目录名变化。manifest 保存稳定 project identity、逻辑相对路径和实际 blob/generation 映射;导入引用按项目规则解析,不能因复制到发布目录而重新生成全部符号身份。框架若尚不能区分逻辑身份与物理根,先补该能力,再启用 generation 目录发布;迁移 fixture 必须断言未修改的知识 ID 和跨文档绑定保持稳定。
任务表/幂等/CAS/outbox 需要通用事务能力:先审计 `ext/data` 是否支持事务、条件更新、受影响行数、复合唯一键;缺少则在 Marqdo 数据层补齐,不能用 `.mq.md` 的先读后写模拟原子性。SQLite 使用短事务和有界 busy timeout;WAL/连接池是否开启需按现有插件适配测试确认。单主本地盘为首期部署范围,跨主机共享 SQLite/NFS 不在首期承诺内。
## 10. 临时缓解与迁移
### 10.1 进程池完成前
- 保留 1500ms busy 预算和 Retry-After;展示繁忙,而非无限 spinner。
- 在接纳任何 SSE 之前取得覆盖整个 bridge 生命周期的 legacy 单飞许可,第二条流在修改环境变量/发送 200 前失败;普通请求不得绕过许可观察被污染的状态。
- 断连只标记该任务取消,清理由监督者等待执行结束后负责;无法确认停止时报告 stopping/interrupted。
- 上述步骤只降低 R02/R03 风险,仍不算并行 Endpoint。
### 10.2 功能开关(新增提案)
`runtime.isolated_execution`、`runtime.task_control_v2`、`runtime.event_replay`、`view.analysis_cache_v2`、`runtime.read_lane`。探测返回 feature version 和限制。二进制版本相同不等于所有 native 插件都有该能力。
先离线 fixture → 本地假模型 → 新 workspace → 只读 ASK → staging BUILD → 真正发布。禁止对有副作用的请求做双执行 shadow;允许 shadow 只读分析并比较摘要。
回滚先停接新任务、drain 已接纳任务、保留任务/事件和新 schema;不能将活动任务交给不认识 lease 的旧进程。只读当前发布代可以保留,写入能力按版本协商关闭。ADR 0008 仅在并行金样例与回滚演练通过后由新 ADR 正式替代。
## 11. 开发包与依赖
下列新模块路径是建议,不代表文件已存在。
| 包 | 建议落点与改动 | 前置 | 验收 |
|---|---|---|---|
| M-R0 基线/缓解 | `host/plugin.rs`、`httpx/routes_invoke.go`;固定并发屏障、旧桥许可、取消清理 | 无 | 双流 busy 不改写 A 的桥;断连无提前清理 |
| M-R1 请求上下文 | `workbench/run_context.rs`、`host/subtask.rs`、LLM 插件;统一 token 与显式 sink | M-R0 | 父子运行模型/事件/取消不串;空 token 不取消 |
| M-R2 Worker/IPC | 新 `runtime/{supervisor,worker,protocol,lease}.rs`;独立进程与握手 | M-R1 | 两任务并行、超时回收、子进程无孤儿 |
| M-R3 接纳/控制 | 新 `runtime/{task_store,scheduler,control}.rs` 与 ext/data 事务 primitives | M-R2 | 原子幂等、队列公平、取消与结果 CAS |
| M-R4 事件协议 | `workbench/event_sink.rs`、Web stream/IPC、协议适配器 | M-R3 | 断点恢复/去重/半帧/慢消费/磁盘错误 |
| M-R5 读服务/缓存 | `analysis_cache.rs`、`document_view.rs`、`locator.rs`、MLSP transport | M-R1,可独立推进 | 100 同 key 真正只编译一次;嵌套变更正确失效 |
| M-R5b 首次编译性能 | `knowledge/compile.rs`、`sema/ir.rs`、ProjectIndex;分阶段 profile 与按热点优化 | 基线语义回归 | 现有 1000 单元门禁恢复;release 与规模曲线报告,身份和语义不变 |
| M-R6 提交底座 | `knowledge` generation/manifest、publish journal、条件更新 | M-R3 | 崩溃点恢复,旧代不被半发布污染 |
| M-R7 整合与发布 | 版本探测、CI、release、文档/ADR | M-R4–R6 + 产品接入 | §12 全部必要门禁与回滚演练 |
先以本地文件和单机进程解决明确缺陷;不要把集群、远程 worker、复杂 Actor 系统设为第一阶段依赖。
## 12. 验收、性能预算与可观测性
### 12.1 正确性矩阵
| 编号 | 场景 | 必须观察到的结果 |
|---|---|---|
| MR-01 | A/B 两个 60s 假模型流 + 20 次/s 模型/设置读取 | 两流不混字、不混模型;短请求 200;无 interpreter busy |
| MR-02 | B 在 A 运行时接纳失败/断连 | A 事件和取消句柄完全不变 |
| MR-03 | 同时取消 A、完成 B;取消重复/晚到 | A 正确停;B 成功;终态不回退;审计只结算一次 |
| MR-04 | 帧拆字节、多行、EOF 半帧、重连 | 无丢字/重字;协议错误可见;游标恢复精确 |
| MR-05 | 慢消费者、磁盘满、worker 崩溃 | 内存有界;事件不静默丢失;状态可恢复 |
| MR-06 | 100 个相同读取并发 | 实际编译一次;后续结果复用;失败 leader 不挂死 follower |
| MR-07 | 改子目录依赖、第 201 个文件、配置、来源 | SnapshotKey 改变;缓存失效;旧业务句柄拒绝 |
| MR-08 | 上传有写文件/网络代码、HTML 事件属性 | 阅读不求值;浏览器脚本不执行;正文可读 |
| MR-09 | 发布每个持久化边界 kill | 仅旧完整代或新完整代可见;DB 投影最终追上 |
| MR-10 | 并发幂等请求、取消队列、权限撤回 | 单一 task;同键异内容 409;无越权派发 |
| MR-11 | kill 后副作用未知 | 不自动重放,显示 needs_reconciliation |
| MR-12 | 降级/升级、混合 CLI/ext/native | 缺能力明确禁用,不报已支持 |
### 12.2 性能目标(待测验收预算)
基准机:Linux 4 vCPU/8 GiB SSD;release 构建;1000 个知识单元、文档总量 10 MiB、500 条历史 run;假上游固定 60s、每秒 20 个增量;30s 预热、5min 采样、3 轮,报告 p50/p95/p99、错误率、CPU、RSS、磁盘。另测 10k 单元和 100 MiB 以确定容量上限,不能直接沿用小数据阈值。
| 指标 | 初始预算 | 说明 |
|---|---|---|
| 短读/任务接纳 | p95 ≤200ms,p99 ≤500ms | 两个长任务运行时;过载拒绝另统计 |
| 取消受理 | p95 ≤200ms | 独立于任务停止耗时 |
| 协作取消收敛 | p95 ≤2s | 假上游/可中断工具;不可中断外部动作按不确定处理 |
| 已就绪 worker 调度 | p95 ≤100ms | 不含排队、模型首 token 时间 |
| 事件到订阅者新增延迟 | p95 ≤100ms | 从已收到 provider delta 计,不承诺上游 TTFT |
| 1000 单元首次分析 | p95 ≤2s | 候选目标,超标先剖析,不降低正确性 |
| 热 DocumentView | p95 ≤100ms | 真实复用结果;长文档另测分页 |
| 慢消费者缓冲 | 每订阅 ≤256 KiB | 总连接数也必须受限 |
| 压测结束内存 | 稳态可回收、无持续增长 | 记录每次重复轮次 RSS;不能只看一次峰值 |
新指标至少有 queue_depth/wait、worker_active/recycle、admission_rejected、cancel_ack/stop、orphan_count、event_lag/replay/duplicate、compile_invocations/cache_result_hit、publish_conflict/recovery。指标标签禁止 task_id、原始路径、prompt 等高基数/敏感值;trace 中可记录脱敏 task/attempt/lease 与构建摘要。
现有测试继续保留:`cargo test --offline --locked --test workbench_contracts --test executable_knowledge`、LLM 插件单测、Go httpx 测试。新增集成门禁必须启动真实 HTTP→IPC→worker 路径并使用本地假模型;不能以手写 fixture 或写 token 文件代替端到端行为。本轮执行结果统一记录在[跨库复核 §5](../../../qdagent/doc/gaps/04-workbench-runtime-and-product-audit-2026-10-26.md)。
+443
View File
@@ -0,0 +1,443 @@
# 知识分层:原始语料、可执行知识、调用面
| | |
|---|---|
| 状态 | **Design Review · Recommended(v2.1 语法设计评审)** |
| 日期 | 2026-10-23 |
| 问题 | 「诗人类 → 用李白知识实例化 → `[]()` 调用」的三/四层模型,从**语法设计**上是否自洽? |
| 推荐 | **单体知识类(singleton knowledge class)**:`# 诗人` 是类,`# 李白 = > 诗人` 是知识个体;`李白.出生年份` 是类调用;零新语法 |
| 关联 | [link-syntax.md](link-syntax.md) · [objects.md](objects.md) · [module-namespace.md](module-namespace.md) · [engineering-knowledge.md](engineering-knowledge.md) · [okf.md](okf.md) |
| 示例 | [examples/knowledge-layers/](../../examples/knowledge-layers/) |
---
## 0. 结论先行
### 0.1 一句话
> **分层逻辑是自洽的;不自洽的是「实例化」这个词与当前 `#`/`= >` 语法。**
> 如果「实例化」指**知识个体**,用 `# 李白 = > 诗人` 编码即可,零新语法;
> 如果「实例化」指**运行时对象**,就需要新的可寻址实例声明/注册表,语法成本明显更高。
### 0.2 三层 / 四层:推荐四层
| 层 | 名称 | 内容 | 语法载体 |
|----|------|------|---------|
| **L0** | 原始语料 | 原文、出处、引用、版本 | `.md` / `.mq.md` 叙述 + `来源` 表 |
| **L1** | 本体 / 模式 | 类、字段、类型、约束 | `# 诗人` + 字段/类型表 |
| **L2** | 可执行知识 | 知识个体、事实、返回值、出处 | `# 李白 = > 诗人` + `## 出生年份` + `*701*` |
| **L3** | 调用面 | 链接、类调用、view、LinkInfo、EKC、agent | `[出生年份](李白.出生年份)` |
三层版可以把 L1/L2 合并为「可执行知识体系」;四层版把**本体**与**个体**分开,正好对应 EKC 的 schema/knowledge 分层。
### 0.3 核心判断
| 判断 | 结论 |
|------|------|
| 原始语料 → 可执行知识 → 调用面,逻辑成立 | ✅ |
| 可执行知识能还原/验证回原始语料 | ✅ 需要出处/校验约定,语法上可行 |
| `# 诗人` 是类 | ✅ 现有 `#` 语义 |
| `# 李白 = > 诗人` 是「实例化」 | ⚠️ **语法上是继承/特化,不是运行时实例化** |
| `李白.出生年份` 是类调用 | ✅ 需要类函数 + 项目类索引(v2.1 目标) |
| `[]()` 是调用面,不新增语法 | ✅ `[描述](类.函数)` = 描述 + 已有调用 |
---
## 1. 你的模型(精确复述)
1. 有一个**诗人**类(`# 诗人`),定义诗人应该有什么字段/函数;
2. 用**李白的知识**把这个类「实例化」:
- 李白是诗人;
- 李白有姓名、出生年份等事实;
3. 通过 `[]()` 链接语法调用这个知识:
- `[出生年份](李白.出生年份)`;
4. 整个体系分层:
- 原始语料;
- 改写/抽象后的可执行知识(可还原验证回原始知识);
- 智能体回答/思考时的调用面。
这个模型在**知识架构**上没有问题;问题只在第 2 步的「实例化」如何落到语法。
---
## 2. 当前语法事实
| 语法 | 当前语义 | 对模型的影响 |
|------|---------|-------------|
| `# 诗人` | 类/类型;正文是构造体 | ✅ 可做本体 |
| `# 李白 = > 诗人` | **继承/子类**;不是实例 | ⚠️ 与「实例化」字面不符 |
| `## 李白的出生年份` | 方法;可用 `self`/`自` | ⚠️ 当前是实例方法 |
| `> 李白` | 构造实例(map + `_type`) | ✅ 运行时实例 |
| `李白.李白的出生年份` | 当前被当变量/实例方法路径 | ❌ 类调用未实现 |
| `[描述](...)` | 描述 + 表达式 | ✅ 调用面 |
| `import` | 跨文档绑定 | ⚠️ 当前跨文档继承/调用需 import |
**实测**(`marqdo 2.0.0`):
- `# 李白 = > 诗人` 在**另一个文档**定义 `# 诗人` 时,未 import 会报 `unknown base type 诗人`;
- import 后可以继承,但调用仍需 `> libai.李白` 构造实例,再 `` `li`.李白的出生年份() `` → `701`;
- `李白.李白的出生年份` 直接调用报 `undefined variable`;
- 跨文档类索引不存在。
所以「诗人类 → 李白实例 → 链接调用」在**目标模型**上成立,在**当前语法**上只完成了「类 + 继承 + 实例方法」,缺「类调用 + 类索引」。
---
## 3. 自洽性检查:逐层
### 3.1 L0 原始语料
| 问题 | 结论 |
|------|------|
| 原始语料是否可执行? | 否;它是出处,不是程序 |
| 能否被引用? | ✅ 现有 Markdown 相对链接/`来源` 表 |
| 能否保留原文? | ✅ 叙述、引用块、表格 |
| 语法负担 | 零:就是现有文档 |
**要点**:原始语料必须保持「不可执行」的独立身份;一旦把原文改写成代码,就失去了「还原验证」的基准。所以 L0 与 L2 要**物理/逻辑分离**(`corpus/` vs `knowledge/`)。
### 3.2 L1 本体 / 模式
```markdown
# 诗人
| 字段 | 类型 | 说明 |
|------|------|------|
| 姓名 | text | 诗人姓名 |
| 出生年份 | number | 公元年份 |
```
| 问题 | 结论 |
|------|------|
| `# 诗人` 能否表达类? | ✅ `#` 就是类/类型 |
| 字段/类型能否表达? | ✅ 现有表格 + 契约表 |
| 是否需要新语法? | ❌ 不需要;用字段/类型表的列名约定 |
| 是否能被检查? | 需要新增 `knowledge.schema_*` 检查(工具,不是语法) |
**语法结论**:L1 完全用现有 `#` + 表格;只需要约定「字段表」的列名与语义。
### 3.3 L2 可执行知识:关键歧义
「用李白的知识实例化诗人」有两种落法:
#### A. 单体知识类(推荐)
```markdown
# 李白 = > 诗人
## 李白的出生年份
*701*
```
- 语法:`# 李白 = > 诗人` = 继承/特化;
- 语义:李白是诗人(is-a),并且 `# 李白` 是一个**命名的知识个体**;
- 调用:`李白.李白的出生年份` = 类调用(不使用 `self` 的函数);
- 地址:`# 李白` 是文档里的稳定类名,可被项目类索引解析;
- 运行时:如果需要 map,仍可 `> 李白` 构造实例;
- 代价:**术语上不是「实例」**,是「单体类/知识个体」。
#### B. 运行时实例(不推荐作为 v2.1 语法)
```markdown
# 诗人
## 李白
*> 诗人 姓名="李白" 出生年份=701*
```
- 语法:`## 李白` 是函数,返回一个实例 map;
- 调用:`李白().出生年份`(函数返回实例,再取方法);
- 地址:`李白` 是函数名,不是实体;跨文档要函数索引/缓存;
- 代价:每次调用可能新构造实例;没有稳定的知识实体地址;EKC 节点是函数,不是个体;
- 需要:实例注册表/导出机制,或函数级索引;这比 A 多一层运行时概念。
#### C. 显式个体声明(未来可选)
```markdown
# 李白 : 诗人
```
- `:` 明确「李白是诗人个体」;
- 语法更贴近本体(instance-of),但**新增一个标记**;
- 与 `# Child = > Parent` 形成两种关系,需要决定何时用哪种;
- 不建议 v2.1 引入;可作为 v2.2 的候选。
### 3.4 L3 调用面
```markdown
[出生年份](李白.李白的出生年份)
```
| 问题 | 结论 |
|------|------|
| `[]` 是描述、`()` 是调用? | ✅ 现有语义 |
| `()` 与 `**` 同权? | ✅ 同一 parser/evaluator |
| 跨文档类名能否解析? | 需要项目类索引(v2.1) |
| 正文链接是否执行? | view/check 解析;run 不执行(安全) |
| 终端输出? | 代码链接 + `print` |
| 编译器能否返回 LinkInfo? | 需要新增(工具,不是语法) |
| view 能否显示调用点? | 需要新增(工具,不是语法) |
**语法结论**:L3 不需要新语法;缺的是**解析器/类索引/视图/编译器输出**。
---
## 4. 推荐模型:单体知识类
### 4.1 定义
> **单体知识类**:一个 `# 名称 = > 父类` 的类,代表一个知识个体;它的 `##` 函数是该个体的知识字段/事实;它不需要运行时实例即可被 `类.函数` 调用。
```markdown
# 诗人
| 字段 | 类型 | 说明 |
|------|------|------|
| 姓名 | text | 诗人姓名 |
| 出生年份 | number | 公元年份 |
# 李白 = > 诗人
## 李白的出生年份
| 返回 | 类型 | 来源 |
|------|------|------|
| 701 | number | corpus/libai.md#出生年份 |
*701*
```
调用:
```markdown
# main
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
输出:`701`。
### 4.2 为什么推荐 A
| 维度 | A 单体类 | B 运行时实例 |
|------|---------|-------------|
| 语法新增 | **零** | 需要实例导出/注册/函数索引 |
| 地址稳定 | ✅ 类名 | ❌ 函数返回值 |
| 跨文档 | ✅ 项目类索引 | ❌ 需要实例注册表 |
| EKC 映射 | ✅ 文档/类/函数节点 | ❌ 实例不是文档节点 |
| 可还原 | ✅ 类/函数 + 来源表 | ⚠️ 实例是运行时值 |
| 可检查 | ✅ 类/函数/契约 | ⚠️ 实例状态难静态检查 |
| 术语 | ⚠️ 叫「个体」不叫「实例」 | ✅ 叫实例 |
| 多实例 | ⚠️ 每个个体一个类 | ✅ 自然 |
**结论**:在「文档即知识库」的约束下,A 的语法成本最低、可检查性最好;B 的「实例」语义更纯,但需要新的运行时/注册表,和「零新语法」冲突。
### 4.3 术语约定
| 术语 | 含义 | 语法 |
|------|------|------|
| **类 / 本体** | 诗人的模式 | `# 诗人` |
| **知识个体(单体类)** | 李白这个知识实体 | `# 李白 = > 诗人` |
| **知识字段 / 事实** | 李白的出生年份 | `## 李白的出生年份` + `*701*` |
| **类调用** | 读取知识个体的字段 | `李白.李白的出生年份` |
| **运行时实例** | 代码里 `> 李白` 得到的 map | `> 李白` / `_type` |
| **知识链接** | 描述 + 类调用 | `[出生年份](李白.李白的出生年份)` |
> **重要**:语法文档里不要再用「实例化」描述 `# 李白 = > 诗人`;用「知识个体化/单体类」。
> 「实例」保留给运行时 `> 诗人` 产生的 map。这样语法、文档、EKC 三者才一致。
### 4.4 多诗人怎么办
```markdown
# 李白 = > 诗人
# 杜甫 = > 诗人
# 王维 = > 诗人
```
- 每个个体是一个单体类;项目类索引登记它们;
- `李白.出生年份` / `杜甫.出生年份` 分别解析;
- 这是「命名个体注册表」,不是运行时实例集合;
- 如果个体成千上万,类索引会变大;v2.2 可引入表驱动的个体注册(但不改变调用语法)。
---
## 5. 与 EKC 的映射
| 层 | EKC 层 | 节点/边 |
|----|--------|---------|
| L0 原始语料 | Repository / sources | `documented_by` / `derived_from` |
| L1 本体 | Capability / Schema | `# 诗人` class 节点 |
| L2 知识个体 | Knowledge / Symbol | `# 李白` class 节点 + `##` fact 节点;`specializes` 边 → `诗人` |
| L3 调用面 | Symbol / Capability | `[]()` 链接 → `calls` 边;LinkInfo |
| L4 Agent | Agent / Context Pack | `find`/`reuse`/`link.resolve` |
**新增边(建议)**:
- `specializes`:`# 李白 = > 诗人`(语法上是继承;知识语义上是 is-a);
- `derived_from`:fact → 原始语料;
- `calls`:调用文档 → `李白.出生年份`;
- `has_fact`:`# 李白` → `## 出生年份`。
EKC 现有 `depends_on`/`uses`/`implements`/`documented_by` 可以复用;`specializes` 建议新增。
---
## 6. 还原 / 验证(L2 → L0)
「可执行知识能还原验证回原始知识」需要三件事:
### 6.1 出处是数据,不是注释
```markdown
## 李白的出生年份
| 返回 | 类型 | 来源 |
|------|------|------|
| 701 | number | corpus/libai.md#出生年份 |
*701*
```
- `来源` 列指向原始语料(路径 + 标题/锚点);
- 也可以放 frontmatter `sources:`;
- `check` 验证来源存在;`verify` 验证值/引文一致(能自动化的部分)。
### 6.2 可还原的渲染
- `view` 把 `# 李白` 渲染成「知识文档」:字段 + 值 + 来源;
- `catalog` 生成 OKF `Fact` 页,`resource:` 指向 `.mq.md`;
- 渲染结果与原始语料可人工/机器对照;
- 这不是新语法,是 view/catalog 的输出。
### 6.3 漂移检查
| 诊断 | 触发 |
|------|------|
| `knowledge.source_missing` | 事实没有来源 |
| `knowledge.source_dangling` | 来源路径/锚点不存在 |
| `knowledge.value_mismatch` | 事实值与来源引文不一致(可自动判断时) |
| `knowledge.schema_mismatch` | `# 李白` 字段与 `# 诗人` 不匹配 |
| `knowledge.fact_drift` | 原始语料变了,知识未复核 |
这些是**工具诊断**,不是语法。
---
## 7. 调用面:智能体如何使用
```markdown
# main
用户想知道李白的出生年份,我们回答:[李白的出生年份](李白.李白的出生年份)
```
- `view` 显示:`李白.李白的出生年份` → `701` → 来源 `corpus/libai.md#出生年份`;
- `check --json` 返回 LinkInfo(class/function/value/source);
- agent 通过 `link.resolve` / `find` 取到值 + 出处,回答时可引用来源;
- `run` 加 `print` 才输出;正文链接不执行,保证叙述安全。
**这就是「调用面」**:不是自然语言猜,而是可解析、可验证、可引用的类调用。
---
## 8. 反例与边界
| 场景 | 用 A 单体类 | 说明 |
|------|-----------|------|
| 李白、杜甫、王维 | 三个单体类 | 类索引;命名个体 |
| 同一诗人的多个版本 | 多个事实/来源,或子个体 | 版本是事实维度,不是实例 |
| 需要运行时状态(可变对象) | `> 李白` 构造实例 | 运行时实例仍存在,但与知识个体分离 |
| 上千个诗人 | 类索引/表驱动注册 | v2.2 优化;语法不变 |
| 需要 `instanceof` | `# 李白 = > 诗人` 的 `specializes` 边 | 知识语义;不是运行时 `_type` |
| 需要多继承 | 现有不支持 | 不在本设计范围 |
---
## 9. 决策建议
1. **v2.1 采用 A(单体知识类)**:`# 诗人` + `# 李白 = > 诗人` + `##` 事实 + `[]()` 类调用;零新语法。
2. **术语冻结**:`# 李白 = > 诗人` 叫「知识个体/单体类」,不叫「实例」;`> 诗人` 才是运行时实例。
3. **补类函数与类索引**:不使用 `self` 的 `##` 是类函数;项目类索引解析跨文档 `李白`。
4. **补出处/验证**:`来源` 列或 `sources:`;`check`/`verify`;`view`/`catalog` 可还原。
5. **EKC 边**:`specializes` / `derived_from` / `calls` / `has_fact`。
6. **保留 B/C 作为未来**:如果真需要运行时实例/个体声明,再评估 `# 李白 : 诗人` 或实例注册表;不在 v2.1 引入。
### 9.1 备选:frontmatter 个体声明(零语法,但换元数据)
如果不想把 `= >` 的继承语义借给「个体」,可以用 frontmatter 标记:
```markdown
---
type: Individual
class: 诗人
id: libai
---
# 李白
## 出生年份
*701*
```
| 维度 | 单体类 A | frontmatter 个体 |
|------|----------|------------------|
| 可见性 | `# 李白 = > 诗人` 一眼可见 | 类型在 frontmatter,正文只看到 `# 李白` |
| 语法 | 现有 `= >` | 现有 frontmatter,无新标记 |
| 语义纯度 | 继承/特化 | 明确 individual-of |
| EKC | class + specializes | individual + instance_of |
| 代价 | 术语「个体」不是「实例」 | 两套 is-a 表达(`= >` 与 `class:`)需要约定 |
**建议**:v2.1 先用 A(可读、零语法);如果 EKC/本体需要严格区分 class/individual,再启用 frontmatter `type: Individual`,并规定「`= >` 只用于类-类,个体用 frontmatter」。
---
## 10. 结论
> **三层/四层模型自洽;「实例化」是唯一需要修正的词。**
> 在 Marqdo 的语法里,`# 李白 = > 诗人` 是**继承/特化**,不是运行时实例;
> 把它用作**单体知识类**,就能在不新增语法的情况下得到「李白是诗人、李白有出生年份、`李白.出生年份` 可调用」。
> 这正是 EKC 的「文档即知识、知识可执行」:**类是本体的地址,单体类是知识个体的地址,`[]()` 是调用面。**
---
## 附录 A:一页对照
```markdown
# L1 本体
# 诗人
| 字段 | 类型 | 说明 |
| 姓名 | text | ... |
| 出生年份 | number | ... |
# L2 知识个体(单体类)
# 李白 = > 诗人
## 李白的出生年份
| 返回 | 类型 | 来源 |
| 701 | number | corpus/libai.md#出生年份 |
*701*
# L3 调用面
[李白的出生年份](李白.李白的出生年份)
```
| 层 | 语法 | 语义 |
|----|------|------|
| L0 | `.md` 原文 + 来源 | 不可执行 |
| L1 | `# 诗人` + 字段表 | 类/模式 |
| L2 | `# 李白 = > 诗人` + `##` + `*701*` | 知识个体/事实 |
| L3 | `[描述](类.函数)` | 类调用/链接 |
| 运行时 | `> 诗人` / `> 李白` | map 实例(可选) |
## 附录 B:与现有文档的关系
| 文档 | 关系 |
|------|------|
| [link-syntax.md](link-syntax.md) | 调用面的语法;本文补知识分层与单体类 |
| [objects.md](objects.md) | `#`/`##`/`= >` 的对象模型;本文把 `= >` 用于知识个体 |
| [module-namespace.md](module-namespace.md) | 跨文档解析;本文用项目类索引 |
| [engineering-knowledge.md](engineering-knowledge.md) | EKC L0–L4;本文映射到四层 |
| [okf.md](okf.md) | Fact/Concept/路径即身份;本文的 L2 与 Fact 对应 |
+414
View File
@@ -0,0 +1,414 @@
# 纯度路线细化 + 标签过期检测:面向可执行知识体系的一致性机制
| | |
|---|---|
| 状态 | **Accepted**(含语法落地、诊断 schema、分阶段计划) |
| 日期 | 2026-10-22 |
| 决策来源 | 用户:取**纯度**;标签**可省略但编译器须报错**;循环写法不重要;**重点:标签过期与 agent 误导** |
| 前置 | [bracket-as-label-evaluation.md](bracket-as-label-evaluation.md) |
| 依托设施 | `src/diagnostics.rs`(`doc_anchor`/`doc_quote`/`contract_ref`)· `src/mlsp.rs`(`validate`/`repair_targets`/`repair_apply`)· `src/repair.rs`(有界修复)· `src/knowledge/fingerprint.rs` · `src/knowledge/lifecycle.rs`(已有 `find_stale`) |
---
## 0. 决策记录与一个推论
**已定**:
1. **纯度**:`()` 只装机器语句,`[]` 只装人话;取元搬进 `()`。
2. **标签可省略,但编译器报错**:写空方括号是可能的,但那是一个**错误**。
3. **循环写法从简**:`[]` 已是描述,`()` 内部只要自洽即可。
**由此得到一个必须先说清的推论**:
> **纯度强制两件东西同时存在**:
> ① 一个**不带标签**的普通表达式写法(否则每个访问都被迫配一段人话 = 仪式感复辟);
> ② 带标签的形式作为一个**可选包装**。
也就是说 `[标签](表达式)` 不是"唯一的表达式语法",而是"**当你想做断言时才用的包装**"。
这一条同时解决了我在上一份文档里担心的"标签凑数"退化:
**不想断言,就别用这个形式**——而不是"必须写标签但可以写废话"。
---
## 1. 纯度路线下的语法落地
### 1.1 形式
```
带标签表达式 ::= '[' 人话 ']' '(' 表达式 ')'
```
- `表达式` = **现有 Marqdo 表达式文法**(不新增语言)
- `人话` = 任意自然语言,必须是**关于这个值的断言**(§2)
- 出现位置:表达式位置、语句位置、循环位置
### 1.2 关键缺口:普通取元怎么写
纯度之后 `[键](集合)` 不再是取元,所以必须给出**不带标签的取元写法**。四个候选:
| 方案 | 写法 | 优 | 劣 |
|------|------|----|----|
| **A 现有内建** | `[第一项](at value=篮子 index=1)` | 零新语法,今天就能实现 | 啰嗦;`value=`/`index=` 是机器腔 |
| **B 后置方括号** | `[第一项](篮子[1])` | 最像通用语言;`篮子[拿铁]` 读起来自然 | `[]` 出现两种角色(前置=人话,后置=索引),视觉易混 |
| **C 函数式 + 逗号参数** | `[第一项](at(篮子, 1))` | 与 `加一函数(31)` 统一;顺带解决前几轮想要的 `f(args)` | 需支持逗号分隔实参(要改参数分词器) |
| D 点号 | `[拿铁价格](菜单.拿铁)` | 短 | 与库路径 `txt.str_trim`、对象方法 `obj.m` 三者同形 |
**我的建议**:**C**。
理由:你前面想要 `f(args)` 这种"人读友好"的调用,而 C 与它**同一个改动**——
一次性把 `()` 内的表达式升级为「可带括号实参」的形式,
`at(篮子, 1)`、`加一函数(31)`、`get(菜单, 拿铁)` 全部成立,且不新增第二种方括号角色。
代价是参数分词器要支持 `)` 终止与逗号(前几轮原型已验证方向可行,全量 554/0 回归)。
若你希望**零实现风险**,选 A:今天就能用,只是啰嗦,后续可再收窄成 C。
### 1.3 空标签 = 硬错误
```markdown
[](at(篮子, 1)) # ❌ label.missing
```
诊断:`code: "label.missing"`,`severity: error`,`doc_quote: "[]"`,建议:
「给这段语句写一句人话描述,或改用不带标签的普通表达式」。
**这一条是整套设计的门槛**:它把"标签"从可选装饰变成"用了就得负责"的承诺。
也正好落实你说的「可以省略,但编译器应当报错」。
### 1.4 循环
你说不重要,那我给最省事、且与纯度一致的一条:
```markdown
- [从篮子取出的每个果子](foreach 篮子 为 果)
```
- `[]` 是描述(人读)
- `()` 是机器语句:遍历什么、绑定给谁
- 循环变量名从 `[]` **搬进 `()`**——因为 `[]` 不再承担绑定职责
若嫌 `foreach 篮子 为 果` 太新,可就近用现有词:
`- [从篮子取出的每个果子](遍历 篮子 绑定 果)`。
**关键是别再让 `[]` 兼任变量名**——否则"描述"与"标识符"又会打架。
---
## 2. 标签是什么:**可校验断言的载体**
标签不是注释。三者区别:
| | 注释 | 标签 |
|---|------|------|
| 位置 | 游离于代码之外 | **锚定在 AST 节点上**(有 span,可定位) |
| 可核验 | 不能 | **能**(§3) |
| 可进修复协议 | 不能 | **能**(随诊断导出给 LLM) |
| 变更感知 | 无 | **能**(代码变了会撞上旧断言) |
一句话:**标签 = 贴在可执行片段上、可被机器复核的断言。**
这正是 Marqdo 相对传统"文档 + 注释"的核心增量。
---
## 3. 过期检测:三层机制
你问的核心是:**`()` 改了,怎么让 `[]` 的旧描述"叫起来"。**
这需要三种能力,缺一不可,且分属不同层。
### 3.1 L1 引用一致性(无状态、确定性、零成本)
**规则**:标签内用反引号写出的名字 = **实体断言**。
```markdown
[按 `税率` 计算总价](...)
```
可核验的断言:
1. `` `税率` `` 必须**可解析**(在当前作用域/模块里存在)
2. 它必须**出现在 `()` 的实际内容中**(或经调用链可达)
任一条不成立 → `label.stale`(引用已腐烂)。
**为什么低假阳性**:只有**显式反引号**才算断言,普通汉字不参与判定。
这复用了 Marqdo 已有的 `` `名` `` = 实体 的约定,**没有新增记号**。
**局限(必须承认)**:它只查"引用",查不出"语义"。
`税率` 还在,但操作从"乘"改成"除",L1 看不见。
### 3.2 L2 指纹台账(有状态、能查语义腐烂)
**做法**:把「标签写下时,它描述的那段代码」记一份指纹。
`.marqdo/labels.json`(与 EKC 产物同目录,视为**缓存**):
```json
{
"按税率计算总价#1": {
"code_fingerprint": "9f2a…",
"code_quote": "at(税率表, 档位) * 金额",
"confirmed_at": "2026-10-22T09:00:00Z"
}
}
```
- `code_fingerprint`:复用 `src/knowledge/fingerprint.rs`(已有 `collect_calls` / `ops_hint` / `fingerprint_hash`)
→ **调用与运算变了,指纹就变**
- `code_quote`:**旧代码的文本快照**——这就是你说的"保留内容用于校验"的对称物:
`doc_quote` 保留 `[]`,`code_quote` 保留 `()`,两者一起导出给 LLM 对比
- 键 = `规范化标签文本 + 同文本序号`(按标签键而不是按行号,**移动代码不会误报**)
**命中规则**:
| 变化 | 判定 |
|------|------|
| `()` 指纹变 | **stale**:标签描述的代码已变,需复核 |
| 标签文本变 | **新断言**:无历史,首次确认即可 |
| 两者都没变 | 通过 |
**局限**:需要状态文件;合并冲突要处理(§8.2)。
### 3.3 L3 LLM 复核(修复协议闭环)
诊断被导出时同时携带三方信息:
- `doc_quote`:`[]` 里的原话
- `code_past`:`()` 当时的文本(来自台账)
- `code_now`:`()` 现在的文本
模型据此判定三选一:
1. **改标签**(代码意图是对的,描述过期了)
2. **改代码**(描述是对的,实现跑偏了)
3. **确认无害**(改动不影响断言,写回台账 `confirmed`)
这正好接进**已有的修复回路**(`src/repair.rs`):`validate` → `repair_targets` → 模型行编辑 →
`repair_apply`(越界必拒)→ 复验。
### 3.4 为什么三层都要
| 层 | 查什么 | 能否查"乘改除" | 需要状态 | 假阳性 |
|----|--------|--------------|---------|--------|
| L1 | 引用腐烂(改名/删除) | ❌ | 无 | 极低 |
| L2 | 语义腐烂(同引用、不同操作) | ✅ | 需台账 | 中(无害改动也报) |
| L3 | 谁错了(标签 or 代码) | ✅ | 复用 L2 | 由模型判 |
**L1 是地基**(确定性、零成本、可先上),**L2 是覆盖**(能查语义),**L3 是裁决**(谁改)。
---
## 4. 与现有设施的对接(这决定了落地成本)
### 4.1 诊断字段:**已经齐备,不需要新造**
`src/diagnostics.rs` 的 `to_json` 已输出:
```json
{
"code": "…", "severity": "…", "message": "…",
"span": {"file":…, "line":…, "col":…},
"doc_anchor": …, ← 标签位置
"doc_quote": …, ← 标签原文
"contract_ref": {"unit":…, "kind":…, "name":…, "declared":…},
"suggestion": …
}
```
**`contract_ref.declared` 就是"声明"这一侧的先例**:
契约诊断说的是「**declared** number,actual text」,
标签诊断说的是「**declared(标签里的人话)**,actual(`()` 现在的代码)」——
**同一个模式,只是从类型层下沉到散文层。**
> 这也回答了你的问题:"导出时能否保留 `[]` 的内容用于校验"——
> **能,而且字段已经在协议里了**:`doc_quote` 就是它。
### 4.2 契约诊断是现成的范式
`src/contract.rs:203` 的 `Contract::diagnostic(...)` 一次性装配
`code + severity + suggestion + doc_anchor + doc_quote + contract_ref`。
标签诊断可以照抄这套装配,只是 `kind` 从 `"contract"` 换成 `"label"`。
### 4.3 修复范围:允许"标签行 ∪ 代码行"
现在 `repair_apply` 的形状是 `ranges: [[起, 止], …]`,**天然支持多个区间**。
`label.stale` 只需把两段都放进 ranges:
| 允许范围 | 原因 |
|---------|------|
| 标签所在行 | 修法 1:改描述 |
| `()` 所在行 | 修法 2:改实现 |
护栏不变:**越界改动一律拒绝(abstain)**——这正是 `src/repair.rs` 已经强制的语义。
### 4.4 知识层:`stale` 概念已经存在
`src/knowledge/lifecycle.rs` 已有 `find_stale` / `stale_json` / `verify`。
标签过期可以走**同一条 stale 通道**,进入 EKC/OKF 的
`marqdo verify` / `marqdo stale` 报告,成为知识库的健康指标。
> 这一点很重要:**标签过期 = 知识腐烂**,而 Marqdo 已经有"知识会腐烂"的机制,
> 标签只是给它增加了一种新的腐烂类型(文档断言 vs 实现)。
---
## 5. 诊断 schema 草案
```json
{
"code": "label.stale",
"severity": "warning",
"message": "标签可能过期:标签提到 `税率`,但当前语句已不再引用它",
"span": { "file": "报价.mq.md", "line": 42, "col": 12 },
"doc_anchor": { "file": "报价.mq.md", "line": 42, "quote": "按 `税率` 计算总价" },
"doc_quote": "按 `税率` 计算总价",
"label_ref": {
"kind": "label",
"text": "按 `税率` 计算总价",
"refs": ["税率"],
"missing_refs": ["税率"],
"code_past": "at(税率表, 档位) * 金额",
"code_now": "at(税率表, 档位) / 金额",
"fingerprint_past": "9f2a…",
"fingerprint_now": "3c71…",
"layer": "L2"
},
"suggestion": "若意图是乘,请还原 `*`;若意图改为除,请把标签改成「按档位折算比例」",
"ranges": [[42, 42]]
}
```
要点:
- 复用 `doc_anchor` / `doc_quote`,**不新造字段名**
- `label_ref` 仿 `contract_ref`(`kind: "label"`)
- `code_past` / `code_now` 并置 → 模型一眼看出差异
- `layer` 标明是 L1 还是 L2 检出(便于分级治理)
---
## 6. 工作流
```
作者 / agent 改代码
↓
marqdo check 或 MLSP validate
↓
label.stale / label.missing 诊断(带 doc_quote + code_past + code_now)
↓
MLSP repair_targets(ranges = 标签行 ∪ 代码行)
↓
LLM 三选一:改标签 / 改代码 / 确认无害
↓
repair_apply(越界必拒)
↓
复验 → 通过后写回 .marqdo/labels.json(confirmed_fingerprint 更新)
```
**CI 用法**:
- 普通项目:`label.stale` 默认 **warning**(不阻塞)
- 知识库项目(OKF/EKC 仓):可配置为 **error**,把"断言必须新鲜"作为门禁
---
## 7. 反幻觉:这一步到底解决了什么
必须把话说准,否则容易过度承诺。
### 7.1 它解决的**具体一类**
> **文档断言与实现不一致**(doc–code drift at the claim level)。
传统文档的失败模式:
| 失败模式 | 传统文档 | Marqdo(本设计) |
|---------|---------|-----------------|
| 注释过期 | 无声腐烂 | L1/L2 检出 |
| 签名漂移 | 靠类型检查(有) | 契约已有 |
| **散文描述与实现不符** | **完全无解** | **本设计**(新能力) |
| 知识库引用失效 | 靠人工审阅 | 可机械化 |
### 7.2 它**不解决**什么
- 模型凭空编造(幻觉的另一种)
- 代码本身写错
- 标签写得含糊但"不算错"(L1 查不到,L2 只能报"变了")
**所以正确的表述是**:
> 它把"**文档可信度**"从"靠人自觉"提升到"**可被机械复核 + 可被 LLM 裁决**"。
### 7.3 为什么这对"可执行知识体系"是决定性的
一个知识库的价值 = **断言的密度 × 断言的可信度**。
传统知识库只能提高密度(多写),无法保证可信度(写完就腐)。
Marqdo 若能把"断言→复核"闭环,就第一次让**知识库有了保鲜机制**——
这也正好接上 EKC 已有的 `stale` / `verify` 体系。
---
## 8. 风险与反对意见(诚实清单)
### 8.1 误报疲劳(最危险)
如果 `label.stale` 天天响,用户会在三天内学会忽略它。
**对策**:
- L1 **只在能证明冲突时报**(引用了不存在的实体 / 引用的实体不在语句里)
- L2 **默认只报 warning**,且同一标签同一指纹只报一次(台账记录"已复核")
- 诊断里必须给**可执行建议**(改哪一行、改成什么),否则就是噪音
### 8.2 台账的腐烂与合并冲突
`.marqdo/labels.json` 是缓存,不是真相。对策:
- 语义上**可丢弃**:删掉后重建,最多一次全量确认
- 合并冲突策略:**重算优先**(以代码指纹为准,冲突时保留 `confirmed_at` 较新者)
- 不放进版本库时(`.gitignore`),退化为"本地提示";放进版本库时,成为团队级门禁
### 8.3 语义鸿沟
L1 只能查引用;标签写"算总价"而代码改成了"算单价",若两者都引用 `税率`,L1 沉默。
**这是 L2 存在的理由**,也是必须承认的能力边界。
### 8.4 LLM 修标签可能引入新幻觉
"用幻觉修幻觉"是真风险。对策:
- 护栏:**只允许改标签行或代码行**(`repair_apply` 已强制)
- 修改必须**双向可逆**:诊断里给出"过去/现在"两侧,让模型做**判定**而不是**创作**
- 知识库仓建议:L2 级修改需人工确认(`--confirm`)
### 8.5 标签不得参与安全判定
这是我在上一份文档里提的、也是你关心的"agent 误导"的另一面:
**如果沙箱/权限判定读标签,那标签就成了攻击面。**
硬约束:**策略、沙箱、工具白名单只读 `()` 的语义,永不读 `[]`。**
标签只服务于"人读"与"AI 复核",不服务于"机器授权"。
### 8.6 成本
每标签一次指纹计算与比对。可增量:只对**本次变更的文件**做 L2 校验
(与 EKC 的增量编译一致)。
---
## 9. 分阶段落地
| 阶段 | 内容 | 依赖 | 风险 |
|------|------|------|------|
| **P0** | 纯度语法:`[标签](表达式)` + `label.missing` + 普通取元(A 或 C) | 解析器 | 中(506 处迁移) |
| **P1** | L1 引用一致性 + `label.stale` 诊断(无状态) | 诊断字段已有 | 低 |
| **P2** | 诊断 schema + MLSP ranges 并集 + 修复回路 | `mlsp.rs` / `repair.rs` | 低 |
| **P3** | L2 指纹台账 + 增量校验 | `fingerprint.rs` | 中 |
| **P4** | L3 LLM 复核 + `confirmed` 写回 + CI 门禁 | P2+P3 | 中 |
**建议先做 P1**:它零状态、确定性、能立刻抓住"引用了不存在的东西"这类最硬的腐烂,
且不依赖纯度迁移——可以在旧语法上先验证"标签断言"这个概念是否好用。
---
## 10. 待你决策
1. **普通取元选 A(`at value=… index=…`,零新语法)还是 C(`at(篮子, 1)`,需逗号参数)?**
2. **L1 的断言规则**:只认标签内的反引号 `` `名` ``,还是也认"与代码标识符同名"的中文词?
(只认反引号更准;认中文词更聪明但假阳性高)
3. **台账位置**:`.marqdo/labels.json`(默认忽略)还是纳入版本库(团队门禁)?
4. **`label.stale` 默认级别**:warning(推荐)还是 error?
5. **是否先只做 P1**(在旧语法上验证"标签断言"概念),再决定纯度迁移?
> 我的建议顺序:**P1 → P2 → P0 → P3 → P4**。
> 先在旧语法上把"断言 + 复核 + 修复回路"这条链路跑通(它不依赖纯度),
> 再动 506 处迁移——这样即使纯度路线最后要调整,一致性机制也已经沉淀下来了。
+218
View File
@@ -0,0 +1,218 @@
# 方案评估:Markdown 链接式调用 `[函数名](参数…)`
| | |
|---|---|
| 状态 | **Proposed · 已被 [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md) 取代** |
| 日期 | 2026-10-22 |
| 提出 | 用户:「markdown 的链接语义似乎很适合做这种操作」 |
| 相邻 | [spaced-function-names-d8.md](spaced-function-names-d8.md)(方括号调用 + 空格) |
| 影响面 | **核心解析**:`[key](coll)` 链接索引与调用语法冲突 |
> **后续更正**:本文的 L1–L4 方案列表把问题当成「表/语义」来讨论,偏离了用户原意。
> 用户问的是**调用写法**本身。最新评估(含原型实测 554/0 回归)见
> [paren-call-and-readable-invocation.md](paren-call-and-readable-invocation.md):
> 方括号确实不可行(2 个真实冲突文件),但**去掉方括号的 `f(args)` 是空闲语法且可行**。
---
## 0. 一句话结论
**语法本身很优雅,但它与既有特性「链接索引 `[key](map)`」正面冲突。**
冲突不是「难实现」,而是「同一个写法要表示两种语义」。
建议**不要**把它做成调用的主形式;若要引入,只能作为**受限变体**(见 §4)。
---
## 1. 现状事实(实测)
### 1.1 `[…](…)` 目前是链接索引
```markdown
**m = > json.parse text={"a":1}**
**v = [a](m)** # 取 map 的 a 成员
> print text=`v` # → 1
```
这是 v0.3 的**正式特性**,文档里写作「集合取元优先 `[键](集合)`」。
实现有专门入口 `parse_link_index`,并由 `link_index_shape_ahead` 判定:
> `[` … `]` 后面紧跟 `(` → **链接索引**
### 1.2 提议的写法今天会怎样
```markdown
## greet
+ `who`
*"hi " + `who`*
# main
**r = [greet](alice)**
```
实测:
```
error: l2.mq.md:12:1: undefined variable `alice`
```
因为它被当作链接索引 `[greet](alice)`:拿 `alice` **当变量名**去查,
查不到就报错。也就是说**链接索引已经把这块语法占满了**。
### 1.3 歧义判定只有一行
```rust
fn link_index_shape_ahead(s: &str) -> bool {
// '[' … ']' 后紧跟 '(' → 链接索引
}
```
任何 `[X](Y)` 都会走链接索引,没有例外。
---
## 2. 为什么这个提议有吸引力
先说我认可的部分,避免低估它:
1. **视觉语义准确**。Markdown 里 `[文本](目标)` 的直觉是「链接一个东西到另一个」。
调用 `[greet](alice)` 读作「调用 greet,指向 alice」,对非程序员也直观。
2. **参数在括号里,边界清晰**。相比 `> greet alice`(空格切词),
`(alice bob)` 的边界是**显式**的 —— 这恰好是 D8「带空格函数名」痛点的天然解药。
3. **与 Markdown 完全兼容**。`[a](b)` 是合法链接写法,编辑器不会标红。
**但**:这些优点必须在「不破坏链接索引」的前提下才能兑现。
---
## 3. 冲突分析
### 3.1 根本矛盾
| 写法 | 链接索引语义 | 调用语义 | 能否并存 |
|------|-------------|---------|---------|
| `[a](m)` | 取 `m` 的成员 `a` | 用参数 `m` 调用 `a` | **看内容才知道** |
| `[greet](alice)` | 取 `alice` 的成员 `greet` | 用 `alice` 调用 `greet` | 同上 |
**两者形状完全一致**,区别只在「`greet` 是函数还是键名」「`alice` 是集合还是实参」——
这需要**符号表信息**,而语法判定发生在解析期(此时未必知道有哪些函数)。
### 3.2 用「函数表已知」来消歧能行吗
理论上:若 `greet` 是已定义函数 → 调用;否则 → 链接索引。
**问题**:
1. **跨模块不可知**:`[lib.greet](x)` 需要 import 结果,词法/语法期拿不到。
2. **名字冲突**:如果既有 `greet` 函数,又有 map 里叫 `greet` 的键,语义就靠猜。
3. **错误信息会变差**:本意是链接索引但键不存在时,会被误判成调用,
报 `unknown function` 而不是 `missing map key` —— 把清晰错误变成误导错误。
4. **修改即破坏**:今天所有 `[键](集合)` 写法都要进符号表做一次判定,
这是**全量语义变更**,不是增量特性。
### 3.3 冲突的严重度
链接索引是 v0.3 **明确推广**的写法(「集合取元优先 `[键](集合)`」),
仓库里大量使用。让调用去抢这块语法,等于**用新特性侵蚀既有特性**。
---
## 4. 可选的受限方案
### 方案 L1 — 参数列表必须「非单个标识符」(不可靠,不推荐)
仅在 `(…)` 内含**分隔符**时判为调用,如 `[greet](alice, bob)`。
- 优点:`[a](m)` 单参数时保留链接索引语义
- **致命缺陷**:`[greet](alice)` 这种最常见的单参数调用无法表达;
而 `[greet](a, b)` 又和「链接索引 + 逗号」冲突。**语义随参数个数漂移**,最坏的一类设计。
### 方案 L2 — 独立标记前缀(可行,但失去「链接感」)
```markdown
> [call]greet(alice) # 或 @greet(alice)
```
- 优点:零歧义
- 缺点:前面多了标记,就不再是「Markdown 链接」了,失去了提议的全部吸引力
### 方案 L3 — 方括号调用 + 括号参数(**推荐**)
保留既有的方括号调用形式,但允许**参数写在括号里**:
```markdown
> [加一 号](n=1) # 具名参数
> [加一 号](1) # 位置参数
> [greet](alice bob) # 多参数
```
关键:**`]` 后面跟 `(` 时仍优先判为链接索引**——
除非方括号内是「已知的函数名形状」且**调用上下文**成立。
等等,这与 §3 的矛盾相同。**所以 L3 的真正形态是**:
```markdown
> [加一 号] (n=1) # 方括号与括号之间有空格 → 调用+参数组,不是链接
```
用「`]` 与 `(` 之间是否有空格」消歧:
- `[key](coll)`(紧贴)→ 链接索引(**既有语义完全不变**)
- `[callee] (args)`(有空格)→ 调用,参数为一组
- 优点:**零歧义**、**零回归**(紧贴形式完全不动)、保留了「括号包参数」的可读性、
顺带解决 D8 的空格函数名
- 缺点:视觉上 `] (` 有个空格,略不自然;但 Markdown 渲染不受影响
### 方案 L4 — 不在语法层做,在文档层说明(保守)
明确「链接索引是取元,不是调用」,调用一律用 `> callee args` 或 `> [callee] args`。
`[函数名](参数)` 留作**不做**。
---
## 5. 方案对比
| 方案 | 歧义 | 回归风险 | 保留「链接感」 | 解决 D8 | 推荐 |
|------|------|---------|--------------|---------|------|
| L1 参数需含分隔符 | **高**(随参数个数漂移) | 中 | 部分 | 否 | ❌ |
| L2 独立前缀 | 无 | 无 | **否** | 是 | 备选 |
| **L3 空格消歧** | **无** | **无** | 大部分 | **是** | ✅ |
| L4 不做 | 无 | 无 | 否 | 否 | 退路 |
| 直接抢 `[x](y)` | **不可解** | **高** | 是 | 是 | ❌ |
---
## 6. 我的建议
1. **不要**把 `[函数名](参数)` 直接定为调用——它和链接索引形状相同,无法可靠消歧。
2. 采纳 **L3**:`[callee] (args)`(中间有空格)作为「带括号参数组的调用」,
紧贴的 `[key](coll)` 语义**一字不动**。
3. 这样同时满足:
- 「完全兼容 Markdown」(`[x](y)` 仍是链接语义)
- 参数边界显式(括号括起来)
- D8 的空格函数名(方括号内允许空格)
4. 若你觉得 `] (` 的空格不好看,退一步选 **L2**(`> callee(args)` 这种函数式写法),
牺牲链接感换取零歧义。
---
## 7. 若采纳 L3 的验证计划
| 编号 | 用例 | 期望 |
|------|------|------|
| L3-1 | `[a](m)` 紧贴 | 链接索引,取成员(**不变**) |
| L3-2 | `[greet] (alice)` 有空格 | 调用,`alice` 作为位置参数 |
| L3-3 | `[加一 号] (n=1)` | 调用带空格名函数,返回 2 |
| L3-4 | `[greet] (a b)` | 两个位置参数 |
| L3-5 | `[a](m)` 中 `a` 恰好也是函数名 | **仍走链接索引**(紧贴优先) |
| L3-6 | `> print text=(礼貌 [问候] x)` | 内嵌方括号不受影响 |
| L3-7 | 全量 `cargo test` | 554 全绿 |
| L3-8 | 全仓库 `.mq.md` 回归 | 无变化(紧贴形式未动) |
---
## 8. 待你决策
1. **选 L3、L2、还是 L4?**
2. 若选 L3:`] (` 的空格你能接受吗?(渲染上无差别,源码里能看见)
3. 是否同时支持全角 `【函数名】(参数)`?与 D2 全角冒号问题一致考虑。
+799
View File
@@ -0,0 +1,799 @@
# 链接语法:命名载荷、类-函数调用与可执行知识
| | |
|---|---|
| 状态 | **Design Review · v2.1 语义重构(v2.0.0 仅实现本地表达式链接)** |
| 日期 | 2026-10-23 |
| 定位 | `[]()` **不新增语法**:它是 Markdown 链接 + 已有表达式 + 已有 `#`/`##` 类/函数模型的组合;它为任意既有载荷附上人话名称,并产出 view/compiler/知识图元数据 |
| 取代/扩展 | 取代 [occlusion-syntax.md](occlusion-syntax.md) 的「遮蔽」单一框架;把「遮蔽」保留为**显示属性** |
| 证据复核 | [occlusion-vs-executable-knowledge-2026-10.md](../research/occlusion-vs-executable-knowledge-2026-10.md) |
| 示例 | [examples/link-syntax/](../../examples/link-syntax/) |
| 关联 | [knowledge-layers.md](knowledge-layers.md) · [module-namespace.md](module-namespace.md) · [objects.md](objects.md) · [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [engineering-knowledge.md](engineering-knowledge.md) · [view.md](view.md) |
---
## 0. 设计声明
### 0.1 一句话
> **`[]()` 本身不制作新语法。**
> `[]` 是 Markdown 链接的可见文本;`()` 是**已经存在的 Marqdo 代码**,与 `**代码**` 同权。
> `#` 是类,`##` 是函数;`类.函数` 就是类调用。
> 链接把「一次已有载荷」写进文档,并为它附上一个人话名称;view 显示步骤与依赖,编译器返回链接信息。
### 0.1.1 还缺的一步:链接是「命名的可执行步骤」
`()` 可以是任意既有语法:取元、计算、调用、表操作、嵌套表达式或遍历/循环载荷。
所以 `[]()` 不能只被定义成“事实主张 + 函数调用”;那会把通用语法割裂在知识体系之外。
> **`[名称](载荷)` 是命名的可执行步骤:`()` 按原语义执行,`[]` 说明这一步对人意味着什么;编译器把整个步骤写入知识图。**
它始终同时有三种投影:
| 投影 | 规则 | 目的 |
|------|------|------|
| **代码投影** | `execute([label](payload)) = execute(payload)` | 与裸 payload 共用 parser/evaluator,结果、效果和执行代价不变 |
| **文档投影** | 保留 `label` 与所在句子/代码块 | 读者先读每一步的意图,必要时再展开实现 |
| **知识投影** | 产出 `KnowledgeStep { label, kind, inputs, outputs, dependencies, effect, span }` | 让取元、计算、循环、调用和叙述都可检索、解释、验证和影响分析 |
`label` 不进符号表、不改变作用域,也不替 `payload` 背书为“事实”;但它绝不是可丢弃的显示文字。
它是这段代码的人话接口。`payload` 提供操作,`label` 提供意图,二者共同形成可执行知识步骤。
例如:
```markdown
**name = [订单收件人](at(订单, "收件人"))**
**gross = [含税金额](金额 * (1 + 税率))**
- [逐个订单行](遍历 订单.行 为 行)
订单总额为[含税总价](定价.订单定价.含税总价(订单))。
```
它们分别是观测、推导、过程和叙述调用;四者使用同一个 `[]()`,在运行时都复用已有载荷语义,
但在图中拥有不同的输入/输出/依赖/效果边。只有一条步骤最终支撑对外事实时,才沿其依赖链要求来源;
不能要求每一次取元或循环都伪造来源表。
这才同时实现三件事:
- **代码即文档**:函数内部的每一步都有可读意图,不是一个黑盒;
- **文档即代码**:正文中的命名步骤能解析到实际依赖和可选值;
- **知识即可执行**:项目中任意代码步骤都是统一知识图的一部分,来源/规则/函数变化可反查到具体步骤和句子。
完整的跨文件闭环、稳定寻址和层次投影见
[executable-knowledge-system.md](executable-knowledge-system.md)。
### 0.2 三个「不新增」
| 不新增 | 说明 |
|--------|------|
| **不新增链接专用协议前缀 / 别名** | `()` 里就是普通表达式/调用;跨文档代码复用现有 `import bind:target`,正文可用唯一短地址发现 |
| **不新增执行开关 / 模式关键字** | 不引入 frontmatter 别名或执行开关;解析靠已有类/函数/文档结构 |
| **不新增括号 / 标记** | 不引入 `[[...]]` / `@[...]` / `link:`;`[]()` 仍是 Markdown 链接形 |
**本文定义四件事**:
1. **语义**:`#`/`##` 如何形成类/函数,`类.函数` 如何成为类调用;`label` 如何命名任意既有载荷并形成知识步骤;
2. **解析**:`()` 与 `**代码**` 共用 parser/evaluator;跨文档按类索引解析;
3. **校验**:步骤的输入、输出、依赖、效果与来源边分开记录;变更后能定位受影响的代码和句子;
4. **呈现**:view 显示调用点与证据;编译器返回 LinkInfo;EKC 建边;lock 可选。
> **作者不需要学习新标记**:正文链接仍是 `[描述](...)`;`view`/`check` 多了一项「把 payload 解析成类/函数」的能力,而不是要求作者写协议前缀、别名或执行开关。
### 0.3 原始意图
第一个可执行文档:
```markdown
# 李白
这个文档存储了李白的信息。
## 李白的出生年份
李白出生于*某年*
```
在 Marqdo 里:
- `# 李白` = **类**;
- `## 李白的出生年份` = 该类下的**函数**;
- `李白.李白的出生年份` = **类调用这个函数**。
> 注意:正文「李白出生于*某年*」是**叙述**;函数要可调用,需要显式返回值(`*701*` 或表,见 §2.6)。
第二个文档:
```markdown
# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
```
`[]` 是描述,`()` 是已有调用 `李白.李白的出生年份`。它不需要 `print`:
**view 模式天然显示 `()` 的调用信息**。如果要终端输出,加一行 `print` 即可:
```markdown
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
这不是两套语法,而是同一套语法的两种呈现:
- `**year = 李白.李白的出生年份**` 是代码;
- `[李白的出生年份](李白.李白的出生年份)` 是**带描述的同一段代码**;
- `[描述](...)` 唯一新增的是「描述」与「view/compiler 元数据」,不是执行规则。
### 0.4 当前实现的偏差
v2.0.0 把「类-函数」收窄成了「实例方法」:
| 设计意图 | 当前实现 | 后果 |
|----------|---------|------|
| `# 李白` 是类 | `# 李白` 是对象/类型 | 可以,但 `##` 被当成实例方法 |
| `## 李白的出生年份` 是函数 | `##` 是实例方法,需要 `self`/接收者 | `李白.李白的出生年份` 被拒绝 |
| `类.函数` 是类调用 | 必须 `> 李白` 构造实例,再 `obj.函数()` | 多一步实例化,知识不能直接调用 |
| 跨文档按类名链接 | 裸类名不解析,必须 `import` + 绑定 | 第二个文档的链接是 `undefined variable` |
| 链接是「命名载荷 + 已有语义」 | 被收窄成「遮蔽/本地表达式」 | 取元/循环/调用的步骤图、跨文档链接、view 依赖信息缺失 |
这正是「功能被阉割」的地方:**不是 `[]()` 不够,而是 `#`/`##` 的调用语义被实现成了实例方法,跨文档类索引没有建立。**
### 0.5 三个统一
| 统一 | 链接语法的作用 |
|------|---------------|
| **代码即文档** | 调用写在文档里;`**` 是代码,`[]()` 是同一段代码 + 人话描述 |
| **文档即知识库** | `#` 类是知识命名空间,`##` 函数是知识单元;`类.函数` 是地址 |
| **知识即可执行** | 链接解析到类/函数并求值;view 显示调用点;编译器返回 LinkInfo |
形式化:
> **`[label](expr) ≡ expr`;`expr` 可以是 `类.函数`。**
> 链接不改变求值;它增加 label/上下文所形成的命名步骤,以及 view 呈现、编译器元数据和图关系。
---
## 1. 术语
| 术语 | 定义 |
|------|------|
| **链接语法** | `[描述](载荷)`;描述在运行时 inert、在知识层是步骤名称;载荷复用所在位置的已有代码/结构语法 |
| **描述 / 名称(label)** | `[]` 内自由文本;不参与运行时求值,但用于显示、检索、诊断、LinkInfo、意图漂移校验与新鲜度复核 |
| **载荷(payload)** | `()` 内的表达式;与 `**代码**` 同权;唯一执行体 |
| **类(class)** | `# 名称`;知识命名空间/类型 |
| **函数(function)** | `## 名称`(及更深);类下或模块顶层的可调用单元 |
| **类调用(class call)** | `类.函数`;不构造实例,直接调用类函数 |
| **实例调用(instance call)** | `对象.函数`;对象是局部变量/实例,函数可使用 `self`/`自` |
| **知识链接** | 目标为类/函数的 `[]()`;view 显示目标与值 |
| **代码链接** | 出现在 `**...**` / `*...*` / 调用实参/表格单元格里的 `[]()`;参与表达式 |
| **正文链接** | 出现在叙述里的 `[]()`;view/check 解析,`run` 不执行(除非加 `print` 或代码链接) |
| **LinkInfo** | 编译器返回的命名步骤信息:描述与上下文、源位置、payload 类型、输入/输出、依赖、效果、值/来源/指纹 |
| **链接图** | 文档/类/函数/命名步骤为点,读、推导、遍历、调用、效果、叙述、来源为边;EKC/catalog/view 共用 |
| **遮蔽** | 链接的显示属性:`()` 的代码在 Markdown 里被折叠,读者只看描述与结果 |
---
## 2. 语义
### 2.1 描述永不执行,载荷唯一执行
```text
[label](expr) ≡ expr
```
- `[]` 不进符号表、不参与运行时求值、不改变作用域;但它进入 LinkInfo,作为命名步骤的人话接口;
- `()` 是唯一执行体;空 `()` 值为 `None`;
- `label.missing` / `label.empty_payload` 仍是结构诊断;
- 链接的**可执行性**来自 `payload` 的原有语法;链接的**知识性**来自 `label`、位置以及编译器提取的输入/输出/依赖/效果。任意载荷都可成为知识步骤,不以是否类调用为前提。
### 2.2 `#` 是类,`##` 是函数
| 标记 | 语义 |
|------|------|
| `# 名称` | 类/知识命名空间;正文是构造体 |
| `## 名称` | 类下的函数;可被 `类.函数` 调用 |
| `###` … | 更深层函数/子命名空间 |
| 顶层 `## 名称` | 模块级自由函数;可被 `模块.函数` 调用 |
**函数与实例的关系**:
- 函数体使用 `self` / `自` → **实例函数**,只能通过实例调用(`obj.函数`);
- 函数体不使用 `self` / `自` → **类函数**,可被 `类.函数` 直接调用;
- 类函数不执行 `# 类` 的构造体,不产生实例;
- 实例函数保留现有 `> 对象.函数` / `obj.函数()` 语义。
这条规则只用已有语法(`#`、`##`、`self`/`自`、`.`),不新增标记。
### 2.3 `类.函数` 是类调用
| 写法 | 语义 |
|------|------|
| `李白.李白的出生年份` | 类 `李白` 的零参函数 `李白的出生年份`;**隐式调用** |
| `李白.问候("世界")` | 类 `李白` 的函数 `问候`,带位置参数 |
| `李白.计税(档位=2, 金额=100)` | 具名参数,复用现有实参文法 |
| `obj.李白的出生年份()` | 实例调用;`obj` 是局部变量/实例 |
| `文档.李白.李白的出生年份` | 文档限定;用于同名类消歧 |
**隐式调用规则**:当点号路径解析到一个**零参函数**时,路径表达式就是调用,值为函数返回值;
带参数时必须写 `(...)`;解析到类名本身(无函数段)时,仍是类型/构造,不隐式调用。
> 这条规则不是新语法:它只规定「点号路径解析到函数」时的语义。
> 它让 `李白.李白的出生年份` 与 `**李白.李白的出生年份**` 同权,也让链接与代码同权。
### 2.4 跨文档:模块身份优先,类索引只做发现
链接目标可以跨文档。可运行代码的解析顺序:
1. **局部变量/对象**:第一段是当前作用域变量 → 实例调用;
2. **当前文档类/函数**:`# 类` / `## 函数`;
3. **已 import 的模块**:现有 `import bind:target` 绑定;
4. **内置/插件**。
文件 frontmatter 的 `id` + 现有 `import bind:target` 是规范地址;例如
`li_bai.李白.出生年份`。项目类索引仍是**编译器/链接器的发现索引**,不是运行时的
按名加载机制:
- 索引 `id`、`# 类` 名、`## 函数` 名、签名、文件位置;
- 排除 `# main`;
- 正文短地址同名 → `link.ambiguous`;解析成功后 LinkInfo/lock 固化 `id`、文件与指纹;
- 索引只在项目根内(`--fs-root`),不访问网络;
- 索引可缓存(按文件 mtime)。
> 正文可以直接写 `李白.出生年份`,由 catalog 唯一发现并 lock;
> 代码仍应使用显式 import,避免同名、重命名和加载顺序使大型项目失去可复现性。
### 2.5 `()` 与 `**代码**` 同权
| 能力 | `**代码**` | `[描述](载荷)` 的 `()` |
|------|-----------|----------------------|
| 算术/比较/布尔 | ✅ | ✅ 同一 parser |
| 变量/插值 | ✅ | ✅ |
| 本地调用 `callee(args)` | ✅ | ✅ |
| 类调用 `类.函数` | ✅ | ✅ |
| 实例调用 `obj.函数` | ✅ | ✅ |
| 表/列/映射 | ✅ | ✅ |
| 返回值 | Value | Value(同类型系统) |
| 副作用 | 可 | 可(受沙箱限制) |
**实现约束**:表达式位置的 `[label](payload)` 必须复用 `**代码**` 的表达式入口;遍历位置的
`[label](payload)` 必须复用既有 LoopSpec 入口;禁止另造「简化知识表达式」或「知识循环」。
**代码链接 vs 正文链接**:
| 上下文 | `[]()` 行为 |
|--------|-------------|
| `**...**` / `*...*` / 调用实参 / 表格单元格 | 代码链接:求值,参与表达式 |
| 正文(叙述) | 正文链接:view/check 解析并显示;`run` 不执行 |
| 标题 / frontmatter | 不执行;按普通文本处理 |
正文链接不执行,是为了保持「叙述默认安全」;它由 view 呈现、由 check 解析。
要终端输出,就把同一段代码放进代码链接并加 `print`。
**正文链接的识别**:`view`/`check` 扫描正文里的 Markdown 链接;payload 先按所在位置的既有
载荷文法解析,再提取其依赖与角色。URL/相对路径为导航;任意可解析的表达式、调用或遍历
都是命名步骤;解析歧义 → `link.ambiguous`。这仍是语义分类,不是新语法。
### 2.6 输出:值知识必须有值,过程知识必须声明效果
当一个 `##` 作为可被叙述或计算使用的值知识时,目标函数必须返回一个值:
```markdown
## 李白的出生年份
*701*
```
或者用表格/契约声明返回值。**正文叙述可以保留**(例如「李白出生于某年」),但**叙述不是值**;值知识要的是返回值/表。只有叙述、没有返回的函数:
- `run` 得到 `None`;
- `check` 报 `link.no_value`(warning/error,视知识链接用途);
- view 显示「无返回值」;
- 这不是语法问题,是值知识单元没有编码值。遍历、写入、请求等过程知识不必伪造返回值,
但 LinkInfo 必须记录输入、输出绑定和 `effect`,以便 view、权限检查与影响分析。
### 2.7 view 显示调用信息
**代码链接**:
```text
┌─ 链接 ─────────────────────────────┐
│ `year` = [李白的出生年份] │
│ → 李白.李白的出生年份 │
│ class 李白 · function · () -> number │
│ value 701 · ok │
└────────────────────────────────────┘
```
**正文链接**:
```text
用户想要知道李白的出生年份,我们要告诉用户 701。
↑
悬浮:李白的出生年份 → 李白.李白的出生年份
class 李白 · () -> number · value 701
```
- Structure 模式:显示 label + 目标类/函数 + 状态 + 源位置;
- Execution 模式:显示值;
- 点击目标:跳到目标文档/类/函数;
- 错误:错误 chip + 诊断码 + 修复建议;
- 无返回值:显示「无返回值」,不伪造值。
**这就是「示例不带 print」的原因**:view 显示调用信息;`run` 才需要 `print` 才有终端输出。
### 2.8 编译器返回 LinkInfo
每个 `[]()` 产出:
```json
{
"label": "逐个订单行",
"payload_kind": "loop",
"roles": ["iterate"],
"source": {"file": "pricing.mq.md", "line": 18, "col": 3},
"inputs": [{"path": "订单.行", "type": "list<订单行>"}],
"outputs": [{"name": "行", "type": "订单行"}],
"dependencies": [
{"kind": "local_value", "path": "订单.行"},
{"kind": "symbol", "id": "capability.pricing::订单定价.含税价"}
],
"effect": "pure",
"value": null,
"fingerprint": "sha256:…"
}
```
- `payload_kind`:`expr` / `loop` / `inline` / `navigation`;复用所在位置的已有文法;
- `roles`:`observe` / `derive` / `reuse` / `iterate` / `act` / `narrate`,由 AST、效果和依赖推导;
- `dependencies` 是集合而非单一 target;任意复杂表达式都可同时读表、调用多个知识函数和产生副作用;
- `value` 在 `check` 中为 `null`(不执行);在 `view`/`run` 中可填;
- `fingerprint` 是 label、payload、依赖解析及契约的指纹;用于意图漂移与 lock 检查。
### 2.8.1 LinkInfo 是统一知识步骤记录,不只是调用记录
`LinkInfo` 至少要区分三类状态:
| 层 | 要回答的问题 | 典型状态 |
|------|-------------|----------|
| **载荷状态** | `()` 能否按它原有语法解析/执行? | `ok` / `unresolved` / `arg_mismatch` / `type_mismatch` |
| **步骤状态** | 输入、输出、依赖和效果能否被提取? | `resolved` / `partial` / `ambiguous` |
| **证据状态** | 一个发布事实沿依赖链是否能抵达来源? | `supported` / `needs_review` / `unsupported` |
三者不能混为一谈:字典取元可以 `ok` 且完全不需要来源;但当它被一个事实函数或
正文结论使用时,最终的证据链仍可为 `unsupported`。反过来,来源充足也不能掩盖
`link.unresolved` 或副作用越权。
来源是统一步骤图上的 `derived_from` 边,不是只属于一种“知识链接”的特殊 payload。
这不是新增语法,而是让既有 `#`/`##`、表、表达式和 `[]()` 共同产生同一张图。
### 2.9 链接既是步骤节点,也是图边
```text
定价.订单定价 --contains--> step#逐个订单行
step#逐个订单行 --observes--> 订单.行
step#逐个订单行 --calls--> 定价.订单定价.含税价
定价.订单定价.含税价 --derived_from--> corpus/tax.md#税率
```
- 每个 `[]()` 都保留为步骤节点;`calls` 只是 `observes`/`derives`/`iterates`/`acts`/
`narrates` 等边的一种;
- EKC `graph.json` 增加 class/function/步骤节点和上述关系边;
- `catalog` 模块页显示「链接到/被链接」;
- `find`/`impact`/`verify` 沿步骤、调用和来源边遍历;表字段、循环、函数或来源变更时,
都可精确找出受影响的代码步骤和句子;
- view 的 Structure 面板显示上下游。
### 2.10 安全
| 风险 | 规则 |
|------|------|
| 类名歧义 | `link.ambiguous`;要求 `文档.类.函数` |
| 实例函数被类调用 | `link.instance_only`;提示用实例 |
| 构造副作用 | 类调用不执行构造体;不会隐式构造实例 |
| 函数副作用 | 目标函数可能写文件/发请求;`run`/live view 受沙箱限制;`check` 不执行 |
| 循环 | 链接图检测环;运行时深度/步数上限 |
| 路径逃逸 | 项目类索引只在根内;`--fs-root` 限制;不访问网络 |
| 标签欺骗 | 标签不可信;解析/权限只看 target,不看 label |
| view | 静态模式不执行;live 执行需用户操作;错误不吞 |
### 2.11 可复现(可选,生成物)
- LinkInfo 带 label、payload、依赖解析、效果与可用来源边的指纹;
- `marqdo links lock` 生成 `.marqdo/links.lock.yaml`;
- `check --locked` 校验;载荷、依赖、契约或来源边变化 → `link.stale` / `knowledge.needs_review`;
- 这是生成物/工具,不是新语法。
### 2.12 知识分层:类、知识个体、调用面
链接语法是**调用面**;它上面还有两层知识结构(详见 [knowledge-layers.md](knowledge-layers.md)):
```markdown
# 诗人 # L1 本体:类/模式
| 字段 | 类型 | 说明 |
| 姓名 | text | ... |
| 出生年份 | number | ... |
# 李白 = > 诗人 # L2 知识个体:单体知识类
## 李白的出生年份
| 返回 | 类型 | 来源 |
| 701 | number | corpus/libai.md#出生年份 |
*701*
# L3 调用面
[李白的出生年份](李白.李白的出生年份)
```
**术语**:
- `# 李白 = > 诗人` 是**知识个体/单体类**(语法上是继承/特化),不是运行时实例;
- `> 李白` 才是运行时实例(map + `_type`);
- `李白.李白的出生年份` 是类调用;
- `[]()` 是调用面,不新增语法。
**为什么不在 v2.1 引入运行时实例作为知识实体**:
- 运行时实例是值,不是文档里的稳定地址;跨文档链接需要实例注册表/导出;
- EKC 的节点是文档/类/函数,不是运行时 map;
- 单体类已经能表达「李白是诗人,李白有出生年份」,且零新语法。
---
## 3. 当前实现 vs 目标
### 3.1 已具备(v2.0.0)
| 能力 | 状态 | 证据 |
|------|------|------|
| `[描述](表达式)` 解析 | ✅ | `Expr::Occluded` / `markup: occlusion` |
| `()` 内 `callee(args)` | ✅ | M1;`加一 号(31)` |
| 本地表达式透明求值 | ✅ | `interp.rs:1117` |
| view 本地链接卡 | ✅ | `render.rs:1227` |
| 标签诊断/检索 | ✅ | `label.*` / `marqdo labels` |
| 实例调用 | ✅ | `obj.method()` / `> obj.method` |
### 3.2 缺失(v2.1 目标)
| 能力 | 状态 | 影响 |
|------|------|------|
| `类.函数` 类调用 | ❌ | `李白.李白的出生年份` 被当成变量/实例方法 |
| 跨文档类索引 | ❌ | 裸类名不解析;必须 import + 实例 |
| 统一 `[]()` 分类 | ❌ | 默认 Classic 下 `[]()` 是取元;需 `markup` |
| LinkInfo | ❌ | 编译器不返回链接信息 |
| view 目标/类/函数/值 | ⚠️ 只有本地卡片 | 没有跨文档目标信息 |
| 链接图边(EKC) | ❌ | 知识图不从链接取边 |
| 正文链接解析 | ❌ | 第二个文档的链接不解析 |
| 类函数契约/返回校验 | ❌ | 无返回值也不报 |
### 3.3 为什么旧例子失败
| 层 | 旧例子 | 设计要求 |
|----|--------|---------|
| 上下文 | 正文普通链接 | 正文链接由 view/check 解析(run 不执行) |
| 类索引 | 无 import | 项目类索引解析 `李白` |
| 调用 | `李白.李白的出生年份` 被当变量 | 解析为类函数,隐式调用 |
| 分派 | `##` 是实例方法 | 不使用 `self` 的函数是类函数 |
| 值 | 方法体无返回 | 知识函数必须返回 `701` |
| 静态检查 | 不解析 | `check` 报 `link.*` |
---
## 4. 编译器 / view / CLI 表面
### 4.1 `check --json`
- 解析所有 `[]()`(表达式、遍历、代码与正文),输出带载荷/步骤/证据状态的 LinkInfo 与 `link.*` / `knowledge.*` 诊断;
- 不执行目标函数;
- `link.ok` 可作 info,不阻断;
- `link.unresolved` / `link.ambiguous` / `link.instance_only` / `link.no_value` 按级别报。
### 4.2 MLSP
| method | 作用 |
|--------|------|
| `link.resolve` | 解析一个链接 → LinkInfo |
| `links.list` | 列出文件/项目所有链接 |
| `links.graph` | 返回链接图 |
| `link.check` | 校验一个链接 |
AI 闭环:`locate` → `link.resolve` → 构造/修复 → `check` → `view`/`run`。
### 4.3 `catalog` / EKC
- `catalog` 增加 `links:` 段与链接图;
- EKC `graph.json` 增加 class/function、命名步骤节点与 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates`/`derived_from` 边;
- `find`/`impact` 能按类/函数/步骤检索,也能从变更的字段、规则或来源反查受影响的代码与文档句子。
### 4.4 `links` CLI(可选)
```bash
marqdo links list [PATH] --json
marqdo links resolve FILE:LINE:COL
marqdo links graph [PATH] --json
marqdo links lock [PATH] # 可选,生成指纹锁
```
### 4.5 诊断
| code | 级别 | 触发 | 建议 |
|------|------|------|------|
| `link.unresolved` | error | 类/函数/文档不存在 | 检查类名/文档名/拼写 |
| `link.ambiguous` | error | 同名类/函数 | 用 `文档.类.函数` 限定 |
| `link.instance_only` | error | 类调用命中实例函数 | 用实例 `obj.函数`,或去掉 `self` |
| `link.no_value` | warning | 知识函数无返回 | 加 `*值*` 或表/契约 |
| `link.arg_mismatch` | error | 参数数量/名称不匹配 | 按签名补/删 |
| `link.type_mismatch` | error | 返回/参数类型不匹配(可静态判断) | 修契约/转换 |
| `link.cycle` | error | 链接图成环 | 拆分事实/减少互引 |
| `link.stale` | warning | 目标指纹变化(lock 模式) | 更新 lock 并复核 |
| `knowledge.unsupported` | warning | 对外发布的事实/结论沿步骤依赖链没有来源支撑 | 补来源边或将其标明为未验证推导 |
| `knowledge.needs_review` | warning | payload、依赖、规则或来源变化,受影响步骤/句子待复核 | 复核步骤与叙述后更新 lock |
| `label.missing` | error | 空描述 | 写一句人话 |
| `label.empty_payload` | warning | 空载荷 | 写 `None` 或真实目标 |
---
## 5. 开发指导
### 5.1 里程碑
| 阶段 | 目标 | 交付 |
|------|------|------|
| **L0** | 统一 `[]()` 节点 | `Bracket { label, payload }`;代码/正文两处解析;不新增语法 |
| **L1** | 步骤索引 + 解析 | `Named<T>` 的输入/输出/依赖/效果提取;类/模块解析;`link.*`/`knowledge.*` 诊断 |
| **L2** | 类调用运行时 | `类.函数` 隐式调用;参数;实例函数拒绝;双后端 |
| **L3** | view | 链接卡;正文链接信息;目标跳转;值/状态/源位置 |
| **L4** | 图 + lock | EKC 步骤节点/读写推导遍历调用来源边;catalog;可选 lock/stale |
| **L5** | 默认/迁移/文档 | 统一解析替代 `markup` 方言;旧取元迁移;README/示例 |
**顺序**:L0 → L1 → L2 → L3 → L4 → L5。
L1 完成后 AI 就能静态查链接;L2/L3 才是执行与呈现。
### 5.2 文件级改动
| 文件 | 改动 |
|------|------|
| `src/ast.rs` | `Bracket { label, payload }`(可由 `Occluded` 演进);不新增语法节点族 |
| `src/parse/expr.rs` | `[]()` 统一解析;payload 复用 `**` 表达式入口;保留 `markup` 兼容 |
| `src/parse/mod.rs` | 正文 `[]()` 扫描;行/列定位;表格单元格 |
| `src/link.rs`(新增) | 模块/类解析、`Named<T>` 步骤记录、依赖/效果提取、诊断、指纹、图边 |
| `src/load.rs` | 项目扫描/类索引缓存;`--fs-root`;循环检测 |
| `src/check.rs` | 链接解析集成;`link.*`;`--links/--no-links/--locked` |
| `src/interp.rs` | `类.函数` 类调用;隐式零参调用;实例函数拒绝;正文链接不执行 |
| `src/bytecode/compile.rs` + `vm.rs` | 类调用编译/执行;双后端一致 |
| `src/view/render.rs` | 链接卡;正文链接信息;目标/值/状态/跳转 |
| `src/view/document.rs` / `output.rs` | 正文链接扫描/渲染 |
| `src/knowledge/graph.rs` | class/function/命名步骤节点;读/推导/遍历/调用/效果/叙述/来源边 |
| `src/knowledge/extract.rs` | 类/函数/命名步骤提取;依赖与来源关系 |
| `src/catalog.rs` | links 段/图 |
| `src/mlsp.rs` | `link.resolve` / `links.list` / `links.graph` |
| `src/main.rs` | `links` 子命令;check 选项 |
| `README.md` | 链接语法章节(不新增语法) |
| `doc/README.md` | 登记本文/示例 |
| `examples/link-syntax/` | 用户原始示例 + compat |
### 5.3 关键实现点
1. **类函数判定**:扫描函数体是否出现 `self` / `自`;出现 → 实例函数;不出现 → 类函数。
2. **隐式调用**:点号路径解析到零参函数时,求值为调用;带参必须 `(...)`;解析到类名不调用。
3. **类索引**:只索引 `#`/`##` 名、签名、文件、行;排除 `# main`;同名报歧义。
4. **`[]()` 分类**:
- payload 是类/函数路径 → 知识链接;
- payload 是表达式(运算符/字面量/调用)→ 本地表达式链接;
- payload 是单标识符且解析为集合 → 旧取元(兼容;`markup` 模式可强制链接);
- 正文 `[]()` → 正文链接(view/check)。
5. **正文链接不执行**:`run` 不改行为;`view`/`check` 解析;要输出用代码链接 + `print`。
6. **LinkInfo**:check/view/catalog 共用;任意 `[]()` 都记录 payload kind、输入/输出、依赖、效果与步骤状态;无需执行即可得到结构图。
7. **图**:每个 `[]()` 是步骤节点;按角色建 `observes`/`derives`/`iterates`/`calls`/`acts`/`narrates` 边,来源只是其中一种边。
8. **安全**:类调用不构造实例;沙箱;根目录;标签不可信。
**最小改动原则**(证明「不新增语法」):
| 层 | 现状 | v2.1 改动 |
|----|------|-----------|
| parser | `[label](payload)` → `Occluded { label, payload }` | **不改 grammar**;可把节点改名为 `Bracket` 便于阅读 |
| payload | 已是表达式,`callee(args)` 已支持 | 不改;`类.函数` 是现有 dot path |
| AST | `Occluded { label, payload }` | 不新增 `Ref`/`Class` 节点;类/函数用现有 `Function`/`is_object` |
| resolver | 无 | **新增**:类索引 + `类.函数` 解析 + `self` 判定 |
| interp | 透明求值 payload | **新增**:dot path 解析到类函数时隐式调用 |
| view/check | 本地卡片/契约 | **新增**:正文 `[]()` 扫描 + LinkInfo |
| 语法 | — | **零新增**:没有协议前缀、别名、执行开关、模式关键字 |
> 当前 `李白.李白的出生年份` 在 AST 里是 `Var("李白.李白的出生年份")`(v2.0.0 实测报 `undefined variable`)。
> **不要依赖 parser 生成新节点**:resolver 按 `.` 拆分这个变量名,先找类 `李白`,再找函数 `李白的出生年份`;
> 找到后按类调用求值。若 parser 已生成 `Call { path: ["李白","李白的出生年份"] }`,同样按 path 解析。
### 5.4 测试
| 层 | 用例 |
|----|------|
| 单元 | `类.函数` 解析;零参隐式调用;带参;`self` 判定;同名歧义 |
| 集成 | 用户两文档:正文链接 view 显示 701;代码链接 + print 输出 701 |
| 诊断 | unresolved / ambiguous / instance_only / no_value / arg/type/cycle |
| view | 链接卡/正文链接/目标跳转/错误/无返回值 快照 |
| 图 | EKC 观测/推导/遍历/调用/效果/叙述/来源边;catalog;impact |
| 双后端 | tree + bytecode 一致 |
| 回归 | 现有 605 测试不减;实例调用不变;旧 `markup` 兼容 |
| 安全 | 根目录逃逸、循环、副作用、标签注入 |
### 5.5 迁移
- `#`/`##` 的实例调用保持;
- 不使用 `self` 的现有方法自动获得类调用能力(增量);
- `类.函数` 是新增解析,不改变旧调用;
- `[]()` 在 `markup: occlusion` 下继续是链接;在 Classic 下按 payload 分类,单标识符/集合仍是旧取元;
- 目标:v2.2 移除 `markup` 方言,统一按 payload 分类。
---
## 6. 示例
完整见 [examples/link-syntax/](../../examples/link-syntax/)。
### 6.1 用户原始示例(目标)
`libai.mq.md`:
```markdown
# 李白
这个文档存储了李白的信息。
## 李白的出生年份
李白的出生年份是公元 701 年。
*701*
```
`main.mq.md`:
```markdown
# main
用户想要知道李白的出生年份,我们要告诉用户[李白的出生年份](李白.李白的出生年份)
```
- `view`:正文链接显示 `李白.李白的出生年份`、类 `李白`、函数、签名、值 `701`;
- `run`:无输出(正文链接不执行);加 `print` 才有终端输出;
- `check --json`:LinkInfo(target/class/function/signature/status);
- `catalog`:`main.mq.md --calls--> libai.mq.md::李白.李白的出生年份`。
### 6.2 加 print(终端输出)
```markdown
# main
**year = [李白的出生年份](李白.李白的出生年份)**
> print text=`year`
```
输出:`701`。
### 6.3 带参数
```markdown
# main
**greeting = [问候](李白.问候("世界"))**
> print text=`greeting`
```
### 6.4 当前兼容写法(v2.0.0)
```markdown
---
markup: occlusion
import:
libai: libai.mq.md
---
# main
**li = > libai.李白**
**year = [李白的出生年份](li.李白的出生年份())**
> print text=`year`
```
输出 `701`。这只是**当前实现**的等价写法;v2.1 的目标是去掉 `import`/实例两步。
---
## 7. 验收标准
| # | 验收 | 判定 |
|---|------|------|
| 1 | 用户原始示例的 `view` 显示 `701` 与调用信息 | view 快照 |
| 2 | `**year = [..](李白.李白的出生年份)**` + `print` 输出 701 | run |
| 3 | `check --json` 返回 LinkInfo(class/function/signature/status) | link.ok |
| 4 | 类名改成不存在 → `link.unresolved` | 反例 |
| 5 | 同名类 → `link.ambiguous` | 反例 |
| 6 | 实例函数被类调用 → `link.instance_only` | 反例 |
| 7 | 无返回值 → `link.no_value` | 反例 |
| 8 | EKC 出现 `calls` 边 | graph.json |
| 9 | 正文链接 `run` 不执行;`view` 解析 | 行为 |
| 10 | 旧 605 测试不减;实例调用不变 | 回归 |
| 11 | 表字段、规则或来源变化后,受影响的取元/循环/推导/句子变为 `knowledge.needs_review` | impact 反例 |
**一句话验收**:
> **`[李白的出生年份](李白.李白的出生年份)` 不新增任何语法;`view` 能显示它,`check` 能解析它,`run` 加 `print` 能输出 701,`catalog` 能建边。**
> 四者缺一,说明 `#`/`##` 的类-函数语义还没补齐。
---
## 8. 风险与开放问题
| 风险 | 说明 | 缓解 |
|------|------|------|
| 类名歧义 | 多个 `# 李白` | `link.ambiguous`;`文档.类.函数` |
| 实例/类判定 | 依赖 `self`/`自` 扫描 | 明确规则;无法判定时 `link.instance_only` |
| 构造副作用 | 类调用不应构造实例 | 类调用不执行构造体;实例函数拒绝 |
| 无返回值 | 知识函数只有叙述 | `link.no_value`;要求 `*值*`/表 |
| 正文链接 | run 不执行 | view/check 解析;print 用代码链接 |
| 旧取元歧义 | `[key](collection)` | 单标识符/集合按旧取元;`markup` 兼容;逐步迁移 |
| 性能 | 大项目类索引 | 缓存;只索引签名;增量 |
| 安全 | 类函数执行副作用 | 沙箱;check 不执行;标签不可信 |
| 跨项目 | 类索引只在根内 | 用 import/模块;不引入新语法 |
**开放问题**:
1. 类函数是否允许访问类级常量/字段?v1 只允许函数体自包含;v1.1 再定义。
2. `# 类` 的构造体与类函数的关系?v1 类调用不构造;实例函数用 `self`。
3. 同名类跨文档是否允许?v1 报歧义;用 `文档.类.函数`。
4. 正文链接是否要在 `run` 中渲染?v1 不执行;view 显示;v1.1 可加 `--render-links`。
5. `[]()` 与旧取元的自动分类是否足够稳定?先保留 `markup` 兼容;v2.2 再移除。
6. 是否需要函数作为一等值?v1 不需要;`类.函数` 解析即调用。
---
## 9. 结论
> **`[]()` 不是新语法,它是「命名载荷 + 已有语义」的组合。**
> `#` 是类,`##` 是函数,`类.函数` 是类调用;`()` 与 `**` 同权。
> 链接不改变载荷;它把取元、计算、循环、调用和正文槽统一提升为能被读、查、验和追溯的知识步骤。
v2.0.0 把 `##` 实现成了实例方法,把跨文档链接实现成了 import + 实例,把 `[]()` 收窄成了本地遮蔽。
v2.1 要补的是**语义**,不是语法:
1. `#`/`##` → 类/函数;不使用 `self` 的函数是类函数;
2. `类.函数` → 类调用;跨文档用项目类索引;
3. `[]()` → 命名载荷 + 已有语义;表达式/循环按原规则执行,正文由 view/check 解析;
4. LinkInfo / view / EKC 的步骤节点与读、推导、遍历、调用、效果、来源边 —— 让代码与文档可查、可看、可验、可建图。
**一句话**:
> **不是给 `[]()` 加语法,而是让 `#`/`##` 真正成为类/函数,让 `类.函数` 真正可调用;`[]()` 只是把这次调用写成一句人话。**
---
## 附录 A:一页速查
```markdown
# 类
## 函数
*701*
# 代码链接(求值)
**year = [出生年份](李白.李白的出生年份)**
> print text=`year`
# 正文链接(view/check 解析,run 不执行)
李白出生于 [李白的出生年份](李白.李白的出生年份)。
# 带参类调用
**g = [问候](李白.问候("世界"))**
```
| 写法 | 执行 | 用途 |
|------|------|------|
| `**类.函数**` | ✅ | 普通代码/调用 |
| `[描述](类.函数)`(代码内) | ✅ | 带描述的类调用 |
| `[描述](类.函数)`(正文) | ❌ run / ✅ view/check | 知识链接 |
| `[描述](expr)`(代码内) | ✅ | 本地表达式链接 |
| `[描述](url)` | ❌ | 普通导航 |
## 附录 B:与旧文档的关系
| 旧文档 | 关系 |
|--------|------|
| [occlusion-syntax.md](occlusion-syntax.md) | 旧文把 `[]()` 定义为「遮蔽」;本文把它定义为「命名载荷 + 已有语义」;遮蔽只是显示属性 |
| [occlusion-description-and-search.md](occlusion-description-and-search.md) | 标签/桩/检索仍适用;本文把标签归入 LinkInfo |
| [change-m7-migration.md](change-m7-migration.md) | 旧取元迁移保留;v2.1 统一按 payload 分类,逐步移除 `markup` |
| [objects.md](objects.md) | 扩展:`#` 类是命名空间;`##` 不使用 `self` 时是类函数 |
| [module-namespace.md](module-namespace.md) | `import` 仍用于代码模块;链接额外支持项目类索引 |
| [engineering-knowledge.md](engineering-knowledge.md) | 链接边接入 EKC 图 |
+40 -27
View File
@@ -2,7 +2,7 @@
| | |
|---|---|
| 状态 | **Accepted;统一 `import bind:target` 已锁定** |
| 状态 | **Accepted;嵌套 YAML `import:` / `导入:` 映射已锁定** |
| 日期 | 2026-08-13 |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-i18n.md](stdlib-i18n.md) · [markdown-mapping.md](markdown-mapping.md) · [objects.md](objects.md) · [call-arguments.md](call-arguments.md) · [ext-agent.md](ext-agent.md) |
@@ -16,9 +16,9 @@
- `lib/json` 的 `parse` 与 `lib/time` 的 `parse` 不能共存。
- 官方 ext / 多库编排无法按大型语言习惯书写 `time.parse` / `json.parse`。
- 旧 frontmatter `import path:path.mq.md` 对 Markdown / 编辑器不友好,且与调用标记 `>` 抢外形。
- 旧 frontmatter 一行式 `import bind:target` 在 YAML 里会变成带空格的键,与正规元信息不兼容。
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为可读的 `import bind:target`。
**结论**:模块命名空间 + 点号寻址;frontmatter 导入统一为嵌套 YAML 映射 `import:\n bind: target`。
---
@@ -29,8 +29,8 @@
1. **导入绑定库名**:导入一个 `.mq.md` 得到一个**库(模块)绑定**,成员不倒进全局。
2. **点号寻址调用**:`库.成员`、`库.对象.成员`;`.` 表示定义树寻址。
3. **库名不是变量**:路径段为**裸标识符**,不加反引号。
4. **短名与文件导入同形**:`import fmt:time.format`,废除独立 `use` 关键字。
5. **中英对等**:`import` / `导入`。
4. **短名与文件导入同形**:同在 `import:` 映射下写 `fmt: time.format`,废除独立 `use` 关键字。
5. **中英对等**:`import:` / `导入:`。
### 2.2 非目标
@@ -54,27 +54,38 @@
### 3.2 导入句法(frontmatter)
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。
仍只出现在文件头成对 `---` 内。**调用**仍用 `> print`(不变)。键为合法 YAML:`import:` / `导入:`,值为嵌套映射。
```yaml
---
import:
utils: utils.mq.md
json: lib/json.mq.md
fmt: time.format
---
```
| 含义 | 英文 | 中文 |
|------|------|------|
| 导入文件 | `import utils:utils.mq.md` | `导入 utils:utils.mq.md` |
| 标准库 | `import json:lib/json.mq.md` | `导入 json:lib/json.mq.md` |
| 短名(成员) | `import fmt:time.format` | `导入 fmt:时间.格式化` |
| 导入文件 | `import:` → `utils: utils.mq.md` | `导入:` → `utils: utils.mq.md` |
| 标准库 | `json: lib/json.mq.md` | 同左(或中文库路径) |
| 短名(成员) | `fmt: time.format` | `fmt: 时间.格式化` |
规则:
- **绑定名必填**,在 `:` 左侧(裸名,无反引号)。
- `:` 右侧 `target`:
- **绑定名必填**,为映射键(裸名,无反引号);冒号后须有空格(正规 YAML)。
- 映射值 `target`:
- 以 `.mq.md` 结尾 → **文件导入**;
- 否则为 **点号路径**(≥2 段),把该成员绑为本地短名(须先有对应文件导入)。
- 同一文件内绑定名不得冲突(文件库名与短名共用命名空间)→ 硬错误。
- 旧写法 `> ….mq.md`、`> … as …`、`> use …`、`> 使用 …` → **硬错误**,并提示新句法。
- 同一文件不得同时出现 `import:` 与 `导入:`。
- 旧写法一行式 `import bind:target`、`> ….mq.md`、`> use …` → **硬错误**;可用 `marqdo migrate imports --write` 迁移。
### 3.3 废除的旧规则
不再支持:
- 一行式 `import bind:target` / `导入 bind:target`;
- 省略绑定名时用文件名茎作库名;
- 导入侧 `as` / `作为`;
- 独立关键字 `use` / `使用`。
@@ -101,8 +112,9 @@ path_callee ::= ident ('.' ident)+
```markdown
---
import time:lib/time.mq.md
import json:lib/json.mq.md
import:
time: lib/time.mq.md
json: lib/json.mq.md
---
# main
@@ -139,8 +151,9 @@ import json:lib/json.mq.md
```markdown
---
import time:lib/time.mq.md
import fmt:time.format
import:
time: lib/time.mq.md
fmt: time.format
---
# main
@@ -153,10 +166,11 @@ import fmt:time.format
```markdown
---
import time:lib/time.mq.md
import writeback:lib/writeback.mq.md
import agent:ext/ai/agent.mq.md
import json:lib/json.mq.md
import:
time: lib/time.mq.md
writeback: lib/writeback.mq.md
agent: ext/ai/agent.mq.md
json: lib/json.mq.md
---
# main
@@ -179,13 +193,12 @@ import json:lib/json.mq.md
| 旧 | 新 |
|----|----|
| `import time:lib/time.mq.md` | `import time:lib/time.mq.md` |
| `import t`:lib/time.mq.md | `import t:lib/time.mq.md` |
| `import fmt`:time.format
| `import time:lib/time.mq.md` | `import:` → `time: lib/time.mq.md` |
| `import fmt:time.format` | `import:` → `fmt: time.format` |
| 茎名默认库名 | 绑定名始终显式 |
| 扁平合并进全局 | 仅库绑定 + 可选短名 |
不提供旧 `>` 导入过渡开关。
不提供旧一行式 / `>` 导入过渡开关;`marqdo migrate imports --write` 可机械迁移。
---
@@ -201,20 +214,20 @@ import json:lib/json.mq.md
## 8. 实现要点
1. frontmatter 只解析 `import` / `导入` 行;右侧分流文件 / 成员。
1. frontmatter 解析嵌套 `import:` / `导入:` 映射;子项分流文件 / 成员。
2. AST 仍用 `Import`(文件)与 `Use`(短名)存储,对外无 `use` 关键字。
3. 金样例:`tests/structure/import/`、`tests/structure/ns/`。
| 阶段 | 内容 |
|------|------|
| M1+M2 | 点号路径 + 短名 — 已落地 |
| **Import 句法** | 统一 `import bind:target` — **本波次** |
| **Import 句法** | 嵌套 YAML `import:` — **本波次** |
---
## 9. 决议摘要
1. 导入 = `import bind:target`(`导入` 等价)。
1. 导入 = 嵌套 `import:` / `导入:` 映射(`bind: target`)。
2. target = `.mq.md` 文件 **或** `库.成员` 点号路径。
3. 调用以裸名点号路径寻址;实例方法用反引号接收者(仅独立 `>` 调用;`*…*`/`**…**` 段内接收者不加反引号)。
4. 裸点号 `a.b`:`a` 为局部变量 → 方法调用,否则 → 库路径(Python 统一命名空间)。
+531
View File
@@ -0,0 +1,531 @@
# 文档会话(View Cells)
| | |
|---|---|
| 状态 | **D1–D3 首版已实现;D4/D5 待做** |
| 日期 | 2026-10-17 |
| 层 | Runtime + Document(view 服务端 / 交互单元) |
| 相关 | [notebook-syntax.md](notebook-syntax.md) · [foreign-kernel.md](foreign-kernel.md) · [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [view.md](view.md) · [view-debug.md](view-debug.md) · [stdlib-subtask.md](stdlib-subtask.md) |
| 核心表面 Δ | 无(读取既有 AST 与表格) |
> 文档会话是 view 背后的交互单元运行时:它记住哪些 cell、在哪个内核、按什么顺序执行、状态是什么、结果是否过期。它不是第二个 CLI 模式——`marqdo view` 是唯一的交互面,`marqdo run` 是规范执行。
---
## 1. 目标
1. **像 Jupyter 一样即时**:点一个 cell 就执行,状态保留。
2. **不像 Jupyter 一样隐藏**:执行顺序、内核归属、状态、过期情况都可查。
3. **不破坏 Marqdo 程序语义**:`marqdo run` 仍是规范执行;view 会话是交互镜头。
4. **Git 友好**:状态/输出不默认写进 `.mq.md`。
5. **多语言**:命名内核 + 显式状态桥。
6. **可复现**:Run All / journal / dirty / stale / replay。
---
## 1.1 实施状态(2026-10-18)
| 能力 | 状态 | 位置 |
|---|---|---|
| `foreign.session` 句柄(kernels/cells 表参数) | ✅ | `lib/foreign.mq.md` · `src/host/foreign_doc.rs` |
| cell plan 求值 | ✅ 解释器求值 `会话` 绑定;不扫描源码行、不认保留表名 | `src/interp.rs` · `src/host/foreign_doc.rs` |
| cell index(绑定名 / 行号 / source hash) | ✅ | 同上 |
| 命名内核 + 默认内核 + 语言校验 | ✅ | 同上 |
| 同内核共享 / 跨内核隔离 | ✅ | Node 金样例 + 单测 |
| `run_cell` / `step` / `run_all(restart)` | ✅ | `DocumentSession` |
| `restart_kernel` / `assign_kernel` | ✅ | 同上 |
| `kernel/interrupt` | 待做 | — |
| 状态桥 `push` / `pull` / `state_list` | ✅ | `DocumentSession` + `foreign_session` |
| journal(记录 + API + Journal 按钮) | ✅ | `DocumentSession::journal_json` · view |
| view 工具栏 / 状态徽标 / 内核下拉 / 状态表单 | ✅ | `src/view/html.rs` |
| `POST /api/session/*` | ✅(含 `reload`) | `src/view/notebook_api.rs` |
| cell step | ✅ | 同上 |
| Marqdo statement step | ✅(view 工具栏 Debug → 同一 view 服务的 `/debug`;`/api/debug/*`) | `src/debug` · `src/view/debug_api.rs` |
| dirty/stale 自动检测 | 部分(reload → dirty;assign → dirty;stale 传播待做) | `src/host/foreign_doc.rs` |
| writeback 集成 | 待做 | `writeback` |
| replay / 持久化 | 待做 | — |
| Python 会话 | ✅(本机无 python,CI/用户机条件测试) | `src/host/foreign_session.rs` |
| Node 会话 | ✅ | 同上 |
首版刻意不做:把状态写进 `.mq.md`、自动镜像变量、foreign 行级 debug、跨文档共享内核。
---
## 2. 两个执行面(不是两个 CLI 模式)
### 2.1 Program execution(规范)
- 入口:`marqdo run doc.mq.md` / CI / `view` 的 `Run document`。
- 执行:`# main` 程序语义;外联通过显式 `foreign.session_open/eval/call` 编排。
- 状态:一次运行内有效;运行结束进程退出(除非显式持久内核)。
- 结果:可复现;是文档的“真理”。
### 2.2 View cells(交互)
- 入口:`marqdo view doc.mq.md` → 文档单元(cell)控制。
- 执行:按 `会话表`(或自动顺序)逐 cell 执行。
- 状态:内核持久;可切换、重启、单步。
- 结果:默认临时显示;可显式 writeback。
- 不是“真理”:是探索界面;需要复现时用 Run All 或把编排写进 `# main`。
### 2.3 两者关系
```text
.mq.md
/ \
Program run View cells
(canonical) (interactive)
\ /
Document Session
├── cell index
├── kernel registry
├── journal
└── state panel
```
- 共享 cell index 与 kernel registry。
- `run` 不消费视图会话;`view` 只在文档绑定 `会话 = > foreign.session ...` 时提供持久 cell 控制;无 `会话` 时 cells 无状态一次性执行。
- 冲突时以 `run` 的程序语义为准;view cells 不改变文档语义。
---
## 3. 文档会话模型
```text
DocumentSession
├── doc_path / doc_hash
├── cells: Vec<Cell>
│ ├── id (name / anon@line)
│ ├── name (binding)
│ ├── lang
│ ├── line_start / line_end
│ ├── source_hash
│ ├── kernel (resolved)
│ └── status: never | clean | dirty | stale | error | running
├── kernels: KernelRegistry
│ ├── name → ForeignSession
│ └── default per language
├── value_store: HashMap<String, Value> // Marqdo 侧会话值
├── journal: Vec<ExecutionRecord>
├── created_ms / last_active_ms
└── surface: program | view
```
### 3.1 Cell
- 只有**绑定名**的代码围栏才是 cell:
```markdown
`加载` =
```python
...
```
```
- 未绑定围栏仍是叙述,不是 cell。
- `id`:优先绑定名;匿名围栏用 `anon@<line>`(不进入会话表)。
- 同名 cell 重复 → 诊断;会话表按名字引用。
- `source_hash` 用于 dirty 判断。
- `line_start/line_end` 用于定位;编辑后重建索引。
### 3.2 Cell index 构建
1. 读取/解析文档(现有 `parse_source` / `load_module`)。
2. 遍历 AST,找 `Stmt::Assign { name, value: Expr::Code(c) }`。
3. 记录 name、lang、source、span、source hash。
4. 通过解释器求值 `会话` 绑定(`foreign.session` 返回的句柄,含简单依赖);不扫描源码行、不认保留表名(见 [notebook-syntax.md](notebook-syntax.md))。
5. 解析 kernel 声明与 cell 归属;校验;生成诊断。
6. 生成执行顺序:
- 有会话表 → 行顺序;
- 无 → 文档顺序。
7. 未入会话的 cell → 状态 `unlisted`,UI 显示徽标。
### 3.3 Kernel registry
- key:`<document_id>:<kernel_name>`。
- 默认:`default:python`、`default:node`,按需启动。
- 命名:来自 `内核表`,首次执行时启动。
- 状态:`idle | starting | ready | busy | dead`。
- 同一 kernel 的 cell 严格串行;不同 kernel 可并行。
- 重启:kill + 清空状态 + 重新启动;cell 状态变 `never`。
- 关闭:kill + 移除。
### 3.4 Value store(Marqdo 侧会话值)
- 保存可从 Marqdo 推入内核的值(来自最近一次 Program run 的 bindings,或用户手动输入)。
- 也保存从内核取回的值(`session_get` / 状态面板 Pull)。
- 不是解释器 Env 的实时镜像;它是会话层的**值缓存**。
- 注入解释器:未来通过 `SessionEnv` 或显式变量赋值;v2 不做隐式注入。
- 用途:
- 状态面板显示;
- Push 到内核;
- 作为 `session_set` 的值来源;
- journal 记录。
### 3.5 Journal
每次执行追加一条:
```json
{
"seq": 3,
"cell": "汇总",
"kernel": "分析",
"lang": "python",
"ok": true,
"code": 0,
"ms": 42,
"source_hash": "…",
"stdout_hash": "…",
"result_hash": "…",
"started_ms": 1760000000000,
"error": ""
}
```
用途:
- 执行序号 / 顺序;
- dirty/stale 判断;
- replay;
- 视图显示;
- 调试(“为什么这个 cell 有值”)。
存储:内存 + 可选 `.marqdo/sessions/<doc-hash>.json`(默认 git 忽略)。
---
## 4. 执行语义
### 4.1 操作
| 操作 | 语义 |
|---|---|
| **Run cell** | 执行选中的 cell;必要时启动/复用 kernel |
| **Run above** | 按会话顺序执行到选中 cell(含) |
| **Run all** | 按会话顺序执行全部;可选 `restart` |
| **Step next cell** | 执行会话顺序中的下一个未执行/选中 cell |
| **Step next statement** | Marqdo 语句级单步(DebugController) |
| **Restart kernel** | kill + 重建;cell 状态 `never` |
| **Interrupt** | kill 当前 cell 进程组;kernel 标记 dead 或重启 |
| **Reset session** | 关闭所有 kernel,清 journal / value store |
### 4.2 执行一个 cell
```text
resolve cell -> resolve kernel
-> ensure kernel ready
-> [送入?] 显式 bridge 由文档代码/UI 负责
-> foreign.session_eval(kernel, source, input?)
-> record -> update cell status
-> [取回?] 由文档代码/UI 负责
-> journal append
-> view update
```
- 默认 cwd = 文档目录;env = kernel env。
- 输出:stdout / stderr / result / ms / truncated。
- 失败:cell 状态 `error`;journal 记录;不自动重试。
- 同一 kernel 串行;UI 禁用并发 Run。
### 4.3 Step 语义
| 类型 | 行为 |
|---|---|
| **Cell step** | 执行下一个会话 cell;状态保留 |
| **Marqdo statement step** | 执行下一条 Marqdo 语句;遇到 `foreign.session_eval` 时整个外联调用原子完成 |
| **Foreign line step** | 不做;未来 DAP |
- Cell step 是 view cells 的主单步。
- Statement step 复用 `DebugController`;需要把 debug session 与 DocumentSession 关联。
- 两者可以互相切换:cell step 到某个 Marqdo cell 后可 statement step;语句执行完回到 cell 边界。
### 4.4 中断
- `Interrupt`:向当前 kernel 进程组发 SIGINT/SIGKILL;记录 `interrupted`。
- 若 kernel 状态不确定 → 标记 dead;建议 restart。
- 不允许“中断后继续用同一 kernel”除非确认状态。
### 4.5 并发
- 同一 kernel:一次一个 cell。
- 不同 kernel:可并行(例如 Python 分析与 Node 前端)。
- `Run all` 默认按会话顺序串行;可配置“按 kernel 并行、按依赖串行”(后续)。
- 并发上限沿用 foreign(32)。
---
## 5. 状态桥(会话层)
### 5.1 显式 API
文档代码:
```markdown
把 `数值表` 送进 `分析` 内核:
**> foreign.session_set id="分析" name="xs" value=`数值表`**
从 `分析` 内核取回 `mean`:
**`均值` = > foreign.session_get id="分析" name="mean"**
```
### 5.2 状态面板
- 左侧:Marqdo 侧值(最近 Program run bindings + value store)。
- 右侧:每个 kernel 的变量(`session_names` + 按需 `session_get`)。
- 操作:
- Push:选 Marqdo 值 → kernel 变量;
- Pull:选 kernel 变量 → value store / 显示;
- Refresh;
- 复制名称/值。
- Secret 打码;大对象显示摘要(类型/长度/repr 截断)。
### 5.3 自动镜像
- v2 不做。
- 后续 `mirror`:`mq_` 前缀、白名单、按值拷贝、默认关。
- 原因见 [decisions](../research/foreign-notebook-decisions.md) §1-F。
### 5.4 类型
- JSON 拷贝;复杂对象需 `to_dict` / JSON。
- 大对象:v2 显示摘要;传输用文件/DB。
- 未来:Arrow / Parquet / 共享文件句柄。
---
## 6. Dirty / Stale / Run All
### 6.1 定义
| 状态 | 条件 |
|---|---|
| `never` | 未执行 |
| `clean` | 上次执行成功后源码未变 |
| `dirty` | 源码 hash 变了 |
| `stale` | 上游 cell 变了(依赖图;v2 先按会话顺序近似) |
| `error` | 上次执行失败 |
| `running` | 正在执行 |
| `unlisted` | 不在会话表 |
### 6.2 依赖
- v2:会话表行顺序 + 简单规则:
- 若上游 cell 的 source_hash 变了,下游标 `stale`;
- 若 kernel 重启,全部 `never`。
- v2.1:变量级依赖图(静态分析 + bridge 表),精确 stale。
- 不假装 Jupyter 的“隐藏顺序”:顺序就是表/文档顺序。
### 6.3 Run All
- 默认:按会话顺序执行;可选 `restart=true`。
- 规范执行:**restart + run all**;UI 明确按钮 `Restart & Run All`。
- 未重启时:显示“当前 kernel 有历史状态”警告。
- 执行后:生成 session summary(ok/fail/耗时/跳过的 cell)。
### 6.4 Replay
- 用 journal 的顺序和输入 hash,在新 kernel 上重放;
- 比较 stdout/result hash;
- 输出 divergence 报告。
- v2 可选;至少保留 journal 以便未来实现。
---
## 7. 输出与文档
### 7.1 默认
- View cells 输出只在 view 中显示;不写 `.mq.md`。
- 关闭/刷新后可通过 journal 恢复最近结果(若 session 持久化)。
- 不写 execution_count 到文档。
### 7.2 显式 writeback
- 复用 `lib/writeback` 的 `<!-- marqdo-out … -->`。
- cell 输出锚点:cell 名 + 行号;写入位置在围栏之后,或文档末尾的“输出”区。
- 可选:
- 单 cell 写回;
- 全部写回;
- 只写回文本/数值,不写复杂对象。
- Git 友好:输出是普通 Markdown 注释块;可 diff、可忽略。
### 7.3 不写回
- 避免 Jupyter 的 `.ipynb` 输出噪声。
- 需要分享结果时,导出 HTML / 静态 view,而不是改源文件。
---
## 8. View 交互
### 8.1 工具栏
```text
[Run All] [Restart & Run All] [Step Cell] [Step Statement]
Kernel: [分析 ▾] Status: ready [Restart] [Interrupt]
[State] [Journal] [Writeback ▾]
```
### 8.2 每个 code card
```text
`加载` python · kernel 分析 · run #3 · 42ms · clean
[Run] [Step] [Kernel ▾] [State] [Copy output]
```
- 状态徽标:`never` / `clean` / `dirty` / `stale` / `error` / `running` / `unlisted`。
- 输出区:stdout / stderr / result / 截断提示。
- 内核下拉:切换归属;不迁移状态;提示需要重跑。
- `Step` = 执行此 cell(cell step)。
### 8.3 状态面板
- Marqdo / kernel 分栏。
- Push/Pull。
- Secret 打码。
- 大对象摘要 + 复制 JSON。
### 8.4 Journal 面板
- 表格:seq / cell / kernel / ok / ms / 时间 / 错误。
- 点击跳转 cell。
- 导出 JSON。
### 8.5 键盘
- `Ctrl/Cmd + Enter`:Run cell。
- `Shift + Enter`:Run cell + 下一个。
- `Alt + Enter`:Run cell + 插入?不做。
- `F10`:Step statement(与 debug 一致)。
- `F5`:Run All。
---
## 9. 服务端 API
所有 API 以文档相对路径 + session id 定位;session 内存驻留,进程退出即失。
| 方法 | 路径 | 作用 |
|---|---|---|
| POST | `/api/session/open` | 打开文档会话,返回 cells / kernels / journal |
| POST | `/api/session/close` | 关闭会话,kill 所有 kernel |
| POST | `/api/session/reload` | 重新解析文档,保留 kernel(标记 dirty) |
| POST | `/api/session/cell/run` | 执行指定 cell |
| POST | `/api/session/cell/step` | 执行下一个 cell |
| POST | `/api/session/run_all` | 按会话顺序执行;`restart` 可选 |
| POST | `/api/session/kernel/restart` | 重启指定 kernel |
| POST | `/api/session/kernel/interrupt` | 中断当前 cell |
| POST | `/api/session/kernel/assign` | 改 cell 的 kernel 归属(会话内) |
| POST | `/api/session/state/list` | Marqdo / kernel 变量列表 |
| POST | `/api/session/state/push` | Marqdo 值 → kernel |
| POST | `/api/session/state/pull` | kernel 变量 → value store |
| POST | `/api/debug/*` + `/debug` | Marqdo 语句单步(Debug 按钮,复用 debugger) |
| POST | `/api/session/writeback` | 显式写回 cell 输出 |
| POST | `/api/session/journal` | 执行日志 |
| GET | `/api/session` | 当前会话摘要 |
响应统一:`{ok, session, ...}`;错误 `{ok:false, error, code?}`。
---
## 10. 生命周期与持久化
- Session key:`<root>/<doc_rel>`;每个文档一个。
- 打开:解析、建 cell index、按需启动 kernel。
- 空闲超时:默认 30 分钟关闭(可配置)。
- 文档关闭 / 服务退出:kill 所有 kernel。
- 文件变更:view 刷新时 `reload`;cell hash 变化 → dirty;kernel 保留。
- 持久化(可选):
- `.marqdo/sessions/<doc-hash>.json`:kernel 名称/语言、cell 归属、journal、value store 摘要;
- 默认 git 忽略;
- 不持久化进程状态 / 大对象。
- 不把 session 状态写进 `.mq.md`。
---
## 11. 安全
| 项 | 策略 |
|---|---|
| exec | 所有 kernel 启动/执行检查 `allow_exec`;沙箱拒绝 |
| 生命周期 | 每文档;关闭/drop kill;不跨文档 |
| cwd | 文档目录 / `fs_root`;越界拒绝 |
| 输出 | 有界;截断标记 |
| 超时 | cell 级;进程组 kill |
| 中断 | 杀进程组;kernel 标记 dead |
| Secret | 状态面板打码;JSON 不默认暴露 |
| 未信任文档 | 不自动打开会话;必须显式 Run |
| 并发 | 同 kernel 串行;不同 kernel 上限 32 |
| writeback | 显式;路径沙箱;不自动改文档 |
---
## 12. 测试
### 12.1 服务端
- cell index:绑定名/行号/lang/source hash;未绑定围栏排除。
- 会话解析:foreign.session 句柄/自动模式/重复/未知/语言不匹配。
- 会话:open/close/reload;kernel 启动/重启/中断。
- cell run:状态机 never→running→clean/error;dirty/stale。
- step:cell step 顺序;statement step 与 debug 联动。
- state:push/pull/list;Secret 打码;大对象摘要。
- journal:顺序、hash、失败。
- 并发:同 kernel 串行;不同 kernel 并行。
- 安全:exec=false 拒绝;cwd 越界;超时。
### 12.2 金样例
- `tests/notebook/kernels.mq.md`:foreign.session 句柄。
- `tests/notebook/shared-state.mq.md`:两个 Python cell 共享 `x`。
- `tests/notebook/step.mq.md`:cell step 顺序。
- `tests/notebook/state-bridge.mq.md`:Marqdo ↔ Python 推拉。
- `tests/notebook/invalid-*.mq.md`:诊断。
- 依赖:node 为主,python 条件跳过。
### 12.3 UI
- 手工冒烟:Run cell / Step / Run All / Restart / State Push/Pull / Journal。
- 不引入前端测试框架;用服务端 API + 静态检查。
---
## 13. 与 Jupyter 对照
| 维度 | Jupyter | Document Session |
|---|---|---|
| 源 | `.ipynb` | `.mq.md` |
| 执行顺序 | 隐藏的 `In[n]` | 会话表 / 文档顺序 / journal |
| 状态 | 隐藏 kernel | kernel + value store + 状态面板 |
| 多语言 | 一文档一 kernel | 命名内核 + 每 cell 归属 |
| 单步 | cell | cell + statement |
| 复现 | 手动 | Restart & Run All + journal + replay |
| Git | 输出/计数噪声 | 源码干净;输出显式 |
| 知识 | 无 | OKF / catalog |
| 调试 | 语言 pdb | Marqdo 断点 + cell 级;行级后续 |
---
## 14. 实现顺序(D 层)
| 阶段 | 内容 |
|---|---|
| D0 | 设计/语法/决策文档(本文件) |
| D1 | `src/host/foreign_doc.rs`:cell index、foreign.session 句柄、session 结构、诊断 |
| D2 | 服务端 API:open/close/cell run/step/run_all/restart/interrupt |
| D3 | view UI:工具栏、cell 徽标、kernel 下拉、状态面板、journal |
| D4 | statement step 接入;dirty/stale;writeback |
| D5 | replay / 持久化 / 并发优化 / 测试补全 |
依赖 F 层:F3 持久内核、F3.5 状态桥先完成,D2 才能工作。
---
## 15. 明确不做(v2)
- Foreign line-level step。
- 自动镜像变量。
- 跨文档共享 kernel。
- 全进程快照。
- 自动执行 cell。
- 把 session 状态写进 `.mq.md`。
- 前端 SPA 框架重写;沿用现有 HTML/JS。
+305
View File
@@ -0,0 +1,305 @@
# 文档原生 view cells 语法
| | |
|---|---|
| 状态 | **Decided;D1 解析已实现** |
| 日期 | 2026-10-17 |
| 层 | Document(读取约定) + Runtime(校验) |
| 相关 | [foreign-notebook-decisions.md](../research/foreign-notebook-decisions.md) · [notebook-session.md](notebook-session.md) · [foreign-kernel.md](foreign-kernel.md) · [core-surface.md](core-surface.md) · [layers.md](layers.md) |
| 核心表面 Δ | **无**——不新增标记;只用既有 `# main` / 赋值 / 表格 / 反引号 |
> 目标:让“这段代码在哪个内核里、按什么顺序执行、和谁共享状态”像目录一样可读,而不是像 IDE 配置一样可读。
---
## 1. 为什么不用围栏元数据
Jupyter 的 cell 元数据、VS Code 的 `kernel=`、YAML 的 `kernels:` 都属于**代码/编辑器思维**:
- 读者看到的是一行属性,不是一段知识;
- 属性藏在围栏 info string 或 JSON 里,Markdown 预览看不见意图;
- 一旦加 `kernel=`,它就是 Language 层语法,需要 ADR、core-surface 增行;
- 同一个文档的执行计划被拆散到每个围栏,无法一眼总览。
Marqdo 的选择:
> **执行计划本身是一张表。表是文档的一部分,人先读表,机器再读表。**
这不是新语法。GFM 表已经是集合,`` `名` = `` + 表已经是数据绑定;我们只约定两个**数据表的名字**。
---
## 2. 两个约定数据表
它们放在 `# main`(或唯一入口对象)的体内,和代码单元并列:
```markdown
# main
`内核表` =
| 名称 | 语言 | 命令 | 说明 |
|------|------|------|------|
| 分析 | python | | 读取与清洗数据 |
| 绘图 | python | | 独立环境 |
`会话表` =
| 单元 | 内核 | 说明 |
|------|------|------|
| 加载 | 分析 | 读取原始数据 |
| 清洗 | 分析 | 处理缺失值 |
| 汇总 | 分析 | 按城市聚合 |
| 绘图 | 绘图 | 输出 SVG |
```
为什么是“绑定的表”,不是 `# 外联内核` 对象:
- `#` 是对象/函数;把元数据做成顶层对象会把文档拆成多个作用域,code fence 会被困在对象里。
- 绑定表是入口体内的**数据**,与 cell 同一作用域;不执行、不改变控制流。
- View / 文档会话读取 AST 中的绑定值,不需要执行文档。
- 解析器零改动。
### 2.1 `内核表` / `kernels`
| 列 | 必填 | 含义 |
|---|---|---|
| `名称` / `Name` | ✅ | 内核名,供 `会话表` 引用;建议用领域词(分析/绘图/前端) |
| `语言` / `Language` | ✅ | 预设 id 或已注册语言:`python` / `node` / … |
| `命令` / `Command` | 可选 | 覆盖解释器命令;空白 = 预设 / `set_cmd` / 配置 / 环境变量 |
| `说明` / `Notes` | 可选 | 给人读的一句话;不影响执行 |
规则:
- 名称在文件内唯一;重复 → 诊断。
- 语言不支持会话时,内核仍可声明,但只能执行一次性 cell;`session_*` 报错。
- `命令` 只写可执行文件;参数请用 `.marqdo/foreign.toml` 或 `session_open`。
- 没有 `内核表`:每种语言自动一个 `default` 内核。
- 声明了内核但 `会话表` 没引用:允许,只是没有被使用。
### 2.2 `会话表` / `session`
| 列 | 必填 | 含义 |
|---|---|---|
| `单元` / `Cell` | ✅ | 代码围栏的绑定名(`` `加载` = `` 后面的名字),表格里**不写反引号** |
| `内核` / `Kernel` | ✅ | `内核表` 中的名称,或语言 id(`python` / `node`)表示该语言默认内核 |
| `说明` / `Notes` | 可选 | 给人读的一句话 |
规则:
- **行顺序 = 执行顺序**。这是 `Run All`、`Step`、`Run Above` 的规范顺序。
- 只有列出的 cell 参与会话;未列出的代码围栏仍然显示,但标记为“未入会话”,Run All 不执行。
- 没有 `会话表`:所有绑定名的代码围栏按**文档出现顺序**自动入会话,每种语言用默认内核。
- `单元` 必须对应一个已绑定名的代码围栏;找不到 → 诊断。
- 同名 cell 重复出现 → 诊断;建议一个名字只绑一个围栏。
- `内核` 未声明且不是语言 id → 诊断,列出已声明内核。
- cell 的语言与内核语言不一致 → 诊断;别名等价(`python3`/`py` ↔ `python`)。
- 表可以出现在 `# main` 体内任意位置;读者可以从表一眼看到执行计划。
### 2.3 为什么放在 `# main` 体内
- `# main` 是入口;cell 绑定与元数据表同一作用域。
- `marqdo run` 会正常求值这两个表(得到 `List of Map`),没有副作用。
- 文档会话从 AST / 最近一次运行的 bindings 读取它们;不需要新的解析路径。
- 如果文档没有 `# main` 而是唯一 `#` 对象,同样适用。
---
## 3. 完整示例
````markdown
# main
这份文档演示一个最小 view cells 文档:两个 Python 单元共享 `分析` 内核,
一个绘图单元在隔离的 `绘图` 内核里运行。
`内核表` =
| 名称 | 语言 | 命令 | 说明 |
|------|------|------|------|
| 分析 | python | | 数据读取与聚合 |
| 绘图 | python | | 独立绘图环境 |
`会话表` =
| 单元 | 内核 | 说明 |
|------|------|------|
| 加载 | 分析 | 读取原始数据 |
| 清洗 | 分析 | 处理缺失值 |
| 汇总 | 分析 | 按城市聚合 |
| 绘图 | 绘图 | 输出 SVG |
`加载` =
```python
import json
rows = [
{"city": "上海", "value": 3},
{"city": "北京", "value": 5},
]
print(json.dumps(rows, ensure_ascii=False))
```
`清洗` =
```python
rows = [r for r in rows if r["value"] > 0]
```
`汇总` =
```python
from collections import Counter
counts = Counter(r["city"] for r in rows)
print(dict(counts))
```
`绘图` =
```python
print("plot-ready")
```
`汇总` 和 `绘图` 分属两个内核;`绘图` 看不到 `rows`。
需要共享时,用 Marqdo 显式把值送过去:
**> foreign.session_set id="绘图" name="rows" value=`rows`**
````
读者即使不运行,也能从 `会话表` 读出:先加载、再清洗、再汇总,最后绘图;前三个共享 `分析`,绘图在 `绘图`。
---
## 4. 自动模式(没有表)
### 4.1 没有任何约定表
````markdown
# main
`分析` =
```python
x = 41
```
`结论` =
```python
print(x + 1)
```
````
解释:
- 两个 cell 都是 `python`;
- 自动使用 `default:python` 内核(一个);
- 按文档顺序执行;
- 共享 `x`。
现有文档不需要改一行就能在 view 里 cell-by-cell 运行。
### 4.2 只有内核表
- 所有 cell 按文档顺序;
- 每种语言解析到该语言的 `default` 内核;
- 命名内核只有被 `会话表` 引用时才使用。
### 4.3 只有会话表
- `内核` 列只能写语言 id;
- 每个语言 id 解析到该语言默认内核;
- 未列出的 cell 不入会话。
---
## 5. 可读性规则(语法评审标准)
新增/修改任何 cell 表约定,必须满足:
1. **先读人话**:去掉执行语义后,表格仍像目录/清单。
2. **不使用属性串**:不写 `kernel=…`、`class=…`、JSON/YAML 元数据。
3. **不隐藏意图**:执行顺序、内核归属必须在一处可见。
4. **不引入新标记**:只用 `#` / 表格 / 反引号 / 既有代码面。
5. **默认安全**:表格只声明,不自动执行;只有 Run / Step 触发。
6. **命名用领域词**:`分析`、`绘图`、`前端`,不用 `k1`、`default`、`stage2`(除非确实是默认)。
7. **说明列可选但推荐**:给未来的读者/LLM 一点上下文。
8. **错误可读**:诊断要指出“哪个单元、哪个内核、哪一行、怎么修”。
9. **中英对称**:中文用中文列名,英文用英文列名;语义一一对应。
10. **无表也能跑**:约定表是增强,不是前置条件。
---
## 6. 诊断规范
| 情况 | 诊断(中文示例) | 修复建议 |
|---|---|---|
| 内核名重复 | `内核表: 内核名「分析」重复(第 12、20 行)` | 改名或合并 |
| 会话引用未知内核 | `foreign.session: cell「汇总」引用了未声明的内核「分析」` | 在 kernels 表声明,或改用语言 id |
| 会话引用未知单元 | `会话表: 找不到名为「清洗」的代码单元` | 检查 `` `清洗` = `` 绑定 |
| 单元重复 | `会话表: 单元「汇总」重复出现` | 每个单元只列一次 |
| 语言不匹配 | `会话表: 单元「前端」(node) 不能使用 python 内核「分析」` | 换内核或换语言 |
| 未入会话 | (非错误)view 徽标:`未入会话` | 需要时加一行 |
| 内核表为空 | `内核表: 至少声明一个内核,或删除该表使用默认内核` | 删除表或补行 |
| 会话表为空 | `会话表: 至少列出一个单元,或删除该表使用自动顺序` | 删除表或补行 |
原则:**不静默忽略**。读者必须知道为什么某个 cell 没跑。
---
## 7. 与 program execution 的关系
- `内核表` / `会话表` 只是传递给 `foreign.session` 的普通表变量,不是保留名。
- `marqdo run` 仍然执行 `# main` 的程序语义;这两个表会被求值为普通数据。
- `run` 的外联编排用显式 API(`foreign.session_open` / `session_eval` / `call`);`foreign.session` 句柄服务 `view` 的 cells 与一键 Run All。
- 两者可以并存:
- 文档用表描述“交互时怎么跑”;
- `# main` 用显式调用描述“CI 时怎么跑”。
- 如果两者冲突,以 `run` 的程序语义为准;cell 表只影响 `view`。
这样避免把“执行计划”变成第二套程序语义。
---
## 8. 状态桥的语法边界
v2 **不**为状态交换新增表格/注释。原因:
- “什么时候送、什么时候取、送到哪个内核、赋值给哪个 Marqdo 变量”需要精确语义;
- 若做成隐式表格动作,容易产生隐藏状态与顺序歧义;
- v2 先用显式 API,把时序讲清楚:
```markdown
把 `数值表` 送进 `分析` 内核:
**> foreign.session_set id="分析" name="xs" value=`数值表`**
从 `分析` 内核取回 `mean`:
**`均值` = > foreign.session_get id="分析" name="mean"**
```
- view 提供状态面板与 Push/Pull 按钮,减少手写 API 的需要;
- 声明式 `共享表` 作为 v2.1 提案,等 session value store 与“每次单元执行前后”的时序稳定后再引入。
这不是降级:v2 的功能完整(可读可写、可推可拉),只是不用隐式语法承载时序。
---
## 9. 未来扩展(不承诺进 v2)
1. `共享表`:
`| 内核变量 | Marqdo 变量 | 方向 | 说明 |`,每次单元执行前送入、后取回。
2. 每个 cell 的“运行条件/依赖”列:`依赖` 列声明上游单元。
3. 内核别名:`内核表` 的 `名称` 可被 `use` 或短名引用。
4. 多文件会话:跨 `.mq.md` 的共享内核(默认仍隔离)。
5. 语言特定的“会话能力”列(是否支持持久、是否支持行级调试)。
任何一项都要先过 §5 的可读性规则与 `core-surface` 检查。
---
## 10. 实现落点
| 逻辑 | 位置 |
|---|---|
| 识别 `会话` 的 foreign.session 句柄 | `src/host/foreign_doc.rs` |
| 读取绑定值 | AST `Stmt::Assign` + `Expr::Table` / `Expr::List`;或最近一次 run 的 bindings |
| 校验名称/语言/重复/未入会话 | 同上;错误进入现有 Diagnostic |
| cell index(绑定名/行号/语言/source hash) | 解析后的 `Module` 遍历 |
| 只读展示 | view Structure:表渲染成普通表格 + 徽标 |
| 执行 | Document Session API(见 [notebook-session.md](notebook-session.md)) |
解析器本身**不需要改**。这是本设计最重要的约束:语法是既有标记的组合,不是新构造。
@@ -0,0 +1,426 @@
# 遮蔽描述与两级检索:内置词表做范例,参数做扩展
| | |
|---|---|
| 状态 | **Accepted · 实施中**(与 [occlusion-syntax.md](occlusion-syntax.md) 同步) |
| 日期 | 2026-10-22 |
| 关键决策 | ①`[]` 是自由描述,不执行 ②**两级词表**:内置=范例/默认,参数=扩展 ③空载荷**一律 warning** ④工程化写进 README,提示词同步更新 |
| 前置 | [occlusion-syntax.md](occlusion-syntax.md) |
---
## 0. 五条定调
1. **`[]` 里是纯粹的描述文字,对执行没有任何作用。** 编译器**不解析**,只做**检索**。
2. **两级词表**:
- **内置词表 = 范例 + 默认检索集**(零配置可用;给 LLM 一个稳定范式)
- **参数 = 扩展/覆盖**(`--grep 任意词`,项目自己的说法照样能搜)
3. **空载荷一律 warning**:`()` 为空说明"这段遮蔽里没有可执行内容",写 `None` 即消除。
4. **强力推荐 LLM 申报**:写不了真接口就"申报",别"假装"。提示词同步更新。
5. **工程化实践写进 README**,不另造文档。
一句话:
> **描述给人读;内置词给个范式;参数给自由;空着不写会被提醒。**
---
## 1. 为什么要允许「假接通」
模型被要求"接入搜索"时,最省力的是写个返回固定值的函数,然后声称已接通。
| 处理方式 | 结果 | 问题 |
|---------|------|------|
| **A 禁止**("不许伪造") | 模型改用更隐蔽的伪造 | 不可检测、不可计数 |
| **B 放任** | 静默假功能 | 文档撒谎,没人知道欠了多少 |
| **C 申报**(本方案) | 允许,但写进描述 | 代码照跑;欠据可数、可查 |
C 的关键:**不改道德要求,改激励**——申报比伪造省力,且申报后代码照样跑。
---
## 2. `()` 内部语法定稿
### 2.1 取元
| 语义 | 写法 |
|------|------|
| Map 取成员 | `at(表, 键)` |
| List 第 n 项(1-based) | `at(列表, 1)` |
| 缺键取默认(不崩) | `get(表, 键, 默认值)` |
### 2.2 调用
| 形态 | 写法 |
|------|------|
| 位置实参 | `加一函数(31)`(逗号可选:`加一函数(31 2)`) |
| 具名实参 | `计税(档位=2, 金额=100)` |
| **带空格 callee** | `加一 号(31)` → callee = 第一个 `(` 之前的全部文本 |
| 库路径 / 方法 | `txt.str_trim(s)` / `obj.方法(x)` |
实测:`加一 号(31 )` → `32`;`> 加一 号 31` → `unknown function 加一`。
**`(` 是明确分隔符**——这是缺陷 D8 的结构性解法。
### 2.3 循环
```markdown
- [从篮子里取出的每个果子](遍历 篮子 为 果)
```
### 2.4 空载荷:**一律 warning**
| 写法 | 结果 |
|------|------|
| `[功能,开发中]()` | ⚠️ `label.empty_payload` |
| `[功能,开发中](None)` | ✅ 无警告 |
| `[功能,开发中](json.parse text="[]")` | ✅ 无警告 |
**为什么一律报**:空 `()` 就是"什么都没写"。哪怕桩也该说明返回什么——
`None` 也是答案,下游能据此判断。
**为什么不会造成存量噪音**:遮蔽语法是新形式,**今天仓库里一处都没有**。
> 可调旋钮(**非默认**):若实际使用中觉得"已申报的桩也报警"太吵,
> 可开启「命中内置词表则降为 hint」。默认关闭——遵守"空载荷必须被看见"。
---
## 3. 两级词表
### 3.1 第一级:内置词表(范式 + 默认检索集)
**它是什么**:编译器内置的一张**小词表**,用途三个——
| 用途 | 说明 |
|------|------|
| **范式** | 给 LLM 一个稳定写法:不知道怎么写状态,就照这个词表写 |
| **默认检索集** | `marqdo labels pending` 零配置即可用;跨项目可比 |
| **默认豁免集** | 命中这些词的遮蔽默认跳过 stale(见 §6.1) |
**它不是什么**:**不是语法**。写不写、怎么写都不影响解析与执行。
### 3.2 内置词表(v1)
| 组 | 关键词(子串任一命中即算) | 计入 |
|----|--------------------------|------|
| **未完成** | `待开发` `未开发` `开发中` `未实现` `待实现` `未接` `接口未接` `TODO` | pending |
| **假数据** | `模拟` `假数据` `桩` `占位` `stub` `mock` | pending |
| **演示** | `示例` `样例` `demo` | demo |
| **不稳** | `实验` `试验` `experimental` | experimental |
| **将删** | `废弃` `弃用` `deprecated` | deprecated |
| **待核** | `待校验` `未验证` `待确认` | unverified |
- 组间**独立计数**,不合并
- `pending` = 未完成 ∪ 假数据(默认口径,最常用)
- 词表版本随编译器走;扩词表**不动语法**
### 3.3 第二级:参数(扩展与覆盖)
```bash
# 默认:内置 pending 集
marqdo labels pending
# 覆盖:只用我给的词
marqdo labels search --grep "接口未联调,联调中"
# 合并:我给的 + 内置
marqdo labels search --grep "联调中" --also-builtin
```
| 参数 | 语义 |
|------|------|
| `--grep A,B` | **替换**为 A、B(子串、OR、英文大小写不敏感) |
| `--also-builtin` | 与内置词表**取并集** |
| `--group pending,demo` | 用内置的某几组(不带 `--grep` 时) |
MLSP 对应:
```json
{ "method": "labels.search",
"params": { "grep": ["联调中"], "also_builtin": true, "json": true } }
```
### 3.4 为什么保留内置词表
| 理由 | 说明 |
|------|------|
| **LLM 有范本** | 模型不必发明措辞,照着写即可,稳定性显著提高 |
| **跨项目可比** | 大家用同一套词,"还有多少没做"才有统一含义 |
| **零配置可用** | CI 不必先写一份词表才能统计 |
| **失败模式可控** | 词不全时用参数补,而不是每个项目各自发明一套 |
**代价**:内置词表是一种"语义偏见"。缓解方式是**两级**——
内置只做默认值,参数永远可覆盖/扩展;且词表不参与语法,写别的措辞完全合法。
### 3.5 识别规则:纯子串,无位置/分隔符要求
```rust
// 语义示意
for (group, words) in TABLE(words_from_params_or_builtin) {
if words.iter().any(|w| label_text.contains(w)) { hits.insert(group) }
}
```
| 写法 | 命中 |
|------|------|
| `[某某功能开发中]` | ✅ 无分隔符 |
| `[搜索接入,待开发]` | ✅ 逗号 |
| `[搜索接入-待开发]` | ✅ 连字符 |
| `[【待开发】搜索接入]` | ✅ 括号 |
| `[这段还没写完]` | ❌ 无词(合法,不计数) |
- **识别不到不报错、不提示**——描述自由
- **误判必然存在**(`[不属于待开发范围]` 会命中):只影响计数,不影响执行;
输出带描述原文,人可判断;否定词窗口留 v1.1 可选
---
## 4. 桩的语义
### 4.1 三条规则
| # | 规则 | 原因 |
|---|------|------|
| 1 | **桩必须能跑**(不得报错) | 否则整篇文档被阻断 |
| 2 | **桩必须写明返回什么** | 空载荷 → warning;写 `None` 也行,但不能什么都不写 |
| 3 | **桩不得被当成已完成** | 描述里申报;检索能查到;`view` 有徽章 |
### 4.2 桩返回什么
| 手段 | 写法 |
|------|------|
| 显式空值 | `[某某功能开发中](None)` |
| 常量占位 | `[税率预报,模拟](0.1)` |
| 假数据 | `[搜索结果,模拟](json.parse text="[]")` |
| **桩 + 契约(推荐)** | 配合返回契约声明类型 → 桩是"有类型的洞" |
```markdown
## 搜索
| 返回 | 类型 | 说明 |
|------|------|------|
| | list | 命中列表(当前未接) |
[按关键词检索,接口未接,模拟](json.parse text="[]")
```
### 4.3 惯例(不强制):桩返回值带 `stub: true`
```markdown
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
```
---
## 5. 工程化:写进 README,提示词同步更新
### 5.1 README 增补(`README.md` 新节)
> **工程习惯:允许申报未完成,但不允许假装完成**
>
> ```markdown
> [按关键词检索,接口未接,待开发](None)
> ```
>
> - 桩必须能跑,并写清返回值(写 `None` 也比空着好)
> - 描述是自由文本;内置词表只是推荐用词与默认检索集
> - 盘点:`marqdo labels pending`;自定义:`--grep 你的词 --also-builtin`
> - 门禁:`--baseline` + `--fail-on-increase`(棘轮:只拦新增,不追旧账)
> - LLM:接不了就申报;提示词见 `ext/ai/agent.mq.md`
### 5.2 提示词更新(`ext/ai/agent.mq.md`)
| 位置 | 现状 | 增补 |
|------|------|------|
| `:48` 默认 standing(`You are a Marqdo agent…`) | 只讲"源码是真相" | 追加一句申报约定 |
| `:39` how-to-act 协议段 | 只讲 CALL/READ | 追加"未完成必须申报" |
**建议追加文本**(英文,与现有 standing 一致):
```text
When you cannot truly wire a capability, do not fake it silently and never claim it works.
Write it as an occlusion with an explicit status instead:
[按关键词检索,接口未接,待开发](None)
Stubs must run without error and must state their return value (None is acceptable).
Before finishing, check your own declarations with labels.pending.
```
**为什么这条对 LLM 有效**:把"编造"变成"填表"——模型不必判断算不算伪造,
只需写出状态词并给一个返回值。
### 5.3 工具面
| 工具 | 用途 |
|------|------|
| `labels pending` | 内置词表口径的未完成清单 |
| `labels search --grep … [--json/--count/--also-builtin]` | 任意词盘点 |
| `labels search … --changed` | 只看本次变更涉及的 |
| MLSP `labels.search` | 协议内同上 |
### 5.4 指标
| 指标 | 算法 |
|------|------|
| `pending_count` | `labels pending --count` |
| `unlabeled_empty` | `label.empty_payload` warning 数 |
| `stub_ratio` | pending / 遮蔽总数 |
| `stub_age` | 需 VCS(可选,不进默认路径) |
---
## 6. 生命周期
```
① 写桩 [按关键词检索,接口未接,待开发](None)
↓
② 盘点 labels pending → 列出它
↓
③ 开发 换成真实 HTTP 调用
↓
④ 复核 去掉"待开发"字样、改写描述
↓
⑤ 数字-1 检索结果自动减少
```
### 6.1 stale 豁免(默认用内置集)
| 情形 | stale 行为 |
|------|-----------|
| 描述命中**内置 pending 组**(未完成/假数据) | **豁免** |
| 命中 `将删`(废弃) | **豁免** |
| 命中 `示例` / `实验` / `待核` | 正常报 |
| 空载荷 | **豁免**(它就是桩) |
| 无命中、有实现 | 正常报 |
| `check --stub-words "A,B"` | **覆盖**内置集,用 A,B 判定豁免 |
理由:桩本来就是"未完成",描述已明说。若桩一被改动就报 stale,
12 个桩会变 12 条常驻警告——**正好制造我们要消灭的疲劳**。
### 6.2 防"做完了忘去掉申报"
- `labels search --grep … --changed`:本次变更中被改过的桩
- 会话末汇总带一行 `pending_touched: 2`(只给数字,不逐条)
---
## 7. 与防疲劳机制的协同
| 机制 | 作用 |
|------|------|
| 桩豁免 stale(默认内置集) | 12 个桩不会变成 12 条常驻警告 |
| 债务用**棘轮**(`--baseline` + `--fail-on-increase`) | 老债不阻塞、新债立刻拦 |
| 检索是**按需命令**,不进 `check` 人类输出 | 零噪音 |
| 搜不到**不报错** | 描述自由,机器不纠正用词 |
| 空载荷 warning 仅作用于新语法 | 不可能产生历史债 |
---
## 8. 编译器实现点
| 位置 | 要做的事 |
|------|---------|
| `src/parse` | 解析 `[描述](实现)`,**原样保存描述**(不解析、不分类) |
| `src/ast.rs` | `Expr::Occluded { label: String, inner: Option<Box<Expr>> }` |
| `src/label.rs`(新增) | **内置词表常量** + 描述索引/检索(子串、OR、大小写不敏感)+ L1 引用一致性 + T1 前后对比 |
| `src/check.rs` | 三条:`label.missing`(error)、`label.ref_dangling`(error)、`label.empty_payload`(**warning,一律**) |
| `src/interp.rs` | 描述**不影响求值**;空载荷 → `None` |
| `src/main.rs` | `labels pending/search --grep … [--also-builtin/--json/--count/--changed]`;`check --stub-words …` |
| `src/mlsp.rs` | `labels.search`(含 `also_builtin`)、`validate.stub_words`、会话汇总 `pending_touched` |
| `src/view/render.rs` | 遮蔽渲染:描述为正文、实现可折叠;桩徽章 |
| `README.md` | 新增「工程习惯」一节(§5.1) |
| `ext/ai/agent.mq.md` | `:48` standing 与 `:39` 协议段追加申报约定(§5.2) |
**分层**:内置词表是**数据**(常量表),检索是**纯函数**,语法**零依赖**——
扩词表不改语法,改语法不动词表。
---
## 9. 示例
### 9.1 无分隔符申报
```markdown
[某某功能开发中](None)
```
```bash
marqdo labels pending # 命中(内置「开发中」)
```
### 9.2 假算指标
```markdown
本季度 **[客户留存率,待开发](0.0)**,环比变化 **[留存环比,模拟](0.0)**。
```
### 9.3 假接通外部系统
```markdown
[ERP 推送,模拟](json.parse text={"ok":true,"stub":true})
```
### 9.4 该报 warning 的空载荷
```markdown
[应纳税额]() # ⚠️ label.empty_payload
```
### 9.5 项目自己的说法(参数层)
```markdown
[接口还在联调,先返回空](json.parse text="[]")
```
```bash
marqdo labels search --grep "联调" --also-builtin # 内置 + 自定义一起数
```
### 9.6 任意措辞(合法、不被自动分类,但可被搜)
```markdown
[这段还没写完](0)
```
```bash
marqdo labels search --grep 还没写完 # LLM 自己挑的词,照样搜到
```
---
## 10. 风险与取舍
| 风险 | 说明 | 缓解 |
|------|------|------|
| 子串误判 | `[不属于待开发范围]` 会命中 | 只影响计数;输出带原文;否定词窗口留 v1.1 |
| 内置词表是语义偏见 | 规定了"什么算未完成" | **两级**:内置只做默认,参数可覆盖/扩展 |
| 空载荷 warning 偏多 | 作者爱留空 | 修法极简(写 `None`);仅影响新语法;可留降级旋钮 |
| 桩腐化 | 忘去掉申报 | `--changed` + 会话汇总,不做常驻警告 |
| 假功能上生产 | 最坏情况 | `view` 显著标记;CI 可 `--count` 门禁 |
| LLM 滥用申报逃避检查 | 把真实现标成待开发 | 申报只增加可见性、不减少检查;豁免 stale 的代价是计入债务 |
---
## 11. 已定 vs 待定
**已定(本文即规范)**
| 项 | 结论 |
|----|------|
| 描述性质 | 自由文本,不执行,不参与类型/作用域 |
| 词表 | **两级**:内置范例/默认 + 参数扩展 |
| 空载荷 | **一律 warning**(写 `None` 消除) |
| 检索语义 | 子串 + OR + 英文大小写不敏感 |
| stale 豁免 | 默认内置 pending/将删组;`--stub-words` 覆盖 |
| 棘轮 | `--baseline` + `--fail-on-increase` |
| 工程化落点 | README 一节 + `ext/ai` 提示词两处 |
**待你点头**
| # | 问题 | 建议 |
|---|------|------|
| 1 | 内置词表就 §3.2 这六组 | 是 |
| 2 | `pending` = 未完成 ∪ 假数据 | 是 |
| 3 | `--grep` 替换、`--also-builtin` 合并 | 是 |
| 4 | 空载荷"降级旋钮"先不做 | 是(先按一律 warning 跑一段看噪音) |
| 5 | 提示词追加文本按 §5.2 写 | 是 |
> 点头后即按 M1 → M2 → M4 → M9 → M6 开工;首批金样用 §9 的六个例子。
+624
View File
@@ -0,0 +1,624 @@
# 遮蔽语法(Occlusion Syntax):`[描述](实现)` 设计与实施总纲
| | |
|---|---|
| 状态 | **Accepted · 实施中**(M0 起,本文档为实施依据) |
| 日期 | 2026-10-22 |
| 决策 | 纯度;标签可省略书写但**编译器报错**;新鲜度校验**不依赖 git**;**会话末做一次性汇总** |
| 定位 | 本文把 `[]()` 从「若干语法的集合」重新定义为**一种语法、一个目的:遮蔽** |
| 前置 | [bracket-as-label-evaluation.md](bracket-as-label-evaluation.md) · [label-freshness-and-repair.md](label-freshness-and-repair.md) · [warning-fatigue-control.md](warning-fatigue-control.md) · [staleness-providers.md](staleness-providers.md) · [t1-session-staleness.md](t1-session-staleness.md) |
| 增补 | [occlusion-description-and-search.md](occlusion-description-and-search.md) — **两级词表(内置=范例/默认;参数=扩展)**;空载荷一律 warning;桩语义;工程化落点(README + `ext/ai` 提示词);**`()` 内部语法定稿见该文 §2** |
---
## 0. 术语(后文一律按此使用)
| 术语 | 含义 |
|------|------|
| **遮蔽(occlusion)** | 用一段人话盖住一段实现:读者看人话,机器看实现 |
| **描述(label)** | `[]` 里的文本。**不可执行**,只给人读,是可被机器核验的断言 |
| **实现(payload)** | `()` 里的表达式。**唯一执行**的部分 |
| **显式遮蔽** | `[描述](实现)` —— 描述与实现写在同一处 |
| **隐式遮蔽** | 叙述段落 + 紧接的 `>` 调用 —— 描述是上方那段散文 |
| **新鲜(fresh)** | 描述与实现仍然相符 |
| **过期(stale)** | 实现变了、描述没变 —— 描述可能已不再成立 |
## 0.1 开发环境前置(实施前必须就绪)
本机(glibc 2.36、无系统 gcc/go/python3)已验证过的完整环境:
```bash
source scripts/dev-env.sh # rust 1.81 + go 1.25 + python 3.12 + zig(gcc shim, glibc 2.36)
./scripts/build-web-plugin.sh # 产出 libweb.so,否则 gold 测试会失败
```
两个非直觉约束(踩过的坑,写进文档免得后人重踩):
| 约束 | 现象 | 处理 |
|------|------|------|
| `$HOME` 不可写 | zig 报 `AccessDenied` | `ZIG_GLOBAL_CACHE_DIR` / `ZIG_LOCAL_CACHE_DIR` 指向工作区 |
| **`/tmp` 是 noexec tmpfs** | Go 链接 `signal: aborted`、zig `AccessDenied` | `TMPDIR` 指向可写且**可执行**目录 |
基线(改动前必须先跑通):`cargo test --release` → **554 passed / 0 failed**;
`marqdo check` 对 `lib/` + `ext/ai/`(59 文件)→ **0 warning / 0 error**。
任何里程碑都不得让这两个数字变差。
---
# Part I · 示例先行
## 1. 六个示例
### 1.1 嵌套取值:不可读 → 可读
**今天**(读者要在三层括号间来回跳):
```markdown
**单价 = [1]([苹果]([水果类](货架)))**
```
**遮蔽之后**:
```markdown
**单价 = [水果类里苹果的第 1 项价格](at(at(at(货架, 水果类), 苹果), 1))**
```
人读方括号,机器读圆括号。**嵌套再深,读者也只看一句人话。**
### 1.2 长表达式打断叙述
**今天**:
```markdown
本季度应缴税额为 **金额 * 税率 * (1 - 减免比例) + 附加费**,请注意申报期限。
```
一句话被一串符号劈成两半。
**遮蔽之后**:
```markdown
本季度应缴税额为 **[应缴税额](金额 * 税率 * (1 - 减免比例) + 附加费)**,请注意申报期限。
```
叙述仍然是句子;复杂算式被折进 `()`。
### 1.3 抽象层次混杂:把实现藏到读者不需要看的地方
**今天**(读者被迫读实现细节):
```markdown
价格随会员等级浮动,具体为 **基础价 * 会员折扣[等级](折扣表) * (1 + 旺季系数)**。
```
**遮蔽之后**(论证留在叙述里,算法藏起来):
```markdown
价格随会员等级浮动:**[会员最终价](基础价 * at(折扣表, 等级) * (1 + 旺季系数))**。
```
### 1.4 循环:来源从此可见
**今天**(渲染成「名为果的链接指向篮子」,看不出是遍历):
```markdown
- [果](篮子)
**总重 = 总重 + [重量](果)**
```
**遮蔽之后**:
```markdown
- [从篮子里取出的每个果子](遍历 篮子 为 果)
**总重 = 总重 + [重量](at(果, 重量))**
```
「从哪来」写进了人话——**不再依赖读者是否用了 `marqdo view` 才能看懂。**
### 1.5 带空格的函数名(**已实测验证**)
**今天**(`>` 调用无法表达,这是缺陷 D8):
```markdown
> 加一 号 31 # ❌ unknown function `加一` —— 空格把名字切断了
```
**遮蔽之后**(`(` 成为明确分隔符,空格不再是切词依据):
```markdown
**结果 = [加一之后的值](加一 号(31))**
```
**实测证据**(1.5.2 原型):
| 写法 | 结果 |
|------|------|
| `> 加一 号 31` | ❌ `unknown function 加一` |
| `加一 号(31 )`(括号调用) | ✅ **32** |
| `问候("世界")` | ✅ `你好 世界` |
> **因为 `()` 里的 callee 取「第一个 `(` 之前的全部文本」,空格不再有任何歧义。**
> 这正是你说的「`()` 内部对带空格的函数名处理方式很多样」——而且它不只是"很多样",
> 它是**结构上唯一正确**的处理:用括号做边界,而不是用空白。
### 1.6 反例:什么时候**不该**遮蔽
```markdown
# 反例:为遮蔽而遮蔽
**总计 = [总计](a + b)** # ❌ 描述等于代码,白加一层
**[价格](price)** # ❌ 描述等于变量名,无信息增量
```
**判据**:如果描述不能比实现**多提供信息**(意图、来源、单位、why),就不要遮蔽。
遮蔽的收益是"读者不用读实现",若描述只是把实现读了一遍,收益为零、成本照付。
---
## 2. 定义:遮蔽语法
```markdown
[ 描述 ] ( 实现 )
└─ 人读 ─┘ └─ 机读 ─┘
```
### 2.1 三条铁律
| # | 铁律 | 理由 |
|---|------|------|
| 1 | `[]` **永不执行** | 与「叙述默认安全」一致:只说人话的东西不改变程序行为 |
| 2 | `()` **是唯一执行体** | 语义只有一处,读者不必猜两层 |
| 3 | **遮蔽必须可校验** | 见 §2.2 |
### 2.2 核心定理:遮蔽创造信任负债
> **你把实现藏起来,读者就必须相信描述。**
> 所以:**遮蔽 ⇔ 描述成为承重结构 ⇔ 必须可被机器核验。**
这条定理把「新鲜度校验」从"附加功能"变成"遮蔽的**代价与前提**":
- 不遮蔽 → 读者能自己核对代码 → 描述过期无伤大雅(顶多是注释旧了)
- 遮蔽 → 读者看不见代码 → **描述一旦过期,文档就变成了假的**
所以平台必须提供:**实现一变,描述立刻被质疑**。
这不是锦上添花,是这套语法的**合法性来源**。
### 2.3 为什么必须是「链接外形」
| 性质 | 链接(`[]()`) | 其它候选 |
|------|--------------|---------|
| 文本不可执行、目标可执行 | ✅ 天生分离 | 括号内联(`(...)`)做不到"只读文本" |
| 与 Markdown 渲染一致 | ✅ 渲染成超链接,读者熟悉 | 箭头 `→` 是自造符号 |
| 可承载任意长文本 | ✅ | 下标 `x[y]` 放不下长描述 |
| 可被工具定位/跳转 | ✅ 天然锚点 | 注释块不行 |
**一句话**:链接是唯一"人类文本与机器目标天然分工"的 Markdown 结构,
而 Marqdo 正好需要这个分工。
---
# Part II · 应用场景(按**动机**分类,不按语法分类)
**重要**:遮蔽语法**不是**"循环语法""取元语法""调用语法"。
它没有专属用途——它是**一种处理不可读性的手段**。任何表达式都可被遮蔽。
## 3. 五类遮蔽动机
| 动机 | 症状 | 遮蔽后得到什么 |
|------|------|---------------|
| **A 不可读** | 嵌套过深、括号堆叠 | 读者只看一句人话 |
| **B 打断叙述** | 长算式把句子劈成两半 | 句子完整,算式退居括号 |
| **C 层次混杂** | 论证与实现细节混排 | 论证在上,实现可折叠 |
| **D 来源不明** | 看不出数据从哪来(如 `- [果](篮子)`) | 来源写进人话 |
| **E 名称受限** | 函数名含空格写不出调用(D8) | `(` 做分隔符,名字自由 |
> 注意 D 与 E:它们是**遮蔽顺带解决的问题**,不是遮蔽的目的。
> 若把它们写成"循环语法 / 调用语法",就会限制这套语法的适用面;
> 按动机写,它才能覆盖未来尚未想到的不可读情形。
## 4. 什么时候不该遮蔽
| 情形 | 说明 |
|------|------|
| 描述 = 实现(§1.6) | 无信息增量 |
| 只用一次且已足够可读 | 遮蔽会**增加**读者的跳转成本 |
| 描述无法具体化 | 笼统的描述不可校验,等于把信任成本转嫁给读者 |
| 性能敏感的热路径 | 遮蔽本身不贵,但过度嵌套的表达式不利于后续优化 |
---
# Part III · 语法规范
## 5. 文法
```
遮蔽 ::= '[' 描述 ']' '(' 表达式? ')'
描述 ::= 非空自由文本(可含 `实体`、空格、关键词;v1 不跨行)
表达式 ::= 现有表达式文法(含 §6 的调用形);**可空** → 值为 None
带括号的调用 ::= callee '(' 实参列表? ')'
callee ::= 非空文本,不含 '('(**允许空格**,见 §6.2)
实参列表 ::= 实参 (分隔 实参)*
实参 ::= 名 '=' 值 | 值
分隔 ::= 空白 | ',' # 逗号可选、容错
```
出现位置:**表达式位置 / 语句位置 / 循环项位置**(三处形态一致)。
> **空载荷 `()`**:合法(值 `None`),但**一律**报 `label.empty_payload`(warning)——
> 修法是显式写 `None` 或一个真实返回值。描述是自由文本,检索由**调用方传词**(子串匹配,无分隔符要求),
> 详见 [occlusion-description-and-search.md](occlusion-description-and-search.md) §3–§4。
## 6. `()` 之内
### 6.1 表达式文法不变
`()` 里就是今天 Marqdo 的表达式:算术、比较、调用、变量(`` `名` ``)、字面量。
**不引入第二套表达式语言。**
### 6.2 callee 可以含空格(解决 D8)
规则:**callee = 第一个 `(` 之前的全部文本**(去首尾空白)。
```markdown
[加一之后的值](加一 号(31)) # callee = "加一 号"
[会员最终价](会员价(等级=2 )) # 具名实参
```
依据实测:`加一 号(31 )` → `32`。
(当前实现的参数分词器会把 `)` 吞进末个实参,需要 M1 修掉;带尾随空格即可绕过。)
### 6.3 取元怎么写(纯度要求)
`[键](集合)` **不再是取元**(见 §9 迁移)。取元改为函数形:
| 语义 | 写法 |
|------|------|
| 取 Map 成员 | `at(表, 键)` 或 `get(表, 键)` |
| 取 List 第 n 项(1-based) | `at(列表, 1)` |
| 缺键不崩 | `get(表, 键, 默认值)` |
**理由**:与调用同一外形,读者不必区分"这是取元还是调用"——
而这正是遮蔽语法要消灭的那种"两套读法"。
### 6.4 循环
```markdown
- [从篮子里取出的每个果子](遍历 篮子 为 果)
```
- `[]` = 人读描述(来源、单位都可写)
- `()` = `遍历 <集合> 为 <变量>`
- **变量名从 `[]` 搬进 `()`**:`[]` 不再兼任标识符(否则"描述"与"名字"又打架)
## 7. 标签规则
| 规则 | 行为 |
|------|------|
| 空标签 `[](…)` | **error `label.missing`**(你说的"可省略书写但编译器报错") |
| 标签内 `` `实体` `` | 视为**断言**:该实体必须可解析且出现在 `()` 中(§10.1) |
| 标签含空格、中文、标点 | 允许 |
| 标签含 `]` | 不允许(转义规则见 §11.3) |
| 标签跨行 | v1 不支持(跨行标签会让定位困难) |
## 8. 与既有语法的关系
| 现有 | 归位 |
|------|------|
| `> 调用` | **保留**,作为"短形调用";同时纳入隐式遮蔽检查(§10.2) |
| `[callee] args` | **保留**为消歧/前置修饰形;仓库实测可执行使用量为 **0**(189 处是 `lib/*` 的 `Caller:` 说明行,不执行) |
| `[键](集合)` | **废止**(改为 `at/get`;复用 `[]()` 外形)→ 需版本门 |
| `- [项](集合)` | **废止**(改为 `- [描述](遍历 …)`)→ 需版本门 |
| `*…*` 返回 | 不变 |
## 9. 迁移(实测规模)
| 受影响 | 数量 | 文件 |
|--------|------|------|
| `[键](集合)` 取元 | **506 处** | 136 |
| `- [项](集合)` 循环 | **44 处** | 24 |
| 可执行方括号调用 | **0** | — |
| `Caller:` 说明行(不执行,无需迁移) | 189 | — |
**危险点:同形换义。** 迁移后 `[键](集合)` 会变成"遮蔽整个集合",语义静默改变。
因此必须:
1. **硬报错**:purity 模式下遇到旧形 → `syntax.legacy_index`,附迁移示例
2. **机械迁移工具**:`marqdo migrate labels --write`
3. **临时标签**:工具生成的标签 = 原键名,并标记为 `label.provisional`(**hint**,不报 error)
—— 不能让 506 处都变成红错,否则没人能开工
## 10. 错误信息规范
| code | 级别 | 触发 | 建议文案 |
|------|------|------|---------|
| `label.missing` | error | `[](…)` | 「给这段实现写一句人话,或改用不带遮蔽的写法」 |
| `label.ref_dangling` | error | 标签引用的实体不存在 | 「`X` 已不存在;改成 `Y` 或删掉该引用」 |
| `label.stale` | hint/warning | 实现变了、标签没变 | 「标签说 A,实现现在是 B;二者之一需改」 |
| `label.provisional` | hint | 标签 = 原键名 | 「建议把键名改写成读者能懂的一句话」 |
| `syntax.legacy_index` | error | 旧 `[键](集合)` | 「取元请写 `at(集合, 键)`;遮蔽请写 `[描述](at(集合, 键))`」 |
---
# Part IV · 新鲜度校验
## 11. 两种遮蔽关系
| 类型 | 形态 | 描述在哪 |
|------|------|---------|
| **显式遮蔽** | `[描述](实现)` | `[]` 里 |
| **隐式遮蔽** | 叙述段落 + 紧接 `> 调用` | 上方那一段散文 |
**两者都要查**——这是你明确要求的:"`>` 这种函数调用其实也应该被检查是否存在过期现象"。
### 11.1 L1:引用一致性(零依赖、确定性)
**规则**:断言 = 标签内的 `` `实体` ``。
1. 实体必须可解析(当前作用域/模块存在)
2. 实体必须出现在 `()` 的实际内容中(或经调用链可达)
不满足 → `label.ref_dangling`(error)。
**为什么低假阳性**:只有**显式反引号**才算断言;纯口语不参与判定。
**为什么能落地**:复用 Marqdo 已有的 `` `名` `` = 实体约定,**零新记号**。
### 11.2 隐式遮蔽:`>` 调用的描述从哪来
**规则**:取 `>` 行**上方紧邻的叙述段落**(连续非空行,遇空行/标题/代码行即止)作为描述。
```markdown
按 `税率` 与 `档位` 计算应缴税额:
> 计税 档位=2 金额=100
```
检查:
- 段落里 `` `税率` ``、`` `档位` `` 必须**出现在调用实参或 callee 中**,或可解析
- 若无叙述段 / 叙述里无反引号 → **不检查**(沉默,零噪音)
**这条规则的价值**:让**存量代码**(今天所有 `>` 调用)**无需改写**就获得新鲜度保护
——只要作者在调用上方写了一句带反引号的说明。
### 11.3 转义
| 需求 | 写法 |
|------|------|
| 标签里要写 `]` | `\]` |
| 标签里要写 `` ` ``(字面) | `` \` `` |
| 实现里要写 `)` | 由括号配对规则处理(字符串内 `)` 不算) |
### 11.4 T1:会话内检测(不依赖 git)
**机制**:`repair_apply` 内部同时持有 before(`source`)与 after(`new_source`),
解析两版,比较每个标签的 `()` 指纹:
> `stale ⟺ 标签文本未变 ∧ () 指纹变了`
- 按**标签文本**配对(不按行号)→ 移动代码不误报
- 标签文本变了 → 视为作者在更新描述,**不报**
- 新增/删除标签 → 不报
- 指纹只需**进程内一致**(`Expr` 现为 `Debug`,可用 `format!("{:?}")`;或补 `derive(PartialEq)`)
**为什么这能消灭疲劳**:作用域 = 模型自己的 diff;投递 = 一次;自包含(下轮不重复)。
### 11.5 会话末一次性汇总(**你要求要做**)
T1 刻意"不重复",因此需要**闭合**:
- **会话**定义:MLSP 一条连接的生命周期;CLI 为一次 `marqdo check` 运行
- 会话结束时输出**一次**:
```json
{ "session": { "labels_stale_seen": 3, "labels_fixed": 1, "labels_outstanding": 2,
"items": ["按 `税率` 计算总价", "篮子里的果子"] } }
```
- 只报**数字 + 标签文本**,不重复诊断详情(详情已在各轮给过)
- 若 `outstanding > 0`,可用 `"block"` 模式让客户端不得直接结束任务
### 11.6 能力自述与降级
| 环境 | 可用层 | 行为 |
|------|--------|------|
| CLI + VCS | L1 + T1 + T2 | 可跨会话 |
| CLI 无 VCS | L1 + T1 | 仅会话内 |
| agent 沙箱(`exec=false`) | L1 + T1 | **不调 git** |
| 浏览器 WASM | L1 + T1 | 无持久状态 |
| 单文件 / zip | L1 + T1 | — |
**`labels status` 必须显示当前启用了哪几层**,避免"没报 = 没问题"的误判。
---
# Part V · 实施计划
## 12. 里程碑总览
| M | 名称 | 产出 | 依赖 | 风险 |
|---|------|------|------|------|
## 13.1 实施进度
**全部完成**:M0 · M1 · M2 · M2.5 · M3 · M4 · M5 · M6 · M7 · M8 · M9 · M10
(每步含变更文档与测试;全量 605 passed / 0 failed;0 编译警告)。
| 里程碑 | 变更文档 |
|--------|---------|
| M1 | [change-m1-paren-call.md](change-m1-paren-call.md) |
| M2 | [change-m2-occlusion.md](change-m2-occlusion.md) |
| M2.5 | [change-m25-label-diagnostics.md](change-m25-label-diagnostics.md) |
| M3 | [change-m3-access-and-loop.md](change-m3-access-and-loop.md) |
| M4 | [change-m4-label-refs.md](change-m4-label-refs.md) |
| M5 | [change-m5-implicit-occlusion.md](change-m5-implicit-occlusion.md) |
| M6 | [change-m6-t1-session.md](change-m6-t1-session.md) |
| M7 | [change-m7-migration.md](change-m7-migration.md) |
| M8 | [change-m8-ratchet.md](change-m8-ratchet.md) |
| M9 | [change-m9-label-search.md](change-m9-label-search.md) |
| M10 | [change-m10-engineering-habits.md](change-m10-engineering-habits.md) |
| **M0** | 语义冻结 | 本文档 Accepted + 术语表进 `doc/design/` | — | 无 |
| **M1** | `()` 内调用增强 | `callee(args)`:`)` 终止、逗号、嵌套、**空格 callee** | M0 | 中(分词器共享) |
| **M2** | 遮蔽语法 | `[描述](表达式)` + 标签节点 + `label.missing` | M1 | 中 |
| **M3** | 普通取元与循环 | `at/get` 落地;`- [描述](遍历 …)` | M2 | 中 |
| **M4** | L1 引用一致性 | `label.ref_dangling`(error) | M2 | 低 |
| **M5** | 隐式遮蔽检查 | `>` 上方叙述 vs 实参 | M4 | 低 |
| **M6** | T1 + 会话汇总 | `repair_apply.check_labels` + 汇总 | M2 | 低 |
| **M7** | 迁移与版本门 | `marqdo migrate labels`、`syntax.legacy_index` | M3 | **高** |
| **M8** | 呈现与门禁 | `view` 徽章、`labels status/review`、CI | M4–M6 | 低 |
| **M9** | 描述检索与桩 | **两级词表**:`labels pending`(内置集)+ `labels search --grep … [--also-builtin]`、MLSP `labels.search`、空载荷 warning | M2 | 低 |
| **M10** | 工程化落点 | `README.md` 工程习惯一节 + `ext/ai/agent.mq.md` 提示词(standing 与 how-to-act)追加申报约定 | M9 | 低 |
**顺序建议**:M0 → M1 → M2 → (M2.5 空载荷/描述) → M4 → **M9** → **M10** → M6 → M5 → M3 → M7 → M8
理由:**先把"断言 + 复核 + 修复回路"跑通(M2/M4/M6),再动 506 处迁移(M7)**。
迁移一旦开始,中间态很痛;而 L1/T1 在旧语法上就能验证。
---
## 13. 每个里程碑的详细步骤
### M0 · 语义冻结
| 项 | 内容 |
|----|------|
| 改动 | 本文档标记 `Accepted`;`doc/README.md` 登记 |
| 要点 | 术语表(§0)作为唯一用词标准;`[]()` 一律称"遮蔽",不称"循环/取元/调用语法" |
| 验收 | 团队评审通过;后续文档一律引用本文术语 |
### M1 · `()` 内调用增强
| 项 | 内容 |
|----|------|
| 目标 | `callee(args)` 可用:`)` 作实参终止、可选逗号、嵌套调用、**callee 允许空格** |
| 改动文件 | `src/parse/expr.rs`(`parse_call_args` / `split_first_token` / `find_next_arg_boundary` / 新增 `try_paren_call`)、`src/parse/mod.rs`(`looks_like_paren_call` 接入两处调用判定) |
| 关键点 | ① `)` 必须是实参终止符(今天会吞进末个实参)② 逗号可容错剥离 ③ 嵌套 `f(g(1))` 需括号深度 ④ `callee = 第一个 '(' 前全部文本`(空格合法) |
| 测试 | 新增金样 `tests/structure/paren-call.mq.md`:单参/多参/具名/字符串/嵌套/空格名/库路径/方法 |
| 验收 | 上述金样全绿;`cargo test --release` **554 全绿不减**;**双后端**(tree + `--backend bytecode`)均通过 |
| 回滚 | 独立提交,可单独 revert(不改既有语义,风险低) |
### M2 · 遮蔽语法
| 项 | 内容 |
|----|------|
| 目标 | `[描述](表达式)` 解析为 `Expr::Occluded { label, inner }` |
| 改动文件 | `src/ast.rs`(新增节点 + `PartialEq`)、`src/parse/mod.rs`(表达式/语句/循环三处入口)、`src/interp.rs`(求值时透明传递 inner)、`src/bytecode/compile.rs`+`vm.rs`(编译为 inner,label 只留在调试信息) |
| 关键点 | ① 遮蔽对语义**完全透明**(`[d](e)` 的值 = `e` 的值)② label 必须存进 AST(供 L1/T1/诊断定位)③ 空 label → `label.missing` |
| 测试 | 金样:三处位置各一例;label 含中文/空格/标点;`label.missing` 反例 |
| 验收 | 双后端一致;554 全绿;`marqdo check` 对空标签报 error |
| 回滚 | 独立提交;新语法是增量的 |
### M3 · 普通取元与循环
| 项 | 内容 |
|----|------|
| 目标 | `at(表, 键)` / `get(表, 键, 默认)` 可用;`- [描述](遍历 集合 为 变量)` 可用 |
| 改动文件 | `src/interp.rs`(`at`/`get` 内建或库函数)、`src/parse/mod.rs`(循环新形)、`lib/table.mq.md`(`get` 带默认值) |
| 关键点 | 1-based 与现有 `at value= index=` 保持一致;`get` 缺键返回默认而非崩(修 D5 的痛点) |
| 测试 | 金样:Map 取元、List 下标、缺键默认、循环 |
| 验收 | 双后端一致;554 全绿 |
### M4 · L1 引用一致性
| 项 | 内容 |
|----|------|
| 目标 | 标签内 `` `实体` `` 校验:可解析 + 出现在 `()` |
| 改动文件 | **新增 `src/label.rs`**(标签模型、引用抽取、校验)、`src/check.rs`(接入)、`src/diagnostics.rs`(复用 `doc_anchor`/`doc_quote`,新增 `label_ref`) |
| 关键点 | ① 只认反引号(不猜中文词)→ 低假阳性 ② `doc_anchor` = 标签 span,`doc_quote` = 标签原文 ③ `code` 字段用 `label.ref_dangling` |
| 测试 | 单元:抽取/解析/缺失;金样:悬空引用的 error、正常引用的通过 |
| 验收 | 554 全绿;对现有仓库跑 `check` 仍为 **0 error**(除非真有悬空) |
### M5 · 隐式遮蔽(`>` 上方叙述)
| 项 | 内容 |
|----|------|
| 目标 | `>` 调用的描述 = 上方紧邻叙述段;其反引号实体须出现在实参/callee |
| 改动文件 | `src/label.rs`(段落归属规则)、`src/check.rs` |
| 关键点 | ① 段落边界:空行/标题/代码行即止 ② 无反引号则跳过(零噪音) ③ 默认级别 **hint** |
| 测试 | 金样:三种(有实体且匹配 / 有实体不匹配 / 无叙述) |
| 验收 | 554 全绿;现有仓库不因该规则新增 error |
### M6 · T1 + 会话汇总
| 项 | 内容 |
|----|------|
| 目标 | `repair_apply` 支持 `check_labels`;会话末输出一次性汇总 |
| 改动文件 | `src/mlsp.rs`(`repair_apply` 内比 before/after;新增 `session.summary` 方法或响应字段)、`src/label.rs`(标签配对与指纹) |
| 关键点 | ① 按标签文本配对 ② 标签变则不报 ③ 指纹进程内一致即可 ④ 会话状态按**连接**保存 |
| 测试 | 集成:`repair_apply` 改 `()` 不改 `[]` → 返回 stale;改 `[]` → 不返回;会话末汇总数字正确 |
| 验收 | 双后端;554 全绿;**无 VCS 环境下同样工作**(CI 里用临时目录验证) |
### M7 · 迁移与版本门
| 项 | 内容 |
|----|------|
| 目标 | `[键](集合)` / `- [项](集合)` 在 purity 模式下**硬报错**;提供机械迁移 |
| 改动文件 | `src/parse/expr.rs`(`link_index_shape_ahead` 改为报 `syntax.legacy_index`)、**新增 `src/migrate.rs`** + `src/main.rs` 子命令 `marqdo migrate labels` |
| 关键点 | ① 报错文案必须给"改成什么" ② 迁移生成 `[键](at(集合, 键))`,标 `label.provisional` ③ 一次性完成 506+44 处,避免中间态 ④ 迁移后必须跑全量回归 + 逐文件抽样 `run` |
| 测试 | 迁移前快照→迁移→回归对比;抽样 20 个文件 `run` 输出一致 |
| 验收 | 554 全绿;`marqdo check` 全仓 0 error;抽样输出无变化 |
| 回滚 | **必须整批回滚**(中间态不可用),建议单独分支 |
### M8 · 呈现与门禁
| 项 | 内容 |
|----|------|
| 目标 | `view` 显示遮蔽徽章与新鲜度;`labels status/review/confirm`;CI 可 gate |
| 改动文件 | `src/view/render.rs`(遮蔽渲染:显示 label,折叠 payload)、`src/main.rs`(`labels` 子命令)、`scripts/ci-*.sh` |
| 关键点 | ① `view` 里 label 是正文、payload 可折叠(这正是遮蔽的呈现价值) ② `labels status` 报能力层级与债务数字 |
| 验收 | 渲染截图人工评审;`labels status` 在无 VCS 环境正确降级 |
---
## 14. 测试计划(贯穿全部里程碑)
| 层 | 内容 | 门禁 |
|----|------|------|
| 单元 | 解析/求值/标签抽取/指纹比较 | `cargo test --lib` 全绿 |
| 金样 | 新增 `tests/structure/occlusion*.mq.md`、`paren-call*.mq.md` | `tests/gold.rs` 全绿 |
| 回归 | 全量 `554`(现基线) | 不得减少 |
| 双后端 | tree 与 `--backend bytecode` 各跑一遍 | 结论一致 |
| 差异 | 迁移前后同文件 `run` 输出逐字节相同 | 抽样 ≥20 文件 |
| 反向 | 故意破坏断言/标签,确认能报 | 每条规则至少一个反例 |
| 环境 | 无 git / 沙箱(`exec=false`)/ WASM 构建 | 不崩、不报依赖错 |
| 性能 | 1000 标签文件的 `check` 耗时 | 不劣化 >10% |
**反向验证是硬要求**:每个新检查必须证明"它真的会响",
否则就是在写永不触发的代码(本项目已多次遇到"静默通过"的缺陷)。
---
## 15. 风险登记
| 风险 | 概率 | 影响 | 缓解 |
|------|------|------|------|
| M1 分词器改动波及所有调用 | 中 | 高 | 独立提交 + 554 回归 + 双后端 |
| M7 迁移中间态不可用 | 高 | 高 | 整批迁移、单独分支、可整批回滚 |
| 遮蔽被滥用(描述=实现) | 高 | 中 | `label.provisional` hint + §1.6 反例进教程 |
| 标签自然语言无法核验 | 必然 | 中 | 只认反引号断言(可证伪才检查) |
| 误报疲劳 | 中 | **高** | T1 变更驱动 + hint 默认 + 会话末汇总 |
| 旧语法语义静默改变 | 中 | **高** | `syntax.legacy_index` 硬报错 |
| `Expr` 无 `PartialEq` | 确定 | 低 | 先用 `Debug`;或补 derive |
---
# Part VI · 待决策
| # | 问题 | 建议 |
|---|------|------|
| 1 | 取元函数名用 `at` 还是 `get`(两者都留?) | 都留:`at` 严格、`get` 带默认 |
| 2 | 实参分隔用逗号还是空白 | 两者都接受(逗号可选、容错) |
| 3 | 循环新形用 `遍历 集合 为 变量` 还是别的 | 先用它,后续可加别名 |
| 4 | `label.stale` 默认级别 | **hint**(会话末汇总再提) |
| 5 | M7 迁移是否在本文档同批做 | **否**:M2/M4/M6 先上线并验证,再动迁移 |
| 6 | 临时标签(`label.provisional`)是否接受 | **接受**,否则 506 处无法开工 |
| 7 | 标签是否允许跨行 | v1 不允许 |
| 8 | 是否把 `[]()` 的官方中文名定为「遮蔽」 | 建议定为**遮蔽语法**,并在教程里替代"取元/循环/调用语法"的说法 |
---
## 附:一句话总结
> **遮蔽语法不是给三种句式加糖,而是给"读者不该被迫读的那部分代码"一个体面的出口。**
> 它用链接的天然分工(人话 / 目标)实现这一点,
> 又因为"遮蔽创造了信任负债",所以必须配套可校验的新鲜度机制——
> 而 `>` 调用同样在负债之列。
@@ -0,0 +1,231 @@
# 调用写法评估:`[函数名](参数)` 与更接近人读的调用形式
> **2026-10-23 审阅裁决**:“原型回退”仅描述当时实验,当前 payload 已支持 `f(args)` 和具名实参。旧 Classic 索引冲突不再决定默认语法;保留熟悉的调用形态与文档原生描述并不矛盾。参见[文档原生指导 §2](document-native-development-guide.md#2-语法审查的保留修正与暂缓),不要把本文备选形式当作已批准的新语法。
| | |
|---|---|
| 状态 | **Proposed · 待决策**(原型已验证并已回退,未合入代码) |
| 日期 | 2026-10-22 |
| 提出 | 「`[函数名](参数1 参数2)` 这种写法有没有可能成立;调用能否更符合人读习惯」 |
| 更正 | 本文替代前两轮对用户意图的误读(前两轮在讨论「表 / 函数即值」,不是调用语法) |
| 相邻 | [link-style-call-evaluation.md](link-style-call-evaluation.md) · [function-as-table-semantics.md](function-as-table-semantics.md) · [collection-access-link.md](collection-access-link.md) · [call-arguments.md](call-arguments.md) |
---
## 0. 结论
| 问题 | 答案 |
|------|------|
| `[函数名](参数1 参数2)` 能否成立 | **技术上能,但代价在方括号**:它撞的是取元 `[键](集合)`,而命名空间里确有 2 个真实文件以函数名作键,任何「按名字消歧」都会静默改语义 |
| 更人读的调用能否成立 | **能,而且更干净**:`函数名(参数1 参数2)`(**不带方括号**)目前是**完全空闲的语法**,原型实测全量 **554 passed / 0 failed**,零回归 |
一句话:**想要「参数进括号」这个美感,不需要方括号——去掉方括号反而没有任何冲突。**
```markdown
**税率 = 查询税率(档位=2)** # 具名,读起来像函数调用
**合计 = 加(1 2)** # 位置,读起来像数学
**名 = txt.str_trim(" x ")** # 库函数同样适用(原型已验证)
```
---
## 1. 现状:今天的调用写法盘点(全部实测)
| 写法 | 位置 | 实测 |
|------|------|------|
| `> 加 1 2` | 语句 | ✅ 位置参数 |
| `> 加 a=1 b=2` | 语句 | ✅ 具名参数 |
| `[加] 1 2` | 语句 | ✅ 方括号标记 + 位置参数(用于消歧/前置修饰) |
| `**r = > [加] 1 2**` | 粗体赋值 | ✅ 返回 3(方括号调用**已支持空格参数**) |
| `**r = 加 1 2**` | 粗体赋值 | ✅ **不带 `>` 也能调用,已可用**(打印 3) |
| `**r = > 加 a=1**` | 粗体赋值 | ✅ 显式 `>` 形态 |
| `**r = 加(1)**` | 粗体赋值 | ❌ `trailing input in expression: "(1)"` |
| `**r = [加](1 2)**` | 粗体赋值 | ❌ `unknown function `[加](1`` |
| `> [加](1 2)` | 语句 | ❌ `unknown function `[加](1`` |
也就是说:**「参数放在括号里」这件事今天完全不存在**。
---
## 2. `[函数名](参数)` 为什么碰壁
### 2.1 方括号 + 圆括号 = 取元,这是**已定的语义**
[collection-access-link.md](collection-access-link.md) §1 写的是心智模型:
> **方括号 = 取出的名字,圆括号 = 从哪取。**
```markdown
**价 = [拿铁](菜单)** # 从菜单里取出「拿铁」
```
[call-arguments.md](call-arguments.md) §2 进一步锁定:
> `]` 后**紧邻** `(` → **取元** `[key](collection)`,不是 callee 标记。
所以 `[f](x)` 不是「还没被用的语法」,而是**已经被取元占用**。
### 2.2 靠「名字是函数还是键」消歧,会真的打断现有代码
这是本轮新增的硬证据。我把全仓库扫了一遍:
| 指标 | 数值 |
|------|------|
| `.mq.md` 文件 | 851 |
| `##` 级函数名 | 2367 |
| `[键](…)` 出现次数 | 983 |
| **键名与同文件函数名相同的冲突** | **5(去重后 2 个真实文件)** |
两个真实冲突(不是构造出来的):
```
ext/data/db.mq.md:122 *[count](r)* # 函数名 ## count,同时 r 里有 count 列
examples/code-as-docs/index.mq.md:79 价=[单价](行) # 函数名 ## 单价,同时 行 里有 单价 字段
```
**这说明任何「函数名优先」的规则都会改变这两处的行为**:它们本意是取元,却会被解释成调用。
反过来「数据优先」则永远无法用 `[f](1)` 调用。**两条路都走不通**——这不是实现难度问题,
而是同一外形承载两种语义的固有代价。
### 2.3 但有一个「无歧义子集」确实存在
`[f](1 2)` 与 `[f](a=1)` 里的括号内容**不是合法表达式**(实测 `x=1` 报
`unknown function`、`1 2` 报 `unknown function`),所以理论上可判为参数列表:
| 括号内容 | 能否是取元 | 可否判为调用 |
|---------|-----------|-------------|
| `(1 2)` 多 token | 否(非单一表达式) | ✅ 无歧义 |
| `(a=1)` 具名 | 否 | ✅ 无歧义 |
| `(1)` 单 token | **能** | ❌ 与 `[1](篮子)` 冲突 |
| `(m)` 单变量 | **能** | ❌ 与 `[a](m)` 冲突 |
于是 `[f](1)`(最常见的单参调用)**永远无法**与取元区分。
一个「多参数能用、单参数不能用」的语法,对使用者是最难记的一类。
---
## 3. `函数名(参数)`:空闲语法,原型验证通过
### 3.1 它是空闲的
实测 `**r = 加(1)**`(原型前)报 `trailing input in expression: "(1)"` ——
说明 `名字(` 今天既不表示取元,也不表示任何别的含义。**没有既有语义要保护。**
### 3.2 原型做了什么
改了两处(**已回退,仅作验证**):
1. `src/parse/expr.rs`:新增 `try_paren_call` —— 紧随其后的 `(` 视为参数列表;
在 `parse_call_tail` 里优先尝试。
2. `src/parse/mod.rs`:粗体赋值与 `>` 两条路径的「像调用」判定加上
`looks_like_paren_call`(让单 token 的 `加(1)` 也能进入调用分支)。
### 3.3 原型实测结果
| 用例 | 结果 |
|------|------|
| `加(1)` | ✅ 返回 2(单参) |
| `加(1 2 )` | ✅ 返回 3(多参) |
| `加("1" "2")` | ✅ 返回 `12`(字符串参数) |
| `加(1 2)` | ❌ 末参数把 `)` 吞了 |
| `加(a=1 b=2)` | ❌ 具名参数值把 `)` 吞了 |
| `加(1, 2)` | ❌ 逗号不是分隔符 |
| `加(加(1 2) 3)` | ❌ 嵌套未支持 |
| `txt.str_trim(" x ")` | ✅ 返回 `x`(**库函数路径可用**) |
| **全量测试** | ✅ **554 passed / 0 failed** |
**两条关键结论**:
1. **零回归**:新语法是纯增量,没有破坏任何既有用例(含 4 个 `[k](c)` 取元金样)。
2. **真正的落点在参数分词器,不在语法**:`加(1 2)` 失败、`加(1 2 )` 成功,
差别只是 `)` 前多一个空格——说明 `parse_call_args` 的分词把 `)` 当成了 token 的一部分。
要修就得动 `parse_call_args` / `split_first_token` / `find_next_arg_boundary`,
而这个分词器是**所有调用**(含今天在用的 `> f a=1`)共享的。
这解释了为什么这件事「看起来 10 行、实际一次核心改动」。
---
## 4. 人读性对比
同一个意思,五种写法:
| 写法 | 读起来 | 现状 |
|------|--------|------|
| `> 加 1 2` | 「调用加,1 和 2」 | ✅ |
| `**合计 = 加 1 2**` | 同上,无 `>` | ✅ |
| `**合计 = 加(1 2)**` | 「加(1, 2)」,**像数学/函数调用** | 原型通过 |
| `**合计 = 加(a=1 b=2)**` | 「加,a=1、b=2」,自解释 | 原型通过 |
| `**[加](1 2)**` | 像链接,但与取元同形 | ❌ 不建议 |
我的判断:**`f(args)` 是这几种里最符合人读习惯的**,理由有三:
1. **与数学记号同构**:`税率(2)`、`sin(x)` 是跨语言、跨学科的通用写法,不需要学。
2. **参数边界显式**:括号天然划定起止,解决了 `> f a b` 里「参数到哪结束」的模糊
(这也是 D8「函数名含空格」难题的天然解药)。
3. **不占用 Markdown 的链接语义**:渲染出来是普通文本 `f(1)`,
不会像 `[f](1)` 那样在预览里变成超链接。
---
## 5. 要走完这条路,需要做什么(评估工作量)
原型只验证了「方向可行」,要合入还缺这些:
| # | 事项 | 位置 | 风险 |
|---|------|------|------|
| 1 | `)` 作为参数终止符 | `parse_call_args` / `split_first_token` / `find_next_arg_boundary` | **中高**:所有调用共享 |
| 2 | 逗号分隔 `f(1, 2)` | 同上 | 中:逗号在文本参数里合法(`"a,b"` 已加引号则无碍) |
| 3 | 嵌套 `f(g(1) 2)` | `parse_call_args` 递归 | 中:需要括号深度跟踪 |
| 4 | 方法 `obj.m(1)` / 库 `lib.fn(1)` | `try_paren_call` 已有基础(库路径实测通过) | 低 |
| 5 | 位置/具名混用规则 | 复用 [call-arguments.md](call-arguments.md) §3 | 低 |
| 6 | 空参 `f()` | 需定义语义(零参调用) | 低 |
| 7 | EKC 指纹 | `collect_calls` 已读 `c.callee`,`CallExpr` 不变 → 自动兼容 | 无 |
| 8 | `view` 渲染 | `[callee]` 已有 `bracket_marked` 标记,需决定是否回显括号形式 | 低 |
| 9 | `marqdo check` | 需新增「`名字(` 但不是函数」的诊断 | 低 |
**注意第 7 条**:因为 `f(args)` 最终仍产出 `CallExpr { callee, args }`,
EKC 指纹、契约、字节码 `Op::Call(fid, argc)` **全部自动兼容**——
这正是它与「一等函数」方案([functions-as-values-evaluation.md](functions-as-values-evaluation.md) §5 路径 A)的本质区别:
**它只是换了一种写法,没有改变调用模型。**
---
## 6. 建议
### 6.1 推荐路线
1. **不做 `[f](args)`**:与取元同形,且已证明按名消歧会打断 2 个真实文件;
而「多参能用、单参不能用」的规则不可教。
2. **做 `f(args)`**:空闲语法、零回归、人读性好、不动调用模型。
3. 先落**具名**形态 `f(k=v)`(最无争议、自解释),再补位置 `f(1 2)`,最后考虑逗号与嵌套。
### 6.2 若你想保留方括号的「链接感」
有一个不碰取元的位置:**语句位置**。
```markdown
> [加](1 2) # 今天报 unknown function;语句位置的 [k](c) 无实际用途
```
`[k](c)` 作为**独立语句**今天只会算出值然后丢弃。全仓库扫描(851 文件):
以 `[` 起行且形如 `[k](c)` 的独立行只有 **2 处**,且都是样式示例文件里的
普通 Markdown 链接文本(`[海上花开](https://…)`),并非取元代码。
所以在**语句调用**里允许 `[f](args)` 几乎无成本,表达式里则不允许。
代价是「同一写法在两种位置含义不同」,可教性差;我倾向不做。
---
## 7. 待你决策
1. **是否采纳 `f(args)`**(不带方括号)作为新调用写法?
2. 若采纳,**先做哪一档**:
- A 只做具名 `f(k=v)`(最小、最稳)
- B 具名 + 位置 `f(1 2)`(需改分词器,价值最大)
- C 再加逗号与嵌套(一次做全)
3. **`[f](args)` 是否彻底放弃**(我建议放弃,理由 §2.2);
还是只允许在语句位置(§6.2)?
4. 是否需要我按 B 档做一次完整实现(含分词器改造 + 金样例 + 变更文档),
做完再走 554 回归?
原型代码已全部回退,工作区干净。等你定档我再动手。
+208
View File
@@ -0,0 +1,208 @@
# 设计:解析器诊断缺陷修复(D8 / D9)
| | |
|---|---|
| 状态 | **Accepted** |
| 日期 | 2026-10-22 |
| 来源 | [qdagent-refactor-defects-2026-10.md](../research/qdagent-refactor-defects-2026-10.md) D8 / D9 |
| 影响面 | **核心解析**(`src/lex/mod.rs` 行分类 + `src/parse/expr.rs` 函数调用) |
| 关联 | [markdown-mapping-v0.3.md](markdown-mapping-v0.3.md) · [code-vs-comment.md](code-vs-comment.md) |
---
## 0. 为什么这两条要先做调研
D8 与 D9 都落在**行分类**这一层:它决定一行是「叙述」还是「代码」。
改错的代价是**整类文档解析结果变化**,而不是某个函数行为变化。
所以本文先量化影响面、列出候选方案并逐条否决,再动手。
一句话结论:
- **D9** 的根因是分类层把「引号未闭合的粗体行」降级为叙述,
导致解析层精心准备的 `unterminated " string` 报错**永远走不到**。
修法是在分类层补一条「粗体起始但闭合搜索失败」的判定,让它进入解析层报错。
语料实测 620 个文件 0 处受影响,风险可控。
- **D8** 的根因是函数名解析按空格切词,与定义侧不对称。
修法是在**定义期**拒绝含空格的函数名(fail fast),
而不是在调用期做贪婪匹配(那会改变所有多词行的语义)。
---
## 1. D9 — 未闭合引号静默吞行
### 1.1 现状链路
```
源码行 "**s = \"abc"
↓ classify_source → classify_line
↓ 首字符 '*' → is_marqdo_star_line?
trimmed.starts_with("**") → matching_bold_close(trimmed)
→ matching_bold_close_opts(require_eol=true)
扫描时遇 '"' → in_str = true
之后没有任何 '"' 关闭它 → 后续 '*' 全部被当作字符串内容跳过
返回 None(找不到收尾 **)
→ is_marqdo_star_line = false
↓ classify_line 落到 `Some('*') if !is_marqdo_star_line` → LineKind::Comment
↓ 该行成为**叙述**,parser 根本看不到它
↓ parse_quoted_string 里 `bail!("unterminated {quote} string")` 不可达
```
**结论**:这不是解析器的 bug,是**分类器的静默降级**。
解析层已经把错误信息写好了,却没有人把这一行送到它面前。
### 1.2 影响(为什么算高严重度)
| 场景 | 后果 |
|------|------|
| 手写漏一个引号 | 该行消失;变量未定义 → 在别处报 `undefined variable`,方向被引偏 |
| LLM 生成文档 | 少一段内容,但 `exit 0`、`marqdo check` 通过,**文档看起来完整却缺节** |
| CI/门禁 | 门禁试跑通过 → 错误文档被沉淀入库 |
对「文档即程序」而言,这属于最危险的一类:**静默产出错误结果**。
### 1.3 候选方案与评判
#### 方案 A:分类层补判定(采纳)
在 `is_marqdo_star_line` 中,当 `trimmed.starts_with("**")` 且
`matching_bold_close` 返回 `None` 时,再判断「这一行是否**像**粗体代码」:
- 行内含有 `=`(赋值)或 `>` 前导(调用)等强代码信号
- 且引号计数为奇数
满足则**仍判为 Code**,让解析层去报 `unterminated " string`。
**优点**
- 改动局限在分类层,不动解析语义
- 复用解析层已有的、措辞准确的报错
- 对「正常叙述中含 `**` 强调」零影响(那些行引号是配对的)
**风险**:叙述里恰好出现 `**…"…` 这种畸形组合会被判成代码 → 报错。
但实测语料 0 例,且这种组合本身就是写法错误,报错是**期望行为**。
#### 方案 B:解析层预扫描(否决)
在 `parse_classified` 前加一遍全文引号配对检查。
**否决理由**:引号可以合法地出现在叙述、围栏代码块、行内代码里。
全文扫描无法区分上下文,会制造大量假阳性(例如叙述里写「他说 "你好」)。
逐行判断需要的是**分类**信息,而这正是方案 A 在做的事。
#### 方案 C:放宽 `matching_bold_close`,引号未闭合时也认 `**` 收尾(否决)
**否决理由**:会改变「粗体闭合」的语义。`**s = "a ** b"` 这类行
会提前在中间 `**` 处闭合,把字符串拆断,产生更难理解的错误。
这是把静默错误换成**更混乱的错误**,不是改进。
### 1.4 影响面实测
对仓库内全部 `.mq.md`(`target/` 除外)做静态扫描:
| 指标 | 数值 |
|------|------|
| `.mq.md` 文件总数 | 845 |
| 含 `**` 起始代码行的文件 | 620 |
| **引号计数为奇数的代码行** | **0** |
扫描时正确跳过了 `\` 转义(`\"` 不算引号开合)。
结论:修复不会改变任何现有文件的解析结果。
### 1.5 验收
| 用例 | 期望 |
|------|------|
| `**s = "abc`(未闭合) | 报 `unterminated " string`,退出码非 0 |
| `**s = "abc"`(闭合) | 正常运行 |
| 跨行 `**s = "a` + `b"**` | 报错(不跨行拼接,符合现状) |
| 叙述 `他说 "你好"` | 仍是叙述,不受影响 |
| 全量 `cargo test` | 233 全绿 |
| 全仓库重跑 `marqdo check` | 无新增错误 |
---
## 2. D8 — 函数名含空格:定义成功、调用必崩
> **⚠️ 本节方案已作废。** 原主张「定义期拒绝空格」违背了「完全兼容 Markdown」:
> `## 用户 登录流程` 是合法标题,不该为了可调用而改写。
> 现行评估见 [spaced-function-names-d8.md](spaced-function-names-d8.md)(Proposed · 待审阅)。
> 本文其余部分(D9)仍然有效。
### 2.1 现状链路
```
定义侧:## 加一 号 → 标题整体作为函数名 "加一 号"(允许空格)
调用侧:> 加一 号 n=1
↓ 按空白切词
token[0] = "加一" → 当作函数名
token[1..] = ["号", "n=1"]
↓ "号" 无 `=` → 按位置参数/变量插值处理
↓ 变量 "号" 不存在 → undefined variable `号`
```
两侧不对称:定义时把整串当名字,调用时只取第一个词。
### 2.2 候选方案与评判
#### 方案 A:定义期拒绝空格(**已否决**)
解析 `## 函数名` 时,若函数名含空白则报错:
```
error: 文件:行: function name may not contain spaces: `加一 号`
(write `加一_号`, or quote the call as `> "加一 号"`)
```
**优点**
- fail fast:错误在定义处暴露,与调用处报 `undefined variable` 相比指向明确
- 不改变任何合法程序的语义
- 与「标识符不含空格」的通行约定一致
**风险**:可能已有文件用了空格函数名且**只定义不调用**(今天能跑)。
需先扫描语料确认。
#### 方案 B:调用侧贪婪匹配已知函数名(否决)
按「已知函数名的最长前缀」匹配。
**否决理由**:
1. 需要把「所有已定义函数名」带进表达式解析上下文,跨越模块边界后不可判定
2. `> print text=hello world` 里 `hello world` 会被尝试拼成函数名,语义歧义
3. 改变所有多词行的解析路径,属于核心语义变更,收益远小于风险
#### 方案 C:只警告不报错(否决)
**否决理由**:D8 的危害正是「check 通过、运行崩」。继续给警告等于维持现状。
### 2.3 影响面实测
统计仓库内**定义侧含空格**的 `##`/`###` 标题(仅可调用的层级):
| 指标 | 数值 |
|------|------|
| 含空格的二级及以下标题 | 4 |
| 其中位于源码(非运行时目录)的 | **0** |
| 分布 | 全部在 `.marqdo/agent/contexts/*.mq.md` 运行时生成物,且是叙述性标题("Existing Capabilities"),从未被调用 |
结论:源码中不存在含空格的函数名,加定义期校验不会破坏任何现有模块。
运行时生成的 context 文件不受影响——它们不被 import。
### 2.4 验收
| 用例 | 期望 |
|------|------|
| `## 加一 号` | 报 `function name may not contain spaces` |
| `## 加一_号` + 调用 | 正常 |
| `## 断言干净`(中文连写) | 正常 |
| 方法 `### 名字 带空格` | 同样拒绝 |
| 全量测试 | 233 全绿 |
---
## 3. 实施顺序
1. D9(分类层,影响面已量化)→ 测试 → 文档
2. D8(定义期校验)→ 测试 → 文档
3. 两条都做完后跑全仓库回归(`cargo test` + 抽样 `marqdo run`)
每一步独立提交,便于回滚。
@@ -0,0 +1,435 @@
# qdagent 知识工作台所需的多模型运行与 View 嵌入支持
日期:2026-10-25。状态:Partial / in progress(M00–M06 合同门禁 + F02 agent.step/resume 假模型 e2e + USTC live selection smoke + DocumentView 浏览器只读核对已落地;F 矩阵未全绿,不得整文宣称 Verified;原生非兼容适配器仍 unavailable)。
源码基线:Marqdo `dc853fb`(2.1.2),qdagent `643dd31`,已同步远端。应用侧配套:[qdagent 多提供商与知识工作台](../../../qdagent/doc/design/multi-provider-and-knowledge-workbench-2026-10-25.md)。跨仓相对链接以兄弟仓库工作区布局为准。
沿用 [文档原生开发指导](document-native-development-guide.md)、[可执行知识规范](../next/Marqdo_Executable_Knowledge_Development.md) 与 [View 阅读体验设计](view-knowledge-reading-experience-2026-10-24.md)。本规格补充嵌入、调用身份和运行观测,不另造语言或第二套知识真相。
## 1. 框架目标与责任边界
让任何宿主应用可以按请求构造模型、追踪所有真实模型调用、以只读 View 展示知识文档,并从引用定位到版本一致的知识与来源。qdagent 的设置页、模型目录持久化、账单展示、会话导航、工作区授权和画像管理由应用实现。
| 能力 | Marqdo 拥有 | qdagent 拥有 |
|---|---|---|
| 多提供商 | 协议适配、模型 handle、能力协商、调用参数、归一化错误 | 提供商账户/端点/模型 CRUD、默认选择、凭证管理 |
| 模型路由 | Runtime 执行显式选择和允许的辅助模型策略 | 用户选择、工作区模型允许列表、路由授权 |
| 用量 | 每次请求/重试的身份、usage 来源与完整性、子任务传播 | 持久化账本、价格版本、费用估算、筛选/导出/预算策略 |
| 实时运行 | 逐事件输出、取消传播、背压、终态 | HTTP 会话鉴权、轮次映射、持久化事件重放、断线 UX |
| View | 文档语义、正文/目录/步骤、纯读取、稳定定位、可嵌入输出 | 容器/主题/深链/阅读历史/产品操作 |
| 知识引用 | 解析/歧义/版本/来源定位、验证多维事实 | 消息引用标识、授权、历史资料保存与入口 |
| 工作区 | 按显式 project 编译/查询,缓存及输出隔离 | 工作区 registry、root 解析、用户权限、文件管理 |
| 画像与笔记 | 通用文档渲染、来源关联、验证/编译原语 | 内容策略、提案/确认、生命周期、展示和上下文选择 |
不在语言核心添加 provider/workspace/profile 关键字;沿用 `.mq.md` 函数、结构化参数、扩展插件和 MLSP。不得让“可读”取决于用户手填 hash、node id、source span 等机器字段。
## 2. 2.1.2 已完成的基础与剩余缺口
### 2.1 当前可复用基础
| 源码 | 已有内容 | 本规格的增量 |
|---|---|---|
| [ext/ai/llm](../../ext/ai/llm.mq.md) | `create(model,base_url,api_key,backend,name)`、命名 handle、ask/stream | 无需重做基础 handle;增加隔离策略、协议能力、完整消息与调用身份 |
| [LLM plugin](../../plugins/llm/src/lib.rs) | 兼容 chat completions HTTP、SSE 文本读取、非流 usage 三项 | SSE usage/异常终态/每次调用观测、可取消持续输出 |
| [Agent](../../ext/ai/agent.mq.md) | Agent 唯一 loop、router_model、EFI、绑定/发布门闩 | 主/路由/修复/生成工作簿的模型及计量上下文传播 |
| [语义 IR](../../src/sema/ir.rs) | Artifact、KnowledgeStep、KnowledgeRef、SourceLocation、BoundCall | View 面向阅读的完整投影及 ID/版本映射 |
| [MLSP](../../src/mlsp.rs) | `artifact.inspect`、`link.resolve`、verify/bind/execute、document.extract | 只读 document/引用解析及 capabilities 版本握手 |
| [KnowledgePresentation](../../src/view/knowledge_present.rs) | schema v1,artifact nodes、依赖、generation/page token | 保留兼容,新增正文/目录/refs/source spans/结构化诊断 |
| [View output](../../src/view/output.rs) | `--no-exec` 在构建前跳过 capture | 将纯读取能力暴露给嵌入客户端,不复用会执行的 live 默认路径 |
| [document extract](../../src/document_extract.rs) | TXT/MD,partial,PDF/DOCX/OCR 显式不支持 | 能力查询及稳定来源定位;不要求本阶段重造 OCR |
| [数据资源](../../ext/data/db.mq.md) | SQLite migrate/exec/事务、唯一/索引声明 | 应用可直接承载 registry/账本/索引;不需另加产品专用数据库框架 |
2.1.2 已把知识辅助块移到正文后并折叠,跳过 module/type 卡片,显示“结构步骤非实际执行时序”。旧 View 截图中的最初顺序问题已有改进;但这不意味着已提供能直接放进 qdagent 右栏的独立阅读 SDK。
### 2.2 直接影响集成的事实
1. `llm.complete_result` 当前仍走 `openai.chat_completions`,Ollama 也是兼容路径;`backend` 名称不是任意原生协议适配器。
2. `plugins/llm::chat_completions` 从 `prompt` 构造一条 user 消息,没有完整消息列表契约;不能靠模型选择 UI 弥补历史丢失。
3. `usage_from` 缺字段填零;Agent `model_turn(stream=True)` 直接 `tokens=0`,最终 `token_cost=tokens`。现有输出无法支撑准确货币或流式用量显示。
4. 原生 LLM SSE parser 返回事件数组;`ext/ai` 有流事件机制,但应用所用 [web invoke](../../plugins/web/internal/httpx/routes_invoke.go) 在 `CallLibPath` 返回后才写 `{sse}`。需要打通实际增量路径,不能只换 Content-Type。
5. Agent 生成子工作簿的模板仍能构造默认 `llm.llm`;只传主 agent handle 不足以证明嵌套调用沿用了用户选定模型。
6. `build_file_view` 默认传 `execute=true`;live GET 路径使用它。嵌入阅读绝不能直接暴露这个入口。
7. Presentation 目前按 artifacts 投影,缺全量 prose/heading/step/ref 的统一阅读树;`render_knowledge_html` 另从 steps/refs 渲染,容易与 JSON 事实发生覆盖差异。
8. `source_digest` 当前由语义 artifact hashes 汇总,`semantic_generation` 是语义散列截短,`page_token` 来自原文件。它们不能直接分别冒充原文 revision、`.marqdo/CURRENT` generation 和跨请求完整版本。
9. `sse_accepts_packet` 对缺 token 的 legacy 包放行;正式嵌入客户端必须采用严格版本匹配,而不是继承这项兼容宽容。
10. `artifact.inspect/link.resolve` 每次走当前 semantic_project;现有入口不保证可以读任意历史 generation。历史引用需要明确的保留与解析合同。
## 3. 共用合同、版本与能力发现
合同名字固定为 `ModelSelectionV1`、`ModelCallUsageV1`、`RuntimeEventV1`、`DocumentViewV1`、`KnowledgeLocatorV1`;它们是这次扩展的 v1,与当前 KnowledgePresentation `schema_version:1` 不混用。新增 read model 不强行给已有 JSON 改含义。
新增 MLSP `capabilities`(拟议):
```json
{
"schema_version": 1,
"runtime_version": "implementation-version",
"features": {
"llm.explicit_selection": 1,
"llm.call_usage": 1,
"runtime.event_stream": 1,
"runtime.cancel": 1,
"view.document": 1,
"view.reference_resolve": 1
},
"adapters": [{"id": "openai-compatible", "available": true}],
"extract_formats": [{"format": "text", "available": true}],
"loaded_plugins": [{"name": "llm", "capabilities": ["call_usage_v1"]}]
}
```
只返回实际探测且加载可用的功能。不能仅从 CLI 版本推断 native plugin 符号存在;字段未知时应用降级或解释不支持。协议允许新增可选字段;删除/改变状态语义必须提升 major contract version。能力查询不调用供应商、不执行项目代码。
MLSP 继续使用现有 `{id,ok,result|error}` envelope;qdagent `/api/app` 转为自己的 `{ok,schema_version,data|error}`,不要要求它们共享同一层 envelope。所有合同提供成功、partial、unknown、unsupported、stale、cancelled、错误 fixtures 与 JSON Schema;应用和框架从相同样本跑消费测试。
## 4. M01:请求级模型身份与适配器
### 4.1 显式选择合同
应用将配置解析成可信 `ModelSelectionV1` 后传入 runtime,核心字段:
```json
{
"schema_version": 1,
"selection_id": "sel-1",
"provider_id": "provider-1",
"model_id": "model-2",
"provider_revision": 3,
"model_revision": 5,
"adapter": "openai-compatible",
"endpoint_ref": "endpoint-local-1",
"credential_ref": "credential-local-1",
"credential_version": 2,
"upstream_model_id": "example-model",
"parameters": {"max_output_tokens": 2048},
"fallback_policy": "disabled"
}
```
endpoint/credential 引用由宿主 resolver 解析为调用局部配置;短期直接向现有 `llm.create` 传参数亦可,但这不是可序列化的 public snapshot。API key 不能出现在 events、debug JSON、生成工作簿、prompt、错误 URI 或持久化模型对象中。
当前显式 args 优先的能力保留;新增 strict selection 模式:字段缺失报错,不回退 process env/frontmatter。无凭证端点通过 `auth_mode:none` 显式表达,避免 falsy key 触发环境 fallback。legacy 命令行未传 selection 时仍可沿用原有 env 行为;本地便利兼容不扩散到应用请求。
每个运行绑定 selection snapshot,后续设置改变不修改它。主模型与 router_model 分开但同属受控 selection 集;manual 模式所有需要 LLM 的步骤固定选择,REUSE 无模型调用仍允许。fallback 必须由宿主明确授予、列出允许目标,不能因额度/网络错误静默转到另一个供应商。
### 4.2 子任务和工作簿传播
统一 `RunContextV1 = run_id,parent_run_id?,turn_id?,workspace_scope,selection_context,usage_sink,event_sink,cancellation_token`。进入 ask/step/plan、repair、summary、learn、子工作簿时显式继承;新 run/call id 关联父节点。
生成工作簿只包含不可重放滥用的运行上下文引用,不写密钥;执行时宿主注入/解析。独立导出工作簿在缺凭证/选择时清晰要求配置,不偷偷取默认模型。在任何 child/spawn/resume 路径遗漏 selection 都应由 strict 模式拒绝并给出定位诊断。
同时审查环境变量不只是凭证:project root、temp request、输出目录、event sink 也必须请求局部,不能在并发运行中依靠进程可变状态串联。
### 4.3 适配器与消息
适配器最小职责:验证 selection、报告能力、序列化请求、解析增量结果、usage 归一化、取消传输、错误归一化。可选 discovery/probe;无模型列表 API 仍允许手工配置。
V1 消息包含 role 和 content parts,parts 最低 text,附件通过受控引用;tool call/result 要保持配对及 role。不支持的 part/parameter 返回 `llm.unsupported_input/parameter`,不能悄悄转成空字符串。适配器决定协议格式,Agent 决定行为;qdagent 不拥有供应商协议代码。
阶段一验证两个不同兼容端点,分别至少两个模型,以及无密钥本地兼容服务。阶段二增加原生非兼容协议:每个适配器需具名能力、流式/非流式/错误/取消/usage fixtures 和独立接入说明后才能在 capabilities 中置 available。不能把所有厂商默认走兼容接口后统称全支持。
统一参数采用 `max_output_tokens,temperature?,stop?,reasoning?` 等语义键,能力不支持时明确拒绝;不随意透传客户端未知参数。实际 upstream model 若与请求 id 不同,在 result 中保留 requested/resolved 两者。供应商版本与价格随时变化,本文仅锁定内部合同;实施原生适配器时另附当时官方协议核验记录。
## 5. M02:用量、事件流与取消
### 5.1 ModelCallUsageV1
```json
{
"schema_version": 1,
"call_id": "call-1",
"attempt_id": "attempt-1",
"parent_call_id": null,
"run_id": "run-1",
"turn_id": "turn-1",
"workspace_scope": "ws-1",
"purpose": "answer",
"selection_id": "sel-1",
"provider_id": "provider-1",
"model_id": "model-2",
"requested_model": "example-model",
"resolved_model": "example-model",
"status": "succeeded",
"usage_state": "final",
"measurement_source": "provider",
"input_tokens": 1200,
"output_tokens": 300,
"total_tokens": 1500,
"cached_input_tokens": 800,
"reasoning_output_tokens": null,
"revision": 2,
"provider_request_id": "opaque-provider-id",
"started_at": "2026-10-25T01:00:00Z",
"finished_at": "2026-10-25T01:00:03Z"
}
```
字段要求:tokens 非负整数或 null;`usage_state = pending|partial|final|unknown`;`measurement_source = provider|estimated|none`。估算可作为单独 estimate 字段返回,不能覆盖实测字段。供应商没有报告时用 null/unknown,传输失败不能自动解释成零消耗。
`status = started|succeeded|failed|cancelled|interrupted`,status 和 usage_state 独立。每个真实发出的 HTTP attempt 一个唯一 id;预检拒绝只产生 call-rejected 事件,不伪造已发送请求。框架重试必须可观测:所有 attempts 包括失败/有部分输出的 attempt;重复 delivery 的 usage revision 不算新请求。
累计 SSE usage 在同 attempt 内按 revision 发布完整快照,不让上层猜是 delta 还是 total。provider 总量与 input/output 不一致时保留原始读数及 `usage.inconsistent` 诊断,不自行强制改账;细分字段要标 inclusion 关系以避免缓存、reasoning 与总量重复相加。只保留脱敏的必要 provider usage 扩展字段,不把完整原始响应当 public usage。
纯知识复用用 run summary 中 `llm_calls=0`、`measurement_source=none` 表示,而不是伪造一条耗费为零的模型请求。框架输出 `call_count,known_tokens,unknown_call_count`,宿主据此显示覆盖程度。
### 5.2 事件流合同
```text
run.started
→ model.resolved
→ model.call.started
→ message.delta / tool.progress / usage.updated(零到多次)
→ model.call.finished(每个 attempt 各一条)
→ document.produced / citation.produced(仅有真实对象时)
→ run.completed | run.failed | run.cancelled | run.interrupted
```
`RuntimeEventV1` 公共字段:`schema_version,event_id,seq,run_id,parent_run_id?,turn_id?,workspace_scope,timestamp,type,payload`。seq 每个 run 单调;不同子 run 可以并发,宿主按所属 turn 另分配产品流序号。runtime terminal 事件仅一次;后续补全计量用有 revision 的 `usage.updated`,不能改变内容终态。
事件 sink 支持有界队列和背压;慢客户端不能无限堆积 token。丢弃可合并 progress 时记录 gap;内容与终态事件不可无声丢失。连接终止不会自动重跑;持久化/重放由应用,但框架需在实时回调后仍提供可核对的 final result/call summaries。
同一真实调用所有数据使用同一 run/call identity,不能流与最终结果各生成一套 id。工具参数/结果按 policy 脱敏,不把 secret、完整私有文件、模型内部推理链写入默认进度事件。
### 5.3 打通传输而不重造 Agent
需要同时打通 LLM provider reader → Agent event sink → host callback → web streaming handler → 浏览器。现有 `sys.stream_publish` 可以作为底座,但要验证它是否绑定正确请求且在 `CallLibPath` 返回前可写出;不能用进程全局事件广播混流。
可实施路径:新增 web 流式 invoke/job primitive,由框架注册 run handle 和 event sink;调用返回 handle 后宿主可订阅/取消。采用插件 ABI 增量接口及能力检测,旧 ABI 未支持时拒绝新 streaming 模式,保留旧完整返回。qdagent 只挂产品鉴权、event id 持久化和 HTTP 端点,不添加另一个推理循环。
SSE parser 必须处理任意 TCP 分块、UTF-8 跨块、CRLF、多行 data、注释 heartbeat、尾帧、usage-only 帧、[DONE]、连接在结束前关闭。未知可选事件可忽略且记诊断;已知事件无效、异常截断不能静默当成功完成。公共 framing 不包含供应商私有认证信息。
### 5.4 取消与重试
取消 token 传到 HTTP reader、循环、工具边界、子任务。取消后不得启动新模型调用/新工具;正在进行的不可抢占操作返回 `cancelling` 和是否仍运行,结束后才报告 cancelled。明确“停止生成”不能撤销已经完成的外部写入。
调用超时、连接错误、鉴权失败、限流、协议错误分开;错误字段包含 `code,retryable,retry_after_ms?,call_id,attempt_id,usage_state`。不要将原始包含密钥/完整 prompt 的错误直接传到 UI。限流/短暂网络错误按有界策略重试;已产生输出的重试不能接在同一条文字后假装连续,也不能把未知结果的外部工具操作自动重做。
费用价格由应用管理。框架保留 legacy `tokens/token_cost` 并标注 deprecated/单位为 token,新功能只消费 ModelCallUsageV1,避免破坏旧脚本的同时停止误用。
## 6. M03:无执行的嵌入式 View
### 6.1 新入口与纯度约束
新增内部公共服务 `analyze_document → project_read_model → render_fragment`;MLSP 暴露 `view.document`,可选 CLI `view document --json --no-exec` 与它共享实现。不要让新入口先进入 `build_file_view` 再隐藏按钮/清空输出。
读取允许:授权范围内原文/已编译快照/已有验证记录。读取禁止:运行模块入口、加载文档声明插件、执行外国代码、LLM、自动抓取 URL、写回、重新验证执行测试、隐式发布/重编译写盘。静态分析/内存投影允许;缺完整依赖时明确 partial。任何需要执行的行为必须另走显式 execute/verify 产品流程。
当前 `compile_project` 声明不加载插件/不求值/不抓取来源,可复用;缓存写入若需要,作为单独的宿主管理路径,不能把“读文档”隐含写项目目录。
### 6.2 DocumentViewV1 结构
请求由宿主传入受控 project 和文档定位,宿主必须已授权;框架仍做路径边界校验。
```json
{
"method": "view.document",
"params": {
"project": "/authorized/project",
"document": "knowledge/example.mq.md",
"revision": "sha256:requested-source",
"generation": "generation-id-or-null",
"mode": "read",
"node_id": "optional-node",
"include": ["fragment", "outline", "nodes", "refs", "diagnostics"]
}
}
```
```json
{
"schema": "DocumentViewV1",
"schema_version": 1,
"document": {
"id": "project-relative-document-id",
"title": "知识标题",
"source_revision": "sha256:raw-bytes-digest",
"semantic_digest": "sha256:semantic-facts",
"generation_id": null,
"presentation_token": "opaque-token"
},
"execution": {"state": "not_run", "run_id": null},
"render": {"format": "sanitized_html", "fragment": "<article class=\"mq-document\">…</article>", "renderer_version": "1"},
"outline": [],
"nodes": [],
"refs": [],
"diagnostics": [],
"completeness": "complete",
"capabilities": {"read_only": true, "has_semantics": true}
}
```
`generation_id` 来自实际编译投影;即时分析但未编译发布时为 null,同时给 semantic_digest。`source_revision` 是原始文件字节摘要,不能复用当前基于 artifacts 的 `source_digest`;`presentation_token` 覆盖 source revision、generation/semantic digest、依赖版本、renderer/schema、读取策略与请求范围。应用缓存还必须含用户授权范围。
`completeness = complete|partial`;语法损坏时允许返回原文与结构化诊断,但不能展示猜测出来的正常知识图。失败用 error envelope,不能空字符串伪装“文档无内容”。大文档 response 支持 section cursor 和 truncated 标识,限制要可配置并在响应中标明。
### 6.3 统一正文、目录、节点与引用
节点包含 `id,parent_id,kind,label,order,source_span,artifact_id?,ref_ids[],children[]`。kind 包括 heading/prose/table/code/observe/derive/call/iterate/narrate/navigation;正文树来自 parser/classifier/sema 的共同投影,不能只枚举 functions 后把每个步骤标 call。
outline 描述读者文档层级,不简单把函数和对象全铺成同一级。HTML 中节点带 `data-mq-node`,引用带 `data-mq-ref`;实现 payload 按需展开,说明作为正文。动态调用/无法解析引用保持原文并解释原因,不虚构执行边。
首批 renderer 共享 `src/view/document.rs` 的文档表面,standalone/full page 和嵌入模式调用同一 read model;只改变容器和导航外观,不产生第二种语义解释。替换当前 `KnowledgePresentation` 与 `render_knowledge_html` 双路径重复组装。
稳定 ID 的保证范围要写明:
- 同一 revision 再次读取,node/ref id 必须相同。
- 仅前插空行/叙述时,已有命名符号保持 symbol id;步骤 id 由结构身份映射,不能只靠行号。
- 同一行多个节点需要 column/offset/span 区分,不能都映射成 `stmt-N`。
- 匿名步骤重排/重复同名内容可能无法唯一映射;返回 unmapped/ambiguous,不能声称任意编辑下永恒稳定。
- source span 明确 1-based line/column 和 UTF-8 byte offset;JavaScript UTF-16 偏移不直接当 Rust 字节偏移。
旧 `#stmt-{line}` 可保留为当前版本兼容锚点,但不得作为跨版本唯一身份。
### 6.4 嵌入渲染、主题与访问性
fragment 不包含 html/body、应用导航、运行按钮、内联可执行 script、全局 CSS;CSS 以 `.mq-document` namespace 限定。主题暴露 `--mq-bg/surface/text/muted/border/accent/font-body/font-code`,宿主映射自己的设计 tokens;不把独立 View 的全局 `*`/body 样式注入 qdagent。
首批推荐 fragment + 结构化引用 + 宿主事件代理;无需为 iframe 和 React 各重做 parser。可选 iframe embedded shell 必须只读、无重复导航,宿主/子页通信校验 origin/source/nonce/schema,仅允许 open-reference/selection/ready 等已定义消息,不能从内容发任意运行指令。
所有文本/属性转义,允许的 Markdown HTML 白名单净化;链接 scheme 限制;外部资源不默认跨网加载;代码/公式不得执行。静态导出、独立页面、嵌入三者都测试恶意文本/闭合标签/危险 URL。不要把 KnowledgePresentation 内 JSON 的转义当作所有正文 XSS 防护。
标题/列表/表格用语义 HTML;说明链接有可访问名称,焦点可见,视觉排序和键盘顺序一致。折叠只隐藏技术细节,不隐藏理解结论所需的正文。320–720px 容器宽、暗色、200% 缩放和 print 都要能读,不出现遮住正文的关系连线。无 JS 时仍能读正文和普通链接。
## 7. M04:知识、来源与历史引用定位
### 7.1 KnowledgeLocatorV1
统一 locator:`project_id,document_id,source_revision,generation_id?,artifact_id?,node_id?,source_ref_id?,span?,relation`。relation 区分 cites/supports/derived_from/executes。普通链接导航、NarrativeRef 和 BoundCall 都能定位,但语义不同;点击说明永不成为 BoundCall 的执行。
新增 `view.reference_resolve`:接受 locator 或当前文档 ref_id,返回 `resolution = resolved|stale|unresolved|ambiguous|version_unavailable|unsupported`、目标 locator、候选(若有)、定位精度、诊断、读者标签。框架内部路径不作为浏览器 href,应用根据授权映射为 document/source route。
扩展 `artifact.inspect` 的版本参数,旧无版本调用仍查当前;新调用带 expected source/generation mismatch 时不能自动降到当前。来源读取接口可由宿主取实际文件,再调用框架 locator 映射;框架不自动 fetch 外部网页。`mq://` 必须按框架规则解析,不能交给浏览器或把 URI 直接当文件路径。
### 7.2 历史版本与保留责任
生成 artifact/generation 元数据不等于保存了原文历史。框架须输出可保存的 snapshot manifest:原文 revision、依赖 revision、source refs、artifact hashes、renderer/schema version;应用决定哪些源版本随引用保留及保留周期。已有 Git 或内容寻址存储可提供 snapshot resolver;不强制应用部署 Git。
source revision 定位到存储快照后,框架基于该快照解析;缺失任何必要版本时返回 version_unavailable/partial,不读取最新文件填充旧快照。如果只留 artifact 元数据、原始资料已删除,仍可展示历史元数据但明确“原文不可读取”。
知识改名、移动或 source anchor 改变可返回候选映射,只有唯一可靠匹配才自动导航;否则用户选择最新版/候选。保持旧引用与新引用两个对象,防止历史回答证据在后台悄悄改变。
### 7.3 验证和运行事实
节点详情至少携带 purpose/description、signature、applicability、provenance、effects、dependencies,以及 parse/resolve/contract/tests/evidence/execution 各自状态与记录来源。sourced 只能说“已关联来源”;static verify 成功不表示执行成功或适用业务正确。
真实执行证据独立结构 `run_id,artifact_digest,closure_digest,source_revision,generation_id,inputs_digest,executed_at,result_state,evidence_ref`,展示时匹配版本。旧运行结果不涂成当前文档的绿色通过。知识复用必须存在实际 bind/execute trace,不能凭 find 命中显示“已执行”。
View 不运行验证测试以填满状态。若用户点“验证”,应用走已有 verify/policy 门禁并记录新 evidence,之后读取才刷新详情。
### 7.4 错误与授权协作
| 内部结果 | 应用建议呈现 | 不能做 |
|---|---|---|
| unresolved | 无法定位该知识,可读原引用 | 跳转到第一个同名 artifact |
| ambiguous | 显示已授权候选和位置 | 自动选择或暴露不可见候选 |
| stale | 该知识/来源已变化,提供版本选择 | 静默替换旧引用 |
| version_unavailable | 回答所用版本不可用,可查看最新版 | 用最新版伪装历史证据 |
| partial | 部分依赖或来源缺失,说明范围 | 默认绿色通过 |
| permission denied(应用) | 无权访问 | 在错误中泄漏标题、路径、片段 |
用户权限归应用;框架服务在调用边界接受 scoped project/source resolver,不把传来一个 root 视为可遍历整个服务器。所有路径经过 canonicalize/symlink 检查;缓存的语义事实可共享,带原文的响应必须按权限复核,不能只靠 artifact id 缓存授权。
## 8. M05:工作区、笔记与导入所需的通用底座
不为 qdagent 画像加语言特殊节点。通用能力应支持普通文档元信息读取、来源范围、内容修订、diff/patch 的 expected digest、提取格式 capability。
document.extract 继续使用 DocumentSource→ExtractedDocument,报告 format/status/segments/source locator/diagnostics。TXT/MD 可支持;PDF/DOCX/OCR 没有适配器时明确 unsupported/failed,不能将空文本当成功。partial 保留已提取片段及原文范围、遗漏原因;发布政策由应用决定。
同一资料可产生多个知识单元,provenance 必须到具体片段,不能所有函数只指向文件根。原始资料 digest 改动的失效由现有 provenance/closure 保证;应用用户画像也可用普通来源引用,但不自动进入公共知识发布。
ProjectRoot/CompileOptions 显式传递,工作区 A/B 的 source id、输出 generation、缓存、临时目录必须隔离。避免每读一个节点就全项目编译:引入按 project snapshot 复用的分析服务,针对来源/依赖变化失效;并发同 snapshot 请求合并,不能分别写同一个 CURRENT。
上传 multipart/大小限制已有 web 底座,框架只提供安全提取和可消费结果;浏览器上传、作业生命周期、发布确认、权限和历史保存仍在 qdagent。多文件任务桥接采用结构化参数,禁止拼接用户文件名进 shell/JSON 或共用固定请求临时文件。
## 9. 实现落点与兼容策略
| 模块 | 改动方向 | 兼容要求 |
|---|---|---|
| `plugins/llm/src/lib.rs` | adapter boundary、消息数组、usage、event sink、取消 | 保留已有符号;新能力有 probe 和合同版本 |
| `ext/ai/llm.mq.md` 与 `ext/ai/llm/*` | strict selection、结构化 result、public snapshot | 无 selection 的旧调用仍可运行;不得回显密钥 |
| `ext/ai/agent.mq.md` | run context、子工作簿传播、逐调用观测 | 不复制 Agent loop,EFI/verify/publish_gate 不被绕过 |
| `plugins/agent/src/*` | 子任务/恢复上下文、cancel、event identity | resume 不重发已结算请求;不可恢复说明 interrupted |
| `src/host/*`、插件 SDK、web invoke | 请求局部 event/cancel 桥接 | ABI 旧宿主不伪支持;并发请求不混流 |
| `src/view/knowledge_present.rs` | DocumentView read model/兼容 adapter | 旧 presentation v1 不被新字段语义污染 |
| `src/view/document.rs,render.rs,html.rs,mod.rs,output.rs` | 共享纯读取、fragment、scope CSS、定位 | live/debug 与 read 明确分离;旧 no-exec 门禁保留 |
| `src/mlsp.rs` | capabilities、view/document/reference、版本 inspect | 使用现有 envelope;未知 feature 可探测 |
| `src/sema/ir.rs,provenance.rs` | span、snapshot/locator、依赖与来源失效 | 不改变核心语法,不把读请求变为执行 |
| `src/document_extract.rs` | capability 和片段定位完整性 | 保留不支持格式的显式失败 |
测试分层对应 plugin HTTP fixtures、Agent 假模型、MLSP read contracts、web 持续流集成、独立/嵌入 DOM 和浏览器交互。应用共享样本文件必须注明 schema 版本;两仓 PR 在各自文档索引相互链接对应实现说明。
迁移顺序为新增合同/接口 → 旧输出 adapter → qdagent 按 capability 接入 → 切默认 → 后续版本再考虑弃用。不要同时移除 legacy 行为且要求应用一次完成全链升级。发布包对 CLI/ext/native 插件做组合测试,缺插件给功能不可用诊断而非 unknown function 直到用户点击才暴露。
## 10. 交付切片与验收门槛
| 切片 | 前置 | 验收输出 | 支撑应用任务 |
|---|---|---|---|
| M00 合同冻结/探测 | 无 | schemas、fixtures、capabilities、版本和插件清单 | Q00、所有升级探测 |
| M01 多模型隔离 | M00 | 兼容适配器、strict handles、history、子任务选择一致 | Q01/Q02 |
| M02 调用观测与流 | M01 | 每 attempt usage、真流式、取消、错误/重放一致 | Q03/Q06 |
| M03 只读嵌入 View | M00,可与模型线独立 | DocumentViewV1、fragment、目录/节点、无执行证明 | Q04 |
| M04 引用与快照 | M03 | 历史 locator、来源详情、版本失效/歧义 | Q05 |
| M05 文档工作区底座 | M03/M04 + 已有 extract | 范围隔离、提取定位、并发与缓存 | Q07/Q08 |
| M06 集成与性能 | 全部所选切片 | 旧门禁 + 新 contracts + 浏览器与负载报告 | Q09 |
M01 支持多个兼容提供商不等待原生协议全做完;但原生适配器需另列完成状态。M03 不等待计费系统。M04 未完成历史快照前,应用可以显示当前文档,但必须把历史引用标“版本不可用”,不能宣布引用链闭合。
每个切片的 Definition of Done:实际接口可调用、失败合同覆盖、无副作用/隔离测试、文档示例由测试消费、版本能力可探测、qdagent integration fixture 通过。只有可运行的验收证据才可将 proposed 改为 verified。
## 11. 框架测试矩阵
| 编号 | 用例 | 断言 |
|---|---|---|
| F01 | 两端点各两模型、并行 A/B、无密钥本地端点 | 请求 payload/端点/鉴权正确,环境不串扰 |
| F02 | step/plan/router/repair/child/resume | strict selection 和 parent identity 完整,不退回默认模型 |
| F03 | multi-turn、system/tool roles、超限/不支持模态 | 顺序和边界完整,不吞最新 user,不静默降级 |
| F04 | 非流/流式/usage-only/缺 usage/错误后部分 usage | null 与 0 区分,终态和用量独立 |
| F05 | 相同累计 usage 多次、重放、新重试 | 同 attempt revision 覆盖,不重复相加;真重试新增 attempt |
| F06 | 慢供应商、慢消费者、断连、取消、超时 | 完成前有 delta;队列有界;取消不启动后续工具/模型 |
| F07 | 外部工具已写后取消、恢复未知状态 | 不声称撤销,不自动重做可能有副作用的动作 |
| F08 | 带写文件/网络/foreign/插件的文档被阅读 | read API 不加载/运行这些效果,无项目写回 |
| F09 | prose/heading/6 类步骤、同一行多引用、中文 span | HTML/outline/节点/ref 同源,定位唯一准确 |
| F10 | 仅说明变化、依赖变化、旧 SSE 包、无 token | token 正确失效,嵌入 strict 拒绝过期/无身份包 |
| F11 | 来源改删、历史 generation 未留原文、同名歧义 | 明确 stale/unavailable/ambiguous,无猜测替代 |
| F12 | no-js/390px/暗色/长表格/键盘 | 正文可读,可返回,有清晰标题和焦点 |
| F13 | 原始 HTML/危险 URL/闭合 script/越界路径 | 无脚本执行/越权读取/泄漏;不靠应用猜净化 |
| F14 | 两项目同相对路径/并发 100 读取 | scope 缓存隔离,同 snapshot 合并分析 |
| F15 | 编译成功但验证/证据未知、旧执行记录 | 各状态独立;不把 static/sourced 标 verified |
| F16 | CLI/ext/native 版本错配 | capability 早发现不可用,而非运行时静默失败 |
性能目标需实测而非发版文字:固定机器与 release/debug 分开记录,1000 单元分析冷/热、单文档 fragment 体积/时间、并发读取 P95/内存、UI 首屏。应用目标见 Q 文档;如果全量 compile 超时,优先分析重复全库扫描、依赖计算与缓存,不通过删除 fixture 或抬高阈值宣布可用。
## 12. 本次验证结果与已知阻碍
### 12.1 M00–M06 落地证据(2026-10-25 续)
命令(本机):
```bash
cargo test --offline --locked --test workbench_contracts
cargo test --offline --locked -p marqdo_plugin_llm
cargo test --offline --locked --test executable_knowledge f1_agent_eng_bind_gate_mq_offline -- --exact
```
已交付并通过自动化子集(**非** F01–F16 全绿):
| 切片 | 证据 |
|---|---|
| M00 | fixtures + JSON Schema 消费;`capabilities`;`force_unloaded` / `force_*_off`(F16) |
| M01 | strict selection;`RunContextV1` 并行不串扰;llm plugin messages/roles;workbook 禁 `llm.llm`;**F02** `m01_f02_agent_step_selection_and_resume`(mock HTTP + `llm.create` 抗 env poison + resume save/load) |
| M02 | usage null≠0;revision 替换(F05);cancel token(F06/F07);event_sink;web `sse-live` 断连 cancel |
| M03 | `view.document`;CJK outline/nodes;path escape;静态 a11y 子集;F08 无副作用标记;**浏览器** `workbench-docview.html`(`article.mq-document`、0 script、无 `javascript:`) |
| M04 | stale / version_unavailable / **ambiguous**;`SnapshotManifestV1` 输出(retention=application);`artifact.version_mismatch`;embed strict SSE |
| M05 | extract `:B`;analysis_cache begin/finish;**F14 并发 100** 同 snapshot + 跨 project 隔离 |
| M06 | CI 预构建 agent+llm + `workbench_contracts`;Go `drainForward` / cancel-token 桥 |
| Live | `tests/workbench_live.rs`:USTC OpenAI-compatible(`OPENAI_*` env only)`qwen3.8-chat` / `deepseek-flash` selection ask → `pong` + usage;`MARQDO_EXT` 指向仓内 `ext/` 避免 `~/.marqdo/ext` 陈旧遮蔽 |
已知限制(发版前须书面接受或继续补):
- F02 repair/plan **全路径**假模型仍薄于 step+resume;RunContext 三级继承 + skeleton 禁 `llm.llm` + 子任务 env 已有。
- 历史正文由应用按 SnapshotManifest 保留;框架缺快照 → `version_unavailable`(不静默降级)。
- 完整宿主嵌入 F12 / 产品鉴权留给 qdagent;原生适配器 / PDF/OCR 仍 unavailable。
### 12.2 历史基线记录(设计起草时)
起草时 `executable_knowledge` 曾出现 `f1` 缺插件与 `v3_corpus_1000` debug 超时;其后 `ensure_agent_plugin_built` + CI 预构建已修复 f1 路径。1000 单元性能仍按剖面单独记录。
+216
View File
@@ -0,0 +1,216 @@
# 方案评估:函数名含空格的调用(D8)
| | |
|---|---|
| 状态 | **Proposed · 待审阅**(未实施任何代码改动) |
| 日期 | 2026-10-22 |
| 来源 | [qdagent-refactor-defects-2026-10.md](../research/qdagent-refactor-defects-2026-10.md) D8 |
| 前置 | [parser-diagnostics-d8-d9.md](parser-diagnostics-d8-d9.md)(该文方案 A「禁止空格」**已被否决**,见 §0) |
| 影响面 | 核心解析:`src/parse/expr.rs` 调用切词 / `src/lex` 行分类 / 名称解析 |
---
## 0. 为什么原方案被否决
原方案 A 主张「定义期拒绝含空格的函数名」。这是**错的**,理由是我此前忽略的一句话:
> Marqdo 的立身之本就是**完全兼容 Markdown**。
`## 用户 登录` 是一个**完全合法的 Markdown 二级标题**。真实文档里这类标题极多:
```markdown
## 用户 登录流程
## 第三阶段 数据校验
## Appendix A Results
```
如果禁止这些标题当函数名,等于强迫作者为了「能调用」而改写标题措辞——
这恰恰把「代码即文档」降级成「代码迁就文档」。作者写的标题首先应当是**他自己想写的标题**。
**结论:空格必须被支持,问题只在于「怎么把带空格的名字准确传给调用」。**
---
## 1. 事实基础(全部实测,1.5.2)
先固定真实行为,避免方案讨论建立在猜测上。
### 1.1 定义侧
| 输入 | 结果 |
|------|------|
| `## 加一 号` | ✅ 定义成功,函数名**原样**为 `加一 号`(`parse_object_decl` 走 `Ok((raw.to_string(), None))`) |
| `## 用户 登录流程` | ✅ 同上 |
**定义侧完全支持空格**,不需要任何改动。
### 1.2 调用侧
| 输入 | 结果 | 原因 |
|------|------|------|
| `> 加一 号 n=1` | ❌ `undefined variable 号` | `parse_call_tail` 用 `split_whitespace().next()` 只取首词 |
| `> [加一_号] n=1` | ✅ 正常(返回 2) | 方括号标记调用**已存在**且工作 |
| `> [加一 号] n=1` | ❌ `unknown function [加一` | `is_bracket_callee_inner` 第 1248 行**显式拒绝含空白** |
| `` `加一 号` `` 作为表达式 | ❌ `undefined variable 加一 号` | 反引号名走变量解析,找不到函数 |
### 1.3 关键发现
> **方括号标记调用(`[callee]`)已经存在且实现完整**,
> 挡住带空格名字的是 `is_bracket_callee_inner` 里的**两处**校验,
> 而不是一处(首轮评估低估了)。
这是本次评估最重要的发现:**不需要发明新语法**,只需要让既有机制接受空格。
### 1.4 可行性实测(已做,未保留改动)
为回答「放开后运行时到底能不能查到含空格的函数名」,做了受控实验:
临时放开两处校验 → 编译 → 跑用例 → **立即回退**(`src/parse/expr.rs` 已恢复原样)。
| 关卡 | 位置 | 原逻辑 | 放开后 |
|------|------|--------|--------|
| 1 | `is_bracket_callee_inner` | `t.chars().any(is_whitespace)` → 拒绝 | 删除该检查 |
| 2 | 同函数末尾 bare-name 白名单 | `is_alphanumeric() \| '_' \| '.' \| !is_ascii()` | 追加 `\| c == ' '` |
**实验结果**
| 用例 | 结果 |
|------|------|
| `## 加一 号` + `> [加一 号] n=1` | ✅ **返回 `2`**(运行时函数表正确命中含空格名) |
| `## 加一_号` + `> [加一_号] n=1`(对照) | ✅ 仍返回 `2`,既有行为不变 |
| 全量 `cargo test --lib` | ✅ **237 passed, 0 failed** |
**结论**:方案 1 技术上完全成立,且**不破坏既有测试**。
(237 = 基线 233 + 本轮 D9 新增的 4 个分类测试。)
> 注意:实验只证明「可行」,未固化。正式实施需要补 §4 的全部 V1–V9 用例,
> 特别是 V3–V7 的歧义排除,再决定是否合入。
---
## 2. 候选方案
### 方案 1 — 放开方括号内的空格(推荐)
**做法**:把 `is_bracket_callee_inner` 的「含空白即拒绝」改为「允许空白,
但需与既有歧义守卫共存」;并确认调用链后续不再按空格切词。
**用法**:
```markdown
## 用户 登录流程
+ `账号`
*"已登录 " + `账号`*
# main
> [用户 登录流程] 账号=alice
*""
```
**优点**
- 不新增语法:`[…]` 标记调用是**既有**的正式特性,只是被一行校验挡住
- 向后兼容:所有现有调用(含 `[加一_号]`)行为不变
- 与 Markdown 完全兼容:标题怎么写都行,调用时用方括号「引用这个名字」
- 语义清晰:方括号本身就是「这里是一个整体名字」的视觉标记
- 可推广:方法调用 `[obj.方法 名]`、库函数 `[lib.函数 名]` 一并受益
**风险与缓解**
| 风险 | 缓解 |
|------|------|
| `[…]` 也被用于链接索引 `[key](map)` | 已有守卫:`]` 后紧跟 `(` 则不是 callee(第 981 行),保持 |
| JSON 数组 `[1, 2]` 被误认为 callee | 既有守卫:含 `,` `:` `{` `}` `[` `]` 一律拒绝,保持 |
| `print text=(礼貌 [问候] x)` 类内嵌方括号 | 既有守卫:前缀含 `=` `(` `"` `'` `:` 则不当 callee,保持 |
| 运行时按下标查函数表,`加一 号` 能否命中 | **需实测验证**(见 §4 验证计划 V1) |
**工作量**:改 2 处校验 + 补 6–9 个测试 + 更新教程与陷阱手册。**最小可验证改动**。
---
### 方案 2 — 调用侧最长前缀匹配(否决)
**做法**:拿到 `加一 号 n=1` 后,尝试用「已知函数名」做最长前缀匹配。
**否决理由**
1. **上下文不可达**:调用发生在表达式解析阶段,此时只有本模块符号表;
跨模块 `lib.函数 名` 需要 import 解析结果,不可在词法期判定。
2. **歧义爆炸**:`> print text=hello world` 中,若存在名为 `print text` 的函数,
本来正确的调用会突然变成别的函数。所有多词行语义都可能改变。
3. 属于**核心语义变更**,收益(省掉方括号)远小于风险。
---
### 方案 3 — 主张「标题即函数名,调用用完整标题」(不改代码,只改文档)
**做法**:明确官方立场——带空格的名字**不自称可调用**,需要调用就请写
一个无空格的 `## 别名` 转发,或直接把标题写成无空格形式。
```markdown
## 用户 登录流程 ← 给人读的标题,不被调用
## 用户登录流程 ← 真正被调用的函数
+ `账号`
...
```
**优点**:零代码改动;鼓励「标题给人、标识符给机器」的清晰分层。
**缺点**:与「完全兼容 Markdown」仍有张力——作者得写两遍。
**适用**:如果审计认为方括号放开会牵连过多,可作为**保守退路**。
---
### 方案 4 — 反引号名解析到函数(否决)
允许 `` `加一 号` `` 在**调用位**解析成函数引用(`> `加一 号` n=1`)。
**否决理由**:反引号在 Marqdo 中统一表示**变量**引用。让它有时指变量、有时指函数,
会让「反引号=变量」这条最基础的约定失效,错误更难排查。
---
## 3. 方案对比
| 维度 | 方案 1 放开方括号 | 方案 2 前缀匹配 | 方案 3 文档立场 | 方案 4 反引号 |
|------|------------------|----------------|----------------|--------------|
| 兼容 Markdown | ✅ 完全 | ✅ | ⚠️ 需写两遍 | ✅ |
| 新增语法 | 无(复用既有) | 无 | 无 | 有歧义 |
| 改动范围 | 1 处校验 + 测试 | 核心语义 | 0 代码 | 核心语义 |
| 回归风险 | 低 | **高** | 无 | **高** |
| 可验证性 | 高(可枚举用例) | 低 | — | 低 |
| 推荐 | **首选** | 否决 | 备选 | 否决 |
---
## 4. 若采纳方案 1:验证计划
必须全部通过才可合入。
| 编号 | 用例 | 期望 |
|------|------|------|
| V1 ✅| `## 加一 号` + `> [加一 号] n=1` | 返回 `2`(**已实测通过**,见 §1.4) |
| V2 | `## 加一_号` + `> [加一_号] n=1` | 返回 `2`(**既有行为不变**) |
| V3 | 链接索引 `[k](m)` | 仍解析为索引,不被当 callee |
| V4 | `> print text=(礼貌 [问候] x)` | 内嵌方括号不被当 callee |
| V5 | 方括号内 JSON `[1, 2]` / `["a"]` | 仍被拒绝为 callee |
| V6 | 跨模块 `[lib.函数 名]` | 正确解析到库函数 |
| V7 | 方法 `[obj.方法 名]` | 正确解析 receiver |
| V8 | 全量 `cargo test` | 233 全绿(+ 新增用例) |
| V9 | 全仓库 `.mq.md` 回归 | 无新增解析错误 |
**V1 是决定性的**:如果运行时函数表以 `加一 号` 为键能正常查到,
方案 1 就成立;如果查不到(比如符号表内部也做了归一化),需要再评估。
---
## 5. 待你决策的问题
1. **选哪个方案?** 我倾向 **方案 1**(放开方括号空格):不新增语法、
完全兼容 Markdown、改动可控、可验证性强。
2. **若选方案 1,调用书写是否需要中文别名?** 例如同时接受 `【加一 号】`(全角方括号),
与全角冒号问题(D2)一致。
3. **是否要保留方案 3 的文档立场作为补充说明?** 即「标题可自由书写;
需要调用时用 `[完整名]` 引用」——这句话本身就很适合写进教程。
在你确认前,我不会改动 D8 相关代码。
+223
View File
@@ -0,0 +1,223 @@
# 修订:变更检测不该依赖 git —— 「前一状态」的 provider 分层
| | |
|---|---|
| 状态 | **Accepted · 修订**(取代 [warning-fatigue-control.md](warning-fatigue-control.md) §2 的 M5a) |
| 日期 | 2026-10-22 |
| 触发 | 用户:不是所有开发都用 git,依赖 git 是否是好设计 |
| 结论 | **不是好设计**。保住「变更驱动」原则,把「前一状态」抽象为可插拔 provider;核心能力零依赖 |
| 前置 | [label-freshness-and-repair.md](label-freshness-and-repair.md) · [warning-fatigue-control.md](warning-fatigue-control.md) |
---
## 0. 直接回答:不该依赖 git
三条理由,一条比一条硬:
### 0.1 环境覆盖不到
| 环境 | 能调 git 吗 | 依据 |
|------|------------|------|
| 浏览器 WASM | ❌ | `marqdo-wasm`(wasm32-unknown-unknown),无进程能力 |
| **沙箱内执行** | ❌ | `src/host/sandbox_fs.rs`:`allow_exec: false` |
| 单文件分发 / zip 工件 | ❌ | 没有 `.git` |
| CI 容器(浅克隆/无 VCS) | ⚠️ 常常没有 | 取决于流水线 |
| 非 git 用户(hg / svn / fossil / 无) | ❌ 或需另写适配 | — |
### 0.2 语言不该绑定某个 VCS
Marqdo 是**语言与运行时**。把"断言是否过期"的判定建立在"某个工具的目录是否存在"上,
等于把语言的语义正确性外包给环境。今天 git 是主流,明天不是;语言不能跟着换。
### 0.3 最要命的:最重要的消费者恰在不能调 git 的地方
标签过期检测的**最高价值场景**是 agent 修复回路——
模型改了代码,Marqdo 提醒它"你改的这处描述可能不成立了"。
而这个回路:
- 常在沙箱里跑(`exec=false`,**调不了 git**)
- 编辑目标是内存中的文本(`repair_apply` 的 `source`),不一定落在 git 工作区
**如果核心机制依赖 git,那它恰好在最需要它的地方失灵。** 这是设计错误的铁证。
---
## 1. 但 M5 的原则要保住
上一份文档的 M5 有两个部分,必须分开看:
| 部分 | 判定 |
|------|------|
| **原则**:stale 是"变更报告",不是"扫描报告"(没有新信息就不说话) | ✅ **保留**,这是防疲劳的根 |
| **实现**:用 `git diff` 提供"前一状态" | ❌ **降级为可选 provider** |
也就是说:
> **判定逻辑只有一份:`stale ⟺ fingerprint(()) 变了 ∧ label 没变`。
> 变的只是「前一个 `()` 从哪来」。**
这一步抽象之后,git 只是**四种来源之一**。
---
## 2. 四层能力(provider 分层)
### T0 — 引用一致性(零依赖,永远可用)
纯文档分析:标签里的 `` `实体` `` 必须可解析、且出现在 `()` 中。
- 需要:只读当前文件(甚至只需文本)
- 能力:查**引用腐烂**(改名、删除、错引)
- 查不了:语义腐烂(`*` 改 `/`)
### T1 — 会话内前后对照(零依赖,最高性价比)
**任何"编辑前 + 编辑后"都在手的场合**都能算 stale:
| 场合 | 前一状态从哪来 |
|------|---------------|
| `MLSP repair_apply` | 调用方传入的 `source` + `edits` → 前/后两版都在内存里 |
| `view`(保存后检查) | 保存前的模块 AST |
| 编辑器保存钩子 | 编辑器持有的旧缓冲 |
| agent 的 diff | 它自己的编辑集 |
**关键**:只看「本次会话改了哪些标签的 `()` 且没改 `[]`」。
天然变更驱动、天然零台账、天然带 before/after——**而且不需要 git**。
### T2 — 外部历史源(可选,自动探测)
`git` / `hg` / `svn` / 任意"能取到上一版文件内容"的适配器。
- 检测:工作区存在 `.git` / `.hg` 且二进制可用
- 用途:**跨会话**漂移(昨天改了代码,今天才检查)
- 缺失时:**静默关闭**,不报错、不提示、不产生噪音
### T3 — 台账(可选,无 VCS 时的持久化)
`.marqdo/labels.json`:`{标签键 → {code_fingerprint, code_quote, confirmed_at}}`
- 用途:没有 VCS 的环境(沙箱长期任务、编辑器插件)+ 严格模式的"确认"状态
- 语义:**可丢弃缓存**(删了重建,最多一次全量确认)
- 已知代价:合并冲突、需要 bootstrap(因此作为 opt-in,不做默认)
---
## 3. 环境能力矩阵
| 环境 | T0 引用 | T1 会话内 | T2 历史源 | T3 台账 |
|------|--------|----------|----------|--------|
| CLI + git 仓库 | ✅ | ✅ | ✅ | ✅ |
| CLI + hg/svn(有适配) | ✅ | ✅ | ✅ | ✅ |
| CLI 无 VCS | ✅ | ✅ | ❌ | ✅ |
| **agent 沙箱(exec=false)** | ✅ | ✅ | ❌ | ⚠️ CoW 内可写但不持久 |
| **浏览器 WASM** | ✅ | ✅ | ❌ | ❌ 无持久 fs |
| 单文件 / zip 工件 | ✅ | ✅ | ❌ | ❌ |
| 数据库/对象存储里的 `.mq.md` | ✅ | ✅ | ❌ | 由宿主提供 |
**读法**:矩阵里**没有一行全 ❌**。T0+T1 在所有环境都成立——
这两层就足以支撑"agent 改动即时提醒"这个最高价值场景。
---
## 4. 各层的能力边界(必须诚实)
| 层 | 能查 | 查不了 |
|----|------|--------|
| T0 | 引用了不存在的实体;引用的实体不在语句里 | 语义腐烂(乘改除) |
| T1 | **本次会话内**的 `()` 变化 | 跨天/跨机器的漂移 |
| T2 | 跨会话、跨机器的漂移(若 VCS 有历史) | 未提交历史之外的变化;跨仓库移动 |
| T3 | 持久化的漂移(若台账被维护) | 台账未覆盖的标签;合并后需重算 |
**组合起来的语义**:
- 有 T2 → 严格(能查历史)
- 只有 T0+T1 → **会话级严格**(够 agent 用)
- 什么都没有(WASM 首次打开) → 只查引用(T0),且**明确告知能力级别**
---
## 5. 最关键的一条:agent 回路不需要任何 VCS
`MLSP repair_apply` 的参数里**已经同时有前后两版**:
```rust
// src/mlsp.rs:repair_apply 收到 source + ranges + edits
let source = source_text(params)?;
// → 应用 edits 得到 after
```
所以只要给协议补一个字段 `base_code`(或让 `repair_apply` 自己在内部保留 before),
Marqdo 就能在**同一次调用内**算出:
> 哪些标签的 `()` 指纹变了、而 `[]` 没变 → 输出 stale 提示。
**零外部状态、零依赖、零 git。** 而这正是"模型改了代码别忘了改描述"的场景。
**具体协议建议**(只需一个可选字段):
```json
{ "method": "repair_apply",
"params": { "source": "…", "ranges": [[42,42]], "edits": [...],
"check_labels": true } }
```
返回里附:
```json
{ "labels": [{ "stale": 1, "items": [{ "text": "按 `税率` 计算总价",
"code_past": "…* 金额", "code_now": "…/ 金额", "span": {...} }] }] }
```
这样 agent 每轮只看到**自己刚弄脏的那几条**,且带前后对照。
---
## 6. provider 契约(五条硬规则)
1. **核心不依赖**:T0/T1 必须在任何环境可用,不得引入 provider 前置条件。
2. **缺失即降级**:provider 不可用 → 静默关闭该层能力,**绝不报错、绝不提示**。
3. **能力必须自述**:`labels status` 必须显示"当前启用 T0/T1/T2/T3 中的哪些"。
——否则用户会误以为"没报 = 没问题",这是比噪音更坏的失败。
4. **判定单一定义**:`stale` 的定义只有一处实现;provider 只提供 `prev`,不参与判定。
——否则不同环境会给出不同结论,语言就没有统一语义了。
5. **不写进文档**:provider 的状态、指纹、抑制**一律不进 `.mq.md`**。
文档里只允许有人的语言与代码。
> 第 3 条是我这次最想强调的:**宁可少报,也不能假装"检查过了"。**
---
## 7. 被否决的方案
| 方案 | 否决理由 |
|------|---------|
| **强制 git 作为核心** | 环境覆盖不到(§0.1);语言绑定 VCS(§0.2);最关键场景失灵(§0.3) |
| 文档内嵌指纹 | 污染文档;作者一改就失效;与"文档即散文"冲突 |
| 零宽字符隐藏指纹 | 不可见 = 不可审计;复制粘贴即损坏;工具链噩梦 |
| mtime 启发式 | 不可靠(checkout、touch、云同步都会变) |
| `# noqa` 抑制 | 已否(污染 + 不可审计 + 会永久化) |
| 只做全量扫描 + 静音清单 | 静音清单就是台账,且首次即爆炸 |
---
## 8. 对上一份文档的修订
| 原条目 | 修订后 |
|--------|--------|
| M5a「git 结构化 diff」为核心机制 | 降级为 **T2 的一个适配器**;核心改为 **T0 + T1** |
| 严格模式依赖台账 | 严格模式 = 任意 T2 **或** T3 可用即可;无 provider 时按 T0/T1 运行 |
| 验收指标「无变更时输出 = 0」 | 保留,且补一条:**provider 缺失时也必须为 0,并在 `labels status` 里说明** |
---
## 9. 待你决策
1. **接受「T0+T1 为核心,T2/T3 可选」这个分层吗?**
2. **T1 是否足够**作为 agent 回路的默认能力?(我认为够——它覆盖了"刚改完"这个主场景)
3. **能力自述**要不要做成 `labels status` 的固定输出
(含"本次无法检测历史漂移"这类明确提示)?
4. **T2 的适配范围**:只做 git,还是留一个通用接口(返回"某文件的上一版文本")由宿主实现?
5. **T3 台账**是否推迟到有明确需求再做?(我建议推迟——先把 T0+T1 做扎实)
> 我的建议:**先只做 T0 + T1**,把「变更驱动 + 零依赖 + 能力自述」这条骨架立住。
> 这样无论用户在 git、hg、WASM 还是沙箱里,Marqdo 的标签保鲜都成立,
> 只是"能看多远"不同——而这一点会被明确告知,不会假装。
+2 -2
View File
@@ -2,9 +2,9 @@
| | |
|---|---|
| 状态 | **已落地(v1)** |
| 状态 | **v1 已落地**;v2 设计见 [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [notebook-syntax.md](notebook-syntax.md) |
| 日期 | 2026-08-06 |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) |
| 相关 | [stdlib-modules.md](stdlib-modules.md) · [stdlib-math.md](stdlib-math.md)(公式同构绑定) · [foreign-kernel.md](foreign-kernel.md) · [notebook-session.md](notebook-session.md) · [roadmap/foreign-v2.md](../roadmap/foreign-v2.md) |
---
+4 -2
View File
@@ -35,7 +35,8 @@
```markdown
---
import text:lib/text.mq.md
import:
text: lib/text.mq.md
---
# main
@@ -44,7 +45,8 @@ import text:lib/text.mq.md
```markdown
---
导入 文本:lib/文本.mq.md
导入:
文本: lib/文本.mq.md
---
# main
+2 -1
View File
@@ -17,7 +17,8 @@
```markdown
---
import table:lib/table.mq.md
import:
table: lib/table.mq.md
---
# main
+3 -2
View File
@@ -51,8 +51,9 @@ Frontmatter 导入**绑定库名**(默认 = 文件名茎;`as` / `作为` 可
```markdown
---
import text:lib/text.mq.md
import table:lib/table.mq.md
import:
text: lib/text.mq.md
table: lib/table.mq.md
---
```
+233
View File
@@ -0,0 +1,233 @@
# T1 会话内陈旧检测:为什么模型不会收到重复警告
| | |
|---|---|
| 状态 | **Accepted · 机制说明**(M6 落地) |
| 日期 | 2026-10-22 |
| 回答 | 「在不改变的情况下,能让模型免于多次警告疲劳吗?」——**能,而且几乎不用改什么** |
| 前置 | [staleness-providers.md](staleness-providers.md) · [warning-fatigue-control.md](warning-fatigue-control.md) |
---
## 0. 一句话
> **警告的作用域 = 模型自己刚改的那几行;投递次数 = 一次;附着在造成它的那次编辑的返回里。**
不是"我们让它少报",而是**同一件事在结构上不可能被报第二次**。
---
## 1. 机制为什么成立:前后两版本来就在手里
看现有 `repair_apply`(`src/mlsp.rs:233`)的实现:
```rust
let source = source_text(params)?; // ← 改动前(before)
...
match crate::repair::apply_edits(&source, &ranges, &edits) {
Ok(new_source) => { // ← 改动后(after)
Ok(json!({"source": new_source, "edits_applied": edits.len()}))
}
...
}
```
**`source` 和 `new_source` 在同一个函数作用域里同时存在。**
所以"比较改动前后"不需要任何外部东西:
| 需要的东西 | 从哪来 |
|-----------|--------|
| 改动前的 AST | `parse(source)` |
| 改动后的 AST | `parse(new_source)` |
| 标签配对 | 两份 AST 里的标签节点(按标签文本 + 序号) |
| `()` 是否变了 | 比较两边的 AST 指纹 |
| `[]` 是否变了 | 比较标签文本 |
**零 git、零台账、零缓存文件、零环境依赖。** 这就是"agent 回路根本不需要 VCS"的含义。
### 1.1 指纹怎么做(T1 只需要「进程内一致」)
这一点让实现变得很轻:
- `Expr` 目前 `#[derive(Debug, Clone)]`,**没有 `PartialEq`**(`src/ast.rs:184`)。
- 但 T1 只在**同一个进程内**比较前后两版,**不需要跨版本、跨机器稳定的指纹格式**。
于是最简做法是:把 `()` 的比较键取为 `format!("{:?}", expr)`——同一次运行内确定即可。
- 若想更严谨,可给 `Expr` 及其成员补 `#[derive(PartialEq)]`(纯机械改动;`Literal` 含 `f64`,
只可 `PartialEq` 不可 `Eq`),然后直接结构比较,不产生字符串。
- 反过来,**T2/T3 才需要稳定指纹**(跨会话要能对上),那时才动用
`knowledge/fingerprint.rs` 那套。
> 也就是说:T1 的实现成本 ≈ "解析两次 + 比较两棵子树",没有版本化指纹的负担。
---
## 2. 一次修复轮次的完整时序
```
第 N 轮
┌─ validate → 语法/契约诊断(不含标签扫描)
├─ repair_targets → 靶点 + 允许范围
├─ 模型产出 edits (例如:把 `* 金额` 改成 `/ 金额`)
└─ repair_apply(source, ranges, edits)
│
├─ before = source
├─ after = apply_edits(...)
├─ 解析两版 → 比较每个标签的 () 指纹
└─ 返回:
{ "source": after,
"edits_applied": 1,
"labels": { "stale": [ {标签, code_past, code_now, span} ] } }
```
模型在自己这次编辑的**响应里**看到:
```json
{
"labels": {
"stale": [{
"text": "按 `税率` 计算总价",
"code_past": "at(税率表, 档位) * 金额",
"code_now": "at(税率表, 档位) / 金额",
"span": {"line": 42, "col": 12}
}]
}
}
```
它只需要回答一个问题:**"你刚才动了这段实现,描述还成立吗?"**
---
## 3. 为什么「重复」在结构上消失了
三个性质,缺一不可:
| 性质 | 内容 | 效果 |
|------|------|------|
| **作用域 = 自己的 diff** | 只看这次 `apply` 触及的标签 | 全仓库/全文件的旧债永远不进模型的上下文 |
| **投递 = 一次** | 只在造成它的那次响应里出现 | 不会在后续 `validate` 里重复出现 |
| **自包含** | 下一轮的 diff 是新的 | 模型不改那处 → 那条标签不再出现 |
**注意第三条的含义(也是代价)**:模型若忽略了提示,它**不会**在下一轮被再提醒——
因为它没碰那处。这是刻意的取舍:**宁可漏一次,也不反复骚扰**。
> 对比扫描式:一个 20 处标签的文件,5 轮修复里模型可能累计看到上百条重复提示;
> T1 下最多看到 **自己这几行涉及的 0–2 条**,且每条只出现一次。
---
## 4. 关键重构:它在性质上**不是 warning,而是编辑期诊断**
这是我认为最重要的一点。
| | Lint 警告 | 编译器错误 | **T1 stale** |
|---|---|---|---|
| 出现时机 | 常在后台/每次保存 | 你按下构建那一刻 | **你改完那一刻** |
| 数量 | 与存量成正比 | 与你这次写的错成正比 | **与你这次改的成正比** |
| 是否重复 | 反复出现 | 不重复(改了就消失) | **不重复** |
| 用户态度 | 容易忽略 | 必须处理 | **天然要处理** |
没有人抱怨"编译器又报语法错了"——因为它是**一次性的、可归因的、改动驱动的**。
T1 的 stale 正好落在这个类别里。
**所以疲劳问题不是靠压制解决的,是靠把 stale 从"lint 类别"搬到"编译错误类别"解决的。**
---
## 5. 「不改变」到什么程度
你的问法是"在不改变的情况下"。精确回答:
| 项 | 要不要变 |
|----|---------|
| `.mq.md` 文档内容 | **不变**(不嵌指纹、不加 `noqa`、不加标记) |
| 写代码 / 读代码的工作流 | **不变**(还是 validate → repair_targets → 编辑 → repair_apply) |
| 项目状态文件 | **不新增**(无台账、无基线、无 `.marqdo/labels.json`) |
| 对 VCS 的依赖 | **无**(沙箱 `exec=false`、WASM 无进程,照样可用) |
| 环境要求 | **无**(纯内存计算) |
| **MLSP 协议** | **加一个可选参数 + 一个响应字段**(这是唯一的改动) |
唯一的协议改动小到可以忽略:
```json
{ "method": "repair_apply",
"params": { "source": "…", "ranges": [[42,42]], "edits": [...],
"check_labels": true } }
```
- `check_labels` 缺省 = 不做(**默认零开销、零噪音**)
- 客户端(agent 框架)在修复回路里打开它
- 返回里多一个 `labels` 字段;无 stale 时为空数组
---
## 6. 配对规则(哪些算"同一条标签")
比较两份 AST 时:
| 情形 | 判定 |
|------|------|
| 标签文本未变、`()` 指纹变 | ✅ **stale**(核心场景) |
| 标签文本变了 | 不报——作者在更新描述,这就是"确认" |
| `()` 与标签都没变 | 不报 |
| 新插入的标签 | 不报——新断言无历史 |
| 被删掉的标签 | 不报——没有东西可比 |
| 标签移动位置(同文件) | 不报——按标签文本配,不按行号 |
**"按标签文本配对"很关键**:它让"把这段代码挪个位置"不会误报,
而"把这段代码的计算改了"一定报警。
---
## 7. 模型会不会漏掉?三种兜底
T1 的代价是"不重复",所以要设计"漏了怎么办":
| 兜底 | 做法 | 代价 |
|------|------|------|
| **循环预算** | `labels.stale` 非空时,客户端允许下一轮(现有 `max_attempts: 2` 直接可用) | 无 |
| **可选阻塞** | `check_labels: "block"`:apply 成功但返回 `needs_attention: true`,客户端不得结束任务 | 小 |
| **会话末汇总** | 最后一轮给一次总数(只一次,不逐条) | 小 |
**建议默认**:`check_labels: true` + 循环预算。也就是"提示一次,允许一轮修,不强制"。
知识库仓可以用 `"block"`。
---
## 8. 边界(必须说清)
| 问题 | T1 能不能 |
|------|----------|
| 模型刚改完,描述还成立吗 | ✅ 能(核心场景) |
| 昨天有人改了代码,今天打开才发现描述过期 | ❌ 不能(`diff` 里没有,那是 T2 的活) |
| 从别处复制粘贴一段代码带来的旧标签 | ❌ 不能(无历史) |
| 描述写得笼统、无法证伪 | ❌ 不能(L1 也不查) |
**T1 的定位**:保证"**改动者当场被问一次**"。
它不保证"整个仓库始终新鲜"——后者需要 T2/T3,是可选增强,不进默认路径。
---
## 9. 与你担心的「疲劳」对照
| 场景 | 扫描式(每轮全量) | **T1(本机制)** |
|------|------------------|-----------------|
| 模型一轮看到几条 | 全仓库 N 条 | **0–2 条** |
| 5 轮累计 | N × 5 | **≤ 2** |
| 同一标签重复 | 每轮重复 | **一次** |
| 未修复的旧债 | 每轮都提 | 不再提(等它被改到时再说) |
| 模型需要记住"我之前看过" | 需要 | **不需要**(自包含) |
| 需要 VCS / 台账 | 常需要 | **不需要** |
---
## 10. 待你确认
1. **接受"T1 = 编辑期诊断,不是 lint 警告"这个定位吗?**(这是整个防疲劳论证的支点)
2. `check_labels` 默认值:`false`(零开销)还是 `true`(修复回路默认开)?
3. 漏掉的兜底:用**循环预算**(不强制)还是**可选阻塞**(`"block"`)为默认?
4. 会话末汇总要不要做?(一次性总数,不逐条)
> 若你确认,P1 的第一步就很小:给 `repair_apply` 加 `check_labels`,
> 在 `apply_edits` 之后解析两版、比较标签指纹,把结果挂在响应里。
> 文档零改动、状态零新增、不依赖 git——**第一天就不会有任何存量警告**。
+78
View File
@@ -0,0 +1,78 @@
# \(V_{\mathsf{safe}}\) JSON integer contract (host ↔ Lean)
Canonical Lean model: `MarqdoThesis/PLDI/proofs/MarqdoProof/MarqdoProof/ForeignJSON.lean`.
Host mapper: `src/host/json.rs` (`json_to_value` / `value_to_json`).
This document freezes **runtime conformance** of the Marqdo JSON bridge to the
mechanized \(V_{\mathsf{safe}}\) integer domain. It is **not** a verified
compilation of the Rust interpreter.
## Domain
```
MAX_SAFE = 9007199254740991 # 2^53 - 1
```
\(V_{\mathsf{safe}}\) values (mechanized):
| JSON | Marqdo |
|---|---|
| `null` | `None` |
| `bool` | `Bool` |
| integer with `\|n\| ≤ MAX_SAFE` | `Int` |
| `string` | `Text` |
| `array` | `List` |
| `object` | `Map` |
**Host extension (not in Lean `SafeVal`):** JSON non-integer numbers → `Value::Num(f64)` (NaN/Inf encode as `null`). Floats are documented host behavior; they are **not** claimed as mechanized \(V_{\mathsf{safe}}\) fidelity.
## Encode (`value_to_json`)
- `Value::Int(n)` with `|n| ≤ MAX_SAFE` → JSON number.
- `Value::Int(n)` with `|n| > MAX_SAFE` → **refuse** (error).
- `Value::Handle(_)` → **refuse** (`json: session handle cannot be serialized`).
- Column-table `Map` whose fields are all `List` with **unequal lengths** →
**refuse** (`json: table column arity mismatch`).
- Nested `List` / `Map`: any child refuse fails the whole tree.
- GFM table **parse** also refuses unequal row width
(`table row arity mismatch`) before a value is built.
- Wide integers that must cross a language boundary: author converts to a
**decimal string** (∈ \(V_{\mathsf{safe}}\)); the foreign program may use
`BigInt` / Python `int` on that string.
## Foreign oracle (`session_eval` / `session_get`)
Python/Node session bootstraps sanitize results with the same integer gate
before JSON emission. An Ω response containing an OOD integer is a **fault**
(host `Err`), not a soft `ok:false` cell record. Stdout text that authors
`json.parse` themselves is still gated by host `json_to_value`.
## Decode (`json_to_value`)
- JSON integer with `|n| ≤ MAX_SAFE` → `Int`.
- JSON integer with `|n| > MAX_SAFE` → **refuse**.
- JSON unsigned integer `> i64::MAX` → **refuse** (do **not** coerce via `f64` or `Text`).
- Nested array/object: any child refuse fails the whole tree.
- Decimal-string encodings of wide integers → `Text` (in domain).
## Error prefix
All refuse messages use a fixed prefix for probes and diagnostics:
```
json: integer outside V_safe (±(2^53-1)): <n>
```
## In-domain roundtrip
`±MAX_SAFE`, bool, null, string, array, and object roundtrips through
`encode → decode` must succeed. Integers `MAX_SAFE+1`, `-MAX_SAFE-1`, `2^53`,
`2^60`, `2^60+1` (and nested forms) must refuse.
## Non-claims
- Not verified Rust ↔ Lean compilation.
- Not arbitrary host-object fidelity (DataFrame, functions, heap sharing).
- Not automatic BigInt promotion inside Node/Python bootstraps.
- Document-level `Value::Int` may still hold i64 values that are OOD for JSON;
the gate fires when those values enter JSON encode/decode.
@@ -0,0 +1,463 @@
# View 可执行知识阅读体验重设计
| 项目 | 说明 |
|---|---|
| 日期 | 2026-10-24 |
| 状态 | 详细设计建议,待实施;不是已交付能力声明 |
| 审计基线 | `b8a4ddd` / Marqdo 2.1.1;使用当前源码构建的 debug CLI 复核 |
| 输入 | 用户提供的 view 截图:Executable Knowledge 在 Structure 前,Steps、Target、Kind、Signature、Effects、Verification、Lock digest 等字段大量铺开 |
| 范围 | Live view、静态导出、正文结构、知识说明、运行结果、来源与状态呈现;不改语言语义,不增加作者必填的展示 DSL |
| 关联 | [文档原生开发指导](document-native-development-guide.md)、[View 总体设计](view.md)、[文档面与标注](view-document-annotations.md)、[求道相关框架缺口](../roadmap/qdagent-knowledge-support-gaps-2026-10-24.md) |
## 1. 设计决策
**View 首先呈现知识文档本身,结构帮助读者理解和定位,机器信息解释当前所读内容。** 正文、程序结构、知识关系与执行证据应由同一份源文档关联起来,而不是顺序展示几份互相脱节的报告。
确定以下方向:
1. 移除正文之前整块展开的 Executable Knowledge。主阅读流首先出现作者的标题、介绍和内容;不把完整机器报告简单搬到正文后继续平铺。
2. 保留并改进现有 Structure 的叙述保真文档面,面向读者命名为“文档”。正文、表格、公式、函数和可执行步骤在原位置阅读,不生成一份模型改写的平行说明书。
3. 右侧“本文结构”负责章节与知识单元定位;选中知识片段后,在同一辅助栏展示它的解释、输入输出、来源和验证依据。源码标识、摘要与完整协议放在可展开的技术详情中。
4. 运行结果就地关联到对应步骤,明确运行实例与输入;完整日志、运行控制和源码放在正文后。看见一个数值时,读者必须能知道它是文档声明、计算结果还是历史快照。
5. 静态分析、程序运行、测试断言、来源关联和领域确认分别表达。不能用一个 `ok`、`pure` 或绿色“已验证”覆盖不同事实。
6. 功能渐进增强:无 JavaScript、静态导出、移动端、打印时仍能读完文档、定位知识和查看必要依据。普通短文不变成复杂仪表盘。
这些决策恢复 [view.md](view.md) 原有“文档面为主、Browse 与 Debug 分工”的方向,同时修订过度依赖引出线和默认展开技术面板的呈现方式。
## 2. 现状审计:为什么截图难读
### 2.1 可定位的实现依据
| 观察 | 当前代码 | 对阅读的影响 |
|---|---|---|
| 知识面板位于正文前 | [html.rs / page_file](../../src/view/html.rs) 的模板顺序为 notebook → knowledge → Structure → Execution → Source | 必须先越过辅助资料才能看到文档;模块越多越严重 |
| 所有制品一律展开 | [render.rs / render_knowledge_html](../../src/view/render.rs) 按文件筛选 artifacts,并逐项输出完整 `<dl>` | module/type/function 同等突出,容器元信息挤占知识内容 |
| Steps 脱离所属结构 | 同函数把当前文件所有 steps 放在单一 `<ol>` 中,展示 kind、label、完整目标 ID | 静态步骤容易被误读为实际执行顺序;调用/循环/正文引用混在一起 |
| 内部字段未经阅读转译 | URI、签名、effects、verification 拼接文本、完整 sha256 默认可见 | 读者仍不知道这项知识解决什么问题、怎样用、依据在哪里 |
| “Lock digest”名实不符 | 该字段实际显示 `artifact.hashes.artifact`;[mod.rs](../../src/view/mod.rs) 编译使用 `LockMode::Off` | 制品摘要被误读为已经锁定且通过复现检查 |
| 静态说明与运行脱节 | 每张卡固定输出 `Not executed by knowledge preview.`;实际 run capture 在另一条路径 | 即使页面有运行结果,也很难理解“未执行”到底指什么 |
| 分析失败静默消失 | `build_file_view` 对语义编译结果使用 `unwrap_or_default` | 无知识、分析失败、尚未分析在界面上都可能表现为空 |
| 标题与层级表达较弱 | `page_file` 标题取文件名;[document.rs / render_fun_heading](../../src/view/document.rs)统一用 h3 | 作者 frontmatter 标题未用于页标题,嵌套结构主要靠其它线索判断 |
| 知识组件缺少专用布局 | `knowledge-*` 在 HTML 中有类名,但 `html.rs` 没有与面板匹配的专用样式规则 | 大量使用默认列表/定义列表排版,空白多、关系弱,和正文主题缺少一致约束 |
| 新旧皮肤叠加 | `html.rs` 内基础 view CSS 与 `notebook_ui` 大块 notebook 主题共存 | 正文、注释、知识区的字号和密度不一致;不能只修一个卡片颜色 |
| 验收主要看元素存在 | [executable_knowledge.rs](../../tests/executable_knowledge.rs) 的 view 用例检查 step 类名、kind 和 `#stmt-` 链接 | 没检查正文优先、跳转目标存在、可读文案和实际布局 |
已有能力应保留:[document.rs](../../src/view/document.rs) 的叙述/表格保真、Occlusion 描述与实现分离、函数大纲、调用帧/循环帧选择、[annot.rs](../../src/view/annot.rs) 的真实执行标注。重新设计应基于这些能力,而不是退回 AST 卡片浏览器。
### 2.2 对截图的解释边界
截图可直接确认:机器字段先于正文、Steps 只有 `call print`、长 URI/摘要显著占位、英文状态串缺少解释,以及深色底上的孤立黑色短线。
黑色短线的具体来源尚未在浏览器中复现。代码中存在 annotation leader、布局重算和主题覆盖,可能需要检查,但本文件不把它们断言为唯一根因。实施时应使用用户截图对应页面复现,检查实际 DOM、computed style 和几何位置;不能用全局隐藏所有 SVG/边框来掩盖问题。
### 2.3 本轮实际复核
把 [public/features/01-phase-i-treewalk.mq.md](../../public/features/01-phase-i-treewalk.mq.md) 复制到临时目录,使用 debug 2.1.1 执行静态导出并检查生成 HTML:knowledge 确实在 structure 前,共 3 个 `knowledge-card`(含 Steps)和 2 个完整 sha256。该短文的核心只是介绍 tree-walk 流程并打印一句话,当前辅助内容明显过重。
另用隔离临时文件复核 `view output --no-exec`:嵌入的 `fs.write_text` 仍创建了临时标记文件。原因是 [output.rs / write_static](../../src/view/output.rs) 先调用会执行的 `build_file_view`,再在 `opts.no_exec` 分支清空结果。**这是已复现的执行/呈现不一致,必须修复,不能仅把标签改成“未运行”。** §9 给出新的构建边界。未执行线上浏览器像素比对,本文线框为目标设计。
## 3. 读者任务与设计成效
| 读者任务 | 默认应看到 | 按需展开 | 成功判据 |
|---|---|---|---|
| 理解这篇文档 | 作者标题、介绍、正文和核心表格/步骤 | 完整源码 | 不滚过机器报告就能开始阅读 |
| 看懂文档结构 | 章节、类/规则/函数的真实层级,当前位置 | 参数和局部步骤树 | 能判断一个步骤属于哪个知识单元 |
| 理解某项知识 | 描述、简洁公式/调用、条件、返回含义 | payload、契约、精确目标 | 能解释它做什么、需要什么、产生什么 |
| 判断结果是否可信 | 来源状态和所选运行的明确结果 | 测试、来源片段、版本和诊断 | 能区分“可以运行”和“事实成立” |
| 跟踪跨文档复用 | 友好目标名、所属文档、输入输出 | 依赖关系、完整标识 | 能到达定义并返回原阅读位置 |
| 检查某次运行 | 本次输入、选中调用/迭代、对应结果 | 日志、历史帧 | 不把不同运行的值混在一起 |
不要求所有读者理解 SymbolId、IR、hash 或 effect 协议。开发者仍能找到这些信息,但它们不再成为阅读的前置条件。
## 4. 页面信息架构
### 4.1 默认桌面布局
```text
┌ Marqdo 项目 / 文档路径 搜索 主题 ┐
├───────────┬───────────────────────────────┬────────────┤
│ 文件目录 │ Phase I — tree-walk interpreter│ 本文结构 │
│ │ Lex · parse · check … │ 介绍 │
│ 当前文件 │ [运行记录:尚未运行] [详情] │ main 入口 │
│ │ │ │
│ │ Milestone: Phase I … │ │
│ │ Pipeline: load → … → eval │ 选中后: │
│ │ │ 当前知识 │
│ │ main · 入口 │ 作用 │
│ │ 输出说明 print text=… [说明] │ 输入/返回 │
│ │ │ 来源/条件 │
│ │ ▸ 运行与结果 │ 检查/运行 │
│ │ ▸ 完整源码 │ 技术详情 ▸ │
└───────────┴───────────────────────────────┴────────────┘
```
布局是文件导航、主文档、一个辅助栏,不能增加第四条永久侧栏。右栏上部保留可收起的“本文结构”;用户选中片段后,下部显示“当前知识”。空间不足时以当前知识替换下部内容,并提供“返回目录”操作。打开/关闭详情不改变正文宽度,避免重排导致阅读位置跳动。
主文档的默认顺序:
1. 文档标题、已有 description、简短状态入口;title 缺失时退回文件名。
2. 源文档的正文、结构和轻量就地知识说明,保持作者顺序。
3. “运行与结果”:运行按钮、输入、所选运行结果、输出图形/日志;已有重要失败有就地入口。
4. “完整源码”及“文档技术信息”,默认折叠。
不在顶部强制生成内容摘要、全量函数清单、巨大状态矩阵或知识关系图。没有 description 时不调用 LLM 补写。结构大纲始终可达,正文不因折叠辅助栏而变成无结构的文章。
### 4.2 尺寸与响应式规则(设计目标)
| 可用宽度 | 布局 |
|---|---|
| ≥1280 CSS px | 文件栏约 220–260px;正文弹性;辅助栏约 280–320px;正文中文行长约 32–44 字 |
| 900–1279px | 文件栏可收起;正文优先,辅助栏可切换为有标题的侧抽屉 |
| <900px | 单列文档;“目录”“当前知识”作为明确按钮打开抽屉或块内 details |
| 320–390px 手机 | 标题、正文、状态不横向溢出;长表格/代码局部滚动,整页不左右拖动 |
| 打印 | 正文展开,必要来源/验证摘要转为节后附注;交互按钮和导航隐藏;技术原始字段按导出选项包含 |
在 1440×900、100% 缩放的短文验收样例中,首屏应包含至少一段正文和首个主要结构单元;状态头不得因每个 artifact 增长而把正文推出首屏。此约束不截断作者自己的长标题或介绍。
### 4.3 普通文档与复杂知识文档采用同一布局
- 普通说明页只有 main/print:显示原文与输出操作,技术区保留模块信息;不强制展示“1 项可执行知识”卡。
- 可复用函数库:目录列出函数;函数标题下出现紧凑签名和“说明”入口;即使无 main,也能正常阅读。
- 事实/规则文档:来源、条件与验证紧邻相应知识;来源问题不能藏进页尾。
- 教程/Notebook:保留源文档的代码单元与结果;全局单元运行条收进运行区域或显式工作模式,不能把所有文章永久变为 notebook 工具台。
- 大文档:目录按真实层级和顺序组织,可搜索;正文不因知识数量膨胀为另一份报告。
## 5. 文档与结构呈现规范
### 5.1 标题、类与函数层级
页标题优先来自解析后的 frontmatter `title`,其次使用合适的源文档标题,再回退文件名;不要自行用正则重解析 YAML。保留原文标题内容,不擅自把技术名称改成模型生成的名称。
“本文结构”同时服务阅读和程序定位,但明确区分:
- 作者章节按实际文档关系展示。
- 可执行的类/类型、函数、入口附轻量类型词,例如“规则”“函数”“入口”;类型词来自编译结果或已声明元数据,不由标题猜业务类型。
- 同一节点既是章节又是函数时只有一个目录项,旁边标类型,避免两棵树重复。
- 嵌套函数、分支、循环在对应父节点下展开;语义归属与 Markdown 可视层级分别保留,不把所有内容都扁平化为 h3。
- 普通段落引用不提升为函数;module 容器不自动成为一张与业务函数同权的卡。
DOM 标题使用连续、可访问的层级;实际语法的 `#`/`##` 层数在源码面保留。用户复制源码时取得原始合法语法,而非为了 HTML 标题级别改写过的内容。
### 5.2 可执行步骤:就地解释并保留上下文
| 编译器步骤 | 默认阅读文案 | 展开后 |
|---|---|---|
| observe | “读取:商品单价” | 集合、取元表达式、字段说明、当前调用下的值 |
| derive | “计算:商品小计” | 公式、输入来源、计算条件、当前结果 |
| call | 优先作者标签;无标签时“调用 商品小计” | 目标、所属文档、实参映射、返回和运行记录 |
| iterate | “逐项处理:订单商品” | 集合、循环体、迭代数、所选迭代 |
| narrate | 正文保留作者描述,附“知识引用”入口 | 定义与来源;不当作已执行步骤 |
| navigation | 标准文档链接 | 正常导航,不显示虚构的执行结果 |
| 空 payload / stub | 作者描述 + “待实现” | 缺失的实现和已有诊断,不能展示成功数值 |
名称来自当前节点的 label、声明说明、目标可读名,依次回退;没有业务描述时就显示“调用 print”,不得自动声称它是“验证知识”或“输出最终结论”。普通 print 在所属文档位置解释输出作用,放在“输出”类信息中,不作为高价值知识卡突出。
“步骤”列表只在当前知识详情中显示,标为“文档中的步骤”或“结构步骤”。静态序号不能暗示实际执行时序;实际轨迹另按运行事件呈现,分支和循环保留嵌套。
### 5.3 描述、实现与结果的三层关系
以 `**总价 = [计算订单小计](pricing.小计(数量, 单价))**` 为说明示意:
```text
计算订单小计 [说明]
总价 = pricing.小计(数量, 单价) ← 简短实现,次一级视觉
本次示例:数量 2,单价 30 → 60 ← 仅有匹配运行记录时出现
```
作者的上下文句、返回说明、单位和条件仍在原位。短公式/实现可次级显示,长 payload 默认折叠到详情;显式“展开实现”控制可对当前知识单元生效。不得把所有代码完全藏掉,使“代码即文档”退化成只有自然语言标签。
复制操作区分“复制说明”和“复制源码”;源码来自源 span,保留必要定界符、参数和 import 依赖提示。显示为漂亮文本的结果不能被复制成伪造的可执行代码。
### 5.4 表格、条件与关系
数据表按作者结构呈现,表头固定语义,单位与列说明常显;契约表按输入/返回/约束组织。显示层不能把 Marqdo 列向集合悄悄换成行向记录;需要另一种预览时明确标为预览,并能查看真实形状。
前提条件与失败分支不得因“简洁”隐藏。默认显示全部分支结构,所选运行只突出实际命中的分支,继续遵守 [调用帧与结构保真](view-frame-selection.md)。
跨文档关系默认用可读链接,例如“使用:标准税率 · tax.mq.md”,而非 `mq://…`。直接依赖与被引用者各列前几项并可展开;可选局部关系图放在详情层,不作为默认阅读画布。关系图必须有等价文字列表,并显示未知/动态关系,不能补画不存在的边。
## 6. 当前知识详情:回答问题,而非列出字段
### 6.1 内容顺序
```text
商品小计 函数
根据数量与单价计算商品金额。 ← 仅引用已有描述
输入 数量:整数;单价:金额 ← 类型/单位未知则明确未知
返回 金额
条件 数量非负 ← 仅当已声明且可定位
实现 数量 × 单价
来源 定价说明 / 第 2 节 [打开]
检查 契约未检查;测试未运行 [查看依据]
运行记录 示例 #2:2 × 30 → 60 [定位输出]
使用 … [查看定义]
▸ 技术详情:精确标识、完整签名、效应、摘要、诊断 JSON
```
此处“金额”“数量非负”等只用于解释布局,不宣称当前样例具有这些元数据。没有信息就省略非关键行或写“未声明”,不得推断成“无限制”“没有来源也可靠”。缺失影响可用性时常显;纯工具没有业务来源并不自动是错误。
### 6.2 当前字段的去向
| 当前字段 | 新的主要位置与文案 |
|---|---|
| Target / `mq://…` | 标题处可读定义链接;完整 ID 在技术详情,可复制 |
| Kind / callable | 标题旁简短类型词;module 信息进入文档技术信息 |
| Signature | 输入/返回紧凑表;完整规范签名可展开 |
| Effects | “涉及的操作”,说明文件读写、网络等;未知明确显示,非纯不等于失败 |
| Verification 长串 | 分项检查和证据表,见 §7 |
| Lock digest | 更名“制品摘要”,技术详情内显示;锁状态单独来自真实 lock report |
| Depends on | 可读目标列表,指向定义与引用位置;未分析不能写“无依赖” |
| Execution 固定句 | 匹配运行记录,或“尚无该知识的运行记录” |
| SourceRef / applicability | 当前遗漏的关键内容:放入“来源”和“适用条件” |
默认不铺完整 hash。技术详情可显示缩略摘要并提供全值/复制;缩略值不用于识别唯一性。没有读取锁报告时写“未检查锁定状态”,不能把拥有摘要显示成“已锁定”。
### 6.3 交互、跳转与返回
1. 点击正文的“说明”或目录知识项,选中同一 `node_id`;正文轻量高亮,右栏同步。键盘和触屏具有等价入口,不依赖 hover。
2. 跳转到定义时保留来源文件、锚点、滚动位置和所选运行;返回恢复阅读位置。
3. 文件、符号与语句不能只靠显示名称匹配。同名函数的详情显示所在文档和父结构。
4. 默认不自动抢焦点、不因滚动不停替换用户正在阅读的详情。滚动只更新目录当前位置;点击选择才改变详情。
5. 手机抽屉有标题、关闭、返回焦点和滚动管理;无 JS 时使用正文附近的原生 details 或页尾知识附注锚点。
6. 当前 URI 不在导出范围内时显示“定义未包含在此次导出”,提供可读路径和复制引用;禁止输出必然失效的 `mq://` 或 live `/file` 链接。
## 7. 状态设计:读者必须知道什么被证明了
### 7.1 分离三个状态来源
| 状态来源 | 可以说明 | 不能说明 |
|---|---|---|
| 编译/静态分析 | 结构解析、目标绑定、契约检查结果、已建模效应 | 程序已运行、答案正确、资料真实 |
| 运行记录 | 指定输入、环境、源码版本下的执行与输出 | 覆盖所有输入、测试通过、来源可信 |
| 证据/验证记录 | 哪个断言/测试/来源核验通过,何时失效 | 未执行或未核验的其它部分也可靠 |
顶部仅给紧凑事实,例如“静态分析完成 · 尚无运行记录”,或“有 1 项来源问题 · 查看”。普通 unknown/unchecked 不应制造全页红色警报;与当前结论直接相关的失败、过期、未解析必须就地提示且可定位。
### 7.2 分项文案映射
| 机器状态 | 阅读文案 |
|---|---|
| parse=passed | 文档结构可解析 |
| resolve=passed | 此项检查报告目标已解析;覆盖范围见详情 |
| contract=unchecked | 契约尚未检查 |
| execution=not_run | 尚无执行记录 |
| tests=unknown | 尚无测试记录 |
| evidence=sourced | 已关联来源,内容尚未核验 |
| evidence=unverified | 来源内容尚未核验;结合来源列表判断是否已关联 |
| missing_source / expired | 来源缺失 / 已过适用期 |
| domain=unreviewed | 尚无领域审阅记录 |
| effects=pure | 静态分析未发现已建模的外部操作;展开可看范围 |
| effects=unknown | 涉及的操作尚不能完全确定 |
| 无对应字段 | 未提供该项检查结果 |
分项取值不能自动升级成综合“可信”。只有宿主选定的政策实际给出聚合结论,才显示“满足 ×× 政策”,同时附政策名称、版本与证据;业务条件还须明确展示。
### 7.3 结果来源与失效
每个运行值绑定 `run_id + source_digest + node_id + call_id + loop/iteration` 中适用的字段,展示本次输入或简短上下文。无节点映射时只展示整次运行输出,不硬塞到某个函数旁边。
静态导出有快照时标“导出快照”,附生成时间/输入;读者切换调用帧是在看历史结果,不叫“重新计算”。源码、依赖或来源与记录不匹配时标“历史结果,版本已变化”,不继续用成功样式绑定到新正文。
正文里的字面量可以显示为“文档声明值”;解释器实际执行得到的值才叫“运行结果”。没有值、返回 None、stdout 为空、尚未运行、执行失败必须分开,不能统一成 `(no stdout)`。
### 7.4 空态与错误态
| 情况 | 处理 |
|---|---|
| 没有可识别知识单元 | 正常显示文档,不插空知识面板 |
| 语义分析失败 | 保留可读正文/源码,显示“知识关系暂不可用”及可定位诊断 |
| 局部未解析 | 仅对应片段显示问题,保留其它已知结果 |
| 无运行或 no-exec | 运行区说明原因,使用中性状态,无绿色运行成功标记 |
| 运行失败 | 错误摘要定位到源片段;日志在运行区,静态知识仍可读 |
| 证据过期/冲突 | 相关知识常显问题、来源与影响;不静默选择一个结论 |
| 分析被截断/超过扫描范围 | 显示范围和未覆盖项;“未发现”不能替代“没有” |
## 8. 视觉、密度与可访问性
### 8.1 排版与主题
正文建议 16–18px、行高约 1.65;辅助说明 13–14px、行高约 1.5;代码使用等宽字体,全文不因进入 notebook 主题缩为密集工具面板。主次依赖字号、间距和位置共同表达,不能仅靠颜色。
使用现有系统字体和主题机制,建立统一的 view tokens:正文/辅助文字、背景、细分隔、焦点、成功/警告/错误。知识组件只依赖 tokens,不硬编码黑色线条或白底。支持明暗主题,首次尊重系统/显式设置,不为这次改版再写第三套皮肤。
表格与长公式允许局部滚动;ID、路径在详情中可换行;主文无整页水平滚动。重要来源和适用条件不使用极浅灰隐藏。对比度验收目标:普通文字至少 4.5:1,大字和必要非文本边界至少 3:1;这些是实现验收目标,尚非本轮测量结果。
### 8.2 注释和连线
默认使用紧邻内容的短结果行或有标签的注释块,优先通过“同一节点名 + 明确位置”关联。长 L-leader 不再是默认必需元素;复杂节点可保留短连线,必须满足端点存在、在同一块内、不交叉、不覆盖文字。
当目标折叠、帧过滤、元素隐藏或几何测量失败时,不绘制连线。主题/字体/容器宽度变化后只重算当前可见块;采用可取消的局部布局更新,不全页不断测量。窄屏、打印、reduced-motion 下直接使用有编号的注释。截图中的孤立线条归入专门视觉回归场景。
### 8.3 键盘、屏幕阅读器与退化
- 目录用 nav,正文用 main/article,详情用有名字的 aside/section;标题层级连续。
- 展开按钮有 `aria-expanded/controls`;选中状态、失败和待验证都有文字,不依赖颜色或图标。
- 深链接滚动有 `scroll-margin-top`,聚焦目标不被固定工具条遮住;关闭详情后焦点回到触发点。
- 不使用只有鼠标悬停才能看到的来源、代码或错误。大表格有标题与表头关系,日志可复制。
- 无 JS 时正文、目录锚点、来源链接、原生 details 和静态结果仍工作;只失去实时联动与运行操作。
- 选择帧不隐藏源结构;隐藏实现也不能删除文档含义和必需条件。
## 9. 技术设计与数据契约
### 9.1 从预拼 HTML 改为可关联的展示模型
当前 `FileViewModel.knowledge_html` 是独立 HTML 字符串,难以与正文、trace、诊断同步。建议新增结构化 `KnowledgePresentation`,在 Rust 端形成同一份模型,由正文、目录、详情共同消费。兼容阶段可保留旧字段,但不让它继续成为唯一知识接口。
```text
ViewDocument
document_id, source_digest, semantic_generation, title, description
blocks[] 保真正文结构及 source span
outline[] 标题/知识单元父子关系
knowledge_nodes[] 对应 artifact/ref/step,不复制语义解释器
diagnostics[] 范围、严重性、可读说明、定位
execution_state 明确未运行/运行中/成功/失败/快照
run_records[] 与文档版本相匹配的证据
KnowledgeNode
node_id, artifact_id?, symbol_id?, ref_id?, step_id?
owner_id?, source_span, display_name, authored_description?
kind, signature?, payload?, dependencies[], provenance[]
applicability?, verification[], effects, coverage
execution_refs[]
```
这些字段为建议契约,未承诺当前 IR 已提供所有信息。语义事实来自 `SemanticProject`,文档叙述来自解析后的源结构,执行事实来自 capture;缺少关系时展示 unknown,不让 UI 用名称模糊匹配或调用模型编造。
### 9.2 数据流
```mermaid
flowchart LR
S[源文档与项目边界] --> P[解析与语义分析]
P --> B[正文块与结构]
P --> K[知识节点与诊断]
R[显式运行或匹配的历史快照] --> T[执行记录]
B --> V[统一展示模型]
K --> V
T --> V
V --> D[正文与就地说明]
V --> O[目录与当前知识]
V --> E[运行区域与技术详情]
```
知识模型不通过“render HTML → 再抓取文本”生成。页面分析失败不可用空字符串吞掉,应保留有状态的结果;部分成功与整体失败分开。
### 9.3 源位置、稳定身份与锚点
目前 step 跳转用 `#stmt-{line}`,函数用 `#fn-{line}`。一行多个表达式、正文段落合并、同名函数、源码插行都会使单纯行号不够。
新增内部节点锚点注册表,将文档块、函数、语义 step/ref 与真实 DOM id 映射;使用 artifact/node 身份和源 span 生成页内唯一 ID,不把未经编码的 URI 当 DOM id。当前编译器没有稳定 SyntaxNodeId 的地方,退化为“源码版本 + span”,明确跨版本不可保证稳定;不能只把行号哈希一下就宣称稳定身份。
兼容现有 `#structure`、`#fn-N`、`#stmt-N` 链接,保留别名或定位映射;所有生成链接都验目标存在。跨文件 href 复用 [html.rs 的 LinkMode/href_file](../../src/view/html.rs),静态导出保持相对路径;路径展示解码与 URL 安全编码分离。
### 9.4 分离分析与执行,修正 no-exec
将当前 `build_file_view` 拆成可组合路径(名称为建议):
1. `analyze_document`:读取、解析、语义检查、生成静态展示数据,不执行目标程序。
2. `capture_execution`:只有执行策略明确允许时调用 run/cell runtime,返回真实状态与源版本。
3. `assemble_view`:关联正文、语义和匹配的结果,生成同一个展示模型。
`--no-exec` 必须在第 2 步之前分支,不能先跑后清空;snapshot 模式使用匹配快照,不为了构造 UI 又运行一次。Live 现有自动执行兼容行为在首轮不静默改变,必须通过显式 execution policy 传入并如实标注;若后续将 live 默认改为阅读时不执行,作为独立 CLI 行为变更发布和迁移。点击详情、查看来源、展开关系等阅读操作绝不能触发执行。
知识详情不要求通过运行得出静态信息。实现参数预览/试跑时,使用既有受控执行路径,不因“pure”字样绕过宿主能力边界。本文不新增一套求值器或权限系统。
### 9.5 Live 更新一致性
当前 SSE 会替换 structure_html/bindings_html/trace_json,而知识面板来自另一次静态编译,容易新旧混用。建议更新包包含文档摘要、语义代、run_id 和变更节点;前端仅合并兼容版本的数据。
运行写回导致源码变化时,重新分析后一次更新相互关联的正文、目录、知识与运行映射。原选中节点仍存在则保留选择/焦点/滚动;已消失则明确提示,不能悄悄指向同名节点。旧请求返回晚于新请求时按版本丢弃,不覆盖较新阅读状态。
### 9.6 性能与导出体积
避免每个页面重复编译整个项目。一次静态导出共享同一项目语义结果,逐页投影;live 按项目源指纹、编译器版本、配置和适用性时钟缓存,读取使用一致的语义代。来源/有效期变化必须使相关状态失效,不能无限缓存 sourced。
正文服务端生成,不等待 JS 初始化或全部知识图完成才出现。默认只嵌入当前文档必要知识,深层依赖按需取;静态导出则包含保证离线可用的局部数据与明确范围。大量结果采用折叠/分页,但不能让屏幕阅读器和查找失去正文。
性能验收目标:100 个知识单元的本地选择/展开交互 p95 ≤100ms;1000 单元目录可搜索而不阻塞正文滚动;导出项目的语义编译次数不随页面数线性重复。记录硬件、样例和体积,目标未达时先优化数据重复和布局测量,不以截断关键来源达标。
## 10. 实施文件与兼容策略
| 位置 | 建议变更 |
|---|---|
| [src/view/render.rs](../../src/view/render.rs) | 提取知识展示模型;替换全量 dl 面板;关联步骤归属、友好名称与诊断 |
| [src/view/document.rs](../../src/view/document.rs) | 源块/知识节点映射、正文就地入口、层级标题、可复制原始 span |
| [src/view/html.rs](../../src/view/html.rs) | 正文优先布局、辅助栏、详情/目录交互、状态组件、统一 tokens;保留 LinkMode |
| [src/view/mod.rs](../../src/view/mod.rs) | 分离分析/执行、保留诊断、组装统一模型、项目分析缓存 |
| [src/view/output.rs](../../src/view/output.rs) | 提前应用 no-exec/snapshot 策略、共享项目分析、静态详情与相对跳转 |
| [src/view/annot.rs](../../src/view/annot.rs) | 运行标注与节点/帧/版本关联,减少重复输出;缺映射不伪绑定 |
| [src/view/debug_page.rs](../../src/view/debug_page.rs) | 仅回归检查共享组件;不把阅读布局强加给 debug |
| [tests/executable_knowledge.rs](../../tests/executable_knowledge.rs)、view 单测 | 从字符串存在升级到顺序、锚点、状态和执行边界断言 |
| 文档与 public 示例 | 更新旧 View 布局说明、截图和行为描述,区分历史默认与新设计 |
默认展示不要求作者补特殊 frontmatter;title/description、函数说明、契约和来源已有时直接受益。尚无信息的旧文档保真显示,并在详情中如实缺省。
与现有文档的关系:保留 [view-document-annotations](view-document-annotations.md) 的叙述主导和真实结果,修订“长 L-leader 为默认”;保留 [view-frame-selection](view-frame-selection.md) 的源码常显与帧隔离;[view-markup-surface](view-markup-surface.md) 的历史 Classic 例子需按当前默认语法同步,不能在新 UI 继续教授旧取元。外联/WASM 交互沿既有独立路线发展,不作为完成本次阅读改版的前置。
## 11. 分阶段交付
### V0:先纠正顺序、误导状态和执行边界
正文提前;完整知识报告收进明确的辅助入口,module/type 容器默认不铺卡;“Lock digest”改为准确的摘要标签;状态不再共用一个 ok。修复 no-exec 先执行问题,分析错误可见。暂不等待完整节点模型,就能显著改善截图场景。
V0 不算最终完成:仅把面板搬到后面/折叠,仍未解决正文与知识的关联。
### V1:完成阅读与结构理解的主闭环
统一展示模型、标题/目录层级、就地说明、当前知识详情、友好定义跳转与返回。完成函数、计算、来源、空态与基本运行结果的正负例;live/static 共用。
### V2:贯通运行、来源和跨文档关系
匹配运行实例与版本、调用/循环帧、来源定位/失效、局部依赖关系、SSE 原子更新。上游证据能力尚不完整的地方明确显示未知,不能以 UI 补出“验证通过”。
### V3:移动端、离线和规模验收
完成键盘/读屏、无 JS、打印、暗色/浅色、100/1000 单元性能、视觉回归与读者测试。发布前同步 public 示例与说明,保留旧锚点兼容。
## 12. 验收矩阵
### 12.1 必测文档
| 样例 | 必须验证 |
|---|---|
| 截图对应 Phase I 页 | 正文先出现;无 full URI/hash 瀑布;print 在所属正文解释;无孤立线条 |
| 纯叙述/少量 Markdown 页 | 阅读无知识空卡、无误导运行徽章 |
| 单个纯函数,无 main | 参数/返回与调用方式清楚,不因无入口标全文失败 |
| 订单定价、多文档 import | 小计/税率/总额归属和依赖可追踪;输入和结果可对应 |
| 带来源的事实与过期/缺失来源 | sourced 不显示已证实;问题在对应知识旁可见 |
| 同名函数、多次调用和循环分支 | 定义唯一;切换帧只改结果和高亮,不隐藏结构 |
| 空 payload、动态调用、未解析引用 | 待实现/动态/未解析准确可辨,不能展示虚构结果 |
| 一行多个链接、嵌套表达式、中英文/长路径 | span 对应、锚点唯一、文本不丢失、不水平溢出 |
| 运行失败、分析失败、快照过期 | 三种情况分开,仍能读到正文与具体诊断 |
| 外联单元、变量大表、长日志 | 单层主体与对应结果,不重复三份输出;局部滚动 |
### 12.2 自动化判据
1. DOM 中文档主体先于全量知识技术详情,标题来自既有元数据;短文没有隐藏正文的默认展开报告。
2. 每个知识/目录链接都能定位真实节点;一行多节点和同名跨模块不冲突;live/static 路径均有效。
3. 验证、运行、来源状态按固定真值表渲染;无证据时绝不输出综合已验证。
4. no-exec 用隔离目录的副作用计数测试证明没有执行;snapshot 不重跑;展开详情也不执行。
5. 帧选择和 SSE 更新保留正文结构、选中身份与焦点,拒绝过期结果包。
6. 明暗主题/320、390、1024、1440 宽度/200% 缩放下无遮挡、截断关键条件和整页横向溢出;孤立 leader 数为零。
7. 无 JS、file 静态打开、打印预览都保留正文、定义/来源导航和必要证据说明。
8. 输出中的作者内容、label、URI/属性与嵌入 JSON 按原上下文转义;资料中的 HTML/脚本不能因为新详情组件被直接执行。
字符串断言只能覆盖结构,不能替代浏览器布局验收;需截图基线和真实键盘交互测试。可复用现有测试基础,避免测试只镜像组件实现。
### 12.3 读者任务测试
建议用至少 5 位未参与实现的读者,分别完成三个任务,并与当前页面对照:
- 在 30 秒内说清文档目的并找到主要规则/函数。
- 在 60 秒内找到某个结果的输入、定义和原始来源。
- 正确区分“来源已关联但未核验”“本次运行成功”“未运行/历史结果”,不得误认为都已验证。
目标为至少 4/5 完成前两项,第三项无误导性判断;小样本仅作为可用性门槛,不声称统计显著。记录失败位置并修正信息架构,不能只问“是否好看”。
## 13. 完成定义与本次交付边界
完成的 view 应让读者先读懂文档,再自然看到其中的知识与执行结构;需要深入时能沿着一个具体片段追到实现、输入、结果和证据。全量技术字段仍可查,但不要求读者先理解编译器才能读文档。
本次只提交设计文档与索引,不修改渲染实现。实证包括用户截图、当前模板/渲染路径、静态 HTML 顺序检查和临时 no-exec 反例;布局尺寸、交互、性能和读者任务结果均为待实施的验收目标。
+261
View File
@@ -0,0 +1,261 @@
# 防警告疲劳:标签校验必须自带的「静默机制」
| | |
|---|---|
| 状态 | **Accepted**(机制基线:stale 是变更报告) |
| 日期 | 2026-10-22 |
| 触发 | 用户:`[]()` 每次报 warning 会导致烦躁与忽略,必须先有机制再开工 |
| 前置 | [label-freshness-and-repair.md](label-freshness-and-repair.md) |
| 结论 | stale **不是"扫描报告",而是"变更报告"**;默认零噪音,严格模式 opt-in |
> **§2 的 M5 已修订**:原文以 `git diff` 作为核心机制是错的——沙箱 `exec=false` 调不了 git、
> 浏览器 WASM 无进程能力、非 git 用户无从使用,而**最需要它的 agent 修复回路恰在这些环境里**。
> 现改为 **「前一状态」provider 分层**:`T0 引用一致性 + T1 会话内前后对照` 为核心(零依赖),
> `T2 外部历史源(git 等)` 与 `T3 台账` 为可选适配器。
> 见 [staleness-providers.md](staleness-providers.md)。本文其余结论(分级、聚合、去重、
> 可证伪、节流、三道闸、验收指标)不受影响。
---
## 0. 为什么标签检查比一般 lint 更容易被忽视
三个结构性原因:
| 原因 | 说明 |
|------|------|
| **高频** | 纯度之后标签密度会接近"每个取值/调用一处"(现有索引 506 处 + 循环 44 处是下限) |
| **主观** | 标签是自然语言,机器只能近似判断;报告天然带"可能"二字,说服力弱 |
| **持续** | 代码天天改,断言天天可能过期 → 报告是**常驻背景音**,不是一次性事件 |
**而当前基线是零噪音**:实测 `lib/` + `ext/ai/` 共 **59 个文件**跑 `marqdo check`,
**warning = 0、error = 0**
(契约检查只在真错时报 error)。也就是说:
> 标签校验会成为这个项目**第一个持续的警告源**。
> 第一次引入就必须做对——一旦用户学会忽略,再想收回就晚了。
---
## 1. 疲劳的真正根因
不是"报得多",也不是"偶尔报错",而是:
> **同一件已知的事,被反复告知。**
心理学上这叫 habituation:信号无新信息 → 大脑过滤 → 真警报也被过滤。
所以设计目标不是"少报",而是三条更硬的:
1. **没有新信息就不说话**(变化驱动,而非扫描驱动)
2. **说了就必须能做点什么**(可执行、有定位、有建议)
3. **说过的就不再重复**(确认即静默)
---
## 2. 六个候选机制与评估
### M1 分级(hint / warning / error)
按**证据强度**分级,而不是按"我觉得重要":
| 级别 | 判据 | 人类可见 | 影响退出码 |
|------|------|---------|-----------|
| **error** | 能证明断裂:引用了不存在的实体、空标签 `label.missing` | ✅ | ✅ |
| **warning** | 能证明变化,但无法判断谁错(L2 指纹漂移) | ✅(默认聚合) | ❌ |
| **hint** | 弱信号:标签提到的实体仍在,但不在当前语句 | ❌(仅 JSON / view / labels) | ❌ |
**关键**:默认级别取 **hint**,只有项目显式升档才进人类可见输出。
这让"默认安静"成为语言行为,而不是团队纪律。
### M2 聚合(一条汇总,细节下沉)
`check` 的人类输出**最多一行**:
```
contract check OK(另有 3 条标签提示,见 marqdo labels status --json)
```
细节走 `--json`(机器)、`view`(徽章)、`labels`(逐条复核)。
理由:`check` 是 CI 工具,人很少逐条读;真正的阅读界面是 `view` 与编辑器。
### M3 基线(bootstrap 静默吸收)
全量扫描第一次跑时**只写台账、不报告**,把存量债务吸收掉。
适用:从旧语法迁移到纯度之后的第一次。
### M4 确认即静默(ack)
对某个「标签 + `()` 指纹」组合确认后,记录 `confirmed` → 同样的组合不再报。
这是最直接的对症药:**说过的就不再说**。
### M5 结构化 diff(**已修订:降级为可选 provider T2**,见 [staleness-providers.md](staleness-providers.md))
> **stale 只在"`()` 变了、`[]` 没变"时报,且只针对本次变更集。**
三种实现层次:
| 层次 | 做法 | 状态 | 噪音 |
|------|------|------|------|
| M5a | 工作区 vs `HEAD`:解析两版本文本,比较同一标签的 `()` AST 指纹 | **零状态** | 无变更即零 |
| M5b | 工作区 vs 「标签文本最后一次被修改的提交」(`git blame` 定位) | 零状态 | 更精确,但依赖 blame 语义 |
| M5c | 台账比对(上一份文档的 L2) | 需台账 | 中(首次需 bootstrap) |
**M5a 的性质非常关键**:
- **零台账**:git 就是台账,不需要新文件、不会合并冲突
- **零基线**:不需要 bootstrap,第一次跑就安静(因为没变更)
- **零重复**:提交之后 diff 清空 → 报告自动消失(除非再次改到同一处)
- **天生带 before/after**:报告直接给旧代码与新代码,正好是 LLM 复核需要的输入
- **格式化免疫**:比较的是 AST 指纹,不是文本
**边界**:不在 git 仓库 / 无 git 时,M5 自动降级为「只做 L1 引用一致性」(仍然确定性、零噪音)。
### M6 文档内抑制(`[描述](…) # noqa`)—— **否决**
理由:
1. **污染文档**:`noqa` 是机器垃圾,与"文档即散文"直接冲突
2. **不可审计**:抑制理由丢失,后来者不知道当初为什么不查
3. **永久化**:抑制会累积,最终整个文件静音
**替代**:抑制放**台账/配置**(可审计、可过期、可统计),不进文档。
---
## 3. 推荐组合:默认零噪音 + 严格模式 opt-in
### 3.1 默认(所有项目)
| 规则 | 效果 |
|------|------|
| stale 只在 M5a(结构化 diff)时报 | 无变更 → 完全静默 |
| 默认级别 hint | 不进 `check` 人类输出;仅 JSON / view |
| `check` 最多一行聚合 | CI 日志干净 |
| 每条提示必须带:定位、`doc_quote`、`code_past`/`code_now`、一句可执行建议 | 可行动 |
| 同一标签在未处理前只报一次(按变更集去重) | 不重复 |
| 非 git 环境降级为 L1 | 仍然安静 |
### 3.2 严格模式(知识库仓,opt-in)
在默认之上加:
| 规则 | 效果 |
|------|------|
| stale 升为 **warning** 或 **error** | 可作 CI gate |
| 启用 M3 基线 + M4 确认台账 | 存量债务可管理 |
| **棘轮(ratchet)**:允许债务存在,但**禁止增加** | 只拦新增,不清旧账 |
| `labels status` 进 CI 报告 | 债务可见 |
**棘轮**是我认为最值得抄的机制:`baseline.json` 记 `{"stale": 12}`,
`labels check` 只在 **数量增加** 时失败。这样:
- 老债不阻塞任何人
- 新债立刻被拦
- 债务数字可下降,团队有正反馈
---
## 4. 「确认」的三种语义
M4 需要一个"确认"动作,三种可选:
| 语义 | 操作 | 优 | 劣 |
|------|------|----|----|
| **改标签** | 编辑 `[]` 文本 | 留下真实痕迹,最诚实 | 有时标签确实无需改 |
| **改代码** | 恢复 `()` 的行为 | 守住原意图 | 有时代码才是对的 |
| **显式确认** | `marqdo labels confirm <标签>`,台账记新指纹 | 最省事 | 易被当成"消除警告按钮" |
**设计建议**:三者都提供,但**显式确认要留痕**——
台账记录 `confirmed_at` 与 `confirmed_by`(人或模型),
`labels status` 能显示"这条被确认过几次"。
**被反复确认的标签,本身就是坏味道**(说明描述与实现长期脱节),值得在状态里暴露。
---
## 5. 可证伪原则:写得越具体,越接受检查
这条是从根上减少噪音的机制:
> **只有能被证伪的断言才被检查。**
- 标签含 `` `实体` `` 反引号 → 可证伪 → 参与 L1
- 标签是纯口语("按档位折算")→ 不可证伪 → **L1 完全不检查**
于是**检查成本由作者的书写具体程度决定**:
写具体的作者获得更强的保鲜保证,也接受更多检查;
写笼统的作者不被检查(但也得不到保护)。
这不是漏洞,而是诚实的对齐:**机器只能校验它看得懂的断言。**
同时它反向抑制了"为凑数而写废话"——废话没人查,也就没有价值。
---
## 6. agent 侧节流:只问它自己刚改的
智能体是主要编辑者,最容易被警告淹没。规则:
| 场景 | 行为 |
|------|------|
| 一次 `repair_apply` 改了 `()` | 只对**它改到的**那些标签做 stale 检查,最多 N 条(如 5) |
| 未触碰的标签 | 一条都不报 |
| 同一修复轮内 | 只报一次,不随每次编辑重报 |
| 超过 N 条 | 只报前 N 条 + 汇总("另有 K 条") |
这样模型每轮的输入里最多几条相关提示,且都带 before/after——
**它看到的是"你刚改的这处,描述可能不再成立",而不是"全仓库有 200 处过期"**。
---
## 7. 防"用忽视解决"的三道闸
即使有静默机制,用户仍可能整体忽略。三道闸让它**不可能"无声地"忽略**:
1. **债务可见**:`labels status` 输出「12 条待复核 / 共 412 条标签」。
数字不报警,但每次问就给——忽略变成**有意识的选择**而非无意识。
2. **可 gate**:知识库仓把 stale 设为 error,CI 红。
3. **可审计的抑制**:抑制只存在于台账,`labels audit` 能列出所有抑制及其年龄。
超过 N 天未复核的抑制 → 提示"这条抑制过期了"。
---
## 8. 与现有设施的对接
| 现有 | 复用方式 |
|------|---------|
| `marqdo check` | 增加**一行**聚合;细节不给 |
| `--json` 诊断输出 | hint 走这里,机器可读 |
| MLSP `validate` | 默认不含 hint,可传 `labels: "strict"` 打开 |
| MLSP `repair_targets` / `repair_apply` | ranges = 标签行 ∪ 代码行(已有能力) |
| `marqdo view` | 标签徽章(新鲜 / 待复核);点击跳到标签与代码 |
| `marqdo verify` / `stale` | 复用已有的知识 stale 通道,进健康报告 |
| 新增 `marqdo labels` | `status` / `review` / `confirm` / `audit` 四个子命令 |
---
## 9. 验收指标(可量化,写进文档以免日后走样)
上线前必须满足:
| 指标 | 目标 |
|------|------|
| **默认静默率** | 无代码变更时,`check` 输出中标签相关行 = **0** |
| **报告密度** | 单次变更集中标签提示 ≤ **3 条**,或 ≤ 变更涉及标签数的 **20%** |
| **重复率** | 同一标签在未修改前重复提示 = **0** |
| **可行动率** | 每条提示带定位 + before/after + 建议 = **100%** |
| **误报率** | 人工抽检 50 条,误报 ≤ **10%** |
| **默认可见性** | `check` 人类输出最多 **1 行**;逐条只在 JSON / view / labels |
| **退出码** | hint / warning **不影响**退出码 |
---
## 10. 待你决策
1. **核心机制选 M5a(结构化 diff,零状态)吗?**
我强烈建议选它——它把"疲劳"从设计问题降级为几乎不存在,且不需要台账。
2. **默认级别**:hint(我建议)还是 warning?
3. **严格模式的棘轮**(禁止新增、允许存量)要不要一并做?我建议要,成本很低。
4. **显式确认要不要留痕**(`confirmed_by` / 次数)?我建议要——反复确认的标签本身就是坏味道。
5. **`check` 的聚合行**要不要固定出现("标签 0 待复核"也算信息)?
我建议**不出现**:零噪音优先,`labels status` 才回答这个问题。
> 定了这五条,我就可以按 P1(L1 + 诊断 + MLSP 往返)开工——
> 因为 P1 只做"能证明断裂"的 error 与 hint,且天然走 M5 的变更口径,
> 不会在第一天就制造出 506 条警告。
+163
View File
@@ -0,0 +1,163 @@
# Web 热路径:单解释器串行化(设计缺陷说明)
| | |
|---|---|
| 状态 | **Accepted**(缺陷记录 + 缓解已落地) |
| 日期 | 2026-10-26 |
| 规范决策 | [ADR 0008](../adr/0008-web-invoke-serialization.md) |
| 相关 | [ext-web-go-rewrite.md](ext-web-go-rewrite.md) · [ext-abi.md](ext-abi.md) · [ADR 0004](../adr/0004-web-plugin-go.md) · [ADR 0007](../adr/0007-web-document-endpoint.md) |
本文把「页面卡死 / 像单线程」拆成可验证的架构事实、错误语义与演进边界。
**结论先行:HTTP 是多线程的;卡住是因为所有 Endpoint 共享一把解释器锁。**
增量实施提案见 [隔离执行与响应式 Web 运行时(2026-10-26)](isolated-web-runtime-development-2026-10-26.md):独立进程池、控制/读取容量、请求级事件与取消、缓存和恢复。提案通过验收前,本文件及 ADR 0008 的现行单飞约束不变。
---
## 1. 问题陈述
### 1.1 用户可见症状
1. 发起一次长对话(OpenAI 兼容 `POST …/v1/chat/completions` + `stream:true` / `sse-live`)。
2. 对话尚未结束时,打开设置、拉 `/v1/models`、或其它短 JSON API。
3. **旧行为**:浏览器请求一直 pending,整页像死机;只能杀 `marqdo run serve…` 恢复。
4. **目标行为**:短请求在约 1.5s 内得到 **HTTP 503**,错误体标明 `interpreter busy`;对话 SSE 继续;结束后短请求立刻恢复 200。
### 1.2 错误归因(不要再说错)
| 错误说法 | 正确说法 |
|----------|----------|
| 「web 插件是单线程的」 | Go `net/http` 与 SSE 刷写是多 goroutine |
| 「忘记启动进程所以卡死」 | 进程在跑;是 **锁争用** 导致短请求永不返回 |
| 「把 SSE 的等待时间调大就能修好」 | 进程级拉长 `MARQDO_INVOKE_WAIT_MS` 会让短请求一起卡死 |
| 「去掉 INVOKE_LOCK 即可并行」 | `HostContext` 非 Sync,无锁并行会数据竞争 / 未定义行为 |
---
## 2. 调用栈与锁边界
```
Browser
│ GET /v1/models POST /v1/chat/completions (SSE)
▼
Go plugins/web (多 goroutine)
handleInvoke / handleInvokeLiveSSE
│
▼ C ABI host_query("call_lib_path", {path, args})
Rust src/host/plugin.rs
┌─────────────────────────────┐
│ INVOKE_LOCK (进程级 Mutex) │ ← 同一时刻只允许一个 worker 进入
└─────────────────────────────┘
│
▼
HostContext:装载/求值作者 .mq.md、写回、事件总线、LLM 插件回调…
```
要点:
1. **锁在宿主,不在 Go 业务路由表。** 增加更多 Go handler 不会自动并行执行 Marqdo。
2. **SSE 持锁时间 ≈ 整次 Endpoint 求值时间**(含多次 LLM 往返),可达数十秒到数分钟。
3. **事件转发**(`MARQDO_EVENT_FORWARD` NDJSON)与 **取消**(`MARQDO_CANCEL_TOKEN`)在持锁期间仍可由其它 goroutine 写文件/读桥;它们不进入解释器,故不受 `INVOKE_LOCK` 保护,也不应误设长等待。
---
## 3. 为何不能简单「多线程跑 Marqdo」
`HostContext` 持有(非穷尽):
- 当前模块图、函数表、写回缓冲与 FS 根;
- 插件注册与 `CURRENT_HOST` / 全局 host 指针;
- Agent / LLM 运行时与 stream 发布钩子;
- 与文档写回、会话态相关的可变结构。
这些状态在实现上按**单线程求值**建模。把它标成 `Sync` 或去掉 `INVOKE_LOCK` 而没有隔离运行时,属于未定义行为,不是性能优化。
**真并行的合法方向(未实现):**
1. **解释器池**:每请求或每会话一个 `HostContext`(或可重置的 isolate),路由层选闲置实例;
2. **只读快照 + 写队列**:热路径只读克隆,写回串行合并(适合纯查询 Endpoint,不适合带写回的 agent);
3. **把长任务移出解释器**:Marqdo 只做编排,重活在独立进程/队列(与「代码即文档」主路径权衡后再定)。
在上述任一方案落地并经金样例验收前,**产品必须以「单飞解释器」为约束设计 UX**。
---
## 4. 缓解契约(已实现)
### 4.1 宿主:限时争锁
文件:`src/host/plugin.rs`
- 仅当从 worker 线程进入(`CURRENT_HOST` 为空、走全局 host)时争 `INVOKE_LOCK`。
- `acquire_invoke_lock`:`try_lock` 循环,预算默认 **1500ms**(`MARQDO_INVOKE_WAIT_MS`,最小 1)。
- 超时:`set_err("interpreter busy: another request holds the Marqdo invoke lock (waited …ms)")`,返回非 0。
- **不要**在 SSE 入口把该环境变量设成数分钟:它是进程级的,会污染并发短请求。
### 4.2 Web 插件:503
文件:`plugins/web/internal/httpx/routes_invoke.go`
- 普通 JSON invoke:错误信息含 `interpreter busy` → **503** + `Retry-After: 2` + `{ok:false, error:…}`。
- Live SSE:若启动时即 busy,以失败事件/错误结束该流,**不得**无限挂起握手。
### 4.3 客户端:超时与文案
短 API(模型列表、设置、registry 探测等)必须:
- 设置合理 `fetch` 超时(秒级,例如 8s);
- 将 503 / `interpreter busy` 展示为「服务正忙(对话进行中)」类可读提示,而不是空白转圈。
(qdagent 前端 `frontend/src/lib/api.ts` 已按此契约处理。)
### 4.4 验收探针
在本地 serve 上:
```bash
# 终端 A:启动长 SSE 对话(持锁)
curl -N -m 120 -H 'Authorization: Bearer …' -H 'Content-Type: application/json' \
-d '{"stream":true,…}' http://127.0.0.1:PORT/v1/chat/completions
# 终端 B:对话进行中
curl -sS -w 'http=%{http_code} time=%{time_total}\n' --max-time 5 \
-H 'Authorization: Bearer …' http://127.0.0.1:PORT/v1/models
# 期望:http=503,time≈1.5,body 含 interpreter busy
# 对话结束后再打同一 URL → http=200,time≪1s
```
---
## 5. 运维与调参
| 变量 | 默认 | 含义 |
|------|------|------|
| `MARQDO_INVOKE_WAIT_MS` | `1500` | worker 进入解释器前最长等待;超时 → busy |
建议:
- 开发机 / 产品默认保持 1–3s。
- **禁止**为「让第二个聊天排队」而把默认调到分钟级——那等于恢复卡死。
- 需要排队时,应在 **应用层**(会话队列、UI 禁用「再发一条」),而不是拉长宿主锁等待。
---
## 6. 与其它机制的边界
| 机制 | 与 INVOKE_LOCK 的关系 |
|------|----------------------|
| `MARQDO_EVENT_FORWARD` | SSE 期间写 NDJSON;不替代争锁;不延长等待 |
| `MARQDO_CANCEL_TOKEN` | 断开连接时可取消 LLM;释放锁仍取决于解释器何时回到 FFI |
| `web.serve` / 静态资源 | 通常不经 `call_lib_path`,不受本锁影响 |
| 插件内部 Tokio/Go 并发 | 可以;只要不再次 `call_lib_path` 进同一 HostContext |
---
## 7. 演进检查清单(根治前勿宣称「已支持并行 Endpoint」)
- [ ] 多 `HostContext` 或 isolate 的生命周期与 ABI(装载、shutdown、写回冲突)有设计稿与金样例。
- [ ] 池化后 `call_lib_path` 不再依赖进程级单锁,或锁粒度降到实例级。
- [ ] 两个并发长 SSE + 一个短 `/v1/models` 的压力测试:短请求稳定 200,长请求互不污染会话写回。
- [ ] 更新本文件与 ADR 0008 Status(例如改为 Superseded by ADR NNNN)。
在清单完成前,对外与文档中应明确:**Marqdo Web Endpoint 求值在单进程内串行;HTTP 层并发,解释器层单飞。**
+26 -1
View File
@@ -13,6 +13,8 @@
|------|------|------|
| Rust + Cargo | stable,建议 ≥ 1.81(本机验证过 1.81) | `rustc --version` / `cargo --version` |
| Git | 任意近期版本 | `git --version` |
| GCC / Binutils | 原生依赖编译与链接 | `cc --version` / `ld --version` |
| Go | ≥ 1.22(仅构建 `plugins/web` 与 web 扩展测试需要) | `go version` |
安装 Rust(若尚未安装):
@@ -21,7 +23,17 @@
本仓库可选 `rust-toolchain.toml`(钉 1.81.0)。若本机无 `rustup`、但已有匹配的 `rustc`/`cargo`,也可直接开发。
**不需要:** Flex、Bison、LLVM、Node/npm(实现栈为 Rust)。
**不需要:** Flex、Bison、LLVM。Node/npm 只在开发 VS Code 扩展时需要;核心 Rust 开发不依赖它们。
本仓库提供了固定 Rust 版本:`rust-toolchain.toml` 使用 Rust 1.81.0,并启用
`rustfmt` / `clippy`。在受限开发容器中,推荐先加载仓库环境脚本:
```bash
source scripts/dev-env.sh
```
脚本会优先使用 `target/toolchain/` 下的工具链,普通开发机则回退到 PATH 中已有的工具,
并把 Cargo、Go 缓存和临时目录放在工作区内。
---
@@ -36,6 +48,12 @@ cargo test
cargo run -- run tests/structure/hello.mq.md
```
构建 Go web 插件(完整扩展开发需要):
```bash
bash scripts/build-web-plugin.sh
```
当前 M0:`run` 会读入文件并明确报错「evaluation not implemented」(脚手架,非静默假成功)。
> 若 `cargo build` 报 `edition2024` / 过新 crate:仓库已对 `clap` 等做兼容钉扎(见 `Cargo.toml`);请使用附带的 `Cargo.lock`,勿盲目 `cargo update` 到最新 major。
@@ -50,6 +68,13 @@ cargo fmt
cargo clippy --all-targets
```
只验证 Rust 核心时可运行 `cargo test --locked --lib`;包含全部扩展的 gold 测试需要 Go,
并建议单线程运行以避免共享临时夹具互相影响:
```bash
cargo test --locked --test gold -- --test-threads=1
```
代理下拉 crate(可选,与 git 推送类似):
```bash
+576
View File
@@ -0,0 +1,576 @@
# Marqdo 的 `[]()`:从可读语法走向可验证的知识引用
我重新读取了仓库当前 `main` 分支(提交 `1a139892`)的 README、链接语法设计、知识分层设计,以及仓库中针对现有实现的复核报告。
这次我认为应当调整之前对 Marqdo 的评价:你提出的 `[]()` 不只是改善语法外观,它确实有机会成为 Marqdo 从“可执行文档”走向“可复用知识系统”的关键入口。
但当前设计有一个尚未解决的根本问题:
它已经尝试统一“可读描述”和“可执行表达式”,却还没有真正统一“知识的身份、知识的含义、知识的实现、知识的证据,以及知识的版本”。
仅仅让链接能解析到一个函数,并不能保证 AI 没有用错知识。仅仅让函数有一个确定的编译结果,也不能保证这个结果所表达的知识是真的。
这恰恰可能是你不断修改设计,却始终没有得到预期效果的原因。
## 一、先区分仓库已经实现了什么
当前 README 标明的是 v2.0.0,`doc/design/link-syntax.md` 将跨文档类函数调用列为 v2.1 目标。
| 能力 | 仓库当前状态 |
| ---------------- | ---------------------------- |
| `[描述](表达式)` 本地遮蔽 | 已实现,主要通过 `markup: occlusion` |
| `()` 中表达式求值 | 已实现 |
| 用自然语言描述隐藏复杂代码 | 已实现基础能力 |
| `类.函数` 直接调用 | 设计目标,尚未按文档实现 |
| 跨文档自动解析知识目标 | 设计目标 |
| 编译器生成 LinkInfo | 设计目标 |
| 链接进入 EKC 知识图 | 设计目标 |
| 版本指纹和链接锁定 | 设计目标 |
仓库还有一份很重要的复核报告:[occlusion-vs-executable-knowledge-2026-10.md](https://github.com/cflmy/marqdo/blob/main/doc/research/occlusion-vs-executable-knowledge-2026-10.md?utm_source=chatgpt.com)。
它针对 v2.0.0 测试了一个典型案例:在一个文档里定义“李白的出生年份”,再由另一个文档通过链接读取。结果发现,正文链接没有进入执行 AST,跨文档类名没有得到解析,类函数不能直接调用,而且原始知识函数也没有实际返回值。
这份报告说明:问题不是 `[]()` 的形式不够优美,而是链接背后的知识语义基础尚未建成。
这也解释了为什么你已经设计了链接语法,却还没有获得想象中的知识复用能力。
## 二、我建议保留你的两个目标,但增加第三个目标
目标一 · Presentation
自然语言呈现
用 `[]` 给复杂、不适合人类直接阅读的可执行表达式一个清楚的描述。
目标二 · Executable Reference
确定性知识引用
让 `()` 可以绑定已经编译、可解析、可验证的知识单元,而不仅是临时拼出的表达式。
目标三 · Knowledge Integrity
知识一致性保障
当知识定义、实现、版本、证据或适用条件变化时,能检测引用是否仍然有效,阻止 AI 把“能够运行”误认为“知识正确”。
第三个目标不是另加一种语法,而是让前两个目标真正成立所必须的编译器能力。
我倾向于把它称为 Verified Knowledge Reference(可验证知识引用)。
## 三、关键转变:不要把“函数”直接等同于“知识”
目前 [link-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/link-syntax.md?utm_source=chatgpt.com) 的核心设计是:
```
[label](expr) ≡ expr
```
它规定标签不改变计算语义,链接只为表达式增加人类描述和编译器元数据。
这个规则作为表达式语义是合理的,但作为完整知识模型还不够。
原因在于,至少有三种不同的东西可能进入 `()`:
| 内容 | 例子 | 实质 |
| ---- | ---------------------------- | --------------- |
| 表达式 | `[税额](amount * rate)` | 一次计算 |
| 函数 | `[计算税额](Tax.calculate(100))` | 一种计算能力的调用 |
| 知识事实 | `[适用税率](TaxPolicy.rate)` | 一项具有来源、范围、版本的知识 |
第三种不能只靠前两种来解释。
例如,编译器能确定 `TaxPolicy.rate` 返回 `0.10`,只能证明“目标被正确解析并返回该值”,不能证明“2026 年某个地区、某种业务适用的税率确实是 10%”。
确定性执行和知识真实性是两个独立维度。
我建议把 Marqdo 的知识模型扩展为以下结构:
Markdown 文档
自然语言叙述、表格、函数与知识定义
Semantic Artifact · 语义制品
稳定身份、类型、签名、实现、契约、依赖、证据
Verified Knowledge Reference
解析引用、检查约束、固定版本、判定可否复用
解释执行
知识检索
AI 复用
这里最重要的新概念不是链接,而是 Semantic Artifact(语义制品)。
它应当是 Marqdo 编译器第一次真正统一代码、文档与知识的中间产物。
### 一个语义制品应该包含什么?
建议最小模型如下。这里是我的架构提案,不是当前仓库已经实现的格式。
```
{
"id": "knowledge://project/TaxPolicy/rate",
"kind": "fact",
"signature": {
"params": [],
"returns": "number"
},
"implementation": {
"ir": "compiled-reference",
"digest": "sha256:..."
},
"contract": {
"unit": "ratio",
"scope": "example-policy",
"effects": "pure"
},
"provenance": {
"source": "policy.md#rate",
"digest": "sha256:..."
},
"verification": {
"status": "verified",
"methods": ["source-check", "contract-test"]
}
}
```
其中 `id` 是符号身份,`implementation.digest` 是编译内容指纹,`provenance` 是来源证据,`verification` 是验证记录。
这样一来,AI 复用的对象就不再是“某个名字看起来正确的函数”,而是一个具有明确身份和约束的知识制品。
需要注意:这里的 `verified` 只能表示通过了所声明的验证方法,不能凭此宣称该知识在所有现实情境下都正确。
## 四、重新定义 `[]()`:统一写法,不强行统一所有行为
我建议继续保持你所追求的语法纯度:
```
[人类可读的描述](机器可解析的目标)
```
不引入额外的 `knowledge:`、`call:` 或 `ref:` 前缀,也不让 AI 记忆复杂的新标记。
但编译器必须区分目标的性质,而不是把一切都当作普通表达式立即求值。
A · 表达式遮蔽
计算
```
**total = [应付总额](price * quantity + shipping)**
```
对原有表达式的透明包装。编译后仍是普通表达式,描述不改变值。
B · 能力引用
复用
```
**total = [计算应付总额](Pricing.total(订单))**
```
解析到已编译函数,检查参数、类型、依赖、权限和版本,然后调用。
C · 知识事实引用
知识
```
用户可以查阅[李白的出生年份](李白.出生年份)。
```
解析到知识制品;view 展示事实、来源和验证状态。正文保持惰性,不自动产生副作用。
这种设计保留了 `[label](expr) ≡ expr` 的计算规则,但增加了一个重要条件:编译器首先要解析 `expr` 的目标类型,然后才能决定它应该怎样验证、绑定和使用。
这不会使语言多出三套语法,反而能够避免当前设计中“语法统一了,但知识语义仍然散落在工具中”的问题。
## 五、你的第二个目标,最关键的是“绑定”而不是“调用”
假设有这样一份知识文档:
```
# 李白
## 出生年份
| 返回 | 类型 | 来源 |
|---|---|---|
| 701 | number | corpus/libai.md#birth |
*701*
```
另一个文档写:
```
李白的[出生年份](李白.出生年份)是 701 年。
```
理想情况下,编译器应该执行一条确定性的处理链:
Resolve — 查找 `李白.出生年份` 指向哪个知识单元
Bind — 绑定稳定 Symbol ID,而不是仅保存字符串
Validate — 检查返回类型、来源、契约与依赖
Pin — 根据需要固定知识版本和内容指纹
Evaluate — 仅在允许执行的上下文中求值
Trace — 将引用关系、验证结果与来源写入知识图
此时,编译器内部的引用不应该只是:
```
"李白.出生年份"
```
而应该更接近:
```
KnowledgeRef {
target_symbol_id,
resolved_artifact_id,
expected_signature,
pinned_digest,
verification_policy,
source_span
}
```
其中的 `target_symbol_id` 解决“引用谁”,`pinned_digest` 解决“引用哪个版本”,`verification_policy` 解决“什么时候可以信任它”。
这才是让 AI 不必重新生成已有知识,而是能够确定性地调用已有知识的技术基础。
还有一个必须考虑的问题:如果编译器只记录函数源码哈希,而函数内部调用的其他知识已经发生变化,那么源码没有变,实际执行语义也可能已经变化。因此,至少要对调用依赖形成可追踪的版本关系;对需要严格复现的纯函数,还应生成包含传递依赖的制品指纹。对于网络请求、时间、随机数等外部效应,则必须记录环境和执行条件,不能简单承诺重放一定得到相同结果。
## 六、仓库当前设计里,我最想修改的三个地方
### 1. 不要继续把类当作所有知识的唯一载体
[knowledge-layers.md](https://github.com/cflmy/marqdo/blob/main/doc/design/knowledge-layers.md?utm_source=chatgpt.com) 提出用 `# 李白 = > 诗人` 表示知识个体,也就是“单体知识类”。
这可以作为兼容实现路径,但我不建议把它提升为最终的知识本体。
因为“李白是诗人的一个个体”与“李白是诗人的子类”并不相同。让每一个事实实体都成为一个类,可能在知识库规模扩大后引入继承关系和个体关系的混淆。
更理想的是:让编译器内部明确区分 `Type`、`Entity`、`Fact`、`Function`、`Capability` 等制品类型。Markdown 源码可以继续使用现有的标题、表格和 frontmatter 承载这些信息,不要求立即增加新语法。
### 2. 不要让 `check` 与 EKC 各自维护一套知识理解
目前 EKC 已经有 Symbol、Capability、Knowledge、Graph 和 REUSE→ADAPT→CREATE 等概念。参见 [engineering-knowledge.md](https://github.com/cflmy/marqdo/blob/main/doc/design/engineering-knowledge.md?utm_source=chatgpt.com)。
这里完全没有必要再为 `[]()` 平行开发另一套知识注册表。
我建议把架构整理成:
- 编译器负责产出统一 Semantic IR、符号信息和引用关系;
- `check` 消费这些信息进行验证;
- EKC 将它们投影成知识图和上下文包;
- `view` 消费同一份信息展示可读知识;
- Agent 使用同一份引用解析接口,而不是重新理解 `.mq.md` 文本。
如此一来,编译器就是事实上的知识系统基础,EKC 不再承担第二次解释源码的职责。
### 3. 不要认为“描述过期”和“知识过期”是一回事
仓库中的 [occlusion-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/occlusion-syntax.md?utm_source=chatgpt.com) 已经意识到遮蔽会产生信任负债,并设计了标签引用一致性和新鲜度检查。这是有价值的方向。
但是,三类变化必须区分:
| 变化 | 应该检查什么 |
| ------------- | -------------- |
| 实现变了,描述没变 | 描述是否仍与行为一致 |
| 知识来源变了,函数没变 | 知识事实是否仍然有证据支持 |
| 引用目标变了,代码还能运行 | 是否仍满足原始契约和版本要求 |
尤其是第三种:AI 幻觉可能表现为调用了一个真实存在、类型也正确、但是业务含义完全错误的函数。
纯粹的符号解析和类型检查抓不住这种错误。因此,需要让能力契约、适用范围和知识来源成为可检查的制品属性,而不是只依赖 `[]` 中的自然语言。
## 七、建议的实施顺序
不要一次性实现完整知识图谱、版本锁定、自动修复和复杂本体系统。我建议分成四个阶段,每一阶段都必须有独立的可执行验收。
| 阶段 | 核心交付 | 必须通过的测试 |
| ------------ | ------------------------------------- | ---------------------------------- |
| P0 · 统一引用语义 | `[]()` 的统一 AST、目标类型识别、正文/代码上下文区分 | 不再因 Classic/Occlusion 模式造成静默错义 |
| P1 · 稳定寻址 | 项目符号索引、类函数解析、稳定 Symbol ID、静态 LinkInfo | 两文档李白示例无需实例化即可完成解析与引用 |
| P2 · 可验证知识制品 | Semantic Artifact、契约、来源、指纹、统一诊断 | 删除目标、修改签名、改变来源,均得到准确诊断 |
| P3 · 确定性复用 | 依赖图、制品锁定、EKC 集成、Agent 引用优先策略 | AI 不重新生成已存在的能力;错误、过期和不适用的知识被阻止直接复用 |
我特别建议设置一个不依赖 LLM 的核心验收实验:
准备 100 个知识单元,包含同名符号、跨文档引用、版本变更、类型不匹配、来源缺失、循环依赖和正常复用。由程序自动生成和验证预期结果。
先证明编译器能够正确识别、绑定和诊断这些情况,再引入 AI 测试上下文成本和幻觉率。否则很容易把模型能力、索引召回率与编译器的正确性混在一起。
## 八、重新评价 Marqdo 的研究主张
过去 Marqdo 的核心叙述是:
> 代码即文档,文档即知识库,知识即可执行。
我认为现在可以把它变得更加严格:
Marqdo 是一种将人类可读文档编译为可寻址、可验证、可执行、可复用的知识制品的语言与编译系统。
这个定位的价值不在于“Markdown 可以运行代码”,也不在于“Markdown 链接能调用函数”。这两点单独来看都不足以形成很强的研究贡献。
它真正值得探索的创新组合是:
一份自然语言与程序混合的源码,经过统一编译后,同时生成可执行程序、语义符号体系、验证证据、版本化知识引用和 AI 可消费的复用接口。
当然,这仍然是一个待证明的系统设计目标,而不是当前 v2.0.0 已经达到的状态。
## 最终判断
你的 `[]()` 方向值得保留,甚至值得作为下一轮 Marqdo 核心架构调整的切入点。但我不建议继续把主要精力投入到如何让 `[]()` 兼容更多语法、更多函数调用形式或更多 Markdown 场景。
你现在缺少的不是更漂亮的链接语法,而是一个由编译器负责维护的“知识身份与语义绑定层”。
这也是我认为应该优先修正当前 [link-syntax.md](https://github.com/cflmy/marqdo/blob/main/doc/design/link-syntax.md?utm_source=chatgpt.com) 的地方:它现在主要把链接理解为“表达式 + 描述 + 元数据”;下一版应明确规定,表达式可以解析到独立的、具有身份与验证状态的知识制品。
当这种绑定成立时,`[]()` 才能够同时实现你的两个愿望:读者看到自然语言,AI 获取确定性知识引用,编译器负责确保引用并非凭空想象。
而且,这次改变不必要求用户学习更多语法。真正增加的复杂度应当留在编译器和知识中间表示内部,而不是继续转嫁到 `.mq.md` 的作者身上。
是的。我认为你这个判断是正确的,而且它指出了我上一轮分析中的一个偏差:我把实现可执行知识体系所需要的技术条件,提升成了 Marqdo 的最终目标。
实际上,这两者应当区分。
你最初提出的:
> 代码即文档,文档即知识库,知识即可执行。
并不只是一句理念性的口号,它本身已经包含了完整的目标链条:
1. 代码即文档:知识与程序不再被割裂为两套独立的表达体系。
2. 文档即知识库:文档中的内容不再只是供人阅读的信息,而是可以被组织、定位、理解和关联的知识。
3. 知识即可执行:知识不再停留在被检索和解释的阶段,而是能够被直接调用、组合和复用。
其中,知识复用就是第三阶段最重要的结果之一。
因此,我之前提出的“可寻址、可验证、可执行、可复用”,实际上是在描述达成第三阶段需要具备的工程性质,而不是一个比原始理念更高层次的新目标。
## 真正需要解决的是:什么才算知识被复用?
我认为这里才是 Marqdo 当前设计最值得深入的地方。
假设 AI 需要计算一笔订单的最终价格。
传统方式可能是:
- 检索价格计算文档;
- 阅读文档中的公式和约束;
- AI 自己理解并重新编写计算逻辑;
- 执行新生成的代码。
这个过程中,知识被读取了,但未必真正被复用。AI 仍然可能理解错误、遗漏约束或生成不一致的实现。
而你想实现的 Marqdo 应该是:
```
订单最终价格为[计算后的价格](订单.最终价格(订单数据))。
```
这里 AI 不需要重新理解定价公式并生成一套新算法,而是引用已经存在的知识实现。
如果该实现的身份、依赖、契约和适用条件都能被确定,那么 AI 的任务就从:
“根据知识重新生成答案或程序”
转变成:
“发现知识 → 判断是否适用 → 引用知识 → 执行知识 → 使用结果”
这才是 Marqdo 的核心价值。
## 所以,`[]()` 应该承担什么角色?
我建议将整个体系理解成:
代码即文档
统一人类叙述与机器可执行内容
文档即知识库
知识具有结构、身份、关联与约束
知识即可执行
知识能够被确定性引用、调用和组合
知识真正复用
AI 优先使用既有知识,而非反复解释和重新生成
`[]()` 不需要独自完成这一切。
它应该成为整个体系中知识从文档进入使用场景的统一入口。
而编译器、符号系统、知识索引、验证系统与 EKC,则共同保证这个入口背后的知识可以可靠使用。
这里有一个很重要的区别:
- `[]()` 负责表达“我要使用这段知识”。
- 编译器负责确定“究竟是哪段知识”。
- 验证系统负责判断“这段知识是否满足当前使用条件”。
- 运行时负责执行知识。
这些职责不应该全部压到 `[]()` 的语法设计上。
## 我现在更倾向于保留你的原始理念
甚至不建议用我之前那段冗长的定义替换它。
“代码即文档,文档即知识库,知识即可执行”已经足够准确。
真正值得补充的是它背后的一个技术原则:
> 知识复用应当基于已编译知识的确定性引用,而不是基于自然语言的重复解释与生成。
这句话比单纯强调“可寻址、可验证”更接近你真正想解决的 AI 问题。
不过还需要保持一个边界:确定性引用能够减少 AI 在重新解释和生成过程中产生的错误,却不能自动保证被引用的知识本身正确。因此验证仍然必要,只是它属于实现可靠复用的手段。
我认为 Marqdo 下一步最值得研究的,已经不是“如何让文档变成知识库”,而是一个更具体的问题:
如何让一个 AI 在面对新任务时,能够像编译器复用已有函数一样,直接复用知识库中已经编译的知识,而不必重新理解和生成它?
如果 Marqdo 能真正解决这个问题,你原来的三句话就不再只是设计理念,而是一个可以通过实验验证的语言能力。
# Marqdo 可执行知识体系:设计规范与完整范例
我已经基于 Marqdo 当前仓库的语法规范、`[]()` 设计、知识分层、对象模型和 EKC,整理了两份详细文档。
这次设计保留了你的原始理念:
> 代码即文档,文档即知识库,知识即可执行。
核心目标不是让 AI 更容易生成 Marqdo 代码,而是让 AI 尽可能不必重新生成已经存在的知识,转而通过编译器确定性地发现、引用、验证和执行既有知识。
第一份:完整架构设计规范
涵盖语义制品、知识引用、编译器架构、解析优先级、效应安全、版本管理、EKC 集成、Agent 复用协议和实施验收。
阅读设计文档
第二份:多文件可执行知识范例
以虚构书店定价为例,从原始政策文档开始,逐步构造知识定义、对象、计算能力、业务入口、AI 问答、知识复用和错误验证。
阅读完整示例
两份文档打包
下载 ZIP
## 一、这份设计最重要的三个决定
# Marqdo 可执行知识体系:核心设计纲领
**核心理念:代码即文档,文档即知识库,知识即可执行。**
## 1. 知识是可编译的语义制品
文档经过 Marqdo 编译器处理后,不只产生可执行逻辑,还应产生具有稳定身份、类型、签名、契约、依赖关系、来源和验证状态的语义制品(Semantic Artifact)。
知识可以表现为事实、函数、能力、约束、数据集或类型。它们无需全部被强制编码为类。
## 2. `[]()` 是知识使用的统一入口
`[描述](目标)` 保留 Markdown 的可读性。
- `[]` 面向人类,描述意图、意义或用途。
- `()` 面向编译器,包含既有 Marqdo 表达式或者可解析的知识目标。
- 描述不改变执行结果,也不能作为可信性依据。
- 编译器负责将目标解析为确定的符号身份,并验证使用条件。
既支持隐藏不易阅读的代码,也支持引用已经编译的知识。
## 3. AI 复用知识,而不是重新解释知识
AI 面对新任务时,应该遵循:
**Discover → Resolve → Verify → Reuse → Execute → Trace**
当知识缺失或不适用时,才进入 ADAPT 或 CREATE 流程。
检索可以模糊,但最终绑定必须确定。验证必须区分程序可执行性、契约符合性和现实事实正确性。
## 4. 编译器是知识系统的基础
AST、Semantic IR、符号索引、链接关系和知识验证应当由同一套语义体系产生。
解释器、字节码 VM、View、EKC 和 Agent 消费统一的编译结果,而不是各自重新解析文档。
## 5. 最终验收标准
一个 AI 能够发现现有知识、确定其身份、检查适用条件、直接执行既有能力、引用结果和来源,并在知识发生变化时识别受影响的调用者。
只有这条链条成立,Marqdo 才真正实现知识的可执行复用。
## 二、示例将展示什么
我选择了一个具有明确规则和复用价值的业务案例,而不只是使用“李白出生年份”这样的静态事实。
用户购买两件单价 60 元的商品,金卡折扣为 90%,满 100 元免运费。
AI 要处理的业务请求
> 请计算这笔金卡订单的最终应付款,并解释依据。
传统路径
检索政策 → AI 阅读规则 → 重新推导计算 → 生成新代码或答案
Marqdo 目标路径
发现定价能力 → 绑定已编译函数 → 检查输入与政策 → 执行 → 引用结果
目标语法示意(v2.1+,不是 v2.0.0 实测)
```
**应付 = [订单最终应付款](定价.计算应付金额(60, 2, "金卡"))**
```
根据演示政策计算
# ¥108
这套例子进一步展示了参数和返回值、类与继承、表格、条件分支、循环、跨文档调用、自然语言遮蔽,以及知识来源改变时的影响分析。
## 三、与当前版本的兼容边界
我特别保留了一个重要区分:设计目标不等于当前已经实现的功能。
根据这次读取的仓库内容,v2.0.0 已支持本地表达式遮蔽、对象、方法、控制流、表格集合、导入以及现有 EKC 基础;但无实例类函数调用、跨文档知识自动解析、完整 LinkInfo 和语义制品绑定仍需要进一步开发。
因此示例文档明确标注了目标语法和现有兼容写法,没有将尚未验证的代码描述为已经跑通。
## 四、我的主要架构建议
我认为接下来的开发不应该从 `[]()` 的外观继续扩展,而应该先实现:
统一符号索引 → 稳定知识身份 → 引用绑定 → 契约验证 → EKC 复用。
还有一点值得特别强调:我不赞成为了建立知识系统,再单独实现一个与 Marqdo 解释器并列的“知识编译器”。那样会重新制造你希望消除的表示碎片。
更合适的架构是让现有 Marqdo 编译管线产出统一的语义中间表示,然后由运行时、View、EKC 和 Agent 各自消费。
这意味着 Marqdo 的知识体系不是一个外挂的 RAG 框架,而是语言本身的语义能力。
我认为这才是整个设计中最值得投入资源,也最有可能形成独立研究贡献的部分。
+374
View File
@@ -0,0 +1,374 @@
请你重新阅读marqdo的官方库,掌握marqdo的最新进度。在我对marqdo项目的仔细审视之下我发现有一点没有闭环,我终于找到了,考虑现在智能体开发最常用的SKILL,这是一个markdown文件写明了智能体该干什么,我想要更推荐一步,因为marqdo使用markdown语法,支持叙述和代码相互混合,这就使得marqdo满足这样一个条件,当分章节的SKILL撰写下来,只要经过调整就能成为一份marqdo代码其中包含若干函数,我打算开发新的CLI命令marqdo > 函数名 函数参数或者marqdo call 函数名 函数参数 此时SKILL的不同章节就变成了不同的函数,智能体就真正的成为了将知识复现的作用,这让代码即文档、文档即知识,知识即可执行推进了一步变成了知识即工具,真正发挥了marqdo的优势,同样这样的执行还以为着智能体能够自行改进SKILL并接受确定的问题后修改而不会出错,这让自我进化的智能体成为了具备理论支撑和清晰边界的可能
# Marqdo 从“可执行知识”走向“知识即工具”:最新仓库审查与架构建议
我认为你这次找到了 Marqdo 一个非常重要、而且比单纯增加 `marqdo call` 命令更深层的突破口。
你实际上提出了一个新的统一关系:
> SKILL 是人和 AI 都能阅读的操作知识;Marqdo 可以让其中具有确定性执行语义的章节,直接成为可调用的工具。
这样,Agent 的职责就有机会从“阅读说明、理解步骤、临时生成实现”,转向“定位已有能力、填入参数、执行和验证结果”。
这与 Marqdo 原来的三句话是连续的,不需要推翻原来的定位:
代码即文档 → 文档即知识库 → 知识即可执行 → 知识即可作为工具使用。
不过我建议把“知识即工具”视为可执行知识的对外使用形态,而不是再创造一套与语言、知识库平行的 Skill 运行系统。
## 一、重新检查仓库后的最新情况
本次核对的是 [cflmy/marqdo](https://github.com/cflmy/marqdo?utm_source=chatgpt.com) 的 `main` 分支,HEAD 为 `4018e992`,`Cargo.toml` 版本为 2.1.5。最近的 v2.1.5 版本记录日期是 2026 年 10 月 27 日。
与我们之前讨论 v2.0.0 时相比,项目已经完成了不少与你的构想直接相关的基础建设。
| 相关能力 | 最新仓库证据 | 判断 |
| --------------------- | ---------------------------------------------------------------- | -------- |
| 跨文档确定性函数绑定 | `BoundCall`、`SymbolId`,Tree/Bytecode 双后端测试 | 已有核心基础 |
| 已编译知识的执行复用 | MLSP `artifact.bind`、`artifact.execute`、`artifact.reuse_execute` | 已有子集 |
| Agent 复用已有函数 | `agent_eng_bind_execute`、发布门禁 | 已有子集 |
| 指定函数执行 | `marqdo run --call-lib-path`、JSON 参数、隔离 worker | 已有底层入口 |
| 智能体工具规范 | `ToolSpecV1`、效应分类、权限检查与恢复设计 | 已有框架基础 |
| 章节式 SKILL 自动成为 CLI 工具 | 目前没有独立的 `marqdo call` 或 Skill 编译命令 | 待开发 |
| SKILL 自修改、自动测试和受控发布 | 已有局部修改、验证与沙盒组件 | 尚未形成完整闭环 |
因此,现在不是重新开发一个 Skill 执行器,而是将已存在的 Marqdo 函数、知识制品、工具协议和 Agent 机制统一起来。
还有一个与你的新构想直接相关的问题值得先修复:
最新官方 `skills/marqdo/SKILL.md` 的核心语法说明,与仓库中的现行解析器、v0.3 语法规范和可执行测试存在冲突。
目前解析器与测试使用的是:
- `**…**`:代码、赋值、调用等语句;
- `*…*`:返回值。
但官方 Skill 顶部却把两者反过来描述。这不是小的文档笔误:如果 Agent 按照错误规则自我修改 Skill,就可能产生与实际运行时不一致的程序。
这个真实存在的不一致,恰好证明了你所说的闭环为什么重要——SKILL 不能仅靠自然语言说明自己的正确性,它需要由语言编译器和实际测试提供独立验证。
## 二、你真正提出的是一种新的 Skill 体系
我建议把它暂时命名为 Executable Skill(可执行技能)。
它不应被理解为“给 Markdown Skill 增加一点代码”,而应当满足一个更严格的定义:
> Executable Skill 是一份以 Markdown 为人类可读接口、以 Marqdo 函数为确定性执行单元、以编译后的语义制品为工具身份、能够由 Agent 发现、调用、验证和改进的技能文档。
传统 Skill 与你的目标之间,存在一个非常重要的区别。
| 维度 | 普通 Markdown Skill | Marqdo Executable Skill |
| ---- | ----------------------- | ----------------------- |
| 技能说明 | 自然语言 | 自然语言 |
| 操作步骤 | Agent 阅读后自行实施 | 可以绑定已有 Marqdo 函数 |
| 函数接口 | 通常需要额外编写工具代码 | 从 `.mq.md` 的函数和契约生成 |
| 执行 | 依赖 Agent 选择工具、生成代码或操作软件 | 对已实现的步骤直接执行 |
| 输出验证 | 往往需要单独建立 | 可连接编译器、契约和测试 |
| 改进 | 编辑说明或脚本 | 编辑同源的知识与实现,验证后发布 |
| 可追踪性 | 主要依赖工具日志 | 可关联 SymbolId、源码、版本和执行结果 |
但不是每个 Skill 章节都应该自动变成可执行函数。
比如“适用场景”“注意事项”“禁止操作”是知识或约束;“检查订单”“生成报价”“汇总报告”才可能成为可调用能力。编译器应区分文档章节与可执行章节,不能把所有二级标题不加判断地暴露成工具。
### 这实际上使 Agent 的结构发生变化
SKILL.md
目标 · 流程 · 函数 · 契约 · 示例 · 约束
Marqdo Skill Compiler
章节解析 · 符号绑定 · 类型检查 · 效应分析
Knowledge View
Agent 阅读技能与限制
Tool Registry
Agent 调用已编译函数
Agent:选择、组合、执行、观察与改进
由语言运行时执行确定性部分,由模型处理非确定性判断
特别值得注意的是:这不仅是执行接口的统一,还是知识交付接口的统一。
同一份 Skill 能够投影成可读说明、CLI 函数、Agent Tool Schema、MCP 工具描述,以及知识库中的能力节点。实现这些投影的系统仍是同一个 Marqdo 编译器。
## 三、CLI 应采用 `marqdo call`,不要采用 `marqdo >`
你提出了两个命令形式:
```
marqdo > 函数名 函数参数
marqdo call 函数名 函数参数
```
我明确建议采用第二种。
原因是 `>` 在 Bash、PowerShell、CMD 等 Shell 中已经具有输出重定向语义。`marqdo > xxx` 会被 Shell 先行解释,无法可靠地作为传递给 Marqdo 的函数调用语法。
推荐设计为:
```
# 按函数名调用
marqdo call "订单计算.商品小计" \
--skill ./skills/order-calculator \
--arg 单价=30 \
--arg 数量=2
# 结构化调用,供 Agent 使用
marqdo call "订单计算.商品小计" \
--skill ./skills/order-calculator \
--args-json inputs.json \
--output json \
--policy pure
```
上述是建议新增的 CLI 接口,不是 v2.1.5 已支持的命令。
我还建议在 CLI 层保留一个便利别名:`marqdo skill call`。它与 `marqdo call` 进入同一个 dispatcher,不应分别实现两套调用逻辑。
### 最小必要的 CLI 能力
| 命令 | 作用 |
| ---------------------------- | ----------------------- |
| `marqdo skill inspect PATH` | 解析 Skill 文档、章节、可调用函数和依赖 |
| `marqdo skill list PATH` | 列出对 Agent 暴露的工具 |
| `marqdo skill check PATH` | 检查语法、绑定、签名、效应和工具导出规则 |
| `marqdo call TARGET` | 调用指定 Marqdo 函数并返回结果 |
| `marqdo skill test PATH` | 执行 Skill 的测试与契约检查 |
| `marqdo skill export PATH` | 生成通用工具描述或 MCP 暴露接口 |
| `marqdo skill trial PATH` | 对修改后的候选版本进行隔离验证 |
| `marqdo skill promote PATH` | 在门禁通过后发布新版本 |
| `marqdo skill rollback PATH` | 恢复到指定已接受版本 |
不过不建议一次性实现这九项命令。最小可用产品只需要 `inspect`、`call`、`check`、`test` 四项,版本发布与改进机制可以随后补齐。
最重要的技术决策是:
`marqdo call` 必须调用现有编译器绑定的函数,不得重新用字符串搜索源码、猜测章节位置再执行。
当前 [src/mlsp.rs](https://github.com/cflmy/marqdo/blob/main/src/mlsp.rs?utm_source=chatgpt.com) 已有 `artifact.bind` 与 `artifact.execute`,能够检查制品指纹、依赖闭包、来源摘要和效应策略。新的 CLI 应复用相同的应用服务和语义校验,而不是通过进程内调用 MLSP JSON 接口制造另一层重复协议。
还有一个现有实现细节:`marqdo run --call-lib-path` 已支持隔离 worker 通过 JSON 参数调用函数,但当前 `src/lib.rs` 的这个入口只在树遍历分支中处理,Bytecode 分支仍按普通程序入口执行。新的公开 `call` 命令需要补齐这一差异,或者明确在第一版只支持 Tree backend,不能静默忽略所选后端。
## 四、完整示例:让一份 Skill 同时成为文档、知识和工具
我建议第一版尽量保持作者体验简单:人只维护一份 Markdown 源文件,编译器自动生成工具描述、函数索引和知识制品。
例如,我们建立一个订单计算 Skill。
下面是目标设计示例。其中 `runtime` 和 `tools` 是我建议为 Skill 编译增加的元数据约定,目前不能将这份 `SKILL.md` 直接交给 v2.1.5 的 CLI,期待自动注册工具。
```
---
name: order-calculator
description: 订单价格计算,包括商品小计和含税金额
runtime: marqdo
tools:
- 订单计算.商品小计
- 订单计算.含税金额
---
# 订单计算
这份技能用于计算订单金额。
所有金额使用同一货币单位。税率使用小数表示,
例如 0.10 表示 10%。
## 商品小计
给定商品单价`单价`和购买数量`数量`,
计算未税商品小计。
*[商品小计](单价 * 数量)*
## 含税金额
给定商品单价`单价`、购买数量`数量`
和适用税率`税率`,计算含税金额。
**小计 = [计算商品小计](订单计算.商品小计(单价=单价, 数量=数量))**
*[最终含税金额](小计 * (1 + 税率))*
```
这里的计算是演示规则。正式业务技能还需要校验数量范围、金额精度、货币单位、税率适用条件与舍入规则;这些不能由函数名字自动推断为正确。
### 这份 Skill 会产生三种投影
给人阅读: 它是一份正常的 Markdown 文档。读者能理解每个步骤的目的,以及所需输入和返回值。
给 Marqdo 编译器: 两个 `##` 单元构成可解析的函数;第二个函数可以确定性地调用第一个函数;符号索引能够记录它们的依赖关系。
给 Agent 使用: 编译器输出两个工具的结构化描述。Agent 不需要重新生成乘法计算程序,只需选择工具并提供参数。
例如,编译后的工具描述可以是:
```
{
"id": "order-calculator::订单计算.商品小计",
"description": "计算未税商品小计",
"input_schema": {
"type": "object",
"properties": {
"单价": {"type": "number"},
"数量": {"type": "number"}
},
"required": ["单价", "数量"]
},
"output_schema": {
"type": "number"
},
"effect": "pure"
}
```
但这个 Schema 必须由明确的类型契约和编译器检查生成。若源文件没有足够的类型信息,应标记为未知或要求补全,不能因为变量参加了乘法就无条件断言它一定是 `number`。
需要强调:不是 `##` 标题自动等于一个公开工具。 `##` 让章节具备 Marqdo 函数的结构,`tools` 则声明哪些函数允许对外暴露。这样才能避免“安全说明”一类章节被意外注册成工具,也避免内部辅助函数被 Agent 随意调用。
### 为什么采用显式的 `runtime: marqdo`?
因为普通 Skill 的 Markdown 本来就可能包含 `**加粗内容**`、编号列表、代码块和二级标题。这些在现有 Marqdo 中可能具有执行语义。
如果直接把所有 `SKILL.md` 当成 `.mq.md` 执行,很可能发生严重的语义误读。
所以我建议:
- 未明确声明 Marqdo 运行时的 `SKILL.md`,仍然是普通 Markdown 文档。
- 明确声明 `runtime: marqdo` 的 Skill 才进入 Marqdo 编译流程。
- 内嵌示例代码块不应因展示而执行。
- 编辑器应对具有执行意义的 Markdown 标记提供可视化提示。
- 导出的工具必须经过独立检查和授权。
未来还可以支持从已有普通 Skill 中自动提取候选函数,但那应当是生成可审阅的转换补丁,而不是默认把自然语言步骤当成已经实现的代码。
## 五、这次最有价值的部分:自我改进的 Skill
你提出的第二层意义,我认为甚至比 `marqdo call` 更值得研究。
传统 Agent 修改一个 Skill 时,常见问题是:它修改了一段说明或脚本,却无法可靠判断其他步骤是否受到影响。
Marqdo 已经具备一些适合解决这个问题的基础,例如 `SymbolId`、依赖闭包、`artifact.patch`、`artifact.verify` 和知识影响分析。
但是,不能由此推出“智能体修改 Skill 就不会出错”。
更精确的目标是:智能体可以提出改进,系统能够判定一组明确、可测试的性质是否被保持,并且只有通过门禁的版本才有资格替换原有 Skill。
我建议采用以下演化协议:
已发布 Skill v1
现有稳定版本与完整依赖
1\. 发现确定的问题
失败测试、诊断、复现步骤或用户提出的明确修改要求
2\. AI 生成局部修改候选
只修改获准的章节或函数,记录版本与修改意图
3\. 编译与静态验证
语法、符号、参数、返回类型、效应、依赖关系
4\. 隔离测试与回归验证
目标问题修复、历史行为保持、异常输入、性能与权限边界
5\. 发布门禁
仅当策略允许且必要验证通过时晋升新版本;否则保留旧版本
Skill v2 · 已接受版本
可追溯、可回滚、后续调用绑定到明确版本
### 举一个真正的自我改进案例
原 Skill 中存在:
```
## 商品小计
商品单价`单价`,购买数量`数量`。
*[小计](单价 * 数量)*
```
现在发现一个确定的问题:输入 `数量=-1` 时,函数返回负数,但业务要求数量必须大于零。
Agent 不应该只是把说明修改成“数量必须大于零”。这不会改变执行行为。
它应当在候选版本中增加可执行的校验逻辑,并补充至少三个测试:
| 测试 | 输入 | 期望 |
| ---- | ----------- | ------------- |
| 正常订单 | 单价 30,数量 2 | 返回 60 |
| 非法数量 | 单价 30,数量 -1 | 返回结构化参数错误 |
| 边界数量 | 单价 30,数量 0 | 根据业务契约决定接受或拒绝 |
如果 Marqdo 尚不具备合适的语言级错误返回或异常处理方式,这个案例还会暴露一个语言能力缺口:需要一种由 Marqdo 程序自身构造、传递和处理错误的机制,而不是只能依赖 Rust 宿主报错。
这与此前我们讨论的通用语言能力重构是直接关联的。
### 自我进化的边界必须比普通代码修改更严格
我建议把以下约束固定下来:
1. 修改不能自动扩大权限。 原 Skill 只有纯计算权限,新版本不能因为 Agent 自己添加网络或文件操作就获得这些权限。
2. 候选版不能直接覆盖运行中的正式版本。 需要隔离工作区、原子发布和固定引用版本。
3. 必须证明目标问题被修复。 不允许通过删除测试、放宽断言或隐藏失败来宣称成功。
4. 测试通过不是绝对正确的证明。 未覆盖的业务情况、外部事实和依赖服务仍可能出错。
5. 高风险修改需要更严格的发布决策。 尤其是支付、外部写入、删除、凭证和安全策略变更,不能由被修改的 Skill 自己批准。
最新仓库的 `artifact.patch` 已经提供基于摘要的修改和有限回滚,但它还不是完整的候选版本事务与测试后晋升系统。现有 `HostCaps` 的默认值也允许文件写入、执行、网络和插件,因此新 `call` 的安全默认值应当收紧,不能简单继承普通本地运行的全部宿主权限。
这就是“有界自我进化”的含义:不保证 Agent 永不犯错,而是让它能够在可验证、可回滚、可限制权限的范围内持续改进。
## 六、我建议如何安排开发
| 阶段 | 目标 | 关键验收 |
| ---------------- | ---------------------------------------- | ------------------------ |
| S0 · Skill 语义一致性 | 修复官方 Skill 与解析器的标记冲突,建立 Skill 语法同步测试 | Skill 记载的每条核心语法都有可运行金样例 |
| S1 · 函数调用 CLI | `marqdo call` 调用已绑定的普通函数、类函数和跨文档函数 | JSON 参数正确绑定;错误路径和双后端行为明确 |
| S2 · Skill 编译 | 对显式启用的 `SKILL.md` 解析章节和可执行函数 | 自动产生 SymbolId、签名、依赖、导出清单 |
| S3 · 知识即工具 | 将公开函数编译为 ToolSpec,并接入现有 Agent dispatcher | Agent 不重新生成实现即可调用并取得结果 |
| S4 · Skill 测试 | 增加 `skill check/test`、负例、效应门禁和回归测试 | 未通过验证的 Skill 不得自动发布 |
| S5 · Skill 演化 | 实现候选修改、隔离验证、影响分析、版本晋升与回滚 | 修改失败不影响已发布版本,权限不能自行扩大 |
这里还需要一项对你的研究目标尤其重要的对照实验。
让相同模型分别使用普通 Markdown Skill、Markdown Skill 加外部脚本工具、以及 Marqdo Executable Skill 完成相同的一组任务。分别测量正确率、模型需要重新生成的代码量、工具调用参数错误、修改后的回归失败率、token 消耗和完成时间。
只有与“Markdown + 现有工具调用”进行公平对照,才能证明 Marqdo 的优势来自文档、程序与知识的统一,而不只是因为它额外提供了一个执行器。
## 七、我对这项构想的最终评价
我认为这次构想具有三个非常值得肯定的性质。
第一,它有明确的语言基础。`#`、`##`、自然语言叙述、函数参数、`[]()`、契约表和跨文档符号绑定并不是为了 Skill 重新创造的。Skill 可以成为现有语言的一种应用形态。
第二,它有真实的工程基础。当前 Marqdo 已经具备部分确定性绑定、制品验证、Agent 复用与隔离运行能力。你需要做的是将这些能力收敛到统一的公开接口,而不是重新实现一套 Agent 框架。
第三,它能够引出一个更有研究价值的问题:自然语言描述的操作知识,如何逐步转化为可调用、可检查、可维护,并可由 Agent 在受限条件下自行改进的程序制品?
但是,“SKILL 章节即函数”本身还不足以证明新的编程范式。Markdown 章节映射函数,与文学编程、文档驱动工作流及现有工具包装有明显的共同点。
更有价值的是把三个原本需要单独维护的对象——Skill 说明、函数实现、Agent Tool Schema——统一为一个可编译的源事实,并展示这种统一确实降低了错误、维护成本和重复生成成本。
我建议为 Marqdo 保留原来的核心理念,并将这一阶段的技术方向明确为:
> 知识即工具(Knowledge as Tool):将可执行知识直接编译为 Agent 能够发现、调用和验证的工具,并允许智能体在明确的语义、测试和权限边界内持续改进这些知识。
这可能是 Marqdo 从“AI 可以使用的编程语言”,进一步走向“AI 能够使用并维护的可执行知识体系”的关键一步。
备注,这里实际上有一点叙述错误,marqdo支持mq.md文件,所以最好针对SKILL也是SKILL.mq.md这样会比较统一。
+249
View File
@@ -0,0 +1,249 @@
SKILL的名称应该是.mq.md有一点必须提及,SKILL其实命名不一定必须得是SKILL,平常的一个marqdo文件也可以是一份skill这里的设计太复杂了没有抽离出来核心本质,你看对于一个平常的marqdo文件,完全也可以和SKILL一样,这都是没有区别的,所谓的知识即工具作为高度抽象本质就是带参数调用函数,所以你的inspect等等命令其实完全可以对传统的marqdo也生效而不是非要绑定SKILL对吧,而且这样处理还有好处是方面智能体做单元测试,单个函数是否可以带参数直接运行,换句话说,你仔细思考就会发现这些好处是marqdo的设计哲学在增加一点点call自然派生的优势,所以不需要繁复的设计
你说得对。这次我认为你抓住了真正的核心,而且我的上一版设计确实把一个本来很自然的语言能力复杂化了。
Marqdo 根本不需要引入一种叫作 Executable Skill 的新概念,也不需要专门建立 Skill 编译器。
因为在 Marqdo 的设计哲学下:
> 一个 `.mq.md` 文件本身就是文档、知识与程序。只要允许从外部直接调用其中的函数,它自然也就能够成为 Skill。
这不是为 Skill 开发一套新系统,而是为 Marqdo 补齐一个非常基础的语言使用入口。
## 一、真正缺少的只有一件事:函数级执行入口
Marqdo 当前已经支持函数定义、参数、返回值、模块引用,以及确定性符号绑定。
但是日常使用时,我们往往仍然站在“运行整个文件”的角度:
```
marqdo run example.mq.md
```
你现在提出的是:
```
marqdo call example.mq.md 函数名 参数
```
这实际上意味着:
Marqdo 的最小可执行单位,从文件进一步扩展为文件中的任意可调用函数。
而这一点会自然派生大量优势。
普通 `.mq.md` 文件
自然语言叙述 + 函数 + 参数 + 返回值
marqdo call
指定函数 + 绑定参数 + 直接执行
知识复用
调用已存在的实现
Agent Skill
直接暴露函数为工具
单元测试
逐个函数验证结果
自我改进
修改函数并重新测试
这里不存在四套实现,只有一个底层能力的四种使用方式。
## 二、一个普通的 Marqdo 文件就足够了
比如,文件 `calculator.mq.md`:
```
# 计算器
这是一个普通的 Marqdo 文档。
其中包含一些可以复用的数学计算知识。
## 加法
计算两个数字`a`和`b`的和。
*[计算结果](a + b)*
## 乘法
计算两个数字`a`和`b`的积。
*[计算结果](a * b)*
```
它既是可阅读的文档,也包含两个函数。
现在只需要支持:
```
marqdo call calculator.mq.md 计算器.加法 a=2 b=3
```
返回:
```
5
```
再比如:
```
marqdo call calculator.mq.md 计算器.乘法 a=4 b=6
```
返回:
```
24
```
以上 `marqdo call` 是拟新增的命令形式;函数示例遵循当前 `*…*` 返回、`[]()` 遮蔽的语义。
这时候,一个 Agent 只要能够读取这个 `.mq.md` 文档,就可以理解函数的用途;只要能够调用 Marqdo CLI,就能执行其中的能力。
它根本不需要关心这个文件是不是 Skill,也不需要一份特殊的 `SKILL.md`。
如果 Agent 把它当成 Skill 阅读和使用,它就是 Skill;如果开发者把它当成程序库调用,它就是程序库;如果研究者把它作为知识库中的一部分,它就是可执行知识。
文件的身份没有变化,变化的是使用方式。
## 三、这项能力会自然解决三个问题
### 1. 让知识成为工具
传统 Skill:
Agent 阅读操作说明,决定如何完成任务。
Marqdo:
Agent 阅读函数说明,找到适合的函数,传入参数,直接执行。
这就将原来的:
知识 → Agent 理解 → 重新实现 → 执行
缩短为:
知识 → 函数定位 → 参数调用 → 执行
但模型仍然需要负责判断应该调用哪个函数、传入哪些参数。确定性的是被调用函数的语言语义,而不是整个 Agent 决策过程。
### 2. 让单元测试成为语言的天然能力
我非常赞同你提到的单元测试价值。
有了 `marqdo call`,可以直接测试:
```
marqdo call calculator.mq.md 计算器.加法 a=2 b=3
# 期望 5
marqdo call calculator.mq.md 计算器.加法 a=-2 b=3
# 期望 1
marqdo call calculator.mq.md 计算器.乘法 a=0 b=100
# 期望 0
```
不必为了测试一个函数,再创建一个 `# main`,再编写调用、打印和结果检查的包装程序。
未来即使增加 `marqdo test`,底层仍然可以复用同一个函数调用接口。
### 3. 让 Agent 可以针对知识进行局部改进
这是你提出的最有意义的延伸。
假设一个 Agent 发现 `计算器.乘法` 对某类输入存在错误。
它可以:
1. 阅读相应函数及其上下文。
2. 修改这个 `.mq.md` 文件中的函数实现。
3. 直接用 `marqdo call` 传入错误输入验证。
4. 再运行该函数的历史测试。
5. 如果检查通过,就提交候选修改;否则保留原有实现。
这使得 Agent 的改进对象不再仅仅是自然语言提示词,而是有明确输入、输出和可执行语义的知识单元。
当然,测试不能证明函数在所有输入上都正确;正式发布和权限控制仍需要遵循已有的项目验证机制。但不需要为此创造一套 Skill 专属的演化协议。
## 四、真正的 CLI 设计可以非常简单
我建议第一阶段只做一个命令:
```
marqdo call <文件> <函数> [具名参数...]
```
比如:
```
marqdo call book.mq.md 订单.计算总价 单价=30 数量=2
```
它只需要完成五件事:
| 步骤 | 职责 |
| -- | -------------------- |
| 1 | 加载指定 `.mq.md` 文件及其导入 |
| 2 | 解析并唯一定位目标函数 |
| 3 | 根据现有函数签名绑定、校验参数 |
| 4 | 使用现有运行时执行该函数 |
| 5 | 返回函数结果和结构化错误 |
额外提供一个 `--json` 输出选项就足够方便 Agent 调用。
如果未来需要 `marqdo inspect`,它也应该针对任何 `.mq.md` 文件,列出其中函数、参数和文档描述,而非限定 Skill。
此外,当前仓库已经有 `--call-lib-path` 和 `artifact.execute` 的相关基础,因此实现时应尽量复用现有函数定位与执行机制,而不是重复开发解释器。
唯一值得坚持的边界是:外部调用仍必须经过现有权限检查,不能因为新增了 `call` 就默认允许 Agent 对任意函数执行文件删除、网络写入等操作。
## 五、我认为你的设计哲学现在更加清晰了
你原来的理念:
> 代码即文档,文档即知识库,知识即可执行。
实际上已经足够完整。
“知识即工具”不是额外的设计理念,而是“知识即可执行”在函数级调用能力成熟后自然出现的结果。
进一步看,这件事还有一个很漂亮的对称性:
| 参与者 | 对同一个 `.mq.md` 的使用方式 |
| ---------- | ------------------- |
| 人类 | 阅读文档、理解知识 |
| 编译器 | 解析并验证函数 |
| 开发者 | 调用函数、组合程序 |
| Agent | 发现知识、调用工具 |
| 测试系统 | 输入参数、检查结果 |
| 维护者或 Agent | 修改实现、验证改进 |
这些角色并没有要求作者维护六份不同的东西。
同一份文件,同一套语义,同一个函数调用接口。
这也恰恰是我认为 Marqdo 相比传统“Markdown 文档 + 外部工具”组合最值得证明的优势:知识描述与执行实现共址,而且能够直接由语言工具链消费,避免维护重复的工具包装和操作说明。
所以,我现在的建议与上一轮不同:
不要开发 Executable Skill 系统。不要设计 Skill 专属语法。不要引入新的 Skill 注册、编译和执行机制。
先完成 `marqdo call`,使普通 `.mq.md` 中的可调用函数都能被精确定位、传参执行,并用现有语义系统验证。
这是一个相对很小的接口变化,却可能自然打通 Marqdo 的编程、知识复用、Agent 工具调用和函数级测试四个场景。
我认为这才是你所说的:让 Marqdo 自己的设计哲学发挥作用,而不是不断增加外部框架来证明它的价值。
@@ -0,0 +1,295 @@
# Marqdo 可执行知识体系:统一语义制品与知识引用设计规范
> 状态:设计提案(非当前版本的已实现功能)
> 基线:仓库 main,2026-10-23;README 标记 v2.0.0;跨文档类调用与 LinkInfo 为 v2.1 目标
> 宗旨:**代码即文档,文档即知识库,知识即可执行。**
> 核心判据:当 AI 遇到任务时,能否先发现已有知识,并以确定性绑定复用,而不是再生成一份“看起来相同”的知识或实现?
## 1. 决策摘要
保持 `[描述](表达式或知识目标)` 的 Markdown 形态,不引入新的前缀或第二套表达式文法。`[]` 是面向读者的陈述,`()` 内的内容进入统一表达式解析器。语言内部建立稳定的 **Semantic Artifact(语义制品)** 和 **Verified Knowledge Reference(可验证知识引用)** 两种核心抽象。前者承载身份、语义、实现、依赖、契约与来源;后者是一个经编译期解析、受上下文约束的引用。它们不必对应新语法标记,而是 `.mq.md` 经语义分析得到的统一中间表示。
**三项不变式:**
1. **表达式透明性**:在求值上下文中 `[L](E)` 与 `E` 取得同一类型和值;`L` 不进入符号绑定或改变结果。引用额外产生诊断与溯源元数据。
2. **文本安全性**:叙述中的知识链接在 `check/view` 中解析;`run` 不因正文出现链接而隐式执行有副作用的函数。导航链接(HTTP、相对文档路径)仍属于普通 Markdown 链接。
3. **知识可信边界**:`resolved`、`compiled`、`tested`、`source_verified`、`domain_validated` 是不同状态。能执行不等于事实真;有来源不等于来源仍然适用。没有证据时允许展示,但不得向 agent 宣称为已验证知识。
### 1.1 不是要做的事
- 不将 Markdown 转成一个独立于解释器的新运行语言。
- 不把所有知识都强制构建为类,也不等同“知识 = 函数”。
- 不把自然语言标签作为权限或事实正确性的证明。
- 不把符号名的字符串匹配当成稳定知识复用。
- 不要求所有调用都锁版本:本地临时表达式可无锁,跨文档公共知识/关键业务则可选或强制锁定。
## 2. 以真实仓库为准的兼容边界
| 语法或能力 | 当前已支持 | 目标设计/注意事项 |
|---|---|---|
| `.mq.md` 和 Markdown 叙述 | 是 | 原有叙述默认安全 |
| `#` 对象/类型,`##` 函数/方法 | 是 | 目标:不依赖 `self` 的函数可通过类命名空间直接调用 |
| `**表达式**`、`*返回*` | 是 | 复用现有表达式解析器,不另造链接表达式 |
| `+ \`参数\``/叙述推断参数 | 是 | 签名必须能静态抽取并生成规范化形式 |
| `1.` 条件分支、`-` 循环 | 是 | 新版链接循环形式须通过模式迁移;旧式依赖 Classic |
| Markdown 表格→List/Map/列向表/行向记录 | 是 | 数据语义与契约表应从上下文区别 |
| Frontmatter `import` | 是 | 可作为当前跨文档路径的兼容实现 |
| `[描述](本地表达式)` | v2.0.0 已有,主要需 `markup: occlusion` | 统一后免模式开关;旧 `[键](集合)` 必须避免静默变义 |
| `类.函数` 无实例直接调用 | 未按目标实现 | **新能力**:区分类函数/实例方法、隐式零参调用 |
| 跨文档项目符号索引 | 尚缺 | **新能力**:可控作用域、同名消歧、增量索引 |
| LinkInfo/知识引用图/links.lock | 目标设计 | **新能力**;与已有 EKC 统一,拒绝第二套知识图 |
| 双执行后端(树遍历、字节码) | 是 | 引用语义必须在两个后端一致 |
项目示例分为:**V2-目标示例**(体现最终范式)与**V2.0-兼容示例**(现有调用方式)。所有目标示例是规范性设计,不宣称已在 v2.0.0 执行验证。
## 3. 知识不是代码字符串:规范化语义模型
### 3.1 Semantic Artifact
每个可引用实体编译为 `Artifact`,而非仅落入 AST 一个节点。
```text
Artifact {
symbol_id: StableSymbolId, // 跨增量构建稳定的身份(命名空间 + 显式/规范化路径)
kind: Type | Entity | Fact | Function | Capability | Constraint | Policy | Dataset,
visibility: Local | Module | Project | Exported,
source_span: SourceSpan,
signature: CanonicalSignature?, // 参数、返回值、默认值、单位与结构类型
ir: CompiledIR?, // 运行逻辑或规范化常量;普通叙述可无
effects: EffectSet, // pure / fs.read / fs.write / network / llm / time / random ...
dependencies: [SymbolId],
contract: [Predicate | Schema | Condition],
provenance: [SourceRef],
hashes: { interface, implementation, dependency_closure, evidence },
verification: VerificationRecord
}
```
区分以下四个概念:
- **Identity(身份)**:目标属于哪一知识单元;名称调整可使用迁移映射,不允许悄悄重绑定到不同实体。
- **Content(内容)**:符号当前定义和可执行 IR;代码变更指纹改变。
- **Applicability(适用性)**:参数、业务前提、单位、时间/地区/场景等约束;匹配才可复用。
- **Evidence(证据)**:来源、测试与验证结果。证据改变不等同于程序改变,但需要重新评估可信状态。
### 3.2 Knowledge Reference
```text
KnowledgeRef {
label: String,
payload_ast: Expr,
context: Narrative | Code | Return | Argument | Table | Heading,
resolution: ResolvedSymbol | LocalExpression | NavigationURL | Unresolved,
target_symbol_id: SymbolId?,
target_digest: Digest?,
expected_signature: Signature?,
required_verification: VerificationPolicy,
source_span: SourceSpan
}
```
`[描述](E)` 在运行语义上是透明的,但其静态解析必须构建 KnowledgeRef。在调用点将地址绑定到 `SymbolId`,不能每次由 AI 重新解释描述。
### 3.3 类型 / 知识实体 / 计算能力分别建模
- `# 诗人` 是 Type;`# 李白 = > 诗人` 在现有语法中仍是**继承/特化**。作为 v2.1 过渡方案可视为“单体知识类”,但不得默认为真正的 `instance_of`。
- 事实可以由 `## 出生年份` + 返回值 + 来源表承载;编译器推导为 Fact Artifact。是否是事实要根据可检查的声明/契约,不应仅凭函数名字猜测。
- 业务函数如 `## 计算应付` 是 Function/Capability;不应因为带中文说明就被误识别成事实。
- 未来需要大规模实体库时,Entity/Fact 应支持表驱动注册,不为每个实体强制生成 Rust 或 Marqdo 类。
## 4. `[]()` 的确定语义
### 4.1 一个表面形式、三种解析结果
| 表面形式 | 静态解释 | `run` | `check` / `view` |
|---|---|---|---|
| `**总额=[应付](数量*单价)**` | 本地表达式遮蔽 | 求值 | 保存标签、表达式和诊断 |
| `**总额=[计算总额](Pricing.计算总额(订单))**` | 知识能力调用 | 绑定后调用 | 检查签名、效应、依赖和版本 |
| `文中参见[税率](Policy.税率)` | 叙述知识引用 | 不执行 | 解析、展示受信任/未验证状态,纯目标可选择显式求值 |
| `[项目文档](./guide.md)` | 导航链接 | 不执行 | 保持 Markdown 导航 |
语法上的“同权”是 `()` 与 `**...**` 共用表达式文法;**不是正文和代码拥有相同的执行许可**。 `view` 对具外部效应的目标默认只展示元数据,必须明确授权才允许运行。
### 4.2 最小语义规则
```text
parse_bracket(label, payload, context) -> KnowledgeRef
context ∈ executable_context:
verify_resolved_target(); evaluate(payload_ast)
context ∈ narrative_context:
resolve_only(); never_schedule_effects()
payload ∈ ordinary_navigation:
preserve_as_markdown_link()
```
### 4.3 唯一性与优先级
1. 当前词法作用域的变量/接收者;
2. 当前文档的声明;
3. 显式 `import` 命名空间;
4. 项目导出索引(受 `--fs-root` 和导出策略约束);
5. 内置/已安装扩展。
如果两个候选都满足同一级优先规则,报 `link.ambiguous`;不能随文件顺序自动挑一个。解析失败必须有诊断,不能把知识目标悄悄解释成字面字符串或导航路径。
### 4.4 类函数 vs 实例方法
- 目标函数使用 `self/自` → 实例方法,必须有显式接收者。
- 函数不使用接收者 → 可由 `类.函数` 调用;不运行类的构造体。
- 路径解析到零参函数时可以省略 `()`,但**函数作为一等值的语义必须避免与隐式调用冲突**。建议只有被 `[]()` 用作知识目标、或显式值需求时才触发零参隐式调用;直接 `类.函数` 在函数值场景需明确消歧。最终以一致的形式化语义测试冻结。
### 4.5 版本策略与效应
`interface_digest` 代表签名兼容性,`implementation_digest` 代表实现变化,`dependency_closure_digest` 代表传递依赖;`evidence_digest` 代表证据状态。既存调用在接口未变时不必全部报错,但“严格复现”任务应使用 lock 来禁止目标悄然变化。
纯知识事实允许受控求值与缓存;依赖网络、时间、随机数、外部模型的调用即使锁了源码也不天然确定。必须记录输入快照、环境与效应,并明确“不保证结果复现”的状态。
## 5. 静态分析、来源与可信性
### 5.1 五层验证(必须分层报告)
1. **Parse**:Markdown 结构/语法可解析。
2. **Resolve**:目标存在,歧义可消除。
3. **Type/Contract**:签名、入参与结构类型、单位、前置条件匹配。
4. **Execution/Test**:纯函数或受控沙箱完成运行与测试。
5. **Evidence/Domain**:事实来源可访问,内容匹配,满足适用范围;复杂自然语言事实可能需要人工或 LLM 辅助复核,复核结果必须标识非确定性。
严禁将 `check OK` 展示成“现实知识已被证明正确”。
### 5.2 诊断码草案
| Code | 默认级别 | 含义 |
|---|---|---|
| `link.unresolved` | error | 找不到可绑定的目标 |
| `link.ambiguous` | error | 目标符号不唯一 |
| `link.kind_mismatch` | error | 把类型/实例/函数错当为可执行知识 |
| `link.instance_only` | error | 类调用命中实例方法 |
| `link.arg_mismatch` | error | 参数与签名不符 |
| `link.effect_forbidden` | error | 当前位置不允许此类副作用 |
| `link.target_changed` | warning/error | 被锁定或要求稳定的目标发生变更 |
| `knowledge.source_missing` | warning/error | 来源缺失 |
| `knowledge.source_changed` | warning | 来源指纹变化尚未复核 |
| `knowledge.constraint_unmet` | error | 当前输入不满足适用条件 |
| `knowledge.unverified` | info/warning | 可用但未得到所需级别的验证 |
| `label.ref_dangling` | error | 标签中反引号引用无法解析(保留已有规则) |
| `label.possibly_stale` | hint | 代码变更但描述未更新,需要人工检查 |
标签里提到的自然语言不能被静态类型系统完全证明。所有自动语义比对必须报告置信限制。
## 6. 编译器实施架构
```text
Markdown Source
│
├─ CommonMark/GFM-aware parse + Marqdo lexical context
▼
Syntax AST (prose + code + table + heading + bracket)
▼
Symbol Index (module, class, function, fact, export)
▼
Resolution & Type / Contract / Effect Analysis
▼
Semantic Artifact IR + KnowledgeRef IR
├──────────────┬──────────────────┬───────────────────────┐
▼ ▼ ▼ ▼
Tree Interpreter Bytecode VM View / Debug EKC/Catalog/MLSP
│ │
└──────────┬────────────┘
▼
Agent deterministic reuse
```
**实现优先原则**:统一在语义分析层生成符号与引用元信息。不要在 view、EKC、Agent 中分别重新解析 `.mq.md` 来猜同一段代码代表什么。
### 6.1 Markdown 链接兼容性
`[描述](含空格或括号的表达式)` 不是任意标准 Markdown 渲染器都可识别的合法 URL 目标。Marqdo 必须定义其**源码级别的上下文语义和渲染行为**:先保留有意义的源码跨度,再由专属 view 转为原生可读的标签及悬浮信息;不能假设 GitHub Markdown 会在所有表达式上正确渲染。代码围栏、行内代码、转义以及普通 URL 链接不能被误识别成可执行引用。
### 6.2 旧语法迁移
Classic 的 `[键](集合)` 曾用于取元,`- [项](集合)` 曾用于循环。默认统一为遮蔽含义前,需要 AST 辅助迁移:
```text
[key](table) → [可读描述](at(table, key))
- [item](list) → - [逐项遍历](遍历 list 为 item)
```
避免靠简单正则批量替换;不能把旧代码成功运行但产生不同值视为兼容。迁移应生成审计报告、变更 diff 与双后端对照测试。
## 7. EKC 与 Agent 复用协议
当前 EKC 已有 Symbol、Capability、Knowledge、Context Pack、REUSE→ADAPT→CREATE。将这些能力变为统一 Semantic Artifact 的**投影/索引**,不要再建第二套符号管理器。
Agent 必须按以下状态机处理:
```text
TASK → DISCOVER → RESOLVE → CONTRACT_CHECK
│ │
│ ├─ verified + applicable → REUSE → EXECUTE → TRACE
│ ├─ adaptable → ADAPT → VERIFY → PROMOTE
│ └─ absent/unusable → CREATE → VERIFY → PROMOTE
└─ ambiguous → REQUEST_DISAMBIGUATION / FAIL_CLOSED
```
- **Discovery 是召回**,可以模糊检索,不等于可信复用。
- **Resolve 必须精确**,让自然语言意图最终绑定到具体 `SymbolId`。
- **Reuse 是编译器行为**:Agent 持有可验证引用,并使用明确的输入与契约,不复制代码段。
- **Promote 是门槛**:新生成内容必须通过所需静态检查、测试与来源规则才可进入已验证知识索引。
- **Trace 可审计**:保存“这次回答具体用了哪些符号、哪些版本和哪些输入”,不是仅存 LLM 的解释文本。
建议新增的 MLSP 读接口:`artifact.find`、`artifact.inspect`、`link.resolve`、`artifact.verify`、`artifact.impact`、`artifact.bind`;后者在编译器确定性解析后返回可调用句柄/引用描述,不应凭自然语言标签直接执行。
## 8. 里程碑与硬验收
### M0 语义冻结
明确新语义与 Classic 的区别,形成机器可读 gold cases,涵盖 URL、嵌套括号、空标签、取元、循环、代码围栏、换行、标题、叙述链接与作用域。所有未经标注的旧语义变化不得静默放行。
### M1 符号身份与项目索引
构建导出符号表、稳定 `SymbolId`、同名诊断。验收:同仓两个 `李白` 定义应报歧义;限定名可解析;改变目录扫描顺序不影响绑定结果。
### M2 统一 Bracket IR 与类函数调用
语法识别→表达式解析→目标绑定→双后端执行。验收:含 `self` 与不含 `self` 的函数正确分派,构造不产生意外副作用;正文不自动执行。
### M3 Semantic Artifact / 验证
签名、effect、contract、provenance、验证记录与指纹。验收:接口修改、依赖修改、证据变化、适用条件不匹配得到不同诊断。
### M4 EKC、view、agent 集成
整个工具链共享 SymbolId/LinkInfo,生成 links graph、可查看调用与来源、可追踪复用。验收:图边与实际编译的调用目标完全一致;Agent 命中已有能力时不得偷偷生成新实现。
### M5 基准实验(对照 Python/Notebook/普通 Markdown+检索)
同一模型、同一任务集、相当的工具与提示预算;分别统计可执行成功率、知识错误引用率、重复实现比例、文件改动数、调用/修复次数、总 tokens、端到端时延、可复核程度。公开任务、生成器、冻结环境、置信区间和失败样本;不要使用只在 Marqdo 方案可解的夹具,也不要把编译器固有优势等同整个 Agent 的领先。
## 9. 设计原则冻结
1. **源码可读,编译结果确定**。
2. **知识是制品,不是文本片段**。
3. **检索可以模糊,绑定必须确定**。
4. **知识能够执行,但执行不等于真实**。
5. **知识可以复用,但必须满足契约与适用条件**。
6. **显示文字可自由,语义判断不依赖显示文字**。
7. **默认保持叙述安全,副作用需要明确执行上下文**。
8. **保持一种语法,一个语义解析器,一套符号索引**。
9. **双后端与 view/EKC 使用同一份语义中间表示**。
10. **失败必须可观察,不能因为链接看起来优雅而隐去错误**。
## 10. 来源依据
仓库:<https://github.com/cflmy/marqdo>。重点阅读:
- `README.md`(v2.0.0 现状与 v2.1 目标)
- `doc/design/markdown-mapping-v0.3.md`(基本语法)
- `doc/design/objects.md`(类、实例、自/self、继承)
- `doc/design/link-syntax.md`(现有链接设计声明)
- `doc/design/occlusion-syntax.md`(遮蔽与描述新鲜度)
- `doc/design/knowledge-layers.md`(知识分层、过渡型单体类)
- `doc/design/engineering-knowledge.md`(EKC 与复用流程)
- `.cursor/skills/marqdo/reference.md` 与 `examples.md`(参考语法;其部分 Classic 旧写法必须经过迁移)
附录项目:`Marqdo_Executable_Knowledge_Example.md`。其中对未实现特性逐项标注,所有业务数据均为虚构演示数据。
File diff suppressed because it is too large. Load diff
@@ -0,0 +1,400 @@
# Marqdo 可执行知识范式:多文件完整示例与对照
> **规范性目标示例**:用于描述 v2.1+ 期望语义;并非宣称 v2.0.0 已能运行所有代码。示例内价格、折扣、门槛均为虚构业务数据。
> 展示:Markdown 叙述、frontmatter 导入、`#` 类型、`##` 函数、继承、表格集合、隐式形参、`**` 代码、`*` 返回、条件有序列表、循环无序列表、变量反引号、带描述的 `[]()`、对象、契约、来源、知识索引与 Agent 复用。
## 1. 实际业务场景
一家虚构的“云雀书店”需要将定价规则维护为**人类可阅读的运营文档**,由网站、客服机器人、后端结算、审计报告复用,而不是让四个 AI 分别根据文字重新写四次逻辑。业务规则:普通会员 100% 计价,银卡会员 95%,金卡会员 90%;订单满 100 元免 8 元运费;仅处理人民币订单,件数为正整数。所有规则均为示例,没有现实效力。
### 项目结构
```text
bookshop/
├─ corpus/
│ └─ pricing-policy.md # 业务原始资料(不可执行)
├─ knowledge/
│ ├─ policy.mq.md # 已编译的政策知识
│ ├─ order.mq.md # 数据类型及订单操作
│ └─ pricing.mq.md # 定价能力
├─ apps/
│ ├─ checkout.mq.md # 业务执行入口
│ ├─ assistant.mq.md # AI 问答呈现/知识引用
│ └─ batch.mq.md # 列表与循环
└─ .marqdo/ # 生成:catalog、symbols、graph、links.lock
```
## 2. 原始资料 `corpus/pricing-policy.md`
```markdown
# 云雀书店价格政策(演示)
生效范围:2026 年演示订单,人民币;不代表任何真实商店。
## 会员折扣
普通会员不优惠;银卡会员九五折;金卡会员九折。
## 运费
商品合计满 100 元免运费,否则运费为 8 元。
## 约束
商品单价不得为负;数量必须为正整数。会员等级仅允许普通、银卡、金卡。
```
这是原始证据,并非运行时调用目标。它可被查看、引用和版本化,但不能因为被 AI 读到就自动获得 `verified` 状态。
## 3. 政策知识 `knowledge/policy.mq.md`
使用现有类/函数、返回值与契约表,将业务知识拆成稳定的、可发现的编译单元。
```markdown
---
title: 云雀书店演示定价政策
type: policy
---
# 书店政策
这是云雀书店的演示业务政策,供结算、客服和审计引用。
规则只适用于人民币演示订单,来源为
[价格政策原文](../corpus/pricing-policy.md)。
## 金卡折扣
| 返回 | 类型 | 单位 | 来源 |
|---|---|---|---|
| 0.90 | number | ratio | corpus/pricing-policy.md#会员折扣 |
*0.90*
## 银卡折扣
| 返回 | 类型 | 单位 | 来源 |
|---|---|---|---|
| 0.95 | number | ratio | corpus/pricing-policy.md#会员折扣 |
*0.95*
## 免运费门槛
| 返回 | 类型 | 单位 | 来源 |
|---|---|---|---|
| 100 | number | CNY | corpus/pricing-policy.md#运费 |
*100*
## 基础运费
| 返回 | 类型 | 单位 | 来源 |
|---|---|---|---|
| 8 | number | CNY | corpus/pricing-policy.md#运费 |
*8*
## 获取折扣
根据输入会员等级`等级`确定折扣比例。
| 参数 | 类型 | 说明 |
|---|---|---|
| 等级 | text | 普通、银卡、金卡 |
| 返回 | 类型 | 说明 |
|---|---|---|
| 比例 | number | 0 到 1 之间的比例 |
1. `等级` == "金卡"
*[金卡优惠比例](书店政策.金卡折扣)*
2. `等级` == "银卡"
*[银卡优惠比例](书店政策.银卡折扣)*
3. *
*1*
```
**说明**:`书店政策.金卡折扣` 等类函数直接调用属于 v2.1 目标;现有 `#` 类型/`##` 方法和表格、分支是当前语言能力。严格策略下,非法会员等级应报 `knowledge.constraint_unmet` 而不是无条件走默认分支;此处末尾 `3. *` 只是语言分支结构示范,正式实现需要额外拒绝非法等级。
## 4. 订单类型与继承 `knowledge/order.mq.md`
```markdown
# 订单
一个订单至少包含数量、单价和会员等级。
## 描述
本方法使用`自`读取对象字段,属于**实例方法**。
*自*
# 线上订单 = > 订单
线上订单是订单类型的一个特化。此处是实际继承语义,不把它误称为“知识实体实例化”。
## 渠道
*"online"*
```
注意:`# 线上订单 = > 订单` 在 Marqdo 中的确代表子类型继承;`> 线上订单` 构造实例,实例方法需要实例接收者。在知识分层中,普通 Fact 不应强制视为类实例。
## 5. 核心能力 `knowledge/pricing.mq.md`
这是“知识直接被复用”的核心,而不是把文字重新交给 AI 算一遍。
```markdown
---
title: 价格计算能力
import policy:knowledge/policy.mq.md
---
# 定价
下列函数实现演示书店的结算规则,适用于人民币演示订单。
## 计算商品小计
输入商品`单价`和`数量`。
| 参数 | 类型 | 约束 |
|---|---|---|
| 单价 | number | 大于等于 0;单位 CNY |
| 数量 | number | 大于 0,且为整数 |
| 返回 | 类型 | 单位 |
|---|---|---|
| 小计 | number | CNY |
**小计 = [商品小计](单价 * 数量)**
*小计*
## 计算运费
根据商品折扣后的金额`金额`决定是否免运费。
1. `金额` >= [免运费门槛](书店政策.免运费门槛)
*0*
2. *
*[基础运费](书店政策.基础运费)*
## 计算应付金额
接受`单价`、`数量`、`等级`;输出应付总金额。
**小计 = [商品小计](定价.计算商品小计(单价, 数量))**
**折扣 = [当前会员折扣](书店政策.获取折扣(等级))**
**折后价 = [折扣后商品金额](小计 * 折扣)**
**运费 = [应收运费](定价.计算运费(折后价))**
**应付 = [最终应付人民币金额](折后价 + 运费)**
*应付*
```
**目标能力标记**:这一示例使用 `类.函数` 静态调用、跨文档自动类索引以及嵌入条件表达式中的知识引用,这些是计划实现的语义。当前实际版本中,一般需要显式 `import` 和实例句柄。其余 `**代码**`、`*返回*`、契约表、分支为现有基础。
这里看得最清楚:对读者,整段代码是一个有清晰描述的计算故事;对编译器,括号内是有类型、依赖、来源的调用图;对 AI,复用的不是价格公式的自然语言解释,而是绑定到已有符号的能力。
## 6. 结算入口 `apps/checkout.mq.md`
```markdown
---
title: 演示结算
import pricing:knowledge/pricing.mq.md
---
# main
一位金卡用户购买两件单价 60 元的商品。
**单价 = 60**
**数量 = 2**
**等级 = "金卡"**
**应付 = [本次订单应付款](定价.计算应付金额(单价, 数量, 等级))**
> 打印 内容=`应付`
```
预期:`60 × 2 × 0.90 = 108` 元,达到免运费门槛,输出 `108`。这是目标语义下的预期值,而非当前版本的实测输出。
**对照(相对现有版本更接近可执行)**:使用 `import`、构造实例,再调用实例方法。下面的最小兼容样例来自仓库 `examples/link-syntax/main.compat.mq.md`:
```markdown
---
markup: occlusion
import libai:libai.mq.md
---
# main
**li = > libai.李白**
**year = [李白的出生年份](li.李白的出生年份())**
> print text=`year`
```
此兼容片段是仓库实例,不能直接替代上面的定价案例:它用于说明当前版本与目标引用模型之间的差距。
## 7. 文档问答 `apps/assistant.mq.md`
```markdown
# main
# 云雀书店结算说明
普通会员原价结算;金卡会员使用[已登记的金卡折扣](书店政策.金卡折扣)。
当前免运费门槛为[已登记的门槛金额](书店政策.免运费门槛)。
关于政策出处,参见[原始价格政策](../corpus/pricing-policy.md)。
```
这展示**知识链接与导航链接共存**:前两条必须由编译器解析知识目标,最后一条仍是传统 Markdown 导航。不应把全文正文都作为主动执行入口。UI 可以显示“来源文件/目标类型/验证状态/必要时的值”;若目标未验证,应明确标注。
## 8. 表格几何与循环 `apps/batch.mq.md`
演示一列 List、横表 Map、`@` 行向记录、无序列表循环和条件分支。根据 v2.0 新语义,旧 `[key](collection)` 取元改为 `at(collection,key)`。
```markdown
---
markup: occlusion
---
# main
`会员等级` =
| 等级 |
|---|
| 普通 |
| 银卡 |
| 金卡 |
`折扣说明` =
| 普通 | 银卡 | 金卡 |
|---|---|---|
| 1 | 0.95 | 0.90 |
`演示订单` =
| @ | 客户 | 等级 | 单价 | 数量 |
|---|---|---|---|---|
| 1 | 甲 | 金卡 | 60 | 2 |
| 2 | 乙 | 银卡 | 30 | 2 |
**银卡比例 = [银卡折扣值](at(折扣说明, "银卡"))**
- [逐个检查会员等级](遍历 会员等级 为 等级)
1. `等级` == "金卡"
> 打印 内容="识别到金卡会员"
2. *
> 打印 内容=`等级`
```
表格语义:单列→List;两列以上一数据行→Map;首列 `@`→按行组成的 List of Map。此处只演示集合构造、访问与循环,避免假定尚未验证的嵌套函数语义。`遍历` 链接循环是新设计形式,必须通过现有版本的解析器验收后才能标记为已实现。
## 9. 编译后的产物应当长什么样
下列均是**建议输出示意**,不是现有 CLI 的真实输出:
```json
{
"symbol": "knowledge://bookshop/定价/计算应付金额",
"kind": "capability",
"signature": {
"params": ["单价:number", "数量:number", "等级:text"],
"returns": "number:CNY"
},
"dependencies": [
"knowledge://bookshop/定价/计算商品小计",
"knowledge://bookshop/书店政策/获取折扣",
"knowledge://bookshop/定价/计算运费"
],
"effects": ["pure"],
"verification": {"parse": "ok", "resolve": "ok", "contracts": "ok", "evidence": "pending"}
}
```
假设用户把政策金卡折扣由 0.90 改为 0.88,正确行为应该是:
1. `书店政策.金卡折扣` 的实现摘要变化;
2. `书店政策.获取折扣` 与 `定价.计算应付金额` 的传递依赖指纹变化;
3. 所有引用这些知识的文档都能由 `impact` 找到;
4. 如果使用 lock,校验报告“知识目标变更”,而不是静默引用新版;
5. 修改政策的原始来源还需要单独复核,不把源码更新等同于证据更新;
6. Agent 必须先检查适用性和验证状态,不能拿一个未复核的版本装作确定事实。
## 10. AI 原生复用:有无语义制品的差别
**传统文档 + RAG**:
```text
用户问“金卡买两件 60 元的商品多少钱?”
→ 检索到价格政策.md
→ LLM 阅读、复述并临时写计算步骤
→ 得到 108(本次碰巧正确)
→ 下次又重新解释规则,可能遗漏免运费条件
```
**Marqdo 目标路径**:
```text
用户请求
→ EKC.find("计算应付金额") // 发现候选,不等于信任
→ artifact.inspect(定价.计算应付金额) // 得到签名、适用范围、来源
→ link.resolve(...) // 确定性绑定具体符号
→ verify(contract, input) // 单价60、数量2、等级金卡
→ execute(bound_symbol, input) // 执行编译制品,得到108
→ trace(symbol+digest+input+result) // 可审计记录
→ AI 用自然语言解释结果
```
AI 不必记住“满百免运费”的公式,也不用每次生成新的结算代码。它需要做的是找准能力、验证条件并引用它。
## 11. 演示必须通过的负例
| 变更/攻击输入 | 期待结果 |
|---|---|
| 将 `书店政策.金卡折扣` 改名但未迁移引用 | `link.unresolved` |
| 新增第二个同名 `书店政策` | `link.ambiguous` |
| 对 `定价.计算应付金额` 漏传数量 | `link.arg_mismatch` |
| 数量传入 0 | `knowledge.constraint_unmet` |
| 来源 `pricing-policy.md` 删除 | `knowledge.source_missing` |
| 来源内容变化但知识函数不变 | `knowledge.source_changed` |
| 来源规则仍然正确但业务已过期 | 需要过期/适用期检查,不能自动声称 verified |
| 尝试在正文链接里执行网络支付 | `link.effect_forbidden` 或只解析不执行 |
| 标签写“免费”但表达式仍产生费用 | 结构检查可能通过;标签语义审查需报警或人工审核,不得保证静态证明 |
| 类实例方法经 `类.方法` 直接调用 | `link.instance_only` |
## 12. 为什么这个范式更强
1. **人类维护规则**:读的是 Markdown 业务故事、表格与政策,不是必须遍历全仓源码。
2. **编译器复用行为**:跨文档引用已绑定语义制品,避免重复造轮子。
3. **错误能被提前拦截**:同名、失效、类型、契约、来源变化有各自诊断。
4. **审计能回答“依据是什么”**:结果、符号、版本、输入和来源可追踪。
5. **AI 只负责不确定环节**:意图匹配、适用性判断、结果解释;确定性的计算留给编译制品。
6. **上下文可以缩短,但不是无条件保证**:目标是让 Agent 读取能力摘要而非每次粘贴全部实现;是否节省 tokens 需要客观实验。
**核心竞争力不是 Markdown 链接本身,而是“自然语言描述 → 精确符号绑定 → 可验证语义制品 → 执行与复用”的完整链条。**
## 13. 语法覆盖与非目标
本示例涵盖语法主干,但“全部语法”还包括外联代码围栏、公式 `$$`、浏览器/WASM、原生插件 ABI、量子与线性代数扩展、MCP/Agent、网络和文件 API 等。它们的具体运行依赖扩展与环境,不能当作知识引用所必需的语言核心;统一 IR 应允许这些能力以受效应约束的 Artifact 注册和复用,而不必将每种扩展硬塞入同一个教学案例。
建议另建生态回归套件:
- foreign/LLM/network 函数注册为 EffectSet 的非纯函数;
- 数学公式与表格按返回类型编译为 Artifact;
- 浏览器和 Web 插件导出的能力经符号索引显式引用;
- Agent 的复用接口通过 MLSP 获得固定签名与效果说明。
## 14. 原仓库参考资料
- <https://github.com/cflmy/marqdo/blob/main/doc/design/link-syntax.md>
- <https://github.com/cflmy/marqdo/blob/main/doc/design/markdown-mapping-v0.3.md>
- <https://github.com/cflmy/marqdo/blob/main/doc/design/objects.md>
- <https://github.com/cflmy/marqdo/blob/main/doc/design/knowledge-layers.md>
- <https://github.com/cflmy/marqdo/blob/main/doc/design/engineering-knowledge.md>
- <https://github.com/cflmy/marqdo/blob/main/examples/link-syntax/main.compat.mq.md>
@@ -0,0 +1,83 @@
# 可执行知识语法:仓库级测试与兼容性规程
本文是 `Marqdo_Executable_Knowledge_Development.md` 的验证规程。它约束稳定符号 URI、零参数知识路径、关联函数/实例方法区分及其 CLI 解析进入标准库、扩展库和发布流程后的测试方式。
## 覆盖目标
新写法只在需要值的位置把零参数路径解释为调用:
```marqdo
**pi = math.pi**
**year = facts.Person.birth_year**
```
旧的 `**pi = > math.pi**` 和 `> math.pi` 继续兼容。对象子函数不读取 `self` / `自` 时是 `associated_function`;读取接收者时是 `instance_method`,不能由 `Type.method` 直接执行。
每项语法变更必须同时证明:新写法正确、旧写法未回归、Tree/Bytecode 一致、CLI 静态解析和运行时规则一致,并且标准库与扩展库仍能加载、运行。
## 自动化测试矩阵
| 层级 | 覆盖内容 | 命令 | 通过条件 |
|---|---|---|---|
| 解析 | 零参路径降级 Call;带参路径不能静默执行 | `cargo test --locked --lib parse::expr` | AST、参数数与诊断稳定 |
| 语义 | ProjectRoot、ModuleId、SymbolId、关联/实例分类、歧义 | `cargo test --locked --lib sema::` | 扫描顺序不影响结果;分类不改变 SymbolId |
| Tree | 标准库裸路径、关联函数、旧写法 | `cargo test --locked --test gold structure_new_path_stdlib structure_ns_associated_function` | stdout 金样一致 |
| Bytecode | 同一正例的后端一致性 | `cargo test --locked --test gold bytecode_new_path_stdlib bytecode_ns_associated_function` | stdout、退出码一致 |
| 负例 | 接收者依赖路径被拒绝 | `cargo test --locked --test gold error_ns_instance_method knowledge_resolve_rejects_instance_path` | 不构造对象、不执行方法 |
| CLI | `inspect` / `resolve` JSON | `cargo test --locked --test gold knowledge_resolve_new_path` | 返回 URI、source、callable;resolve 不执行代码 |
| 标准库 | 英文/中文零参知识 | `cargo test --locked --test gold lib_log_uuid_smoke lib_log_uuid_zh_smoke` | `uuid.v4` 等裸路径可用 |
| 扩展库 | 改写后的扩展调用和插件加载 | `cargo test --locked --test gold ext_quantum_gates_smoke` | `math.pi` 新写法输出不变 |
## 每次语法改动的执行顺序
```bash
source scripts/dev-env.sh
cargo check --locked
cargo test --locked --lib
cargo test --locked --test gold -- --test-threads=1
cargo test --locked
cargo build --locked
```
发布前再做可观察的 CLI/双后端冒烟:
```bash
target/debug/marqdo knowledge tests/structure/ns --json resolve \
helpers.Box.birth_year --from tests/structure/ns/associated.mq.md
target/debug/marqdo run tests/structure/new-path-stdlib.mq.md --backend tree
target/debug/marqdo run tests/structure/new-path-stdlib.mq.md --backend bytecode
```
完整 gold 会构建部分原生/Go 扩展,必须单线程执行。网络、真实 LLM 与 ignored 实验不属于离线语法门禁,不能以其失败掩盖核心回归。
## 标准库与扩展库改写准则
仅改写可机械证明等价的值表达式:
| 原写法 | 新写法 | 前提 |
|---|---|---|
| `**x = > math.pi**` | `**x = math.pi**` | 目标零参数、值位置 |
| `**id = > uuid.v4**` | `**id = uuid.v4**` | 目标零参数、值位置 |
| `**x = > Type.fact**` | `**x = Type.fact**` | 目标为关联函数 |
禁止自动改写副作用语句、带必填参数函数、实例方法、文本/围栏/URL/导航链接,以及不能同时通过 Tree/Bytecode 的变更。本轮用 `math.pi`(量子扩展夹具)、`数学.圆周率`(中文标准库夹具)和 `uuid.v4`(标准库夹具)作为真实金样。
## CLI 合约
```text
marqdo knowledge PATH --json inspect SYMBOL
marqdo knowledge PATH --json resolve REFERENCE --from CALLER.mq.md
```
`resolve` 只绑定、不执行。它依据 `--from` 的 frontmatter import 解析第一个路径段,不会在项目中按名字猜测目标。关联函数返回 `resolution: "symbol"`;实例方法返回 `resolution: "instance_only"` 并以退出码 1 拒绝直接路径调用。
## 发布门槛
1. `git diff --check` 无错误;
2. Rust 核心、gold、完整 `cargo test --locked` 通过;
3. 每个新正例有 Tree、Bytecode 和 CLI(适用时)覆盖;
4. 每个语义拒绝路径有稳定负例;
5. 标准库/扩展库改写保留原 stdout 金样;
6. 不提交 `.marqdo/`、插件构建物或本地凭据。
失败报告必须记录命令、后端、夹具、stdout/stderr、插件/网络依赖及与旧写法的差异。
@@ -0,0 +1,102 @@
# 智能体能力调研与求道差距复核(2026-10-27)
| 项目 | 说明 |
|---|---|
| 状态 | Research / 设计输入;不是功能交付声明 |
| 调研日期 | 2026-10-27,Asia/Shanghai |
| 源码基线 | Marqdo `16f26d7d60ce9fbc62feb0e8e83f93951f7b53fe`;qdagent `68b757e02ebfb64833b5262b0c8a683512581e8b` |
| 框架设计 | [Agent 恢复、工具与资源协议](../design/agent-reliability-tools-resources-2026-10-27.md) |
| 产品设计 | [求道智能体能力与预览体验](../../../qdagent/doc/design/agent-capabilities-and-preview-2026-10-27.md)(同级仓库) |
## 1. 方法与结论边界
先以 `git pull --ff-only` 同步两仓,再追踪真实调用链与前端入口;对比公开官方文档,不以营销介绍、工具数量或旧设计中的 done 标签代替实现证据。本次是静态源码复核与官方资料研究,没有启动部署实例,没有调用付费模型,没有进行竞品账号实测。因此,下表“源码确认”仅代表代码路径可见,“设计判断”与“待实测”不能写成已复现或已交付。
主流能力的共同方向是:可恢复的执行、结构化工具与资源、按需上下文、可追溯结果、独立产物展示。不同产品和模型支持范围不同;这里不是市场占有率调查,也不声称所有智能体都具备全部能力。求道应保留文档原生、EKC、验证后沉淀的定位,吸收机制,不引入第二套 Agent Runtime。
## 2. 官方资料与可借鉴机制
以下页面均在调研日实际打开;MCP 特意引用固定 `2025-06-18` 版本,作为兼容基线,不宣称它是最新协议。厂商专有能力必须探测,不能因为端点兼容 `/v1` 就认为全部可用。
| 编号 | 官方来源 | 已核实内容 | 对求道的设计启示 |
|---|---|---|---|
| S01 | [OpenAI Agents:集成与可观测性](https://developers.openai.com/api/docs/guides/agents/integrations-observability) | MCP 接入与运行、模型、工具等 tracing | 统一 call/attempt/span 关联;产品只显示阶段摘要,详细事件可展开 |
| S02 | [OpenAI:Memory 与 Compaction](https://developers.openai.com/cookbook/examples/agents_sdk/building_reliable_agents_memory_compaction) | 区分当前任务上下文压缩、跨运行记忆、可审阅产物 | 历史不要无限拼接;完整产物不等于聊天全文 |
| S03 | [LangGraph Persistence](https://docs.langchain.com/oss/python/langgraph/persistence) | checkpointer 保存 thread 状态,store 支撑跨 thread 数据 | 恢复执行状态和用户长期知识是两种生命周期 |
| S04 | [LangGraph Interrupts](https://docs.langchain.com/oss/python/langgraph/interrupts) | 恢复时节点代码可能重新执行 | 检查点不能单独保证写操作只执行一次,必须记录效应与幂等键 |
| S05 | [Claude Tool search](https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool) | 工具定义按需进入模型上下文 | 工具多不代表每轮注入全部定义;检索后再校验权限 |
| S06 | [Claude Programmatic tool calling](https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling) | 在执行环境中编排工具、筛选结果 | 大批量只读处理可减少模型往返;后置于基础工具可靠性 |
| S07 | [Deep Agents overview](https://docs.langchain.com/oss/python/deepagents/overview) | 文件系统、上下文管理、子任务与可选规划能力 | 规划应按任务启用;简单问答不强制复杂工作流 |
| S08 | [Gemini Tools](https://ai.google.dev/gemini-api/docs/tools) | 检索、URL、文件搜索、代码执行等工具面 | 覆盖“找资料—读内容—计算—形成产物”,不能只有工程检索 |
| S09 | [Gemini File search](https://ai.google.dev/gemini-api/docs/file-search) | 文件检索与引用信息 | 命中要能定位原文,检索摘要不能代替源文件版本 |
| S10 | [MCP Tools](https://modelcontextprotocol.io/specification/2025-06-18/server/tools) | schema、结构化结果、资源链接;annotations 有信任边界 | 工具结果包含短摘要和资源引用;注解不是权限凭证 |
| S11 | [MCP Resources](https://modelcontextprotocol.io/specification/2025-06-18/server/resources) | URI 资源、读取和应用决定的上下文注入 | “预览”“加入上下文”“执行”必须是独立动作 |
| S12 | [Claude Artifacts](https://support.claude.com/en/articles/17153992-what-are-artifacts-and-how-do-i-use-them) | 产物在会话旁独立打开,可继续查看与编辑 | 右栏应承载正文;不应只提供离开当前会话的入口 |
| S13 | [Mozilla PDF.js](https://mozilla.github.io/pdf.js/) | Web PDF 解析和渲染 | PDF 视觉预览和 OCR/知识提取分开交付 |
| S14 | [DOMPurify 官方仓库](https://github.com/cure53/DOMPurify) | DOM 清洗、标签/属性配置;插入前清洗 | 替换前端正则“清洗器”,配合同源资源代理和 CSP |
上述设计启示是本次推导,相关性能收益、成本下降比例不照搬厂商基准。工程路线不绑定某个最新模型或套餐。
## 3. 源码事实清单
下列 qdagent 路径相对该仓库;Marqdo 路径相对本仓库。基线 commit 已固定,后续实现需按符号再定位。
| 编号 | 当前实现证据 | 结论与限制 |
|---|---|---|
| F01 | qdagent `agent/qdagent.mq.md::契约提示`、`ask` | ASK 和 BUILD 都要求完整六段式 `.mq.md`,包含 main、验证和元数据;普通回答变长有明确结构性诱因。不能断言这是唯一原因 |
| F02 | 同文件 `ask` 的门禁修复分支 | `r2` 送入第二次门禁后,成功分支仍 `result = raw`;可能展示修复前内容,设计必须绑定同一 accepted candidate |
| F03 | 同文件 `ask` 返回表 | `gated_error` 路径仍可能保留 `status=ok` 且返回 `ok=True`;必须明确业务失败与输送成功的不同含义 |
| F04 | 同文件 `eng_tools` | 默认白名单是 `tool_find/reuse/bind/verify/summarize` 五个工程工具;不是整个框架只有五个工具,也不代表已覆盖网页、笔记、文件编辑 |
| F05 | `ext/ai/agent.mq.md` | 有 step/plan/run、READ、CALL、观察压缩、工作簿和恢复接口;应扩展这些原语,不另造循环 |
| F06 | `plugins/agent/src/resume.rs::resume_save` | JSON 直接 `fs::write`;现有恢复接口不等于具备原子检查点、工具效应对账及任意步骤自动续跑 |
| F07 | `src/runtime/`、`src/workbench/capabilities.rs` | 已有隔离执行、取消、事件回放与读通道;这一轮是 Agent 级恢复补足,不重新规划整个进程池 |
| F08 | qdagent `session-store.ts::resumeTurn` | 终态 completed/failed/interrupted 直接返回;已有事件续订,但终态消息补齐与中断后的执行恢复需分别处理 |
| F09 | qdagent `DesktopFrame.tsx::RightNotesPanel` | 实际只有“查看全部笔记”导航至 `/notes`,没有侧栏笔记正文 |
| F10 | 同文件 `RightFilesPanel`、`WorkspacePage.tsx::openFile` | 文件点击已调 `openTarget`;右栏取首个 workspace,根目录最多 40 个非目录项。不能笼统写“所有按钮都跳转” |
| F11 | `DesktopFrame.tsx` 的 reader/rightbar 条件 | `DocumentReader` 与右侧 tab 容器互斥,且使用两套开关/宽度状态;不是统一的资源浏览面板 |
| F12 | qdagent `NotesPage.tsx` detail | 剥离 frontmatter 后以 `whiteSpace: pre-wrap` 显示文本;没有 Markdown/Marqdo 正文结构渲染 |
| F13 | qdagent `DocumentReader.tsx` | 已有 DocumentView、引用版本传递、请求代数防迟到覆盖;`profile_item` target 未进入读取分支,格式不是通用资源分派 |
| F14 | 同文件 `sanitizeHtmlFragment` | 主要靠正则移除 script/事件/javascript URL;不能当作完整 HTML 白名单安全边界。未在本次做漏洞利用实验 |
| F15 | `src/workbench/document_view.rs` | 有只读文档视图,注释与实现明确避开执行路径;已解析语义应继续复用 |
| F16 | `src/workbench/capabilities.rs` | text/markdown 提取可用,pdf/docx/ocr 标 unavailable;提取能力与浏览器 PDF 预览能力须分别探测 |
| F17 | qdagent `lib/web_search.mq.md` | 既有网页搜索桥使用 legacy 脚本和固定 `last_web_search.json`;存在并发覆盖设计风险,不能直接作为新工具通道 |
| F18 | `plugins/agent/src/mcp_client.rs` | 已有 stdio connect/list/call/close;不能把本轮描述为“从零添加 MCP”,远程连接和资源能力需另验 |
| F19 | qdagent `compose_messages` / `ask` | 对话按角色标记拼成字符串注入 standing;会话语义、上下文预算和外部内容信任层级仍需强化 |
| F20 | qdagent `lib/workbench.mq.md::documents_read` | 临时文件名以秒和环境 RANDOM 构造,RANDOM 缺失又退到秒;设计仍需真正唯一临时文件。workspace 缺省 `.` 不应作为新授权资源接口规则 |
这些是本轮优先级依据。10-26 release notes 所列修复作为已有基础保留,但“Implemented(本仓)”不能替代浏览器、真实 HTTP、进程中断与模型输出的联合验收。
## 4. 能力覆盖与差距优先级
| 能力 | 当前基础 | 本轮目标 | 优先级 / 归属 |
|---|---|---|---|
| 自动纠错 | 一次文档门禁修复、plan patch | 分类错误、有限修复、正确结果替换、可恢复失败 | P0 / 两仓 |
| 执行恢复 | 任务隔离、取消、事件回放、JSON checkpoint | 传输续订与执行续跑分离;效应对账 | P0 / Marqdo 原语,qdagent UX |
| 回答长度 | 六段式文档、完整历史 | 直接回答、摘要+产物、显式详述三种表达 | P0 / qdagent 策略,Marqdo 输出通道 |
| 资源阅读 | DocumentView / Locator | 笔记、工作文件、引用、产物统一入口 | P0 / 两仓 |
| 侧栏预览 | 两套状态与导航入口 | 单一右栏,点击即预览,聊天不中断 | P0 / qdagent |
| 工具使用 | 五工具默认白名单、MCP/库原语 | schema 注册、按需发现、资源读取/搜索/写入/验证 | P1 / 两仓 |
| 联网研究 | legacy 搜索脚本 | search+fetch、来源时间、限量正文、可定位引用 | P1 / 两仓 |
| 上下文与记忆 | EFI pack、profile、history | 分层上下文、预算、可编辑记忆、资源 pin | P1 / 两仓 |
| 多格式 | 文档视图、文本提取 | text/md/mq/code/json/csv/image;PDF 后续 | P0→P1 / 两仓 |
| 长任务与计划 | plan 工作簿 | 里程碑、预算、暂停/继续、产物进度 | P1 / 两仓 |
| 多智能体与浏览器 | 不作为当前完成前提 | 有界委派、隔离执行、受控浏览器工具 | P2 / 框架主导 |
| 可观测评测 | usage、事件与既有测试 | 工具/恢复指标、实际任务语料、回归门禁 | P0 起持续 / 两仓 |
## 5. 采用与暂缓的决策
采用:有界失败恢复;工具结果摘要+资源引用;结构化参数;步骤效应账本;产物与聊天投影分离;资源预览与“加入上下文”分离;用户可检查的引用;按需工具发现。原有源码、知识、工作簿与验证证据仍是权威,衍生视图可重建。
暂缓:全自动跨站电脑操作、任意外部 MCP 自动信任、默认多智能体协作、所有 Office 格式保真编辑、每次问答都规划/运行代码。它们不能先于当前恢复、工具授权和预览闭环。
不采用:把长回答直接 substring 截断、把失败原文当最终成功、前端断流即重发任务、把所有文件当 HTML、用网页内容改写 system 指令、把预览等同于执行可执行文档。
## 6. 必须补做的动态验证
1. 在真实聊天中验证六段式输出与门禁失败/修复的最终消息和持久产物是否一致。
2. 丢弃最后一帧、断网、刷新、worker 崩溃分别注入,确认事件重放不重做工具副作用。
3. 使用真实 HTTP 入口验证右栏笔记、嵌套文件、历史引用、跨 workspace 资源;不只调用兄弟辅助函数。
4. 用恶意/畸形 HTML、路径与符号链接、过大文件验证预览隔离;no-exec 通过哨兵副作用测试。
5. 对无凭证模型、text-only provider、不可用转换器做明确降级;记录版本与环境,禁止以 mock 成功声称上线成功。
后续设计文档中的时间、轮数、字符数、成功率阈值均为拟定验收目标,需用该语料校准。
@@ -0,0 +1,58 @@
# 缺陷记录:LLM 传输失败硬中断 Agent Runtime
| | |
|---|---|
| 状态 | **Fixed(2026-10-16)** — 见 §3;金样 `tests/ext/agent-llm-transport-soft.mq.md` |
| 日期 | 2026-10-16 |
| 发现方 | qdagent(接通 `agent.run` live 路径时) |
| 影响面 | `host/net` · `plugins/llm` · `ext/ai/llm` · `ext/ai/llm/openai` · `ext/ai/agent` |
| 相关 | [agent-run-efi-resolve-bugs-2026-10.md](agent-run-efi-resolve-bugs-2026-10.md) · [ext-agent.md](../design/ext-agent.md) |
---
## 0. 一句话
上游 LLM **连接拒绝 / 超时 / 非 200** 时,Runtime 曾以 **硬错误** 终止整个 `marqdo run`;产品(qdagent ASK/BUILD)无法落到结构化 `status=error`。
---
## 1. 复现
```bash
OPENAI_API_KEY=offline OPENAI_BASE_URL=http://127.0.0.1:9 \
marqdo run tests/ext/agent-llm-transport-soft.mq.md
# 修复前:exit≠0,error: http POST …
# 修复后:exit 0,ask/step/run 均带 finish|status=error + error 文本
```
---
## 2. 根因
| 层 | 行为 |
|----|------|
| `host_http_post` / SSE | 传输失败 `Err(...)` → VM abort |
| `plugins/llm` `llm_chat_completions` | 同上 `Err` |
| `ext/ai/llm/openai` | HTTP≠200 → `sys.exit 1` |
| `agent.model_turn` / `step` / `plan` | 无软失败臂 |
---
## 3. 修复清单
| # | 改动 | 文件 |
|---|------|------|
| 1 | 传输失败 → `{status:0, body}` / SSE error event | `src/host/net.rs` |
| 2 | 插件返回 `{finish:error, error, …}` 而非 `Err` | `plugins/llm/src/lib.rs` |
| 3 | openai 非 200 → 结构化 pack,禁止 `sys.exit` | `ext/ai/llm/openai.mq.md` |
| 4 | `llm.ask` 透传 `error` / `finish` | `ext/ai/llm.mq.md` |
| 5 | `model_turn` / `step` / `plan` 收成 `status=error` | `ext/ai/agent.mq.md` |
| 6 | 金样 | `tests/ext/agent-llm-transport-soft.mq.md` |
**契约**:Agent Runtime 对 LLM 传输失败必须可捕获;`status=error` + `error` 字符串;进程退出码 0(程序正常返回错误图)。
---
## 4. 对 qdagent
`ensure_llm` 有 key 但上游不可达时,`ask`/`build` 可走既有 `mode=error` 臂写 workbook,不再整 CLI 崩。
@@ -0,0 +1,117 @@
# 缺陷记录:`agent.run` EFI / resolve 在消费方崩溃(qdagent 复现)
| | |
|---|---|
| 状态 | **Fixed(2026-10-16)** — 见 §3;金样 `tests/ext/agent-run-cold-efi.mq.md` |
| 日期 | 2026-10-16 |
| 发现方 | qdagent(`~/work/qdagent`)接通 Marqdo ≥1.4.2 Agent EFI 全路径时 |
| 影响面 | `ext/ai/agent` · `## run` · `plugins/agent` `agent_resolve` |
| 相关 | [ext-agent.md](../design/ext-agent.md) · [engineering-knowledge.md](../design/engineering-knowledge.md) · [ai-agent-llm-optimize-2026-10.md](ai-agent-llm-optimize-2026-10.md) |
---
## 0. 一句话
`agent.run` 在 **空 OKF / 无 skill 命中** 或 **`efi=True`** 时,会以硬错误退出,而不是降级到 `plan` 探索。
这是 **Agent Runtime 契约不完整**,不是 qdagent 业务写错。
---
## 1. 复现(qdagent)
环境:工作区 Marqdo `1.4.2` + `MARQDO_EXT=~/work/marqdo/ext`;qdagent 调用:
```text
助手 = > agent.agent …
`助手`.run task=… efi=True # 或 efi=False 后仍进 resolve
```
本仓几乎没有 `.marqdo/agent-kb` 编译 skill。
### Bug A — `efi=True` → `unknown function preflight`
**位置**:[`ext/ai/agent.mq.md`](../../ext/ai/agent.mq.md) `## run`
```markdown
1. `efi`
**efi_pf = preflight task=`task`**
```
同文件其它同对象方法一律写 `` `self`.route `` / `` `self`.resolve ``。
裸标识 `preflight` 在导入消费方(如 `cli/求道-构建.mq.md`)里被解析成**全局函数**,找不到 → 硬错。
**期望**:`` **efi_pf = > `self`.preflight task=`task`** ``(或等价 method call)。
### Bug B — miss resolve → `missing map key llm_free`
**位置**:
1. Plugin:[`plugins/agent/src/memory.rs`](../../plugins/agent/src/memory.rs) `resolve_task`
当 `kb_lookup` 返回 null:
```rust
Ok(json!({
"mode": "unknown",
"skill": null,
"resource": null,
"confidence": 0.0,
// 缺 llm_free
}))
```
2. Facade:`## run` 在 resolve 之后:
```markdown
**llm_free = [llm_free](resolved)**
```
脚注式取键在缺键时 **硬失败**,无法落到后面的 `plan` 探索臂。
**期望**:
- miss 结果始终带 `"llm_free": false`(与命中路径字段集对齐)
- facade 侧对可选键用 `json.get`(缺省 `False`),防御其它调用方
---
## 2. 为何金样没拦住
| 金样 | 为何漏网 |
|------|----------|
| `tests/ext/agent-zero-llm.mq.md` | 先编译 skill / policy,再 `run`;resolve **命中** |
| `tests/ext/eng-preflight.mq.md` | 只测 `agent_eng_preflight`,**不**走 `agent.run efi=` |
| 多数 `agent-*-live` | 自带 kb 或 `efi=False` / 不经过 cold miss |
qdagent 是第一个「冷库 + 产品 EFI + `run`」消费方,因此打穿。
---
## 3. 修复清单(本轮)
| # | 改动 | 文件 |
|---|------|------|
| 1 | miss resolve 补 `llm_free: false` | `plugins/agent/src/memory.rs` |
| 2 | `` `self`.preflight ``;`llm_free`/`mode` 用 `json.get` | `ext/ai/agent.mq.md` |
| 3 | 回归金样:冷 kb + `run efi=True` 不崩溃,落到 explore/plan | `tests/ext/agent-run-cold-efi.mq.md` |
| 4 | 重建 `marqdo_plugin_agent` 并跑金样 | `cargo build -p marqdo_plugin_agent --release` |
---
## 4. 对 qdagent 的含义
修复后 qdagent 可恢复:
```text
product preflight → latch → agent.run (efi=True|False) / plan
```
而不必长期绕开 `agent.run`。
在插件未装入新 so 前,qdagent 侧 EFI latch + `step`/`plan` 仍是合法降级。
---
## 5. 非目标
- 不改 EKC / `agent_eng_preflight` 语义
- 不引入第二套 Agent loop
- 不把向量检索升为权威真相
Loaded 100 of 981 files, more files were not shown because too many files have changed in this diff. Show more