- CHANGELOG.md:v2.8.0 条目(中英双语); - README.md:版本行 2.7.1→2.8.0 + 愿景第 6 条(知识可证明); - doc/releases/v2.8.0.md:双语发版说明(亮点/用法/已知限制); - skills/marqdo-dev/index.mq.md:新增 prove 任务(路径/目录模式/ require_lean/json;参数用 + 行声明升参,check 与 narrative-ratio 通过); - 设计文档 §12.5 标记已合入;发版链接统一指向 doc/releases/v2.8.0.md。
9.5 KiB
Executable File
marqdo view — 源结构浏览器与静态文档导出
| 状态 | 已定(v0.0.2 方向) |
| 日期 | 2026-08-04 |
| 相关 | examples-and-tests.md · view-markup-surface.md · view-document-annotations.md · view-static-interactive.md · generated-yaml-manifest.md · 视觉参考 id.cflmy.cn |
1. 动机
.mq.md 既是文档也是程序。需要:
- 本地浏览:按 AST 展示结构 + 执行结果;
- 静态导出:同一套渲染写成 HTML,作为用户文档站点(勿手写第二套站点);
- 启动快:样式极简,无外链字体/厚主题,避免 view 冷启动慢。
2. 视觉(Apple HIG / Docs 极简)
对齐 Apple HIG 的 clarity / deference / white space,并参考常见 docs 布局(sticky 侧栏 + 居中主栏,见 Nextra / Docusaurus 类站点):系统灰底、白内容面、浅分隔线、系统字体。作者站 id.cflmy.cn 仍作克制感参考,但不强行纯黑描边。
| 规则 | 要求 |
|---|---|
| 色板 | 页底 #f5f5f7;内容面 #ffffff;正文 #1d1d1f;次要字 #6e6e73;分隔 #d2d2d7;选中侧栏项反白 |
| 布局 | 壳层 max-width ≈ 1680px;侧栏 ≈280px;主内容 max-width ≈ 76rem;Structure 旁函数大纲;≤800px 侧栏收起 |
| 默认页 | 打开目录时 直接展示排序后的第一个 .mq.md(实时 / 与静态 index.html 同),不要求用户先从欢迎页点选 |
| 字体 | 仅系统栈:-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;等宽 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace |
| 外链 | 禁止 Google Fonts / CDN 样式;CSS 全部内联于 HTML |
| 装饰 | 无多层阴影、无渐变、无发光;圆角 ≈12px;结构区为分组列表(底部分隔),非堆叠厚卡片 |
| 诊断路径 | 展示时去掉 Windows \\?\ 前缀,并优先用相对 view 根的路径 |
验收:首屏无外网字体请求;宽屏主栏明显宽于早期 58rem 方案(现约 76rem / 壳 1680px)。
3. CLI
3.1 实时浏览
marqdo view [PATH] [--port PORT] [--host HOST] [--no-open]
| 参数 | 默认 | 说明 |
|---|---|---|
PATH |
. |
.mq.md 或目录 |
--port |
7429 |
|
--host |
127.0.0.1 |
|
--no-open |
关 | 不打开浏览器 |
3.2 静态导出(文档生成)
marqdo view output [PATH] -o OUT_DIR [--no-exec]
| 参数 | 默认 | 说明 |
|---|---|---|
PATH |
. |
与 view 相同扫描范围 |
-o / --out |
(必填) | 输出目录(不存在则创建) |
--no-exec |
关 | 不跑程序,执行区显示「skipped」 |
产物布局:
OUT_DIR/
index.html # 默认 = 排序后第一个 .mq.md 的完整页(侧栏高亮该项)
pages/
<相对路径>.html # 每个 .mq.md 一页;路径中的 `/` 保留为子目录
# 例:structure/hello.mq.md → pages/structure/hello.mq.md.html
- 页内链接一律相对路径,可用任意静态服务器或
file://(同目录结构下)打开。 - 用户文档推荐流程:
marqdo view output public -o public,将生成物发布到gh-pages(见 user-site.md)。 - 执行权限:与
marqdo run一致(导入即用);view/导出仅对exit/sleep做软化,避免拖垮进程。详见 stdlib-modules.md §6。 - 金样例浏览仍可用:
marqdo view output tests -o /tmp/mq-tests(含 errors,勿当对外用户站)。 - 渲染逻辑与实时
view共用同一路径:build_file_view→ 文档面 Structure(document.rs+ annots)→page_file(同一 CSS/JS,含 call/loop picker、#mq-view-trace)。禁止第二套皮肤。--no-exec时仍出文档面,但无运行标注。
示例:
marqdo view output public -o public
marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
4. 信息架构
侧栏文件索引 + 主区:文档面 Structure · 执行 · 源码。Structure(Browse)为叙述保真文档面:标记面(变量/语句/返回无源码定界符)、表/列表/分支结构保真,跑后结果经 CSS L-leader 引出——见 view-document-annotations.md · view-execution-trace.md。不是 AST 卡片栈(那是 debug)。
结构旁右侧栏(现有 outline 槽)为:
| 区块 | 内容 |
|---|---|
| Functions | 原函数大纲 + 搜索;可折叠(默认展开) |
| Variables | 跑完后的入口(# main)顶层绑定只读快照;List/Map/@ 行向渲成 HTML 表;可折叠(默认展开) |
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。--no-exec 时 Variables 显示 skipped。Live /api/run 终态帧可带 bindings_html 刷新该面板;终态亦可刷新 Structure 内标注。
表达式为表面语法。断点调试不在 view 内,见 marqdo debug。
5. HTTP(实时模式)
| 方法 | 路径 | 含义 |
|---|---|---|
GET |
/ |
默认打开第一个 .mq.md(无文件时为空提示) |
GET |
/file?path=… |
单文件页 |
GET |
/api/tree |
JSON 树(可选) |
GET |
/api/events?path=… |
可选长订 EventBus(调试);Stream 面板默认不用(避免页载常连导致标签页一直转圈) |
POST |
/api/run |
JSON {path, stdin?} → 直接返回 text/event-stream(本次 run 的事件);结束后关流 |
POST |
/api/foreign-run |
外联代码块试跑 |
根目录锁死;拒绝 .. 逃逸。默认页加载仍可整页执行;Stream 为增强路径。
5.1 Stream 面板(对齐主流 LLM 呈现)
仅当当前文件 frontmatter 导入了 ext/ai/llm / 大模型 或 ext/ai/agent / 智能体(及等价路径)时,在 live Execution 区显示;普通脚本页不出现该组件。
参考常见助手产品(思考折叠 + 正文流式、工具/子步骤独立卡片):不要把所有 SSE 事件打成一条混色终端日志。
| 区块 | 事件 | 呈现 |
|---|---|---|
| Thinking | reasoning |
可折叠;流式追加到同一块;默认展开直至本轮 delta/done 开始,之后可收起 |
| Answer | delta |
主文;token 连续拼进同一段落(禁止每 token 换行);主色正文 |
| Decision | decision |
时间线条目标记(RUN / CONTINUE / DONE / REUSE / NEW + 可选 summary) |
| Tool | tool_start / tool_end |
父 Plan-and-Move 的 CALL/READ:名称 + kind;tool_end 可带截断 result |
| Phase | decompose |
父 pre-run 分解开始(workbook 链);填补「决策后到首 token」空隙 |
| Child / Workbook | await → round |
await:Child running… 占位卡(quiet 子任务等待中);round:升级为完成卡(退出码 + 可选 result) |
| Status | run_start / done / error |
顶栏状态 + 错误行;嵌套 LLM done(无 run_id)只冲刷 drip,不改顶栏;终态 done.result 仅在无 Answer 时作摘要 |
传输与流畅度(对齐 ChatGPT 类产品):
- Run = 一次
fetchPOST,用ReadableStream读响应体里的 SSE 帧;不要页载常驻EventSource。 - 「Run with input」拦截表单:
preventDefault后走同一 Stream/api/run,禁止整页重载;带?stdin=进入时 live 页也不再阻塞跑完,改为自动开 Stream。 - 只改 Stream 对话框 DOM;token 按动画帧合批一次写入(rAF coalesce,不人为节流;打字感来自网络到达节奏)。
- Stick-to-bottom:仅在用户仍贴底时跟随;程序化
scrollTop产生的 scroll 事件忽略;上拉后不抢滚动,可点「↓ Latest」。 - Stop:
AbortController中止 fetch。 - 子任务并发进度:
spawn立即返回;wait阻塞父循环期间,子进程经MARQDO_EVENT_FORWARD把 EventBus 帧实时转发到父 SSE;view 把source=child的 delta 画进 Child 卡。quiet 仍不污染父 TTY。
视觉约束(与 §2 一致):
- 浅色内容面,不用深色「伪终端」底;Thinking 用次要字色 / 浅底。
- 一屏只突出 Answer;Thinking 与 Child 是附属。
- plan 多轮:每一轮 Child 一张卡;父侧 Thinking/Answer 按 decision 分轮,不清空历史。
事件字段约定(与 agent-streaming.md 一致):round 可带 result(子 # main 返回值摘要);reasoning/delta 的 text 为增量。
6. 验收
- 实时
view:HIG 风极简、无外链字体、结构与执行正确;打开目录即见首个文件;函数大纲可搜索跳转。 view output public -o public(或临时目录)生成可点的index.html(首文件)与各pages/…。- 静态页中执行区与
marqdo run一致(未加--no-exec时);失败诊断路径无\\?\。 - 冷启动无明显外网依赖。
- 调试用
marqdo debug(默认端口 7430),与 view 页面分离。 - Stream:
fetch+SSE 局部更新;Thinking/Answer 分栏;stick-to-bottom;rAF 合批;页载不常连 EventSource。