Add marqdo debug (breakpoints/step/locals), restore view as docs with function search, and emphasize OKF-aligned knowledge-base direction. Co-authored-by: Cursor <cursoragent@cursor.com>
117 lines
4.9 KiB
Markdown
117 lines
4.9 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+注释;旁侧函数大纲可搜索)· 执行 · 源码。表达式为表面语法。
|
||
**断点调试**不在 view 内,见 [`marqdo debug`](view-debug.md)。
|
||
|
||
---
|
||
|
||
## 5. HTTP(实时模式)
|
||
|
||
| 方法 | 路径 | 含义 |
|
||
|------|------|------|
|
||
| `GET` | `/` | 默认打开第一个 `.mq.md`(无文件时为空提示) |
|
||
| `GET` | `/file?path=…` | 单文件页 |
|
||
| `GET` | `/api/tree` | JSON 树(可选) |
|
||
|
||
根目录锁死;拒绝 `..` 逃逸。
|
||
|
||
---
|
||
|
||
## 6. 验收
|
||
|
||
1. 实时 `view`:HIG 风极简、无外链字体、结构与执行正确;打开目录即见首个文件;函数大纲可搜索跳转。
|
||
2. `view output public -o public`(或临时目录)生成可点的 `index.html`(首文件)与各 `pages/…`。
|
||
3. 静态页中执行区与 `marqdo run` 一致(未加 `--no-exec` 时);失败诊断路径无 `\\?\`。
|
||
4. 冷启动无明显外网依赖。
|
||
5. 调试用 `marqdo debug`(默认端口 7430),与 view 页面分离。
|