Add probs/Bloch draw kinds and matches_matrix, plus feature docs; hide the view Stream panel unless llm/agent is imported, and stop rewriting method names like 绘图 through host_plot aliases. Co-authored-by: Cursor <cursoragent@cursor.com>
162 lines
8.8 KiB
Markdown
162 lines
8.8 KiB
Markdown
# `marqdo view` — 源结构浏览器与静态文档导出
|
||
|
||
| | |
|
||
|---|---|
|
||
| 状态 | 已定(v0.0.2 方向) |
|
||
| 日期 | 2026-08-04 |
|
||
| 相关 | [examples-and-tests.md](examples-and-tests.md) · [generated-yaml-manifest.md](generated-yaml-manifest.md) · 视觉参考 [id.cflmy.cn](https://id.cflmy.cn) |
|
||
|
||
---
|
||
|
||
## 1. 动机
|
||
|
||
`.mq.md` 既是文档也是程序。需要:
|
||
|
||
1. **本地浏览**:按 AST 展示结构 + 执行结果;
|
||
2. **静态导出**:同一套渲染写成 HTML,作为**用户文档站点**(勿手写第二套站点);
|
||
3. **启动快**:样式极简,无外链字体/厚主题,避免 view 冷启动慢。
|
||
|
||
---
|
||
|
||
## 2. 视觉(Apple HIG / Docs 极简)
|
||
|
||
对齐 [Apple HIG](https://developer.apple.com/design/human-interface-guidelines) 的 **clarity / deference / white space**,并参考常见 docs 布局(sticky 侧栏 + 居中主栏,见 Nextra / Docusaurus 类站点):**系统灰底、白内容面、浅分隔线、系统字体**。作者站 [id.cflmy.cn](https://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 实时浏览
|
||
|
||
```bash
|
||
marqdo view [PATH] [--port PORT] [--host HOST] [--no-open]
|
||
```
|
||
|
||
| 参数 | 默认 | 说明 |
|
||
|------|------|------|
|
||
| `PATH` | `.` | `.mq.md` 或目录 |
|
||
| `--port` | `7429` | |
|
||
| `--host` | `127.0.0.1` | |
|
||
| `--no-open` | 关 | 不打开浏览器 |
|
||
|
||
### 3.2 静态导出(文档生成)
|
||
|
||
```bash
|
||
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](user-site.md))。
|
||
- **执行权限**:与 `marqdo run` 一致(导入即用);view/导出仅对 `exit`/`sleep` 做软化,避免拖垮进程。详见 [stdlib-modules.md](stdlib-modules.md) §6。
|
||
- 金样例浏览仍可用:`marqdo view output tests -o /tmp/mq-tests`(含 errors,勿当对外用户站)。
|
||
- 渲染逻辑与实时 `view` **共用**同一套 HTML 构件(结构 / 执行 / 源码),禁止两套皮肤分叉。
|
||
|
||
示例:
|
||
|
||
```bash
|
||
marqdo view output public -o public
|
||
marqdo view output tests/structure/hello.mq.md -o /tmp/hello-doc
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 信息架构
|
||
|
||
侧栏文件索引 + 主区:结构(AST+注释)· 执行 · 源码。结构旁**右侧栏**(现有 outline 槽)为:
|
||
|
||
| 区块 | 内容 |
|
||
|------|------|
|
||
| **Functions** | 原函数大纲 + 搜索;可折叠(默认展开) |
|
||
| **Variables** | 跑完后的入口(`# main`)顶层绑定只读快照;List/Map/`@` 行向渲成 HTML 表;可折叠(默认展开) |
|
||
|
||
view Variables ≠ debug Variables:前者是跑后快照,后者是暂停时的 locals。`--no-exec` 时 Variables 显示 skipped。Live `/api/run` 终态帧可带 `bindings_html` 刷新该面板。
|
||
|
||
表达式为表面语法。**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
|
||
|
||
---
|
||
|
||
## 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 类产品):**
|
||
|
||
1. **Run = 一次 `fetch` POST**,用 `ReadableStream` 读响应体里的 SSE 帧;**不要**页载常驻 `EventSource`。
|
||
2. **「Run with input」拦截表单**:`preventDefault` 后走同一 Stream `/api/run`,**禁止整页重载**;带 `?stdin=` 进入时 live 页也不再阻塞跑完,改为自动开 Stream。
|
||
3. **只改 Stream 对话框 DOM**;token **按动画帧合批一次写入**(rAF coalesce,不人为节流;打字感来自网络到达节奏)。
|
||
4. **Stick-to-bottom**:仅在用户仍贴底时跟随;程序化 `scrollTop` 产生的 scroll 事件忽略;上拉后不抢滚动,可点「↓ Latest」。
|
||
5. **Stop**:`AbortController` 中止 fetch。
|
||
6. **子任务并发进度**:`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](../roadmap/agent-streaming.md) 一致):`round` 可带 `result`(子 `# main` 返回值摘要);`reasoning`/`delta` 的 `text` 为增量。
|
||
|
||
---
|
||
|
||
## 6. 验收
|
||
|
||
1. 实时 `view`:HIG 风极简、无外链字体、结构与执行正确;打开目录即见首个文件;函数大纲可搜索跳转。
|
||
2. `view output public -o public`(或临时目录)生成可点的 `index.html`(首文件)与各 `pages/…`。
|
||
3. 静态页中执行区与 `marqdo run` 一致(未加 `--no-exec` 时);失败诊断路径无 `\\?\`。
|
||
4. 冷启动无明显外网依赖。
|
||
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
|
||
6. Stream:`fetch`+SSE 局部更新;Thinking/Answer 分栏;stick-to-bottom;rAF 合批;页载不常连 EventSource。
|