Browse Structure keeps narration and surfaces post-stmt values, branch arms, and call/loop pickers; static `view output` shares the same render path so exported HTML matches live view. Co-authored-by: Cursor <cursoragent@cursor.com>
3.8 KiB
3.8 KiB
View:执行轨迹与文档面保真
| 状态 | Active |
| 日期 | 2026-10-15 |
| 相关 | view-document-annotations.md · view-frame-selection.md · view.md · view-markup-surface.md |
1. 目标
marqdo view Browse Structure 必须同时做到:
- 标记面:变量名 / 可执行语句 / 返回值按表面渲染(无源码定界符字面量)。
- 结构块:GFM 表、循环(
-)、分支(1.)有正确 HTML 与缩进。 - 语句后值:赋值行标注该语句执行后的值,不用入口终态回填。
- 执行臂:高亮实际走的分支臂。
- 多调用帧:同函数多次调用可用下拉切换经历。
- AI 可读:与 HTML 同源的
ViewExecutionReportJSON。
Debug 仍用 AST 卡片 + 断点;不做文档 callout。
2. 标记面
| 源标记 | 显示(无定界符) | class |
|---|---|---|
`名` / `名`=默认 |
名(默认次要后缀) |
mq-anchor mq-decl |
**…**(可执行) |
内层文本 | mq-anchor mq-code |
*…*(返回) |
内层文本 | mq-anchor mq-return |
data-byte-start/end 仍为源码字节偏移(供 CSS L-leader)。软强调不进 anchor。
3. 结构块
| 块 | 呈现 |
|---|---|
| GFM 表 | <table class="doc-table"> |
- 循环 |
<ul class="doc-loop">,体按源缩进 --doc-indent |
1. 分支 |
<ol class="doc-branch">;命中 arm-taken,未走 arm-miss |
| 公式 / 外联代码 | 现有 formula-card / code-card |
> 调用 |
表面高亮,非整行灰 code |
4. StmtEvent / CallFrame
解释器 capture 时静默采集(非 trace_eval stderr):
StmtEvent {
line, kind, // assign | return | call | branch | loop | bind_ref
name?, value_after?, // post-stmt 或求值结果
arm_index?, iter?,
call_id // 当前用户函数调用帧
}
CallFrame {
call_id, fn_name, fn_line, ordinal,
args_brief, // 短摘要供下拉
events[] // 或全局 events 用 call_id 过滤
}
- Assign → 写入后的值挂在该行。
- 循环内多次写入:UI 默认末次;可带次数。
- Branch → taken
arm_index+ 条件摘要。 - 进入用户函数分配
call_id;# main单帧无下拉。
5. ViewExecutionReport(AI)
{
"version": 1,
"path": "…",
"ok": true,
"calls": [{ "call_id": 1, "fn": "等级说明", "ordinal": 1, "args_brief": "等级=及格" }],
"events": [{ "line": 24, "kind": "assign", "name": "总分", "value_after": "0", "call_id": 0 }],
"bindings_final": { "均分": "73", "等级": "及格" }
}
产出:页内 #mq-view-trace JSON;live GET /api/view-trace?path=;SSE done.trace_json。
6. UI
- 函数标题旁
<select class="call-picker">(调用数 ≥ 2)。 - 循环头旁
<select class="loop-picker">(迭代数 ≥ 2);默认最后一轮;摘要分 = 分数表[i] · value。 - 源码常显:切换帧只改 chip / 臂高亮,不
hidden结构节点。详见 view-frame-selection.md。 - CSS L-leader(非 SVG);拥挤 keyed 降级。
7. 验收
- 无字面
**/ 返回定界*/ 变量外层`(Source 除外)。 - 表为真表格;循环/分支有缩进列表;未选中臂源码仍可见。
总分 = 0标注0,非终态累加。- 命中臂可视化;多调用下只显示当前帧的 taken。
- 循环可按迭代切换;JSON 含
loops;单测覆盖。
8. 修订历史
| 日期 | 说明 |
|---|---|
| 2026-10-15 | 初稿:标记面、结构块、StmtEvent、CallFrame、AI 报告 |
| 2026-10-15 | 帧选择保真:call_id 分支、LoopFrame、源码常显 |